From 6c9f9cc1dc7231507c7442e37ee44238c3d8f4a3 Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Mon, 13 Jan 2025 13:14:24 +0000
Subject: [PATCH 01/82] refactor: unify mock_pma_entry implementations

---
 src/mock-pma-entry.h               | 165 +++++++++++++++++++++++++++++
 src/pma.cpp                        |  12 ---
 src/pma.h                          |  18 ----
 src/replay-step-state-access.h     | 141 ++----------------------
 uarch/uarch-machine-state-access.h | 162 +++-------------------------
 5 files changed, 187 insertions(+), 311 deletions(-)
 create mode 100644 src/mock-pma-entry.h

diff --git a/src/mock-pma-entry.h b/src/mock-pma-entry.h
new file mode 100644
index 000000000..883bd6725
--- /dev/null
+++ b/src/mock-pma-entry.h
@@ -0,0 +1,165 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef MOCK_PMA_ENTRY_H
+#define MOCK_PMA_ENTRY_H
+
+#include "clint.h"
+#include "htif.h"
+#include "plic.h"
+#include "pma-constants.h"
+#include "shadow-state.h"
+#include "shadow-tlb.h"
+
+namespace cartesi {
+
+class mock_pma_entry {
+public:
+    struct flags {
+        bool M;
+        bool IO;
+        bool E;
+        bool R;
+        bool W;
+        bool X;
+        bool IR;
+        bool IW;
+        PMA_ISTART_DID DID;
+    };
+
+private:
+    uint64_t m_pma_index;
+    uint64_t m_start;
+    uint64_t m_length;
+    flags m_flags;
+    const pma_driver *m_driver{nullptr};
+
+    static constexpr flags split_flags(uint64_t istart) {
+        flags f{};
+        f.M = ((istart & PMA_ISTART_M_MASK) >> PMA_ISTART_M_SHIFT) != 0;
+        f.IO = ((istart & PMA_ISTART_IO_MASK) >> PMA_ISTART_IO_SHIFT) != 0;
+        f.E = ((istart & PMA_ISTART_E_MASK) >> PMA_ISTART_E_SHIFT) != 0;
+        f.R = ((istart & PMA_ISTART_R_MASK) >> PMA_ISTART_R_SHIFT) != 0;
+        f.W = ((istart & PMA_ISTART_W_MASK) >> PMA_ISTART_W_SHIFT) != 0;
+        f.X = ((istart & PMA_ISTART_X_MASK) >> PMA_ISTART_X_SHIFT) != 0;
+        f.IR = ((istart & PMA_ISTART_IR_MASK) >> PMA_ISTART_IR_SHIFT) != 0;
+        f.IW = ((istart & PMA_ISTART_IW_MASK) >> PMA_ISTART_IW_SHIFT) != 0;
+        f.DID = static_cast<PMA_ISTART_DID>((istart & PMA_ISTART_DID_MASK) >> PMA_ISTART_DID_SHIFT);
+        return f;
+    }
+
+public:
+    template <typename ERR_F>
+    mock_pma_entry(uint64_t pma_index, uint64_t istart, uint64_t ilength, ERR_F errf) :
+        m_pma_index{pma_index},
+        m_start{istart & PMA_ISTART_START_MASK},
+        m_length{ilength},
+        m_flags{split_flags(istart)} {
+        if (m_flags.IO) {
+            switch (m_flags.DID) {
+                case PMA_ISTART_DID::shadow_state:
+                    m_driver = &shadow_state_driver;
+                    break;
+                case PMA_ISTART_DID::shadow_TLB:
+                    m_driver = &shadow_tlb_driver;
+                    break;
+                case PMA_ISTART_DID::CLINT:
+                    m_driver = &clint_driver;
+                    break;
+                case PMA_ISTART_DID::PLIC:
+                    m_driver = &plic_driver;
+                    break;
+                case PMA_ISTART_DID::HTIF:
+                    m_driver = &htif_driver;
+                    break;
+                default:
+                    errf("unsupported device in mock_pma_entry");
+                    break;
+            }
+        }
+    }
+
+    uint64_t get_index() const {
+        return m_pma_index;
+    }
+
+    flags get_flags() const {
+        return m_flags;
+    }
+
+    uint64_t get_start() const {
+        return m_start;
+    }
+
+    uint64_t get_length() const {
+        return m_length;
+    }
+
+    bool get_istart_M() const {
+        return m_flags.M;
+    }
+
+    bool get_istart_IO() const {
+        return m_flags.IO;
+    }
+
+    bool get_istart_E() const {
+        return m_flags.E;
+    }
+
+    bool get_istart_R() const {
+        return m_flags.R;
+    }
+
+    bool get_istart_W() const {
+        return m_flags.W;
+    }
+
+    bool get_istart_X() const {
+        return m_flags.X;
+    }
+
+    bool get_istart_IR() const {
+        return m_flags.IR;
+    }
+
+    const auto *get_driver() const {
+        return m_driver;
+    }
+
+    const auto &get_device_noexcept() const {
+        return *this;
+    }
+
+    static void *get_context() {
+        return nullptr;
+    }
+
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    void mark_dirty_page(uint64_t address_in_range) {
+        (void) address_in_range;
+        // Dummy implementation.
+    }
+};
+
+template <typename ERR_F>
+static inline mock_pma_entry make_mock_pma_entry(uint64_t index, uint64_t istart, uint64_t ilength, ERR_F errf) {
+    return mock_pma_entry{index, istart, ilength, errf};
+}
+
+} // namespace cartesi
+
+#endif
diff --git a/src/pma.cpp b/src/pma.cpp
index 45d29a5e5..9a112b4dd 100644
--- a/src/pma.cpp
+++ b/src/pma.cpp
@@ -73,11 +73,6 @@ pma_memory::pma_memory(const std::string &description, uint64_t length, const ca
     }
 }
 
-pma_memory::pma_memory(const std::string & /*description*/, uint64_t length, const mockd & /*m*/) :
-    m_length{length},
-    m_host_memory{nullptr},
-    m_mmapped{false} {}
-
 pma_memory::pma_memory(const std::string &description, uint64_t length, const std::string &path, const callocd &c) :
     pma_memory{description, length, c} {
     // Try to load image file, if any
@@ -259,13 +254,6 @@ pma_entry make_callocd_memory_pma_entry(const std::string &description, uint64_t
         memory_peek};
 }
 
-pma_entry make_mockd_memory_pma_entry(const std::string &description, uint64_t start, uint64_t length) {
-    if (length == 0) {
-        throw std::invalid_argument{description + " length cannot be zero"s};
-    }
-    return pma_entry{description, start, length, pma_memory{description, length, pma_memory::mockd{}}, pma_peek_error};
-}
-
 pma_entry make_device_pma_entry(const std::string &description, uint64_t start, uint64_t length, pma_peek peek,
     const pma_driver *driver, void *context) {
     if (length == 0) {
diff --git a/src/pma.h b/src/pma.h
index 2224cfdcf..7c2ae90aa 100644
--- a/src/pma.h
+++ b/src/pma.h
@@ -123,9 +123,6 @@ class pma_memory final {
     /// \brief Calloc'd range data (just a tag).
     struct callocd {};
 
-    /// \brief Mock'd range data (just a tag).
-    struct mockd {};
-
     /// \brief Constructor for calloc'd ranges.
     /// \param description Informative description of PMA entry for use in error messages
     /// \param length Length of range.
@@ -139,12 +136,6 @@ class pma_memory final {
     /// \param c Calloc'd range data (just a tag).
     pma_memory(const std::string &description, uint64_t length, const callocd &c);
 
-    /// \brief Constructor for mock ranges.
-    /// \param description Informative description of PMA entry for use in error messages
-    /// \param length Length of range.
-    /// \param m Mock'd range data (just a tag).
-    pma_memory(const std::string &description, uint64_t length, const mockd &m);
-
     /// \brief No copy constructor
     pma_memory(const pma_memory &other) = delete;
 
@@ -551,15 +542,6 @@ pma_entry make_callocd_memory_pma_entry(const std::string &description, uint64_t
 pma_entry make_mmapd_memory_pma_entry(const std::string &description, uint64_t start, uint64_t length,
     const std::string &path, bool shared);
 
-/// \brief Creates a PMA entry for a new mock memory region (no allocation).
-/// \param description Informative description of PMA entry for use in error messages
-/// \param start Start of physical memory range in the target address
-/// space on which to map the memory region.
-/// \param length Length of physical memory range in the
-/// target address space on which to map the memory region.
-/// \returns Corresponding PMA entry
-pma_entry make_mockd_memory_pma_entry(const std::string &description, uint64_t start, uint64_t length);
-
 /// \brief Creates a PMA entry for a new memory-mapped IO device.
 /// \param description Informative description of PMA entry for use in error messages
 /// \param start Start of physical memory range in the target address
diff --git a/src/replay-step-state-access.h b/src/replay-step-state-access.h
index b8d61d3d2..6f1162223 100644
--- a/src/replay-step-state-access.h
+++ b/src/replay-step-state-access.h
@@ -20,12 +20,10 @@
 #include <cstdlib>
 #include <optional>
 
-#include "clint.h"
 #include "compiler-defines.h"
 #include "device-state-access.h"
-#include "htif.h"
 #include "i-state-access.h"
-#include "plic.h"
+#include "mock-pma-entry.h"
 #include "pma-constants.h"
 #include "replay-step-state-access-interop.h"
 #include "riscv-constants.h"
@@ -42,136 +40,6 @@ namespace cartesi {
 // \file this code is designed to be compiled for a free-standing environment.
 // Environment-specific functions have the prefix "interop_" and are declared in "replay-step-state-access-interop.h"
 
-//??D can we merge this calss with uarch_pma_entry in uarch/uarch-machine-state-access.h ?
-//??D maybe implement base class in pma.h and subclass here if there is some minor difference?
-class mock_pma_entry final {
-public:
-    struct flags {
-        bool M;
-        bool IO;
-        bool E;
-        bool R;
-        bool W;
-        bool X;
-        bool IR;
-        bool IW;
-        PMA_ISTART_DID DID;
-    };
-
-private:
-    uint64_t m_pma_index;
-    uint64_t m_start;
-    uint64_t m_length;
-    flags m_flags;
-    const pma_driver *m_driver{nullptr};
-
-    static constexpr flags split_flags(uint64_t istart) {
-        flags f{};
-        f.M = ((istart & PMA_ISTART_M_MASK) >> PMA_ISTART_M_SHIFT) != 0;
-        f.IO = ((istart & PMA_ISTART_IO_MASK) >> PMA_ISTART_IO_SHIFT) != 0;
-        f.E = ((istart & PMA_ISTART_E_MASK) >> PMA_ISTART_E_SHIFT) != 0;
-        f.R = ((istart & PMA_ISTART_R_MASK) >> PMA_ISTART_R_SHIFT) != 0;
-        f.W = ((istart & PMA_ISTART_W_MASK) >> PMA_ISTART_W_SHIFT) != 0;
-        f.X = ((istart & PMA_ISTART_X_MASK) >> PMA_ISTART_X_SHIFT) != 0;
-        f.IR = ((istart & PMA_ISTART_IR_MASK) >> PMA_ISTART_IR_SHIFT) != 0;
-        f.IW = ((istart & PMA_ISTART_IW_MASK) >> PMA_ISTART_IW_SHIFT) != 0;
-        f.DID = static_cast<PMA_ISTART_DID>((istart & PMA_ISTART_DID_MASK) >> PMA_ISTART_DID_SHIFT);
-        return f;
-    }
-
-public:
-    mock_pma_entry(uint64_t pma_index, uint64_t istart, uint64_t ilength) :
-        m_pma_index{pma_index},
-        m_start{istart & PMA_ISTART_START_MASK},
-        m_length{ilength},
-        m_flags{split_flags(istart)} {
-        if (m_flags.IO) {
-            switch (m_flags.DID) {
-                case PMA_ISTART_DID::shadow_state:
-                    m_driver = &shadow_state_driver;
-                    break;
-                case PMA_ISTART_DID::shadow_TLB:
-                    m_driver = &shadow_tlb_driver;
-                    break;
-                case PMA_ISTART_DID::CLINT:
-                    m_driver = &clint_driver;
-                    break;
-                case PMA_ISTART_DID::PLIC:
-                    m_driver = &plic_driver;
-                    break;
-                case PMA_ISTART_DID::HTIF:
-                    m_driver = &htif_driver;
-                    break;
-                default:
-                    interop_throw_runtime_error("unsupported device in build_mock_pma_entry");
-                    break;
-            }
-        }
-    }
-
-    uint64_t get_index() const {
-        return m_pma_index;
-    }
-
-    flags get_flags() const {
-        return m_flags;
-    }
-
-    uint64_t get_start() const {
-        return m_start;
-    }
-
-    uint64_t get_length() const {
-        return m_length;
-    }
-
-    bool get_istart_M() const {
-        return m_flags.M;
-    }
-
-    bool get_istart_IO() const {
-        return m_flags.IO;
-    }
-
-    bool get_istart_E() const {
-        return m_flags.E;
-    }
-
-    bool get_istart_R() const {
-        return m_flags.R;
-    }
-
-    bool get_istart_W() const {
-        return m_flags.W;
-    }
-
-    bool get_istart_X() const {
-        return m_flags.X;
-    }
-
-    bool get_istart_IR() const {
-        return m_flags.IR;
-    }
-
-    const auto *get_driver() const {
-        return m_driver;
-    }
-
-    const auto &get_device_noexcept() const {
-        return *this;
-    }
-
-    static void *get_context() {
-        return nullptr;
-    }
-
-    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    void mark_dirty_page(uint64_t address_in_range) {
-        (void) address_in_range;
-        // Dummy implementation.
-    }
-};
-
 // \brief checks if a buffer is large enough to hold a data block of N elements of size S starting at a given offset
 // \param max The maximum offset allowed
 // \param current The current offset
@@ -896,8 +764,11 @@ class replay_step_state_access : public i_state_access<replay_step_state_access,
         assert(index < PMA_MAX);
         const uint64_t istart = read_pma_istart(index);
         const uint64_t ilength = read_pma_ilength(index);
-        if (!m_context.pmas[index]) {
-            m_context.pmas[index] = mock_pma_entry(index, istart, ilength);
+        // NOLINTNEXTLINE(bugprone-narrowing-conversions)
+        const int i = static_cast<int>(index);
+        if (!m_pmas[i]) {
+            m_pmas[i] =
+                make_mock_pma_entry(index, istart, ilength, [](const char *err) { interop_throw_runtime_error(err); });
         }
         // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
         return m_context.pmas[index].value();
diff --git a/uarch/uarch-machine-state-access.h b/uarch/uarch-machine-state-access.h
index aa9346eb9..d43c64d86 100644
--- a/uarch/uarch-machine-state-access.h
+++ b/uarch/uarch-machine-state-access.h
@@ -19,10 +19,9 @@
 
 #include "uarch-runtime.h" // must be included first, because of assert
 
-#include "clint.h"
-#include "plic.h"
+#define MOCK_THROW_RUNTIME_ERROR(err) abort()
+#include "mock-pma-entry.h"
 #include "device-state-access.h"
-#include "htif.h"
 #include "i-state-access.h"
 #include "pma-constants.h"
 #include "riscv-constants.h"
@@ -50,142 +49,9 @@ static void raw_write_memory(uint64_t paddr, T val) {
     *p = val;
 }
 
-//??D can we merge this class with the mock_pma_entry in src/replay-step-state-access.h ?
-//??D maybe implement base class in pma.h and subclass here if there is some minor difference?
-class uarch_pma_entry final {
-public:
-    struct flags {
-        bool M{};
-        bool IO{};
-        bool E{};
-        bool R{};
-        bool W{};
-        bool X{};
-        bool IR{};
-        bool IW{};
-        PMA_ISTART_DID DID{PMA_ISTART_DID::memory};
-    };
-
-private:
-
-    uint64_t m_pma_index;
-    uint64_t m_start;
-    uint64_t m_length;
-    flags m_flags;
-    const pma_driver *m_driver{nullptr};
-
-    static constexpr flags split_flags(uint64_t istart) {
-        flags f{};
-        f.M = (((istart & PMA_ISTART_M_MASK) >> PMA_ISTART_M_SHIFT) != 0);
-        f.IO = (((istart & PMA_ISTART_IO_MASK) >> PMA_ISTART_IO_SHIFT) != 0);
-        f.E = (((istart & PMA_ISTART_E_MASK) >> PMA_ISTART_E_SHIFT) != 0);
-        f.R = (((istart & PMA_ISTART_R_MASK) >> PMA_ISTART_R_SHIFT) != 0);
-        f.W = (((istart & PMA_ISTART_W_MASK) >> PMA_ISTART_W_SHIFT) != 0);
-        f.X = (((istart & PMA_ISTART_X_MASK) >> PMA_ISTART_X_SHIFT) != 0);
-        f.IR = (((istart & PMA_ISTART_IR_MASK) >> PMA_ISTART_IR_SHIFT) != 0);
-        f.IW = (((istart & PMA_ISTART_IW_MASK) >> PMA_ISTART_IW_SHIFT) != 0);
-        f.DID = static_cast<PMA_ISTART_DID>((istart & PMA_ISTART_DID_MASK) >> PMA_ISTART_DID_SHIFT);
-        return f;
-    }
-
-public:
-
-    uarch_pma_entry(uint64_t pma_index, uint64_t istart, uint64_t ilength) :
-        m_pma_index{pma_index},
-        m_start{istart & PMA_ISTART_START_MASK},
-        m_length{ilength},
-        m_flags{split_flags(istart)} {
-        if (m_flags.IO) {
-            switch (m_flags.DID) {
-                case PMA_ISTART_DID::shadow_state:
-                    m_driver = &shadow_state_driver;
-                    break;
-                case PMA_ISTART_DID::shadow_TLB:
-                    m_driver = &shadow_tlb_driver;
-                    break;
-                case PMA_ISTART_DID::CLINT:
-                    m_driver = &clint_driver;
-                    break;
-                case PMA_ISTART_DID::PLIC:
-                    m_driver = &plic_driver;
-                    break;
-                case PMA_ISTART_DID::HTIF:
-                    m_driver = &htif_driver;
-                    break;
-                default:
-                    // Other unsupported device in uarch (eg. VirtIO)
-                    abort();
-                    break;
-            }
-        }
-    }
-
-    uint64_t get_index() const {
-        return m_pma_index;
-    }
-
-    flags get_flags() const {
-        return m_flags;
-    }
-
-    uint64_t get_start() const {
-        return m_start;
-    }
-
-    uint64_t get_length() const {
-        return m_length;
-    }
-
-    bool get_istart_M() const {
-        return m_flags.M;
-    }
-
-    bool get_istart_IO() const {
-        return m_flags.IO;
-    }
-
-    bool get_istart_E() const {
-        return m_flags.E;
-    }
-
-    bool get_istart_R() const {
-        return m_flags.R;
-    }
-
-    bool get_istart_W() const {
-        return m_flags.W;
-    }
-
-    bool get_istart_X() const {
-        return m_flags.X;
-    }
-
-    bool get_istart_IR() const {
-        return m_flags.IR;
-    }
-
-    const pma_driver *get_driver() const {
-        return m_driver;
-    }
-
-    const auto &get_device_noexcept() const {
-        return *this;
-    }
-
-    static void *get_context() {
-        return nullptr;
-    }
-
-    void mark_dirty_page(uint64_t /*address_in_range*/) {
-        // Dummy implementation here.
-        // This runs in microarchitecture.
-        // The Host pages affected by writes will be marked dirty by uarch_bridge.
-    }
-};
-
 // Provides access to the state of the big emulator from microcode
-class uarch_machine_state_access : public i_state_access<uarch_machine_state_access, uarch_pma_entry> {
-    std::array<std::optional<uarch_pma_entry>, PMA_MAX> &m_pmas; //NOLINT(cppcoreguidelines-avoid-const-or-ref-data-members)
+class uarch_machine_state_access : public i_state_access<uarch_machine_state_access, mock_pma_entry> {
+    std::array<std::optional<mock_pma_entry>, PMA_MAX> m_pmas;
 
 public:
     explicit uarch_machine_state_access(std::array<std::optional<uarch_pma_entry>, PMA_MAX>& pmas) : m_pmas(pmas) {}
@@ -196,7 +62,7 @@ class uarch_machine_state_access : public i_state_access<uarch_machine_state_acc
     ~uarch_machine_state_access() = default;
 
 private:
-    friend i_state_access<uarch_machine_state_access, uarch_pma_entry>;
+    friend i_state_access<uarch_machine_state_access, mock_pma_entry>;
 
     // NOLINTBEGIN(readability-convert-member-functions-to-static)
 
@@ -569,17 +435,21 @@ class uarch_machine_state_access : public i_state_access<uarch_machine_state_acc
         raw_write_memory(paddr, val);
     }
 
-    uarch_pma_entry &do_read_pma_entry(uint64_t index) {
+    mock_pma_entry &do_read_pma_entry(uint64_t index) {
         const uint64_t istart = read_pma_istart(index);
         const uint64_t ilength = read_pma_ilength(index);
-        if (!m_pmas[index]) {
-            m_pmas[index] = uarch_pma_entry{index, istart, ilength};
+        // NOLINTNEXTLINE(bugprone-narrowing-conversions)
+        int i = static_cast<int>(index);
+        if (!m_pmas[i]) {
+            m_pmas[i] = make_mock_pma_entry(index, istart, ilength, [](const char * /*err*/) {
+                abort();
+            });
         }
         // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
         return m_pmas[index].value();
     }
 
-    unsigned char *do_get_host_memory(uarch_pma_entry &/*pma*/) {
+    unsigned char *do_get_host_memory(mock_pma_entry &/*pma*/) {
         return nullptr;
     }
 
@@ -639,14 +509,14 @@ class uarch_machine_state_access : public i_state_access<uarch_machine_state_acc
     }
 
     template <TLB_entry_type ETYPE>
-    unsigned char *do_replace_tlb_entry(uint64_t vaddr, uint64_t paddr, uarch_pma_entry &pma) {
+    unsigned char *do_replace_tlb_entry(uint64_t vaddr, uint64_t paddr, mock_pma_entry &pma) {
         uint64_t eidx = tlb_get_entry_index(vaddr);
         volatile tlb_cold_entry &tlbce = do_get_tlb_entry_cold<ETYPE>(eidx);
         volatile tlb_hot_entry &tlbhe = do_get_tlb_hot_entry<ETYPE>(eidx);
         // Mark page that was on TLB as dirty so we know to update the Merkle tree
         if constexpr (ETYPE == TLB_WRITE) {
             if (tlbhe.vaddr_page != TLB_INVALID_PAGE) {
-                uarch_pma_entry &pma = do_read_pma_entry(tlbce.pma_index);
+                mock_pma_entry &pma = do_read_pma_entry(tlbce.pma_index);
                 pma.mark_dirty_page(tlbce.paddr_page - pma.get_start());
             }
         }
@@ -675,7 +545,7 @@ class uarch_machine_state_access : public i_state_access<uarch_machine_state_acc
             if (tlbhe.vaddr_page != TLB_INVALID_PAGE) {
                 tlbhe.vaddr_page = TLB_INVALID_PAGE;
                 const volatile tlb_cold_entry &tlbce = do_get_tlb_entry_cold<ETYPE>(eidx);
-                uarch_pma_entry &pma = do_read_pma_entry(tlbce.pma_index);
+                mock_pma_entry &pma = do_read_pma_entry(tlbce.pma_index);
                 pma.mark_dirty_page(tlbce.paddr_page - pma.get_start());
             } else {
                 tlbhe.vaddr_page = TLB_INVALID_PAGE;

From 1153cc63b6899829a68c40cfd8d455a7ca9b050f Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Mon, 20 Jan 2025 14:39:28 +0000
Subject: [PATCH 02/82] refactor: remove htif depencency on os.h

---
 src/Makefile                       |    2 +-
 src/device-state-access.h          |    8 +
 src/htif.cpp                       |    6 +-
 src/i-device-state-access.h        |   14 +
 src/i-state-access.h               |   12 +
 src/record-step-state-access.h     |    8 +
 src/replay-step-state-access.h     |    8 +
 src/state-access.h                 |   11 +
 uarch/uarch-machine-state-access.h |   41 +-
 uarch/uarch-printf.c               | 1834 ++++++++++++++--------------
 uarch/uarch-printf.h               |  225 ++--
 uarch/uarch-runtime.cpp            |   20 -
 uarch/uarch-runtime.h              |    2 +-
 13 files changed, 1113 insertions(+), 1078 deletions(-)

diff --git a/src/Makefile b/src/Makefile
index eff7a414c..2fcc1a4c4 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -282,7 +282,7 @@ CLANG_TIDY=clang-tidy
 CLANG_TIDY_TARGETS=$(patsubst %.cpp,%.clang-tidy,$(patsubst %.c,%.clang-tidy,$(LINTER_SOURCES)))
 
 CLANG_FORMAT=clang-format
-CLANG_FORMAT_UARCH_FILES:=$(wildcard ../uarch/*.cpp)
+CLANG_FORMAT_UARCH_FILES:=$(wildcard ../uarch/*.cpp, ../uarch/*.h)
 CLANG_FORMAT_UARCH_FILES:=$(filter-out %uarch-printf%,$(strip $(CLANG_FORMAT_UARCH_FILES)))
 CLANG_FORMAT_FILES:=$(wildcard *.cpp) $(wildcard *.c) $(wildcard *.h) $(wildcard *.hpp) $(CLANG_FORMAT_UARCH_FILES)
 CLANG_FORMAT_IGNORE_FILES:=interpret-jump-table.h
diff --git a/src/device-state-access.h b/src/device-state-access.h
index 97dcad701..812d2c1cb 100644
--- a/src/device-state-access.h
+++ b/src/device-state-access.h
@@ -146,6 +146,14 @@ class device_state_access : public i_device_state_access {
     bool do_write_memory(uint64_t paddr, const unsigned char *data, uint64_t length) override {
         return m_a.write_memory(paddr, data, length);
     }
+
+    void do_putchar(uint8_t c) override {
+        return m_a.putchar(c);
+    }
+
+    int do_getchar() override {
+        return m_a.getchar();
+    }
 };
 
 } // namespace cartesi
diff --git a/src/htif.cpp b/src/htif.cpp
index fc5b00b39..9ffcec2ef 100644
--- a/src/htif.cpp
+++ b/src/htif.cpp
@@ -19,7 +19,6 @@
 #include "htif.h"
 #include "i-device-state-access.h"
 #include "interpret.h"
-#include "os.h"
 #include "pma-driver.h"
 
 namespace cartesi {
@@ -93,15 +92,14 @@ static execute_status htif_console(i_device_state_access *a, uint64_t cmd, uint6
     if (cmd < 64 && (((a->read_htif_iconsole() >> cmd) & 1) != 0)) {
         if (cmd == HTIF_CONSOLE_CMD_PUTCHAR) {
             const uint8_t ch = data & 0xff;
-            os_putchar(ch);
+            a->putchar(ch);
             a->write_htif_fromhost(HTIF_BUILD(HTIF_DEV_CONSOLE, cmd, 0, 0));
         } else if (cmd == HTIF_CONSOLE_CMD_GETCHAR) {
             // In blockchain, this command will never be enabled as there is no way to input the same character
             // to every participant in a dispute: where would c come from? So if the code reached here in the
             // blockchain, there must be some serious bug
             // In interactive mode, we just get the next character from the console and send it back in the ack
-            os_poll_tty(0);
-            const int c = os_getchar() + 1;
+            const int c = a->getchar() + 1;
             a->write_htif_fromhost(HTIF_BUILD(HTIF_DEV_CONSOLE, cmd, 0, static_cast<uint32_t>(c)));
         }
     }
diff --git a/src/i-device-state-access.h b/src/i-device-state-access.h
index efdfaa06e..784e2c684 100644
--- a/src/i-device-state-access.h
+++ b/src/i-device-state-access.h
@@ -193,6 +193,18 @@ class i_device_state_access {
         return do_write_memory(paddr, data, length);
     }
 
+    /// \brief Writes a character to the console
+    /// \param c Character to output
+    void putchar(uint8_t c) {
+        do_putchar(c);
+    }
+
+    /// \brief Reads a character from the console
+    /// \returns Character read if any, -1 otherwise
+    int getchar() {
+        return do_getchar();
+    }
+
 private:
     virtual void do_set_mip(uint64_t mask) = 0;
     virtual void do_reset_mip(uint64_t mask) = 0;
@@ -216,6 +228,8 @@ class i_device_state_access {
     virtual uint64_t do_read_htif_iyield() = 0;
     virtual bool do_read_memory(uint64_t paddr, unsigned char *data, uint64_t length) = 0;
     virtual bool do_write_memory(uint64_t paddr, const unsigned char *data, uint64_t length) = 0;
+    virtual void do_putchar(uint8_t c) = 0;
+    virtual int do_getchar() = 0;
 };
 
 } // namespace cartesi
diff --git a/src/i-state-access.h b/src/i-state-access.h
index 694d728ad..d255899ee 100644
--- a/src/i-state-access.h
+++ b/src/i-state-access.h
@@ -740,6 +740,18 @@ class i_state_access { // CRTP
         return derived().do_write_memory_with_padding(paddr, data, data_length, write_length_log2_size);
     }
 
+    /// \brief Writes a character to the console
+    /// \param c Character to output
+    void putchar(uint8_t c) {
+        return derived().do_putchar(c);
+    }
+
+    /// \brief Reads a character from the console
+    /// \returns Character read if any, -1 otherwise
+    int getchar() {
+        return derived().do_getchar();
+    }
+
 #ifdef DUMP_COUNTERS
     auto &get_statistics() {
         return derived().do_get_statistics();
diff --git a/src/record-step-state-access.h b/src/record-step-state-access.h
index b1b443d78..a54cc2555 100644
--- a/src/record-step-state-access.h
+++ b/src/record-step-state-access.h
@@ -756,6 +756,14 @@ class record_step_state_access : public i_state_access<record_step_state_access,
     bool do_get_soft_yield() {
         return m_m.get_state().soft_yield;
     }
+
+    void do_putchar(uint8_t c) { // NOLINT(readability-convert-member-functions-to-static)
+        os_putchar(c);
+    }
+
+    int do_getchar() { // NOLINT(readability-convert-member-functions-to-static)
+        return -1;
+    }
 };
 
 } // namespace cartesi
diff --git a/src/replay-step-state-access.h b/src/replay-step-state-access.h
index 6f1162223..d219a0c4c 100644
--- a/src/replay-step-state-access.h
+++ b/src/replay-step-state-access.h
@@ -893,6 +893,14 @@ class replay_step_state_access : public i_state_access<replay_step_state_access,
     bool do_get_soft_yield() { // NOLINT(readability-convert-member-functions-to-static)
         return false;
     }
+
+    void do_putchar(uint8_t /* c */) { // NOLINT(readability-convert-member-functions-to-static)
+        ;
+    }
+
+    int do_getchar() { // NOLINT(readability-convert-member-functions-to-static)
+        return -1;
+    }
 };
 
 } // namespace cartesi
diff --git a/src/state-access.h b/src/state-access.h
index 83e837c27..66f462efb 100644
--- a/src/state-access.h
+++ b/src/state-access.h
@@ -598,6 +598,17 @@ class state_access : public i_state_access<state_access, pma_entry> {
         }
     }
 
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    void do_putchar(uint8_t c) {
+        os_putchar(c);
+    }
+
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    int do_getchar() {
+        os_poll_tty(0);
+        return os_getchar();
+    }
+
 #ifdef DUMP_COUNTERS
     machine_statistics &do_get_statistics() {
         return m_m.get_state().stats;
diff --git a/uarch/uarch-machine-state-access.h b/uarch/uarch-machine-state-access.h
index d43c64d86..6d21dae88 100644
--- a/uarch/uarch-machine-state-access.h
+++ b/uarch/uarch-machine-state-access.h
@@ -20,17 +20,17 @@
 #include "uarch-runtime.h" // must be included first, because of assert
 
 #define MOCK_THROW_RUNTIME_ERROR(err) abort()
-#include "mock-pma-entry.h"
+#include "compiler-defines.h"
 #include "device-state-access.h"
 #include "i-state-access.h"
+#include "machine-reg.h"
+#include "mock-pma-entry.h"
 #include "pma-constants.h"
 #include "riscv-constants.h"
-#include "machine-reg.h"
 #include "shadow-pmas.h"
+#include "strict-aliasing.h"
 #include "uarch-constants.h"
 #include "uarch-defines.h"
-#include "strict-aliasing.h"
-#include "compiler-defines.h"
 #include <optional>
 
 namespace cartesi {
@@ -66,10 +66,9 @@ class uarch_machine_state_access : public i_state_access<uarch_machine_state_acc
 
     // NOLINTBEGIN(readability-convert-member-functions-to-static)
 
-    void do_push_bracket(bracket_type /*type*/, const char */*text*/) {
-    }
+    void do_push_bracket(bracket_type /*type*/, const char * /*text*/) {}
 
-    int do_make_scoped_note(const char */*text*/) {
+    int do_make_scoped_note(const char * /*text*/) {
         return 0;
     }
 
@@ -414,24 +413,24 @@ class uarch_machine_state_access : public i_state_access<uarch_machine_state_acc
     }
 
     template <typename T>
-    void do_read_memory_word(uint64_t paddr, const unsigned char */*hpage*/, uint64_t /*hoffset*/, T *pval) {
+    void do_read_memory_word(uint64_t paddr, const unsigned char * /*hpage*/, uint64_t /*hoffset*/, T *pval) {
         *pval = raw_read_memory<T>(paddr);
     }
 
-    bool do_read_memory(uint64_t /*paddr*/, unsigned char */*data*/, uint64_t /*length*/) {
+    bool do_read_memory(uint64_t /*paddr*/, unsigned char * /*data*/, uint64_t /*length*/) {
         // This is not implemented yet because it's not being used
         abort();
         return false;
     }
 
-    bool do_write_memory(uint64_t /*paddr*/, const unsigned char */*data*/, uint64_t /*length*/) {
+    bool do_write_memory(uint64_t /*paddr*/, const unsigned char * /*data*/, uint64_t /*length*/) {
         // This is not implemented yet because it's not being used
         abort();
         return false;
     }
 
     template <typename T>
-    void do_write_memory_word(uint64_t paddr, const unsigned char */*hpage*/, uint64_t /*hoffset*/, T val) {
+    void do_write_memory_word(uint64_t paddr, const unsigned char * /*hpage*/, uint64_t /*hoffset*/, T val) {
         raw_write_memory(paddr, val);
     }
 
@@ -441,20 +440,18 @@ class uarch_machine_state_access : public i_state_access<uarch_machine_state_acc
         // NOLINTNEXTLINE(bugprone-narrowing-conversions)
         int i = static_cast<int>(index);
         if (!m_pmas[i]) {
-            m_pmas[i] = make_mock_pma_entry(index, istart, ilength, [](const char * /*err*/) {
-                abort();
-            });
+            m_pmas[i] = make_mock_pma_entry(index, istart, ilength, [](const char * /*err*/) { abort(); });
         }
         // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
         return m_pmas[index].value();
     }
 
-    unsigned char *do_get_host_memory(mock_pma_entry &/*pma*/) {
+    unsigned char *do_get_host_memory(mock_pma_entry & /*pma*/) {
         return nullptr;
     }
 
     template <TLB_entry_type ETYPE>
-    volatile tlb_hot_entry& do_get_tlb_hot_entry(uint64_t eidx) {
+    volatile tlb_hot_entry &do_get_tlb_hot_entry(uint64_t eidx) {
         // Volatile is used, so the compiler does not optimize out, or do of order writes.
         // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast,performance-no-int-to-ptr)
         volatile tlb_hot_entry *tlbe = reinterpret_cast<tlb_hot_entry *>(tlb_get_entry_hot_abs_addr<ETYPE>(eidx));
@@ -462,7 +459,7 @@ class uarch_machine_state_access : public i_state_access<uarch_machine_state_acc
     }
 
     template <TLB_entry_type ETYPE>
-    volatile tlb_cold_entry& do_get_tlb_entry_cold(uint64_t eidx) {
+    volatile tlb_cold_entry &do_get_tlb_entry_cold(uint64_t eidx) {
         // Volatile is used, so the compiler does not optimize out, or do of order writes.
         // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast,performance-no-int-to-ptr)
         volatile tlb_cold_entry *tlbe = reinterpret_cast<tlb_cold_entry *>(tlb_get_entry_cold_abs_addr<ETYPE>(eidx));
@@ -534,7 +531,7 @@ class uarch_machine_state_access : public i_state_access<uarch_machine_state_acc
         tlbhe.vaddr_page = vaddr_page; // "unlock"
         // Note that we can't write here the correct vh_offset value, because it depends in a host pointer,
         // however the uarch memory bridge will take care of updating it.
-        return cast_addr_to_ptr<unsigned char*>(paddr_page);
+        return cast_addr_to_ptr<unsigned char *>(paddr_page);
     }
 
     template <TLB_entry_type ETYPE>
@@ -573,6 +570,14 @@ class uarch_machine_state_access : public i_state_access<uarch_machine_state_acc
         return false;
     }
 
+    void do_putchar(uint8_t c) {
+        _putchar(c);
+    }
+
+    int do_getchar() {
+        return -1;
+    }
+
     // NOLINTEND(readability-convert-member-functions-to-static)
 };
 
diff --git a/uarch/uarch-printf.c b/uarch/uarch-printf.c
index eb1c9391e..d328b95c0 100644
--- a/uarch/uarch-printf.c
+++ b/uarch/uarch-printf.c
@@ -1,917 +1,917 @@
-///////////////////////////////////////////////////////////////////////////////
-// \author (c) Marco Paland (info@paland.com)
-//             2014-2019, PALANDesign Hannover, Germany
-//
-// \license The MIT License (MIT)
-//
-// Permission is hereby granted, free of charge, to any person obtaining a copy
-// of this software and associated documentation files (the "Software"), to deal
-// in the Software without restriction, including without limitation the rights
-// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-// copies of the Software, and to permit persons to whom the Software is
-// furnished to do so, subject to the following conditions:
-//
-// The above copyright notice and this permission notice shall be included in
-// all copies or substantial portions of the Software.
-//
-// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-// THE SOFTWARE.
-//
-// \brief Tiny printf, sprintf and (v)snprintf implementation, optimized for speed on
-//        embedded systems with a very limited resources. These routines are thread
-//        safe and reentrant!
-//        Use this instead of the bloated standard/newlib printf cause these use
-//        malloc for printf (and may not be thread safe).
-//
-///////////////////////////////////////////////////////////////////////////////
-
-#define PRINTF_DISABLE_SUPPORT_FLOAT
-#define PRINTF_DISABLE_SUPPORT_EXPONENTIAL
-
-#include <stdbool.h>
-#include <stdint.h>
-
-#include "uarch-printf.h"
-
-
-// define this globally (e.g. gcc -DPRINTF_INCLUDE_CONFIG_H ...) to include the
-// printf_config.h header file
-// default: undefined
-#ifdef PRINTF_INCLUDE_CONFIG_H
-#include "printf_config.h"
-#endif
-
-
-// 'ntoa' conversion buffer size, this must be big enough to hold one converted
-// numeric number including padded zeros (dynamically created on stack)
-// default: 32 byte
-#ifndef PRINTF_NTOA_BUFFER_SIZE
-#define PRINTF_NTOA_BUFFER_SIZE    32U
-#endif
-
-// 'ftoa' conversion buffer size, this must be big enough to hold one converted
-// float number including padded zeros (dynamically created on stack)
-// default: 32 byte
-#ifndef PRINTF_FTOA_BUFFER_SIZE
-#define PRINTF_FTOA_BUFFER_SIZE    32U
-#endif
-
-// support for the floating point type (%f)
-// default: activated
-#ifndef PRINTF_DISABLE_SUPPORT_FLOAT
-#define PRINTF_SUPPORT_FLOAT
-#endif
-
-// support for exponential floating point notation (%e/%g)
-// default: activated
-#ifndef PRINTF_DISABLE_SUPPORT_EXPONENTIAL
-#define PRINTF_SUPPORT_EXPONENTIAL
-#endif
-
-// define the default floating point precision
-// default: 6 digits
-#ifndef PRINTF_DEFAULT_FLOAT_PRECISION
-#define PRINTF_DEFAULT_FLOAT_PRECISION  6U
-#endif
-
-// define the largest float suitable to print with %f
-// default: 1e9
-#ifndef PRINTF_MAX_FLOAT
-#define PRINTF_MAX_FLOAT  1e9
-#endif
-
-// support for the long long types (%llu or %p)
-// default: activated
-#ifndef PRINTF_DISABLE_SUPPORT_LONG_LONG
-#define PRINTF_SUPPORT_LONG_LONG
-#endif
-
-// support for the ptrdiff_t type (%t)
-// ptrdiff_t is normally defined in <stddef.h> as long or long long type
-// default: activated
-#ifndef PRINTF_DISABLE_SUPPORT_PTRDIFF_T
-#define PRINTF_SUPPORT_PTRDIFF_T
-#endif
-
-///////////////////////////////////////////////////////////////////////////////
-
-// internal flag definitions
-#define FLAGS_ZEROPAD   (1U <<  0U)
-#define FLAGS_LEFT      (1U <<  1U)
-#define FLAGS_PLUS      (1U <<  2U)
-#define FLAGS_SPACE     (1U <<  3U)
-#define FLAGS_HASH      (1U <<  4U)
-#define FLAGS_UPPERCASE (1U <<  5U)
-#define FLAGS_CHAR      (1U <<  6U)
-#define FLAGS_SHORT     (1U <<  7U)
-#define FLAGS_LONG      (1U <<  8U)
-#define FLAGS_LONG_LONG (1U <<  9U)
-#define FLAGS_PRECISION (1U << 10U)
-#define FLAGS_ADAPT_EXP (1U << 11U)
-
-
-// import float.h for DBL_MAX
-#if defined(PRINTF_SUPPORT_FLOAT)
-#include <float.h>
-#endif
-
-
-// output function type
-typedef void (*out_fct_type)(char character, void* buffer, size_t idx, size_t maxlen);
-
-
-// wrapper (used as buffer) for output function type
-typedef struct {
-  void  (*fct)(char character, void* arg);
-  void* arg;
-} out_fct_wrap_type;
-
-
-// internal buffer output
-static inline void _out_buffer(char character, void* buffer, size_t idx, size_t maxlen)
-{
-  if (idx < maxlen) {
-    ((char*)buffer)[idx] = character;
-  }
-}
-
-
-// internal null output
-static inline void _out_null(char character, void* buffer, size_t idx, size_t maxlen)
-{
-  (void)character; (void)buffer; (void)idx; (void)maxlen;
-}
-
-
-// internal _putchar wrapper
-static inline void _out_char(char character, void* buffer, size_t idx, size_t maxlen)
-{
-  (void)buffer; (void)idx; (void)maxlen;
-  if (character) {
-    _putchar(character);
-  }
-}
-
-
-// internal output function wrapper
-static inline void _out_fct(char character, void* buffer, size_t idx, size_t maxlen)
-{
-  (void)idx; (void)maxlen;
-  if (character) {
-    // buffer is the output fct pointer
-    ((out_fct_wrap_type*)buffer)->fct(character, ((out_fct_wrap_type*)buffer)->arg);
-  }
-}
-
-
-// internal secure strlen
-// \return The length of the string (excluding the terminating 0) limited by 'maxsize'
-static inline unsigned int _strnlen_s(const char* str, size_t maxsize)
-{
-  const char* s;
-  for (s = str; *s && maxsize--; ++s);
-  return (unsigned int)(s - str);
-}
-
-
-// internal test if char is a digit (0-9)
-// \return true if char is a digit
-static inline bool _is_digit(char ch)
-{
-  return (ch >= '0') && (ch <= '9');
-}
-
-
-// internal ASCII string to unsigned int conversion
-static unsigned int _atoi(const char** str)
-{
-  unsigned int i = 0U;
-  while (_is_digit(**str)) {
-    i = i * 10U + (unsigned int)(*((*str)++) - '0');
-  }
-  return i;
-}
-
-
-// output the specified string in reverse, taking care of any zero-padding
-static size_t _out_rev(out_fct_type out, char* buffer, size_t idx, size_t maxlen, const char* buf, size_t len, unsigned int width, unsigned int flags)
-{
-  const size_t start_idx = idx;
-
-  // pad spaces up to given width
-  if (!(flags & FLAGS_LEFT) && !(flags & FLAGS_ZEROPAD)) {
-    for (size_t i = len; i < width; i++) {
-      out(' ', buffer, idx++, maxlen);
-    }
-  }
-
-  // reverse string
-  while (len) {
-    out(buf[--len], buffer, idx++, maxlen);
-  }
-
-  // append pad spaces up to given width
-  if (flags & FLAGS_LEFT) {
-    while (idx - start_idx < width) {
-      out(' ', buffer, idx++, maxlen);
-    }
-  }
-
-  return idx;
-}
-
-
-// internal itoa format
-static size_t _ntoa_format(out_fct_type out, char* buffer, size_t idx, size_t maxlen, char* buf, size_t len, bool negative, unsigned int base, unsigned int prec, unsigned int width, unsigned int flags)
-{
-  // pad leading zeros
-  if (!(flags & FLAGS_LEFT)) {
-    if (width && (flags & FLAGS_ZEROPAD) && (negative || (flags & (FLAGS_PLUS | FLAGS_SPACE)))) {
-      width--;
-    }
-    while ((len < prec) && (len < PRINTF_NTOA_BUFFER_SIZE)) {
-      buf[len++] = '0';
-    }
-    while ((flags & FLAGS_ZEROPAD) && (len < width) && (len < PRINTF_NTOA_BUFFER_SIZE)) {
-      buf[len++] = '0';
-    }
-  }
-
-  // handle hash
-  if (flags & FLAGS_HASH) {
-    if (!(flags & FLAGS_PRECISION) && len && ((len == prec) || (len == width))) {
-      len--;
-      if (len && (base == 16U)) {
-        len--;
-      }
-    }
-    if ((base == 16U) && !(flags & FLAGS_UPPERCASE) && (len < PRINTF_NTOA_BUFFER_SIZE)) {
-      buf[len++] = 'x';
-    }
-    else if ((base == 16U) && (flags & FLAGS_UPPERCASE) && (len < PRINTF_NTOA_BUFFER_SIZE)) {
-      buf[len++] = 'X';
-    }
-    else if ((base == 2U) && (len < PRINTF_NTOA_BUFFER_SIZE)) {
-      buf[len++] = 'b';
-    }
-    if (len < PRINTF_NTOA_BUFFER_SIZE) {
-      buf[len++] = '0';
-    }
-  }
-
-  if (len < PRINTF_NTOA_BUFFER_SIZE) {
-    if (negative) {
-      buf[len++] = '-';
-    }
-    else if (flags & FLAGS_PLUS) {
-      buf[len++] = '+';  // ignore the space if the '+' exists
-    }
-    else if (flags & FLAGS_SPACE) {
-      buf[len++] = ' ';
-    }
-  }
-
-  return _out_rev(out, buffer, idx, maxlen, buf, len, width, flags);
-}
-
-
-// internal itoa for 'long' type
-static size_t _ntoa_long(out_fct_type out, char* buffer, size_t idx, size_t maxlen, unsigned long value, bool negative, unsigned long base, unsigned int prec, unsigned int width, unsigned int flags)
-{
-  char buf[PRINTF_NTOA_BUFFER_SIZE];
-  size_t len = 0U;
-
-  // no hash for 0 values
-  if (!value) {
-    flags &= ~FLAGS_HASH;
-  }
-
-  // write if precision != 0 and value is != 0
-  if (!(flags & FLAGS_PRECISION) || value) {
-    do {
-      const char digit = (char)(value % base);
-      buf[len++] = digit < 10 ? '0' + digit : (flags & FLAGS_UPPERCASE ? 'A' : 'a') + digit - 10;
-      value /= base;
-    } while (value && (len < PRINTF_NTOA_BUFFER_SIZE));
-  }
-
-  return _ntoa_format(out, buffer, idx, maxlen, buf, len, negative, (unsigned int)base, prec, width, flags);
-}
-
-
-// internal itoa for 'long long' type
-#if defined(PRINTF_SUPPORT_LONG_LONG)
-static size_t _ntoa_long_long(out_fct_type out, char* buffer, size_t idx, size_t maxlen, unsigned long long value, bool negative, unsigned long long base, unsigned int prec, unsigned int width, unsigned int flags)
-{
-  char buf[PRINTF_NTOA_BUFFER_SIZE];
-  size_t len = 0U;
-
-  // no hash for 0 values
-  if (!value) {
-    flags &= ~FLAGS_HASH;
-  }
-
-  // write if precision != 0 and value is != 0
-  if (!(flags & FLAGS_PRECISION) || value) {
-    do {
-      const char digit = (char)(value % base);
-      buf[len++] = digit < 10 ? '0' + digit : (flags & FLAGS_UPPERCASE ? 'A' : 'a') + digit - 10;
-      value /= base;
-    } while (value && (len < PRINTF_NTOA_BUFFER_SIZE));
-  }
-
-  return _ntoa_format(out, buffer, idx, maxlen, buf, len, negative, (unsigned int)base, prec, width, flags);
-}
-#endif  // PRINTF_SUPPORT_LONG_LONG
-
-
-#if defined(PRINTF_SUPPORT_FLOAT)
-
-#if defined(PRINTF_SUPPORT_EXPONENTIAL)
-// forward declaration so that _ftoa can switch to exp notation for values > PRINTF_MAX_FLOAT
-static size_t _etoa(out_fct_type out, char* buffer, size_t idx, size_t maxlen, double value, unsigned int prec, unsigned int width, unsigned int flags);
-#endif
-
-
-// internal ftoa for fixed decimal floating point
-static size_t _ftoa(out_fct_type out, char* buffer, size_t idx, size_t maxlen, double value, unsigned int prec, unsigned int width, unsigned int flags)
-{
-  char buf[PRINTF_FTOA_BUFFER_SIZE];
-  size_t len  = 0U;
-  double diff = 0.0;
-
-  // powers of 10
-  static const double pow10[] = { 1, 10, 100, 1000, 10000, 100000, 1000000, 10000000, 100000000, 1000000000 };
-
-  // test for special values
-  if (value != value)
-    return _out_rev(out, buffer, idx, maxlen, "nan", 3, width, flags);
-  if (value < -DBL_MAX)
-    return _out_rev(out, buffer, idx, maxlen, "fni-", 4, width, flags);
-  if (value > DBL_MAX)
-    return _out_rev(out, buffer, idx, maxlen, (flags & FLAGS_PLUS) ? "fni+" : "fni", (flags & FLAGS_PLUS) ? 4U : 3U, width, flags);
-
-  // test for very large values
-  // standard printf behavior is to print EVERY whole number digit -- which could be 100s of characters overflowing your buffers == bad
-  if ((value > PRINTF_MAX_FLOAT) || (value < -PRINTF_MAX_FLOAT)) {
-#if defined(PRINTF_SUPPORT_EXPONENTIAL)
-    return _etoa(out, buffer, idx, maxlen, value, prec, width, flags);
-#else
-    return 0U;
-#endif
-  }
-
-  // test for negative
-  bool negative = false;
-  if (value < 0) {
-    negative = true;
-    value = 0 - value;
-  }
-
-  // set default precision, if not set explicitly
-  if (!(flags & FLAGS_PRECISION)) {
-    prec = PRINTF_DEFAULT_FLOAT_PRECISION;
-  }
-  // limit precision to 9, cause a prec >= 10 can lead to overflow errors
-  while ((len < PRINTF_FTOA_BUFFER_SIZE) && (prec > 9U)) {
-    buf[len++] = '0';
-    prec--;
-  }
-
-  int whole = (int)value;
-  double tmp = (value - whole) * pow10[prec];
-  unsigned long frac = (unsigned long)tmp;
-  diff = tmp - frac;
-
-  if (diff > 0.5) {
-    ++frac;
-    // handle rollover, e.g. case 0.99 with prec 1 is 1.0
-    if (frac >= pow10[prec]) {
-      frac = 0;
-      ++whole;
-    }
-  }
-  else if (diff < 0.5) {
-  }
-  else if ((frac == 0U) || (frac & 1U)) {
-    // if halfway, round up if odd OR if last digit is 0
-    ++frac;
-  }
-
-  if (prec == 0U) {
-    diff = value - (double)whole;
-    if ((!(diff < 0.5) || (diff > 0.5)) && (whole & 1)) {
-      // exactly 0.5 and ODD, then round up
-      // 1.5 -> 2, but 2.5 -> 2
-      ++whole;
-    }
-  }
-  else {
-    unsigned int count = prec;
-    // now do fractional part, as an unsigned number
-    while (len < PRINTF_FTOA_BUFFER_SIZE) {
-      --count;
-      buf[len++] = (char)(48U + (frac % 10U));
-      if (!(frac /= 10U)) {
-        break;
-      }
-    }
-    // add extra 0s
-    while ((len < PRINTF_FTOA_BUFFER_SIZE) && (count-- > 0U)) {
-      buf[len++] = '0';
-    }
-    if (len < PRINTF_FTOA_BUFFER_SIZE) {
-      // add decimal
-      buf[len++] = '.';
-    }
-  }
-
-  // do whole part, number is reversed
-  while (len < PRINTF_FTOA_BUFFER_SIZE) {
-    buf[len++] = (char)(48 + (whole % 10));
-    if (!(whole /= 10)) {
-      break;
-    }
-  }
-
-  // pad leading zeros
-  if (!(flags & FLAGS_LEFT) && (flags & FLAGS_ZEROPAD)) {
-    if (width && (negative || (flags & (FLAGS_PLUS | FLAGS_SPACE)))) {
-      width--;
-    }
-    while ((len < width) && (len < PRINTF_FTOA_BUFFER_SIZE)) {
-      buf[len++] = '0';
-    }
-  }
-
-  if (len < PRINTF_FTOA_BUFFER_SIZE) {
-    if (negative) {
-      buf[len++] = '-';
-    }
-    else if (flags & FLAGS_PLUS) {
-      buf[len++] = '+';  // ignore the space if the '+' exists
-    }
-    else if (flags & FLAGS_SPACE) {
-      buf[len++] = ' ';
-    }
-  }
-
-  return _out_rev(out, buffer, idx, maxlen, buf, len, width, flags);
-}
-
-
-#if defined(PRINTF_SUPPORT_EXPONENTIAL)
-// internal ftoa variant for exponential floating-point type, contributed by Martijn Jasperse <m.jasperse@gmail.com>
-static size_t _etoa(out_fct_type out, char* buffer, size_t idx, size_t maxlen, double value, unsigned int prec, unsigned int width, unsigned int flags)
-{
-  // check for NaN and special values
-  if ((value != value) || (value > DBL_MAX) || (value < -DBL_MAX)) {
-    return _ftoa(out, buffer, idx, maxlen, value, prec, width, flags);
-  }
-
-  // determine the sign
-  const bool negative = value < 0;
-  if (negative) {
-    value = -value;
-  }
-
-  // default precision
-  if (!(flags & FLAGS_PRECISION)) {
-    prec = PRINTF_DEFAULT_FLOAT_PRECISION;
-  }
-
-  // determine the decimal exponent
-  // based on the algorithm by David Gay (https://www.ampl.com/netlib/fp/dtoa.c)
-  union {
-    uint64_t U;
-    double   F;
-  } conv;
-
-  conv.F = value;
-  int exp2 = (int)((conv.U >> 52U) & 0x07FFU) - 1023;           // effectively log2
-  conv.U = (conv.U & ((1ULL << 52U) - 1U)) | (1023ULL << 52U);  // drop the exponent so conv.F is now in [1,2)
-  // now approximate log10 from the log2 integer part and an expansion of ln around 1.5
-  int expval = (int)(0.1760912590558 + exp2 * 0.301029995663981 + (conv.F - 1.5) * 0.289529654602168);
-  // now we want to compute 10^expval but we want to be sure it won't overflow
-  exp2 = (int)(expval * 3.321928094887362 + 0.5);
-  const double z  = expval * 2.302585092994046 - exp2 * 0.6931471805599453;
-  const double z2 = z * z;
-  conv.U = (uint64_t)(exp2 + 1023) << 52U;
-  // compute exp(z) using continued fractions, see https://en.wikipedia.org/wiki/Exponential_function#Continued_fractions_for_ex
-  conv.F *= 1 + 2 * z / (2 - z + (z2 / (6 + (z2 / (10 + z2 / 14)))));
-  // correct for rounding errors
-  if (value < conv.F) {
-    expval--;
-    conv.F /= 10;
-  }
-
-  // the exponent format is "%+03d" and largest value is "307", so set aside 4-5 characters
-  unsigned int minwidth = ((expval < 100) && (expval > -100)) ? 4U : 5U;
-
-  // in "%g" mode, "prec" is the number of *significant figures* not decimals
-  if (flags & FLAGS_ADAPT_EXP) {
-    // do we want to fall-back to "%f" mode?
-    if ((value >= 1e-4) && (value < 1e6)) {
-      if ((int)prec > expval) {
-        prec = (unsigned)((int)prec - expval - 1);
-      }
-      else {
-        prec = 0;
-      }
-      flags |= FLAGS_PRECISION;   // make sure _ftoa respects precision
-      // no characters in exponent
-      minwidth = 0U;
-      expval   = 0;
-    }
-    else {
-      // we use one sigfig for the whole part
-      if ((prec > 0) && (flags & FLAGS_PRECISION)) {
-        --prec;
-      }
-    }
-  }
-
-  // will everything fit?
-  unsigned int fwidth = width;
-  if (width > minwidth) {
-    // we didn't fall-back so subtract the characters required for the exponent
-    fwidth -= minwidth;
-  } else {
-    // not enough characters, so go back to default sizing
-    fwidth = 0U;
-  }
-  if ((flags & FLAGS_LEFT) && minwidth) {
-    // if we're padding on the right, DON'T pad the floating part
-    fwidth = 0U;
-  }
-
-  // rescale the float value
-  if (expval) {
-    value /= conv.F;
-  }
-
-  // output the floating part
-  const size_t start_idx = idx;
-  idx = _ftoa(out, buffer, idx, maxlen, negative ? -value : value, prec, fwidth, flags & ~FLAGS_ADAPT_EXP);
-
-  // output the exponent part
-  if (minwidth) {
-    // output the exponential symbol
-    out((flags & FLAGS_UPPERCASE) ? 'E' : 'e', buffer, idx++, maxlen);
-    // output the exponent value
-    idx = _ntoa_long(out, buffer, idx, maxlen, (expval < 0) ? -expval : expval, expval < 0, 10, 0, minwidth-1, FLAGS_ZEROPAD | FLAGS_PLUS);
-    // might need to right-pad spaces
-    if (flags & FLAGS_LEFT) {
-      while (idx - start_idx < width) out(' ', buffer, idx++, maxlen);
-    }
-  }
-  return idx;
-}
-#endif  // PRINTF_SUPPORT_EXPONENTIAL
-#endif  // PRINTF_SUPPORT_FLOAT
-
-
-// internal vsnprintf
-static int _vsnprintf(out_fct_type out, char* buffer, const size_t maxlen, const char* format, va_list va)
-{
-  unsigned int flags, width, precision, n;
-  size_t idx = 0U;
-
-  if (!buffer) {
-    // use null output function
-    out = _out_null;
-  }
-
-  while (*format)
-  {
-    // format specifier?  %[flags][width][.precision][length]
-    if (*format != '%') {
-      // no
-      out(*format, buffer, idx++, maxlen);
-      format++;
-      continue;
-    }
-    else {
-      // yes, evaluate it
-      format++;
-    }
-
-    // evaluate flags
-    flags = 0U;
-    do {
-      switch (*format) {
-        case '0': flags |= FLAGS_ZEROPAD; format++; n = 1U; break;
-        case '-': flags |= FLAGS_LEFT;    format++; n = 1U; break;
-        case '+': flags |= FLAGS_PLUS;    format++; n = 1U; break;
-        case ' ': flags |= FLAGS_SPACE;   format++; n = 1U; break;
-        case '#': flags |= FLAGS_HASH;    format++; n = 1U; break;
-        default :                                   n = 0U; break;
-      }
-    } while (n);
-
-    // evaluate width field
-    width = 0U;
-    if (_is_digit(*format)) {
-      width = _atoi(&format);
-    }
-    else if (*format == '*') {
-      const int w = va_arg(va, int);
-      if (w < 0) {
-        flags |= FLAGS_LEFT;    // reverse padding
-        width = (unsigned int)-w;
-      }
-      else {
-        width = (unsigned int)w;
-      }
-      format++;
-    }
-
-    // evaluate precision field
-    precision = 0U;
-    if (*format == '.') {
-      flags |= FLAGS_PRECISION;
-      format++;
-      if (_is_digit(*format)) {
-        precision = _atoi(&format);
-      }
-      else if (*format == '*') {
-        const int prec = (int)va_arg(va, int);
-        precision = prec > 0 ? (unsigned int)prec : 0U;
-        format++;
-      }
-    }
-
-    // evaluate length field
-    switch (*format) {
-      case 'l' :
-        flags |= FLAGS_LONG;
-        format++;
-        if (*format == 'l') {
-          flags |= FLAGS_LONG_LONG;
-          format++;
-        }
-        break;
-      case 'h' :
-        flags |= FLAGS_SHORT;
-        format++;
-        if (*format == 'h') {
-          flags |= FLAGS_CHAR;
-          format++;
-        }
-        break;
-#if defined(PRINTF_SUPPORT_PTRDIFF_T)
-      case 't' :
-        flags |= (sizeof(ptrdiff_t) == sizeof(long) ? FLAGS_LONG : FLAGS_LONG_LONG);
-        format++;
-        break;
-#endif
-      case 'j' :
-        flags |= (sizeof(intmax_t) == sizeof(long) ? FLAGS_LONG : FLAGS_LONG_LONG);
-        format++;
-        break;
-      case 'z' :
-        flags |= (sizeof(size_t) == sizeof(long) ? FLAGS_LONG : FLAGS_LONG_LONG);
-        format++;
-        break;
-      default :
-        break;
-    }
-
-    // evaluate specifier
-    switch (*format) {
-      case 'd' :
-      case 'i' :
-      case 'u' :
-      case 'x' :
-      case 'X' :
-      case 'o' :
-      case 'b' : {
-        // set the base
-        unsigned int base;
-        if (*format == 'x' || *format == 'X') {
-          base = 16U;
-        }
-        else if (*format == 'o') {
-          base =  8U;
-        }
-        else if (*format == 'b') {
-          base =  2U;
-        }
-        else {
-          base = 10U;
-          flags &= ~FLAGS_HASH;   // no hash for dec format
-        }
-        // uppercase
-        if (*format == 'X') {
-          flags |= FLAGS_UPPERCASE;
-        }
-
-        // no plus or space flag for u, x, X, o, b
-        if ((*format != 'i') && (*format != 'd')) {
-          flags &= ~(FLAGS_PLUS | FLAGS_SPACE);
-        }
-
-        // ignore '0' flag when precision is given
-        if (flags & FLAGS_PRECISION) {
-          flags &= ~FLAGS_ZEROPAD;
-        }
-
-        // convert the integer
-        if ((*format == 'i') || (*format == 'd')) {
-          // signed
-          if (flags & FLAGS_LONG_LONG) {
-#if defined(PRINTF_SUPPORT_LONG_LONG)
-            const long long value = va_arg(va, long long);
-            idx = _ntoa_long_long(out, buffer, idx, maxlen, (unsigned long long)(value > 0 ? value : 0 - value), value < 0, base, precision, width, flags);
-#endif
-          }
-          else if (flags & FLAGS_LONG) {
-            const long value = va_arg(va, long);
-            idx = _ntoa_long(out, buffer, idx, maxlen, (unsigned long)(value > 0 ? value : 0 - value), value < 0, base, precision, width, flags);
-          }
-          else {
-            const int value = (flags & FLAGS_CHAR) ? (char)va_arg(va, int) : (flags & FLAGS_SHORT) ? (short int)va_arg(va, int) : va_arg(va, int);
-            idx = _ntoa_long(out, buffer, idx, maxlen, (unsigned int)(value > 0 ? value : 0 - value), value < 0, base, precision, width, flags);
-          }
-        }
-        else {
-          // unsigned
-          if (flags & FLAGS_LONG_LONG) {
-#if defined(PRINTF_SUPPORT_LONG_LONG)
-            idx = _ntoa_long_long(out, buffer, idx, maxlen, va_arg(va, unsigned long long), false, base, precision, width, flags);
-#endif
-          }
-          else if (flags & FLAGS_LONG) {
-            idx = _ntoa_long(out, buffer, idx, maxlen, va_arg(va, unsigned long), false, base, precision, width, flags);
-          }
-          else {
-            const unsigned int value = (flags & FLAGS_CHAR) ? (unsigned char)va_arg(va, unsigned int) : (flags & FLAGS_SHORT) ? (unsigned short int)va_arg(va, unsigned int) : va_arg(va, unsigned int);
-            idx = _ntoa_long(out, buffer, idx, maxlen, value, false, base, precision, width, flags);
-          }
-        }
-        format++;
-        break;
-      }
-#if defined(PRINTF_SUPPORT_FLOAT)
-      case 'f' :
-      case 'F' :
-        if (*format == 'F') flags |= FLAGS_UPPERCASE;
-        idx = _ftoa(out, buffer, idx, maxlen, va_arg(va, double), precision, width, flags);
-        format++;
-        break;
-#if defined(PRINTF_SUPPORT_EXPONENTIAL)
-      case 'e':
-      case 'E':
-      case 'g':
-      case 'G':
-        if ((*format == 'g')||(*format == 'G')) flags |= FLAGS_ADAPT_EXP;
-        if ((*format == 'E')||(*format == 'G')) flags |= FLAGS_UPPERCASE;
-        idx = _etoa(out, buffer, idx, maxlen, va_arg(va, double), precision, width, flags);
-        format++;
-        break;
-#endif  // PRINTF_SUPPORT_EXPONENTIAL
-#endif  // PRINTF_SUPPORT_FLOAT
-      case 'c' : {
-        unsigned int l = 1U;
-        // pre padding
-        if (!(flags & FLAGS_LEFT)) {
-          while (l++ < width) {
-            out(' ', buffer, idx++, maxlen);
-          }
-        }
-        // char output
-        out((char)va_arg(va, int), buffer, idx++, maxlen);
-        // post padding
-        if (flags & FLAGS_LEFT) {
-          while (l++ < width) {
-            out(' ', buffer, idx++, maxlen);
-          }
-        }
-        format++;
-        break;
-      }
-
-      case 's' : {
-        const char* p = va_arg(va, char*);
-        unsigned int l = _strnlen_s(p, precision ? precision : (size_t)-1);
-        // pre padding
-        if (flags & FLAGS_PRECISION) {
-          l = (l < precision ? l : precision);
-        }
-        if (!(flags & FLAGS_LEFT)) {
-          while (l++ < width) {
-            out(' ', buffer, idx++, maxlen);
-          }
-        }
-        // string output
-        while ((*p != 0) && (!(flags & FLAGS_PRECISION) || precision--)) {
-          out(*(p++), buffer, idx++, maxlen);
-        }
-        // post padding
-        if (flags & FLAGS_LEFT) {
-          while (l++ < width) {
-            out(' ', buffer, idx++, maxlen);
-          }
-        }
-        format++;
-        break;
-      }
-
-      case 'p' : {
-        width = sizeof(void*) * 2U;
-        flags |= FLAGS_ZEROPAD | FLAGS_UPPERCASE;
-#if defined(PRINTF_SUPPORT_LONG_LONG)
-        const bool is_ll = sizeof(uintptr_t) == sizeof(long long);
-        if (is_ll) {
-          idx = _ntoa_long_long(out, buffer, idx, maxlen, (uintptr_t)va_arg(va, void*), false, 16U, precision, width, flags);
-        }
-        else {
-#endif
-          idx = _ntoa_long(out, buffer, idx, maxlen, (unsigned long)((uintptr_t)va_arg(va, void*)), false, 16U, precision, width, flags);
-#if defined(PRINTF_SUPPORT_LONG_LONG)
-        }
-#endif
-        format++;
-        break;
-      }
-
-      case '%' :
-        out('%', buffer, idx++, maxlen);
-        format++;
-        break;
-
-      default :
-        out(*format, buffer, idx++, maxlen);
-        format++;
-        break;
-    }
-  }
-
-  // termination
-  out((char)0, buffer, idx < maxlen ? idx : maxlen - 1U, maxlen);
-
-  // return written chars without terminating \0
-  return (int)idx;
-}
-
-
-///////////////////////////////////////////////////////////////////////////////
-
-int printf_(const char* format, ...)
-{
-  va_list va;
-  va_start(va, format);
-  char buffer[1];
-  const int ret = _vsnprintf(_out_char, buffer, (size_t)-1, format, va);
-  va_end(va);
-  return ret;
-}
-
-
-int sprintf_(char* buffer, const char* format, ...)
-{
-  va_list va;
-  va_start(va, format);
-  const int ret = _vsnprintf(_out_buffer, buffer, (size_t)-1, format, va);
-  va_end(va);
-  return ret;
-}
-
-
-int snprintf_(char* buffer, size_t count, const char* format, ...)
-{
-  va_list va;
-  va_start(va, format);
-  const int ret = _vsnprintf(_out_buffer, buffer, count, format, va);
-  va_end(va);
-  return ret;
-}
-
-
-int vprintf_(const char* format, va_list va)
-{
-  char buffer[1];
-  return _vsnprintf(_out_char, buffer, (size_t)-1, format, va);
-}
-
-
-int vsnprintf_(char* buffer, size_t count, const char* format, va_list va)
-{
-  return _vsnprintf(_out_buffer, buffer, count, format, va);
-}
-
-
-int fctprintf(void (*out)(char character, void* arg), void* arg, const char* format, ...)
-{
-  va_list va;
-  va_start(va, format);
-  const out_fct_wrap_type out_fct_wrap = { out, arg };
-  const int ret = _vsnprintf(_out_fct, (char*)(uintptr_t)&out_fct_wrap, (size_t)-1, format, va);
-  va_end(va);
-  return ret;
-}
+///////////////////////////////////////////////////////////////////////////////
+// \author (c) Marco Paland (info@paland.com)
+//             2014-2019, PALANDesign Hannover, Germany
+//
+// \license The MIT License (MIT)
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+//
+// \brief Tiny printf, sprintf and (v)snprintf implementation, optimized for speed on
+//        embedded systems with a very limited resources. These routines are thread
+//        safe and reentrant!
+//        Use this instead of the bloated standard/newlib printf cause these use
+//        malloc for printf (and may not be thread safe).
+//
+///////////////////////////////////////////////////////////////////////////////
+
+#define PRINTF_DISABLE_SUPPORT_FLOAT
+#define PRINTF_DISABLE_SUPPORT_EXPONENTIAL
+
+#include <stdbool.h>
+#include <stdint.h>
+
+#include "uarch-printf.h"
+
+
+// define this globally (e.g. gcc -DPRINTF_INCLUDE_CONFIG_H ...) to include the
+// printf_config.h header file
+// default: undefined
+#ifdef PRINTF_INCLUDE_CONFIG_H
+#include "printf_config.h"
+#endif
+
+
+// 'ntoa' conversion buffer size, this must be big enough to hold one converted
+// numeric number including padded zeros (dynamically created on stack)
+// default: 32 byte
+#ifndef PRINTF_NTOA_BUFFER_SIZE
+#define PRINTF_NTOA_BUFFER_SIZE    32U
+#endif
+
+// 'ftoa' conversion buffer size, this must be big enough to hold one converted
+// float number including padded zeros (dynamically created on stack)
+// default: 32 byte
+#ifndef PRINTF_FTOA_BUFFER_SIZE
+#define PRINTF_FTOA_BUFFER_SIZE    32U
+#endif
+
+// support for the floating point type (%f)
+// default: activated
+#ifndef PRINTF_DISABLE_SUPPORT_FLOAT
+#define PRINTF_SUPPORT_FLOAT
+#endif
+
+// support for exponential floating point notation (%e/%g)
+// default: activated
+#ifndef PRINTF_DISABLE_SUPPORT_EXPONENTIAL
+#define PRINTF_SUPPORT_EXPONENTIAL
+#endif
+
+// define the default floating point precision
+// default: 6 digits
+#ifndef PRINTF_DEFAULT_FLOAT_PRECISION
+#define PRINTF_DEFAULT_FLOAT_PRECISION  6U
+#endif
+
+// define the largest float suitable to print with %f
+// default: 1e9
+#ifndef PRINTF_MAX_FLOAT
+#define PRINTF_MAX_FLOAT  1e9
+#endif
+
+// support for the long long types (%llu or %p)
+// default: activated
+#ifndef PRINTF_DISABLE_SUPPORT_LONG_LONG
+#define PRINTF_SUPPORT_LONG_LONG
+#endif
+
+// support for the ptrdiff_t type (%t)
+// ptrdiff_t is normally defined in <stddef.h> as long or long long type
+// default: activated
+#ifndef PRINTF_DISABLE_SUPPORT_PTRDIFF_T
+#define PRINTF_SUPPORT_PTRDIFF_T
+#endif
+
+///////////////////////////////////////////////////////////////////////////////
+
+// internal flag definitions
+#define FLAGS_ZEROPAD   (1U <<  0U)
+#define FLAGS_LEFT      (1U <<  1U)
+#define FLAGS_PLUS      (1U <<  2U)
+#define FLAGS_SPACE     (1U <<  3U)
+#define FLAGS_HASH      (1U <<  4U)
+#define FLAGS_UPPERCASE (1U <<  5U)
+#define FLAGS_CHAR      (1U <<  6U)
+#define FLAGS_SHORT     (1U <<  7U)
+#define FLAGS_LONG      (1U <<  8U)
+#define FLAGS_LONG_LONG (1U <<  9U)
+#define FLAGS_PRECISION (1U << 10U)
+#define FLAGS_ADAPT_EXP (1U << 11U)
+
+
+// import float.h for DBL_MAX
+#if defined(PRINTF_SUPPORT_FLOAT)
+#include <float.h>
+#endif
+
+
+// output function type
+typedef void (*out_fct_type)(char character, void* buffer, size_t idx, size_t maxlen);
+
+
+// wrapper (used as buffer) for output function type
+typedef struct {
+  void  (*fct)(char character, void* arg);
+  void* arg;
+} out_fct_wrap_type;
+
+
+// internal buffer output
+static inline void _out_buffer(char character, void* buffer, size_t idx, size_t maxlen)
+{
+  if (idx < maxlen) {
+    ((char*)buffer)[idx] = character;
+  }
+}
+
+
+// internal null output
+static inline void _out_null(char character, void* buffer, size_t idx, size_t maxlen)
+{
+  (void)character; (void)buffer; (void)idx; (void)maxlen;
+}
+
+
+// internal _putchar wrapper
+static inline void _out_char(char character, void* buffer, size_t idx, size_t maxlen)
+{
+  (void)buffer; (void)idx; (void)maxlen;
+  if (character) {
+    _putchar(character);
+  }
+}
+
+
+// internal output function wrapper
+static inline void _out_fct(char character, void* buffer, size_t idx, size_t maxlen)
+{
+  (void)idx; (void)maxlen;
+  if (character) {
+    // buffer is the output fct pointer
+    ((out_fct_wrap_type*)buffer)->fct(character, ((out_fct_wrap_type*)buffer)->arg);
+  }
+}
+
+
+// internal secure strlen
+// \return The length of the string (excluding the terminating 0) limited by 'maxsize'
+static inline unsigned int _strnlen_s(const char* str, size_t maxsize)
+{
+  const char* s;
+  for (s = str; *s && maxsize--; ++s);
+  return (unsigned int)(s - str);
+}
+
+
+// internal test if char is a digit (0-9)
+// \return true if char is a digit
+static inline bool _is_digit(char ch)
+{
+  return (ch >= '0') && (ch <= '9');
+}
+
+
+// internal ASCII string to unsigned int conversion
+static unsigned int _atoi(const char** str)
+{
+  unsigned int i = 0U;
+  while (_is_digit(**str)) {
+    i = i * 10U + (unsigned int)(*((*str)++) - '0');
+  }
+  return i;
+}
+
+
+// output the specified string in reverse, taking care of any zero-padding
+static size_t _out_rev(out_fct_type out, char* buffer, size_t idx, size_t maxlen, const char* buf, size_t len, unsigned int width, unsigned int flags)
+{
+  const size_t start_idx = idx;
+
+  // pad spaces up to given width
+  if (!(flags & FLAGS_LEFT) && !(flags & FLAGS_ZEROPAD)) {
+    for (size_t i = len; i < width; i++) {
+      out(' ', buffer, idx++, maxlen);
+    }
+  }
+
+  // reverse string
+  while (len) {
+    out(buf[--len], buffer, idx++, maxlen);
+  }
+
+  // append pad spaces up to given width
+  if (flags & FLAGS_LEFT) {
+    while (idx - start_idx < width) {
+      out(' ', buffer, idx++, maxlen);
+    }
+  }
+
+  return idx;
+}
+
+
+// internal itoa format
+static size_t _ntoa_format(out_fct_type out, char* buffer, size_t idx, size_t maxlen, char* buf, size_t len, bool negative, unsigned int base, unsigned int prec, unsigned int width, unsigned int flags)
+{
+  // pad leading zeros
+  if (!(flags & FLAGS_LEFT)) {
+    if (width && (flags & FLAGS_ZEROPAD) && (negative || (flags & (FLAGS_PLUS | FLAGS_SPACE)))) {
+      width--;
+    }
+    while ((len < prec) && (len < PRINTF_NTOA_BUFFER_SIZE)) {
+      buf[len++] = '0';
+    }
+    while ((flags & FLAGS_ZEROPAD) && (len < width) && (len < PRINTF_NTOA_BUFFER_SIZE)) {
+      buf[len++] = '0';
+    }
+  }
+
+  // handle hash
+  if (flags & FLAGS_HASH) {
+    if (!(flags & FLAGS_PRECISION) && len && ((len == prec) || (len == width))) {
+      len--;
+      if (len && (base == 16U)) {
+        len--;
+      }
+    }
+    if ((base == 16U) && !(flags & FLAGS_UPPERCASE) && (len < PRINTF_NTOA_BUFFER_SIZE)) {
+      buf[len++] = 'x';
+    }
+    else if ((base == 16U) && (flags & FLAGS_UPPERCASE) && (len < PRINTF_NTOA_BUFFER_SIZE)) {
+      buf[len++] = 'X';
+    }
+    else if ((base == 2U) && (len < PRINTF_NTOA_BUFFER_SIZE)) {
+      buf[len++] = 'b';
+    }
+    if (len < PRINTF_NTOA_BUFFER_SIZE) {
+      buf[len++] = '0';
+    }
+  }
+
+  if (len < PRINTF_NTOA_BUFFER_SIZE) {
+    if (negative) {
+      buf[len++] = '-';
+    }
+    else if (flags & FLAGS_PLUS) {
+      buf[len++] = '+';  // ignore the space if the '+' exists
+    }
+    else if (flags & FLAGS_SPACE) {
+      buf[len++] = ' ';
+    }
+  }
+
+  return _out_rev(out, buffer, idx, maxlen, buf, len, width, flags);
+}
+
+
+// internal itoa for 'long' type
+static size_t _ntoa_long(out_fct_type out, char* buffer, size_t idx, size_t maxlen, unsigned long value, bool negative, unsigned long base, unsigned int prec, unsigned int width, unsigned int flags)
+{
+  char buf[PRINTF_NTOA_BUFFER_SIZE];
+  size_t len = 0U;
+
+  // no hash for 0 values
+  if (!value) {
+    flags &= ~FLAGS_HASH;
+  }
+
+  // write if precision != 0 and value is != 0
+  if (!(flags & FLAGS_PRECISION) || value) {
+    do {
+      const char digit = (char)(value % base);
+      buf[len++] = digit < 10 ? '0' + digit : (flags & FLAGS_UPPERCASE ? 'A' : 'a') + digit - 10;
+      value /= base;
+    } while (value && (len < PRINTF_NTOA_BUFFER_SIZE));
+  }
+
+  return _ntoa_format(out, buffer, idx, maxlen, buf, len, negative, (unsigned int)base, prec, width, flags);
+}
+
+
+// internal itoa for 'long long' type
+#if defined(PRINTF_SUPPORT_LONG_LONG)
+static size_t _ntoa_long_long(out_fct_type out, char* buffer, size_t idx, size_t maxlen, unsigned long long value, bool negative, unsigned long long base, unsigned int prec, unsigned int width, unsigned int flags)
+{
+  char buf[PRINTF_NTOA_BUFFER_SIZE];
+  size_t len = 0U;
+
+  // no hash for 0 values
+  if (!value) {
+    flags &= ~FLAGS_HASH;
+  }
+
+  // write if precision != 0 and value is != 0
+  if (!(flags & FLAGS_PRECISION) || value) {
+    do {
+      const char digit = (char)(value % base);
+      buf[len++] = digit < 10 ? '0' + digit : (flags & FLAGS_UPPERCASE ? 'A' : 'a') + digit - 10;
+      value /= base;
+    } while (value && (len < PRINTF_NTOA_BUFFER_SIZE));
+  }
+
+  return _ntoa_format(out, buffer, idx, maxlen, buf, len, negative, (unsigned int)base, prec, width, flags);
+}
+#endif  // PRINTF_SUPPORT_LONG_LONG
+
+
+#if defined(PRINTF_SUPPORT_FLOAT)
+
+#if defined(PRINTF_SUPPORT_EXPONENTIAL)
+// forward declaration so that _ftoa can switch to exp notation for values > PRINTF_MAX_FLOAT
+static size_t _etoa(out_fct_type out, char* buffer, size_t idx, size_t maxlen, double value, unsigned int prec, unsigned int width, unsigned int flags);
+#endif
+
+
+// internal ftoa for fixed decimal floating point
+static size_t _ftoa(out_fct_type out, char* buffer, size_t idx, size_t maxlen, double value, unsigned int prec, unsigned int width, unsigned int flags)
+{
+  char buf[PRINTF_FTOA_BUFFER_SIZE];
+  size_t len  = 0U;
+  double diff = 0.0;
+
+  // powers of 10
+  static const double pow10[] = { 1, 10, 100, 1000, 10000, 100000, 1000000, 10000000, 100000000, 1000000000 };
+
+  // test for special values
+  if (value != value)
+    return _out_rev(out, buffer, idx, maxlen, "nan", 3, width, flags);
+  if (value < -DBL_MAX)
+    return _out_rev(out, buffer, idx, maxlen, "fni-", 4, width, flags);
+  if (value > DBL_MAX)
+    return _out_rev(out, buffer, idx, maxlen, (flags & FLAGS_PLUS) ? "fni+" : "fni", (flags & FLAGS_PLUS) ? 4U : 3U, width, flags);
+
+  // test for very large values
+  // standard printf behavior is to print EVERY whole number digit -- which could be 100s of characters overflowing your buffers == bad
+  if ((value > PRINTF_MAX_FLOAT) || (value < -PRINTF_MAX_FLOAT)) {
+#if defined(PRINTF_SUPPORT_EXPONENTIAL)
+    return _etoa(out, buffer, idx, maxlen, value, prec, width, flags);
+#else
+    return 0U;
+#endif
+  }
+
+  // test for negative
+  bool negative = false;
+  if (value < 0) {
+    negative = true;
+    value = 0 - value;
+  }
+
+  // set default precision, if not set explicitly
+  if (!(flags & FLAGS_PRECISION)) {
+    prec = PRINTF_DEFAULT_FLOAT_PRECISION;
+  }
+  // limit precision to 9, cause a prec >= 10 can lead to overflow errors
+  while ((len < PRINTF_FTOA_BUFFER_SIZE) && (prec > 9U)) {
+    buf[len++] = '0';
+    prec--;
+  }
+
+  int whole = (int)value;
+  double tmp = (value - whole) * pow10[prec];
+  unsigned long frac = (unsigned long)tmp;
+  diff = tmp - frac;
+
+  if (diff > 0.5) {
+    ++frac;
+    // handle rollover, e.g. case 0.99 with prec 1 is 1.0
+    if (frac >= pow10[prec]) {
+      frac = 0;
+      ++whole;
+    }
+  }
+  else if (diff < 0.5) {
+  }
+  else if ((frac == 0U) || (frac & 1U)) {
+    // if halfway, round up if odd OR if last digit is 0
+    ++frac;
+  }
+
+  if (prec == 0U) {
+    diff = value - (double)whole;
+    if ((!(diff < 0.5) || (diff > 0.5)) && (whole & 1)) {
+      // exactly 0.5 and ODD, then round up
+      // 1.5 -> 2, but 2.5 -> 2
+      ++whole;
+    }
+  }
+  else {
+    unsigned int count = prec;
+    // now do fractional part, as an unsigned number
+    while (len < PRINTF_FTOA_BUFFER_SIZE) {
+      --count;
+      buf[len++] = (char)(48U + (frac % 10U));
+      if (!(frac /= 10U)) {
+        break;
+      }
+    }
+    // add extra 0s
+    while ((len < PRINTF_FTOA_BUFFER_SIZE) && (count-- > 0U)) {
+      buf[len++] = '0';
+    }
+    if (len < PRINTF_FTOA_BUFFER_SIZE) {
+      // add decimal
+      buf[len++] = '.';
+    }
+  }
+
+  // do whole part, number is reversed
+  while (len < PRINTF_FTOA_BUFFER_SIZE) {
+    buf[len++] = (char)(48 + (whole % 10));
+    if (!(whole /= 10)) {
+      break;
+    }
+  }
+
+  // pad leading zeros
+  if (!(flags & FLAGS_LEFT) && (flags & FLAGS_ZEROPAD)) {
+    if (width && (negative || (flags & (FLAGS_PLUS | FLAGS_SPACE)))) {
+      width--;
+    }
+    while ((len < width) && (len < PRINTF_FTOA_BUFFER_SIZE)) {
+      buf[len++] = '0';
+    }
+  }
+
+  if (len < PRINTF_FTOA_BUFFER_SIZE) {
+    if (negative) {
+      buf[len++] = '-';
+    }
+    else if (flags & FLAGS_PLUS) {
+      buf[len++] = '+';  // ignore the space if the '+' exists
+    }
+    else if (flags & FLAGS_SPACE) {
+      buf[len++] = ' ';
+    }
+  }
+
+  return _out_rev(out, buffer, idx, maxlen, buf, len, width, flags);
+}
+
+
+#if defined(PRINTF_SUPPORT_EXPONENTIAL)
+// internal ftoa variant for exponential floating-point type, contributed by Martijn Jasperse <m.jasperse@gmail.com>
+static size_t _etoa(out_fct_type out, char* buffer, size_t idx, size_t maxlen, double value, unsigned int prec, unsigned int width, unsigned int flags)
+{
+  // check for NaN and special values
+  if ((value != value) || (value > DBL_MAX) || (value < -DBL_MAX)) {
+    return _ftoa(out, buffer, idx, maxlen, value, prec, width, flags);
+  }
+
+  // determine the sign
+  const bool negative = value < 0;
+  if (negative) {
+    value = -value;
+  }
+
+  // default precision
+  if (!(flags & FLAGS_PRECISION)) {
+    prec = PRINTF_DEFAULT_FLOAT_PRECISION;
+  }
+
+  // determine the decimal exponent
+  // based on the algorithm by David Gay (https://www.ampl.com/netlib/fp/dtoa.c)
+  union {
+    uint64_t U;
+    double   F;
+  } conv;
+
+  conv.F = value;
+  int exp2 = (int)((conv.U >> 52U) & 0x07FFU) - 1023;           // effectively log2
+  conv.U = (conv.U & ((1ULL << 52U) - 1U)) | (1023ULL << 52U);  // drop the exponent so conv.F is now in [1,2)
+  // now approximate log10 from the log2 integer part and an expansion of ln around 1.5
+  int expval = (int)(0.1760912590558 + exp2 * 0.301029995663981 + (conv.F - 1.5) * 0.289529654602168);
+  // now we want to compute 10^expval but we want to be sure it won't overflow
+  exp2 = (int)(expval * 3.321928094887362 + 0.5);
+  const double z  = expval * 2.302585092994046 - exp2 * 0.6931471805599453;
+  const double z2 = z * z;
+  conv.U = (uint64_t)(exp2 + 1023) << 52U;
+  // compute exp(z) using continued fractions, see https://en.wikipedia.org/wiki/Exponential_function#Continued_fractions_for_ex
+  conv.F *= 1 + 2 * z / (2 - z + (z2 / (6 + (z2 / (10 + z2 / 14)))));
+  // correct for rounding errors
+  if (value < conv.F) {
+    expval--;
+    conv.F /= 10;
+  }
+
+  // the exponent format is "%+03d" and largest value is "307", so set aside 4-5 characters
+  unsigned int minwidth = ((expval < 100) && (expval > -100)) ? 4U : 5U;
+
+  // in "%g" mode, "prec" is the number of *significant figures* not decimals
+  if (flags & FLAGS_ADAPT_EXP) {
+    // do we want to fall-back to "%f" mode?
+    if ((value >= 1e-4) && (value < 1e6)) {
+      if ((int)prec > expval) {
+        prec = (unsigned)((int)prec - expval - 1);
+      }
+      else {
+        prec = 0;
+      }
+      flags |= FLAGS_PRECISION;   // make sure _ftoa respects precision
+      // no characters in exponent
+      minwidth = 0U;
+      expval   = 0;
+    }
+    else {
+      // we use one sigfig for the whole part
+      if ((prec > 0) && (flags & FLAGS_PRECISION)) {
+        --prec;
+      }
+    }
+  }
+
+  // will everything fit?
+  unsigned int fwidth = width;
+  if (width > minwidth) {
+    // we didn't fall-back so subtract the characters required for the exponent
+    fwidth -= minwidth;
+  } else {
+    // not enough characters, so go back to default sizing
+    fwidth = 0U;
+  }
+  if ((flags & FLAGS_LEFT) && minwidth) {
+    // if we're padding on the right, DON'T pad the floating part
+    fwidth = 0U;
+  }
+
+  // rescale the float value
+  if (expval) {
+    value /= conv.F;
+  }
+
+  // output the floating part
+  const size_t start_idx = idx;
+  idx = _ftoa(out, buffer, idx, maxlen, negative ? -value : value, prec, fwidth, flags & ~FLAGS_ADAPT_EXP);
+
+  // output the exponent part
+  if (minwidth) {
+    // output the exponential symbol
+    out((flags & FLAGS_UPPERCASE) ? 'E' : 'e', buffer, idx++, maxlen);
+    // output the exponent value
+    idx = _ntoa_long(out, buffer, idx, maxlen, (expval < 0) ? -expval : expval, expval < 0, 10, 0, minwidth-1, FLAGS_ZEROPAD | FLAGS_PLUS);
+    // might need to right-pad spaces
+    if (flags & FLAGS_LEFT) {
+      while (idx - start_idx < width) out(' ', buffer, idx++, maxlen);
+    }
+  }
+  return idx;
+}
+#endif  // PRINTF_SUPPORT_EXPONENTIAL
+#endif  // PRINTF_SUPPORT_FLOAT
+
+
+// internal vsnprintf
+static int _vsnprintf(out_fct_type out, char* buffer, const size_t maxlen, const char* format, va_list va)
+{
+  unsigned int flags, width, precision, n;
+  size_t idx = 0U;
+
+  if (!buffer) {
+    // use null output function
+    out = _out_null;
+  }
+
+  while (*format)
+  {
+    // format specifier?  %[flags][width][.precision][length]
+    if (*format != '%') {
+      // no
+      out(*format, buffer, idx++, maxlen);
+      format++;
+      continue;
+    }
+    else {
+      // yes, evaluate it
+      format++;
+    }
+
+    // evaluate flags
+    flags = 0U;
+    do {
+      switch (*format) {
+        case '0': flags |= FLAGS_ZEROPAD; format++; n = 1U; break;
+        case '-': flags |= FLAGS_LEFT;    format++; n = 1U; break;
+        case '+': flags |= FLAGS_PLUS;    format++; n = 1U; break;
+        case ' ': flags |= FLAGS_SPACE;   format++; n = 1U; break;
+        case '#': flags |= FLAGS_HASH;    format++; n = 1U; break;
+        default :                                   n = 0U; break;
+      }
+    } while (n);
+
+    // evaluate width field
+    width = 0U;
+    if (_is_digit(*format)) {
+      width = _atoi(&format);
+    }
+    else if (*format == '*') {
+      const int w = va_arg(va, int);
+      if (w < 0) {
+        flags |= FLAGS_LEFT;    // reverse padding
+        width = (unsigned int)-w;
+      }
+      else {
+        width = (unsigned int)w;
+      }
+      format++;
+    }
+
+    // evaluate precision field
+    precision = 0U;
+    if (*format == '.') {
+      flags |= FLAGS_PRECISION;
+      format++;
+      if (_is_digit(*format)) {
+        precision = _atoi(&format);
+      }
+      else if (*format == '*') {
+        const int prec = (int)va_arg(va, int);
+        precision = prec > 0 ? (unsigned int)prec : 0U;
+        format++;
+      }
+    }
+
+    // evaluate length field
+    switch (*format) {
+      case 'l' :
+        flags |= FLAGS_LONG;
+        format++;
+        if (*format == 'l') {
+          flags |= FLAGS_LONG_LONG;
+          format++;
+        }
+        break;
+      case 'h' :
+        flags |= FLAGS_SHORT;
+        format++;
+        if (*format == 'h') {
+          flags |= FLAGS_CHAR;
+          format++;
+        }
+        break;
+#if defined(PRINTF_SUPPORT_PTRDIFF_T)
+      case 't' :
+        flags |= (sizeof(ptrdiff_t) == sizeof(long) ? FLAGS_LONG : FLAGS_LONG_LONG);
+        format++;
+        break;
+#endif
+      case 'j' :
+        flags |= (sizeof(intmax_t) == sizeof(long) ? FLAGS_LONG : FLAGS_LONG_LONG);
+        format++;
+        break;
+      case 'z' :
+        flags |= (sizeof(size_t) == sizeof(long) ? FLAGS_LONG : FLAGS_LONG_LONG);
+        format++;
+        break;
+      default :
+        break;
+    }
+
+    // evaluate specifier
+    switch (*format) {
+      case 'd' :
+      case 'i' :
+      case 'u' :
+      case 'x' :
+      case 'X' :
+      case 'o' :
+      case 'b' : {
+        // set the base
+        unsigned int base;
+        if (*format == 'x' || *format == 'X') {
+          base = 16U;
+        }
+        else if (*format == 'o') {
+          base =  8U;
+        }
+        else if (*format == 'b') {
+          base =  2U;
+        }
+        else {
+          base = 10U;
+          flags &= ~FLAGS_HASH;   // no hash for dec format
+        }
+        // uppercase
+        if (*format == 'X') {
+          flags |= FLAGS_UPPERCASE;
+        }
+
+        // no plus or space flag for u, x, X, o, b
+        if ((*format != 'i') && (*format != 'd')) {
+          flags &= ~(FLAGS_PLUS | FLAGS_SPACE);
+        }
+
+        // ignore '0' flag when precision is given
+        if (flags & FLAGS_PRECISION) {
+          flags &= ~FLAGS_ZEROPAD;
+        }
+
+        // convert the integer
+        if ((*format == 'i') || (*format == 'd')) {
+          // signed
+          if (flags & FLAGS_LONG_LONG) {
+#if defined(PRINTF_SUPPORT_LONG_LONG)
+            const long long value = va_arg(va, long long);
+            idx = _ntoa_long_long(out, buffer, idx, maxlen, (unsigned long long)(value > 0 ? value : 0 - value), value < 0, base, precision, width, flags);
+#endif
+          }
+          else if (flags & FLAGS_LONG) {
+            const long value = va_arg(va, long);
+            idx = _ntoa_long(out, buffer, idx, maxlen, (unsigned long)(value > 0 ? value : 0 - value), value < 0, base, precision, width, flags);
+          }
+          else {
+            const int value = (flags & FLAGS_CHAR) ? (char)va_arg(va, int) : (flags & FLAGS_SHORT) ? (short int)va_arg(va, int) : va_arg(va, int);
+            idx = _ntoa_long(out, buffer, idx, maxlen, (unsigned int)(value > 0 ? value : 0 - value), value < 0, base, precision, width, flags);
+          }
+        }
+        else {
+          // unsigned
+          if (flags & FLAGS_LONG_LONG) {
+#if defined(PRINTF_SUPPORT_LONG_LONG)
+            idx = _ntoa_long_long(out, buffer, idx, maxlen, va_arg(va, unsigned long long), false, base, precision, width, flags);
+#endif
+          }
+          else if (flags & FLAGS_LONG) {
+            idx = _ntoa_long(out, buffer, idx, maxlen, va_arg(va, unsigned long), false, base, precision, width, flags);
+          }
+          else {
+            const unsigned int value = (flags & FLAGS_CHAR) ? (unsigned char)va_arg(va, unsigned int) : (flags & FLAGS_SHORT) ? (unsigned short int)va_arg(va, unsigned int) : va_arg(va, unsigned int);
+            idx = _ntoa_long(out, buffer, idx, maxlen, value, false, base, precision, width, flags);
+          }
+        }
+        format++;
+        break;
+      }
+#if defined(PRINTF_SUPPORT_FLOAT)
+      case 'f' :
+      case 'F' :
+        if (*format == 'F') flags |= FLAGS_UPPERCASE;
+        idx = _ftoa(out, buffer, idx, maxlen, va_arg(va, double), precision, width, flags);
+        format++;
+        break;
+#if defined(PRINTF_SUPPORT_EXPONENTIAL)
+      case 'e':
+      case 'E':
+      case 'g':
+      case 'G':
+        if ((*format == 'g')||(*format == 'G')) flags |= FLAGS_ADAPT_EXP;
+        if ((*format == 'E')||(*format == 'G')) flags |= FLAGS_UPPERCASE;
+        idx = _etoa(out, buffer, idx, maxlen, va_arg(va, double), precision, width, flags);
+        format++;
+        break;
+#endif  // PRINTF_SUPPORT_EXPONENTIAL
+#endif  // PRINTF_SUPPORT_FLOAT
+      case 'c' : {
+        unsigned int l = 1U;
+        // pre padding
+        if (!(flags & FLAGS_LEFT)) {
+          while (l++ < width) {
+            out(' ', buffer, idx++, maxlen);
+          }
+        }
+        // char output
+        out((char)va_arg(va, int), buffer, idx++, maxlen);
+        // post padding
+        if (flags & FLAGS_LEFT) {
+          while (l++ < width) {
+            out(' ', buffer, idx++, maxlen);
+          }
+        }
+        format++;
+        break;
+      }
+
+      case 's' : {
+        const char* p = va_arg(va, char*);
+        unsigned int l = _strnlen_s(p, precision ? precision : (size_t)-1);
+        // pre padding
+        if (flags & FLAGS_PRECISION) {
+          l = (l < precision ? l : precision);
+        }
+        if (!(flags & FLAGS_LEFT)) {
+          while (l++ < width) {
+            out(' ', buffer, idx++, maxlen);
+          }
+        }
+        // string output
+        while ((*p != 0) && (!(flags & FLAGS_PRECISION) || precision--)) {
+          out(*(p++), buffer, idx++, maxlen);
+        }
+        // post padding
+        if (flags & FLAGS_LEFT) {
+          while (l++ < width) {
+            out(' ', buffer, idx++, maxlen);
+          }
+        }
+        format++;
+        break;
+      }
+
+      case 'p' : {
+        width = sizeof(void*) * 2U;
+        flags |= FLAGS_ZEROPAD | FLAGS_UPPERCASE;
+#if defined(PRINTF_SUPPORT_LONG_LONG)
+        const bool is_ll = sizeof(uintptr_t) == sizeof(long long);
+        if (is_ll) {
+          idx = _ntoa_long_long(out, buffer, idx, maxlen, (uintptr_t)va_arg(va, void*), false, 16U, precision, width, flags);
+        }
+        else {
+#endif
+          idx = _ntoa_long(out, buffer, idx, maxlen, (unsigned long)((uintptr_t)va_arg(va, void*)), false, 16U, precision, width, flags);
+#if defined(PRINTF_SUPPORT_LONG_LONG)
+        }
+#endif
+        format++;
+        break;
+      }
+
+      case '%' :
+        out('%', buffer, idx++, maxlen);
+        format++;
+        break;
+
+      default :
+        out(*format, buffer, idx++, maxlen);
+        format++;
+        break;
+    }
+  }
+
+  // termination
+  out((char)0, buffer, idx < maxlen ? idx : maxlen - 1U, maxlen);
+
+  // return written chars without terminating \0
+  return (int)idx;
+}
+
+
+///////////////////////////////////////////////////////////////////////////////
+
+int printf_(const char* format, ...)
+{
+  va_list va;
+  va_start(va, format);
+  char buffer[1];
+  const int ret = _vsnprintf(_out_char, buffer, (size_t)-1, format, va);
+  va_end(va);
+  return ret;
+}
+
+
+int sprintf_(char* buffer, const char* format, ...)
+{
+  va_list va;
+  va_start(va, format);
+  const int ret = _vsnprintf(_out_buffer, buffer, (size_t)-1, format, va);
+  va_end(va);
+  return ret;
+}
+
+
+int snprintf_(char* buffer, size_t count, const char* format, ...)
+{
+  va_list va;
+  va_start(va, format);
+  const int ret = _vsnprintf(_out_buffer, buffer, count, format, va);
+  va_end(va);
+  return ret;
+}
+
+
+int vprintf_(const char* format, va_list va)
+{
+  char buffer[1];
+  return _vsnprintf(_out_char, buffer, (size_t)-1, format, va);
+}
+
+
+int vsnprintf_(char* buffer, size_t count, const char* format, va_list va)
+{
+  return _vsnprintf(_out_buffer, buffer, count, format, va);
+}
+
+
+int fctprintf(void (*out)(char character, void* arg), void* arg, const char* format, ...)
+{
+  va_list va;
+  va_start(va, format);
+  const out_fct_wrap_type out_fct_wrap = { out, arg };
+  const int ret = _vsnprintf(_out_fct, (char*)(uintptr_t)&out_fct_wrap, (size_t)-1, format, va);
+  va_end(va);
+  return ret;
+}
diff --git a/uarch/uarch-printf.h b/uarch/uarch-printf.h
index 6104ccfb7..43341e9ef 100644
--- a/uarch/uarch-printf.h
+++ b/uarch/uarch-printf.h
@@ -1,117 +1,108 @@
-///////////////////////////////////////////////////////////////////////////////
-// \author (c) Marco Paland (info@paland.com)
-//             2014-2019, PALANDesign Hannover, Germany
-//
-// \license The MIT License (MIT)
-//
-// Permission is hereby granted, free of charge, to any person obtaining a copy
-// of this software and associated documentation files (the "Software"), to deal
-// in the Software without restriction, including without limitation the rights
-// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-// copies of the Software, and to permit persons to whom the Software is
-// furnished to do so, subject to the following conditions:
-// 
-// The above copyright notice and this permission notice shall be included in
-// all copies or substantial portions of the Software.
-// 
-// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-// THE SOFTWARE.
-//
-// \brief Tiny printf, sprintf and snprintf implementation, optimized for speed on
-//        embedded systems with a very limited resources.
-//        Use this instead of bloated standard/newlib printf.
-//        These routines are thread safe and reentrant.
-//
-///////////////////////////////////////////////////////////////////////////////
-
-#ifndef _PRINTF_H_
-#define _PRINTF_H_
-
-#include <stdarg.h>
-#include <stddef.h>
-
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-
-/**
- * Output a character to a custom device like UART, used by the printf() function
- * This function is declared here only. You have to write your custom implementation somewhere
- * \param character Character to output
- */
-void _putchar(char character);
-
-
-/**
- * Tiny printf implementation
- * You have to implement _putchar if you use printf()
- * To avoid conflicts with the regular printf() API it is overridden by macro defines
- * and internal underscore-appended functions like printf_() are used
- * \param format A string that specifies the format of the output
- * \return The number of characters that are written into the array, not counting the terminating null character
- */
-#define printf printf_
-int printf_(const char* format, ...);
-
-
-/**
- * Tiny sprintf implementation
- * Due to security reasons (buffer overflow) YOU SHOULD CONSIDER USING (V)SNPRINTF INSTEAD!
- * \param buffer A pointer to the buffer where to store the formatted string. MUST be big enough to store the output!
- * \param format A string that specifies the format of the output
- * \return The number of characters that are WRITTEN into the buffer, not counting the terminating null character
- */
-#define sprintf sprintf_
-int sprintf_(char* buffer, const char* format, ...);
-
-
-/**
- * Tiny snprintf/vsnprintf implementation
- * \param buffer A pointer to the buffer where to store the formatted string
- * \param count The maximum number of characters to store in the buffer, including a terminating null character
- * \param format A string that specifies the format of the output
- * \param va A value identifying a variable arguments list
- * \return The number of characters that COULD have been written into the buffer, not counting the terminating
- *         null character. A value equal or larger than count indicates truncation. Only when the returned value
- *         is non-negative and less than count, the string has been completely written.
- */
-#define snprintf  snprintf_
-#define vsnprintf vsnprintf_
-int  snprintf_(char* buffer, size_t count, const char* format, ...);
-int vsnprintf_(char* buffer, size_t count, const char* format, va_list va);
-
-
-/**
- * Tiny vprintf implementation
- * \param format A string that specifies the format of the output
- * \param va A value identifying a variable arguments list
- * \return The number of characters that are WRITTEN into the buffer, not counting the terminating null character
- */
-#define vprintf vprintf_
-int vprintf_(const char* format, va_list va);
-
-
-/**
- * printf with output function
- * You may use this as dynamic alternative to printf() with its fixed _putchar() output
- * \param out An output function which takes one character and an argument pointer
- * \param arg An argument pointer for user data passed to output function
- * \param format A string that specifies the format of the output
- * \return The number of characters that are sent to the output function, not counting the terminating null character
- */
-int fctprintf(void (*out)(char character, void* arg), void* arg, const char* format, ...);
-
-
-#ifdef __cplusplus
-}
-#endif
-
-
-#endif  // _PRINTF_H_
+///////////////////////////////////////////////////////////////////////////////
+// \author (c) Marco Paland (info@paland.com)
+//             2014-2019, PALANDesign Hannover, Germany
+//
+// \license The MIT License (MIT)
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+//
+// \brief Tiny printf, sprintf and snprintf implementation, optimized for speed on
+//        embedded systems with a very limited resources.
+//        Use this instead of bloated standard/newlib printf.
+//        These routines are thread safe and reentrant.
+//
+///////////////////////////////////////////////////////////////////////////////
+
+#ifndef _PRINTF_H_
+#define _PRINTF_H_
+
+#include <stdarg.h>
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Output a character to a custom device like UART, used by the printf() function
+ * This function is declared here only. You have to write your custom implementation somewhere
+ * \param character Character to output
+ */
+void _putchar(char character);
+
+/**
+ * Tiny printf implementation
+ * You have to implement _putchar if you use printf()
+ * To avoid conflicts with the regular printf() API it is overridden by macro defines
+ * and internal underscore-appended functions like printf_() are used
+ * \param format A string that specifies the format of the output
+ * \return The number of characters that are written into the array, not counting the terminating null character
+ */
+#define printf printf_
+int printf_(const char *format, ...);
+
+/**
+ * Tiny sprintf implementation
+ * Due to security reasons (buffer overflow) YOU SHOULD CONSIDER USING (V)SNPRINTF INSTEAD!
+ * \param buffer A pointer to the buffer where to store the formatted string. MUST be big enough to store the output!
+ * \param format A string that specifies the format of the output
+ * \return The number of characters that are WRITTEN into the buffer, not counting the terminating null character
+ */
+#define sprintf sprintf_
+int sprintf_(char *buffer, const char *format, ...);
+
+/**
+ * Tiny snprintf/vsnprintf implementation
+ * \param buffer A pointer to the buffer where to store the formatted string
+ * \param count The maximum number of characters to store in the buffer, including a terminating null character
+ * \param format A string that specifies the format of the output
+ * \param va A value identifying a variable arguments list
+ * \return The number of characters that COULD have been written into the buffer, not counting the terminating
+ *         null character. A value equal or larger than count indicates truncation. Only when the returned value
+ *         is non-negative and less than count, the string has been completely written.
+ */
+#define snprintf snprintf_
+#define vsnprintf vsnprintf_
+int snprintf_(char *buffer, size_t count, const char *format, ...);
+int vsnprintf_(char *buffer, size_t count, const char *format, va_list va);
+
+/**
+ * Tiny vprintf implementation
+ * \param format A string that specifies the format of the output
+ * \param va A value identifying a variable arguments list
+ * \return The number of characters that are WRITTEN into the buffer, not counting the terminating null character
+ */
+#define vprintf vprintf_
+int vprintf_(const char *format, va_list va);
+
+/**
+ * printf with output function
+ * You may use this as dynamic alternative to printf() with its fixed _putchar() output
+ * \param out An output function which takes one character and an argument pointer
+ * \param arg An argument pointer for user data passed to output function
+ * \param format A string that specifies the format of the output
+ * \return The number of characters that are sent to the output function, not counting the terminating null character
+ */
+int fctprintf(void (*out)(char character, void *arg), void *arg, const char *format, ...);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // _PRINTF_H_
diff --git a/uarch/uarch-runtime.cpp b/uarch/uarch-runtime.cpp
index bc52e5d62..bb8758875 100644
--- a/uarch/uarch-runtime.cpp
+++ b/uarch/uarch-runtime.cpp
@@ -103,23 +103,3 @@ extern "C" NO_RETURN void abort() {
     // execution will never reach this point
     __builtin_trap();
 }
-
-namespace cartesi {
-
-void os_open_tty() {}
-
-void os_close_tty() {}
-
-bool os_poll_tty(uint64_t /*timeout_us*/) {
-    return false;
-}
-
-int os_getchar() {
-    return -1;
-}
-
-void os_putchar(uint8_t ch) {
-    _putchar(ch);
-}
-
-} // namespace cartesi
diff --git a/uarch/uarch-runtime.h b/uarch/uarch-runtime.h
index cbf0f2464..96e804e13 100644
--- a/uarch/uarch-runtime.h
+++ b/uarch/uarch-runtime.h
@@ -17,8 +17,8 @@
 #ifndef UARCH_RUNTIME_H
 #define UARCH_RUNTIME_H
 
-#include "uarch-printf.h"
 #include "compiler-defines.h"
+#include "uarch-printf.h"
 
 #include <inttypes.h>
 #include <stddef.h>

From cf6a83ca02daddf71655134095ac26ef5dca4318 Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Thu, 9 Jan 2025 16:59:42 +0000
Subject: [PATCH 03/82] refactor: move TLB management to interpret.cpp

---
 src/Makefile                        |  11 +-
 src/find-pma-entry.h                |  17 +-
 src/host-addr.h                     |  98 ++++
 src/i-state-access.h                | 264 ++++++-----
 src/interpret.cpp                   | 258 ++++++++---
 src/machine-state.h                 |   2 +-
 src/machine.cpp                     | 204 +++++---
 src/machine.h                       |  31 ++
 src/pma.h                           |  10 +
 src/record-send-cmio-state-access.h |  21 +-
 src/record-step-state-access.h      | 254 +++++-----
 src/replay-send-cmio-state-access.h |  22 +-
 src/replay-step-state-access.h      | 690 ++++++++++++++--------------
 src/shadow-pmas.h                   |  10 +
 src/shadow-state.h                  |   1 +
 src/shadow-tlb-factory.cpp          |  56 +--
 src/shadow-tlb.h                    | 122 ++---
 src/state-access.h                  | 249 ++++------
 src/strict-aliasing.h               |  94 ++--
 src/tlb.h                           |  98 ++++
 src/translate-virtual-address.h     |  24 +-
 src/uarch-bridge.h                  |  28 +-
 src/uarch-solidity-compat.h         |  23 +-
 src/uarch-state-access.h            |   4 +
 src/uarch-step.cpp                  |  28 +-
 25 files changed, 1480 insertions(+), 1139 deletions(-)
 create mode 100644 src/host-addr.h
 create mode 100644 src/tlb.h

diff --git a/src/Makefile b/src/Makefile
index 2fcc1a4c4..f7780c2fb 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -374,20 +374,21 @@ LIBCARTESI_OBJS:= \
 	base64.o \
 	interpret.o \
 	virtual-machine.o \
-	uarch-machine.o \
-	uarch-step.o \
-	uarch-reset-state.o \
 	sha3.o \
 	machine-merkle-tree.o \
 	pristine-merkle-tree.o \
-	uarch-interpret.o \
 	machine-c-api.o \
 	uarch-pristine-ram.o \
 	uarch-pristine-state-hash.o \
 	uarch-pristine-hash.o \
-	send-cmio-response.o \
 	replay-step-state-access-interop.o
 
+	#send-cmio-response.o \
+	#uarch-machine.o \
+    #uarch-interpret.o \
+	#uarch-step.o \
+	#uarch-reset-state.o \
+
 CARTESI_CLUA_OBJS:= \
 	clua.o \
 	clua-i-virtual-machine.o
diff --git a/src/find-pma-entry.h b/src/find-pma-entry.h
index a9a41f919..1e2b223b9 100644
--- a/src/find-pma-entry.h
+++ b/src/find-pma-entry.h
@@ -27,10 +27,11 @@ namespace cartesi {
 /// \tparam STATE_ACCESS Class of machine state accessor object.
 /// \param a Machine state accessor object.
 /// \param paddr Target physical address of word.
+/// \param index Receives index where PMA entry was found.
 /// \returns PMA entry where word falls, or empty sentinel.
 template <typename T, typename STATE_ACCESS>
-static FORCE_INLINE auto &find_pma_entry(STATE_ACCESS a, uint64_t paddr) {
-    uint64_t index = 0;
+auto &find_pma_entry(STATE_ACCESS &a, uint64_t paddr, uint64_t &index) {
+    index = 0;
     while (true) {
         auto &pma = a.read_pma_entry(index);
         const auto length = pma.get_length();
@@ -53,6 +54,18 @@ static FORCE_INLINE auto &find_pma_entry(STATE_ACCESS a, uint64_t paddr) {
     }
 }
 
+/// \brief Returns PMAs entry where a word falls.
+/// \tparam T uint8_t, uint16_t, uint32_t, or uint64_t.
+/// \tparam STATE_ACCESS Class of machine state accessor object.
+/// \param a Machine state accessor object.
+/// \param paddr Target physical address of word.
+/// \returns PMA entry where word falls, or empty sentinel.
+template <typename T, typename STATE_ACCESS>
+FORCE_INLINE auto &find_pma_entry(STATE_ACCESS &a, uint64_t paddr) {
+    uint64_t index = 0;
+    return find_pma_entry<T>(a, paddr, index);
+}
+
 } // namespace cartesi
 
 #endif // FIND_PMA_ENTRY_H
diff --git a/src/host-addr.h b/src/host-addr.h
new file mode 100644
index 000000000..b6a33f6d1
--- /dev/null
+++ b/src/host-addr.h
@@ -0,0 +1,98 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef HOST_ADDR_H
+#define HOST_ADDR_H
+
+namespace cartesi {
+
+// This is simply an uint64_t as a separate type, not automatically convertible to uint64_t
+// It prevents any attempt of passing a host_addr where one is not expected
+enum class host_addr : uint64_t {};
+
+// Comparison operaator
+static constexpr bool operator<(host_addr a, host_addr b) {
+    return static_cast<uint64_t>(a) < static_cast<uint64_t>(b);
+}
+
+// Addition between host_addr
+static constexpr host_addr operator+(host_addr a, host_addr b) {
+    return host_addr{static_cast<uint64_t>(a) + static_cast<uint64_t>(b)};
+}
+
+// Subtraction between host_addr
+static constexpr host_addr operator-(host_addr a, host_addr b) {
+    return host_addr{static_cast<uint64_t>(a) - static_cast<uint64_t>(b)};
+}
+
+// Addition between host_addr and uint64_t
+static constexpr host_addr operator+(uint64_t a, host_addr b) {
+    return host_addr{a + static_cast<uint64_t>(b)};
+}
+
+// Addition between host_addr and uint64_t
+static constexpr host_addr operator+(host_addr a, uint64_t b) {
+    return host_addr{static_cast<uint64_t>(a) + b};
+}
+
+// Subtraction between host_addr and uint64_t
+static constexpr host_addr operator-(uint64_t a, host_addr b) {
+    return host_addr{a - static_cast<uint64_t>(b)};
+}
+
+// Subtraction between host_addr and uint64_t
+static constexpr host_addr operator-(host_addr a, uint64_t b) {
+    return host_addr{static_cast<uint64_t>(a) - b};
+}
+
+/// \brief Converts pointer to host_addr.
+/// \tparam PTR Pointer type to perform the cast.
+/// \param ptr The pointer to retrieve its unsigned integer representation.
+/// \returns Corresponding host_addr.
+/// \details Use cast_host_addr_to_ptr The address returned by this function,
+/// can later be converted to a pointer using cast_addr_to_ptr,
+/// and must be read/written using aliased_aligned_read/aliased_aligned_write,
+/// otherwise strict aliasing rules may be violated.
+static inline host_addr cast_ptr_to_host_addr(const void *ptr) {
+    static_assert(sizeof(void *) == sizeof(uintptr_t));
+    static_assert(sizeof(host_addr) >= sizeof(uintptr_t));
+    // Note that bellow we cast the pointer to void* first,
+    // according to the C spec this is required is to ensure the same presentation, before casting to uintptr_t
+    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast,bugprone-casting-through-void)
+    return host_addr{reinterpret_cast<uintptr_t>(ptr)};
+}
+
+/// \brief Casts a pointer to an unsigned integer.
+/// \details The pointer returned by this function
+/// must only be read/written using aliased_aligned_read/aliased_aligned_write,
+/// otherwise strict aliasing rules may be violated.
+/// \tparam T Unsigned integer type to cast to.
+/// \tparam PTR Pointer type to perform the cast.
+/// \param addr The address of the pointer represented by an unsigned integer.
+/// \returns A pointer.
+static inline void *cast_host_addr_to_ptr(host_addr host_addr) {
+    // Enforcement on type arguments
+    static_assert(sizeof(void *) == sizeof(uintptr_t));
+    static_assert(sizeof(host_addr) >= sizeof(uintptr_t));
+    // Note that bellow we cast the address to void* first,
+    // according to the C spec this is required is to ensure the same presentation, before casting to PTR
+    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast,bugprone-casting-through-void,performance-no-int-to-ptr)
+    return reinterpret_cast<void *>(static_cast<uintptr_t>(host_addr));
+}
+
+} // namespace cartesi
+
+#endif
diff --git a/src/i-state-access.h b/src/i-state-access.h
index d255899ee..2b2fad014 100644
--- a/src/i-state-access.h
+++ b/src/i-state-access.h
@@ -26,13 +26,25 @@
 
 #include "compiler-defines.h"
 #include "meta.h"
-#include "shadow-tlb.h"
+#include "tlb.h"
 
 namespace cartesi {
 
 // Forward declarations
 enum class bracket_type;
 
+// Type trait that should return the pma_entry type for a state access class
+template <typename STATE_ACCESS>
+struct i_state_access_pma_entry {};
+template <typename STATE_ACCESS>
+using i_state_access_pma_entry_t = typename i_state_access_pma_entry<STATE_ACCESS>::type;
+
+// Type trait that should return the fast_addr type for a state access class
+template <typename STATE_ACCESS>
+struct i_state_access_fast_addr {};
+template <typename STATE_ACCESS>
+using i_state_access_fast_addr_t = typename i_state_access_fast_addr<STATE_ACCESS>::type;
+
 /// \class i_state_access
 /// \brief Interface for machine state access.
 /// \details \{
@@ -40,8 +52,8 @@ enum class bracket_type;
 /// The "run" function does not need a log, and must be as fast as possible.
 /// Both functions share the exact same implementation of what it means to advance the machine state by one cycle.
 /// In this common implementation, all state accesses go through a class that implements the i_state_access interface.
-/// When looging is needed, a logged_state_access class is used.
-/// When no logging is needed, a state_access class is used.
+/// When logging is needed, a record state access class is used.
+/// When no logging is needed, a direct state access class is used.
 ///
 /// In a typical design, i_state_access would be pure virtual.
 /// For speed, we avoid virtual methods and instead use templates.
@@ -54,7 +66,7 @@ enum class bracket_type;
 /// Methods are provided to read and write each state component.
 /// \}
 /// \tparam DERIVED Derived class implementing the interface. (An example of CRTP.)
-template <typename DERIVED, typename PMA_ENTRY_TYPE>
+template <typename DERIVED>
 class i_state_access { // CRTP
     i_state_access() = default;
     friend DERIVED;
@@ -70,6 +82,10 @@ class i_state_access { // CRTP
     }
 
 public:
+    using pma_entry = i_state_access_pma_entry_t<DERIVED>;
+    using fast_addr = i_state_access_fast_addr_t<DERIVED>;
+
+    //??D We should probably remove this from the interface
     /// \brief Returns machine state for direct access.
     auto &get_naked_state() {
         return derived().do_get_naked_state();
@@ -99,8 +115,8 @@ class i_state_access { // CRTP
     /// \brief Writes register to general-purpose register.
     /// \param reg Register index.
     /// \param val New register value.
-    /// \details Writes to register zero *break* the machine. There is an assertion to catch this, but NDEBUG will let
-    /// the value pass through.
+    /// \details Writes to register zero *break* the machine.
+    /// There is an assertion to catch this, but NDEBUG will let the value pass through.
     void write_x(int reg, uint64_t val) {
         return derived().do_write_x(reg, val);
     }
@@ -591,21 +607,9 @@ class i_state_access { // CRTP
         return derived().do_read_htif_iyield();
     }
 
-    /// \brief Poll for external interrupts.
-    /// \param mcycle Current machine mcycle.
-    /// \param mcycle_max Maximum mcycle to wait for interrupts.
-    /// \returns A pair, the first value is the new machine mcycle advanced by the relative elapsed time while
-    /// polling, the second value is a boolean that is true when the poll is stopped due do an external interrupt
-    /// request.
-    /// \details When mcycle_max is greater than mcycle, this function will sleep until an external interrupt
-    /// is triggered or mcycle_max relative elapsed time is reached.
-    std::pair<uint64_t, bool> poll_external_interrupts(uint64_t mcycle, uint64_t mcycle_max) {
-        return derived().do_poll_external_interrupts(mcycle, mcycle_max);
-    }
-
     /// \brief Reads PMA entry at a given index.
     /// \param index Index of PMA
-    PMA_ENTRY_TYPE &read_pma_entry(uint64_t index) {
+    pma_entry &read_pma_entry(uint64_t index) {
         return derived().do_read_pma_entry(index);
     }
 
@@ -631,98 +635,124 @@ class i_state_access { // CRTP
         return derived().do_write_memory(paddr, data, length);
     }
 
-    /// \brief Reads a word from memory.
-    /// \tparam T Type of word to read.
-    /// \param paddr Target physical address.
-    /// \param hpage Pointer to page start in host memory.
-    /// \param hoffset Offset in page (must be aligned to sizeof(T)).
-    /// \param pval Pointer to word receiving value.
-    template <typename T>
-    void read_memory_word(uint64_t paddr, const unsigned char *hpage, uint64_t hoffset, T *pval) {
-        static_assert(std::is_integral_v<T> && sizeof(T) <= sizeof(uint64_t), "unsupported type");
-        return derived().template do_read_memory_word<T>(paddr, hpage, hoffset, pval);
-    }
-
-    /// \brief Writes a word to memory.
-    /// \tparam T Type of word to write.
-    /// \param paddr Target physical address.
-    /// \param hpage Pointer to page start in host memory.
-    /// \param hoffset Offset in page (must be aligned to sizeof(T)).
-    /// \param val Value to be written.
-    template <typename T>
-    void write_memory_word(uint64_t paddr, unsigned char *hpage, uint64_t hoffset, T val) {
-        static_assert(std::is_integral_v<T> && sizeof(T) <= sizeof(uint64_t), "unsupported type");
-        return derived().template do_write_memory_word<T>(paddr, hpage, hoffset, val);
-    }
-
-    auto get_host_memory(PMA_ENTRY_TYPE &pma) {
-        return derived().do_get_host_memory(pma);
-    }
-
-    /// \brief Try to translate a virtual address to a host pointer through the TLB.
-    /// \tparam ETYPE TLB entry type.
-    /// \tparam T Type of word that would be read with the pointer.
-    /// \param vaddr Target virtual address.
-    /// \param phptr Pointer to host pointer receiving value.
-    /// \returns True if successful (TLB hit), false otherwise.
-    template <TLB_entry_type ETYPE, typename T>
-    bool translate_vaddr_via_tlb(uint64_t vaddr, unsigned char **phptr) {
-        return derived().template do_translate_vaddr_via_tlb<ETYPE, T>(vaddr, phptr);
+    /// \brief Write a data buffer to memory padded with 0
+    /// \param paddr Destination physical address.
+    /// \param data Pointer to source data buffer.
+    /// \param data_length Length of data buffer.
+    /// \param write_length_log2_size Log2 size of the total write length.
+    void write_memory_with_padding(uint64_t paddr, const unsigned char *data, uint64_t data_length,
+        int write_length_log2_size) {
+        return derived().do_write_memory_with_padding(paddr, data, data_length, write_length_log2_size);
     }
 
-    /// \brief Try to read a word from memory through the TLB.
-    /// \tparam ETYPE TLB entry type.
-    /// \tparam T Type of word to read.
-    /// \param vaddr Target virtual address.
+    /// \brief Reads a word from memory.
+    /// \tparam T Type of word to read, potentially unaligned.
+    /// \tparam A Type to which \p paddr and \p haddr are known to be aligned.
+    /// \param faddr Implementation-defined fast address.
     /// \param pval Pointer to word receiving value.
-    /// \returns True if successful (TLB hit), false otherwise.
-    template <TLB_entry_type ETYPE, typename T>
-    bool read_memory_word_via_tlb(uint64_t vaddr, T *pval) {
-        static_assert(std::is_integral_v<T> && sizeof(T) <= sizeof(uint64_t), "unsupported type");
-        return derived().template do_read_memory_word_via_tlb<ETYPE, T>(vaddr, pval);
+    /// \warning T must not cross page boundary starting from \p faddr
+    /// \warning T may or may not cross a Merkle tree word boundary starting from \p faddr!
+    template <typename T, typename A = T>
+    void read_memory_word(fast_addr faddr, uint64_t pma_index, T *pval) {
+        static_assert(std::is_integral<T>::value && sizeof(T) <= sizeof(uint64_t), "unsupported type");
+        return derived().template do_read_memory_word<T, A>(faddr, pma_index, pval);
     }
 
-    /// \brief Try to write a word to memory through the TLB.
-    /// \tparam ETYPE TLB entry type.
+    /// \brief Writes a word to memory.
     /// \tparam T Type of word to write.
-    /// \param vaddr Target virtual address.
+    /// \tparam A Type to which \p paddr and \p haddr are known to be aligned.
+    /// \param faddr Implementation-defined fast address.
     /// \param val Value to be written.
-    /// \returns True if successful (TLB hit), false otherwise.
-    template <TLB_entry_type ETYPE, typename T>
-    bool write_memory_word_via_tlb(uint64_t vaddr, T val) {
-        static_assert(std::is_integral_v<T> && sizeof(T) <= sizeof(uint64_t), "unsupported type");
-        return derived().template do_write_memory_word_via_tlb<ETYPE, T>(vaddr, val);
+    /// \details \p haddr is ONLY valid when there is a host machine.
+    /// It should never be referenced outside of this context.
+    /// \warning T must not cross page boundary starting from \p faddr
+    /// \warning T may or may not cross a Merkle tree word boundary starting from \p faddr!
+    template <typename T, typename A = T>
+    void write_memory_word(fast_addr faddr, uint64_t pma_index, T val) {
+        static_assert(std::is_integral<T>::value && sizeof(T) <= sizeof(uint64_t), "unsupported type");
+        return derived().template do_write_memory_word<T, A>(faddr, pma_index, val);
+    }
+
+    /// \brief Reads TLB's vaddr_page
+    /// \tparam USE TLB set
+    /// \param slot_index Slot index
+    /// \returns Value in slot.
+    template <TLB_set_use USE>
+    uint64_t read_tlb_vaddr_page(uint64_t slot_index) {
+        return derived().template do_read_tlb_vaddr_page<USE>(slot_index);
+    }
+
+    /// \brief Reads TLB's vp_offset
+    /// \tparam USE TLB set
+    /// \param slot_index Slot index
+    /// \returns Value in slot.
+    template <TLB_set_use USE>
+    fast_addr read_tlb_vp_offset(uint64_t slot_index) {
+        return derived().template do_read_tlb_vp_offset<USE>(slot_index);
+    }
+
+    /// \brief Reads TLB's pma_index
+    /// \tparam USE TLB set
+    /// \param slot_index Slot index
+    /// \returns Value in slot.
+    template <TLB_set_use USE>
+    uint64_t read_tlb_pma_index(uint64_t slot_index) {
+        return derived().template do_read_tlb_pma_index<USE>(slot_index);
+    }
+
+    /// \brief Writes to a TLB slot
+    /// \tparam USE TLB set
+    /// \param slot_index Slot index
+    /// \param vaddr_page Value to write
+    /// \param vp_offset Value to write
+    /// \param pma_index Value to write
+    /// \detail Writes to the TLB must be modify all fields atomically to prevent an inconsistent state.
+    /// This simplifies all state access implementations.
+    template <TLB_set_use USE>
+    void write_tlb(uint64_t slot_index, uint64_t vaddr_page, fast_addr vp_offset, uint64_t pma_index) {
+        return derived().template do_write_tlb<USE>(slot_index, vaddr_page, vp_offset, pma_index);
+    }
+
+    /// \brief Converts a target physical address to the implementation-defined fast address
+    /// \param paddr Target physical address to convert
+    /// \param pma_index Index of PMA where address falls
+    /// \returns Correspnding implementation-defined fast address
+    fast_addr get_faddr(uint64_t paddr, uint64_t pma_index) const {
+        return derived().do_get_faddr(paddr, pma_index);
+    }
+
+    /// \brief Marks a page as dirty
+    /// \param faddr Implementation-defined fast address.
+    /// \param pma_index Index of PMA where page falls
+    /// \details When there is a host machine, the Merkle tree only updates the hashes for pages that
+    /// have been modified. Pages can only be written to if they appear in the write TLB. Therefore,
+    /// the Merkle tree only considers the pages that are currently in the write TLB and those that
+    /// have been marked dirty. When a page leaves the write TLB, it is marked dirty.
+    /// If the state belongs to a host machine, then this call MUST be forwarded to machine::mark_dirty_page();
+    void mark_dirty_page(fast_addr faddr, uint64_t pma_index) {
+        return derived().do_mark_dirty_page(faddr, pma_index);
     }
 
-    /// \brief Replaces an entry in the TLB.
-    /// \tparam ETYPE TLB entry type to replace.
-    /// \param vaddr Target virtual address.
-    /// \param paddr Target physical address.
-    /// \param pma PMA entry for the physical address.
-    /// \returns Pointer to page start in host memory.
-    template <TLB_entry_type ETYPE>
-    unsigned char *replace_tlb_entry(uint64_t vaddr, uint64_t paddr, PMA_ENTRY_TYPE &pma) {
-        return derived().template do_replace_tlb_entry<ETYPE>(vaddr, paddr, pma);
-    }
-
-    /// \brief Invalidates all TLB entries of a type.
-    /// \tparam ETYPE TLB entry type to flush.
-    template <TLB_entry_type ETYPE>
-    void flush_tlb_type() {
-        return derived().template do_flush_tlb_type<ETYPE>();
+    /// \brief Writes a character to the console
+    /// \param c Character to output
+    void putchar(uint8_t c) {
+        return derived().do_putchar(c);
     }
 
-    /// \brief Invalidates all TLB entries of all types.
-    NO_INLINE void flush_all_tlb() {
-        derived().template flush_tlb_type<TLB_CODE>();
-        derived().template flush_tlb_type<TLB_READ>();
-        derived().template flush_tlb_type<TLB_WRITE>();
-    }
+    // ---
+    // These methods ONLY need to be implemented when state belongs to non-reproducible host machine
+    // ---
 
-    /// \brief Invalidates TLB entries for a specific virtual address.
-    /// \param vaddr Target virtual address.
-    NO_INLINE void flush_tlb_vaddr(uint64_t vaddr) {
-        return derived().do_flush_tlb_vaddr(vaddr);
+    /// \brief Poll for external interrupts.
+    /// \param mcycle Current machine mcycle.
+    /// \param mcycle_max Maximum mcycle to wait for interrupts.
+    /// \returns A pair, the first value is the new machine mcycle advanced by the relative elapsed time while
+    /// polling, the second value is a boolean that is true when the poll is stopped due do an external interrupt
+    /// request.
+    /// \details When mcycle_max is greater than mcycle, this function will sleep until an external interrupt
+    /// is triggered or mcycle_max relative elapsed time is reached.
+    std::pair<uint64_t, bool> poll_external_interrupts(uint64_t mcycle, uint64_t mcycle_max) {
+        return derived().do_poll_external_interrupts(mcycle, mcycle_max);
     }
 
     /// \brief Returns true if soft yield HINT instruction is enabled at runtime
@@ -730,22 +760,6 @@ class i_state_access { // CRTP
         return derived().do_get_soft_yield();
     }
 
-    /// \brief Write a data buffer to memory padded with 0
-    /// \param paddr Destination physical address.
-    /// \param data Pointer to source data buffer.
-    /// \param data_length Length of data buffer.
-    /// \param write_length_log2_size Log2 size of the total write length.
-    void write_memory_with_padding(uint64_t paddr, const unsigned char *data, uint64_t data_length,
-        int write_length_log2_size) {
-        return derived().do_write_memory_with_padding(paddr, data, data_length, write_length_log2_size);
-    }
-
-    /// \brief Writes a character to the console
-    /// \param c Character to output
-    void putchar(uint8_t c) {
-        return derived().do_putchar(c);
-    }
-
     /// \brief Reads a character from the console
     /// \returns Character read if any, -1 otherwise
     int getchar() {
@@ -753,10 +767,30 @@ class i_state_access { // CRTP
     }
 
 #ifdef DUMP_COUNTERS
+    //??D we should probably remove this from the interface
     auto &get_statistics() {
         return derived().do_get_statistics();
     }
 #endif
+
+protected:
+
+    /// \brief Default implementation when state does not belong to non-reproducible host machine
+    bool do_get_soft_yield() { // NOLINT(readability-convert-member-functions-to-static)
+        return false;
+    }
+
+    /// \brief Default implementation when state does not belong to non-reproducible host machine
+    std::pair<uint64_t, bool> do_poll_external_interrupts(uint64_t mcycle,
+        uint64_t /* mcycle_max */) { // NOLINT(readability-convert-member-functions-to-static)
+        return {mcycle, false};
+    }
+
+    /// \brief Default implementation when state does not belong to non-reproducible host machine
+    int do_getchar() { // NOLINT(readability-convert-member-functions-to-static)
+        return -1;
+    }
+
 };
 
 /// \brief SFINAE test implementation of the i_state_access interface
diff --git a/src/interpret.cpp b/src/interpret.cpp
index 231f8bb3b..d986d4f7e 100644
--- a/src/interpret.cpp
+++ b/src/interpret.cpp
@@ -21,8 +21,10 @@
 #include <utility>
 
 #ifdef MICROARCHITECTURE
+#ifdef OKUARCH
 #include "uarch-machine-state-access.h"
 #include "uarch-runtime.h"
+#endif
 #else
 #include "record-step-state-access.h"
 #include "replay-step-state-access.h"
@@ -31,9 +33,10 @@
 #endif // MICROARCHITECTURE
 
 #include "compiler-defines.h"
+#include "device-state-access.h"
 #include "i-state-access.h"
 #include "machine-statistics.h"
-#include "shadow-tlb.h"
+#include "tlb.h"
 
 /// \file
 /// \brief Interpreter implementation.
@@ -334,7 +337,7 @@ static FORCE_INLINE void set_prv(STATE_ACCESS a, int new_prv) {
     INC_COUNTER(a.get_statistics(), priv_level[new_prv]);
     a.write_iprv(new_prv);
     // Invalidate all TLB entries
-    a.flush_all_tlb();
+    flush_all_tlb(a);
     INC_COUNTER(a.get_statistics(), tlb_flush_all);
     INC_COUNTER(a.get_statistics(), tlb_flush_set_prv);
     //??D new privileged 1.11 draft says invalidation should
@@ -823,6 +826,104 @@ static FORCE_INLINE int32_t insn_get_C_SWSP_imm(uint32_t insn) {
     return static_cast<int32_t>(((insn >> (9 - 2)) & 0x3c) | ((insn >> (7 - 6)) & 0xc0));
 }
 
+/// \brief Flushes out a TLB slot
+/// \tparam USE TLB set
+/// \tparam STATE_ACCESS Class of machine state accessor object.
+/// \param a Machine state accessor object.
+/// \param slot_index Slot index
+template <TLB_set_use USE, typename STATE_ACCESS>
+static void flush_tlb_slot(STATE_ACCESS &a, uint64_t slot_index) {
+    // Make sure a valid page leaving the write TLB is marked as dirty
+    // We must do this BEFORE we modify the TLB entries themselves
+    // (Otherwise, we could stop uarch before it marks the page dirty but after
+    // the entry is no longer in the TLB, which would cause the Merkle tree to
+    // miss a dirty page.)
+    if constexpr (USE == TLB_WRITE) {
+        const auto old_vaddr_page = a.template read_tlb_vaddr_page<TLB_WRITE>(slot_index);
+        if (old_vaddr_page != TLB_INVALID_PAGE) {
+            auto old_pma_index = a.template read_tlb_pma_index<TLB_WRITE>(slot_index);
+            const auto old_faddr_page = old_vaddr_page + a.template read_tlb_vp_offset<TLB_WRITE>(slot_index);
+            a.mark_dirty_page(old_faddr_page, old_pma_index);
+        }
+    }
+    // We do not leave garbage behind in empty slots
+    // (It would make state access classes trickier to implement)
+    const auto vaddr_page = TLB_INVALID_PAGE;
+    const auto vp_offset = i_state_access_fast_addr_t<STATE_ACCESS>{};
+    const auto pma_index = TLB_INVALID_PMA_INDEX;
+    a.template write_tlb<USE>(slot_index, vaddr_page, vp_offset, pma_index);
+}
+
+/// \brief Flushes out an entire TLB set
+/// \tparam USE TLB set
+/// \tparam STATE_ACCESS Class of machine state accessor object.
+/// \param a Machine state accessor object.
+template <TLB_set_use USE, typename STATE_ACCESS>
+static void flush_tlb_set(STATE_ACCESS &a) {
+    for (uint64_t slot_index = 0; slot_index < PMA_TLB_SIZE; ++slot_index) {
+        flush_tlb_slot<USE>(a, slot_index);
+    }
+}
+
+/// \brief Flushes out the entire TLB
+/// \tparam STATE_ACCESS Class of machine state accessor object.
+/// \param a Machine state accessor object.
+template <typename STATE_ACCESS>
+static void flush_all_tlb(STATE_ACCESS &a) {
+    flush_tlb_set<TLB_CODE>(a);
+    flush_tlb_set<TLB_READ>(a);
+    flush_tlb_set<TLB_WRITE>(a);
+}
+
+/// \brief Flushes out a single virtual mapping in the TLB
+/// \tparam STATE_ACCESS Class of machine state accessor object.
+/// \param a Machine state accessor object.
+/// \param vaddr Virtual address to remove form mapping
+template <typename STATE_ACCESS>
+static void flush_tlb_vaddr(STATE_ACCESS &a, uint64_t /* vaddr */) {
+    // We can't flush just one TLB entry for that specific virtual address,
+    // because megapages/gigapages may be in use while this TLB implementation ignores it,
+    // so we have to flush all addresses.
+    flush_tlb_set<TLB_CODE>(a);
+    flush_tlb_set<TLB_READ>(a);
+    flush_tlb_set<TLB_WRITE>(a);
+}
+
+/// \brief Replaces a virtual mapping in a TLB set
+/// \tparam USE TLB set
+/// \tparam STATE_ACCESS Class of machine state accessor object.
+/// \param a Machine state accessor object.
+/// \param vaddr Virtual address of new mapping
+/// \param paddr Corresponding physical address
+/// \param paddr Index of PMA where paddr falls
+/// \param vp_offset Receives the new vp_offset that will be stored in the slot
+/// \returns The implementation-defined fast address corresponding to paddr
+template <TLB_set_use USE, typename STATE_ACCESS>
+static i_state_access_fast_addr_t<STATE_ACCESS> replace_tlb_entry(STATE_ACCESS &a, uint64_t vaddr, uint64_t paddr,
+    uint64_t pma_index, i_state_access_fast_addr_t<STATE_ACCESS> &vp_offset) {
+    const auto slot_index = tlb_slot_index(vaddr);
+    flush_tlb_slot<USE>(a, slot_index);
+    const auto vaddr_page = tlb_addr_page(vaddr);
+    const auto faddr = a.get_faddr(paddr, pma_index);
+    vp_offset = faddr - vaddr;
+    a.template write_tlb<USE>(slot_index, vaddr_page, vp_offset, pma_index);
+    return faddr;
+}
+
+/// \brief Replaces a virtual mapping in a TLB set
+/// \tparam USE TLB set
+/// \tparam STATE_ACCESS Class of machine state accessor object.
+/// \param a Machine state accessor object.
+/// \param vaddr Virtual address of new mapping
+/// \param paddr Corresponding physical address
+/// \param paddr Index of PMA where paddr falls
+/// \returns The implementation-defined fast address corresponding to paddr
+template <TLB_set_use USE, typename STATE_ACCESS>
+static FORCE_INLINE auto replace_tlb_entry(STATE_ACCESS &a, uint64_t vaddr, uint64_t paddr, uint64_t pma_index) {
+    i_state_access_fast_addr_t<STATE_ACCESS> vp_offset{0};
+    return replace_tlb_entry<USE>(a, vaddr, paddr, pma_index, vp_offset);
+}
+
 /// \brief Read an aligned word from virtual memory (slow path that goes through virtual address translation).
 /// \tparam T uint8_t, uint16_t, uint32_t, or uint64_t.
 /// \tparam STATE_ACCESS Class of machine state accessor object.
@@ -855,12 +956,12 @@ static NO_INLINE std::pair<bool, uint64_t> read_virtual_memory_slow(STATE_ACCESS
             vaddr);
         return {false, pc};
     }
-    auto &pma = find_pma_entry<T>(a, paddr);
+    uint64_t pma_index = 0;
+    const auto &pma = find_pma_entry<T>(a, paddr, pma_index);
     if (likely(pma.get_istart_R())) {
         if (likely(pma.get_istart_M())) {
-            unsigned char *hpage = a.template replace_tlb_entry<TLB_READ>(vaddr, paddr, pma);
-            const uint64_t hoffset = vaddr & PAGE_OFFSET_MASK;
-            a.read_memory_word(paddr, hpage, hoffset, pval);
+            const auto faddr = replace_tlb_entry<TLB_READ>(a, vaddr, paddr, pma_index);
+            a.template read_memory_word(faddr, pma_index, pval);
             return {true, pc};
         }
         if (likely(pma.get_istart_IO())) {
@@ -893,7 +994,9 @@ static NO_INLINE std::pair<bool, uint64_t> read_virtual_memory_slow(STATE_ACCESS
 template <typename T, typename STATE_ACCESS, bool RAISE_STORE_EXCEPTIONS = false>
 static FORCE_INLINE bool read_virtual_memory(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint64_t vaddr, T *pval) {
     // Try hitting the TLB
-    if (unlikely(!(a.template read_memory_word_via_tlb<TLB_READ>(vaddr, pval)))) {
+    const auto slot_index = tlb_slot_index(vaddr);
+    const auto slot_vaddr_page = a.template read_tlb_vaddr_page<TLB_READ>(slot_index);
+    if (unlikely(!tlb_is_hit<T>(slot_vaddr_page, vaddr))) {
         // Outline the slow path into a function call to minimize host CPU code cache pressure
         INC_COUNTER(a.get_statistics(), tlb_rmiss);
         T val = 0; // Don't pass pval reference directly so the compiler can store it in a register
@@ -903,6 +1006,10 @@ static FORCE_INLINE bool read_virtual_memory(STATE_ACCESS a, uint64_t &pc, uint6
         pc = new_pc;
         return status;
     }
+    const auto pma_index = a.template read_tlb_pma_index<TLB_READ>(slot_index);
+    const auto vp_offset = a.template read_tlb_vp_offset<TLB_READ>(slot_index);
+    const auto faddr = vaddr + vp_offset;
+    a.template read_memory_word<T>(faddr, pma_index, pval);
     INC_COUNTER(a.get_statistics(), tlb_rhit);
     return true;
 }
@@ -936,12 +1043,12 @@ static NO_INLINE std::pair<execute_status, uint64_t> write_virtual_memory_slow(S
         pc = raise_exception(a, pc, MCAUSE_STORE_AMO_PAGE_FAULT, vaddr);
         return {execute_status::failure, pc};
     }
-    auto &pma = find_pma_entry<T>(a, paddr);
+    uint64_t pma_index = 0;
+    auto &pma = find_pma_entry<T>(a, paddr, pma_index);
     if (likely(pma.get_istart_W())) {
         if (likely(pma.get_istart_M())) {
-            unsigned char *hpage = a.template replace_tlb_entry<TLB_WRITE>(vaddr, paddr, pma);
-            const uint64_t hoffset = vaddr & PAGE_OFFSET_MASK;
-            a.write_memory_word(paddr, hpage, hoffset, static_cast<T>(val64));
+            const auto faddr = replace_tlb_entry<TLB_WRITE>(a, vaddr, paddr, pma_index);
+            a.write_memory_word(faddr, pma_index, static_cast<T>(val64));
             return {execute_status::success, pc};
         }
         if (likely(pma.get_istart_IO())) {
@@ -971,13 +1078,19 @@ template <typename T, typename STATE_ACCESS>
 static FORCE_INLINE execute_status write_virtual_memory(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint64_t vaddr,
     uint64_t val64) {
     // Try hitting the TLB
-    if (unlikely((!a.template write_memory_word_via_tlb<TLB_WRITE>(vaddr, static_cast<T>(val64))))) {
-        INC_COUNTER(a.get_statistics(), tlb_wmiss);
+    const uint64_t slot_index = tlb_slot_index(vaddr);
+    const uint64_t slot_vaddr_page = a.template read_tlb_vaddr_page<TLB_WRITE>(slot_index);
+    if (unlikely(!tlb_is_hit<T>(slot_vaddr_page, vaddr))) {
         // Outline the slow path into a function call to minimize host CPU code cache pressure
+        INC_COUNTER(a.get_statistics(), tlb_wmiss);
         auto [status, new_pc] = write_virtual_memory_slow<T>(a, pc, mcycle, vaddr, val64);
         pc = new_pc;
         return status;
     }
+    const auto pma_index = a.template read_tlb_pma_index<TLB_READ>(slot_index);
+    const auto vp_offset = a.template read_tlb_vp_offset<TLB_READ>(slot_index);
+    const auto faddr = vaddr + vp_offset;
+    a.template write_memory_word<T>(faddr, pma_index, static_cast<T>(val64));
     INC_COUNTER(a.get_statistics(), tlb_whit);
     return execute_status::success;
 }
@@ -2041,7 +2154,7 @@ static NO_INLINE execute_status write_csr_satp(STATE_ACCESS a, uint64_t val) {
     // because software is required to execute SFENCE.VMA when recycling an ASID.
     const uint64_t mod = old_satp ^ stap;
     if (mod & (SATP_ASID_MASK | SATP_MODE_MASK)) {
-        a.flush_all_tlb();
+        flush_all_tlb(a);
         INC_COUNTER(a.get_statistics(), tlb_flush_all);
         INC_COUNTER(a.get_statistics(), tlb_flush_satp);
         return execute_status::success_and_flush_fetch;
@@ -2103,11 +2216,11 @@ static NO_INLINE execute_status write_csr_mstatus(STATE_ACCESS a, uint64_t val)
 
     // Flush TLBs when needed
     if (flush_tlb_read) {
-        a.template flush_tlb_type<TLB_READ>();
+        flush_tlb_set<TLB_READ>(a);
         INC_COUNTER(a.get_statistics(), tlb_flush_read);
     }
     if (flush_tlb_write) {
-        a.template flush_tlb_type<TLB_WRITE>();
+        flush_tlb_set<TLB_WRITE>(a);
         INC_COUNTER(a.get_statistics(), tlb_flush_write);
     }
     if (flush_tlb_read || flush_tlb_write) {
@@ -3358,7 +3471,7 @@ static FORCE_INLINE execute_status execute_SFENCE_VMA(STATE_ACCESS a, uint64_t &
     const uint32_t rs1 = insn_get_rs1(insn);
     [[maybe_unused]] const uint32_t rs2 = insn_get_rs2(insn);
     if (rs1 == 0) {
-        a.flush_all_tlb();
+        flush_all_tlb(a);
 #ifdef DUMP_COUNTERS
         INC_COUNTER(a.get_statistics(), tlb_flush_all);
         if (rs2 == 0) {
@@ -3373,7 +3486,7 @@ static FORCE_INLINE execute_status execute_SFENCE_VMA(STATE_ACCESS a, uint64_t &
 #endif
     } else {
         const uint64_t vaddr = a.read_x(rs1);
-        a.flush_tlb_vaddr(vaddr);
+        flush_tlb_vaddr(a, vaddr);
 #ifdef DUMP_COUNTERS
         INC_COUNTER(a.get_statistics(), tlb_flush_vaddr);
         if (rs2 == 0) {
@@ -5212,12 +5325,13 @@ enum class fetch_status : int {
 /// \param a Machine state accessor object.
 /// \param pc Virtual address for the current instruction being executed.
 /// \param vaddr Virtual address to be fetched.
-/// \param phptr Receives host pointer.
+/// \param vp_offset Receives vp_offset in the TLB slot
+/// \param pma_index Receives the index of PMA where vaddr falls
 /// \return Returns fetch_status::success if load succeeded, fetch_status::exception if it caused an exception.
 //          In that case, raise the exception.
 template <typename STATE_ACCESS>
 static FORCE_INLINE fetch_status fetch_translate_pc_slow(STATE_ACCESS a, uint64_t &pc, uint64_t vaddr,
-    unsigned char **phptr) {
+    i_state_access_fast_addr_t<STATE_ACCESS> &vp_offset, uint64_t &pma_index) {
     uint64_t paddr{};
     // Walk page table and obtain the physical address
     if (unlikely(!translate_virtual_address(a, &paddr, vaddr, PTE_XWR_X_SHIFT))) {
@@ -5225,16 +5339,14 @@ static FORCE_INLINE fetch_status fetch_translate_pc_slow(STATE_ACCESS a, uint64_
         return fetch_status::exception;
     }
     // Walk memory map to find the range that contains the physical address
-    auto &pma = find_pma_entry<uint16_t>(a, paddr);
+    const auto &pma = find_pma_entry<uint16_t>(a, paddr, pma_index);
     // We only execute directly from RAM (as in "random access memory")
     // If the range is not memory or not executable, this as a PMA violation
     if (unlikely(!pma.get_istart_M() || !pma.get_istart_X())) {
         pc = raise_exception(a, pc, MCAUSE_INSN_ACCESS_FAULT, vaddr);
         return fetch_status::exception;
     }
-    unsigned char *hpage = a.template replace_tlb_entry<TLB_CODE>(vaddr, paddr, pma);
-    const uint64_t hoffset = vaddr & PAGE_OFFSET_MASK;
-    *phptr = hpage + hoffset;
+    replace_tlb_entry<TLB_CODE>(a, vaddr, paddr, pma_index, vp_offset);
     return fetch_status::success;
 }
 
@@ -5243,18 +5355,23 @@ static FORCE_INLINE fetch_status fetch_translate_pc_slow(STATE_ACCESS a, uint64_
 /// \param a Machine state accessor object.
 /// \param pc Virtual address for the current instruction being executed.
 /// \param vaddr Virtual address to be fetched.
-/// \param phptr Receives the host pointer.
+/// \param vp_offset Receives vp_offset in the TLB slot
+/// \param pma_index Receives the index of PMA where vaddr falls
 /// \return Returns fetch_status::success if load succeeded, fetch_status::exception if it caused an exception.
 //          In that case, raise the exception.
 template <typename STATE_ACCESS>
 static FORCE_INLINE fetch_status fetch_translate_pc(STATE_ACCESS a, uint64_t &pc, uint64_t vaddr,
-    unsigned char **phptr) {
+    i_state_access_fast_addr_t<STATE_ACCESS> &vp_offset, uint64_t &pma_index) {
     // Try to perform the address translation via TLB first
-    if (unlikely(!(a.template translate_vaddr_via_tlb<TLB_CODE, uint16_t>(vaddr, phptr)))) {
+    const uint64_t slot_index = tlb_slot_index(vaddr);
+    const uint64_t slot_vaddr_page = a.template read_tlb_vaddr_page<TLB_CODE>(slot_index);
+    if (unlikely(!tlb_is_hit<uint16_t>(slot_vaddr_page, vaddr))) {
         INC_COUNTER(a.get_statistics(), tlb_cmiss);
         // Outline the slow path into a function call to minimize host CPU code cache pressure
-        return fetch_translate_pc_slow(a, pc, vaddr, phptr);
+        return fetch_translate_pc_slow(a, pc, vaddr, vp_offset, pma_index);
     }
+    vp_offset = a.template read_tlb_vp_offset<TLB_CODE>(slot_index);
+    pma_index = a.template read_tlb_pma_index<TLB_CODE>(slot_index);
     INC_COUNTER(a.get_statistics(), tlb_chit);
     return fetch_status::success;
 }
@@ -5264,66 +5381,57 @@ static FORCE_INLINE fetch_status fetch_translate_pc(STATE_ACCESS a, uint64_t &pc
 /// \param a Machine state accessor object.
 /// \param pc Virtual address for the current instruction being executed.
 /// \param insn Receives the instruction.
-/// \param fetch_vaddr_page Fetch virtual address translation page cache.
-/// \param fetch_vh_offset Fetch virtual address host pointer offset cache.
+/// \param last_vaddr_page Receives and updates vaddr_page for cache.
+/// \param last_vp_offset Receives and updates vp_offset for cache.
+/// \param last_pma_index Receives and updates pma_index for cache.
 /// \return Returns fetch_status::success if load succeeded, fetch_status::exception if it caused an exception.
 //          In that case, raise the exception.
 template <typename STATE_ACCESS>
-static FORCE_INLINE fetch_status fetch_insn(STATE_ACCESS a, uint64_t &pc, uint32_t &insn, uint64_t &fetch_vaddr_page,
-    uint64_t &fetch_vh_offset) {
-    // Efficiently checks if current pc is in the same page as last pc fetch
-    // and it's not crossing a page boundary.
-    if (likely((pc ^ fetch_vaddr_page) < (PMA_PAGE_SIZE - 2))) {
-        // Fetch pc is in the same page as the last pc fetch and it's not crossing a page boundary,
-        // we can just reuse last fetch translation, skipping TLB or slow address translation altogether.
-        const unsigned char *hptr = cast_addr_to_ptr<unsigned char *>(pc + fetch_vh_offset);
-
-        // Here we are sure that reading 4 bytes won't cross a page boundary.
-        // However pc may not be 4 byte aligned, at best it can only be 2-byte aligned,
-        // therefore we must perform a misaligned 4 byte read on a 2 byte aligned pointer.
-        // In case pc holds a compressed instruction, insn will store 2 additional bytes,
-        // but this is fine because later the instruction decoder will discard them.
-        insn = aliased_unaligned_read<uint32_t, uint16_t>(hptr);
-        return fetch_status::success;
-    }
-    // Fetch pc is either not the same as last cache or crossing a page boundary.
-
-    // Perform address translation
-    unsigned char *hptr = nullptr;
-    if (unlikely(fetch_translate_pc(a, pc, pc, &hptr) == fetch_status::exception)) {
-        return fetch_status::exception;
+static FORCE_INLINE fetch_status fetch_insn(STATE_ACCESS a, uint64_t &pc, uint32_t &insn, uint64_t &last_vaddr_page,
+    i_state_access_fast_addr_t<STATE_ACCESS> &last_vp_offset, uint64_t &last_pma_index) {
+    i_state_access_fast_addr_t<STATE_ACCESS> faddr{0};
+    const uint64_t pc_vaddr_page = tlb_addr_page(pc);
+    // If pc is in the same page as the last pc fetch,
+    // we can just reuse last fetch translation, skipping TLB or slow address translation altogether.
+    if (likely(pc_vaddr_page == last_vaddr_page)) {
+        faddr = pc + last_vp_offset;
+    } else {
+        // Not in the same page as last the fetch, we need to perform address translation
+        if (unlikely(fetch_translate_pc(a, pc, pc, last_vp_offset, last_pma_index) == fetch_status::exception)) {
+            return fetch_status::exception;
+        }
+        // Update fetch address translation cache
+        last_vaddr_page = pc_vaddr_page;
+        faddr = pc + last_vp_offset;
     }
-    // Update fetch address translation cache
-    fetch_vaddr_page = pc & ~PAGE_OFFSET_MASK;
-    fetch_vh_offset = cast_ptr_to_addr<uint64_t>(hptr) - pc;
-
     // The following code assumes pc is always 2-byte aligned, this is guaranteed by RISC-V spec.
     // If pc is pointing to the very last 2 bytes of a page, it's crossing a page boundary.
     if (unlikely(((~pc & PAGE_OFFSET_MASK) >> 1) == 0)) {
         // Here we are crossing page boundary, this is unlikely (1 in 2048 possible cases)
-        insn = aliased_aligned_read<uint16_t>(hptr);
+        uint16_t insn16 = 0;
+        a.template read_memory_word(faddr, last_pma_index, &insn16);
+        insn = insn16;
         // If not a compressed instruction, we must read 2 additional bytes from the next page.
         if (unlikely(insn_is_uncompressed(insn))) {
             // We have to perform a new address translation to read the next 2 bytes since we changed pages.
-            const uint64_t vaddr = pc + 2;
-            if (unlikely(fetch_translate_pc(a, pc, vaddr, &hptr) == fetch_status::exception)) {
+            const uint64_t pc2 = pc + 2;
+            if (unlikely(fetch_translate_pc(a, pc, pc2, last_vp_offset, last_pma_index) == fetch_status::exception)) {
                 return fetch_status::exception;
             }
-            // Update fetch translation cache
-            fetch_vaddr_page = vaddr;
-            fetch_vh_offset = cast_ptr_to_addr<uint64_t>(hptr) - vaddr;
-            // Produce the final 4-byte instruction
-            insn |= aliased_aligned_read<uint16_t>(hptr) << 16;
+            last_vaddr_page = tlb_addr_page(pc2);
+            faddr = pc2 + last_vp_offset;
+            a.template read_memory_word(faddr, last_pma_index, &insn16);
+            insn |= insn16 << 16;
         }
         return fetch_status::success;
     }
 
     // Here we are sure that reading 4 bytes won't cross a page boundary.
-    // However pc may not be 4 byte aligned, at best it can only be 2-byte aligned,
-    // therefore we must perform a misaligned 4 byte read on a 2 byte aligned pointer.
+    // However pc may not be 4-byte aligned, at worst it could be only 2-byte aligned,
+    // therefore we must perform a misaligned 4-byte read on a 2-byte aligned pointer.
     // In case pc holds a compressed instruction, insn will store 2 additional bytes,
     // but this is fine because later the instruction decoder will discard them.
-    insn = aliased_unaligned_read<uint32_t, uint16_t>(hptr);
+    a.template read_memory_word<uint32_t, uint16_t>(faddr, last_pma_index, &insn);
     return fetch_status::success;
 }
 
@@ -5352,8 +5460,9 @@ static NO_INLINE execute_status interpret_loop(STATE_ACCESS a, uint64_t mcycle_e
     uint64_t pc = a.read_pc();
 
     // Initialize fetch address translation cache invalidated
-    uint64_t fetch_vaddr_page = ~pc;
-    uint64_t fetch_vh_offset = 0;
+    uint64_t fetch_vaddr_page = TLB_INVALID_PAGE;
+    uint64_t fetch_pma_index = TLB_INVALID_PMA_INDEX;
+    i_state_access_fast_addr_t<STATE_ACCESS> fetch_vp_offset{};
 
     // The outer loop continues until there is an interruption that should be handled
     // externally, or mcycle reaches mcycle_end
@@ -5390,7 +5499,8 @@ static NO_INLINE execute_status interpret_loop(STATE_ACCESS a, uint64_t mcycle_e
             uint32_t insn = 0;
 
             // Try to fetch the next instruction
-            if (likely(fetch_insn(a, pc, insn, fetch_vaddr_page, fetch_vh_offset) == fetch_status::success)) {
+            if (likely(fetch_insn(a, pc, insn, fetch_vaddr_page, fetch_vp_offset, fetch_pma_index) ==
+                    fetch_status::success)) {
                 // clang-format off
                 // NOLINTBEGIN
                 execute_status status; // explicit uninitialized as an optimization
@@ -5856,7 +5966,7 @@ static NO_INLINE execute_status interpret_loop(STATE_ACCESS a, uint64_t mcycle_e
                     // due to MRET/SRET instructions (execute_status::success_and_serve_interrupts)
                     // As a simplification (and optimization), the next line will also invalidate in more cases,
                     // but this it's fine.
-                    fetch_vaddr_page = ~pc;
+                    fetch_vaddr_page = TLB_INVALID_PAGE;
                     // All status above execute_status::success_and_serve_interrupts will require breaking the loop
                     if (unlikely(status >= execute_status::success_and_serve_interrupts)) {
                         // Increment the cycle counter mcycle
@@ -5932,14 +6042,16 @@ interpreter_break_reason interpret(STATE_ACCESS a, uint64_t mcycle_end) {
     }
     if (status == execute_status::success_and_yield) {
         return interpreter_break_reason::yielded_softly;
-    } // Reached mcycle_end
+    }                                      // Reached mcycle_end
     assert(a.read_mcycle() == mcycle_end); // LCOV_EXCL_LINE
     return interpreter_break_reason::reached_target_mcycle;
 }
 
 #ifdef MICROARCHITECTURE
+#ifdef OKUARCH
 // Explicit instantiation for uarch_machine_state_access
 template interpreter_break_reason interpret(uarch_machine_state_access a, uint64_t mcycle_end);
+#endif
 #else
 // Explicit instantiation for state_access
 template interpreter_break_reason interpret(state_access a, uint64_t mcycle_end);
diff --git a/src/machine-state.h b/src/machine-state.h
index e13edea6d..0b85a386e 100644
--- a/src/machine-state.h
+++ b/src/machine-state.h
@@ -106,7 +106,7 @@ struct machine_state {
     } plic;
 
     /// \brief TLB state
-    shadow_tlb_state tlb{};
+    tlb_state tlb{};
 
     /// \brief HTIF state
     struct {
diff --git a/src/machine.cpp b/src/machine.cpp
index 46ff2acd8..f18acd299 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -65,14 +65,17 @@
 #include "shadow-uarch-state.h"
 #include "state-access.h"
 #include "strict-aliasing.h"
+#include "tlb.h"
 #include "translate-virtual-address.h"
-#include "uarch-interpret.h"
 #include "uarch-pristine-state-hash.h"
+#ifdef OKUARCH
+#include "uarch-interpret.h"
 #include "uarch-record-state-access.h"
 #include "uarch-replay-state-access.h"
 #include "uarch-reset-state.h"
 #include "uarch-state-access.h"
 #include "uarch-step.h"
+#endif
 #include "unique-c-ptr.h"
 #include "virtio-console.h"
 #include "virtio-device.h"
@@ -223,48 +226,70 @@ void machine::replace_memory_range(const memory_range_config &range) {
     throw std::invalid_argument{"attempt to replace inexistent memory range"};
 }
 
-template <TLB_entry_type ETYPE>
-static void load_tlb_entry(machine &m, uint64_t eidx, unsigned char *hmem) {
-    tlb_hot_entry &tlbhe = m.get_state().tlb.hot[ETYPE][eidx];
-    tlb_cold_entry &tlbce = m.get_state().tlb.cold[ETYPE][eidx];
-    auto vaddr_page = aliased_aligned_read<uint64_t>(hmem + tlb_get_vaddr_page_rel_addr<ETYPE>(eidx));
-    auto paddr_page = aliased_aligned_read<uint64_t>(hmem + tlb_get_paddr_page_rel_addr<ETYPE>(eidx));
-    auto pma_index = aliased_aligned_read<uint64_t>(hmem + tlb_get_pma_index_rel_addr<ETYPE>(eidx));
-    if (vaddr_page != TLB_INVALID_PAGE) {
-        if ((vaddr_page & ~PAGE_OFFSET_MASK) != vaddr_page) {
-            throw std::invalid_argument{"misaligned virtual page address in TLB entry"};
+void machine::init_tlb() {
+    for (auto use : {TLB_CODE, TLB_READ, TLB_WRITE}) {
+        auto &hot_set = m_s.tlb.hot[use];
+        auto &cold_set = m_s.tlb.cold[use];
+        for (uint64_t slot_index = 0; slot_index < TLB_SET_SIZE; ++slot_index) {
+            auto &hot_slot = hot_set[slot_index];
+            hot_slot.vaddr_page = TLB_INVALID_PAGE;
+            hot_slot.vh_offset = host_addr{};
+            auto &cold_slot = cold_set[slot_index];
+            cold_slot.pma_index = TLB_INVALID_PMA_INDEX;
         }
-        if ((paddr_page & ~PAGE_OFFSET_MASK) != paddr_page) {
-            throw std::invalid_argument{"misaligned physical page address in TLB entry"};
-        }
-        const pma_entry &pma = m.find_pma_entry<uint64_t>(paddr_page);
-        // Checks if the PMA still valid
-        if (pma.get_length() == 0 || !pma.get_istart_M() || pma_index >= m.get_state().pmas.size() ||
-            &pma != &m.get_state().pmas[pma_index]) {
-            throw std::invalid_argument{"invalid PMA for TLB entry"};
+    }
+}
+
+void machine::init_tlb(const shadow_tlb_state &shadow_tlb) {
+    const char *err_prefix = "stored TLB is corrupted: ";
+    for (auto use : {TLB_CODE, TLB_READ, TLB_WRITE}) {
+        auto &hot_set = m_s.tlb.hot[use];
+        auto &cold_set = m_s.tlb.cold[use];
+        auto &shadow_set = shadow_tlb[use];
+        for (uint64_t slot_index = 0; slot_index < TLB_SET_SIZE; ++slot_index) {
+            // copy from shadow to live TLB
+            auto &shadow_slot = shadow_set[slot_index];
+            auto &cold_slot = cold_set[slot_index];
+            const auto pma_index = cold_slot.pma_index = shadow_slot.pma_index;
+            auto &hot_slot = hot_set[slot_index];
+            const auto vaddr_page = hot_slot.vaddr_page = shadow_slot.vaddr_page;
+            // check consistency of slot, if valid, and compute live host address offset
+            if (shadow_slot.vaddr_page != TLB_INVALID_PAGE) {
+                // virtual page address must be page-aligned
+                if (shadow_slot.vaddr_page & PAGE_OFFSET_MASK) {
+                    throw std::invalid_argument{err_prefix + "invalid vaddr_page in TLB slot"s};
+                }
+                // PMA index cannot be outside pmas array
+                if (pma_index >= m_s.pmas.size()) {
+                    throw std::invalid_argument{err_prefix + "invalid pma_index in active TLB slot"s};
+                }
+                // PMA at index must be a non-empty memory PMA
+                const auto &pma = m_s.pmas[pma_index];
+                if (pma.get_length() == 0 || !pma.get_istart_M()) {
+                    throw std::invalid_argument{err_prefix + "invalid pma_index in active TLB slot"s};
+                }
+                auto paddr_page = shadow_slot.vaddr_page + shadow_slot.vp_offset;
+                // translated physical page address must be page-aligned
+                if (paddr_page & PAGE_OFFSET_MASK) {
+                    throw std::invalid_argument{err_prefix + "invalid vp_offset in active TLB slot"s};
+                }
+                // translated physical page address must fall entirely into designated PMA
+                if (paddr_page < pma.get_start() || paddr_page - pma.get_start() > pma.get_length() - PMA_PAGE_SIZE) {
+                    throw std::invalid_argument{err_prefix + "invalid vp_offset in active TLB slot"s};
+                }
+                hot_slot.vh_offset = get_host_addr(paddr_page, pma_index) - vaddr_page;
+            } else {
+                if (shadow_slot.vp_offset != 0) {
+                    throw std::invalid_argument{err_prefix + "invalid vp_offset in empty TLB slot"s};
+                }
+                if (pma_index != TLB_INVALID_PMA_INDEX) {
+                    throw std::invalid_argument{err_prefix + "invalid pma_index in empty TLB slot"s};
+                }
+                // We never leave garbage behind, even in invalid slots
+                hot_slot.vh_offset = host_addr{};
+            }
         }
-        const unsigned char *hpage = pma.get_memory().get_host_memory() + (paddr_page - pma.get_start());
-        // Valid TLB entry
-        tlbhe.vaddr_page = vaddr_page;
-        tlbhe.vh_offset = cast_ptr_to_addr<uint64_t>(hpage) - vaddr_page;
-        tlbce.paddr_page = paddr_page;
-        tlbce.pma_index = pma_index;
-    } else { // Empty or invalidated TLB entry
-        tlbhe.vaddr_page = vaddr_page;
-        tlbhe.vh_offset = 0;
-        tlbce.paddr_page = paddr_page;
-        tlbce.pma_index = pma_index;
-    }
-}
-
-template <TLB_entry_type ETYPE>
-static void init_tlb_entry(machine &m, uint64_t eidx) {
-    tlb_hot_entry &tlbhe = m.get_state().tlb.hot[ETYPE][eidx];
-    tlb_cold_entry &tlbce = m.get_state().tlb.cold[ETYPE][eidx];
-    tlbhe.vaddr_page = TLB_INVALID_PAGE;
-    tlbhe.vh_offset = 0;
-    tlbce.paddr_page = TLB_INVALID_PAGE;
-    tlbce.pma_index = TLB_INVALID_PMA;
+    }
 }
 
 machine::machine(const machine_config &c, const machine_runtime_config &r) : m_c{c}, m_uarch{c.uarch}, m_r{r} {
@@ -511,24 +536,16 @@ machine::machine(const machine_config &c, const machine_runtime_config &r) : m_c
     // Last, add sentinel PMA
     m_merkle_pmas.push_back(&m_s.empty_pma);
 
-    // Initialize TLB device
-    // this must be done after all PMA entries are already registered, so we can lookup page addresses
+    // Initialize TLB device.
+    // This must be done after all PMA entries are already registered, so we can lookup page addresses
     if (!m_c.tlb.image_filename.empty()) {
-        // Create a temporary PMA entry just to load TLB contents from an image file
-        pma_entry tlb_image_pma = make_mmapd_memory_pma_entry("shadow TLB device"s, PMA_SHADOW_TLB_START,
-            PMA_SHADOW_TLB_LENGTH, m_c.tlb.image_filename, false);
-        unsigned char *hmem = tlb_image_pma.get_memory().get_host_memory();
-        for (uint64_t i = 0; i < PMA_TLB_SIZE; ++i) {
-            load_tlb_entry<TLB_CODE>(*this, i, hmem);
-            load_tlb_entry<TLB_READ>(*this, i, hmem);
-            load_tlb_entry<TLB_WRITE>(*this, i, hmem);
-        }
+        unsigned char *buf = os_map_file(m_c.tlb.image_filename.c_str(), PMA_SHADOW_TLB_LENGTH, false);
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        const auto &shadow_tlb = *reinterpret_cast<const shadow_tlb_state *>(buf);
+        init_tlb(shadow_tlb);
+        os_unmap_file(buf, PMA_SHADOW_TLB_LENGTH);
     } else {
-        for (uint64_t i = 0; i < PMA_TLB_SIZE; ++i) {
-            init_tlb_entry<TLB_CODE>(*this, i);
-            init_tlb_entry<TLB_READ>(*this, i);
-            init_tlb_entry<TLB_WRITE>(*this, i);
-        }
+        init_tlb();
     }
 
     // Initialize TTY if console input is enabled
@@ -769,6 +786,33 @@ pma_entry &machine::find_pma_entry(const CONTAINER &pmas, uint64_t paddr, uint64
     return const_cast<pma_entry &>(std::as_const(*this).find_pma_entry(pmas, paddr, length));
 }
 
+uint64_t machine::get_paddr(host_addr haddr, uint64_t pma_index) const {
+    return static_cast<uint64_t>(haddr + get_hp_offset(pma_index));
+}
+
+host_addr machine::get_host_addr(uint64_t paddr, uint64_t pma_index) const {
+    return host_addr{paddr} - get_hp_offset(pma_index);
+}
+
+void machine::mark_dirty_page(host_addr haddr, uint64_t pma_index) {
+    auto paddr = get_paddr(haddr, pma_index);
+    auto &pma = m_s.pmas[static_cast<int>(pma_index)];
+    pma.mark_dirty_page(paddr - pma.get_start());
+}
+
+host_addr machine::get_hp_offset(uint64_t pma_index) const {
+    if (pma_index >= m_s.pmas.size()) {
+        throw std::domain_error{"PMA is out of range"};
+    }
+    const auto &pma = m_s.pmas[static_cast<int>(pma_index)];
+    if (!pma.get_istart_M()) {
+        throw std::domain_error{"PMA is not memory"};
+    }
+    auto haddr = cast_ptr_to_host_addr(pma.get_memory().get_host_memory());
+    auto paddr = pma.get_start();
+    return paddr - haddr;
+}
+
 template <typename CONTAINER>
 const pma_entry &machine::find_pma_entry(const CONTAINER &pmas, uint64_t paddr, uint64_t length) const {
     for (const auto &p : pmas) {
@@ -1663,18 +1707,22 @@ uint64_t machine::get_reg_address(reg r) {
 }
 
 void machine::mark_write_tlb_dirty_pages() const {
-    for (uint64_t i = 0; i < PMA_TLB_SIZE; ++i) {
-        const tlb_hot_entry &tlbhe = m_s.tlb.hot[TLB_WRITE][i];
-        if (tlbhe.vaddr_page != TLB_INVALID_PAGE) {
-            const tlb_cold_entry &tlbce = m_s.tlb.cold[TLB_WRITE][i];
-            if (tlbce.pma_index >= m_s.pmas.size()) {
+    auto &hot_set = m_s.tlb.hot[TLB_WRITE];
+    auto &cold_set = m_s.tlb.cold[TLB_WRITE];
+    for (uint64_t slot_index = 0; slot_index < PMA_TLB_SIZE; ++slot_index) {
+        const auto &hot_slot = hot_set[slot_index];
+        if (hot_slot.vaddr_page != TLB_INVALID_PAGE) {
+            auto haddr_page = hot_slot.vaddr_page + hot_slot.vh_offset;
+            const auto &cold_slot = cold_set[slot_index];
+            if (cold_slot.pma_index >= m_s.pmas.size()) {
                 throw std::runtime_error{"could not mark dirty page for a TLB entry: TLB is corrupt"};
             }
-            pma_entry &pma = m_s.pmas[tlbce.pma_index];
-            if (!pma.contains(tlbce.paddr_page, PMA_PAGE_SIZE)) {
+            auto paddr_page = get_paddr(haddr_page, cold_slot.pma_index);
+            pma_entry &pma = m_s.pmas[cold_slot.pma_index];
+            if (!pma.contains(paddr_page, PMA_PAGE_SIZE)) {
                 throw std::runtime_error{"could not mark dirty page for a TLB entry: TLB is corrupt"};
             }
-            pma.mark_dirty_page(tlbce.paddr_page - pma.get_start());
+            pma.mark_dirty_page(paddr_page - pma.get_start());
         }
     }
 }
@@ -2137,11 +2185,14 @@ void machine::verify_send_cmio_response(uint16_t reason, const unsigned char *da
 }
 
 void machine::reset_uarch() {
+#if OKUARCH
     uarch_state_access a(m_uarch.get_state(), get_state());
     uarch_reset_state(a);
+#endif
 }
 
 access_log machine::log_reset_uarch(const access_log::type &log_type) {
+#if OKUARCH
     hash_type root_hash_before;
     get_root_hash(root_hash_before);
     // Call uarch_reset_state with a uarch_record_state_access object
@@ -2155,10 +2206,13 @@ access_log machine::log_reset_uarch(const access_log::type &log_type) {
     get_root_hash(root_hash_after);
     verify_reset_uarch(root_hash_before, *a.get_log(), root_hash_after);
     return std::move(*a.get_log());
+#endif
+    return access_log{log_type};
 }
 
 void machine::verify_reset_uarch(const hash_type &root_hash_before, const access_log &log,
     const hash_type &root_hash_after) {
+#if OKUARCH
     // There must be at least one access in log
     if (log.get_accesses().empty()) {
         throw std::invalid_argument{"too few accesses in log"};
@@ -2173,12 +2227,19 @@ void machine::verify_reset_uarch(const hash_type &root_hash_before, const access
     if (obtained_root_hash != root_hash_after) {
         throw std::invalid_argument{"mismatch in root hash after replay"};
     }
+#endif
+    (void) root_hash_before;
+    (void) log;
+    (void) root_hash_after;
 }
 
 // Declaration of explicit instantiation in module uarch-step.cpp
+#if OKUARCH
 extern template UArchStepStatus uarch_step(uarch_record_state_access &a);
+#endif
 
 access_log machine::log_step_uarch(const access_log::type &log_type) {
+#if OKUARCH
     if (m_uarch.get_state().ram.get_istart_E()) {
         throw std::runtime_error("microarchitecture RAM is not present");
     }
@@ -2194,13 +2255,18 @@ access_log machine::log_step_uarch(const access_log::type &log_type) {
     get_root_hash(root_hash_after);
     verify_step_uarch(root_hash_before, *a.get_log(), root_hash_after);
     return std::move(*a.get_log());
+#endif
+    return access_log{log_type};
 }
 
 // Declaration of explicit instantiation in module uarch-step.cpp
+#if OKUARCH
 extern template UArchStepStatus uarch_step(uarch_replay_state_access &a);
+#endif
 
 void machine::verify_step_uarch(const hash_type &root_hash_before, const access_log &log,
     const hash_type &root_hash_after) {
+#if OKUARCH
     // There must be at least one access in log
     if (log.get_accesses().empty()) {
         throw std::invalid_argument{"too few accesses in log"};
@@ -2215,6 +2281,10 @@ void machine::verify_step_uarch(const hash_type &root_hash_before, const access_
     if (obtained_root_hash != root_hash_after) {
         throw std::invalid_argument{"mismatch in root hash after replay"};
     }
+#endif
+    (void) root_hash_before;
+    (void) log;
+    (void) root_hash_after;
 }
 
 machine_config machine::get_default_config() {
@@ -2223,6 +2293,7 @@ machine_config machine::get_default_config() {
 
 // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
 uarch_interpreter_break_reason machine::run_uarch(uint64_t uarch_cycle_end) {
+#if OKUARCH
     if (read_reg(reg::iunrep) != 0) {
         throw std::runtime_error("microarchitecture cannot be used with unreproducible machines");
     }
@@ -2231,6 +2302,9 @@ uarch_interpreter_break_reason machine::run_uarch(uint64_t uarch_cycle_end) {
     }
     uarch_state_access a(m_uarch.get_state(), get_state());
     return uarch_interpret(a, uarch_cycle_end);
+#endif
+    (void) uarch_cycle_end;
+    return uarch_interpreter_break_reason::uarch_halted;
 }
 
 interpreter_break_reason machine::log_step(uint64_t mcycle_count, const std::string &filename) {
diff --git a/src/machine.h b/src/machine.h
index c7bb5f705..07ea6e104 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -28,6 +28,7 @@
 #include <boost/container/static_vector.hpp>
 
 #include "access-log.h"
+#include "host-addr.h"
 #include "i-device-state-access.h"
 #include "interpret.h"
 #include "machine-config.h"
@@ -125,6 +126,17 @@ class machine final {
     template <typename CONTAINER>
     const pma_entry &find_pma_entry(const CONTAINER &pmas, uint64_t paddr, uint64_t length) const;
 
+    /// \brief Returns offset that converts between machine host addresses and target physical addresses
+    /// \param pma_index Index of the memory PMA for the desired offset
+    host_addr get_hp_offset(uint64_t pma_index) const;
+
+    /// \brief Initializes machine TLB from scratch
+    void init_tlb();
+
+    /// \brief Initializes machine TLB from shadow tlb
+    /// \param shadow_tlb Shadow TLB loaded from disk
+    void init_tlb(const shadow_tlb_state &shadow_tlb);
+
 public:
     /// \brief Type of hash
     using hash_type = machine_merkle_tree::hash_type;
@@ -430,6 +442,25 @@ class machine final {
     /// \param length Length of response data.
     void send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length);
 
+    /// \brief Converts from machine host address to target physical address
+    /// \param haddr Machine host address to convert
+    /// \param pma_index Index of PMA where address falls
+    /// \returns Corresponding target physical address
+    /// \details This method also converts from vh_offset to vp_offset
+    uint64_t get_paddr(host_addr haddr, uint64_t pma_index) const;
+
+    /// \brief Converts from target physical address to machine host address
+    /// \param paddr Target physical address to convert
+    /// \param pma_index Index of PMA where address falls
+    /// \returns Corresponding machine host address
+    /// \details This method also converts from vp_offset to vh_offset
+    host_addr get_host_addr(uint64_t paddr, uint64_t pma_index) const;
+
+    /// \brief Marks a page as dirty
+    /// \param haddr Machine host address within page
+    /// \param pma_index Index of PMA where address falls
+    void mark_dirty_page(host_addr haddr, uint64_t pma_index);
+
     /// \brief Sends cmio response and returns an access log
     /// \param reason Reason for sending response.
     /// \param data Response data.
diff --git a/src/pma.h b/src/pma.h
index 7c2ae90aa..69d53d035 100644
--- a/src/pma.h
+++ b/src/pma.h
@@ -342,6 +342,11 @@ class pma_entry final {
         return *std::get_if<pma_memory>(&m_data);
     }
 
+    /// \returns data specific to IO ranges (cannot throw exceptions).
+    const pma_memory &get_memory_noexcept() const {
+        return *std::get_if<pma_memory>(&m_data);
+    }
+
     /// \returns data specific to IO ranges
     const pma_device &get_device() const {
         return std::get<pma_device>(m_data);
@@ -352,6 +357,11 @@ class pma_entry final {
         return std::get<pma_device>(m_data);
     }
 
+    /// \returns data specific to IO ranges (cannot throw exceptions).
+    const pma_device &get_device_noexcept() const {
+        return *std::get_if<pma_device>(&m_data);
+    }
+
     /// \returns data specific to IO ranges (cannot throw exceptions).
     pma_device &get_device_noexcept() {
         return *std::get_if<pma_device>(&m_data);
diff --git a/src/record-send-cmio-state-access.h b/src/record-send-cmio-state-access.h
index c7f66cd76..3c595e53a 100644
--- a/src/record-send-cmio-state-access.h
+++ b/src/record-send-cmio-state-access.h
@@ -27,6 +27,7 @@
 #include <utility>
 
 #include "access-log.h"
+#include "host-addr.h"
 #include "i-hasher.h"
 #include "i-state-access.h"
 #include "machine-merkle-tree.h"
@@ -38,10 +39,23 @@
 
 namespace cartesi {
 
+class record_send_cmio_state_access;
+
+// Type trait that should return the pma_entry type for a state access class
+template <>
+struct i_state_access_pma_entry<record_send_cmio_state_access> {
+    using type = pma_entry;
+};
+// Type trait that should return the fast_addr type for a state access class
+template <>
+struct i_state_access_fast_addr<record_send_cmio_state_access> {
+    using type = host_addr;
+};
+
 /// \class record_send_cmio_state_access
 /// \details This records all state accesses that happen during the execution of
 /// a machine::send_cmio_response() function call
-class record_send_cmio_state_access : public i_state_access<record_send_cmio_state_access, pma_entry> {
+class record_send_cmio_state_access : public i_state_access<record_send_cmio_state_access> {
     using hasher_type = machine_merkle_tree::hasher_type;
     using hash_type = machine_merkle_tree::hash_type;
     // NOLINTBEGIN(cppcoreguidelines-avoid-const-or-ref-data-members)
@@ -63,6 +77,8 @@ class record_send_cmio_state_access : public i_state_access<record_send_cmio_sta
     }
 
 private:
+    friend i_state_access<record_send_cmio_state_access>;
+
     /// \brief Logs a read access of a uint64_t word from the machine state.
     /// \param paligned Physical address in the machine state, aligned to a 64-bit word.
     /// \param text Textual description of the access.
@@ -168,9 +184,6 @@ class record_send_cmio_state_access : public i_state_access<record_send_cmio_sta
         update_after_write(paligned);
     }
 
-    // Declare interface as friend to it can forward calls to the "overridden" methods.
-    friend i_state_access<record_send_cmio_state_access, pma_entry>;
-
     void do_push_bracket(bracket_type &type, const char *text) {
         m_log.push_bracket(type, text);
     }
diff --git a/src/record-step-state-access.h b/src/record-step-state-access.h
index a54cc2555..8c94c439f 100644
--- a/src/record-step-state-access.h
+++ b/src/record-step-state-access.h
@@ -23,6 +23,7 @@
 #include "device-state-access.h"
 #include "i-state-access.h"
 #include "shadow-pmas.h"
+#include "shadow-tlb.h"
 #include "unique-c-ptr.h"
 #include <map>
 #include <optional>
@@ -30,13 +31,25 @@
 
 namespace cartesi {
 
+class record_step_state_access;
+
+// Type trait that should return the pma_entry type for a state access class
+template <>
+struct i_state_access_pma_entry<record_step_state_access> {
+    using type = pma_entry;
+};
+// Type trait that should return the fast_addr type for a state access class
+template <>
+struct i_state_access_fast_addr<record_step_state_access> {
+    using type = host_addr;
+};
+
 /// \class record_step_state_access
 /// \brief Records machine state access into a step log file
-class record_step_state_access : public i_state_access<record_step_state_access, pma_entry> {
-public:
+class record_step_state_access : public i_state_access<record_step_state_access> {
     constexpr static int TREE_LOG2_ROOT_SIZE = machine_merkle_tree::get_log2_root_size();
     constexpr static int TREE_LOG2_PAGE_SIZE = machine_merkle_tree::get_log2_page_size();
-    constexpr static uint64_t TREE_PAGE_SIZE = UINT64_C(1) << TREE_LOG2_PAGE_SIZE;
+    constexpr static uint64_t TREE_PAGE_SIZE = UINT64_C(1) << LOG2_PAGE_SIZE;
 
     using address_type = machine_merkle_tree::address_type;
     using page_data_type = std::array<uint8_t, TREE_PAGE_SIZE>;
@@ -45,6 +58,8 @@ class record_step_state_access : public i_state_access<record_step_state_access,
     using sibling_hashes_type = std::vector<hash_type>;
     using page_indices_type = std::vector<address_type>;
 
+public:
+
     struct context {
         /// \brief Constructor of record step state access context
         /// \param filename where to save the log
@@ -113,12 +128,14 @@ class record_step_state_access : public i_state_access<record_step_state_access,
     }
 
 private:
-    friend i_state_access<record_step_state_access, pma_entry>;
+    using pma_entry_type = pma_entry;
+    using fast_addr_type = host_addr;
+    friend i_state_access<record_step_state_access>;
 
     /// \brief Mark a page as touched and save its contents
     /// \param address address of the page
     void touch_page(address_type address) const {
-        auto page = address & ~(TREE_PAGE_SIZE - 1);
+        auto page = address & ~PAGE_OFFSET_MASK;
         if (m_context.touched_pages.find(page) != m_context.touched_pages.end()) {
             return; // already saved
         }
@@ -590,180 +607,115 @@ class record_step_state_access : public i_state_access<record_step_state_access,
         return m_m.get_state().htif.iyield;
     }
 
-    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    NO_INLINE std::pair<uint64_t, bool> do_poll_external_interrupts(uint64_t mcycle, uint64_t mcycle_max) {
-        (void) mcycle_max;
-        return {mcycle, false};
-    }
-
-    template <typename T>
-    void do_read_memory_word(uint64_t paddr, const unsigned char *hpage, uint64_t hoffset, T *pval) const {
-        (void) paddr;
-        touch_page(paddr);
-        *pval = cartesi::aliased_aligned_read<T>(hpage + hoffset);
-    }
-
-    template <typename T>
-    void do_write_memory_word(uint64_t paddr, unsigned char *hpage, uint64_t hoffset, T val) {
-        (void) paddr;
-        touch_page(paddr);
-        aliased_aligned_write(hpage + hoffset, val);
-    }
-
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
     bool do_read_memory(uint64_t paddr, const unsigned char *data, uint64_t length) const {
         (void) paddr;
         (void) data;
         (void) length;
-        throw std::runtime_error("Unexpected call to do_read_memory");
+        throw std::runtime_error("unexpected call to record_step_state_access::read_memory");
     }
 
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
     bool do_write_memory(uint64_t paddr, const unsigned char *data, uint64_t length) {
-
         (void) paddr;
         (void) data;
         (void) length;
-        throw std::runtime_error("Unexpected call to do_write_memory");
-    }
-
-    static unsigned char *do_get_host_memory(pma_entry &pma) {
-        return pma.get_memory_noexcept().get_host_memory();
+        throw std::runtime_error("unexpected call to record_step_state_access::write_memory");
     }
 
     pma_entry &do_read_pma_entry(uint64_t index) {
         assert(index < PMA_MAX);
-        touch_page(shadow_pmas_get_pma_abs_addr(index));
-        return m_m.get_state().pmas[index];
-    }
-
-    template <TLB_entry_type ETYPE, typename T>
-    bool do_translate_vaddr_via_tlb(uint64_t vaddr, unsigned char **phptr) {
-        const uint64_t eidx = tlb_get_entry_index(vaddr);
-        touch_page(tlb_get_entry_hot_abs_addr<ETYPE>(eidx));
-        touch_page(tlb_get_entry_cold_abs_addr<ETYPE>(eidx));
-        const tlb_hot_entry &tlbhe = m_m.get_state().tlb.hot[ETYPE][eidx];
-        if (unlikely(!tlb_is_hit<T>(tlbhe.vaddr_page, vaddr))) {
-            return false;
+        // replay_step_state_access reconstructs a mock_pma_entry from the
+        // corresponding istart and ilength fields in the shadow pmas
+        // so we mark the page where they live here
+        touch_page(shadow_pmas_get_pma_istart_abs_addr(index));
+        touch_page(shadow_pmas_get_pma_ilength_abs_addr(index));
+        // NOLINTNEXTLINE(bugprone-narrowing-conversions)
+        return m_m.get_state().pmas[static_cast<int>(index)];
+    }
+
+    template <typename T, typename A>
+    void do_read_memory_word(host_addr haddr, uint64_t pma_index, T *pval) {
+        touch_page(m_m.get_paddr(haddr, pma_index));
+        *pval = aliased_aligned_read<T, A>(haddr);
+    }
+
+    template <typename T, typename A>
+    void do_write_memory_word(host_addr haddr, uint64_t pma_index, T val) {
+        touch_page(m_m.get_paddr(haddr, pma_index));
+        aliased_aligned_write<T, A>(haddr, val);
+    }
+
+    template <TLB_set_use USE>
+    uint64_t do_read_tlb_vaddr_page(uint64_t slot_index) {
+        touch_page(shadow_tlb_get_vaddr_page_abs_addr<USE>(slot_index));
+        return m_m.get_state().tlb.hot[USE][slot_index].vaddr_page;
+    }
+
+    template <TLB_set_use USE>
+    host_addr do_read_tlb_vp_offset(uint64_t slot_index) {
+        // During initialization, replay_step_state_access translates all vp_offset to corresponding vh_offset
+        // At deinitialization, it translates them back
+        // To do that, it needs the corresponding paddr_page = vaddr_page + vp_offset, and page data itself
+        // It will only do the translation if the slot is valid and it has access to all required fields
+        // Obviously, the slot we are reading will be needed during replay, so we touch all the pages involved here.
+        touch_page(shadow_tlb_get_vaddr_page_abs_addr<USE>(slot_index));
+        touch_page(shadow_tlb_get_vp_offset_abs_addr<USE>(slot_index));
+        touch_page(shadow_tlb_get_pma_index_abs_addr<USE>(slot_index));
+        // writes to the TLB slot are atomic, so we know the values in a slot are ALWAYS internally consistent
+        const auto vaddr_page = m_m.get_state().tlb.hot[USE][slot_index].vaddr_page;
+        const auto vh_offset = m_m.get_state().tlb.hot[USE][slot_index].vh_offset;
+        if (vaddr_page != TLB_INVALID_PAGE) {
+            const auto pma_index = m_m.get_state().tlb.cold[USE][slot_index].pma_index;
+            const auto haddr_page = vaddr_page + vh_offset;
+            auto paddr_page = m_m.get_paddr(haddr_page, pma_index);
+            touch_page(paddr_page);
         }
-        *phptr = cast_addr_to_ptr<unsigned char *>(tlbhe.vh_offset + vaddr);
-        const tlb_cold_entry &tlbce = m_m.get_state().tlb.cold[ETYPE][eidx];
-        touch_page(tlbce.paddr_page);
-        return true;
-    }
-
-    template <TLB_entry_type ETYPE, typename T>
-    bool do_read_memory_word_via_tlb(uint64_t vaddr, T *pval) {
-        const uint64_t eidx = tlb_get_entry_index(vaddr);
-        const tlb_hot_entry &tlbhe = m_m.get_state().tlb.hot[ETYPE][eidx];
-        const tlb_cold_entry &tlbce = m_m.get_state().tlb.cold[ETYPE][eidx];
-        touch_page(tlb_get_entry_hot_abs_addr<ETYPE>(eidx));
-        touch_page(tlb_get_entry_cold_abs_addr<ETYPE>(
-            eidx)); // save cold entry to allow reconstruction of paddr during playback
-        if (unlikely(!tlb_is_hit<T>(tlbhe.vaddr_page, vaddr))) {
-            return false;
+        return vh_offset;
+    }
+
+    template <TLB_set_use USE>
+    uint64_t do_read_tlb_pma_index(uint64_t slot_index) {
+        touch_page(shadow_tlb_get_pma_index_abs_addr<USE>(slot_index));
+        return m_m.get_state().tlb.cold[USE][slot_index].pma_index;
+    }
+
+    template <TLB_set_use USE>
+    void do_write_tlb(uint64_t slot_index, uint64_t vaddr_page, host_addr vh_offset, uint64_t pma_index) {
+        // During initialization, replay_step_state_access translates all vp_offset to corresponding vh_offset
+        // At deinitialization, it translates them back
+        // To do that, it needs the corresponding paddr_page = vaddr_page + vp_offset, and page data itself
+        // It will only do the translation if the slot is valid and it has access to all required fields
+        // Obviously, the slot we are modifying will be needed during replay, so we touch all the pages involved here.
+        touch_page(shadow_tlb_get_vaddr_page_abs_addr<USE>(slot_index));
+        touch_page(shadow_tlb_get_vp_offset_abs_addr<USE>(slot_index));
+        touch_page(shadow_tlb_get_pma_index_abs_addr<USE>(slot_index));
+        m_m.get_state().tlb.hot[USE][slot_index].vaddr_page = vaddr_page;
+        m_m.get_state().tlb.hot[USE][slot_index].vh_offset = vh_offset;
+        m_m.get_state().tlb.cold[USE][slot_index].pma_index = pma_index;
+        if (vaddr_page != TLB_INVALID_PAGE) {
+            const auto haddr_page = vaddr_page + vh_offset;
+            auto paddr_page = m_m.get_paddr(haddr_page, pma_index);
+            touch_page(paddr_page);
         }
-        const auto *h = cast_addr_to_ptr<const unsigned char *>(tlbhe.vh_offset + vaddr);
-        *pval = cartesi::aliased_aligned_read<T>(h);
-        touch_page(tlbce.paddr_page);
-
-        return true;
     }
 
-    template <TLB_entry_type ETYPE, typename T>
-    bool do_write_memory_word_via_tlb(uint64_t vaddr, T val) {
-        const uint64_t eidx = tlb_get_entry_index(vaddr);
-        const tlb_hot_entry &tlbhe = m_m.get_state().tlb.hot[ETYPE][eidx];
-        touch_page(tlb_get_entry_hot_abs_addr<ETYPE>(eidx));
-        touch_page(tlb_get_entry_cold_abs_addr<ETYPE>(eidx));
-        if (unlikely(!tlb_is_hit<T>(tlbhe.vaddr_page, vaddr))) {
-            return false;
-        }
-        touch_page(tlb_get_entry_cold_abs_addr<ETYPE>(
-            eidx)); // save cold entry to allow reconstruction of paddr during playback
-        const tlb_cold_entry &tlbce = m_m.get_state().tlb.cold[ETYPE][eidx];
-        touch_page(tlbce.paddr_page);
-
-        auto *h = cast_addr_to_ptr<unsigned char *>(tlbhe.vh_offset + vaddr);
-        aliased_aligned_write(h, val);
-        return true;
-    }
-
-    template <TLB_entry_type ETYPE>
-    unsigned char *do_replace_tlb_entry(uint64_t vaddr, uint64_t paddr, pma_entry &pma) {
-        const uint64_t eidx = tlb_get_entry_index(vaddr);
-        touch_page(tlb_get_entry_hot_abs_addr<ETYPE>(eidx));
-        touch_page(tlb_get_entry_cold_abs_addr<ETYPE>(
-            eidx)); // save cold entry to allow reconstruction of paddr during playback
-        tlb_hot_entry &tlbhe = m_m.get_state().tlb.hot[ETYPE][eidx];
-        tlb_cold_entry &tlbce = m_m.get_state().tlb.cold[ETYPE][eidx];
-        // Mark page that was on TLB as dirty so we know to update the Merkle tree
-        if constexpr (ETYPE == TLB_WRITE) {
-            if (tlbhe.vaddr_page != TLB_INVALID_PAGE) {
-                pma_entry &pma = do_read_pma_entry(tlbce.pma_index);
-                pma.mark_dirty_page(tlbce.paddr_page - pma.get_start());
-            }
-        }
-        const uint64_t vaddr_page = vaddr & ~PAGE_OFFSET_MASK;
-        const uint64_t paddr_page = paddr & ~PAGE_OFFSET_MASK;
-        unsigned char *hpage = pma.get_memory_noexcept().get_host_memory() + (paddr_page - pma.get_start());
-        tlbhe.vaddr_page = vaddr_page;
-        tlbhe.vh_offset = cast_ptr_to_addr<uint64_t>(hpage) - vaddr_page;
-        tlbce.paddr_page = paddr_page;
-        tlbce.pma_index = static_cast<uint64_t>(pma.get_index());
-        touch_page(tlbce.paddr_page);
-        return hpage;
-    }
-
-    template <TLB_entry_type ETYPE>
-    void do_flush_tlb_entry(uint64_t eidx) {
-        touch_page(tlb_get_entry_hot_abs_addr<ETYPE>(eidx));
-        touch_page(tlb_get_entry_cold_abs_addr<ETYPE>(
-            eidx)); // save cold entry to allow reconstruction of paddr during playback
-        tlb_hot_entry &tlbhe = m_m.get_state().tlb.hot[ETYPE][eidx];
-        // Mark page that was on TLB as dirty so we know to update the Merkle tree
-        if constexpr (ETYPE == TLB_WRITE) {
-            if (tlbhe.vaddr_page != TLB_INVALID_PAGE) {
-                tlbhe.vaddr_page = TLB_INVALID_PAGE;
-                const tlb_cold_entry &tlbce = m_m.get_state().tlb.cold[ETYPE][eidx];
-                pma_entry &pma = do_read_pma_entry(tlbce.pma_index);
-                pma.mark_dirty_page(tlbce.paddr_page - pma.get_start());
-            } else {
-                tlbhe.vaddr_page = TLB_INVALID_PAGE;
-            }
-        } else {
-            tlbhe.vaddr_page = TLB_INVALID_PAGE;
-        }
-    }
-
-    template <TLB_entry_type ETYPE>
-    void do_flush_tlb_type() {
-        for (uint64_t i = 0; i < PMA_TLB_SIZE; ++i) {
-            do_flush_tlb_entry<ETYPE>(i);
-        }
-    }
-
-    void do_flush_tlb_vaddr(uint64_t vaddr) {
-        (void) vaddr;
-        // We can't flush just one TLB entry for that specific virtual address,
-        // because megapages/gigapages may be in use while this TLB implementation ignores it,
-        // so we have to flush all addresses.
-        do_flush_tlb_type<TLB_CODE>();
-        do_flush_tlb_type<TLB_READ>();
-        do_flush_tlb_type<TLB_WRITE>();
+    fast_addr do_get_faddr(uint64_t paddr, uint64_t pma_index) const {
+        // replay_step_state_access needs the corresponding page to perform a
+        // translation between paddr and its own haddr, so we touch the page here
+        touch_page(paddr);
+        return m_m.get_host_addr(paddr, pma_index);
     }
 
-    bool do_get_soft_yield() {
-        return m_m.get_state().soft_yield;
+    void do_mark_dirty_page(host_addr haddr, uint64_t pma_index) {
+        // this is a noop in replay_step_state_access, so we do nothing else
+        m_m.mark_dirty_page(haddr, pma_index);
     }
 
     void do_putchar(uint8_t c) { // NOLINT(readability-convert-member-functions-to-static)
         os_putchar(c);
     }
 
-    int do_getchar() { // NOLINT(readability-convert-member-functions-to-static)
-        return -1;
-    }
 };
 
 } // namespace cartesi
diff --git a/src/replay-send-cmio-state-access.h b/src/replay-send-cmio-state-access.h
index 29242b308..155c3a909 100644
--- a/src/replay-send-cmio-state-access.h
+++ b/src/replay-send-cmio-state-access.h
@@ -34,21 +34,35 @@
 #include "i-state-access.h"
 #include "machine-merkle-tree.h"
 #include "meta.h"
-#include "pma.h"
+#include "mock-pma-entry.h"
 #include "riscv-constants.h"
 #include "shadow-state.h"
 #include "unique-c-ptr.h"
 
 namespace cartesi {
 
+class replay_send_cmio_state_access;
+
+// Type trait that should return the pma_entry type for a state access class
+template <>
+struct i_state_access_pma_entry<replay_send_cmio_state_access> {
+    using type = mock_pma_entry;
+};
+// Type trait that should return the fast_addr type for a state access class
+template <>
+struct i_state_access_fast_addr<replay_send_cmio_state_access> {
+    using type = uint64_t;
+};
+
 /// \brief Allows replaying a machine::send_cmio_response() from an access log.
-class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_state_access, pma_entry> {
-public:
+class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_state_access> {
     using tree_type = machine_merkle_tree;
     using hash_type = tree_type::hash_type;
     using hasher_type = tree_type::hasher_type;
     using proof_type = tree_type::proof_type;
 
+public:
+
     struct context {
         /// \brief Constructor replay_send_cmio_state_access context
         /// \param log Access log to be replayed
@@ -91,7 +105,7 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
     }
 
 private:
-    friend i_state_access<replay_send_cmio_state_access, pma_entry>;
+    friend i_state_access<replay_send_cmio_state_access>;
 
     std::string access_to_report() const {
         auto index = m_context.next_access + 1;
diff --git a/src/replay-step-state-access.h b/src/replay-step-state-access.h
index d219a0c4c..0d757ac41 100644
--- a/src/replay-step-state-access.h
+++ b/src/replay-step-state-access.h
@@ -22,6 +22,7 @@
 
 #include "compiler-defines.h"
 #include "device-state-access.h"
+#include "host-addr.h"
 #include "i-state-access.h"
 #include "mock-pma-entry.h"
 #include "pma-constants.h"
@@ -40,6 +41,19 @@ namespace cartesi {
 // \file this code is designed to be compiled for a free-standing environment.
 // Environment-specific functions have the prefix "interop_" and are declared in "replay-step-state-access-interop.h"
 
+class replay_step_state_access;
+
+// Type trait that should return the pma_entry type for a state access class
+template <>
+struct i_state_access_pma_entry<replay_step_state_access> {
+    using type = mock_pma_entry;
+};
+// Type trait that should return the fast_addr type for a state access class
+template <>
+struct i_state_access_fast_addr<replay_step_state_access> {
+    using type = host_addr;
+};
+
 // \brief checks if a buffer is large enough to hold a data block of N elements of size S starting at a given offset
 // \param max The maximum offset allowed
 // \param current The current offset
@@ -59,13 +73,8 @@ static inline bool validate_and_advance_offset(uint64_t max, uint64_t current, u
     return *next <= max;
 }
 
-static_assert(sizeof(shadow_tlb_state::hot[0]) == PMA_PAGE_SIZE, "size of hot tlb cache must be PM_PAGE_SIZE bytes");
-static_assert(sizeof(shadow_tlb_state::cold[0]) == PMA_PAGE_SIZE, "size of cold tlb cache must be PM_PAGE_SIZE bytes");
-static_assert(sizeof(shadow_tlb_state::hot) + sizeof(shadow_tlb_state::cold) == sizeof(shadow_tlb_state),
-    "size of shadow tlb state");
-
 // \brief Provides machine state from a step log file
-class replay_step_state_access : public i_state_access<replay_step_state_access, mock_pma_entry> {
+class replay_step_state_access : public i_state_access<replay_step_state_access> {
 public:
     using address_type = uint64_t;
     using data_type = unsigned char[PMA_PAGE_SIZE];
@@ -101,15 +110,10 @@ class replay_step_state_access : public i_state_access<replay_step_state_access,
         m_context(context) {
         // relevant offsets in the log data
         uint64_t first_page_offset{};
-        uint64_t first_siblng_offset{};
+        uint64_t first_sibling_offset{};
         uint64_t sibling_count_offset{};
         uint64_t end_offset{}; // end of the log data
 
-        // ensure that log_step + size does not overflow
-        if (__builtin_add_overflow(cast_ptr_to_addr<uint64_t>(log_image), log_size, &end_offset)) {
-            interop_throw_runtime_error("step log size overflow");
-        }
-
         // set page count
         if (!validate_and_advance_offset(log_size, 0, sizeof(m_context.page_count), 1, &first_page_offset)) {
             interop_throw_runtime_error("page count past end of step log");
@@ -129,18 +133,18 @@ class replay_step_state_access : public i_state_access<replay_step_state_access,
 
         // set sibling count and hashes
         if (!validate_and_advance_offset(log_size, sibling_count_offset, sizeof(m_context.sibling_count), 1,
-                &first_siblng_offset)) {
+                &first_sibling_offset)) {
             interop_throw_runtime_error("sibling count past end of step log");
         }
         memcpy(&m_context.sibling_count, log_image + sibling_count_offset, sizeof(m_context.sibling_count));
 
         // set sibling hashes
-        if (!validate_and_advance_offset(log_size, first_siblng_offset, sizeof(hash_type), m_context.sibling_count,
+        if (!validate_and_advance_offset(log_size, first_sibling_offset, sizeof(hash_type), m_context.sibling_count,
                 &end_offset)) {
             interop_throw_runtime_error("sibling hashes past end of step log");
         }
         // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        m_context.sibling_hashes = reinterpret_cast<hash_type *>(log_image + first_siblng_offset);
+        m_context.sibling_hashes = reinterpret_cast<hash_type *>(log_image + first_sibling_offset);
 
         // ensure that we read exactly the expected log size
         if (end_offset != log_size) {
@@ -165,9 +169,9 @@ class replay_step_state_access : public i_state_access<replay_step_state_access,
             interop_throw_runtime_error("initial root hash mismatch");
         }
         // relocate all tlb vh offsets into the logged page data
-        relocate_all_tlb_vh_offset<TLB_CODE>();
-        relocate_all_tlb_vh_offset<TLB_READ>();
-        relocate_all_tlb_vh_offset<TLB_WRITE>();
+        relocate_tlb_vp_offset_to_vh_offset<TLB_CODE>();
+        relocate_tlb_vp_offset_to_vh_offset<TLB_READ>();
+        relocate_tlb_vp_offset_to_vh_offset<TLB_WRITE>();
     }
 
     // \brief Finish the replay and check the final machine root hash
@@ -176,9 +180,9 @@ class replay_step_state_access : public i_state_access<replay_step_state_access,
     void finish(const hash_type &root_hash_after) {
         // reset all tlb vh offsets to zero
         // this is to mimic peek behavior of tlb pma device
-        reset_all_tlb_vh_offset<TLB_CODE>();
-        reset_all_tlb_vh_offset<TLB_READ>();
-        reset_all_tlb_vh_offset<TLB_WRITE>();
+        relocate_tlb_vh_offset_to_vp_offset<TLB_CODE>();
+        relocate_tlb_vh_offset_to_vp_offset<TLB_READ>();
+        relocate_tlb_vh_offset_to_vp_offset<TLB_WRITE>();
         // compute and check machine root hash after the replay
         auto computed_final_root_hash = compute_root_hash();
         if (computed_final_root_hash != root_hash_after) {
@@ -187,72 +191,42 @@ class replay_step_state_access : public i_state_access<replay_step_state_access,
     }
 
 private:
-    friend i_state_access<replay_step_state_access, mock_pma_entry>;
+    friend i_state_access<replay_step_state_access>;
 
-    // \brief Relocate all TLB virtual to host offsets
-    // \details Points the vh_offset relative to the logged page data
-    template <TLB_entry_type ETYPE>
-    void relocate_all_tlb_vh_offset() {
-        // NOLINTBEGIN(cppcoreguidelines-pro-type-reinterpret-cast))
-        for (size_t i = 0; i < PMA_TLB_SIZE; ++i) {
-            const auto he_address = tlb_get_entry_hot_abs_addr<ETYPE>(i);
-            const auto he_page = he_address & ~(PMA_PAGE_SIZE - 1);
-            const auto he_offset = he_address - he_page;
-            auto *he_log = try_find_page(he_page);
-            // if the page containing the tlb hot entries is present in the log
-            if (he_log) {
-                volatile tlb_hot_entry *tlbhe = reinterpret_cast<tlb_hot_entry *>(he_log->data + he_offset);
-                if (tlbhe->vh_offset != 0) {
-                    interop_throw_runtime_error("expected vh_offset to be zero");
-                }
-                // find the logged cold entry page
-                const auto ce_addr = tlb_get_entry_cold_abs_addr<ETYPE>(i);
-                const auto ce_page = ce_addr & ~(PMA_PAGE_SIZE - 1);
-                const auto ce_offset = ce_addr - ce_page;
-                auto *ce_log = find_page(ce_page);
-                volatile tlb_cold_entry *tlbce = reinterpret_cast<tlb_cold_entry *>(ce_log->data + ce_offset);
-                // find the logged page pointed by the cold entry
-                auto *log = try_find_page(tlbce->paddr_page);
-                if (log) {
-                    // point vh_offset to the logged page data
-                    tlbhe->vh_offset = cast_ptr_to_addr<uint64_t>(log->data) - tlbhe->vaddr_page;
-                }
+    /// \brief Try to find a page in the logged data by its physical address
+    /// \param paddr The physical address of the page
+    /// \return A pointer to the page_type structure if found, nullptr otherwise
+    page_type *try_find_page(uint64_t paddr_page) const {
+        const auto page_index = paddr_page >> PMA_PAGE_SIZE_LOG2;
+        uint64_t min{0};
+        uint64_t max{m_context.page_count};
+        while (min < max) {
+            auto mid = (min + max) >> 1;
+            if (m_context.pages[mid].index == page_index) {
+                return &m_context.pages[mid];
             }
-        }
-        // NOLINTEND(cppcoreguidelines-pro-type-reinterpret-cast))
-    }
-
-    // \brief Reset all TLB virtual to host offsets
-    // \details Points the vh_offset to zero, replicating the behavior of the tlb pma device
-    template <TLB_entry_type ETYPE>
-    void reset_all_tlb_vh_offset() {
-        // NOLINTBEGIN(cppcoreguidelines-pro-type-reinterpret-cast))
-        for (size_t i = 0; i < PMA_TLB_SIZE; ++i) {
-            const auto addr = tlb_get_entry_hot_abs_addr<ETYPE>(i);
-            const auto page = addr & ~(PMA_PAGE_SIZE - 1);
-            const auto offset = addr - page;
-            auto *p = try_find_page(page);
-            if (p) {
-                volatile tlb_hot_entry *tlbhe = reinterpret_cast<tlb_hot_entry *>(p->data + offset);
-                tlbhe->vh_offset = 0;
+            if (m_context.pages[mid].index < page_index) {
+                min = mid + 1;
+            } else {
+                max = mid;
             }
         }
-        // NOLINTEND(cppcoreguidelines-pro-type-reinterpret-cast))
+        return nullptr;
     }
 
-    /// \brief Try to find a page in the logged data
-    /// \param address The physical address of the page
+    /// \brief Try to find a page in the logged data by the host address of its data
+    /// \param haddr Host address of page data
     /// \return A pointer to the page_type structure if found, nullptr otherwise
-    page_type *try_find_page(uint64_t address) const {
-        const auto page_index = address >> PMA_PAGE_SIZE_LOG2;
+    page_type *try_find_page(host_addr haddr_page) const {
         uint64_t min{0};
         uint64_t max{m_context.page_count};
         while (min < max) {
             auto mid = (min + max) >> 1;
-            if (m_context.pages[mid].index == page_index) {
+            auto mid_page_data = cast_ptr_to_host_addr(m_context.pages[mid].data);
+            if (mid_page_data == haddr_page) {
                 return &m_context.pages[mid];
             }
-            if (m_context.pages[mid].index < page_index) {
+            if (mid_page_data < haddr_page) {
                 min = mid + 1;
             } else {
                 max = mid;
@@ -261,63 +235,107 @@ class replay_step_state_access : public i_state_access<replay_step_state_access,
         return nullptr;
     }
 
-    /// \brief Find a page in the logged data
-    /// \param address The physical address of the page
-    /// \return A pointer to the page_type structure
-    page_type *find_page(uint64_t address) const {
-        auto *page = try_find_page(address);
-        if (page == nullptr) {
-            interop_throw_runtime_error("find_page: page not found");
+    // \brief Relocate all TLB vp_offset fields to vh_offset
+    // \details This makes the translation point directly to logged page data
+    template <TLB_set_use USE>
+    void relocate_tlb_vp_offset_to_vh_offset() {
+        for (uint64_t slot_index = 0; slot_index < TLB_SET_SIZE; ++slot_index) {
+            const auto vp_offset_field_addr = shadow_tlb_get_vp_offset_abs_addr<USE>(slot_index);
+            auto *vp_offset_log = try_find_page(vp_offset_field_addr & ~PAGE_OFFSET_MASK);
+            const auto vaddr_page_field_addr = shadow_tlb_get_vaddr_page_abs_addr<USE>(slot_index);
+            auto *vaddr_page_log = try_find_page(vaddr_page_field_addr & ~PAGE_OFFSET_MASK);
+            // If vp_offset was accessed during record, both it and vaddr_apge will appear in the log
+            // (record_step_state_access makes sure of it)
+            // Otherwise, we do not need to translate
+            if (vp_offset_log == nullptr || vaddr_page_log == nullptr) {
+                continue;
+            }
+            const auto vaddr_page_field_haddr =
+                cast_ptr_to_host_addr(vaddr_page_log->data) + (vaddr_page_field_addr & PAGE_OFFSET_MASK);
+            const auto vaddr_page = aliased_aligned_read<uint64_t>(vaddr_page_field_haddr);
+            // If, moreover, the slot was valid, the corresponding page will also appear in the log
+            // (record_step_state_access makes sure of it)
+            // Otherwise, we do not need to translate
+            if (vaddr_page != TLB_INVALID_PAGE) {
+                const auto vp_offset_field_haddr =
+                    cast_ptr_to_host_addr(vp_offset_log->data) + (vp_offset_field_addr & PAGE_OFFSET_MASK);
+                const auto vp_offset = aliased_aligned_read<uint64_t>(vp_offset_field_haddr);
+                const auto paddr_page = vaddr_page + vp_offset;
+                auto *page_log = try_find_page(paddr_page);
+                if (page_log == nullptr) {
+                    continue;
+                }
+                const auto haddr_page = cast_ptr_to_host_addr(page_log->data);
+                const auto vh_offset = haddr_page - vaddr_page;
+                aliased_aligned_write<host_addr>(vp_offset_field_haddr, vh_offset);
+            }
         }
-        return page;
     }
 
-    /// \brief Find a page in the logged data
-    /// \param address The physical address of the page
-    /// \return A pointer to the page_type structure
-    page_type *find_page(uint64_t address) {
-        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-const-cast): remove const to reuse code
-        return static_cast<const replay_step_state_access *>(this)->find_page(address);
+    // \brief Reverses changes to TLB so we have vp_offset fields again instead of vh_offset
+    // \details This makes the translation point back to target physical addresses
+    template <TLB_set_use USE>
+    void relocate_tlb_vh_offset_to_vp_offset() {
+        for (uint64_t slot_index = 0; slot_index < TLB_SET_SIZE; ++slot_index) {
+            const auto vp_offset_field_addr = shadow_tlb_get_vp_offset_abs_addr<USE>(slot_index);
+            auto *vp_offset_log = try_find_page(vp_offset_field_addr & ~PAGE_OFFSET_MASK);
+            const auto vaddr_page_field_addr = shadow_tlb_get_vaddr_page_abs_addr<USE>(slot_index);
+            auto *vaddr_page_log = try_find_page(vaddr_page_field_addr & ~PAGE_OFFSET_MASK);
+            // If vp_offset was accessed during record, both it and vaddr_apge will appear in the log
+            // (record_step_state_access makes sure of it)
+            // Otherwise, we do not need to translate
+            if (vp_offset_log == nullptr || vaddr_page_log == nullptr) {
+                continue;
+            }
+            const auto vaddr_page_field_haddr =
+                cast_ptr_to_host_addr(vaddr_page_log->data) + (vaddr_page_field_addr & PAGE_OFFSET_MASK);
+            const auto vaddr_page = aliased_aligned_read<uint64_t>(vaddr_page_field_haddr);
+            // If, moreover, the slot was valid, the corresponding page will also appear in the log
+            // (record_step_state_access makes sure of it)
+            // Otherwise, we do not need to translate
+            // We also don't need to translate back if it is no longer valid
+            if (vaddr_page != TLB_INVALID_PAGE) {
+                const auto vp_offset_field_haddr =
+                    cast_ptr_to_host_addr(vp_offset_log->data) + (vp_offset_field_addr & PAGE_OFFSET_MASK);
+                const auto vh_offset = aliased_aligned_read<host_addr>(vp_offset_field_haddr);
+                const auto haddr_page = vaddr_page + vh_offset;
+                auto *page_log = try_find_page(haddr_page);
+                if (page_log == nullptr) {
+                    continue;
+                }
+                const auto paddr_page = page_log->index << PMA_PAGE_SIZE_LOG2;
+                const auto vp_offset = paddr_page - vaddr_page;
+                aliased_aligned_write<uint64_t>(vp_offset_field_haddr, vp_offset);
+            }
+        }
     }
 
-    /// \brief Get the raw memory pointer for a given physical address
-    /// \param paddr The physical address
-    /// \param size The size of the memory region
-    /// \return A pointer to the raw memory
-    void *get_raw_memory_pointer(uint64_t paddr, size_t size) const {
-        auto page = paddr & ~(PMA_PAGE_SIZE - 1);
-        const auto offset = paddr - page;
-        auto end_page = (paddr + size - 1) & ~(PMA_PAGE_SIZE - 1);
-        if (end_page != page) {
-            interop_throw_runtime_error("get_raw_memory_pointer: paddr crosses page boundary");
+    page_type *find_page(uint64_t paddr_page) const {
+        auto *page_log = try_find_page(paddr_page);
+        if (page_log == nullptr) {
+            interop_throw_runtime_error("find_page: page not found");
         }
-        auto *data = find_page(page);
-        auto *p = data->data + offset;
-        return p;
+        return page_log;
     }
 
-    /// \brief Read a value from raw memory
-    /// \tparam T The type of the value to read
-    /// \param paddr The physical address
-    /// \return The value read
-    template <typename T>
-    T raw_read_memory(uint64_t paddr) const {
-        auto size = sizeof(T);
-        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        volatile T *ptr = reinterpret_cast<T *>(get_raw_memory_pointer(paddr, size));
-        return *ptr;
+    page_type *find_page(host_addr haddr_page) const {
+        auto *page_log = try_find_page(haddr_page);
+        if (page_log == nullptr) {
+            interop_throw_runtime_error("find_page: page not found");
+        }
+        return page_log;
     }
 
-    /// \brief Write a value to raw memory
-    /// \tparam T The type of the value to write
+    /// \brief Convert physical address to host address
     /// \param paddr The physical address
-    /// \param val The value to write
-    template <typename T>
-    void raw_write_memory(uint64_t paddr, T val) {
-        auto size = sizeof(T);
-        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        volatile T *ptr = reinterpret_cast<T *>(get_raw_memory_pointer(paddr, size));
-        *ptr = val;
+    /// \return Host address
+    host_addr do_get_faddr(uint64_t paddr, uint64_t /* pma_index */ = 0) const {
+        // This assumes the corresponding page has been touched
+        // (replay_step_state_access makes sure of it for any address we try to convert)
+        const auto paddr_page = paddr & ~PAGE_OFFSET_MASK;
+        auto *page_log = find_page(paddr_page);
+        const auto offset = paddr & PAGE_OFFSET_MASK;
+        return cast_ptr_to_host_addr(page_log->data) + offset;
     }
 
     // \brief Compute the current machine root hash
@@ -388,353 +406,417 @@ class replay_step_state_access : public i_state_access<replay_step_state_access,
         return 0;
     }
 
+    //??D we should probably optimize access to the shadow so it doesn't perform a translation every time
+    // We can do this by caching the vh_offset trasnslation of the processor shadow page. This is easy if
+    // static_assert(sizeof(shadow_state) <= PMA_PAGE_SIZE, "shadow state must fit in single page");
     uint64_t do_read_x(int reg) {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::x0, reg));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::x0, reg));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_x(int reg, uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::x0, reg), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::x0, reg));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_f(int reg) {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::f0, reg));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::f0, reg));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_f(int reg, uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::f0, reg), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::f0, reg));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_pc() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::pc));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::pc));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_pc(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::pc), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::pc));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_fcsr() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::fcsr));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::fcsr));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_fcsr(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::fcsr), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::fcsr));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_icycleinstret() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::icycleinstret));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::icycleinstret));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_icycleinstret(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::icycleinstret), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::icycleinstret));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_mvendorid() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::mvendorid));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mvendorid));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     uint64_t do_read_marchid() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::marchid));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::marchid));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     uint64_t do_read_mimpid() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::mimpid));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mimpid));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     uint64_t do_read_mcycle() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::mcycle));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mcycle));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_mcycle(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::mcycle), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mcycle));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_mstatus() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::mstatus));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mstatus));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_mstatus(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::mstatus), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mstatus));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_mtvec() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::mtvec));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mtvec));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_mtvec(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::mtvec), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mtvec));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_mscratch() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::mscratch));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mscratch));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_mscratch(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::mscratch), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mscratch));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_mepc() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::mepc));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mepc));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_mepc(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::mepc), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mepc));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_mcause() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::mcause));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mcause));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_mcause(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::mcause), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mcause));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_mtval() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::mtval));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mtval));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_mtval(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::mtval), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mtval));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_misa() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::misa));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::misa));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_misa(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::misa), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::misa));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_mie() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::mie));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mie));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_mie(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::mie), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mie));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_mip() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::mip));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mip));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_mip(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::mip), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mip));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_medeleg() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::medeleg));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::medeleg));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_medeleg(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::medeleg), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::medeleg));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_mideleg() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::mideleg));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mideleg));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_mideleg(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::mideleg), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mideleg));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_mcounteren() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::mcounteren));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mcounteren));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_mcounteren(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::mcounteren), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mcounteren));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_senvcfg() const {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::senvcfg));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::senvcfg));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_senvcfg(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::senvcfg), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::senvcfg));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_menvcfg() const {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::menvcfg));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::menvcfg));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_menvcfg(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::menvcfg), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::menvcfg));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_stvec() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::stvec));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::stvec));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_stvec(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::stvec), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::stvec));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_sscratch() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::sscratch));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::sscratch));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_sscratch(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::sscratch), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::sscratch));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_sepc() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::sepc));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::sepc));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_sepc(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::sepc), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::sepc));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_scause() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::scause));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::scause));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_scause(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::scause), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::scause));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_stval() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::stval));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::stval));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_stval(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::stval), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::stval));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_satp() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::satp));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::satp));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_satp(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::satp), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::satp));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_scounteren() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::scounteren));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::scounteren));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_scounteren(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::scounteren), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::scounteren));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_ilrsc() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::ilrsc));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::ilrsc));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_ilrsc(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::ilrsc), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::ilrsc));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_iprv() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::iprv));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::iprv));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_iprv(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::iprv), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::iprv));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_iflags_X() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::iflags_X));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::iflags_X));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_iflags_X(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::iflags_X), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::iflags_X));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_iflags_Y() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::iflags_Y));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::iflags_Y));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_iflags_Y(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::iflags_Y), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::iflags_Y));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_iflags_H() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::iflags_H));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::iflags_H));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_iflags_H(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::iflags_H), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::iflags_H));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_iunrep() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::iunrep));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::iunrep));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_iunrep(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::iunrep), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::iunrep));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_clint_mtimecmp() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::clint_mtimecmp));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::clint_mtimecmp));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_clint_mtimecmp(uint64_t val) {
-        raw_write_memory<uint64_t>(machine_reg_address(machine_reg::clint_mtimecmp), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::clint_mtimecmp));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_plic_girqpend() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::plic_girqpend));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::plic_girqpend));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_plic_girqpend(uint64_t val) {
-        raw_write_memory<uint64_t>(machine_reg_address(machine_reg::plic_girqpend), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::plic_girqpend));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_plic_girqsrvd() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::plic_girqsrvd));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::plic_girqsrvd));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_plic_girqsrvd(uint64_t val) {
-        raw_write_memory<uint64_t>(machine_reg_address(machine_reg::plic_girqsrvd), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::plic_girqsrvd));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_htif_fromhost() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::htif_fromhost));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::htif_fromhost));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_htif_fromhost(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::htif_fromhost), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::htif_fromhost));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_htif_tohost() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::htif_tohost));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::htif_tohost));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     void do_write_htif_tohost(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::htif_tohost), val);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::htif_tohost));
+        aliased_aligned_write<uint64_t>(haddr, val);
     }
 
     uint64_t do_read_htif_ihalt() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::htif_ihalt));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::htif_ihalt));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     uint64_t do_read_htif_iconsole() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::htif_iconsole));
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::htif_iconsole));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     uint64_t do_read_htif_iyield() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::htif_iyield));
-    }
-
-    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    std::pair<uint64_t, bool> do_poll_external_interrupts(uint64_t mcycle, uint64_t mcycle_max) {
-        (void) mcycle_max;
-        return {mcycle, false};
-    }
-
-    uint64_t read_pma_istart(uint64_t i) {
-        return raw_read_memory<uint64_t>(shadow_pmas_get_pma_abs_addr(i));
-    }
-
-    uint64_t read_pma_ilength(uint64_t i) {
-        return raw_read_memory<uint64_t>(shadow_pmas_get_pma_abs_addr(i) + sizeof(uint64_t));
-    }
-
-    template <typename T>
-    void do_read_memory_word(uint64_t paddr, const unsigned char *hpage, uint64_t hoffset, T *pval) {
-        (void) hpage;
-        (void) hoffset;
-        *pval = raw_read_memory<T>(paddr);
+        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::htif_iyield));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
@@ -753,154 +835,80 @@ class replay_step_state_access : public i_state_access<replay_step_state_access,
         return false;
     }
 
-    template <typename T>
-    void do_write_memory_word(uint64_t paddr, const unsigned char *hpage, uint64_t hoffset, T val) {
-        (void) hpage;
-        (void) hoffset;
-        raw_write_memory(paddr, val);
+    uint64_t read_pma_istart(uint64_t index) {
+        const auto haddr = do_get_faddr(shadow_pmas_get_pma_istart_abs_addr(index));
+        return aliased_aligned_read<uint64_t>(haddr);
+    }
+
+    uint64_t read_pma_ilength(uint64_t index) {
+        const auto haddr = do_get_faddr(shadow_pmas_get_pma_ilength_abs_addr(index));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
     mock_pma_entry &do_read_pma_entry(uint64_t index) {
         assert(index < PMA_MAX);
+        // record_step_state_access will have recorded the access to istart and
+        // ilength in its implementation of read_pma_entry.
         const uint64_t istart = read_pma_istart(index);
         const uint64_t ilength = read_pma_ilength(index);
         // NOLINTNEXTLINE(bugprone-narrowing-conversions)
         const int i = static_cast<int>(index);
-        if (!m_pmas[i]) {
-            m_pmas[i] =
+        if (!m_context.pmas[i]) {
+            m_context.pmas[i] =
                 make_mock_pma_entry(index, istart, ilength, [](const char *err) { interop_throw_runtime_error(err); });
         }
         // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
         return m_context.pmas[index].value();
     }
 
-    unsigned char *do_get_host_memory(mock_pma_entry &pma) { // NOLINT(readability-convert-member-functions-to-static)
-        (void) pma;
-        return nullptr;
+    template <typename T, typename A>
+    void do_read_memory_word(host_addr haddr, uint64_t /* pma_index */, T *pval) {
+        *pval = aliased_aligned_read<T, A>(haddr);
     }
 
-    template <TLB_entry_type ETYPE>
-    volatile tlb_hot_entry &do_get_tlb_hot_entry(uint64_t eidx) {
-        auto addr = tlb_get_entry_hot_abs_addr<ETYPE>(eidx);
-        auto size = sizeof(tlb_hot_entry);
-        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        volatile tlb_hot_entry *tlbe = reinterpret_cast<tlb_hot_entry *>(get_raw_memory_pointer(addr, size));
-        return *tlbe;
+    template <typename T, typename A>
+    void do_write_memory_word(host_addr haddr, uint64_t /* pma_index */, T val) {
+        aliased_aligned_write<T, A>(haddr, val);
     }
 
-    template <TLB_entry_type ETYPE>
-    volatile tlb_cold_entry &do_get_tlb_entry_cold(uint64_t eidx) {
-        auto addr = tlb_get_entry_cold_abs_addr<ETYPE>(eidx);
-        auto size = sizeof(tlb_cold_entry);
-        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        volatile tlb_cold_entry *tlbe = reinterpret_cast<tlb_cold_entry *>(get_raw_memory_pointer(addr, size));
-        return *tlbe;
+    template <TLB_set_use USE>
+    uint64_t do_read_tlb_vaddr_page(uint64_t slot_index) {
+        const auto haddr = do_get_faddr(shadow_tlb_get_vaddr_page_abs_addr<USE>(slot_index));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
-    template <TLB_entry_type ETYPE, typename T>
-    bool do_translate_vaddr_via_tlb(uint64_t vaddr, unsigned char **phptr) {
-        const uint64_t eidx = tlb_get_entry_index(vaddr);
-        const volatile tlb_hot_entry &tlbhe = do_get_tlb_hot_entry<ETYPE>(eidx);
-        if (tlb_is_hit<T>(tlbhe.vaddr_page, vaddr)) {
-            *phptr = cast_addr_to_ptr<unsigned char *>(tlbhe.vh_offset + vaddr);
-            return true;
-        }
-        return false;
+    template <TLB_set_use USE>
+    host_addr do_read_tlb_vp_offset(uint64_t slot_index) {
+        const auto haddr = do_get_faddr(shadow_tlb_get_vp_offset_abs_addr<USE>(slot_index));
+        return aliased_aligned_read<host_addr>(haddr);
     }
 
-    template <TLB_entry_type ETYPE, typename T>
-    bool do_read_memory_word_via_tlb(uint64_t vaddr, T *pval) {
-        const uint64_t eidx = tlb_get_entry_index(vaddr);
-        const volatile tlb_hot_entry &tlbhe = do_get_tlb_hot_entry<ETYPE>(eidx);
-        if (tlb_is_hit<T>(tlbhe.vaddr_page, vaddr)) {
-            const uint64_t poffset = vaddr & PAGE_OFFSET_MASK;
-            const volatile tlb_cold_entry &tlbce = do_get_tlb_entry_cold<ETYPE>(eidx);
-            *pval = raw_read_memory<T>(tlbce.paddr_page + poffset);
-            return true;
-        }
-        return false;
+    template <TLB_set_use USE>
+    uint64_t do_read_tlb_pma_index(uint64_t slot_index) {
+        const auto haddr = do_get_faddr(shadow_tlb_get_pma_index_abs_addr<USE>(slot_index));
+        return aliased_aligned_read<uint64_t>(haddr);
     }
 
-    template <TLB_entry_type ETYPE, typename T>
-    bool do_write_memory_word_via_tlb(uint64_t vaddr, T val) {
-        const uint64_t eidx = tlb_get_entry_index(vaddr);
-        const volatile tlb_hot_entry &tlbhe = do_get_tlb_hot_entry<ETYPE>(eidx);
-        if (tlb_is_hit<T>(tlbhe.vaddr_page, vaddr)) {
-            const uint64_t poffset = vaddr & PAGE_OFFSET_MASK;
-            const volatile tlb_cold_entry &tlbce = do_get_tlb_entry_cold<ETYPE>(eidx);
-            raw_write_memory(tlbce.paddr_page + poffset, val);
-            return true;
-        }
-        return false;
+    template <TLB_set_use USE>
+    void do_write_tlb(uint64_t slot_index, uint64_t vaddr_page, host_addr vh_offset, uint64_t pma_index) {
+        const auto haddr_vaddr_page = do_get_faddr(shadow_tlb_get_vaddr_page_abs_addr<USE>(slot_index));
+        aliased_aligned_write<uint64_t>(haddr_vaddr_page, vaddr_page);
+        const auto haddr_vp_offset = do_get_faddr(shadow_tlb_get_vp_offset_abs_addr<USE>(slot_index));
+        aliased_aligned_write<host_addr>(haddr_vp_offset, vh_offset);
+        const auto haddr_pma_index = do_get_faddr(shadow_tlb_get_pma_index_abs_addr<USE>(slot_index));
+        aliased_aligned_write<uint64_t>(haddr_pma_index, pma_index);
     }
 
-    template <TLB_entry_type ETYPE>
-    unsigned char *do_replace_tlb_entry(uint64_t vaddr, uint64_t paddr, mock_pma_entry &pma) {
-        const uint64_t eidx = tlb_get_entry_index(vaddr);
-        volatile tlb_hot_entry &tlbhe = do_get_tlb_hot_entry<ETYPE>(eidx);
-        volatile tlb_cold_entry &tlbce = do_get_tlb_entry_cold<ETYPE>(eidx);
-        if constexpr (ETYPE == TLB_WRITE) {
-            if (tlbhe.vaddr_page != TLB_INVALID_PAGE) {
-                mock_pma_entry &pma = do_read_pma_entry(tlbce.pma_index);
-                pma.mark_dirty_page(tlbce.paddr_page - pma.get_start());
-            }
-        }
-        const uint64_t vaddr_page = vaddr & ~PAGE_OFFSET_MASK;
-        const uint64_t paddr_page = paddr & ~PAGE_OFFSET_MASK;
-
-        auto *page_type = find_page(paddr_page);
-        auto *hpage = page_type->data;
-
-        tlbhe.vaddr_page = vaddr_page;
-        tlbhe.vh_offset = cast_ptr_to_addr<uint64_t>(hpage) - vaddr_page;
-        tlbce.paddr_page = paddr_page;
-        tlbce.pma_index = pma.get_index();
-        return hpage;
-    }
-
-    template <TLB_entry_type ETYPE>
-    void do_flush_tlb_entry(uint64_t eidx) {
-        volatile tlb_hot_entry &tlbhe = do_get_tlb_hot_entry<ETYPE>(eidx);
-        // Mark page that was on TLB as dirty so we know to update the Merkle tree
-        if constexpr (ETYPE == TLB_WRITE) {
-            if (tlbhe.vaddr_page != TLB_INVALID_PAGE) {
-                tlbhe.vaddr_page = TLB_INVALID_PAGE;
-                const volatile tlb_cold_entry &tlbce = do_get_tlb_entry_cold<ETYPE>(eidx);
-                mock_pma_entry &pma = do_read_pma_entry(tlbce.pma_index);
-                pma.mark_dirty_page(tlbce.paddr_page - pma.get_start());
-            } else {
-                tlbhe.vaddr_page = TLB_INVALID_PAGE;
-            }
-        } else {
-            tlbhe.vaddr_page = TLB_INVALID_PAGE;
-        }
-    }
-
-    template <TLB_entry_type ETYPE>
-    void do_flush_tlb_type() {
-        for (uint64_t i = 0; i < PMA_TLB_SIZE; ++i) {
-            do_flush_tlb_entry<ETYPE>(i);
-        }
+    void do_mark_dirty_page(host_addr /* haddr */, uint64_t /* pma_index */) {
+        // this is a noop since we have no host machine
     }
 
-    void do_flush_tlb_vaddr(uint64_t vaddr) {
-        (void) vaddr;
-        do_flush_tlb_type<TLB_CODE>();
-        do_flush_tlb_type<TLB_READ>();
-        do_flush_tlb_type<TLB_WRITE>();
-    }
-
-    bool do_get_soft_yield() { // NOLINT(readability-convert-member-functions-to-static)
-        return false;
-    }
-
-    void do_putchar(uint8_t /* c */) { // NOLINT(readability-convert-member-functions-to-static)
-        ;
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    std::pair<uint64_t, bool> do_poll_external_interrupts(uint64_t mcycle, uint64_t mcycle_max) {
+        (void) mcycle_max;
+        return {mcycle, false};
     }
 
-    int do_getchar() { // NOLINT(readability-convert-member-functions-to-static)
-        return -1;
-    }
 };
 
 } // namespace cartesi
diff --git a/src/shadow-pmas.h b/src/shadow-pmas.h
index 1aa7656da..60a2df6df 100644
--- a/src/shadow-pmas.h
+++ b/src/shadow-pmas.h
@@ -53,6 +53,16 @@ static inline uint64_t shadow_pmas_get_pma_abs_addr(uint64_t p) {
     return PMA_SHADOW_PMAS_START + shadow_pmas_get_pma_rel_addr(p);
 }
 
+/// \brief Obtains the absolute address of the istart field in a PMA entry in shadow memory.
+static inline uint64_t shadow_pmas_get_pma_istart_abs_addr(uint64_t p) {
+    return shadow_pmas_get_pma_abs_addr(p) + offsetof(shadow_pma_entry, istart);
+}
+
+/// \brief Obtains the absolute address of the ilength field in a PMA entry in shadow memory.
+static inline uint64_t shadow_pmas_get_pma_ilength_abs_addr(uint64_t p) {
+    return shadow_pmas_get_pma_abs_addr(p) + offsetof(shadow_pma_entry, ilength);
+}
+
 } // namespace cartesi
 
 #endif
diff --git a/src/shadow-state.h b/src/shadow-state.h
index fd35759f1..720112679 100644
--- a/src/shadow-state.h
+++ b/src/shadow-state.h
@@ -22,6 +22,7 @@
 #include <cstdint>
 
 #include "compiler-defines.h"
+#include "pma-constants.h"
 #include "pma-driver.h"
 #include "riscv-constants.h"
 
diff --git a/src/shadow-tlb-factory.cpp b/src/shadow-tlb-factory.cpp
index ba69c6746..c59cd2686 100644
--- a/src/shadow-tlb-factory.cpp
+++ b/src/shadow-tlb-factory.cpp
@@ -37,52 +37,42 @@ static bool shadow_tlb_peek(const pma_entry &pma, const machine &m, uint64_t pag
         *page_data = nullptr;
         return false;
     }
-
     // Clear page
     memset(scratch, 0, PMA_PAGE_SIZE);
-
     // Copy relevant TLB entries to the page
-    for (uint64_t off = 0; off < PMA_PAGE_SIZE; off += sizeof(uint64_t)) {
+    const auto &tlb = m.get_state().tlb;
+    for (uint64_t offset = 0; offset < PMA_PAGE_SIZE; offset += sizeof(uint64_t)) {
         uint64_t val = 0;
-        const uint64_t tlboff = page_offset + off;
-        if (tlboff < offsetof(shadow_tlb_state, cold)) { // Hot entry
-            const uint64_t etype = tlboff / sizeof(std::array<tlb_hot_entry, PMA_TLB_SIZE>);
-            const uint64_t etypeoff = tlboff % sizeof(std::array<tlb_hot_entry, PMA_TLB_SIZE>);
-            const uint64_t eidx = etypeoff / sizeof(tlb_hot_entry);
-            const uint64_t fieldoff = etypeoff % sizeof(tlb_hot_entry);
-            const tlb_hot_entry &tlbhe = m.get_state().tlb.hot[etype][eidx];
-            switch (fieldoff) {
-                case offsetof(tlb_hot_entry, vaddr_page):
-                    val = tlbhe.vaddr_page;
+        if (offset < sizeof(shadow_tlb_state)) {
+            // Figure out in which set (code/read/write) the offset falls
+            const uint64_t set_index = offset / sizeof(shadow_tlb_set);
+            const uint64_t slot_offset = offset % sizeof(shadow_tlb_set);
+            // Figure out in which slot index the offset falls
+            const uint64_t slot_index = slot_offset / sizeof(shadow_tlb_slot);
+            const uint64_t field_offset = slot_offset % sizeof(shadow_tlb_slot);
+            switch (field_offset) {
+                case offsetof(shadow_tlb_slot, vaddr_page):
+                    val = tlb.hot[set_index][slot_index].vaddr_page;
                     break;
-                case offsetof(tlb_hot_entry, vh_offset):
-                default:
-                    // Here we skip host related fields, they are visible as 0 in the device
-                    val = 0;
+                case offsetof(shadow_tlb_slot, vp_offset): {
+                    auto vaddr_page = tlb.hot[set_index][slot_index].vaddr_page;
+                    auto vh_offset = tlb.hot[set_index][slot_index].vh_offset;
+                    auto haddr_page = vaddr_page + vh_offset;
+                    auto pma_index = tlb.cold[set_index][slot_index].pma_index;
+                    auto paddr_page = m.get_paddr(haddr_page, pma_index);
+                    val = paddr_page - vaddr_page;
                     break;
-            }
-        } else if (tlboff < sizeof(shadow_tlb_state)) { // Cold entry
-            const uint64_t coldoff = tlboff - offsetof(shadow_tlb_state, cold);
-            const uint64_t etype = coldoff / sizeof(std::array<tlb_cold_entry, PMA_TLB_SIZE>);
-            const uint64_t etypeoff = coldoff % sizeof(std::array<tlb_cold_entry, PMA_TLB_SIZE>);
-            const uint64_t eidx = etypeoff / sizeof(tlb_cold_entry);
-            const uint64_t fieldoff = etypeoff % sizeof(tlb_cold_entry);
-            const tlb_cold_entry &tlbce = m.get_state().tlb.cold[etype][eidx];
-            switch (fieldoff) {
-                case offsetof(tlb_cold_entry, paddr_page):
-                    val = tlbce.paddr_page;
-                    break;
-                case offsetof(tlb_cold_entry, pma_index):
-                    val = tlbce.pma_index;
+                }
+                case offsetof(shadow_tlb_slot, pma_index):
+                    val = tlb.cold[set_index][slot_index].pma_index;
                     break;
                 default:
                     val = 0;
                     break;
             }
         }
-        aliased_aligned_write<uint64_t>(scratch + off, val);
+        aliased_aligned_write<uint64_t>(scratch + offset, val);
     }
-
     *page_data = scratch;
     return true;
 }
diff --git a/src/shadow-tlb.h b/src/shadow-tlb.h
index 3ecff19c7..c088aff9f 100644
--- a/src/shadow-tlb.h
+++ b/src/shadow-tlb.h
@@ -19,123 +19,53 @@
 
 /// \file
 /// \brief TLB device.
-/// \details The Translation Lookaside Buffer is a small cache used to speed up translation between
-/// virtual target addresses and the corresponding memory address in the host.
+/// \details The Translation Lookaside Buffer is a small cache used to speed up translation between address spaces.
 
 #include <array>
 #include <cstddef>
 #include <cstdint>
 
-#include "pma-constants.h"
+#include "compiler-defines.h"
 #include "pma-driver.h"
-#include "riscv-constants.h"
+#include "tlb.h"
 
 namespace cartesi {
 
-extern const pma_driver shadow_tlb_driver;
-
-/// \brief TLB entry type.
-enum TLB_entry_type : uint64_t { TLB_CODE, TLB_READ, TLB_WRITE };
-
-/// \brief TLB constants.
-enum TLB_constants : uint64_t { TLB_INVALID_PAGE = UINT64_C(-1), TLB_INVALID_PMA = PMA_MAX };
-
-/// \brief TLB hot entry.
-struct tlb_hot_entry final {
-    uint64_t vaddr_page; ///< Target virtual address of page start
-    uint64_t vh_offset;  ///< Offset that maps target virtual addresses directly to host addresses.
+/// \brief Shadow TLB slot
+struct PACKED shadow_tlb_slot {
+    uint64_t vaddr_page; ///< Tag is target virtual address of start of page
+    uint64_t vp_offset;  ///< Value is offset from target virtual address to target physical address within page
+    uint64_t pma_index;  ///< Index of PMA where physical page falls
 };
 
-/// \brief TLB cold entry.
-struct tlb_cold_entry final {
-    uint64_t paddr_page; ///< Target physical address of page start
-    uint64_t pma_index;  ///< PMA entry index for corresponding range
-};
+/// \brief Shadow TLB set
+using shadow_tlb_set = std::array<shadow_tlb_slot, TLB_SET_SIZE>;
 
-/// \brief TLB state.
-struct shadow_tlb_state final {
-    // The TLB state is split in hot and cold regions.
-    // The hot region is accessed with very high frequency every hit check,
-    // while the cold region with low frequency only when replacing or flushing write TLB entries.
-    //
-    // Splitting into hold and cold regions increases host CPU cache usage when checking TLB hits,
-    // due to more data locality, therefore improving the TLB performance.
-    std::array<std::array<tlb_hot_entry, PMA_TLB_SIZE>, 3> hot;
-    std::array<std::array<tlb_cold_entry, PMA_TLB_SIZE>, 3> cold;
-};
+/// \brief Shadow TLB memory layout
+using shadow_tlb_state = std::array<shadow_tlb_set, TLB_LAST_ + 1>; // one set for code, one for read and one for write
 
-//??E Do we even want to support 128 bit systems someday?
-// Make sure uint64_t is large enough to hold host pointers, otherwise 'vh_offset' field will not work correctly.
-static_assert(sizeof(uint64_t) >= sizeof(uintptr_t), "TLB expects host pointer to be at maximum 64bit");
-
-// This TLB algorithm assumes the following conditions
-static_assert((sizeof(tlb_hot_entry) & (sizeof(tlb_hot_entry) - 1)) == 0 &&
-        (sizeof(tlb_cold_entry) & (sizeof(tlb_cold_entry) - 1)) == 0,
-    "TLB entry size must be a power of 2");
-static_assert(PMA_SHADOW_TLB_LENGTH % sizeof(std::array<tlb_hot_entry, PMA_TLB_SIZE>) == 0 &&
-        PMA_SHADOW_TLB_LENGTH % sizeof(std::array<tlb_cold_entry, PMA_TLB_SIZE>) == 0,
-    "code assumes PMA TLB length is divisible by TLB entry array size");
-static_assert(PMA_SHADOW_TLB_LENGTH == sizeof(shadow_tlb_state),
-    "code assumes PMA TLB length is equal to TLB state size");
-
-/// \brief Gets a TLB entry index.
-/// \param vaddr Target virtual address.
-static inline uint64_t tlb_get_entry_index(uint64_t vaddr) {
-    return (vaddr >> PMA_PAGE_SIZE_LOG2) & (PMA_TLB_SIZE - 1);
-}
+static_assert(PMA_SHADOW_TLB_LENGTH >= sizeof(shadow_tlb_state), "TLB state must fit in TLB shadow");
 
-/// \brief Checks for a TLB hit.
-/// \tparam T Type of access needed (uint8_t, uint16_t, uint32_t, uint64_t).
-/// \param vaddr_page Target virtual address of page start of a TLB entry
-/// \param vaddr Target virtual address.
-/// \returns True on hit, false otherwise.
-template <typename T>
-static inline bool tlb_is_hit(uint64_t vaddr_page, uint64_t vaddr) {
-    // Make sure misaligned accesses are always considered a miss
-    // Otherwise, we could report a hit for a word that goes past the end of the PMA range.
-    // Aligned accesses cannot do so because the PMA ranges
-    // are always page-aligned.
-    return (vaddr_page == (vaddr & ~(PAGE_OFFSET_MASK & ~(sizeof(T) - 1))));
-}
-
-template <TLB_entry_type ETYPE>
-static inline uint64_t tlb_get_entry_hot_rel_addr(uint64_t eidx) {
-    return offsetof(shadow_tlb_state, hot) + (ETYPE * sizeof(std::array<tlb_hot_entry, PMA_TLB_SIZE>)) +
-        (eidx * sizeof(tlb_hot_entry));
-}
-
-template <TLB_entry_type ETYPE>
-static inline uint64_t tlb_get_entry_cold_rel_addr(uint64_t eidx) {
-    return offsetof(shadow_tlb_state, cold) + (ETYPE * sizeof(std::array<tlb_cold_entry, PMA_TLB_SIZE>)) +
-        (eidx * sizeof(tlb_cold_entry));
-}
-
-template <TLB_entry_type ETYPE>
-static inline uint64_t tlb_get_entry_hot_abs_addr(uint64_t eidx) {
-    return PMA_SHADOW_TLB_START + tlb_get_entry_hot_rel_addr<ETYPE>(eidx);
-}
+extern const pma_driver shadow_tlb_driver;
 
-template <TLB_entry_type ETYPE>
-static inline uint64_t tlb_get_entry_cold_abs_addr(uint64_t eidx) {
-    return PMA_SHADOW_TLB_START + tlb_get_entry_cold_rel_addr<ETYPE>(eidx);
+template <TLB_set_use USE>
+constexpr uint64_t shadow_tlb_get_slot_abs_addr(uint64_t slot_index) {
+    return PMA_SHADOW_TLB_START + USE * sizeof(shadow_tlb_set) + slot_index * sizeof(shadow_tlb_slot);
 }
 
-template <TLB_entry_type ETYPE>
-static inline uint64_t tlb_get_vaddr_page_rel_addr(uint64_t eidx) {
-    return offsetof(shadow_tlb_state, hot) + (ETYPE * sizeof(std::array<tlb_hot_entry, PMA_TLB_SIZE>)) +
-        (eidx * sizeof(tlb_hot_entry)) + offsetof(tlb_hot_entry, vaddr_page);
+template <TLB_set_use USE>
+constexpr uint64_t shadow_tlb_get_vaddr_page_abs_addr(uint64_t slot_index) {
+    return shadow_tlb_get_slot_abs_addr<USE>(slot_index) + offsetof(shadow_tlb_slot, vaddr_page);
 }
 
-template <TLB_entry_type ETYPE>
-static inline uint64_t tlb_get_paddr_page_rel_addr(uint64_t eidx) {
-    return offsetof(shadow_tlb_state, cold) + (ETYPE * sizeof(std::array<tlb_cold_entry, PMA_TLB_SIZE>)) +
-        (eidx * sizeof(tlb_cold_entry)) + offsetof(tlb_cold_entry, paddr_page);
+template <TLB_set_use USE>
+constexpr uint64_t shadow_tlb_get_vp_offset_abs_addr(uint64_t slot_index) {
+    return shadow_tlb_get_slot_abs_addr<USE>(slot_index) + offsetof(shadow_tlb_slot, vp_offset);
 }
 
-template <TLB_entry_type ETYPE>
-static inline uint64_t tlb_get_pma_index_rel_addr(uint64_t eidx) {
-    return offsetof(shadow_tlb_state, cold) + (ETYPE * sizeof(std::array<tlb_cold_entry, PMA_TLB_SIZE>)) +
-        (eidx * sizeof(tlb_cold_entry)) + offsetof(tlb_cold_entry, pma_index);
+template <TLB_set_use USE>
+constexpr uint64_t shadow_tlb_get_pma_index_abs_addr(uint64_t slot_index) {
+    return shadow_tlb_get_slot_abs_addr<USE>(slot_index) + offsetof(shadow_tlb_slot, pma_index);
 }
 
 } // namespace cartesi
diff --git a/src/state-access.h b/src/state-access.h
index 66f462efb..91fc81511 100644
--- a/src/state-access.h
+++ b/src/state-access.h
@@ -28,6 +28,7 @@
 
 #include "compiler-defines.h"
 #include "device-state-access.h"
+#include "host-addr.h"
 #include "i-state-access.h"
 #include "interpret.h"
 #include "machine-state.h"
@@ -42,10 +43,23 @@
 
 namespace cartesi {
 
+class state_access;
+
+// Type trait that should return the pma_entry type for a state access class
+template <>
+struct i_state_access_pma_entry<state_access> {
+    using type = pma_entry;
+};
+// Type trait that should return the fast_addr type for a state access class
+template <>
+struct i_state_access_fast_addr<state_access> {
+    using type = host_addr;
+};
+
 /// \class state_access
 /// \details The state_access class implements fast, direct
 /// access to the machine state. No logs are kept.
-class state_access : public i_state_access<state_access, pma_entry> {
+class state_access : public i_state_access<state_access> {
     // NOLINTNEXTLINE(cppcoreguidelines-avoid-const-or-ref-data-members)
     machine &m_m; ///< Associated machine
 
@@ -65,8 +79,7 @@ class state_access : public i_state_access<state_access, pma_entry> {
     }
 
 private:
-    // Declare interface as friend to it can forward calls to the "overridden" methods.
-    friend i_state_access<state_access, pma_entry>;
+    friend i_state_access<state_access>;
 
     machine_state &do_get_naked_state() {
         return m_m.get_state();
@@ -409,54 +422,6 @@ class state_access : public i_state_access<state_access, pma_entry> {
         return m_m.get_state().htif.iyield;
     }
 
-    NO_INLINE std::pair<uint64_t, bool> do_poll_external_interrupts(uint64_t mcycle, uint64_t mcycle_max) {
-        bool interrupt_raised = false;
-        // Only poll external interrupts if we are in unreproducible mode
-        if (unlikely(do_read_iunrep())) {
-            // Convert the relative interval of cycles we can wait to the interval of host time we can wait
-            uint64_t timeout_us = (mcycle_max - mcycle) / RTC_CYCLES_PER_US;
-            int64_t start_us = 0;
-            if (timeout_us > 0) {
-                start_us = os_now_us();
-            }
-            device_state_access da(*this, mcycle);
-            // Poll virtio for events (e.g console stdin, network sockets)
-            // Timeout may be decremented in case a device has deadline timers (e.g network device)
-            if (m_m.has_virtio_devices() && m_m.has_virtio_console()) { // VirtIO + VirtIO console
-                interrupt_raised |= m_m.poll_virtio_devices(&timeout_us, &da);
-                // VirtIO console device will poll TTY
-            } else if (m_m.has_virtio_devices()) { // VirtIO without a console
-                interrupt_raised |= m_m.poll_virtio_devices(&timeout_us, &da);
-                if (m_m.has_htif_console()) { // VirtIO + HTIF console
-                    // Poll tty without waiting more time, because the pool above should have waited enough time
-                    interrupt_raised |= os_poll_tty(0);
-                }
-            } else if (m_m.has_htif_console()) { // Only HTIF console
-                interrupt_raised |= os_poll_tty(timeout_us);
-            } else if (timeout_us > 0) { // No interrupts to check, just keep the CPU idle
-                os_sleep_us(timeout_us);
-            }
-            // If timeout is greater than zero, we should also increment mcycle relative to the elapsed time
-            if (timeout_us > 0) {
-                const int64_t end_us = os_now_us();
-                const uint64_t elapsed_us = static_cast<uint64_t>(std::max(end_us - start_us, INT64_C(0)));
-                const uint64_t next_mcycle = mcycle + (elapsed_us * RTC_CYCLES_PER_US);
-                mcycle = std::min(std::max(next_mcycle, mcycle), mcycle_max);
-            }
-        }
-        return {mcycle, interrupt_raised};
-    }
-
-    template <typename T>
-    void do_read_memory_word(uint64_t /*paddr*/, const unsigned char *hpage, uint64_t hoffset, T *pval) const {
-        *pval = aliased_aligned_read<T>(hpage + hoffset);
-    }
-
-    template <typename T>
-    void do_write_memory_word(uint64_t /*paddr*/, unsigned char *hpage, uint64_t hoffset, T val) {
-        aliased_aligned_write(hpage + hoffset, val);
-    }
-
     bool do_read_memory(uint64_t paddr, unsigned char *data, uint64_t length) const {
         //??(edubart): Treating exceptions here is not ideal, we should probably
         // move read_memory() method implementation inside state access later
@@ -479,123 +444,107 @@ class state_access : public i_state_access<state_access, pma_entry> {
         }
     }
 
-    static unsigned char *do_get_host_memory(pma_entry &pma) {
-        return pma.get_memory_noexcept().get_host_memory();
-    }
-
     pma_entry &do_read_pma_entry(uint64_t index) {
         assert(index < PMA_MAX);
-        return m_m.get_state().pmas[index];
+        // NOLINTNEXTLINE(bugprone-narrowing-conversions)
+        return m_m.get_state().pmas[static_cast<int>(index)];
     }
 
-    template <TLB_entry_type ETYPE, typename T>
-    bool do_translate_vaddr_via_tlb(uint64_t vaddr, unsigned char **phptr) {
-        const uint64_t eidx = tlb_get_entry_index(vaddr);
-        const tlb_hot_entry &tlbhe = m_m.get_state().tlb.hot[ETYPE][eidx];
-        if (unlikely(!tlb_is_hit<T>(tlbhe.vaddr_page, vaddr))) {
-            return false;
+    void do_write_memory_with_padding(uint64_t paddr, const unsigned char *data, uint64_t data_length,
+        int write_length_log2_size) {
+        if (data == nullptr) {
+            throw std::runtime_error("data is null");
+        }
+        const uint64_t write_length = static_cast<uint64_t>(1) << write_length_log2_size;
+        if (write_length < data_length) {
+            throw std::runtime_error("write_length is less than data_length");
+        }
+        m_m.write_memory(paddr, data, data_length);
+        if (write_length > data_length) {
+            m_m.fill_memory(paddr + data_length, 0, write_length - data_length);
         }
-        *phptr = cast_addr_to_ptr<unsigned char *>(tlbhe.vh_offset + vaddr);
-        return true;
     }
 
-    template <TLB_entry_type ETYPE, typename T>
-    bool do_read_memory_word_via_tlb(uint64_t vaddr, T *pval) {
-        const uint64_t eidx = tlb_get_entry_index(vaddr);
-        const tlb_hot_entry &tlbhe = m_m.get_state().tlb.hot[ETYPE][eidx];
-        if (unlikely(!tlb_is_hit<T>(tlbhe.vaddr_page, vaddr))) {
-            return false;
-        }
-        const auto *h = cast_addr_to_ptr<const unsigned char *>(tlbhe.vh_offset + vaddr);
-        *pval = aliased_aligned_read<T>(h);
-        return true;
+    template <typename T, typename A = T>
+    void do_read_memory_word(host_addr haddr, uint64_t /* pma_index */, T *pval) {
+        *pval = aliased_aligned_read<T, A>(haddr);
     }
 
-    template <TLB_entry_type ETYPE, typename T>
-    bool do_write_memory_word_via_tlb(uint64_t vaddr, T val) {
-        const uint64_t eidx = tlb_get_entry_index(vaddr);
-        const tlb_hot_entry &tlbhe = m_m.get_state().tlb.hot[ETYPE][eidx];
-        if (unlikely(!tlb_is_hit<T>(tlbhe.vaddr_page, vaddr))) {
-            return false;
-        }
-        auto *h = cast_addr_to_ptr<unsigned char *>(tlbhe.vh_offset + vaddr);
-        aliased_aligned_write(h, val);
-        return true;
-    }
-
-    template <TLB_entry_type ETYPE>
-    unsigned char *do_replace_tlb_entry(uint64_t vaddr, uint64_t paddr, pma_entry &pma) {
-        const uint64_t eidx = tlb_get_entry_index(vaddr);
-        tlb_hot_entry &tlbhe = m_m.get_state().tlb.hot[ETYPE][eidx];
-        tlb_cold_entry &tlbce = m_m.get_state().tlb.cold[ETYPE][eidx];
-        // Mark page that was on TLB as dirty so we know to update the Merkle tree
-        if constexpr (ETYPE == TLB_WRITE) {
-            if (tlbhe.vaddr_page != TLB_INVALID_PAGE) {
-                pma_entry &pma = do_read_pma_entry(tlbce.pma_index);
-                pma.mark_dirty_page(tlbce.paddr_page - pma.get_start());
-            }
-        }
-        const uint64_t vaddr_page = vaddr & ~PAGE_OFFSET_MASK;
-        const uint64_t paddr_page = paddr & ~PAGE_OFFSET_MASK;
-        unsigned char *hpage = pma.get_memory_noexcept().get_host_memory() + (paddr_page - pma.get_start());
-        tlbhe.vaddr_page = vaddr_page;
-        tlbhe.vh_offset = cast_ptr_to_addr<uint64_t>(hpage) - vaddr_page;
-        tlbce.paddr_page = paddr_page;
-        tlbce.pma_index = static_cast<uint64_t>(pma.get_index());
-        return hpage;
-    }
-
-    template <TLB_entry_type ETYPE>
-    void do_flush_tlb_entry(uint64_t eidx) {
-        tlb_hot_entry &tlbhe = m_m.get_state().tlb.hot[ETYPE][eidx];
-        // Mark page that was on TLB as dirty so we know to update the Merkle tree
-        if constexpr (ETYPE == TLB_WRITE) {
-            if (tlbhe.vaddr_page != TLB_INVALID_PAGE) {
-                tlbhe.vaddr_page = TLB_INVALID_PAGE;
-                const tlb_cold_entry &tlbce = m_m.get_state().tlb.cold[ETYPE][eidx];
-                pma_entry &pma = do_read_pma_entry(tlbce.pma_index);
-                pma.mark_dirty_page(tlbce.paddr_page - pma.get_start());
-            } else {
-                tlbhe.vaddr_page = TLB_INVALID_PAGE;
-            }
-        } else {
-            tlbhe.vaddr_page = TLB_INVALID_PAGE;
-        }
+    template <typename T, typename A = T>
+    void do_write_memory_word(host_addr haddr, uint64_t /* pma_index */, T val) {
+        aliased_aligned_write<T, A>(haddr, val);
     }
 
-    template <TLB_entry_type ETYPE>
-    void do_flush_tlb_type() {
-        for (uint64_t i = 0; i < PMA_TLB_SIZE; ++i) {
-            do_flush_tlb_entry<ETYPE>(i);
-        }
+    template <TLB_set_use USE>
+    uint64_t do_read_tlb_vaddr_page(uint64_t slot_index) {
+        return m_m.get_state().tlb.hot[USE][slot_index].vaddr_page;
     }
 
-    void do_flush_tlb_vaddr(uint64_t /*vaddr*/) {
-        // We can't flush just one TLB entry for that specific virtual address,
-        // because megapages/gigapages may be in use while this TLB implementation ignores it,
-        // so we have to flush all addresses.
-        do_flush_tlb_type<TLB_CODE>();
-        do_flush_tlb_type<TLB_READ>();
-        do_flush_tlb_type<TLB_WRITE>();
+    template <TLB_set_use USE>
+    host_addr do_read_tlb_vp_offset(uint64_t slot_index) {
+        return m_m.get_state().tlb.hot[USE][slot_index].vh_offset;
     }
 
-    bool do_get_soft_yield() {
-        return m_m.get_state().soft_yield;
+    template <TLB_set_use USE>
+    uint64_t do_read_tlb_pma_index(uint64_t slot_index) {
+        return m_m.get_state().tlb.cold[USE][slot_index].pma_index;
     }
 
-    void do_write_memory_with_padding(uint64_t paddr, const unsigned char *data, uint64_t data_length,
-        int write_length_log2_size) {
-        if (data == nullptr) {
-            throw std::runtime_error("data is null");
-        }
-        const uint64_t write_length = static_cast<uint64_t>(1) << write_length_log2_size;
-        if (write_length < data_length) {
-            throw std::runtime_error("write_length is less than data_length");
-        }
-        m_m.write_memory(paddr, data, data_length);
-        if (write_length > data_length) {
-            m_m.fill_memory(paddr + data_length, 0, write_length - data_length);
+    template <TLB_set_use USE>
+    void do_write_tlb(uint64_t slot_index, uint64_t vaddr_page, host_addr vh_offset, uint64_t pma_index) {
+        m_m.get_state().tlb.hot[USE][slot_index].vaddr_page = vaddr_page;
+        m_m.get_state().tlb.hot[USE][slot_index].vh_offset = vh_offset;
+        m_m.get_state().tlb.cold[USE][slot_index].pma_index = pma_index;
+    }
+
+    fast_addr do_get_faddr(uint64_t paddr, uint64_t pma_index) const {
+        return m_m.get_host_addr(paddr, pma_index);
+    }
+
+    void do_mark_dirty_page(host_addr haddr, uint64_t pma_index) {
+        m_m.mark_dirty_page(haddr, pma_index);
+    }
+
+    NO_INLINE std::pair<uint64_t, bool> do_poll_external_interrupts(uint64_t mcycle, uint64_t mcycle_max) {
+        bool interrupt_raised = false;
+        // Only poll external interrupts if we are in unreproducible mode
+        if (unlikely(do_read_iunrep())) {
+            // Convert the relative interval of cycles we can wait to the interval of host time we can wait
+            uint64_t timeout_us = (mcycle_max - mcycle) / RTC_CYCLES_PER_US;
+            int64_t start_us = 0;
+            if (timeout_us > 0) {
+                start_us = os_now_us();
+            }
+            device_state_access da(*this, mcycle);
+            // Poll virtio for events (e.g console stdin, network sockets)
+            // Timeout may be decremented in case a device has deadline timers (e.g network device)
+            if (m_m.has_virtio_devices() && m_m.has_virtio_console()) { // VirtIO + VirtIO console
+                interrupt_raised |= m_m.poll_virtio_devices(&timeout_us, &da);
+                // VirtIO console device will poll TTY
+            } else if (m_m.has_virtio_devices()) { // VirtIO without a console
+                interrupt_raised |= m_m.poll_virtio_devices(&timeout_us, &da);
+                if (m_m.has_htif_console()) { // VirtIO + HTIF console
+                    // Poll tty without waiting more time, because the pool above should have waited enough time
+                    interrupt_raised |= os_poll_tty(0);
+                }
+            } else if (m_m.has_htif_console()) { // Only HTIF console
+                interrupt_raised |= os_poll_tty(timeout_us);
+            } else if (timeout_us > 0) { // No interrupts to check, just keep the CPU idle
+                os_sleep_us(timeout_us);
+            }
+            // If timeout is greater than zero, we should also increment mcycle relative to the elapsed time
+            if (timeout_us > 0) {
+                const int64_t end_us = os_now_us();
+                const uint64_t elapsed_us = static_cast<uint64_t>(std::max(end_us - start_us, INT64_C(0)));
+                const uint64_t next_mcycle = mcycle + (elapsed_us * RTC_CYCLES_PER_US);
+                mcycle = std::min(std::max(next_mcycle, mcycle), mcycle_max);
+            }
         }
+        return {mcycle, interrupt_raised};
+    }
+
+    bool do_get_soft_yield() {
+        return m_m.get_state().soft_yield;
     }
 
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
diff --git a/src/strict-aliasing.h b/src/strict-aliasing.h
index 5e93457c9..5313f427c 100644
--- a/src/strict-aliasing.h
+++ b/src/strict-aliasing.h
@@ -21,6 +21,8 @@
 #include <cstring>
 #include <type_traits>
 
+#include "host-addr.h"
+
 /// \file
 /// \brief Enforcement of the strict aliasing rule
 
@@ -28,80 +30,46 @@ namespace cartesi {
 
 /// \brief Writes a value to memory.
 /// \tparam T Type of value.
-/// \param p Where to write. Must be aligned to sizeof(T).
+/// \tparam A Type to which \p haddr is aligned.
+/// \param haddr Where to write. Must be aligned to sizeof(A).
 /// \param v Value to write.
-template <typename T>
-static inline void aliased_aligned_write(void *p, T v) {
-    memcpy(__builtin_assume_aligned(p, sizeof(T)), &v, sizeof(T));
+template <typename T, typename A = T>
+static inline void aliased_aligned_write(host_addr haddr, T v) {
+    memcpy(__builtin_assume_aligned(cast_host_addr_to_ptr(haddr), sizeof(A)), &v, sizeof(T));
 }
 
 /// \brief Reads a value from memory.
 /// \tparam T Type of value.
-/// \param p Where to find value. Must be aligned to sizeof(T).
-/// \returns Value.
-template <typename T>
-static inline T aliased_aligned_read(const void *p) {
-    T v;
-    memcpy(&v, __builtin_assume_aligned(p, sizeof(T)), sizeof(T));
-    return v;
-}
-
-/// \brief Reads an unaligned value from memory.
-/// \tparam T Type of unaligned value.
-/// \tparam U Type of aligned value.
-/// \tparam ALIGN Alignment of p.
-/// \param p Where to find value. Must be aligned to sizeof(U).
-/// \returns Value.
-template <typename T, typename U>
-static inline T aliased_unaligned_read(const void *p) {
+/// \tparam A Type to which \p haddr is aligned.
+/// \param haddr Where to find value. Must be aligned to sizeof(A).
+/// \returns Value read.
+template <typename T, typename A = T>
+static inline T aliased_aligned_read(host_addr haddr) {
     T v;
-    memcpy(&v, __builtin_assume_aligned(p, sizeof(U)), sizeof(T));
+    memcpy(&v, __builtin_assume_aligned(cast_host_addr_to_ptr(haddr), sizeof(A)), sizeof(T));
     return v;
 }
 
-/// \brief Casts a pointer to an unsigned integer.
-/// \details The address returned by this function,
-/// can later be converted to a pointer using cast_addr_to_ptr,
-/// and must be read/written using aliased_aligned_read/aliased_aligned_write,
-/// otherwise strict aliasing rules may be violated.
-/// \tparam T Unsigned integer type to cast to.
-/// \tparam PTR Pointer type to perform the cast.
-/// \param ptr The pointer to retrieve its unsigned integer representation.
-/// \returns An unsigned integer.
-template <typename T, typename PTR>
-static inline uint64_t cast_ptr_to_addr(PTR ptr) {
-    // Enforcement on type arguments
-    static_assert(std::is_pointer_v<PTR>);
-    static_assert(std::is_unsigned_v<T>);
-    static_assert(sizeof(PTR) == sizeof(uintptr_t));
-    // We can only cast to integers that large enough to contain a pointer
-    static_assert(sizeof(T) >= sizeof(uintptr_t), "expected sizeof(T) >= sizeof(uintptr_t)");
-    // Note that bellow we cast the pointer to void* first,
-    // according to the C spec this is required is to ensure the same presentation, before casting to uintptr_t
-    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast,bugprone-casting-through-void)
-    return static_cast<T>(reinterpret_cast<uintptr_t>(static_cast<const void *>(ptr)));
+/// \brief Writes a value to memory.
+/// \tparam T Type of value.
+/// \tparam A Type to which \p haddr is aligned.
+/// \param p Where to write. Must be aligned to sizeof(A).
+/// \param v Value to write.
+template <typename T, typename A = T>
+static inline void aliased_aligned_write(void *p, T v) {
+    memcpy(__builtin_assume_aligned(p, sizeof(A)), &v, sizeof(T));
 }
 
-/// \brief Casts a pointer to an unsigned integer.
-/// \details The pointer returned by this function
-/// must only be read/written using aliased_aligned_read/aliased_aligned_write,
-/// otherwise strict aliasing rules may be violated.
-/// \tparam T Unsigned integer type to cast to.
-/// \tparam PTR Pointer type to perform the cast.
-/// \param addr The address of the pointer represented by an unsigned integer.
-/// \returns A pointer.
-template <typename PTR, typename T>
-static inline PTR cast_addr_to_ptr(T addr) {
-    // Enforcement on type arguments
-    static_assert(std::is_pointer_v<PTR>);
-    static_assert(std::is_unsigned_v<T>);
-    static_assert(sizeof(PTR) == sizeof(uintptr_t));
-    // We can only cast from integer that are large enough to contain a pointer
-    static_assert(sizeof(T) >= sizeof(uintptr_t), "expected sizeof(T) >= sizeof(uintptr_t)");
-    // Note that bellow we cast the address to void* first,
-    // according to the C spec this is required is to ensure the same presentation, before casting to PTR
-    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast,bugprone-casting-through-void,performance-no-int-to-ptr)
-    return static_cast<PTR>(reinterpret_cast<void *>(static_cast<uintptr_t>(addr)));
+/// \brief Reads a value from memory.
+/// \tparam T Type of value.
+/// \tparam A Type to which \p haddr is aligned.
+/// \param p Where to find value. Must be aligned to sizeof(A).
+/// \returns Value read.
+template <typename T, typename A = T>
+static inline T aliased_aligned_read(const void *p) {
+    T v;
+    memcpy(&v, __builtin_assume_aligned(p, sizeof(A)), sizeof(T));
+    return v;
 }
 
 } // namespace cartesi
diff --git a/src/tlb.h b/src/tlb.h
new file mode 100644
index 000000000..991f67d32
--- /dev/null
+++ b/src/tlb.h
@@ -0,0 +1,98 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef TLB_H
+#define TLB_H
+
+/// \file
+/// \brief TLB definitions
+/// \details The Translation Lookaside Buffer is a small cache used to speed up translation between address spaces.
+
+#include <array>
+#include <cstddef>
+#include <cstdint>
+
+#include "host-addr.h"
+#include "pma-constants.h"
+#include "pma-driver.h"
+#include "riscv-constants.h"
+
+namespace cartesi {
+
+/// \brief TLB set mode.
+enum TLB_set_use : uint64_t { TLB_CODE, TLB_READ, TLB_WRITE, TLB_LAST_ = TLB_WRITE };
+
+/// \brief TLB constants.
+enum TLB_constants : uint64_t {
+    TLB_SET_SIZE = 256,
+    TLB_INVALID_PAGE = UINT64_C(-1),
+    TLB_INVALID_PMA_INDEX = UINT64_C(-1)
+};
+
+/// \brief TLB hot slot.
+struct tlb_hot_slot final {
+    uint64_t vaddr_page; ///< Tag is the target virtual address of page start
+    host_addr vh_offset; ///< Value is the offset from target virtual address in the same page to
+                         ///< translated host address (vh_offset = haddr - vaddr)
+};
+
+using tlb_hot_set = std::array<tlb_hot_slot, TLB_SET_SIZE>;
+
+/// \brief TLB cold slot.
+struct tlb_cold_slot final {
+    uint64_t pma_index; ///< Index of PMA where physical address falls
+};
+
+using tlb_cold_set = std::array<tlb_cold_slot, TLB_SET_SIZE>;
+
+/// \brief TLB state.
+struct tlb_state {
+    std::array<tlb_hot_set, TLB_LAST_ + 1> hot;
+    std::array<tlb_cold_set, TLB_LAST_ + 1> cold;
+};
+
+static_assert(sizeof(uint64_t) >= sizeof(uintptr_t), "TLB expects host pointer fit in 64 bits");
+//??D why?
+static_assert((sizeof(tlb_hot_slot) & (sizeof(tlb_hot_slot) - 1)) == 0, "TLB slot size must be a power of 2");
+static_assert((sizeof(tlb_cold_slot) & (sizeof(tlb_cold_slot) - 1)) == 0, "TLB slot size must be a power of 2");
+
+/// \brief Gets a TLB slot index for a page.
+/// \param vaddr Target virtual address.
+/// \returns TLB slot index.
+constexpr uint64_t tlb_slot_index(uint64_t vaddr) {
+    return (vaddr >> LOG2_PAGE_SIZE) & (TLB_SET_SIZE - 1);
+}
+
+/// \brief Checks for a TLB hit.
+/// \tparam T Type of access needed (uint8_t, uint16_t, uint32_t, uint64_t).
+/// \param slot_vaddr_page vaddr_page in TLB slot
+/// \param vaddr Target virtual address being looked up.
+/// \returns True on hit, false otherwise.
+template <typename T>
+constexpr bool tlb_is_hit(uint64_t slot_vaddr_page, uint64_t vaddr) {
+    // Make sure misaligned accesses are always considered a miss
+    // Otherwise, we could report a hit for a word that goes past the end of the page.
+    // Aligned accesses smaller than a page size cannot straddle two pages.
+    return slot_vaddr_page == (vaddr & ~(PAGE_OFFSET_MASK & ~(sizeof(T) - 1)));
+}
+
+constexpr uint64_t tlb_addr_page(uint64_t addr) {
+    return addr & ~PAGE_OFFSET_MASK;
+}
+
+} // namespace cartesi
+
+#endif
diff --git a/src/translate-virtual-address.h b/src/translate-virtual-address.h
index a5bfba31f..5a740a29a 100644
--- a/src/translate-virtual-address.h
+++ b/src/translate-virtual-address.h
@@ -58,18 +58,17 @@ namespace cartesi {
 /// \param val Value to write.
 /// \returns True if succeeded, false otherwise.
 template <typename STATE_ACCESS>
-static FORCE_INLINE bool write_ram_uint64(STATE_ACCESS a, uint64_t paddr, uint64_t val) {
-    auto &pma = find_pma_entry<uint64_t>(a, paddr);
+static inline bool write_ram_uint64(STATE_ACCESS a, uint64_t paddr, uint64_t val) {
+    uint64_t pma_index = 0;
+    auto &pma = find_pma_entry<uint64_t>(a, paddr, pma_index);
     if (unlikely(!pma.get_istart_M() || !pma.get_istart_W())) {
         return false;
     }
-    const uint64_t paddr_page = paddr & ~PAGE_OFFSET_MASK;
-    unsigned char *hpage = a.get_host_memory(pma) + (paddr_page - pma.get_start());
-    const uint64_t hoffset = paddr - paddr_page;
+    const auto faddr = a.get_faddr(paddr, pma_index);
     // log writes to memory
-    a.write_memory_word(paddr, hpage, hoffset, val);
+    a.write_memory_word(faddr, pma_index, val);
     // mark page as dirty so we know to update the Merkle tree
-    pma.mark_dirty_page(paddr - pma.get_start());
+    a.mark_dirty_page(faddr, pma_index);
     return true;
 }
 
@@ -80,15 +79,14 @@ static FORCE_INLINE bool write_ram_uint64(STATE_ACCESS a, uint64_t paddr, uint64
 /// \param pval Pointer to word.
 /// \returns True if succeeded, false otherwise.
 template <typename STATE_ACCESS>
-static FORCE_INLINE bool read_ram_uint64(STATE_ACCESS a, uint64_t paddr, uint64_t *pval) {
-    auto &pma = find_pma_entry<uint64_t>(a, paddr);
+static inline bool read_ram_uint64(STATE_ACCESS a, uint64_t paddr, uint64_t *pval) {
+    uint64_t pma_index = 0;
+    auto &pma = find_pma_entry<uint64_t>(a, paddr, pma_index);
     if (unlikely(!pma.get_istart_M() || !pma.get_istart_R())) {
         return false;
     }
-    const uint64_t paddr_page = paddr & ~PAGE_OFFSET_MASK;
-    unsigned char *hpage = a.get_host_memory(pma) + (paddr_page - pma.get_start());
-    const uint64_t hoffset = paddr - paddr_page;
-    a.read_memory_word(paddr, hpage, hoffset, pval);
+    const auto faddr = a.get_faddr(paddr, pma_index);
+    a.read_memory_word(faddr, pma_index, pval);
     return true;
 }
 
diff --git a/src/uarch-bridge.h b/src/uarch-bridge.h
index b09ea5a39..423a2ead2 100644
--- a/src/uarch-bridge.h
+++ b/src/uarch-bridge.h
@@ -27,6 +27,7 @@
 #include "machine-state.h"
 #include "pma-constants.h"
 #include "riscv-constants.h"
+#include "shadow-pmas.h"
 #include "shadow-state.h"
 #include "shadow-tlb.h"
 #include "strict-aliasing.h"
@@ -814,22 +815,27 @@ class uarch_bridge {
             return "f";
         }
 
-        if (paddr >= PMA_SHADOW_PMAS_START && paddr < PMA_SHADOW_PMAS_START + (PMA_MAX * PMA_WORD_SIZE * 2)) {
-            auto word_index = (paddr - PMA_SHADOW_PMAS_START) >> 3;
-            if ((word_index & 1) == 0) {
+        if (paddr >= shadow_pmas_get_pma_abs_addr(0) && paddr < shadow_pmas_get_pma_abs_addr(PMA_MAX)) {
+            if ((paddr & 0b1111) == 0) {
                 return "pma.istart";
             }
-            return "pma.ilength";
+            if ((paddr & 0b1111) == 0b1000) {
+                return "pma.ilength";
+            }
         }
 
-        if (paddr >= PMA_SHADOW_TLB_START && paddr < PMA_SHADOW_TLB_START + PMA_SHADOW_TLB_LENGTH &&
-            paddr % sizeof(uint64_t) == 0) {
-            const uint64_t tlboff = paddr - PMA_SHADOW_TLB_START;
-            if (tlboff < offsetof(shadow_tlb_state, cold)) {
-                return "cold_tlb_entry_field";
+        if (paddr % sizeof(uint64_t) == 0) {
+            if (paddr >= shadow_tlb_get_slot_abs_addr<TLB_WRITE>(0) &&
+                paddr < shadow_tlb_get_slot_abs_addr<TLB_WRITE>(TLB_SET_SIZE)) {
+                return "write tlb";
+            }
+            if (paddr >= shadow_tlb_get_slot_abs_addr<TLB_READ>(0) &&
+                paddr < shadow_tlb_get_slot_abs_addr<TLB_READ>(TLB_SET_SIZE)) {
+                return "read tlb";
             }
-            if (tlboff < sizeof(shadow_tlb_state)) {
-                return "hot_tlb_entry_field";
+            if (paddr >= shadow_tlb_get_slot_abs_addr<TLB_READ>(0) &&
+                paddr < shadow_tlb_get_slot_abs_addr<TLB_READ>(TLB_SET_SIZE)) {
+                return "code tlb";
             }
         }
 
diff --git a/src/uarch-solidity-compat.h b/src/uarch-solidity-compat.h
index fc31d052b..4cc48266f 100644
--- a/src/uarch-solidity-compat.h
+++ b/src/uarch-solidity-compat.h
@@ -100,23 +100,23 @@ static inline void resetState(UarchState &a) {
     a.reset_state();
 }
 
-template <typename UarchState>
-static inline uint64 readIflagsY(UarchState &a) {
+template <typename State>
+static inline uint64 readIflagsY(State &a) {
     return a.read_iflags_Y();
 }
 
 template <typename UarchState>
-static inline void writeIflagsY(UarchState &a, uint64 val) {
+static inline void writeIflagsY(State &a, uint64 val) {
     a.write_iflags_Y(val);
 }
 
-template <typename UarchState>
-static inline void writeHtifFromhost(UarchState &a, uint64 val) {
+template <typename State>
+static inline void writeHtifFromhost(State &a, uint64 val) {
     a.write_htif_fromhost(val);
 }
 
-template <typename UarchState>
-static inline void writeMemoryWithPadding(UarchState &a, uint64 paddr, bytes data, uint64_t data_length,
+template <typename State>
+static inline void writeMemoryWithPadding(State &a, uint64 paddr, bytes data, uint64_t data_length,
     int32 write_length_log2_size) {
     a.write_memory_with_padding(paddr, data, data_length, write_length_log2_size);
 }
@@ -131,6 +131,15 @@ static inline void putChar(UarchState & /*a*/, unsigned char c) {
     os_putchar(c);
 }
 
+template <typename UarchState>
+static inline void markDirtyPage(UarchState &a, uint64 paddr, uint64 pma_index) {
+    a.mark_dirty_page(paddr, pma_index);
+}
+
+static inline void writeTlbVpOffset(UarchState &a, uint64 use, uint64 vp_offset, uint64 pma_index) {
+    a.write_tlb_vp_offset(use, slot_index, vp_offset, pma_index);
+}
+
 // Conversions and arithmetic functions
 
 static inline int32 uint64ToInt32(uint64 v) {
diff --git a/src/uarch-state-access.h b/src/uarch-state-access.h
index c0578f2e6..c840da29c 100644
--- a/src/uarch-state-access.h
+++ b/src/uarch-state-access.h
@@ -27,13 +27,16 @@
 #include "pma.h"
 #include "riscv-constants.h"
 #include "strict-aliasing.h"
+#if OKUARCH
 #include "uarch-bridge.h"
 #include "uarch-pristine.h"
 #include "uarch-state.h"
+#endif
 
 namespace cartesi {
 
 class uarch_state_access : public i_uarch_state_access<uarch_state_access> {
+#ifdef OKUARCH
     // NOLINTBEGIN(cppcoreguidelines-avoid-const-or-ref-data-members)
     uarch_state &m_us;
     machine_state &m_s;
@@ -199,6 +202,7 @@ class uarch_state_access : public i_uarch_state_access<uarch_state_access> {
         m_us.ram.fill_memory(m_us.ram.get_start() + uarch_pristine_ram_len, 0,
             m_us.ram.get_length() - uarch_pristine_ram_len);
     }
+#endif
 };
 
 } // namespace cartesi
diff --git a/src/uarch-step.cpp b/src/uarch-step.cpp
index b1c343027..b7dbd9f4e 100644
--- a/src/uarch-step.cpp
+++ b/src/uarch-step.cpp
@@ -865,17 +865,35 @@ static inline void executeSD(UarchState &a, uint32 insn, uint64 pc) {
 template <typename UarchState>
 static inline void executeECALL(UarchState &a, uint64 pc) {
     [[maybe_unused]] auto note = a.make_scoped_note("ecall");
+    // ECALL conventions
+    // a0--a7 are the same as x10--x17
+    // syscall is passed in a7
+    // arguments are passed in a0--a5
+    // return value is in a0 (and maybe also in a1)
     uint64 fn = readX(a, 17); // a7 contains the function number
     if (fn == UARCH_ECALL_FN_HALT) {
         return setHaltFlag(a);
     }
     if (fn == UARCH_ECALL_FN_PUTCHAR) {
-        uint64 character = readX(a, 16); // a6 contains the character to print
+        uint64 character = readX(a, 10); // a0 contains the character to print
         putChar(a, uint8(character));
-    } else {
-        throwRuntimeError(a, "unsupported ecall function");
-    }
-    return advancePc(a, pc);
+        return advancePc(a, pc);
+    }
+    if (fn == UARCH_ECALL_FN_MARK_DIRTY_PAGE) {
+        uint64 paddr = readX(a, 10);     // a0 contains physical address in page to be marked dirty
+        uint64 pma_index = readX(a, 11); // a1 contains a index of PMA where page falls
+        markDirtyPage(a, paddr, pma_index);
+        return advancePc(a, pc);
+    }
+    if (fn == UARCH_ECALL_FN_WRITE_TLB_VP_OFFSET) {
+        uint64 use = readX(a, 10);        // a0 contains TLB set (code, read, write)
+        uint64 slot_index = readX(a, 11); // a1 contains slot_index to modify
+        uint64 vp_offset = readX(a, 12);  // a2 contains vp_offset to write
+        uint64 pma_index = readX(a, 13);  // a3 contains index of PMA where page falls
+        writeTlbVpOffset(a, use, slot_index, vp_offset, pma_index);
+        return advancePc(a, pc);
+    }
+    throwRuntimeError(a, "unsupported ecall function");
 }
 
 template <typename UarchState>

From a4644227615ceb0803be7bfc5bfd64a4b9e06b31 Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Mon, 20 Jan 2025 13:21:23 +0000
Subject: [PATCH 04/82] refactor: clean up uarch state access mechanism

---
 Makefile                                  |    6 +-
 src/Makefile                              |   38 +-
 src/access-log.h                          |   60 +-
 src/cartesi/util.lua                      |    3 +-
 src/clint-factory.cpp                     |   10 +-
 src/find-pma-entry.h                      |    1 +
 src/htif-factory.cpp                      |   11 +-
 src/htif-factory.h                        |    1 -
 src/i-state-access.h                      |  612 ++++++++++--
 src/i-uarch-state-access.h                |  125 ++-
 src/interpret.cpp                         |   69 +-
 src/machine-c-api.h                       |   26 +-
 src/machine-reg.h                         |  339 ++++---
 src/machine.cpp                           |  641 +++++++------
 src/machine.h                             |  111 ++-
 src/mock-pma-entry.h                      |    4 +
 src/plic-factory.cpp                      |   13 +-
 src/pm-type-name.h                        |   48 +
 src/pma-constants.h                       |   31 +
 src/pma.cpp                               |   29 +-
 src/pma.h                                 |   19 +-
 src/record-send-cmio-state-access.h       |   18 +-
 src/record-step-state-access.h            |  371 ++++----
 src/replay-send-cmio-state-access.h       |    5 +
 src/replay-step-state-access.h            |  387 ++++----
 src/scoped-note.h                         |   52 ++
 src/shadow-peek.h                         |   68 ++
 src/shadow-pmas-factory.h                 |   10 +-
 src/shadow-pmas.h                         |   60 +-
 src/shadow-state-factory.cpp              |   96 +-
 src/shadow-state.h                        |  345 +++++++
 src/shadow-tlb-factory.cpp                |   71 +-
 src/shadow-tlb.h                          |   75 +-
 src/shadow-uarch-state-factory.cpp        |   52 +-
 src/shadow-uarch-state.h                  |  130 +++
 src/state-access.h                        |   54 +-
 src/tlb.h                                 |    4 +-
 src/uarch-bridge.h                        | 1038 ---------------------
 src/uarch-config.h                        |    2 +-
 src/uarch-constants.h                     |    6 +-
 src/uarch-defines.h                       |    6 +-
 src/uarch-interpret.h                     |    5 +-
 src/uarch-machine-bridge.cpp              |  170 ++++
 src/uarch-machine-bridge.h                |   57 ++
 src/uarch-machine.cpp                     |   83 --
 src/uarch-machine.h                       |   83 --
 src/uarch-record-state-access.h           |  525 ++++-------
 src/uarch-replay-state-access.h           |  443 ++++-----
 src/uarch-solidity-compat.h               |   24 +-
 src/uarch-state-access.h                  |  189 ++--
 src/uarch-state.h                         |    2 +-
 src/uarch-step.cpp                        |   26 +-
 tests/Makefile                            |    4 +-
 tests/lua/cartesi/tests/util.lua          |   12 +-
 tests/lua/log-with-mtime-transition.lua   |    4 +
 tests/lua/machine-bind.lua                |  181 ++--
 tests/misc/test-machine-c-api.cpp         |    8 +-
 uarch/Makefile                            |    3 +
 uarch/machine-uarch-bridge-state-access.h |  507 ++++++++++
 uarch/uarch-ecall.c                       |   73 ++
 uarch/uarch-ecall.h                       |   36 +
 uarch/uarch-machine-state-access.h        |  586 ------------
 uarch/uarch-printf.c                      |    4 +-
 uarch/uarch-printf.h                      |    7 -
 uarch/uarch-ram-entry.S                   |    4 +-
 uarch/uarch-run.cpp                       |   26 +-
 uarch/uarch-runtime.cpp                   |   14 -
 uarch/uarch-strict-aliasing.h             |   92 ++
 68 files changed, 4258 insertions(+), 3957 deletions(-)
 create mode 100644 src/pm-type-name.h
 create mode 100644 src/scoped-note.h
 create mode 100644 src/shadow-peek.h
 delete mode 100644 src/uarch-bridge.h
 create mode 100644 src/uarch-machine-bridge.cpp
 create mode 100644 src/uarch-machine-bridge.h
 delete mode 100644 src/uarch-machine.cpp
 delete mode 100644 src/uarch-machine.h
 create mode 100644 uarch/machine-uarch-bridge-state-access.h
 create mode 100644 uarch/uarch-ecall.c
 create mode 100644 uarch/uarch-ecall.h
 delete mode 100644 uarch/uarch-machine-state-access.h
 create mode 100644 uarch/uarch-strict-aliasing.h

diff --git a/Makefile b/Makefile
index 91ee8e864..98a72b129 100644
--- a/Makefile
+++ b/Makefile
@@ -96,6 +96,9 @@ TESTSDIR = $(abspath tests)
 DOWNLOADDIR = $(DEPDIR)/downloads
 SUBCLEAN = $(addsuffix .clean,$(SRCDIR) uarch tests)
 
+# Pass down received UARCH_DEFS to sub-makefiles
+export UARCH_DEFS
+
 # Docker image tag
 TAG ?= devel
 DEBIAN_IMG ?= cartesi/machine-emulator:$(TAG).deb
@@ -306,11 +309,12 @@ toolchain-env: check-toolchain
 		cartesi/machine-emulator:toolchain /bin/bash
 
 toolchain-exec: check-toolchain
-	@docker run --hostname toolchain --rm \
+	docker run --hostname toolchain --rm \
 		-e USER=$$(id -u -n) \
 		-e GROUP=$$(id -g -n) \
 		-e UID=$$(id -u) \
 		-e GID=$$(id -g) \
+		-e UARCH_DEFS="$(UARCH_DEFS)" \
 		-v `pwd`:/opt/cartesi/machine-emulator \
 		-w /opt/cartesi/machine-emulator \
 		cartesi/machine-emulator:toolchain /bin/bash -c "$(CONTAINER_COMMAND)"
diff --git a/src/Makefile b/src/Makefile
index f7780c2fb..53c30cb7b 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -175,17 +175,22 @@ DEFS+=-D_FILE_OFFSET_BITS=64
 DEFS+=-DJSON_HAS_FILESYSTEM=0
 
 ifeq ($(dump),yes)
-#DEFS+=-DDUMP_ILLEGAL_INSN_EXCEPTIONS
-#DEFS+=-DDUMP_EXCEPTIONS
-#DEFS+=-DDUMP_INTERRUPTS
-DEFS+=-DDUMP_HIST
-#DEFS+=-DDUMP_MMU_EXCEPTIONS
-#DEFS+=-DDUMP_INVALID_MEM_ACCESS
-#DEFS+=-DDUMP_INVALID_CSR
-#DEFS+=-DDUMP_INSN
-#DEFS+=-DDUMP_REGS
-#DEFS+=-DDUMP_COUNTERS
+#DUMP_DEFS+=-DDUMP_ILLEGAL_INSN_EXCEPTIONS
+#DUMP_DEFS+=-DDUMP_EXCEPTIONS
+#DUMP_DEFS+=-DDUMP_INTERRUPTS
+#DUMP_DEFS+=-DDUMP_HIST
+#DUMP_DEFS+=-DDUMP_MMU_EXCEPTIONS
+#DUMP_DEFS+=-DDUMP_INVALID_MEM_ACCESS
+#DUMP_DEFS+=-DDUMP_INVALID_CSR
+#DUMP_DEFS+=-DDUMP_INSN
+DUMP_DEFS+=-DDUMP_STATE_ACCESS
+DUMP_DEFS+=-DDUMP_UARCH_STATE_ACCESS
+#DUMP_DEFS+=-DDUMP_REGS
+#DUMP_DEFS+=-DDUMP_COUNTERS
 endif
+DEFS += $(DUMP_DEFS)
+# Pass down UARCH_DEFS to sub-makefiles
+export UARCH_DEFS += $(DUMP_DEFS)
 
 # By default we compile in release with debug information,
 # so the emulator is packaged correctly by default.
@@ -282,7 +287,7 @@ CLANG_TIDY=clang-tidy
 CLANG_TIDY_TARGETS=$(patsubst %.cpp,%.clang-tidy,$(patsubst %.c,%.clang-tidy,$(LINTER_SOURCES)))
 
 CLANG_FORMAT=clang-format
-CLANG_FORMAT_UARCH_FILES:=$(wildcard ../uarch/*.cpp, ../uarch/*.h)
+CLANG_FORMAT_UARCH_FILES:=$(wildcard ../uarch/*.cpp) $(wildcard ../uarch/*.h)
 CLANG_FORMAT_UARCH_FILES:=$(filter-out %uarch-printf%,$(strip $(CLANG_FORMAT_UARCH_FILES)))
 CLANG_FORMAT_FILES:=$(wildcard *.cpp) $(wildcard *.c) $(wildcard *.h) $(wildcard *.hpp) $(CLANG_FORMAT_UARCH_FILES)
 CLANG_FORMAT_IGNORE_FILES:=interpret-jump-table.h
@@ -381,14 +386,13 @@ LIBCARTESI_OBJS:= \
 	uarch-pristine-ram.o \
 	uarch-pristine-state-hash.o \
 	uarch-pristine-hash.o \
+    uarch-interpret.o \
+	uarch-step.o \
+	uarch-machine-bridge.o \
+	uarch-reset-state.o \
+	send-cmio-response.o \
 	replay-step-state-access-interop.o
 
-	#send-cmio-response.o \
-	#uarch-machine.o \
-    #uarch-interpret.o \
-	#uarch-step.o \
-	#uarch-reset-state.o \
-
 CARTESI_CLUA_OBJS:= \
 	clua.o \
 	clua-i-virtual-machine.o
diff --git a/src/access-log.h b/src/access-log.h
index 97d439a77..62e526f6c 100644
--- a/src/access-log.h
+++ b/src/access-log.h
@@ -54,12 +54,12 @@ static inline void set_word_access_data(uint64_t w, access_data &ad) {
     ad.insert(ad.end(), p, p + sizeof(w));
 }
 
-static inline void replace_word_access_data(uint64_t w, access_data &ad, int offset = 0) {
+static inline void replace_word_access_data(uint64_t w, access_data &ad, uint64_t offset = 0) {
     assert(ad.size() >= offset + sizeof(uint64_t));
     aliased_aligned_write<uint64_t>(ad.data() + offset, w);
 }
 
-static inline uint64_t get_word_access_data(const access_data &ad, int offset = 0) {
+static inline uint64_t get_word_access_data(const access_data &ad, uint64_t offset = 0) {
     assert(ad.size() >= offset + sizeof(uint64_t));
     return aliased_aligned_read<uint64_t>(ad.data() + offset);
 }
@@ -258,13 +258,14 @@ class access_log {
     };
 
 private:
-    std::vector<access> m_accesses;       ///< List of all accesses
-    std::vector<bracket_note> m_brackets; ///< Begin/End annotations
-    std::vector<std::string> m_notes;     ///< Per-access annotations
-    type m_log_type;                      ///< Log type
+    std::vector<access> m_accesses;                          ///< List of all accesses
+    std::vector<bracket_note> m_brackets;                    ///< Begin/End annotations
+    std::vector<std::string> m_notes;                        ///< Per-access annotations
+    type m_log_type;                                         ///< Log type
+    std::vector<bracket_note>::size_type m_outstanding_ends; ///< Number of outstanding unmatched end brackets
 
 public:
-    explicit access_log(type log_type) : m_log_type(log_type) {
+    explicit access_log(type log_type) : m_log_type(log_type), m_outstanding_ends{0} {
         ;
     }
 
@@ -273,8 +274,16 @@ class access_log {
         m_accesses(std::forward<ACCESSES>(accesses)),
         m_brackets(std::forward<BRACKETS>(brackets)),
         m_notes(std::forward<NOTES>(notes)),
-        m_log_type(log_type) {
-        ;
+        m_log_type(log_type),
+        m_outstanding_ends(0) {
+        for (const auto &b : m_brackets) {
+            if (b.type == bracket_type::begin) {
+                ++m_outstanding_ends;
+            }
+            if (b.type == bracket_type::end && m_outstanding_ends > 0) {
+                --m_outstanding_ends;
+            }
+        };
     }
 
     /// \brief Clear the log
@@ -282,28 +291,43 @@ class access_log {
         m_accesses.clear();
         m_notes.clear();
         m_brackets.clear();
+        m_outstanding_ends = 0;
     }
 
     /// \brief Adds a bracket annotation to the log (if the log type includes annotations)
     /// \param type Bracket type
     /// \param text Annotation contents
-    void push_bracket(bracket_type type, const char *text) {
+    void push_begin_bracket(const char *text) {
+        if (m_log_type.has_annotations()) {
+            // Increment number of outstanding end brackets we are expecting
+            ++m_outstanding_ends;
+            // Make sure we have room for the matching end bracket as well.
+            // That way, unless the user is messing with unbalanced brackets, there is no way we
+            // would throw an exception for lack of memory on the matching end bracket
+            m_brackets.push_back(bracket_note{bracket_type::begin, m_accesses.size(), text});
+            m_brackets.reserve(m_brackets.size() + m_outstanding_ends);
+        }
+    }
+
+    void push_end_bracket(const char *text) noexcept {
         if (m_log_type.has_annotations()) {
-            if (type == bracket_type::begin) {
-                // make sure we have room for end bracket as well. that way,
-                // unless the user use unbalanced brackets, there is no way we
-                // would throw an exception for lack of memory on and end bracket
-                m_brackets.reserve(m_brackets.size() + 2);
+            // If we failed to push, it was because the system is completely screwed anyway *and* the
+            // user is using unbalanced brackets. Therefore, it's OK to quietly ignore the error.
+            try {
+                m_brackets.push_back(bracket_note{bracket_type::end, m_accesses.size(), text});
+            } catch (...) { // NOLINT(bugprone-empty-catch)
+            }
+            // Decrement number of outstanding end brackets we are expecting
+            if (m_outstanding_ends > 0) {
+                --m_outstanding_ends;
             }
-            m_brackets.push_back(bracket_note{.type = type, .where = m_accesses.size(), .text = text});
         }
     }
 
     /// \brief Adds a new access to the log
     /// \tparam A Type of access
     /// \param a Access object
-    /// \param text Annotation contents (added if the log
-    /// type includes annotations, ignored otherwise)
+    /// \param text Annotation contents (added if the log type includes annotations, ignored otherwise)
     template <typename A>
     void push_access(A &&a, const char *text) {
         m_accesses.push_back(std::forward<A>(a));
diff --git a/src/cartesi/util.lua b/src/cartesi/util.lua
index f050ad64d..d80d5d0d6 100644
--- a/src/cartesi/util.lua
+++ b/src/cartesi/util.lua
@@ -202,10 +202,11 @@ local function hexhash8(hash) return string.sub(hexhash(hash), 1, 8) end
 local function accessdatastring(data, data_hash, data_log2_size, address)
     local data_size = 1 << data_log2_size
     if data_log2_size == 3 then
+        if not data then return "???(no written data)" end
         if data_size < #data then
             -- access data is  smaller than the tree leaf size
             -- the logged data is the entire tree leaf, but we only need the data that was accessed
-            local leaf_aligned_address = address & ~((1 << cartesi.TREE_LOG2_WORD_SIZE) - 1)
+            local leaf_aligned_address = (address >> cartesi.TREE_LOG2_WORD_SIZE) << cartesi.TREE_LOG2_WORD_SIZE
             local word_offset = address - leaf_aligned_address
             data = data:sub(word_offset + 1, word_offset + data_size)
         end
diff --git a/src/clint-factory.cpp b/src/clint-factory.cpp
index c6f34a689..24e323932 100644
--- a/src/clint-factory.cpp
+++ b/src/clint-factory.cpp
@@ -18,22 +18,14 @@
 
 #include "clint-factory.h"
 #include "clint.h"
-#include "machine.h"
 #include "pma-constants.h"
 #include "pma.h"
 
 namespace cartesi {
 
-/// \brief CLINT device peek callback. See ::pma_peek.
-static bool clint_peek(const pma_entry &pma, const machine & /*m*/, uint64_t page_offset,
-    const unsigned char **page_data, unsigned char * /*scratch*/) {
-    *page_data = nullptr;
-    return (page_offset % PMA_PAGE_SIZE) == 0 && page_offset < pma.get_length();
-}
-
 pma_entry make_clint_pma_entry(uint64_t start, uint64_t length) {
     const pma_entry::flags f{.R = true, .W = true, .X = false, .IR = false, .IW = false, .DID = PMA_ISTART_DID::CLINT};
-    return make_device_pma_entry("CLINT device", start, length, clint_peek, &clint_driver).set_flags(f);
+    return make_device_pma_entry("CLINT device", start, length, pma_peek_pristine, &clint_driver).set_flags(f);
 }
 
 } // namespace cartesi
diff --git a/src/find-pma-entry.h b/src/find-pma-entry.h
index 1e2b223b9..1cb857ca4 100644
--- a/src/find-pma-entry.h
+++ b/src/find-pma-entry.h
@@ -31,6 +31,7 @@ namespace cartesi {
 /// \returns PMA entry where word falls, or empty sentinel.
 template <typename T, typename STATE_ACCESS>
 auto &find_pma_entry(STATE_ACCESS &a, uint64_t paddr, uint64_t &index) {
+    [[maybe_unused]] auto note = a.make_scoped_note("find_pma_entry");
     index = 0;
     while (true) {
         auto &pma = a.read_pma_entry(index);
diff --git a/src/htif-factory.cpp b/src/htif-factory.cpp
index 47eff8db4..4754b8ccc 100644
--- a/src/htif-factory.cpp
+++ b/src/htif-factory.cpp
@@ -18,23 +18,14 @@
 
 #include "htif-factory.h"
 #include "htif.h"
-#include "machine-runtime-config.h"
-#include "machine.h"
 #include "pma-constants.h"
 #include "pma.h"
 
 namespace cartesi {
 
-/// \brief HTIF device peek callback. See ::pma_peek.
-static bool htif_peek(const pma_entry &pma, const machine & /*m*/, uint64_t page_offset,
-    const unsigned char **page_data, unsigned char * /*scratch*/) {
-    *page_data = nullptr;
-    return (page_offset % PMA_PAGE_SIZE) == 0 && page_offset < pma.get_length();
-}
-
 pma_entry make_htif_pma_entry(uint64_t start, uint64_t length) {
     const pma_entry::flags f{.R = true, .W = true, .X = false, .IR = false, .IW = false, .DID = PMA_ISTART_DID::HTIF};
-    return make_device_pma_entry("HTIF device", start, length, htif_peek, &htif_driver).set_flags(f);
+    return make_device_pma_entry("HTIF device", start, length, pma_peek_pristine, &htif_driver).set_flags(f);
 }
 
 } // namespace cartesi
diff --git a/src/htif-factory.h b/src/htif-factory.h
index 9a6807682..1bba5844c 100644
--- a/src/htif-factory.h
+++ b/src/htif-factory.h
@@ -19,7 +19,6 @@
 
 #include <cstdint>
 
-#include "machine-runtime-config.h"
 #include "pma.h"
 
 namespace cartesi {
diff --git a/src/i-state-access.h b/src/i-state-access.h
index 2b2fad014..104e27d57 100644
--- a/src/i-state-access.h
+++ b/src/i-state-access.h
@@ -28,6 +28,10 @@
 #include "meta.h"
 #include "tlb.h"
 
+#ifdef DUMP_STATE_ACCESS
+#include "pm-type-name.h"
+#endif
+
 namespace cartesi {
 
 // Forward declarations
@@ -91,11 +95,22 @@ class i_state_access { // CRTP
         return derived().do_get_naked_state();
     }
 
-    /// \brief Adds an annotation bracket to the log
-    /// \param type Type of bracket
+    /// \brief Adds a begin bracket annotation to the log
+    /// \param text String with the text for the annotation
+    void push_begin_bracket(const char *text) {
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "----> begin %s (%s)\n", text, get_name());
+#endif
+        return derived().do_push_begin_bracket(text);
+    }
+
+    /// \brief Adds an end bracket annotation to the log
     /// \param text String with the text for the annotation
-    void push_bracket(bracket_type type, const char *text) {
-        return derived().do_push_bracket(type, text);
+    void push_end_bracket(const char *text) {
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "<---- end %s (%s)\n", text, get_name());
+#endif
+        return derived().do_push_end_bracket(text);
     }
 
     /// \brief Adds annotations to the state, bracketing a scope
@@ -106,511 +121,912 @@ class i_state_access { // CRTP
     }
 
     /// \brief Reads from general-purpose register.
-    /// \param reg Register index.
+    /// \param i Register index.
     /// \returns Register value.
-    uint64_t read_x(int reg) {
-        return derived().do_read_x(reg);
+    uint64_t read_x(int i) {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_x(i);
+        fprintf(stderr, "%s::read_x(%d) = %llu(0x%llx)\n", get_name(), i, val, val);
+        return val;
+#else
+        return derived().do_read_x(i);
+#endif
     }
 
     /// \brief Writes register to general-purpose register.
-    /// \param reg Register index.
+    /// \param i Register index.
     /// \param val New register value.
     /// \details Writes to register zero *break* the machine.
     /// There is an assertion to catch this, but NDEBUG will let the value pass through.
-    void write_x(int reg, uint64_t val) {
-        return derived().do_write_x(reg, val);
+    void write_x(int i, uint64_t val) {
+        derived().do_write_x(i, val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_x(%d, %llu(0x%llx))\n", get_name(), i, val, val);
+#endif
     }
 
     /// \brief Reads from floating-point register.
-    /// \param reg Register index.
+    /// \param i Register index.
     /// \returns Register value.
-    uint64_t read_f(int reg) {
-        return derived().do_read_f(reg);
+    uint64_t read_f(int i) {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_f(i);
+        fprintf(stderr, "%s::read_f(%d) = %llu(0x%llx)\n", get_name(), i, val, val);
+        return val;
+#else
+        return derived().do_read_f(i);
+#endif
     }
 
     /// \brief Writes register to floating-point register.
-    /// \param reg Register index.
+    /// \param i Register index.
     /// \param val New register value.
-    void write_f(int reg, uint64_t val) {
-        return derived().do_write_f(reg, val);
+    void write_f(int i, uint64_t val) {
+        derived().do_write_f(i, val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_f(%d, %llu(%llx))\n", get_name(), i, val, val);
+#endif
     }
 
     /// \brief Reads the program counter.
     /// \returns Register value.
     uint64_t read_pc() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_pc();
+        fprintf(stderr, "%s::read_pc() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_pc();
+#endif
     }
 
     /// \brief Writes the program counter.
     /// \param val New register value.
     void write_pc(uint64_t val) {
-        return derived().do_write_pc(val);
+        derived().do_write_pc(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_pc(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Writes CSR fcsr.
     /// \param val New register value.
     void write_fcsr(uint64_t val) {
-        return derived().do_write_fcsr(val);
+        derived().do_write_fcsr(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_fcsr(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR fcsr.
     /// \returns Register value.
     uint64_t read_fcsr() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_fcsr();
+        fprintf(stderr, "%s::read_fcsr() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_fcsr();
+#endif
     }
 
     /// \brief Reads CSR icycleinstret.
     /// \returns Register value.
     uint64_t read_icycleinstret() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_icycleinstret();
+        fprintf(stderr, "%s::read_icycleinstret() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_icycleinstret();
+#endif
     }
 
     /// \brief Writes CSR icycleinstret.
     /// \param val New register value.
     void write_icycleinstret(uint64_t val) {
-        return derived().do_write_icycleinstret(val);
+        derived().do_write_icycleinstret(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_icycleinstret(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR mvendorid.
     /// \returns Register value.
     uint64_t read_mvendorid() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_mvendorid();
+        fprintf(stderr, "%s::read_mvendorid() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_mvendorid();
+#endif
     }
 
     /// \brief Reads CSR marchid.
     /// \returns Register value.
     uint64_t read_marchid() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_marchid();
+        fprintf(stderr, "%s::read_marchid() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_marchid();
+#endif
     }
 
     /// \brief Reads CSR mimpid.
     /// \returns Register value.
     uint64_t read_mimpid() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_mimpid();
+        fprintf(stderr, "%s::read_mimpid() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_mimpid();
+#endif
     }
 
     /// \brief Reads CSR mcycle.
     /// \returns Register value.
     uint64_t read_mcycle() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_mcycle();
+        fprintf(stderr, "%s::read_mcycle() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_mcycle();
+#endif
     }
 
     /// \brief Writes CSR mcycle.
     /// \param val New register value.
     void write_mcycle(uint64_t val) {
-        return derived().do_write_mcycle(val);
+        derived().do_write_mcycle(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_mcycle(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR mstatus.
     /// \returns Register value.
     uint64_t read_mstatus() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_mstatus();
+        fprintf(stderr, "%s::read_mstatus() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_mstatus();
+#endif
     }
 
     /// \brief Writes CSR mstatus.
     /// \param val New register value.
     void write_mstatus(uint64_t val) {
-        return derived().do_write_mstatus(val);
+        derived().do_write_mstatus(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_mstatus(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR menvcfg.
     /// \returns Register value.
     uint64_t read_menvcfg() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_menvcfg();
+        fprintf(stderr, "%s::read_menvcfg() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_menvcfg();
+#endif
     }
 
     /// \brief Writes CSR menvcfg.
     /// \param val New register value.
     void write_menvcfg(uint64_t val) {
-        return derived().do_write_menvcfg(val);
+        derived().do_write_menvcfg(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_menvcfg(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR mtvec.
     /// \returns Register value.
     uint64_t read_mtvec() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_mtvec();
+        fprintf(stderr, "%s::read_mtvec() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_mtvec();
+#endif
     }
 
     /// \brief Writes CSR mtvec.
     /// \param val New register value.
     void write_mtvec(uint64_t val) {
-        return derived().do_write_mtvec(val);
+        derived().do_write_mtvec(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_mtvec(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR mscratch.
     /// \returns Register value.
     uint64_t read_mscratch() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_mscratch();
+        fprintf(stderr, "%s::read_mscratch() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_mscratch();
+#endif
     }
 
     /// \brief Writes CSR mscratch.
     /// \param val New register value.
     void write_mscratch(uint64_t val) {
-        return derived().do_write_mscratch(val);
+        derived().do_write_mscratch(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_mscratch(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR mepc.
     /// \returns Register value.
     uint64_t read_mepc() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_mepc();
+        fprintf(stderr, "%s::read_mepc() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_mepc();
+#endif
     }
 
     /// \brief Writes CSR mepc.
     /// \param val New register value.
     void write_mepc(uint64_t val) {
-        return derived().do_write_mepc(val);
+        derived().do_write_mepc(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_mepc(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR mcause.
     /// \returns Register value.
     uint64_t read_mcause() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_mcause();
+        fprintf(stderr, "%s::read_mcause() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_mcause();
+#endif
     }
 
     /// \brief Writes CSR mcause.
     /// \param val New register value.
     void write_mcause(uint64_t val) {
-        return derived().do_write_mcause(val);
+        derived().do_write_mcause(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_mcause(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR mtval.
     /// \returns Register value.
     uint64_t read_mtval() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_mtval();
+        fprintf(stderr, "%s::read_mtval() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_mtval();
+#endif
     }
 
     /// \brief Writes CSR mtval.
     /// \param val New register value.
     void write_mtval(uint64_t val) {
-        return derived().do_write_mtval(val);
+        derived().do_write_mtval(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_mtval(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR misa.
     /// \returns Register value.
     uint64_t read_misa() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_misa();
+        fprintf(stderr, "%s::read_misa() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_misa();
+#endif
     }
 
     /// \brief Writes CSR misa.
     /// \param val New register value.
     void write_misa(uint64_t val) {
-        return derived().do_write_misa(val);
+        derived().do_write_misa(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_misa(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR mie.
     /// \returns Register value.
     uint64_t read_mie() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_mie();
+        fprintf(stderr, "%s::read_mie() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_mie();
+#endif
     }
 
     /// \brief Writes CSR mie.
     /// \param val New register value.
     void write_mie(uint64_t val) {
-        return derived().do_write_mie(val);
+        derived().do_write_mie(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_mie(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR mip.
     /// \returns Register value.
     uint64_t read_mip() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_mip();
+        fprintf(stderr, "%s::read_mip() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_mip();
+#endif
     }
 
     /// \brief Writes CSR mip.
     /// \param val New register value.
     void write_mip(uint64_t val) {
-        return derived().do_write_mip(val);
+        derived().do_write_mip(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_mip(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR medeleg.
     /// \returns Register value.
     uint64_t read_medeleg() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_medeleg();
+        fprintf(stderr, "%s::read_medeleg() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_medeleg();
+#endif
     }
 
     /// \brief Writes CSR medeleg.
     /// \param val New register value.
     void write_medeleg(uint64_t val) {
-        return derived().do_write_medeleg(val);
+        derived().do_write_medeleg(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_medeleg(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR mideleg.
     /// \returns Register value.
     uint64_t read_mideleg() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_mideleg();
+        fprintf(stderr, "%s::read_mideleg() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_mideleg();
+#endif
     }
 
     /// \brief Writes CSR mideleg.
     /// \param val New register value.
     void write_mideleg(uint64_t val) {
-        return derived().do_write_mideleg(val);
+        derived().do_write_mideleg(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_mideleg(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR iprv.
     /// \returns Register value.
     uint64_t read_iprv() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_iprv();
+        fprintf(stderr, "%s::read_iprv() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_iprv();
+#endif
     }
 
     /// \brief Writes CSR iprv.
     /// \param val New register value.
     void write_iprv(uint64_t val) {
-        return derived().do_write_iprv(val);
+        derived().do_write_iprv(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_iprv(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR iflags_X.
     /// \returns Register value.
     uint64_t read_iflags_X() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_iflags_X();
+        fprintf(stderr, "%s::read_iflags_X() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_iflags_X();
+#endif
     }
 
     /// \brief Writes CSR iflags_X.
     /// \param val New register value.
     void write_iflags_X(uint64_t val) {
-        return derived().do_write_iflags_X(val);
+        derived().do_write_iflags_X(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_iflags_X(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR iflags_Y.
     /// \returns Register value.
     uint64_t read_iflags_Y() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_iflags_Y();
+        fprintf(stderr, "%s::read_iflags_Y() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_iflags_Y();
+#endif
     }
 
     /// \brief Writes CSR iflags_Y.
     /// \param val New register value.
     void write_iflags_Y(uint64_t val) {
-        return derived().do_write_iflags_Y(val);
+        derived().do_write_iflags_Y(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_iflags_Y(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR iflags_H.
     /// \returns Register value.
     uint64_t read_iflags_H() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_iflags_H();
+        fprintf(stderr, "%s::read_iflags_H() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_iflags_H();
+#endif
     }
 
     /// \brief Writes CSR iflags_H.
     /// \param val New register value.
     void write_iflags_H(uint64_t val) {
-        return derived().do_write_iflags_H(val);
+        derived().do_write_iflags_H(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_iflags_H(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR mcounteren.
     /// \returns Register value.
     uint64_t read_mcounteren() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_mcounteren();
+        fprintf(stderr, "%s::read_mcounteren() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_mcounteren();
+#endif
     }
 
     /// \brief Writes CSR mcounteren.
     /// \param val New register value.
     void write_mcounteren(uint64_t val) {
-        return derived().do_write_mcounteren(val);
+        derived().do_write_mcounteren(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_mcounteren(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR senvcfg.
     /// \returns Register value.
     uint64_t read_senvcfg() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_senvcfg();
+        fprintf(stderr, "%s::read_senvcfg() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_senvcfg();
+#endif
     }
 
     /// \brief Writes CSR senvcfg.
     /// \param val New register value.
     void write_senvcfg(uint64_t val) {
-        return derived().do_write_senvcfg(val);
+        derived().do_write_senvcfg(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_senvcfg(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR stvec.
     /// \returns Register value.
     uint64_t read_stvec() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_stvec();
+        fprintf(stderr, "%s::read_stvec() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_stvec();
+#endif
     }
 
     /// \brief Writes CSR stvec.
     /// \param val New register value.
     void write_stvec(uint64_t val) {
-        return derived().do_write_stvec(val);
+        derived().do_write_stvec(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_stvec(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR sscratch.
     /// \returns Register value.
     uint64_t read_sscratch() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_sscratch();
+        fprintf(stderr, "%s::read_sscratch() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_sscratch();
+#endif
     }
 
     /// \brief Writes CSR sscratch.
     /// \param val New register value.
     void write_sscratch(uint64_t val) {
-        return derived().do_write_sscratch(val);
+        derived().do_write_sscratch(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_sscratch(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR sepc.
     /// \returns Register value.
     uint64_t read_sepc() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_sepc();
+        fprintf(stderr, "%s::read_sepc() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_sepc();
+#endif
     }
 
     /// \brief Writes CSR sepc.
     /// \param val New register value.
     void write_sepc(uint64_t val) {
-        return derived().do_write_sepc(val);
+        derived().do_write_sepc(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_sepc(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR scause.
     /// \returns Register value.
     uint64_t read_scause() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_scause();
+        fprintf(stderr, "%s::read_scause() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_scause();
+#endif
     }
 
     /// \brief Writes CSR scause.
     /// \param val New register value.
     void write_scause(uint64_t val) {
-        return derived().do_write_scause(val);
+        derived().do_write_scause(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_scause(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR stval.
     /// \returns Register value.
     uint64_t read_stval() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_stval();
+        fprintf(stderr, "%s::read_stval() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_stval();
+#endif
     }
 
     /// \brief Writes CSR stval.
     /// \param val New register value.
     void write_stval(uint64_t val) {
-        return derived().do_write_stval(val);
+        derived().do_write_stval(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_stval(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR satp.
     /// \returns Register value.
     uint64_t read_satp() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_satp();
+        fprintf(stderr, "%s::read_satp() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_satp();
+#endif
     }
 
     /// \brief Writes CSR satp.
     /// \param val New register value.
     void write_satp(uint64_t val) {
-        return derived().do_write_satp(val);
+        derived().do_write_satp(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_satp(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR scounteren.
     /// \returns Register value.
     uint64_t read_scounteren() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_scounteren();
+        fprintf(stderr, "%s::read_scounteren() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_scounteren();
+#endif
     }
 
     /// \brief Writes CSR scounteren.
     /// \param val New register value.
     void write_scounteren(uint64_t val) {
-        return derived().do_write_scounteren(val);
+        derived().do_write_scounteren(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_scounteren(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR ilrsc.
     /// \returns Register value.
     /// \details This is Cartesi-specific.
     uint64_t read_ilrsc() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_ilrsc();
+        fprintf(stderr, "%s::read_ilrsc() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_ilrsc();
+#endif
     }
 
     /// \brief Writes CSR ilrsc.
     /// \param val New register value.
     /// \details This is Cartesi-specific.
     void write_ilrsc(uint64_t val) {
-        return derived().do_write_ilrsc(val);
+        derived().do_write_ilrsc(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_ilrsc(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CSR iunrep.
     /// \returns Register value.
     /// \details This is Cartesi-specific.
     uint64_t read_iunrep() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_iunrep();
+        fprintf(stderr, "%s::read_iunrep() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_iunrep();
+#endif
     }
 
     /// \brief Writes CSR iunrep.
     /// \param val New register value.
     /// \details This is Cartesi-specific.
     void write_iunrep(uint64_t val) {
-        return derived().do_write_iunrep(val);
+        derived().do_write_iunrep(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_iunrep(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads CLINT's mtimecmp.
     /// \returns Register value.
     uint64_t read_clint_mtimecmp() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_clint_mtimecmp();
+        fprintf(stderr, "%s::read_clint_mtimecmp() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_clint_mtimecmp();
+#endif
     }
 
     /// \brief Writes CLINT's mtimecmp.
     /// \param val New register value.
     void write_clint_mtimecmp(uint64_t val) {
-        return derived().do_write_clint_mtimecmp(val);
+        derived().do_write_clint_mtimecmp(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_clint_mtimecmp(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads PLIC's girqpend.
     /// \returns Register value.
     uint64_t read_plic_girqpend() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_plic_girqpend();
+        fprintf(stderr, "%s::read_plic_girqpend() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_plic_girqpend();
+#endif
     }
 
     /// \brief Writes PLIC's girqpend.
     /// \param val New register value.
     void write_plic_girqpend(uint64_t val) {
-        return derived().do_write_plic_girqpend(val);
+        derived().do_write_plic_girqpend(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_plic_girqpend(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads PLIC's girqsrvd.
     /// \returns Register value.
     uint64_t read_plic_girqsrvd() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_plic_girqsrvd();
+        fprintf(stderr, "%s::read_plic_girqsrvd() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_plic_girqsrvd();
+#endif
     }
 
     /// \brief Writes PLIC's girqsrvd.
     /// \param val New register value.
     void write_plic_girqsrvd(uint64_t val) {
-        return derived().do_write_plic_girqsrvd(val);
+        derived().do_write_plic_girqsrvd(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_plic_girqsrvd(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads HTIF's fromhost.
     /// \returns Register value.
     uint64_t read_htif_fromhost() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_htif_fromhost();
+        fprintf(stderr, "%s::read_htif_fromhost() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_htif_fromhost();
+#endif
     }
 
     /// \brief Writes HTIF's fromhost.
     /// \param val New register value.
     void write_htif_fromhost(uint64_t val) {
-        return derived().do_write_htif_fromhost(val);
+        derived().do_write_htif_fromhost(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_htif_fromhost(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads HTIF's tohost.
     /// \returns Register value.
     uint64_t read_htif_tohost() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_htif_tohost();
+        fprintf(stderr, "%s::read_htif_tohost() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_htif_tohost();
+#endif
     }
 
     /// \brief Writes HTIF's tohost.
     /// \param val New register value.
     void write_htif_tohost(uint64_t val) {
-        return derived().do_write_htif_tohost(val);
+        derived().do_write_htif_tohost(val);
+#ifdef DUMP_STATE_ACCESS
+        fprintf(stderr, "%s::write_htif_tohost(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     /// \brief Reads HTIF's ihalt.
     /// \returns Register value.
     uint64_t read_htif_ihalt() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_htif_ihalt();
+        fprintf(stderr, "%s::read_htif_ihalt() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_htif_ihalt();
+#endif
     }
 
     /// \brief Reads HTIF's iconsole.
     /// \returns Register value.
     uint64_t read_htif_iconsole() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_htif_iconsole();
+        fprintf(stderr, "%s::read_htif_iconsole() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_htif_iconsole();
+#endif
     }
 
     /// \brief Reads HTIF's iyield.
     /// \returns Register value.
     uint64_t read_htif_iyield() {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_read_htif_iyield();
+        fprintf(stderr, "%s::read_htif_iyield() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_htif_iyield();
+#endif
     }
 
     /// \brief Reads PMA entry at a given index.
     /// \param index Index of PMA
     pma_entry &read_pma_entry(uint64_t index) {
+#ifdef DUMP_STATE_ACCESS
+        auto &pma = derived().do_read_pma_entry(index);
+        fprintf(stderr, "%s::read_pma_entry(%llu) = {%s, 0x%llx, 0x%llx}\n", get_name(), index,
+            pma_get_DID_name(pma.get_istart_DID()), pma.get_start(), pma.get_length());
+        return pma;
+#else
         return derived().do_read_pma_entry(index);
+#endif
+    }
+
+    /// \brief Converts a target physical address to the implementation-defined fast address
+    /// \param paddr Target physical address to convert
+    /// \param pma_index Index of PMA where address falls
+    /// \returns Corresponding implementation-defined fast address
+    fast_addr get_faddr(uint64_t paddr, uint64_t pma_index) const {
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().do_get_faddr(paddr, pma_index);
+        const char *fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
+        fprintf(stderr, "%s::get_faddr(%llu(0x%llx)) = %s{%llu(0x%llx)}\n", get_name(), paddr, paddr, fast_addr_name,
+            val, val);
+        return val;
+#else
+        return derived().do_get_faddr(paddr, pma_index);
+#endif
     }
 
     /// \brief Reads a chunk of data from a memory PMA range.
@@ -642,7 +1058,7 @@ class i_state_access { // CRTP
     /// \param write_length_log2_size Log2 size of the total write length.
     void write_memory_with_padding(uint64_t paddr, const unsigned char *data, uint64_t data_length,
         int write_length_log2_size) {
-        return derived().do_write_memory_with_padding(paddr, data, data_length, write_length_log2_size);
+        derived().do_write_memory_with_padding(paddr, data, data_length, write_length_log2_size);
     }
 
     /// \brief Reads a word from memory.
@@ -655,7 +1071,15 @@ class i_state_access { // CRTP
     template <typename T, typename A = T>
     void read_memory_word(fast_addr faddr, uint64_t pma_index, T *pval) {
         static_assert(std::is_integral<T>::value && sizeof(T) <= sizeof(uint64_t), "unsupported type");
-        return derived().template do_read_memory_word<T, A>(faddr, pma_index, pval);
+#ifdef DUMP_STATE_ACCESS
+        derived().template do_read_memory_word<T, A>(faddr, pma_index, pval);
+        const char *fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
+        fprintf(stderr, "%s::read_memory_word<%s,%s>(%s{0x%llx}, %llu) = %llu(0x%llx)\n", get_name(), pm_type_name_v<T>,
+            pm_type_name_v<A>, fast_addr_name, faddr, pma_index, static_cast<uint64_t>(*pval),
+            static_cast<uint64_t>(*pval));
+#else
+        derived().template do_read_memory_word<T, A>(faddr, pma_index, pval);
+#endif
     }
 
     /// \brief Writes a word to memory.
@@ -670,34 +1094,60 @@ class i_state_access { // CRTP
     template <typename T, typename A = T>
     void write_memory_word(fast_addr faddr, uint64_t pma_index, T val) {
         static_assert(std::is_integral<T>::value && sizeof(T) <= sizeof(uint64_t), "unsupported type");
-        return derived().template do_write_memory_word<T, A>(faddr, pma_index, val);
+        derived().template do_write_memory_word<T, A>(faddr, pma_index, val);
+#ifdef DUMP_STATE_ACCESS
+        const char *fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
+        fprintf(stderr, "%s::write_memory_word<%s,%s>(%s{0x%llx}, %llu, %llu(0x%llx))\n", get_name(), pm_type_name_v<T>,
+            pm_type_name_v<A>, fast_addr_name, faddr, pma_index, static_cast<uint64_t>(val),
+            static_cast<uint64_t>(val));
+#endif
     }
 
     /// \brief Reads TLB's vaddr_page
     /// \tparam USE TLB set
     /// \param slot_index Slot index
     /// \returns Value in slot.
-    template <TLB_set_use USE>
+    template <TLB_set_index SET>
     uint64_t read_tlb_vaddr_page(uint64_t slot_index) {
-        return derived().template do_read_tlb_vaddr_page<USE>(slot_index);
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().template do_read_tlb_vaddr_page<SET>(slot_index);
+        fprintf(stderr, "%s::read_tlb_vaddr_page<%llu>(%llu) = 0x%llx\n", get_name(), SET, slot_index, val);
+        return val;
+#else
+        return derived().template do_read_tlb_vaddr_page<SET>(slot_index);
+#endif
     }
 
     /// \brief Reads TLB's vp_offset
     /// \tparam USE TLB set
     /// \param slot_index Slot index
     /// \returns Value in slot.
-    template <TLB_set_use USE>
+    template <TLB_set_index SET>
     fast_addr read_tlb_vp_offset(uint64_t slot_index) {
-        return derived().template do_read_tlb_vp_offset<USE>(slot_index);
+#ifdef DUMP_STATE_ACCESS
+        const char *fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
+        const auto val = derived().template do_read_tlb_vp_offset<SET>(slot_index);
+        fprintf(stderr, "%s::read_tlb_vp_offset<%llu>(%llu) = %s{0x%llx}\n", get_name(), SET, slot_index,
+            fast_addr_name, val);
+        return val;
+#else
+        return derived().template do_read_tlb_vp_offset<SET>(slot_index);
+#endif
     }
 
     /// \brief Reads TLB's pma_index
     /// \tparam USE TLB set
     /// \param slot_index Slot index
     /// \returns Value in slot.
-    template <TLB_set_use USE>
+    template <TLB_set_index SET>
     uint64_t read_tlb_pma_index(uint64_t slot_index) {
-        return derived().template do_read_tlb_pma_index<USE>(slot_index);
+#ifdef DUMP_STATE_ACCESS
+        const auto val = derived().template do_read_tlb_pma_index<SET>(slot_index);
+        fprintf(stderr, "%s::read_tlb_pma_index<%llu>(%llu) = %llu(0x%llx)\n", get_name(), SET, slot_index, val, val);
+        return val;
+#else
+        return derived().template do_read_tlb_pma_index<SET>(slot_index);
+#endif
     }
 
     /// \brief Writes to a TLB slot
@@ -708,17 +1158,14 @@ class i_state_access { // CRTP
     /// \param pma_index Value to write
     /// \detail Writes to the TLB must be modify all fields atomically to prevent an inconsistent state.
     /// This simplifies all state access implementations.
-    template <TLB_set_use USE>
+    template <TLB_set_index SET>
     void write_tlb(uint64_t slot_index, uint64_t vaddr_page, fast_addr vp_offset, uint64_t pma_index) {
-        return derived().template do_write_tlb<USE>(slot_index, vaddr_page, vp_offset, pma_index);
-    }
-
-    /// \brief Converts a target physical address to the implementation-defined fast address
-    /// \param paddr Target physical address to convert
-    /// \param pma_index Index of PMA where address falls
-    /// \returns Correspnding implementation-defined fast address
-    fast_addr get_faddr(uint64_t paddr, uint64_t pma_index) const {
-        return derived().do_get_faddr(paddr, pma_index);
+        derived().template do_write_tlb<SET>(slot_index, vaddr_page, vp_offset, pma_index);
+#ifdef DUMP_STATE_ACCESS
+        const char *fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
+        fprintf(stderr, "%s::write_tlb<%llu>(%llu, 0x%llx, %s{0x%llx}, %llu)\n", get_name(), SET, slot_index,
+            vaddr_page, fast_addr_name, vp_offset, pma_index);
+#endif
     }
 
     /// \brief Marks a page as dirty
@@ -730,17 +1177,17 @@ class i_state_access { // CRTP
     /// have been marked dirty. When a page leaves the write TLB, it is marked dirty.
     /// If the state belongs to a host machine, then this call MUST be forwarded to machine::mark_dirty_page();
     void mark_dirty_page(fast_addr faddr, uint64_t pma_index) {
-        return derived().do_mark_dirty_page(faddr, pma_index);
+        derived().do_mark_dirty_page(faddr, pma_index);
     }
 
     /// \brief Writes a character to the console
     /// \param c Character to output
     void putchar(uint8_t c) {
-        return derived().do_putchar(c);
+        derived().do_putchar(c);
     }
 
     // ---
-    // These methods ONLY need to be implemented when state belongs to non-reproducible host machine
+    // These methods ONLY need to be implemented when state belongs to non-reproducible host machines
     // ---
 
     /// \brief Poll for external interrupts.
@@ -773,8 +1220,11 @@ class i_state_access { // CRTP
     }
 #endif
 
-protected:
+    constexpr const char *get_name() const {
+        return derived().do_get_name();
+    }
 
+protected:
     /// \brief Default implementation when state does not belong to non-reproducible host machine
     bool do_get_soft_yield() { // NOLINT(readability-convert-member-functions-to-static)
         return false;
@@ -791,6 +1241,18 @@ class i_state_access { // CRTP
         return -1;
     }
 
+    /// \brief For state access classes that do not need annotations
+    void do_push_begin_bracket(const char * /*text*/) {}
+
+    /// \brief For state access classes that do not need annotations
+    void do_push_end_bracket(const char * /*text*/) {}
+
+#ifndef DUMP_STATE_ACCESS
+    /// \brief For state access classes that do not need annotations
+    int do_make_scoped_note(const char * /*text*/) {
+        return 0;
+    }
+#endif
 };
 
 /// \brief SFINAE test implementation of the i_state_access interface
diff --git a/src/i-uarch-state-access.h b/src/i-uarch-state-access.h
index 0f74793d5..875fe7f35 100644
--- a/src/i-uarch-state-access.h
+++ b/src/i-uarch-state-access.h
@@ -20,7 +20,7 @@
 #include <cstdint>
 
 #include "bracket-note.h"
-#include "pma.h"
+#include "tlb.h"
 
 namespace cartesi {
 
@@ -39,11 +39,22 @@ class i_uarch_state_access { // CRTP
     }
 
 public:
-    /// \brief Adds an annotation bracket to the log
-    /// \param type Type of bracket
+    /// \brief Adds a begin bracket annotation to the log
     /// \param text String with the text for the annotation
-    void push_bracket(bracket_type type, const char *text) {
-        return derived().do_push_bracket(type, text);
+    void push_begin_bracket(const char *text) {
+#ifdef DUMP_UARCH_STATE_ACCESS
+        printf("----> begin %s (%s)\n", text, get_name());
+#endif
+        return derived().do_push_begin_bracket(text);
+    }
+
+    /// \brief Adds an end bracket annotation to the log
+    /// \param text String with the text for the annotation
+    void push_end_bracket(const char *text) {
+#ifdef DUMP_UARCH_STATE_ACCESS
+        printf("<---- end %s (%s)\n", text, get_name());
+#endif
+        return derived().do_push_end_bracket(text);
     }
 
     /// \brief Adds annotations to the state, bracketing a scope
@@ -53,54 +64,126 @@ class i_uarch_state_access { // CRTP
         return derived().do_make_scoped_note(text);
     }
 
-    auto read_x(int r) {
-        return derived().do_read_x(r);
+    auto read_x(int i) {
+#ifdef DUMP_UARCH_STATE_ACCESS
+        const auto val = derived().do_read_x(i);
+        printf("%s::read_x(%d) = %llu(0x%llx)\n", get_name(), i, val, val);
+        return val;
+#else
+        return derived().do_read_x(i);
+#endif
     }
 
-    auto write_x(int r, uint64_t v) {
-        return derived().do_write_x(r, v);
+    auto write_x(int i, uint64_t val) {
+        derived().do_write_x(i, val);
+#ifdef DUMP_UARCH_STATE_ACCESS
+        printf("%s::write_x(%d, %llu)\n", get_name(), i, val);
+#endif
     }
 
     auto read_pc() {
+#ifdef DUMP_UARCH_STATE_ACCESS
+        const auto val = derived().do_read_pc();
+        printf("%s::read_pc() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_pc();
+#endif
     }
 
-    auto write_pc(uint64_t v) {
-        return derived().do_write_pc(v);
+    auto write_pc(uint64_t val) {
+        derived().do_write_pc(val);
+#ifdef DUMP_UARCH_STATE_ACCESS
+        printf("%s::write_pc(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     auto read_cycle() {
+#ifdef DUMP_UARCH_STATE_ACCESS
+        const auto val = derived().do_read_cycle();
+        printf("%s::read_cycle() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_cycle();
+#endif
     }
 
     auto read_halt_flag() {
+#ifdef DUMP_UARCH_STATE_ACCESS
+        const auto val = derived().do_read_halt_flag();
+        printf("%s::read_halt_flag() = %llu(0x%llx)\n", get_name(), val, val);
+        return val;
+#else
         return derived().do_read_halt_flag();
+#endif
     }
 
-    auto set_halt_flag() {
-        return derived().do_set_halt_flag();
-    }
-
-    auto reset_halt_flag() {
-        return derived().do_reset_halt_flag();
+    auto write_halt_flag(uint64_t val) {
+        derived().do_write_halt_flag(val);
+#ifdef DUMP_UARCH_STATE_ACCESS
+        printf("%s::write_halt_flag(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
-    auto write_cycle(uint64_t v) {
-        return derived().do_write_cycle(v);
+    auto write_cycle(uint64_t val) {
+        derived().do_write_cycle(val);
+#ifdef DUMP_UARCH_STATE_ACCESS
+        printf("%s::write_cycle(%llu(0x%llx))\n", get_name(), val, val);
+#endif
     }
 
     uint64_t read_word(uint64_t paddr) {
+#ifdef DUMP_UARCH_STATE_ACCESS
+        const auto val = derived().do_read_word(paddr);
+        printf("%s::read_word(phys_addr{0x%llx}) = %llu(0x%llx)\n", get_name(), paddr, val, val);
+        return val;
+#else
         return derived().do_read_word(paddr);
+#endif
     }
 
-    void write_word(uint64_t paddr, uint64_t data) {
-        return derived().do_write_word(paddr, data);
+    void write_word(uint64_t paddr, uint64_t val) {
+        derived().do_write_word(paddr, val);
+#ifdef DUMP_UARCH_STATE_ACCESS
+        printf("%s::write_word(phys_addr{0x%llx}, %llu(0x%llx))\n", get_name(), paddr, val, val);
+#endif
     }
 
     /// \brief Resets uarch to pristine state
     void reset_state() {
         return derived().do_reset_state();
     }
+
+    void putchar(uint8_t c) {
+        derived().do_putchar(c);
+    }
+
+    void mark_dirty_page(uint64_t paddr, uint64_t pma_index) {
+        return derived().do_mark_dirty_page(paddr, pma_index);
+    }
+
+    void write_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset,
+        uint64_t pma_index) {
+        derived().do_write_tlb(set_index, slot_index, vaddr_page, vp_offset, pma_index);
+    }
+
+    constexpr const char *get_name() const {
+        return derived().do_get_name();
+    }
+
+private:
+    /// \brief For state access classes that do not need annotations
+    void do_push_begin_bracket(const char * /*text*/) {}
+
+    /// \brief For state access classes that do not need annotations
+    void do_push_end_bracket(const char * /*text*/) {}
+
+#ifndef DUMP_UARCH_STATE_ACCESS
+    /// \brief For state access classes that do not need annotations
+    int do_make_scoped_note(const char * /*text*/) {
+        return 0;
+    }
+#endif
 };
 
 } // namespace cartesi
diff --git a/src/interpret.cpp b/src/interpret.cpp
index d986d4f7e..42a879860 100644
--- a/src/interpret.cpp
+++ b/src/interpret.cpp
@@ -21,10 +21,8 @@
 #include <utility>
 
 #ifdef MICROARCHITECTURE
-#ifdef OKUARCH
-#include "uarch-machine-state-access.h"
+#include "machine-uarch-bridge-state-access.h"
 #include "uarch-runtime.h"
-#endif
 #else
 #include "record-step-state-access.h"
 #include "replay-step-state-access.h"
@@ -360,7 +358,6 @@ static NO_INLINE uint64_t raise_exception(STATE_ACCESS a, uint64_t pc, uint64_t
         // this is not performed in the instruction hot loop as an optimization.
         tval = static_cast<uint16_t>(tval);
     }
-
 #if defined(DUMP_EXCEPTIONS) || defined(DUMP_MMU_EXCEPTIONS) || defined(DUMP_INTERRUPTS) ||                            \
     defined(DUMP_ILLEGAL_INSN_EXCEPTIONS)
     {
@@ -831,14 +828,14 @@ static FORCE_INLINE int32_t insn_get_C_SWSP_imm(uint32_t insn) {
 /// \tparam STATE_ACCESS Class of machine state accessor object.
 /// \param a Machine state accessor object.
 /// \param slot_index Slot index
-template <TLB_set_use USE, typename STATE_ACCESS>
+template <TLB_set_index SET, typename STATE_ACCESS>
 static void flush_tlb_slot(STATE_ACCESS &a, uint64_t slot_index) {
     // Make sure a valid page leaving the write TLB is marked as dirty
     // We must do this BEFORE we modify the TLB entries themselves
     // (Otherwise, we could stop uarch before it marks the page dirty but after
     // the entry is no longer in the TLB, which would cause the Merkle tree to
     // miss a dirty page.)
-    if constexpr (USE == TLB_WRITE) {
+    if constexpr (SET == TLB_WRITE) {
         const auto old_vaddr_page = a.template read_tlb_vaddr_page<TLB_WRITE>(slot_index);
         if (old_vaddr_page != TLB_INVALID_PAGE) {
             auto old_pma_index = a.template read_tlb_pma_index<TLB_WRITE>(slot_index);
@@ -851,17 +848,17 @@ static void flush_tlb_slot(STATE_ACCESS &a, uint64_t slot_index) {
     const auto vaddr_page = TLB_INVALID_PAGE;
     const auto vp_offset = i_state_access_fast_addr_t<STATE_ACCESS>{};
     const auto pma_index = TLB_INVALID_PMA_INDEX;
-    a.template write_tlb<USE>(slot_index, vaddr_page, vp_offset, pma_index);
+    a.template write_tlb<SET>(slot_index, vaddr_page, vp_offset, pma_index);
 }
 
 /// \brief Flushes out an entire TLB set
 /// \tparam USE TLB set
 /// \tparam STATE_ACCESS Class of machine state accessor object.
 /// \param a Machine state accessor object.
-template <TLB_set_use USE, typename STATE_ACCESS>
+template <TLB_set_index SET, typename STATE_ACCESS>
 static void flush_tlb_set(STATE_ACCESS &a) {
     for (uint64_t slot_index = 0; slot_index < PMA_TLB_SIZE; ++slot_index) {
-        flush_tlb_slot<USE>(a, slot_index);
+        flush_tlb_slot<SET>(a, slot_index);
     }
 }
 
@@ -898,15 +895,16 @@ static void flush_tlb_vaddr(STATE_ACCESS &a, uint64_t /* vaddr */) {
 /// \param paddr Index of PMA where paddr falls
 /// \param vp_offset Receives the new vp_offset that will be stored in the slot
 /// \returns The implementation-defined fast address corresponding to paddr
-template <TLB_set_use USE, typename STATE_ACCESS>
+template <TLB_set_index SET, typename STATE_ACCESS>
 static i_state_access_fast_addr_t<STATE_ACCESS> replace_tlb_entry(STATE_ACCESS &a, uint64_t vaddr, uint64_t paddr,
     uint64_t pma_index, i_state_access_fast_addr_t<STATE_ACCESS> &vp_offset) {
+    [[maybe_unused]] auto note = a.make_scoped_note("replace_tlb_entry");
     const auto slot_index = tlb_slot_index(vaddr);
-    flush_tlb_slot<USE>(a, slot_index);
+    flush_tlb_slot<SET>(a, slot_index);
     const auto vaddr_page = tlb_addr_page(vaddr);
     const auto faddr = a.get_faddr(paddr, pma_index);
     vp_offset = faddr - vaddr;
-    a.template write_tlb<USE>(slot_index, vaddr_page, vp_offset, pma_index);
+    a.template write_tlb<SET>(slot_index, vaddr_page, vp_offset, pma_index);
     return faddr;
 }
 
@@ -918,10 +916,10 @@ static i_state_access_fast_addr_t<STATE_ACCESS> replace_tlb_entry(STATE_ACCESS &
 /// \param paddr Corresponding physical address
 /// \param paddr Index of PMA where paddr falls
 /// \returns The implementation-defined fast address corresponding to paddr
-template <TLB_set_use USE, typename STATE_ACCESS>
+template <TLB_set_index SET, typename STATE_ACCESS>
 static FORCE_INLINE auto replace_tlb_entry(STATE_ACCESS &a, uint64_t vaddr, uint64_t paddr, uint64_t pma_index) {
     i_state_access_fast_addr_t<STATE_ACCESS> vp_offset{0};
-    return replace_tlb_entry<USE>(a, vaddr, paddr, pma_index, vp_offset);
+    return replace_tlb_entry<SET>(a, vaddr, paddr, pma_index, vp_offset);
 }
 
 /// \brief Read an aligned word from virtual memory (slow path that goes through virtual address translation).
@@ -942,6 +940,7 @@ static FORCE_INLINE auto replace_tlb_entry(STATE_ACCESS &a, uint64_t vaddr, uint
 template <typename T, typename STATE_ACCESS, bool RAISE_STORE_EXCEPTIONS = false>
 static NO_INLINE std::pair<bool, uint64_t> read_virtual_memory_slow(STATE_ACCESS a, uint64_t pc, uint64_t mcycle,
     uint64_t vaddr, T *pval) {
+    [[maybe_unused]] auto note = a.make_scoped_note("read_virtual_memory_slow");
     using U = std::make_unsigned_t<T>;
     // No support for misaligned accesses: They are handled by a trap in BBL
     if (unlikely(vaddr & (sizeof(T) - 1))) {
@@ -960,11 +959,13 @@ static NO_INLINE std::pair<bool, uint64_t> read_virtual_memory_slow(STATE_ACCESS
     const auto &pma = find_pma_entry<T>(a, paddr, pma_index);
     if (likely(pma.get_istart_R())) {
         if (likely(pma.get_istart_M())) {
+            [[maybe_unused]] auto note = a.make_scoped_note("read memory");
             const auto faddr = replace_tlb_entry<TLB_READ>(a, vaddr, paddr, pma_index);
             a.template read_memory_word(faddr, pma_index, pval);
             return {true, pc};
         }
         if (likely(pma.get_istart_IO())) {
+            [[maybe_unused]] auto note = a.make_scoped_note("read device");
             const uint64_t offset = paddr - pma.get_start();
             uint64_t val{};
             device_state_access da(a, mcycle);
@@ -993,6 +994,7 @@ static NO_INLINE std::pair<bool, uint64_t> read_virtual_memory_slow(STATE_ACCESS
 /// \returns True if succeeded, false otherwise.
 template <typename T, typename STATE_ACCESS, bool RAISE_STORE_EXCEPTIONS = false>
 static FORCE_INLINE bool read_virtual_memory(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint64_t vaddr, T *pval) {
+    [[maybe_unused]] auto note = a.make_scoped_note("read_virtual_memory");
     // Try hitting the TLB
     const auto slot_index = tlb_slot_index(vaddr);
     const auto slot_vaddr_page = a.template read_tlb_vaddr_page<TLB_READ>(slot_index);
@@ -1031,6 +1033,7 @@ static FORCE_INLINE bool read_virtual_memory(STATE_ACCESS a, uint64_t &pc, uint6
 template <typename T, typename STATE_ACCESS>
 static NO_INLINE std::pair<execute_status, uint64_t> write_virtual_memory_slow(STATE_ACCESS a, uint64_t pc,
     uint64_t mcycle, uint64_t vaddr, uint64_t val64) {
+    [[maybe_unused]] auto note = a.make_scoped_note("write_virtual_memory_slow");
     using U = std::make_unsigned_t<T>;
     // No support for misaligned accesses: They are handled by a trap in BBL
     if (unlikely(vaddr & (sizeof(T) - 1))) {
@@ -1077,6 +1080,7 @@ static NO_INLINE std::pair<execute_status, uint64_t> write_virtual_memory_slow(S
 template <typename T, typename STATE_ACCESS>
 static FORCE_INLINE execute_status write_virtual_memory(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint64_t vaddr,
     uint64_t val64) {
+    [[maybe_unused]] auto note = a.make_scoped_note("write_virtual_memory");
     // Try hitting the TLB
     const uint64_t slot_index = tlb_slot_index(vaddr);
     const uint64_t slot_vaddr_page = a.template read_tlb_vaddr_page<TLB_WRITE>(slot_index);
@@ -1087,8 +1091,8 @@ static FORCE_INLINE execute_status write_virtual_memory(STATE_ACCESS a, uint64_t
         pc = new_pc;
         return status;
     }
-    const auto pma_index = a.template read_tlb_pma_index<TLB_READ>(slot_index);
-    const auto vp_offset = a.template read_tlb_vp_offset<TLB_READ>(slot_index);
+    const auto pma_index = a.template read_tlb_pma_index<TLB_WRITE>(slot_index);
+    const auto vp_offset = a.template read_tlb_vp_offset<TLB_WRITE>(slot_index);
     const auto faddr = vaddr + vp_offset;
     a.template write_memory_word<T>(faddr, pma_index, static_cast<T>(val64));
     INC_COUNTER(a.get_statistics(), tlb_whit);
@@ -1098,6 +1102,7 @@ static FORCE_INLINE execute_status write_virtual_memory(STATE_ACCESS a, uint64_t
 template <typename STATE_ACCESS>
 static void dump_insn([[maybe_unused]] STATE_ACCESS a, [[maybe_unused]] uint64_t pc, [[maybe_unused]] uint32_t insn,
     [[maybe_unused]] const char *name) {
+    [[maybe_unused]] auto note = a.make_scoped_note("dump_insn");
 #ifdef DUMP_HIST
     a.get_naked_state().insn_hist[name]++;
 #endif
@@ -1105,13 +1110,8 @@ static void dump_insn([[maybe_unused]] STATE_ACCESS a, [[maybe_unused]] uint64_t
     dump_regs(a.get_naked_state());
 #endif
 #ifdef DUMP_INSN
-    uint64_t ppc = 0;
-    // If we are running in the microinterpreter, we may or may not be collecting a step access log.
-    // To prevent additional address translation end up in the log,
-    // the following check will always be false when MICROARCHITECTURE is defined.
-    if (std::is_same_v<STATE_ACCESS, state_access> &&
-        !translate_virtual_address<STATE_ACCESS, false>(a, &ppc, pc, PTE_XWR_X_SHIFT)) {
-        ppc = pc;
+    uint64_t ppc = pc;
+    if (!translate_virtual_address<STATE_ACCESS, false>(a, &ppc, pc, PTE_XWR_X_SHIFT)) {
         fprintf(stderr, "v    %08" PRIx64, ppc);
     } else {
         fprintf(stderr, "p    %08" PRIx64, ppc);
@@ -5389,6 +5389,7 @@ static FORCE_INLINE fetch_status fetch_translate_pc(STATE_ACCESS a, uint64_t &pc
 template <typename STATE_ACCESS>
 static FORCE_INLINE fetch_status fetch_insn(STATE_ACCESS a, uint64_t &pc, uint32_t &insn, uint64_t &last_vaddr_page,
     i_state_access_fast_addr_t<STATE_ACCESS> &last_vp_offset, uint64_t &last_pma_index) {
+    [[maybe_unused]] auto note = a.make_scoped_note("fetch_insn");
     i_state_access_fast_addr_t<STATE_ACCESS> faddr{0};
     const uint64_t pc_vaddr_page = tlb_addr_page(pc);
     // If pc is in the same page as the last pc fetch,
@@ -5397,12 +5398,16 @@ static FORCE_INLINE fetch_status fetch_insn(STATE_ACCESS a, uint64_t &pc, uint32
         faddr = pc + last_vp_offset;
     } else {
         // Not in the same page as last the fetch, we need to perform address translation
-        if (unlikely(fetch_translate_pc(a, pc, pc, last_vp_offset, last_pma_index) == fetch_status::exception)) {
+        i_state_access_fast_addr_t<STATE_ACCESS> pc_vp_offset{};
+        uint64_t pc_pma_index{};
+        if (unlikely(fetch_translate_pc(a, pc, pc, pc_vp_offset, pc_pma_index) == fetch_status::exception)) {
             return fetch_status::exception;
         }
         // Update fetch address translation cache
         last_vaddr_page = pc_vaddr_page;
-        faddr = pc + last_vp_offset;
+        last_vp_offset = pc_vp_offset;
+        last_pma_index = pc_pma_index;
+        faddr = pc + pc_vp_offset;
     }
     // The following code assumes pc is always 2-byte aligned, this is guaranteed by RISC-V spec.
     // If pc is pointing to the very last 2 bytes of a page, it's crossing a page boundary.
@@ -5415,10 +5420,14 @@ static FORCE_INLINE fetch_status fetch_insn(STATE_ACCESS a, uint64_t &pc, uint32
         if (unlikely(insn_is_uncompressed(insn))) {
             // We have to perform a new address translation to read the next 2 bytes since we changed pages.
             const uint64_t pc2 = pc + 2;
-            if (unlikely(fetch_translate_pc(a, pc, pc2, last_vp_offset, last_pma_index) == fetch_status::exception)) {
+            i_state_access_fast_addr_t<STATE_ACCESS> pc2_vp_offset{};
+            uint64_t pc2_pma_index{};
+            if (unlikely(fetch_translate_pc(a, pc, pc2, pc2_vp_offset, pc2_pma_index) == fetch_status::exception)) {
                 return fetch_status::exception;
             }
             last_vaddr_page = tlb_addr_page(pc2);
+            last_vp_offset = pc2_vp_offset;
+            last_pma_index = pc2_pma_index;
             faddr = pc2 + last_vp_offset;
             a.template read_memory_word(faddr, last_pma_index, &insn16);
             insn |= insn16 << 16;
@@ -6042,16 +6051,14 @@ interpreter_break_reason interpret(STATE_ACCESS a, uint64_t mcycle_end) {
     }
     if (status == execute_status::success_and_yield) {
         return interpreter_break_reason::yielded_softly;
-    }                                      // Reached mcycle_end
+    } // Reached mcycle_end
     assert(a.read_mcycle() == mcycle_end); // LCOV_EXCL_LINE
     return interpreter_break_reason::reached_target_mcycle;
 }
 
 #ifdef MICROARCHITECTURE
-#ifdef OKUARCH
-// Explicit instantiation for uarch_machine_state_access
-template interpreter_break_reason interpret(uarch_machine_state_access a, uint64_t mcycle_end);
-#endif
+// Explicit instantiation for machine_uarch_bridge_state_access
+template interpreter_break_reason interpret(machine_uarch_bridge_state_access a, uint64_t mcycle_end);
 #else
 // Explicit instantiation for state_access
 template interpreter_break_reason interpret(state_access a, uint64_t mcycle_end);
diff --git a/src/machine-c-api.h b/src/machine-c-api.h
index ae3e523ae..8ad49f0c3 100644
--- a/src/machine-c-api.h
+++ b/src/machine-c-api.h
@@ -522,24 +522,24 @@ CM_API cm_error cm_read_reg(const cm_machine *m, cm_reg reg, uint64_t *val);
 /// \returns 0 for success, non zero code for error.
 CM_API cm_error cm_write_reg(cm_machine *m, cm_reg reg, uint64_t val);
 
-/// \brief Reads a chunk of data from a machine memory range, by its physical address.
+/// \brief Reads a chunk of data, by its target physical address and length.
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
-/// \param address Physical address to start reading.
-/// \param data Receives chunk of memory.
-/// \param length Size of chunk in bytes.
+/// \param paddr Target physical address to start reading from.
+/// \param data Buffer that receives data to read. Must be at least \p length bytes long.
+/// \param length Number of bytes to read from \p paddr to \p data.
 /// \returns 0 for success, non zero code for error.
-/// \details The entire chunk must be inside the same memory range.
-CM_API cm_error cm_read_memory(const cm_machine *m, uint64_t address, uint8_t *data, uint64_t length);
+/// \details The data can be anywhere in the entire address space.
+CM_API cm_error cm_read_memory(const cm_machine *m, uint64_t paddr, uint8_t *data, uint64_t length);
 
-/// \brief Writes a chunk of data to a machine memory range, by its physical address.
+/// \brief Writes a chunk of data to machine memory, by its target physical address and length.
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
-/// \param address Physical address to start writing.
-/// \param data Source for chunk of data.
-/// \param length Size of chunk in bytes.
+/// \param paddr Target physical address to start writing to.
+/// \param data Buffer that contains data to write. Must be at least \p length bytes long.
+/// \param length Number of bytes to write starting from \p data to \p paddr.
 /// \returns 0 for success, non zero code for error.
-/// \details The entire chunk must be inside the same memory range.
-/// Moreover, unlike cm_read_memory(), the memory range written to must not be mapped to a device.
-CM_API cm_error cm_write_memory(cm_machine *m, uint64_t address, const uint8_t *data, uint64_t length);
+/// \details Unlike read_memory(), the entire chunk of data, from \p paddr to \p paddr + \p length,
+/// must reside entirely in the same memory range. Moreover, it cannot be mapped to a device.
+CM_API cm_error cm_write_memory(cm_machine *m, uint64_t paddr, const uint8_t *data, uint64_t length);
 
 /// \brief Reads a chunk of data from a machine memory range, by its virtual address.
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
diff --git a/src/machine-reg.h b/src/machine-reg.h
index 0fc8e77bf..be84ae758 100644
--- a/src/machine-reg.h
+++ b/src/machine-reg.h
@@ -17,7 +17,6 @@
 #ifndef MACHINE_REG_H
 #define MACHINE_REG_H
 
-#include "pma-constants.h"
 #include "shadow-state.h"
 #include "shadow-uarch-state.h"
 
@@ -29,153 +28,156 @@ namespace cartesi {
 /// \brief List of machine registers
 enum class machine_reg : uint64_t {
     // Processor x registers
-    x0 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[0]),
-    x1 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[1]),
-    x2 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[2]),
-    x3 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[3]),
-    x4 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[4]),
-    x5 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[5]),
-    x6 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[6]),
-    x7 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[7]),
-    x8 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[8]),
-    x9 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[9]),
-    x10 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[10]),
-    x11 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[11]),
-    x12 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[12]),
-    x13 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[13]),
-    x14 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[14]),
-    x15 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[15]),
-    x16 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[16]),
-    x17 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[17]),
-    x18 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[18]),
-    x19 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[19]),
-    x20 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[20]),
-    x21 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[21]),
-    x22 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[22]),
-    x23 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[23]),
-    x24 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[24]),
-    x25 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[25]),
-    x26 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[26]),
-    x27 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[27]),
-    x28 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[28]),
-    x29 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[29]),
-    x30 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[30]),
-    x31 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[31]),
-    f0 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[0]),
-    f1 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[1]),
-    f2 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[2]),
-    f3 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[3]),
-    f4 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[4]),
-    f5 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[5]),
-    f6 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[6]),
-    f7 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[7]),
-    f8 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[8]),
-    f9 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[9]),
-    f10 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[10]),
-    f11 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[11]),
-    f12 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[12]),
-    f13 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[13]),
-    f14 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[14]),
-    f15 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[15]),
-    f16 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[16]),
-    f17 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[17]),
-    f18 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[18]),
-    f19 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[19]),
-    f20 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[20]),
-    f21 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[21]),
-    f22 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[22]),
-    f23 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[23]),
-    f24 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[24]),
-    f25 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[25]),
-    f26 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[26]),
-    f27 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[27]),
-    f28 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[28]),
-    f29 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[29]),
-    f30 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[30]),
-    f31 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[31]),
-    pc = PMA_SHADOW_STATE_START + offsetof(shadow_state, pc),
-    fcsr = PMA_SHADOW_STATE_START + offsetof(shadow_state, fcsr),
-    mvendorid = PMA_SHADOW_STATE_START + offsetof(shadow_state, mvendorid),
-    marchid = PMA_SHADOW_STATE_START + offsetof(shadow_state, marchid),
-    mimpid = PMA_SHADOW_STATE_START + offsetof(shadow_state, mimpid),
-    mcycle = PMA_SHADOW_STATE_START + offsetof(shadow_state, mcycle),
-    icycleinstret = PMA_SHADOW_STATE_START + offsetof(shadow_state, icycleinstret),
-    mstatus = PMA_SHADOW_STATE_START + offsetof(shadow_state, mstatus),
-    mtvec = PMA_SHADOW_STATE_START + offsetof(shadow_state, mtvec),
-    mscratch = PMA_SHADOW_STATE_START + offsetof(shadow_state, mscratch),
-    mepc = PMA_SHADOW_STATE_START + offsetof(shadow_state, mepc),
-    mcause = PMA_SHADOW_STATE_START + offsetof(shadow_state, mcause),
-    mtval = PMA_SHADOW_STATE_START + offsetof(shadow_state, mtval),
-    misa = PMA_SHADOW_STATE_START + offsetof(shadow_state, misa),
-    mie = PMA_SHADOW_STATE_START + offsetof(shadow_state, mie),
-    mip = PMA_SHADOW_STATE_START + offsetof(shadow_state, mip),
-    medeleg = PMA_SHADOW_STATE_START + offsetof(shadow_state, medeleg),
-    mideleg = PMA_SHADOW_STATE_START + offsetof(shadow_state, mideleg),
-    mcounteren = PMA_SHADOW_STATE_START + offsetof(shadow_state, mcounteren),
-    menvcfg = PMA_SHADOW_STATE_START + offsetof(shadow_state, menvcfg),
-    stvec = PMA_SHADOW_STATE_START + offsetof(shadow_state, stvec),
-    sscratch = PMA_SHADOW_STATE_START + offsetof(shadow_state, sscratch),
-    sepc = PMA_SHADOW_STATE_START + offsetof(shadow_state, sepc),
-    scause = PMA_SHADOW_STATE_START + offsetof(shadow_state, scause),
-    stval = PMA_SHADOW_STATE_START + offsetof(shadow_state, stval),
-    satp = PMA_SHADOW_STATE_START + offsetof(shadow_state, satp),
-    scounteren = PMA_SHADOW_STATE_START + offsetof(shadow_state, scounteren),
-    senvcfg = PMA_SHADOW_STATE_START + offsetof(shadow_state, senvcfg),
-    ilrsc = PMA_SHADOW_STATE_START + offsetof(shadow_state, ilrsc),
-    iprv = PMA_SHADOW_STATE_START + offsetof(shadow_state, iprv),
-    iflags_X = PMA_SHADOW_STATE_START + offsetof(shadow_state, iflags_X),
-    iflags_Y = PMA_SHADOW_STATE_START + offsetof(shadow_state, iflags_Y),
-    iflags_H = PMA_SHADOW_STATE_START + offsetof(shadow_state, iflags_H),
-    iunrep = PMA_SHADOW_STATE_START + offsetof(shadow_state, iunrep),
-    clint_mtimecmp = PMA_SHADOW_STATE_START + offsetof(shadow_state, clint_mtimecmp),
-    plic_girqpend = PMA_SHADOW_STATE_START + offsetof(shadow_state, plic_girqpend),
-    plic_girqsrvd = PMA_SHADOW_STATE_START + offsetof(shadow_state, plic_girqsrvd),
-    htif_tohost = PMA_SHADOW_STATE_START + offsetof(shadow_state, htif_tohost),
-    htif_fromhost = PMA_SHADOW_STATE_START + offsetof(shadow_state, htif_fromhost),
-    htif_ihalt = PMA_SHADOW_STATE_START + offsetof(shadow_state, htif_ihalt),
-    htif_iconsole = PMA_SHADOW_STATE_START + offsetof(shadow_state, htif_iconsole),
-    htif_iyield = PMA_SHADOW_STATE_START + offsetof(shadow_state, htif_iyield),
+    x0 = static_cast<uint64_t>(shadow_state_what::x0),
+    x1 = static_cast<uint64_t>(shadow_state_what::x1),
+    x2 = static_cast<uint64_t>(shadow_state_what::x2),
+    x3 = static_cast<uint64_t>(shadow_state_what::x3),
+    x4 = static_cast<uint64_t>(shadow_state_what::x4),
+    x5 = static_cast<uint64_t>(shadow_state_what::x5),
+    x6 = static_cast<uint64_t>(shadow_state_what::x6),
+    x7 = static_cast<uint64_t>(shadow_state_what::x7),
+    x8 = static_cast<uint64_t>(shadow_state_what::x8),
+    x9 = static_cast<uint64_t>(shadow_state_what::x9),
+    x10 = static_cast<uint64_t>(shadow_state_what::x10),
+    x11 = static_cast<uint64_t>(shadow_state_what::x11),
+    x12 = static_cast<uint64_t>(shadow_state_what::x12),
+    x13 = static_cast<uint64_t>(shadow_state_what::x13),
+    x14 = static_cast<uint64_t>(shadow_state_what::x14),
+    x15 = static_cast<uint64_t>(shadow_state_what::x15),
+    x16 = static_cast<uint64_t>(shadow_state_what::x16),
+    x17 = static_cast<uint64_t>(shadow_state_what::x17),
+    x18 = static_cast<uint64_t>(shadow_state_what::x18),
+    x19 = static_cast<uint64_t>(shadow_state_what::x19),
+    x20 = static_cast<uint64_t>(shadow_state_what::x20),
+    x21 = static_cast<uint64_t>(shadow_state_what::x21),
+    x22 = static_cast<uint64_t>(shadow_state_what::x22),
+    x23 = static_cast<uint64_t>(shadow_state_what::x23),
+    x24 = static_cast<uint64_t>(shadow_state_what::x24),
+    x25 = static_cast<uint64_t>(shadow_state_what::x25),
+    x26 = static_cast<uint64_t>(shadow_state_what::x26),
+    x27 = static_cast<uint64_t>(shadow_state_what::x27),
+    x28 = static_cast<uint64_t>(shadow_state_what::x28),
+    x29 = static_cast<uint64_t>(shadow_state_what::x29),
+    x30 = static_cast<uint64_t>(shadow_state_what::x30),
+    x31 = static_cast<uint64_t>(shadow_state_what::x31),
+    f0 = static_cast<uint64_t>(shadow_state_what::f0),
+    f1 = static_cast<uint64_t>(shadow_state_what::f1),
+    f2 = static_cast<uint64_t>(shadow_state_what::f2),
+    f3 = static_cast<uint64_t>(shadow_state_what::f3),
+    f4 = static_cast<uint64_t>(shadow_state_what::f4),
+    f5 = static_cast<uint64_t>(shadow_state_what::f5),
+    f6 = static_cast<uint64_t>(shadow_state_what::f6),
+    f7 = static_cast<uint64_t>(shadow_state_what::f7),
+    f8 = static_cast<uint64_t>(shadow_state_what::f8),
+    f9 = static_cast<uint64_t>(shadow_state_what::f9),
+    f10 = static_cast<uint64_t>(shadow_state_what::f10),
+    f11 = static_cast<uint64_t>(shadow_state_what::f11),
+    f12 = static_cast<uint64_t>(shadow_state_what::f12),
+    f13 = static_cast<uint64_t>(shadow_state_what::f13),
+    f14 = static_cast<uint64_t>(shadow_state_what::f14),
+    f15 = static_cast<uint64_t>(shadow_state_what::f15),
+    f16 = static_cast<uint64_t>(shadow_state_what::f16),
+    f17 = static_cast<uint64_t>(shadow_state_what::f17),
+    f18 = static_cast<uint64_t>(shadow_state_what::f18),
+    f19 = static_cast<uint64_t>(shadow_state_what::f19),
+    f20 = static_cast<uint64_t>(shadow_state_what::f20),
+    f21 = static_cast<uint64_t>(shadow_state_what::f21),
+    f22 = static_cast<uint64_t>(shadow_state_what::f22),
+    f23 = static_cast<uint64_t>(shadow_state_what::f23),
+    f24 = static_cast<uint64_t>(shadow_state_what::f24),
+    f25 = static_cast<uint64_t>(shadow_state_what::f25),
+    f26 = static_cast<uint64_t>(shadow_state_what::f26),
+    f27 = static_cast<uint64_t>(shadow_state_what::f27),
+    f28 = static_cast<uint64_t>(shadow_state_what::f28),
+    f29 = static_cast<uint64_t>(shadow_state_what::f29),
+    f30 = static_cast<uint64_t>(shadow_state_what::f30),
+    f31 = static_cast<uint64_t>(shadow_state_what::f31),
+    pc = static_cast<uint64_t>(shadow_state_what::pc),
+    fcsr = static_cast<uint64_t>(shadow_state_what::fcsr),
+    mvendorid = static_cast<uint64_t>(shadow_state_what::mvendorid),
+    marchid = static_cast<uint64_t>(shadow_state_what::marchid),
+    mimpid = static_cast<uint64_t>(shadow_state_what::mimpid),
+    mcycle = static_cast<uint64_t>(shadow_state_what::mcycle),
+    icycleinstret = static_cast<uint64_t>(shadow_state_what::icycleinstret),
+    mstatus = static_cast<uint64_t>(shadow_state_what::mstatus),
+    mtvec = static_cast<uint64_t>(shadow_state_what::mtvec),
+    mscratch = static_cast<uint64_t>(shadow_state_what::mscratch),
+    mepc = static_cast<uint64_t>(shadow_state_what::mepc),
+    mcause = static_cast<uint64_t>(shadow_state_what::mcause),
+    mtval = static_cast<uint64_t>(shadow_state_what::mtval),
+    misa = static_cast<uint64_t>(shadow_state_what::misa),
+    mie = static_cast<uint64_t>(shadow_state_what::mie),
+    mip = static_cast<uint64_t>(shadow_state_what::mip),
+    medeleg = static_cast<uint64_t>(shadow_state_what::medeleg),
+    mideleg = static_cast<uint64_t>(shadow_state_what::mideleg),
+    mcounteren = static_cast<uint64_t>(shadow_state_what::mcounteren),
+    menvcfg = static_cast<uint64_t>(shadow_state_what::menvcfg),
+    stvec = static_cast<uint64_t>(shadow_state_what::stvec),
+    sscratch = static_cast<uint64_t>(shadow_state_what::sscratch),
+    sepc = static_cast<uint64_t>(shadow_state_what::sepc),
+    scause = static_cast<uint64_t>(shadow_state_what::scause),
+    stval = static_cast<uint64_t>(shadow_state_what::stval),
+    satp = static_cast<uint64_t>(shadow_state_what::satp),
+    scounteren = static_cast<uint64_t>(shadow_state_what::scounteren),
+    senvcfg = static_cast<uint64_t>(shadow_state_what::senvcfg),
+    ilrsc = static_cast<uint64_t>(shadow_state_what::ilrsc),
+    iprv = static_cast<uint64_t>(shadow_state_what::iprv),
+    iflags_X = static_cast<uint64_t>(shadow_state_what::iflags_X),
+    iflags_Y = static_cast<uint64_t>(shadow_state_what::iflags_Y),
+    iflags_H = static_cast<uint64_t>(shadow_state_what::iflags_H),
+    iunrep = static_cast<uint64_t>(shadow_state_what::iunrep),
+    clint_mtimecmp = static_cast<uint64_t>(shadow_state_what::clint_mtimecmp),
+    plic_girqpend = static_cast<uint64_t>(shadow_state_what::plic_girqpend),
+    plic_girqsrvd = static_cast<uint64_t>(shadow_state_what::plic_girqsrvd),
+    htif_tohost = static_cast<uint64_t>(shadow_state_what::htif_tohost),
+    htif_fromhost = static_cast<uint64_t>(shadow_state_what::htif_fromhost),
+    htif_ihalt = static_cast<uint64_t>(shadow_state_what::htif_ihalt),
+    htif_iconsole = static_cast<uint64_t>(shadow_state_what::htif_iconsole),
+    htif_iyield = static_cast<uint64_t>(shadow_state_what::htif_iyield),
     first_ = x0,
     last_ = htif_iyield,
 
-    uarch_halt_flag = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, halt_flag),
-    uarch_cycle = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, cycle),
-    uarch_pc = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, pc),
-    uarch_x0 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[0]),
-    uarch_x1 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[1]),
-    uarch_x2 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[2]),
-    uarch_x3 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[3]),
-    uarch_x4 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[4]),
-    uarch_x5 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[5]),
-    uarch_x6 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[6]),
-    uarch_x7 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[7]),
-    uarch_x8 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[8]),
-    uarch_x9 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[9]),
-    uarch_x10 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[10]),
-    uarch_x11 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[11]),
-    uarch_x12 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[12]),
-    uarch_x13 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[13]),
-    uarch_x14 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[14]),
-    uarch_x15 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[15]),
-    uarch_x16 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[16]),
-    uarch_x17 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[17]),
-    uarch_x18 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[18]),
-    uarch_x19 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[19]),
-    uarch_x20 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[20]),
-    uarch_x21 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[21]),
-    uarch_x22 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[22]),
-    uarch_x23 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[23]),
-    uarch_x24 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[24]),
-    uarch_x25 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[25]),
-    uarch_x26 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[26]),
-    uarch_x27 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[27]),
-    uarch_x28 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[28]),
-    uarch_x29 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[29]),
-    uarch_x30 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[30]),
-    uarch_x31 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[31]),
+    uarch_halt_flag = static_cast<uint64_t>(shadow_uarch_state_what::uarch_halt_flag),
+    uarch_cycle = static_cast<uint64_t>(shadow_uarch_state_what::uarch_cycle),
+    uarch_pc = static_cast<uint64_t>(shadow_uarch_state_what::uarch_pc),
+    uarch_x0 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x0),
+    uarch_x1 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x1),
+    uarch_x2 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x2),
+    uarch_x3 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x3),
+    uarch_x4 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x4),
+    uarch_x5 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x5),
+    uarch_x6 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x6),
+    uarch_x7 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x7),
+    uarch_x8 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x8),
+    uarch_x9 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x9),
+    uarch_x10 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x10),
+    uarch_x11 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x11),
+    uarch_x12 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x12),
+    uarch_x13 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x13),
+    uarch_x14 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x14),
+    uarch_x15 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x15),
+    uarch_x16 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x16),
+    uarch_x17 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x17),
+    uarch_x18 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x18),
+    uarch_x19 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x19),
+    uarch_x20 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x20),
+    uarch_x21 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x21),
+    uarch_x22 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x22),
+    uarch_x23 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x23),
+    uarch_x24 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x24),
+    uarch_x25 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x25),
+    uarch_x26 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x26),
+    uarch_x27 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x27),
+    uarch_x28 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x28),
+    uarch_x29 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x29),
+    uarch_x30 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x30),
+    uarch_x31 = static_cast<uint64_t>(shadow_uarch_state_what::uarch_x31),
     uarch_first_ = uarch_halt_flag,
     uarch_last_ = uarch_x31,
 
+    // Something unkonwn
+    unknown_ = UINT64_C(1) << 63, // Outside of RISC-V address space
+
     // Views of registers
     htif_tohost_dev,
     htif_tohost_cmd,
@@ -185,15 +187,58 @@ enum class machine_reg : uint64_t {
     htif_fromhost_cmd,
     htif_fromhost_reason,
     htif_fromhost_data,
-    unknown_,
+    view_first_ = htif_tohost_dev,
+    view_last_ = htif_fromhost_data,
+
 };
 
-constexpr uint64_t machine_reg_address(machine_reg reg, int i = 0) {
-    return static_cast<uint64_t>(reg) + (i * sizeof(uint64_t));
+static constexpr uint64_t machine_reg_address(machine_reg reg, int i = 0) {
+    return static_cast<uint64_t>(reg) + i * sizeof(uint64_t);
+}
+
+static constexpr machine_reg machine_reg_enum(machine_reg reg, int i) {
+    return static_cast<machine_reg>(static_cast<uint64_t>(reg) + i * sizeof(uint64_t));
+}
+
+static constexpr machine_reg machine_reg_enum(shadow_state_what reg) {
+    return static_cast<machine_reg>(reg);
+}
+
+static constexpr machine_reg machine_reg_enum(shadow_uarch_state_what reg) {
+    return static_cast<machine_reg>(reg);
 }
 
-constexpr machine_reg machine_reg_enum(machine_reg reg, int i) {
-    return static_cast<machine_reg>(static_cast<uint64_t>(reg) + (i * sizeof(uint64_t)));
+static constexpr const char *machine_reg_get_name(machine_reg reg) {
+    const auto ureg = static_cast<uint64_t>(reg);
+    if (ureg >= static_cast<uint64_t>(machine_reg::first_) && ureg <= static_cast<uint64_t>(machine_reg::last_)) {
+        return shadow_state_get_what_name(static_cast<shadow_state_what>(reg));
+    }
+    if (ureg >= static_cast<uint64_t>(machine_reg::uarch_first_) &&
+        ureg <= static_cast<uint64_t>(machine_reg::uarch_last_)) {
+        return shadow_uarch_state_get_what_name(static_cast<shadow_uarch_state_what>(reg));
+    }
+    switch (reg) {
+        case machine_reg::htif_tohost_dev:
+            return "htif.tohost_dev";
+        case machine_reg::htif_tohost_cmd:
+            return "htif.tohost_cmd";
+        case machine_reg::htif_tohost_reason:
+            return "htif.tohost_reason";
+        case machine_reg::htif_tohost_data:
+            return "htif.tohost_data";
+        case machine_reg::htif_fromhost_dev:
+            return "htif.fromhost_dev";
+        case machine_reg::htif_fromhost_cmd:
+            return "htif.fromhost_cmd";
+        case machine_reg::htif_fromhost_reason:
+            return "htif.fromhost_reason";
+        case machine_reg::htif_fromhost_data:
+            return "htif.fromhost_data";
+        case machine_reg::unknown_:
+            [[fallthrough]];
+        default:
+            return "unknown";
+    }
 }
 
 static_assert(machine_reg_address(machine_reg::uarch_first_) > machine_reg_address(machine_reg::last_));
diff --git a/src/machine.cpp b/src/machine.cpp
index f18acd299..b3f101340 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -62,20 +62,22 @@
 #include "shadow-state.h"
 #include "shadow-tlb-factory.h"
 #include "shadow-tlb.h"
+#include "shadow-uarch-state-factory.h"
 #include "shadow-uarch-state.h"
 #include "state-access.h"
 #include "strict-aliasing.h"
 #include "tlb.h"
 #include "translate-virtual-address.h"
-#include "uarch-pristine-state-hash.h"
-#ifdef OKUARCH
+#include "uarch-config.h"
+#include "uarch-constants.h"
 #include "uarch-interpret.h"
+#include "uarch-pristine-state-hash.h"
+#include "uarch-pristine.h"
 #include "uarch-record-state-access.h"
 #include "uarch-replay-state-access.h"
 #include "uarch-reset-state.h"
 #include "uarch-state-access.h"
 #include "uarch-step.h"
-#endif
 #include "unique-c-ptr.h"
 #include "virtio-console.h"
 #include "virtio-device.h"
@@ -202,6 +204,7 @@ pma_entry &machine::register_pma_entry(pma_entry &&pma) {
 
 static bool DID_is_protected(PMA_ISTART_DID DID) {
     switch (DID) {
+        case PMA_ISTART_DID::memory:
         case PMA_ISTART_DID::flash_drive:
         case PMA_ISTART_DID::cmio_rx_buffer:
         case PMA_ISTART_DID::cmio_tx_buffer:
@@ -215,7 +218,7 @@ void machine::replace_memory_range(const memory_range_config &range) {
     for (auto &pma : m_s.pmas) {
         if (pma.get_start() == range.start && pma.get_length() == range.length) {
             const auto curr = pma.get_istart_DID();
-            if (DID_is_protected(curr)) {
+            if (pma.get_length() == 0 || DID_is_protected(curr)) {
                 throw std::invalid_argument{"attempt to replace a protected range "s + pma.get_description()};
             }
             // replace range preserving original flags
@@ -227,78 +230,65 @@ void machine::replace_memory_range(const memory_range_config &range) {
 }
 
 void machine::init_tlb() {
-    for (auto use : {TLB_CODE, TLB_READ, TLB_WRITE}) {
-        auto &hot_set = m_s.tlb.hot[use];
-        auto &cold_set = m_s.tlb.cold[use];
+    for (auto set_index : {TLB_CODE, TLB_READ, TLB_WRITE}) {
         for (uint64_t slot_index = 0; slot_index < TLB_SET_SIZE; ++slot_index) {
-            auto &hot_slot = hot_set[slot_index];
-            hot_slot.vaddr_page = TLB_INVALID_PAGE;
-            hot_slot.vh_offset = host_addr{};
-            auto &cold_slot = cold_set[slot_index];
-            cold_slot.pma_index = TLB_INVALID_PMA_INDEX;
+            write_tlb(set_index, slot_index, TLB_INVALID_PAGE, host_addr{}, TLB_INVALID_PMA_INDEX);
         }
     }
 }
 
 void machine::init_tlb(const shadow_tlb_state &shadow_tlb) {
-    const char *err_prefix = "stored TLB is corrupted: ";
-    for (auto use : {TLB_CODE, TLB_READ, TLB_WRITE}) {
-        auto &hot_set = m_s.tlb.hot[use];
-        auto &cold_set = m_s.tlb.cold[use];
-        auto &shadow_set = shadow_tlb[use];
+    for (auto set_index : {TLB_CODE, TLB_READ, TLB_WRITE}) {
         for (uint64_t slot_index = 0; slot_index < TLB_SET_SIZE; ++slot_index) {
-            // copy from shadow to live TLB
-            auto &shadow_slot = shadow_set[slot_index];
-            auto &cold_slot = cold_set[slot_index];
-            const auto pma_index = cold_slot.pma_index = shadow_slot.pma_index;
-            auto &hot_slot = hot_set[slot_index];
-            const auto vaddr_page = hot_slot.vaddr_page = shadow_slot.vaddr_page;
-            // check consistency of slot, if valid, and compute live host address offset
-            if (shadow_slot.vaddr_page != TLB_INVALID_PAGE) {
-                // virtual page address must be page-aligned
-                if (shadow_slot.vaddr_page & PAGE_OFFSET_MASK) {
-                    throw std::invalid_argument{err_prefix + "invalid vaddr_page in TLB slot"s};
-                }
-                // PMA index cannot be outside pmas array
-                if (pma_index >= m_s.pmas.size()) {
-                    throw std::invalid_argument{err_prefix + "invalid pma_index in active TLB slot"s};
-                }
-                // PMA at index must be a non-empty memory PMA
-                const auto &pma = m_s.pmas[pma_index];
-                if (pma.get_length() == 0 || !pma.get_istart_M()) {
-                    throw std::invalid_argument{err_prefix + "invalid pma_index in active TLB slot"s};
-                }
-                auto paddr_page = shadow_slot.vaddr_page + shadow_slot.vp_offset;
-                // translated physical page address must be page-aligned
-                if (paddr_page & PAGE_OFFSET_MASK) {
-                    throw std::invalid_argument{err_prefix + "invalid vp_offset in active TLB slot"s};
-                }
-                // translated physical page address must fall entirely into designated PMA
-                if (paddr_page < pma.get_start() || paddr_page - pma.get_start() > pma.get_length() - PMA_PAGE_SIZE) {
-                    throw std::invalid_argument{err_prefix + "invalid vp_offset in active TLB slot"s};
-                }
-                hot_slot.vh_offset = get_host_addr(paddr_page, pma_index) - vaddr_page;
-            } else {
-                if (shadow_slot.vp_offset != 0) {
-                    throw std::invalid_argument{err_prefix + "invalid vp_offset in empty TLB slot"s};
-                }
-                if (pma_index != TLB_INVALID_PMA_INDEX) {
-                    throw std::invalid_argument{err_prefix + "invalid pma_index in empty TLB slot"s};
-                }
-                // We never leave garbage behind, even in invalid slots
-                hot_slot.vh_offset = host_addr{};
-            }
+            const auto vaddr_page = shadow_tlb[set_index][slot_index].vaddr_page;
+            const auto vp_offset = shadow_tlb[set_index][slot_index].vp_offset;
+            const auto pma_index = shadow_tlb[set_index][slot_index].pma_index;
+            check_shadow_tlb(set_index, slot_index, vaddr_page, vp_offset, pma_index, "stored TLB is corrupt: "s);
+            write_shadow_tlb(set_index, slot_index, vaddr_page, vp_offset, pma_index);
         }
     }
 }
 
-machine::machine(const machine_config &c, const machine_runtime_config &r) : m_c{c}, m_uarch{c.uarch}, m_r{r} {
+void machine::init_uarch(const uarch_config &config) {
+    using reg = machine_reg;
+    write_reg(reg::uarch_pc, config.processor.pc);
+    write_reg(reg::uarch_cycle, config.processor.cycle);
+    write_reg(reg::uarch_halt_flag, config.processor.halt_flag);
+    // General purpose registers
+    for (int i = 1; i < UARCH_X_REG_COUNT; i++) {
+        write_reg(machine_reg_enum(reg::uarch_x0, i), config.processor.x[i]);
+    }
+    // Register shadow state
+    m_us.shadow_state = make_shadow_uarch_state_pma_entry(PMA_SHADOW_UARCH_STATE_START, PMA_SHADOW_UARCH_STATE_LENGTH);
+    // Register RAM
+    constexpr auto ram_description = "uarch RAM";
+    if (!config.ram.image_filename.empty()) {
+        // Load RAM image from file
+        m_us.ram = make_callocd_memory_pma_entry(ram_description, PMA_UARCH_RAM_START, UARCH_RAM_LENGTH,
+            config.ram.image_filename)
+                       .set_flags(m_ram_flags);
+    } else {
+        // Load embedded pristine RAM image
+        m_us.ram = make_callocd_memory_pma_entry(ram_description, PMA_UARCH_RAM_START, PMA_UARCH_RAM_LENGTH)
+                       .set_flags(m_ram_flags);
+        if (uarch_pristine_ram_len > m_us.ram.get_length()) {
+            throw std::runtime_error("embedded uarch RAM image does not fit in uarch ram PMA");
+        }
+        memcpy(m_us.ram.get_memory().get_host_memory(), uarch_pristine_ram, uarch_pristine_ram_len);
+    }
+}
+
+// ??D It is best to leave the std::move() on r because it may one day be necessary!
+// NOLINTNEXTLINE(hicpp-move-const-arg,performance-move-const-arg)
+machine::machine(machine_config c, machine_runtime_config r) : m_c{std::move(c)}, m_r{std::move(r)} {
+
+    init_uarch(m_c.uarch);
 
     if (m_c.processor.marchid == UINT64_C(-1)) {
         m_c.processor.marchid = MARCHID_INIT;
     }
 
-    if (m_c.processor.marchid != MARCHID_INIT && !r.skip_version_check) {
+    if (m_c.processor.marchid != MARCHID_INIT && !m_r.skip_version_check) {
         throw std::invalid_argument{"marchid mismatch, emulator version is incompatible"};
     }
 
@@ -306,7 +296,7 @@ machine::machine(const machine_config &c, const machine_runtime_config &r) : m_c
         m_c.processor.mvendorid = MVENDORID_INIT;
     }
 
-    if (m_c.processor.mvendorid != MVENDORID_INIT && !r.skip_version_check) {
+    if (m_c.processor.mvendorid != MVENDORID_INIT && !m_r.skip_version_check) {
         throw std::invalid_argument{"mvendorid mismatch, emulator version is incompatible"};
     }
 
@@ -314,11 +304,11 @@ machine::machine(const machine_config &c, const machine_runtime_config &r) : m_c
         m_c.processor.mimpid = MIMPID_INIT;
     }
 
-    if (m_c.processor.mimpid != MIMPID_INIT && !r.skip_version_check) {
+    if (m_c.processor.mimpid != MIMPID_INIT && !m_r.skip_version_check) {
         throw std::invalid_argument{"mimpid mismatch, emulator version is incompatible"};
     }
 
-    m_s.soft_yield = r.soft_yield;
+    m_s.soft_yield = m_r.soft_yield;
 
     // General purpose registers
     for (int i = 1; i < X_REG_COUNT; i++) {
@@ -511,14 +501,8 @@ machine::machine(const machine_config &c, const machine_runtime_config &r) : m_c
         dtb_init(m_c, dtb.get_memory().get_host_memory(), PMA_DTB_LENGTH);
     }
 
-    // Include machine PMAs in set considered by the Merkle tree.
-    for (auto &pma : m_s.pmas) {
-        m_merkle_pmas.push_back(&pma);
-    }
-
     // Last, add empty sentinels until we reach capacity (need at least one sentinel)
     register_pma_entry(make_empty_pma_entry("sentinel"s, 0, 0));
-
     // NOLINTNEXTLINE(readability-static-accessed-through-instance)
     if (m_s.pmas.capacity() != PMA_MAX) {
         throw std::logic_error{"PMAs array must be able to hold PMA_MAX entries"};
@@ -530,12 +514,6 @@ machine::machine(const machine_config &c, const machine_runtime_config &r) : m_c
     // Populate shadow PMAs
     populate_shadow_pmas_state(m_s.pmas, shadow_pmas);
 
-    // Include uarch PMAs in set considered by Merkle tree
-    m_merkle_pmas.push_back(&m_uarch.get_state().shadow_state);
-    m_merkle_pmas.push_back(&m_uarch.get_state().ram);
-    // Last, add sentinel PMA
-    m_merkle_pmas.push_back(&m_s.empty_pma);
-
     // Initialize TLB device.
     // This must be done after all PMA entries are already registered, so we can lookup page addresses
     if (!m_c.tlb.image_filename.empty()) {
@@ -557,6 +535,22 @@ machine::machine(const machine_config &c, const machine_runtime_config &r) : m_c
     }
     os_silence_putchar(m_r.htif.no_console_putchar);
 
+    // Disable SIGPIPE handler, because this signal can be raised and terminate the emulator process
+    // when calling write() on closed file descriptors.
+    // This can happen with the stdout console file descriptors or network file descriptors.
+    os_disable_sigpipe();
+
+    // Include machine PMAs in set considered by the Merkle tree.
+    for (auto &pma : m_s.pmas) {
+        if (!pma.get_istart_E()) {
+            m_merkle_pmas.push_back(&pma);
+        }
+    }
+    m_merkle_pmas.push_back(&m_us.shadow_state);
+    m_merkle_pmas.push_back(&m_us.ram);
+    // Last, add sentinel PMA
+    m_merkle_pmas.push_back(&m_s.empty_pma);
+
     // Initialize memory range descriptions returned by get_memory_ranges method
     for (const auto *pma : m_merkle_pmas) {
         if (pma->get_length() != 0) {
@@ -568,11 +562,6 @@ machine::machine(const machine_config &c, const machine_runtime_config &r) : m_c
     // Sort it by increasing start address
     std::sort(m_mrds.begin(), m_mrds.end(),
         [](const machine_memory_range_descr &a, const machine_memory_range_descr &b) { return a.start < b.start; });
-
-    // Disable SIGPIPE handler, because this signal can be raised and terminate the emulator process
-    // when calling write() on closed file descriptors.
-    // This can happen with the stdout console file descriptors or network file descriptors.
-    os_disable_sigpipe();
 }
 
 static void load_hash(const std::string &dir, machine::hash_type &h) {
@@ -583,8 +572,10 @@ static void load_hash(const std::string &dir, machine::hash_type &h) {
     }
 }
 
-machine::machine(const std::string &dir, const machine_runtime_config &r) : machine{machine_config::load(dir), r} {
-    if (r.skip_root_hash_check) {
+// ??D It is best to leave the std::move() on r because it may one day be necessary!
+// NOLINTNEXTLINE(hicpp-move-const-arg,performance-move-const-arg)
+machine::machine(const std::string &dir, machine_runtime_config r) : machine{machine_config::load(dir), std::move(r)} {
+    if (m_r.skip_root_hash_check) {
         return;
     }
     hash_type hstored;
@@ -647,10 +638,10 @@ const machine_runtime_config &machine::get_runtime_config() const {
 }
 
 /// \brief Changes the machine runtime config.
-void machine::set_runtime_config(const machine_runtime_config &r) {
-    m_r = r;
+void machine::set_runtime_config(machine_runtime_config r) {
+    m_r = std::move(r); // NOLINT(hicpp-move-const-arg,performance-move-const-arg)
     m_s.soft_yield = m_r.soft_yield;
-    os_silence_putchar(r.htif.no_console_putchar);
+    os_silence_putchar(m_r.htif.no_console_putchar);
 }
 
 machine_config machine::get_serialization_config() const {
@@ -727,7 +718,7 @@ machine_config machine::get_serialization_config() const {
     c.cmio.rx_buffer.image_filename.clear();
     c.cmio.tx_buffer.image_filename.clear();
     c.uarch.processor.cycle = read_reg(reg::uarch_cycle);
-    c.uarch.processor.halt_flag = (read_reg(reg::uarch_halt_flag) != 0);
+    c.uarch.processor.halt_flag = read_reg(reg::uarch_halt_flag);
     c.uarch.processor.pc = read_reg(reg::uarch_pc);
     for (int i = 1; i < UARCH_X_REG_COUNT; i++) {
         c.uarch.processor.x[i] = read_reg(machine_reg_enum(reg::uarch_x0, i));
@@ -746,7 +737,7 @@ static void store_device_pma(const machine &m, const pma_entry &pma, const std::
         page_start_in_range += PMA_PAGE_SIZE) {
         const unsigned char *page_data = nullptr;
         auto peek = pma.get_peek();
-        if (!peek(pma, m, page_start_in_range, &page_data, scratch.get())) {
+        if (!peek(pma, m, page_start_in_range, PMA_PAGE_SIZE, &page_data, scratch.get())) {
             throw std::runtime_error{"peek failed"};
         }
         if (page_data == nullptr) {
@@ -794,19 +785,96 @@ host_addr machine::get_host_addr(uint64_t paddr, uint64_t pma_index) const {
     return host_addr{paddr} - get_hp_offset(pma_index);
 }
 
-void machine::mark_dirty_page(host_addr haddr, uint64_t pma_index) {
-    auto paddr = get_paddr(haddr, pma_index);
+void machine::mark_dirty_page(uint64_t paddr, uint64_t pma_index) {
     auto &pma = m_s.pmas[static_cast<int>(pma_index)];
     pma.mark_dirty_page(paddr - pma.get_start());
 }
 
+void machine::mark_dirty_page(host_addr haddr, uint64_t pma_index) {
+    auto paddr = get_paddr(haddr, pma_index);
+    mark_dirty_page(paddr, pma_index);
+}
+
+uint64_t machine::read_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, shadow_tlb_what reg) const {
+    switch (reg) {
+        case shadow_tlb_what::vaddr_page:
+            return m_s.tlb.hot[set_index][slot_index].vaddr_page;
+        case shadow_tlb_what::vp_offset: {
+            const auto vaddr_page = m_s.tlb.hot[set_index][slot_index].vaddr_page;
+            if (vaddr_page != TLB_INVALID_PAGE) {
+                const auto vh_offset = m_s.tlb.hot[set_index][slot_index].vh_offset;
+                const auto haddr_page = vaddr_page + vh_offset;
+                const auto pma_index = m_s.tlb.cold[set_index][slot_index].pma_index;
+                return get_paddr(haddr_page, pma_index) - vaddr_page;
+            }
+            return 0;
+        }
+        case shadow_tlb_what::pma_index:
+            return m_s.tlb.cold[set_index][slot_index].pma_index;
+        case shadow_tlb_what::zero_padding_:
+            return 0;
+        default:
+            throw std::domain_error{"unknown shadow TLB register"};
+    }
+}
+
+void machine::check_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset,
+    uint64_t pma_index, const std::string &prefix) const {
+    if (set_index > TLB_LAST_) {
+        throw std::domain_error{prefix + "TLB set index is out of range"s};
+    }
+    if (slot_index >= TLB_SET_SIZE) {
+        throw std::domain_error{prefix + "TLB slot index is out of range"s};
+    }
+    if (vaddr_page != TLB_INVALID_PAGE) {
+        if (pma_index >= m_s.pmas.size()) {
+            throw std::domain_error{prefix + "pma_index is out of range"s};
+        }
+        const auto &pma = m_s.pmas[pma_index];
+        if (pma.get_length() == 0 || !pma.get_istart_M()) {
+            throw std::invalid_argument{prefix + "pma_index does not point to memory range"s};
+        }
+        if ((vaddr_page & PAGE_OFFSET_MASK) != 0) {
+            throw std::invalid_argument{prefix + "vaddr_page is not aligned"s};
+        }
+        const auto paddr_page = vaddr_page + vp_offset;
+        if ((paddr_page & PAGE_OFFSET_MASK) != 0) {
+            throw std::invalid_argument{prefix + "vp_offset is not aligned"s};
+        }
+        const auto pma_end = pma.get_start() + (pma.get_length() - PMA_PAGE_SIZE);
+        if (paddr_page < pma.get_start() || paddr_page > pma_end) {
+            throw std::invalid_argument{prefix + "vp_offset is inconsistent with pma_index"s};
+        }
+    } else if (pma_index != TLB_INVALID_PMA_INDEX || vp_offset != 0) {
+        throw std::domain_error{prefix + "inconsistent empty TLB slot"};
+    }
+}
+
+void machine::write_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, host_addr vh_offset,
+    uint64_t pma_index) {
+    m_s.tlb.hot[set_index][slot_index].vaddr_page = vaddr_page;
+    m_s.tlb.hot[set_index][slot_index].vh_offset = vh_offset;
+    m_s.tlb.cold[set_index][slot_index].pma_index = pma_index;
+}
+
+void machine::write_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset,
+    uint64_t pma_index) {
+    if (vaddr_page != TLB_INVALID_PAGE) {
+        auto paddr_page = vaddr_page + vp_offset;
+        const auto vh_offset = get_host_addr(paddr_page, pma_index) - vaddr_page;
+        write_tlb(set_index, slot_index, vaddr_page, vh_offset, pma_index);
+    } else {
+        write_tlb(set_index, slot_index, TLB_INVALID_PAGE, host_addr{0}, TLB_INVALID_PMA_INDEX);
+    }
+}
+
 host_addr machine::get_hp_offset(uint64_t pma_index) const {
     if (pma_index >= m_s.pmas.size()) {
-        throw std::domain_error{"PMA is out of range"};
+        throw std::domain_error{"PMA index is out of range (" + std::to_string(pma_index) + ")"};
     }
     const auto &pma = m_s.pmas[static_cast<int>(pma_index)];
     if (!pma.get_istart_M()) {
-        throw std::domain_error{"PMA is not memory"};
+        throw std::domain_error{"PMA is not memory (" + pma.get_description() + ")"};
     }
     auto haddr = cast_ptr_to_host_addr(pma.get_memory().get_host_memory());
     auto paddr = pma.get_start();
@@ -856,8 +924,8 @@ void machine::store_pmas(const machine_config &c, const std::string &dir) const
     }
     store_memory_pma(find_pma_entry<uint64_t>(PMA_CMIO_RX_BUFFER_START), dir);
     store_memory_pma(find_pma_entry<uint64_t>(PMA_CMIO_TX_BUFFER_START), dir);
-    if (!m_uarch.get_state().ram.get_istart_E()) {
-        store_memory_pma(m_uarch.get_state().ram, dir);
+    if (!m_us.ram.get_istart_E()) {
+        store_memory_pma(m_us.ram, dir);
     }
 }
 
@@ -940,6 +1008,7 @@ machine::~machine() {
 }
 
 uint64_t machine::read_reg(reg r) const {
+    using reg = machine_reg;
     switch (r) {
         case reg::x0:
             return m_s.x[0];
@@ -1154,75 +1223,75 @@ uint64_t machine::read_reg(reg r) const {
         case reg::htif_iyield:
             return m_s.htif.iyield;
         case reg::uarch_x0:
-            return m_uarch.get_state().x[0];
+            return m_us.x[0];
         case reg::uarch_x1:
-            return m_uarch.get_state().x[1];
+            return m_us.x[1];
         case reg::uarch_x2:
-            return m_uarch.get_state().x[2];
+            return m_us.x[2];
         case reg::uarch_x3:
-            return m_uarch.get_state().x[3];
+            return m_us.x[3];
         case reg::uarch_x4:
-            return m_uarch.get_state().x[4];
+            return m_us.x[4];
         case reg::uarch_x5:
-            return m_uarch.get_state().x[5];
+            return m_us.x[5];
         case reg::uarch_x6:
-            return m_uarch.get_state().x[6];
+            return m_us.x[6];
         case reg::uarch_x7:
-            return m_uarch.get_state().x[7];
+            return m_us.x[7];
         case reg::uarch_x8:
-            return m_uarch.get_state().x[8];
+            return m_us.x[8];
         case reg::uarch_x9:
-            return m_uarch.get_state().x[9];
+            return m_us.x[9];
         case reg::uarch_x10:
-            return m_uarch.get_state().x[10];
+            return m_us.x[10];
         case reg::uarch_x11:
-            return m_uarch.get_state().x[11];
+            return m_us.x[11];
         case reg::uarch_x12:
-            return m_uarch.get_state().x[12];
+            return m_us.x[12];
         case reg::uarch_x13:
-            return m_uarch.get_state().x[13];
+            return m_us.x[13];
         case reg::uarch_x14:
-            return m_uarch.get_state().x[14];
+            return m_us.x[14];
         case reg::uarch_x15:
-            return m_uarch.get_state().x[15];
+            return m_us.x[15];
         case reg::uarch_x16:
-            return m_uarch.get_state().x[16];
+            return m_us.x[16];
         case reg::uarch_x17:
-            return m_uarch.get_state().x[17];
+            return m_us.x[17];
         case reg::uarch_x18:
-            return m_uarch.get_state().x[18];
+            return m_us.x[18];
         case reg::uarch_x19:
-            return m_uarch.get_state().x[19];
+            return m_us.x[19];
         case reg::uarch_x20:
-            return m_uarch.get_state().x[20];
+            return m_us.x[20];
         case reg::uarch_x21:
-            return m_uarch.get_state().x[21];
+            return m_us.x[21];
         case reg::uarch_x22:
-            return m_uarch.get_state().x[22];
+            return m_us.x[22];
         case reg::uarch_x23:
-            return m_uarch.get_state().x[23];
+            return m_us.x[23];
         case reg::uarch_x24:
-            return m_uarch.get_state().x[24];
+            return m_us.x[24];
         case reg::uarch_x25:
-            return m_uarch.get_state().x[25];
+            return m_us.x[25];
         case reg::uarch_x26:
-            return m_uarch.get_state().x[26];
+            return m_us.x[26];
         case reg::uarch_x27:
-            return m_uarch.get_state().x[27];
+            return m_us.x[27];
         case reg::uarch_x28:
-            return m_uarch.get_state().x[28];
+            return m_us.x[28];
         case reg::uarch_x29:
-            return m_uarch.get_state().x[29];
+            return m_us.x[29];
         case reg::uarch_x30:
-            return m_uarch.get_state().x[30];
+            return m_us.x[30];
         case reg::uarch_x31:
-            return m_uarch.get_state().x[31];
+            return m_us.x[31];
         case reg::uarch_pc:
-            return m_uarch.get_state().pc;
+            return m_us.pc;
         case reg::uarch_cycle:
-            return m_uarch.get_state().cycle;
+            return m_us.cycle;
         case reg::uarch_halt_flag:
-            return static_cast<uint64_t>(m_uarch.get_state().halt_flag);
+            return m_us.halt_flag;
         case reg::htif_tohost_dev:
             return HTIF_DEV_FIELD(m_s.htif.tohost);
         case reg::htif_tohost_cmd:
@@ -1564,106 +1633,106 @@ void machine::write_reg(reg w, uint64_t value) {
         case reg::uarch_x0:
             throw std::invalid_argument{"register is read-only"};
         case reg::uarch_x1:
-            m_uarch.get_state().x[1] = value;
+            m_us.x[1] = value;
             break;
         case reg::uarch_x2:
-            m_uarch.get_state().x[2] = value;
+            m_us.x[2] = value;
             break;
         case reg::uarch_x3:
-            m_uarch.get_state().x[3] = value;
+            m_us.x[3] = value;
             break;
         case reg::uarch_x4:
-            m_uarch.get_state().x[4] = value;
+            m_us.x[4] = value;
             break;
         case reg::uarch_x5:
-            m_uarch.get_state().x[5] = value;
+            m_us.x[5] = value;
             break;
         case reg::uarch_x6:
-            m_uarch.get_state().x[6] = value;
+            m_us.x[6] = value;
             break;
         case reg::uarch_x7:
-            m_uarch.get_state().x[7] = value;
+            m_us.x[7] = value;
             break;
         case reg::uarch_x8:
-            m_uarch.get_state().x[8] = value;
+            m_us.x[8] = value;
             break;
         case reg::uarch_x9:
-            m_uarch.get_state().x[9] = value;
+            m_us.x[9] = value;
             break;
         case reg::uarch_x10:
-            m_uarch.get_state().x[10] = value;
+            m_us.x[10] = value;
             break;
         case reg::uarch_x11:
-            m_uarch.get_state().x[11] = value;
+            m_us.x[11] = value;
             break;
         case reg::uarch_x12:
-            m_uarch.get_state().x[12] = value;
+            m_us.x[12] = value;
             break;
         case reg::uarch_x13:
-            m_uarch.get_state().x[13] = value;
+            m_us.x[13] = value;
             break;
         case reg::uarch_x14:
-            m_uarch.get_state().x[14] = value;
+            m_us.x[14] = value;
             break;
         case reg::uarch_x15:
-            m_uarch.get_state().x[15] = value;
+            m_us.x[15] = value;
             break;
         case reg::uarch_x16:
-            m_uarch.get_state().x[16] = value;
+            m_us.x[16] = value;
             break;
         case reg::uarch_x17:
-            m_uarch.get_state().x[17] = value;
+            m_us.x[17] = value;
             break;
         case reg::uarch_x18:
-            m_uarch.get_state().x[18] = value;
+            m_us.x[18] = value;
             break;
         case reg::uarch_x19:
-            m_uarch.get_state().x[19] = value;
+            m_us.x[19] = value;
             break;
         case reg::uarch_x20:
-            m_uarch.get_state().x[20] = value;
+            m_us.x[20] = value;
             break;
         case reg::uarch_x21:
-            m_uarch.get_state().x[21] = value;
+            m_us.x[21] = value;
             break;
         case reg::uarch_x22:
-            m_uarch.get_state().x[22] = value;
+            m_us.x[22] = value;
             break;
         case reg::uarch_x23:
-            m_uarch.get_state().x[23] = value;
+            m_us.x[23] = value;
             break;
         case reg::uarch_x24:
-            m_uarch.get_state().x[24] = value;
+            m_us.x[24] = value;
             break;
         case reg::uarch_x25:
-            m_uarch.get_state().x[25] = value;
+            m_us.x[25] = value;
             break;
         case reg::uarch_x26:
-            m_uarch.get_state().x[26] = value;
+            m_us.x[26] = value;
             break;
         case reg::uarch_x27:
-            m_uarch.get_state().x[27] = value;
+            m_us.x[27] = value;
             break;
         case reg::uarch_x28:
-            m_uarch.get_state().x[28] = value;
+            m_us.x[28] = value;
             break;
         case reg::uarch_x29:
-            m_uarch.get_state().x[29] = value;
+            m_us.x[29] = value;
             break;
         case reg::uarch_x30:
-            m_uarch.get_state().x[30] = value;
+            m_us.x[30] = value;
             break;
         case reg::uarch_x31:
-            m_uarch.get_state().x[31] = value;
+            m_us.x[31] = value;
             break;
         case reg::uarch_pc:
-            m_uarch.get_state().pc = value;
+            m_us.pc = value;
             break;
         case reg::uarch_cycle:
-            m_uarch.get_state().cycle = value;
+            m_us.cycle = value;
             break;
         case reg::uarch_halt_flag:
-            m_uarch.get_state().halt_flag = static_cast<bool>(value);
+            m_us.halt_flag = value;
             break;
         case reg::htif_tohost_dev:
             m_s.htif.tohost = HTIF_REPLACE_DEV(m_s.htif.tohost, value);
@@ -1746,7 +1815,7 @@ bool machine::verify_dirty_page_maps() const {
             const uint64_t page_address = pma.get_start() + page_start_in_range;
             if (pma.get_istart_M()) {
                 const unsigned char *page_data = nullptr;
-                peek(pma, *this, page_start_in_range, &page_data, scratch.get());
+                peek(pma, *this, page_start_in_range, PMA_PAGE_SIZE, &page_data, scratch.get());
                 hash_type stored;
                 hash_type real;
                 m_t.get_page_node_hash(page_address, stored);
@@ -1812,7 +1881,7 @@ bool machine::update_merkle_tree() const {
                 }
                 // If the peek failed, or if it returned a page for update but
                 // we failed updating it, the entire process failed
-                if (!peek(*pma, *this, page_start_in_range, &page_data, scratch.get())) {
+                if (!peek(*pma, *this, page_start_in_range, PMA_PAGE_SIZE, &page_data, scratch.get())) {
                     return false;
                 }
                 if (page_data != nullptr) {
@@ -1867,7 +1936,7 @@ bool machine::update_merkle_tree_page(uint64_t address) {
     m_t.begin_update();
     const unsigned char *page_data = nullptr;
     auto peek = pma.get_peek();
-    if (!peek(pma, *this, page_start_in_range, &page_data, scratch.get())) {
+    if (!peek(pma, *this, page_start_in_range, PMA_PAGE_SIZE, &page_data, scratch.get())) {
         m_t.end_update(h);
         return false;
     }
@@ -1900,7 +1969,22 @@ void machine::get_root_hash(hash_type &hash) const {
 
 machine::hash_type machine::get_merkle_tree_node_hash(uint64_t address, int log2_size,
     skip_merkle_tree_update_t /* unused */) const {
-    return m_t.get_node_hash(address, log2_size);
+    if (log2_size < 0 || log2_size >= machine_merkle_tree::get_log2_root_size()) {
+        throw std::domain_error{"log2_size is out of bounds"};
+    }
+    if (log2_size >= machine_merkle_tree::get_log2_page_size()) {
+        return m_t.get_node_hash(address, log2_size);
+    }
+    if ((address >> log2_size) << log2_size != address) {
+        throw std::domain_error{"address not aligned to log2_size"};
+    }
+    const auto size = UINT64_C(1) << log2_size;
+    auto scratch = unique_calloc<unsigned char>(size);
+    read_memory(address, scratch.get(), size);
+    machine_merkle_tree::hasher_type h;
+    machine_merkle_tree::hash_type hash;
+    get_merkle_tree_hash(h, scratch.get(), size, machine_merkle_tree::get_word_size(), hash);
+    return hash;
 }
 
 machine::hash_type machine::get_merkle_tree_node_hash(uint64_t address, int log2_size) const {
@@ -1925,7 +2009,7 @@ machine_merkle_tree::proof_type machine::get_proof(uint64_t address, int log2_si
     }
     // Check target address alignment
     if ((address & ((~UINT64_C(0)) >> (64 - log2_size))) != 0) {
-        throw std::invalid_argument{"address not aligned to log2_size"};
+        throw std::domain_error{"address not aligned to log2_size"};
     }
     // If proof concerns range smaller than a page, we may need to rebuild part
     // of the proof from the contents of a page inside some PMA range.
@@ -1947,7 +2031,7 @@ machine_merkle_tree::proof_type machine::get_proof(uint64_t address, int log2_si
         if (!pma.get_istart_E()) {
             const uint64_t page_start_in_range = (address - pma.get_start()) & (~(PMA_PAGE_SIZE - 1));
             auto peek = pma.get_peek();
-            if (!peek(pma, *this, page_start_in_range, &page_data, scratch.get())) {
+            if (!peek(pma, *this, page_start_in_range, PMA_PAGE_SIZE, &page_data, scratch.get())) {
                 throw std::runtime_error{"PMA peek failed"};
             }
         }
@@ -1965,70 +2049,91 @@ machine_merkle_tree::proof_type machine::get_proof(uint64_t address, int log2_si
     return get_proof(address, log2_size, skip_merkle_tree_update);
 }
 
-void machine::read_memory(uint64_t address, unsigned char *data, uint64_t length) const {
+void machine::read_memory(uint64_t paddr, unsigned char *data, uint64_t length) const {
     if (length == 0) {
         return;
     }
     if (data == nullptr) {
         throw std::invalid_argument{"invalid data buffer"};
     }
-    const pma_entry &pma = find_pma_entry(m_merkle_pmas, address, length);
-    if (pma.get_istart_M()) {
-        memcpy(data, pma.get_memory().get_host_memory() + (address - pma.get_start()), length);
-        return;
-    }
-    auto scratch = unique_calloc<unsigned char>(PMA_PAGE_SIZE);
-    // relative request address inside pma
-    uint64_t shift = address - pma.get_start();
-    // relative page address inside pma
-    constexpr const auto log2_page_size = PMA_constants::PMA_PAGE_SIZE_LOG2;
-    uint64_t page_address = (shift >> log2_page_size) << log2_page_size;
-    // relative request address inside page
-    shift -= page_address;
-
-    const unsigned char *page_data = nullptr;
-    auto peek = pma.get_peek();
-
-    while (length != 0) {
-        const uint64_t bytes_to_write = std::min(length, PMA_PAGE_SIZE - shift);
-        // avoid copying to the intermediate buffer when getting the whole page
-        if (bytes_to_write == PMA_PAGE_SIZE) {
-            if (!peek(pma, *this, page_address, &page_data, data)) {
+    // Compute the distance between the initial paddr and the first page boundary
+    const uint64_t align_paddr = (paddr & PAGE_OFFSET_MASK) != 0 ? (paddr | PAGE_OFFSET_MASK) + 1 : paddr;
+    uint64_t align_length = align_paddr - paddr;
+    const uint64_t page_size = PMA_PAGE_SIZE;
+    align_length = (align_length == 0) ? page_size : align_length;
+    // First peek goes at most to the next page boundary, or up to length
+    uint64_t peek_length = std::min(align_length, length);
+    // The outer loop finds the PMA for all peeks performed by the inner loop
+    // The inner loop peeks at most min(page_size, length) from the PMA per iteration
+    // All peeks but the absolute first peek start at a page boundary.
+    // That first peek reads at most up to the next page boundary.
+    // So the inner loop iterations never cross page boundaries.
+    for (;;) {
+        const pma_entry &pma = find_pma_entry(m_merkle_pmas, paddr, peek_length);
+        const auto peek = pma.get_peek();
+        const auto pma_start = pma.get_start();
+        const auto pma_empty = pma.get_istart_E();
+        const auto pma_length = pma.get_length();
+        // If the PMA is empty, the inner loop will break after a single iteration.
+        // But it is safe to return pristine data for that one iteration, without even peeking.
+        // This is because the inner iteration never reads past a page boundary, and the next
+        // non-empty PMA starts at the earliest on the next page boundary after paddr.
+        for (;;) {
+            const unsigned char *peek_data = nullptr;
+            // If non-empty PMA, peek, otherwise leave peek_data as nullptr (i.e. pristine)
+            if (!pma_empty && !peek(pma, *this, paddr - pma_start, peek_length, &peek_data, data)) {
                 throw std::runtime_error{"peek failed"};
             }
-            if (page_data == nullptr) {
-                memset(data, 0, bytes_to_write);
+            // If the chunk is pristine, copy zero data to buffer
+            if (peek_data == nullptr) {
+                memset(data, 0, peek_length);
+                // If peek returned pointer to internal buffer, copy to data buffer
+            } else if (peek_data != data) {
+                memcpy(data, peek_data, peek_length);
             }
-        } else {
-            if (!peek(pma, *this, page_address, &page_data, scratch.get())) {
-                throw std::runtime_error{"peek failed"};
+            // Otherwise, peek copied data straight into the data buffer
+            // If we read everything we wanted to read, we are done
+            length -= peek_length;
+            if (length == 0) {
+                return;
+            }
+            paddr += peek_length;
+            data += peek_length;
+            peek_length = std::min(page_size, length);
+            // If the PMA was empty, break to check if next read is in another PMA
+            if (pma_empty) {
+                break;
             }
-            if (page_data == nullptr) {
-                memset(data, 0, bytes_to_write);
-            } else {
-                memcpy(data, page_data + shift, bytes_to_write);
+            // If the next read does not fit in current PMA, break to get the next one
+            // There can be no overflow in the condition.
+            // Since the PMA is non-empty, (paddr-pma_start) >= 0.
+            // Moreover, pma_length >= page_size.
+            // Since, peek_length <= page_size, we get (pma_length-peek_length) >= 0.
+            if (paddr - pma_start >= pma_length - peek_length) {
+                break;
             }
         }
-
-        page_address += PMA_PAGE_SIZE;
-        length -= bytes_to_write;
-        data += bytes_to_write;
-        shift = 0;
     }
 }
 
-void machine::write_memory(uint64_t address, const unsigned char *data, uint64_t length) {
+void machine::write_memory(uint64_t paddr, const unsigned char *data, uint64_t length) {
     if (length == 0) {
         return;
     }
     if (data == nullptr) {
         throw std::invalid_argument{"invalid data buffer"};
     }
-    pma_entry &pma = find_pma_entry(m_merkle_pmas, address, length);
+    pma_entry &pma = find_pma_entry(m_merkle_pmas, paddr, length);
+    if (pma.get_istart_IO()) {
+        throw std::invalid_argument{"attempted write to device memory range"};
+    }
     if (!pma.get_istart_M() || pma.get_istart_E()) {
-        throw std::invalid_argument{"address range not entirely in memory PMA"};
+        throw std::invalid_argument{"address range not entirely in single memory range"};
+    }
+    if (DID_is_protected(pma.get_istart_DID())) {
+        throw std::invalid_argument{"attempt to write to protected memory range"};
     }
-    pma.write_memory(address, data, length);
+    pma.write_memory(paddr, data, length);
 }
 
 void machine::fill_memory(uint64_t address, uint8_t data, uint64_t length) {
@@ -2116,29 +2221,15 @@ uint64_t machine::translate_virtual_address(uint64_t vaddr) {
     return paddr;
 }
 
-uint64_t machine::read_word(uint64_t word_address) const {
+uint64_t machine::read_word(uint64_t paddr) const {
     // Make sure address is aligned
-    if ((word_address & (PMA_WORD_SIZE - 1)) != 0) {
-        throw std::invalid_argument{"address not aligned"};
-    }
-    const pma_entry &pma = find_pma_entry<uint64_t>(word_address);
-    // ??D We should split peek into peek_word and peek_page
-    // for performance. On the other hand, this function
-    // will almost never be used, so one wonders if it is worth it...
-    auto scratch = unique_calloc<unsigned char>(PMA_PAGE_SIZE);
-    const unsigned char *page_data = nullptr;
-    const uint64_t page_start_in_range = (word_address - pma.get_start()) & (~(PMA_PAGE_SIZE - 1));
-    auto peek = pma.get_peek();
-    if (!peek(pma, *this, page_start_in_range, &page_data, scratch.get())) {
-        throw std::invalid_argument{"peek failed"};
-    }
-    // If peek returns a page, read from it
-    if (page_data != nullptr) {
-        const uint64_t word_start_in_range = (word_address - pma.get_start()) & (PMA_PAGE_SIZE - 1);
-        return aliased_aligned_read<uint64_t>(page_data + word_start_in_range);
-        // Otherwise, page is always pristine
+    if ((paddr & (sizeof(uint64_t) - 1)) != 0) {
+        throw std::domain_error{"address not aligned"};
     }
-    return 0;
+    // Use read_memory
+    alignas(sizeof(uint64_t)) std::array<unsigned char, sizeof(uint64_t)> scratch{};
+    read_memory(paddr, scratch.data(), scratch.size());
+    return aliased_aligned_read<uint64_t>(scratch.data());
 }
 
 void machine::send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length) {
@@ -2153,9 +2244,10 @@ access_log machine::log_send_cmio_response(uint16_t reason, const unsigned char
     access_log log(log_type);
     // Call send_cmio_response  with the recording state accessor
     record_send_cmio_state_access a(*this, log);
-    a.push_bracket(bracket_type::begin, "send cmio response");
-    cartesi::send_cmio_response(a, reason, data, length);
-    a.push_bracket(bracket_type::end, "send cmio response");
+    {
+        [[maybe_unused]] auto note = a.make_scoped_note("send_cmio_response");
+        cartesi::send_cmio_response(a, reason, data, length);
+    }
     // Verify access log before returning
     hash_type root_hash_after;
     update_merkle_tree();
@@ -2166,16 +2258,11 @@ access_log machine::log_send_cmio_response(uint16_t reason, const unsigned char
 
 void machine::verify_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
     const hash_type &root_hash_before, const access_log &log, const hash_type &root_hash_after) {
-    // There must be at least one access in log
-    if (log.get_accesses().empty()) {
-        throw std::invalid_argument{"too few accesses in log"};
-    }
     replay_send_cmio_state_access::context context(log, root_hash_before);
     // Verify all intermediate state transitions
     replay_send_cmio_state_access a(context);
     cartesi::send_cmio_response(a, reason, data, length);
     a.finish();
-
     // Make sure the access log ends at the same root hash as the state
     hash_type obtained_root_hash;
     a.get_root_hash(obtained_root_hash);
@@ -2185,38 +2272,42 @@ void machine::verify_send_cmio_response(uint16_t reason, const unsigned char *da
 }
 
 void machine::reset_uarch() {
-#if OKUARCH
-    uarch_state_access a(m_uarch.get_state(), get_state());
-    uarch_reset_state(a);
-#endif
+    using reg = machine_reg;
+    write_reg(reg::uarch_halt_flag, UARCH_HALT_FLAG_INIT);
+    write_reg(reg::uarch_pc, UARCH_PC_INIT);
+    write_reg(reg::uarch_cycle, UARCH_CYCLE_INIT);
+    // General purpose registers
+    for (int i = 1; i < UARCH_X_REG_COUNT; i++) {
+        write_reg(machine_reg_enum(reg::uarch_x0, i), UARCH_X_INIT);
+    }
+    // Load embedded pristine RAM image
+    if (uarch_pristine_ram_len > m_us.ram.get_length()) {
+        throw std::runtime_error("embedded uarch ram image does not fit in uarch ram pma");
+    }
+    // Reset RAM to initial state
+    m_us.ram.fill_memory(m_us.ram.get_start(), 0, m_us.ram.get_length());
+    m_us.ram.write_memory(m_us.ram.get_start(), uarch_pristine_ram, uarch_pristine_ram_len);
 }
 
 access_log machine::log_reset_uarch(const access_log::type &log_type) {
-#if OKUARCH
     hash_type root_hash_before;
     get_root_hash(root_hash_before);
     // Call uarch_reset_state with a uarch_record_state_access object
-    uarch_record_state_access a(m_uarch.get_state(), *this, log_type);
-    a.push_bracket(bracket_type::begin, "reset uarch state");
-    uarch_reset_state(a);
-    a.push_bracket(bracket_type::end, "reset uarch state");
+    uarch_record_state_access a(m_us, *this, log_type);
+    {
+        [[maybe_unused]] auto note = a.make_scoped_note("reset_uarch_state");
+        uarch_reset_state(a);
+    }
     // Verify access log before returning
     hash_type root_hash_after;
     update_merkle_tree();
     get_root_hash(root_hash_after);
     verify_reset_uarch(root_hash_before, *a.get_log(), root_hash_after);
     return std::move(*a.get_log());
-#endif
-    return access_log{log_type};
 }
 
 void machine::verify_reset_uarch(const hash_type &root_hash_before, const access_log &log,
     const hash_type &root_hash_after) {
-#if OKUARCH
-    // There must be at least one access in log
-    if (log.get_accesses().empty()) {
-        throw std::invalid_argument{"too few accesses in log"};
-    }
     // Verify all intermediate state transitions
     uarch_replay_state_access a(log, root_hash_before);
     uarch_reset_state(a);
@@ -2227,50 +2318,35 @@ void machine::verify_reset_uarch(const hash_type &root_hash_before, const access
     if (obtained_root_hash != root_hash_after) {
         throw std::invalid_argument{"mismatch in root hash after replay"};
     }
-#endif
-    (void) root_hash_before;
-    (void) log;
-    (void) root_hash_after;
 }
 
 // Declaration of explicit instantiation in module uarch-step.cpp
-#if OKUARCH
 extern template UArchStepStatus uarch_step(uarch_record_state_access &a);
-#endif
 
 access_log machine::log_step_uarch(const access_log::type &log_type) {
-#if OKUARCH
-    if (m_uarch.get_state().ram.get_istart_E()) {
+    if (m_us.ram.get_istart_E()) {
         throw std::runtime_error("microarchitecture RAM is not present");
     }
     hash_type root_hash_before;
     get_root_hash(root_hash_before);
     // Call interpret with a logged state access object
-    uarch_record_state_access a(m_uarch.get_state(), *this, log_type);
-    a.push_bracket(bracket_type::begin, "step");
-    uarch_step(a);
-    a.push_bracket(bracket_type::end, "step");
+    uarch_record_state_access a(m_us, *this, log_type);
+    {
+        [[maybe_unused]] auto note = a.make_scoped_note("step");
+        uarch_step(a);
+    }
     // Verify access log before returning
     hash_type root_hash_after;
     get_root_hash(root_hash_after);
     verify_step_uarch(root_hash_before, *a.get_log(), root_hash_after);
     return std::move(*a.get_log());
-#endif
-    return access_log{log_type};
 }
 
 // Declaration of explicit instantiation in module uarch-step.cpp
-#if OKUARCH
 extern template UArchStepStatus uarch_step(uarch_replay_state_access &a);
-#endif
 
 void machine::verify_step_uarch(const hash_type &root_hash_before, const access_log &log,
     const hash_type &root_hash_after) {
-#if OKUARCH
-    // There must be at least one access in log
-    if (log.get_accesses().empty()) {
-        throw std::invalid_argument{"too few accesses in log"};
-    }
     // Verify all intermediate state transitions
     uarch_replay_state_access a(log, root_hash_before);
     uarch_step(a);
@@ -2281,10 +2357,6 @@ void machine::verify_step_uarch(const hash_type &root_hash_before, const access_
     if (obtained_root_hash != root_hash_after) {
         throw std::invalid_argument{"mismatch in root hash after replay"};
     }
-#endif
-    (void) root_hash_before;
-    (void) log;
-    (void) root_hash_after;
 }
 
 machine_config machine::get_default_config() {
@@ -2293,18 +2365,14 @@ machine_config machine::get_default_config() {
 
 // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
 uarch_interpreter_break_reason machine::run_uarch(uint64_t uarch_cycle_end) {
-#if OKUARCH
     if (read_reg(reg::iunrep) != 0) {
         throw std::runtime_error("microarchitecture cannot be used with unreproducible machines");
     }
-    if (m_uarch.get_state().ram.get_istart_E()) {
+    if (m_us.ram.get_istart_E()) {
         throw std::runtime_error("microarchitecture RAM is not present");
     }
-    uarch_state_access a(m_uarch.get_state(), get_state());
+    uarch_state_access a(*this);
     return uarch_interpret(a, uarch_cycle_end);
-#endif
-    (void) uarch_cycle_end;
-    return uarch_interpreter_break_reason::uarch_halted;
 }
 
 interpreter_break_reason machine::log_step(uint64_t mcycle_count, const std::string &filename) {
@@ -2350,7 +2418,8 @@ interpreter_break_reason machine::verify_step(const hash_type &root_hash_before,
 }
 
 interpreter_break_reason machine::run(uint64_t mcycle_end) {
-    if (mcycle_end < read_reg(reg::mcycle)) {
+    const auto mcycle = read_reg(reg::mcycle);
+    if (mcycle_end < mcycle) {
         throw std::invalid_argument{"mcycle is past"};
     }
     const state_access a(*this);
diff --git a/src/machine.h b/src/machine.h
index 07ea6e104..31b7a7063 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -40,8 +40,9 @@
 #include "os.h"
 #include "pma-constants.h"
 #include "pma.h"
+#include "shadow-tlb.h"
 #include "uarch-interpret.h"
-#include "uarch-machine.h"
+#include "uarch-state.h"
 #include "virtio-device.h"
 
 namespace cartesi {
@@ -58,18 +59,11 @@ constexpr skip_merkle_tree_update_t skip_merkle_tree_update;
 /// \brief Cartesi Machine implementation
 class machine final {
 private:
-    //??D Ideally, we would hold a unique_ptr to the state. This
-    //    would allow us to remove the machine-state.h include and
-    //    therefore hide its contents from anyone who includes only
-    //    machine.h. Maybe the compiler can do a good job we we are
-    //    not constantly going through the extra indirection. We
-    //    should test this.
-
-    mutable machine_state m_s;              ///< Opaque machine state
+    mutable machine_state m_s;              ///< Big machine state
+    mutable uarch_state m_us;               ///< Microarchitecture state
     mutable machine_merkle_tree m_t;        ///< Merkle tree of state
     std::vector<pma_entry *> m_merkle_pmas; ///< PMAs considered by the Merkle tree: from big machine and uarch
     machine_config m_c;                     ///< Copy of initialization config
-    uarch_machine m_uarch;                  ///< Microarchitecture machine
     machine_runtime_config m_r;             ///< Copy of initialization runtime config
     machine_memory_range_descrs m_mrds;     ///< List of memory ranges returned by get_memory_ranges().
 
@@ -137,6 +131,10 @@ class machine final {
     /// \param shadow_tlb Shadow TLB loaded from disk
     void init_tlb(const shadow_tlb_state &shadow_tlb);
 
+    /// \brief Initializes microarchitecture
+    /// \param config Microarchitecture configuration
+    void init_uarch(const uarch_config &config);
+
 public:
     /// \brief Type of hash
     using hash_type = machine_merkle_tree::hash_type;
@@ -146,12 +144,12 @@ class machine final {
     /// \brief Constructor from machine configuration
     /// \param config Machine config to use instantiating machine
     /// \param runtime Runtime config to use with machine
-    explicit machine(const machine_config &config, const machine_runtime_config &runtime = {});
+    explicit machine(machine_config config, machine_runtime_config runtime = {});
 
     /// \brief Constructor from previously serialized directory
     /// \param directory Directory to load stored machine from
     /// \param runtime Runtime config to use with machine
-    explicit machine(const std::string &directory, const machine_runtime_config &runtime = {});
+    explicit machine(const std::string &directory, machine_runtime_config runtime = {});
 
     /// \brief Serialize entire state to directory
     /// \param directory Directory to store machine into
@@ -235,6 +233,16 @@ class machine final {
         return m_s;
     }
 
+    /// \brief Returns uarch state for direct access.
+    uarch_state &get_uarch_state() {
+        return m_us;
+    }
+
+    /// \brief Returns uarch state for direct read-only access.
+    const uarch_state &get_uarch_state() const {
+        return m_us;
+    }
+
     /// \brief Returns a list of descriptions for all PMA entries registered in the machine, sorted by start
     machine_memory_range_descrs get_memory_ranges() const {
         return m_mrds;
@@ -337,27 +345,25 @@ class machine final {
     static uint64_t get_reg_address(reg r);
 
     /// \brief Read the value of a word in the machine state.
-    /// \param address Word address (aligned to 64-bit boundary).
+    /// \param paddr Word address (aligned to 64-bit boundary).
     /// \returns The value of word at address.
-    /// \warning The current implementation of this function is very slow!
-    uint64_t read_word(uint64_t address) const;
-
-    /// \brief Reads a chunk of data from the machine memory.
-    /// \param address Physical address to start reading.
-    /// \param data Receives chunk of memory.
-    /// \param length Size of chunk.
-    /// \details The entire chunk, from \p address to \p address + \p length must
-    /// be inside the same PMA region.
-    void read_memory(uint64_t address, unsigned char *data, uint64_t length) const;
-
-    /// \brief Writes a chunk of data to the machine memory.
-    /// \param address Physical address to start writing.
-    /// \param data Source for chunk of data.
-    /// \param length Size of chunk.
-    /// \details The entire chunk, from \p address to \p address + \p length must
-    /// be inside the same PMA region. Moreover, this PMA must be a memory PMA,
-    /// and not a device PMA.
-    void write_memory(uint64_t address, const unsigned char *data, uint64_t length);
+    /// \details The word can be anywhere in the entire address space.
+    uint64_t read_word(uint64_t paddr) const;
+
+    /// \brief Reads a chunk of data, by its target physical address and length.
+    /// \param paddr Target physical address to start reading from.
+    /// \param data Buffer that receives data to read. Must be at least \p length bytes long.
+    /// \param length Number of bytes to read from \p paddr to \p data.
+    /// \details The data can be anywhere in the entire address space.
+    void read_memory(uint64_t paddr, unsigned char *data, uint64_t length) const;
+
+    /// \brief Writes a chunk of data to machine memory, by its target physical address and length.
+    /// \param paddr Target physical address to start writing to.
+    /// \param data Buffer that contains data to write. Must be at least \p length bytes long.
+    /// \param length Number of bytes to write starting from \p data to \p paddr.
+    /// \details Unlike read_memory(), the entire chunk of data, from \p paddr to \p paddr + \p length,
+    /// must reside entirely in the same memory range. Moreover, it cannot be mapped to a device.
+    void write_memory(uint64_t paddr, const unsigned char *data, uint64_t length);
 
     /// \brief Fills a memory range with a single byte.
     /// \param address Physical address to start filling.
@@ -428,7 +434,7 @@ class machine final {
     /// \brief Changes the machine runtime config.
     /// \param range Configuration of the new memory range.
     /// \details Some runtime options cannot be changed.
-    void set_runtime_config(const machine_runtime_config &r);
+    void set_runtime_config(machine_runtime_config r);
 
     /// \brief Replaces a memory range.
     /// \param range Configuration of the new memory range.
@@ -461,6 +467,45 @@ class machine final {
     /// \param pma_index Index of PMA where address falls
     void mark_dirty_page(host_addr haddr, uint64_t pma_index);
 
+    /// \brief Marks a page as dirty
+    /// \param paddr Target phyislcal address within page
+    /// \param pma_index Index of PMA where address falls
+    void mark_dirty_page(uint64_t paddr, uint64_t pma_index);
+
+    /// \brief Updates a TLB slot
+    /// \param set_index TLB_CODE, TLB_READ, or TLB_WRITE
+    /// \param slot_index Index of slot to update
+    /// \param vaddr_page Virtual address of page to map
+    /// \param vh_offset Offset from target virtual addresses to host addresses within page
+    /// \param pma_index Index of PMA where address falls
+    void write_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, host_addr vh_offset,
+        uint64_t pma_index);
+
+    /// \brief Updates a TLB slot
+    /// \param set_index TLB_CODE, TLB_READ, or TLB_WRITE
+    /// \param slot_index Index of slot to update
+    /// \param vaddr_page Virtual address of page to map
+    /// \param vp_offset Offset from target virtual addresses to target physical addresses within page
+    /// \param pma_index Index of PMA where address falls
+    void write_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset,
+        uint64_t pma_index);
+
+    /// \brief Check consistency of TLB slot
+    /// \param set_index TLB_CODE, TLB_READ, or TLB_WRITE
+    /// \param slot_index Index of slot to update
+    /// \param vaddr_page Virtual address of page to map
+    /// \param vp_offset Offset from target virtual addresses to target physical addresses within page
+    /// \param pma_index Index of PMA where address falls
+    void check_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset,
+        uint64_t pma_index, const std::string &prefix = "") const;
+
+    /// \brief Reads a TLB register
+    /// \param set_index TLB_CODE, TLB_READ, or TLB_WRITE
+    /// \param slot_index Index of slot to read
+    /// \param reg Register to read from slot
+    /// \returns Value of register
+    uint64_t read_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, shadow_tlb_what reg) const;
+
     /// \brief Sends cmio response and returns an access log
     /// \param reason Reason for sending response.
     /// \param data Response data.
diff --git a/src/mock-pma-entry.h b/src/mock-pma-entry.h
index 883bd6725..75cda69cb 100644
--- a/src/mock-pma-entry.h
+++ b/src/mock-pma-entry.h
@@ -136,6 +136,10 @@ class mock_pma_entry {
         return m_flags.IR;
     }
 
+    PMA_ISTART_DID get_istart_DID() const {
+        return m_flags.DID;
+    }
+
     const auto *get_driver() const {
         return m_driver;
     }
diff --git a/src/plic-factory.cpp b/src/plic-factory.cpp
index d0f139e3e..c68f7b6b1 100644
--- a/src/plic-factory.cpp
+++ b/src/plic-factory.cpp
@@ -14,27 +14,18 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#include "plic-factory.h"
-
 #include <cstdint>
 
+#include "plic-factory.h"
 #include "plic.h"
 #include "pma-constants.h"
 #include "pma.h"
 
 namespace cartesi {
 
-/// \brief PLIC device peek callback. See ::pma_peek.
-static bool plic_peek(const pma_entry &pma, const machine & /*m*/, uint64_t page_offset,
-    const unsigned char **page_data, unsigned char * /*context*/) {
-    // PLIC range can be represented as pristine because its state is already represented in shadow CSRs
-    *page_data = nullptr;
-    return (page_offset % PMA_PAGE_SIZE) == 0 && page_offset < pma.get_length();
-}
-
 pma_entry make_plic_pma_entry(uint64_t start, uint64_t length) {
     const pma_entry::flags f{.R = true, .W = true, .X = false, .IR = false, .IW = false, .DID = PMA_ISTART_DID::PLIC};
-    return make_device_pma_entry("PLIC device", start, length, plic_peek, &plic_driver).set_flags(f);
+    return make_device_pma_entry("PLIC device", start, length, pma_peek_pristine, &plic_driver).set_flags(f);
 }
 
 } // namespace cartesi
diff --git a/src/pm-type-name.h b/src/pm-type-name.h
new file mode 100644
index 000000000..6f3d61e92
--- /dev/null
+++ b/src/pm-type-name.h
@@ -0,0 +1,48 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef PM_TYPE_NAME_H
+#define PM_TYPE_NAME_H
+
+namespace cartesi {
+
+//?DD Poor man's rtti that works in microarchitecture
+template <typename T>
+struct pm_type_name {
+    static constexpr const char *value = "unknown type";
+};
+
+template <typename T>
+constexpr const char *pm_type_name_v = pm_type_name<T>::value;
+
+#define PM_TYPE_NAME(type)                                                                                             \
+    template <>                                                                                                        \
+    struct pm_type_name<type> {                                                                                        \
+        static constexpr const char *value = #type;                                                                    \
+    }
+
+PM_TYPE_NAME(uint8_t);
+PM_TYPE_NAME(int8_t);
+PM_TYPE_NAME(uint16_t);
+PM_TYPE_NAME(int16_t);
+PM_TYPE_NAME(uint32_t);
+PM_TYPE_NAME(int32_t);
+PM_TYPE_NAME(uint64_t);
+PM_TYPE_NAME(int64_t);
+
+} // namespace cartesi
+
+#endif
diff --git a/src/pma-constants.h b/src/pma-constants.h
index be97580eb..8be8edd4a 100644
--- a/src/pma-constants.h
+++ b/src/pma-constants.h
@@ -132,6 +132,37 @@ enum class PMA_ISTART_DID {
     shadow_uarch = PMA_SHADOW_UARCH_STATE_DID_DEF, ///< DID for shadow uarch state device
 };
 
+static constexpr const char *pma_get_DID_name(PMA_ISTART_DID did) {
+    switch (did) {
+        case PMA_ISTART_DID::memory:
+            return "DID.memory";
+        case PMA_ISTART_DID::shadow_state:
+            return "DID.shadow_state";
+        case PMA_ISTART_DID::shadow_pmas:
+            return "DID.shadow_pmas";
+        case PMA_ISTART_DID::shadow_TLB:
+            return "DID.shadow_TLB";
+        case PMA_ISTART_DID::flash_drive:
+            return "DID.flash_drive";
+        case PMA_ISTART_DID::CLINT:
+            return "DID.CLINT";
+        case PMA_ISTART_DID::PLIC:
+            return "DID.PLIC";
+        case PMA_ISTART_DID::HTIF:
+            return "DID.HTIF";
+        case PMA_ISTART_DID::VIRTIO:
+            return "DID.VIRTIO";
+        case PMA_ISTART_DID::cmio_rx_buffer:
+            return "DID.cmio_rx_buffer";
+        case PMA_ISTART_DID::cmio_tx_buffer:
+            return "DID.cmio_tx_buffer";
+        case PMA_ISTART_DID::shadow_uarch:
+            return "DID.shadow_uarch";
+        default:
+            return "DID.unkown";
+    }
+}
+
 static_assert(PMA_CMIO_RX_BUFFER_START_DEF == CM_PMA_CMIO_RX_BUFFER_START);
 static_assert(PMA_CMIO_RX_BUFFER_LOG2_SIZE_DEF == CM_PMA_CMIO_RX_BUFFER_LOG2_SIZE);
 static_assert(PMA_CMIO_TX_BUFFER_START_DEF == CM_PMA_CMIO_TX_BUFFER_START);
diff --git a/src/pma.cpp b/src/pma.cpp
index 9a112b4dd..5edb43f46 100644
--- a/src/pma.cpp
+++ b/src/pma.cpp
@@ -204,28 +204,27 @@ void pma_entry::fill_memory(uint64_t paddr, unsigned char value, uint64_t size)
     }
 }
 
-bool pma_peek_error(const pma_entry & /*pma*/, const machine & /*m*/, uint64_t /*page_address*/,
+bool pma_peek_error(const pma_entry & /*pma*/, const machine & /*m*/, uint64_t /*offset*/, uint64_t /*length*/,
     const unsigned char ** /*page_data*/, unsigned char * /*scratch*/) {
     return false;
 }
 
+bool pma_peek_pristine(const pma_entry &pma, const machine & /*m*/, uint64_t offset, uint64_t length,
+    const unsigned char **data, unsigned char * /*scratch*/) {
+    *data = nullptr;
+    return length <= pma.get_length() && offset <= pma.get_length() - length;
+}
+
 /// \brief Memory range peek callback. See pma_peek.
-static bool memory_peek(const pma_entry &pma, const machine & /*m*/, uint64_t page_address,
-    const unsigned char **page_data, unsigned char *scratch) {
-    // If page_address is not aligned, or if it is out of range, return error
-    if ((page_address & (PMA_PAGE_SIZE - 1)) != 0 || page_address > pma.get_length()) {
-        *page_data = nullptr;
+static bool memory_peek(const pma_entry &pma, const machine & /*m*/, uint64_t offset, uint64_t length,
+    const unsigned char **data, unsigned char * /*scratch*/) {
+    // If desired data does not fit in range, return error
+    if (length > pma.get_length() || offset > pma.get_length() - length) {
+        *data = nullptr;
         return false;
     }
-    // If page is only partially inside range, copy to scratch
-    if (page_address + PMA_PAGE_SIZE > pma.get_length()) {
-        memset(scratch, 0, PMA_PAGE_SIZE);
-        memcpy(scratch, pma.get_memory().get_host_memory() + page_address, pma.get_length() - page_address);
-        *page_data = scratch;
-        return true;
-        // Otherwise, return pointer directly into host memory
-    }
-    *page_data = pma.get_memory().get_host_memory() + page_address;
+    // Otherwise, return pointer directly into host memory
+    *data = pma.get_memory().get_host_memory() + offset;
     return true;
 }
 
diff --git a/src/pma.h b/src/pma.h
index 69d53d035..74f96fa05 100644
--- a/src/pma.h
+++ b/src/pma.h
@@ -41,16 +41,21 @@ class machine;
 /// \brief Prototype for callback invoked when machine wants to peek into a range with no side-effects.
 /// \param pma Reference to corresponding PMA entry.
 /// \param m Reference to associated machine.
-/// \param page_offset Offset of page start within range. Must be aligned to PMA_PAGE_SIZE.
-/// \param page_data Receives pointer to start of page data, or nullptr if page is constant *and* pristine.
-/// \param scratch Pointer to memory buffer that must be able to hold PMA_PAGE_SIZE bytes.
+/// \param offset Offset within range to start reading.
+/// \param length Number of bytes to read.
+/// \param data Receives pointer to start of data, or nullptr if data is constant *and* pristine.
+/// \param scratch Pointer to memory buffer that must be able to hold \p length bytes.
 /// \returns True if operation succeeded, false otherwise.
-using pma_peek = bool (*)(const pma_entry &pma, const machine &m, uint64_t page_offset, const unsigned char **page_data,
-    unsigned char *scratch);
+using pma_peek = bool (*)(const pma_entry &pma, const machine &m, uint64_t offset, uint64_t length,
+    const unsigned char **data, unsigned char *scratch);
 
 /// \brief Default peek callback issues error on peeks.
-bool pma_peek_error(const pma_entry & /*pma*/, const machine & /*m*/, uint64_t /*page_offset*/,
-    const unsigned char ** /*page_data*/, unsigned char * /*scratch*/);
+bool pma_peek_error(const pma_entry & /*pma*/, const machine & /*m*/, uint64_t /*offset*/, uint64_t /*length*/,
+    const unsigned char ** /*data*/, unsigned char * /*scratch*/);
+
+/// \brief Default peek callback for pristine ranges.
+bool pma_peek_pristine(const pma_entry & /*pma*/, const machine & /*m*/, uint64_t offset, uint64_t length,
+    const unsigned char **data, unsigned char * /*scratch*/);
 
 /// \brief Data for IO ranges.
 class pma_device final {
diff --git a/src/record-send-cmio-state-access.h b/src/record-send-cmio-state-access.h
index 3c595e53a..f9964a5f5 100644
--- a/src/record-send-cmio-state-access.h
+++ b/src/record-send-cmio-state-access.h
@@ -35,6 +35,7 @@
 #include "machine.h"
 #include "meta.h"
 #include "pma.h"
+#include "scoped-note.h"
 #include "shadow-state.h"
 
 namespace cartesi {
@@ -184,8 +185,16 @@ class record_send_cmio_state_access : public i_state_access<record_send_cmio_sta
         update_after_write(paligned);
     }
 
-    void do_push_bracket(bracket_type &type, const char *text) {
-        m_log.push_bracket(type, text);
+    void do_push_begin_bracket(const char *text) {
+        m_log.push_begin_bracket(text);
+    }
+
+    void do_push_end_bracket(const char *text) {
+        m_log.push_end_bracket(text);
+    }
+
+    auto do_make_scoped_note(const char *text) {
+        return scoped_note<record_send_cmio_state_access>{*this, text};
     }
 
     void do_write_iflags_Y(uint64_t val) {
@@ -262,6 +271,11 @@ class record_send_cmio_state_access : public i_state_access<record_send_cmio_sta
         // NOLINTEND(bugprone-unchecked-optional-access)
         m_log.push_access(a, "cmio rx buffer");
     }
+
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    constexpr const char *do_get_name() const {
+        return "record_send_cmio_state_access";
+    }
 };
 
 } // namespace cartesi
diff --git a/src/record-step-state-access.h b/src/record-step-state-access.h
index 8c94c439f..626afe5f2 100644
--- a/src/record-step-state-access.h
+++ b/src/record-step-state-access.h
@@ -17,17 +17,21 @@
 #ifndef RECORD_STEP_STATE_ACCESS_H
 #define RECORD_STEP_STATE_ACCESS_H
 
-#include "compiler-defines.h"
-#include "machine.h"
+#include <map>
+#include <optional>
+#include <vector>
 
+#include "compiler-defines.h"
 #include "device-state-access.h"
 #include "i-state-access.h"
+#include "machine.h"
 #include "shadow-pmas.h"
 #include "shadow-tlb.h"
 #include "unique-c-ptr.h"
-#include <map>
-#include <optional>
-#include <vector>
+
+#if DUMP_STATE_ACCESS
+#include "scoped-note.h"
+#endif
 
 namespace cartesi {
 
@@ -184,427 +188,361 @@ class record_step_state_access : public i_state_access<record_step_state_access>
         }
     }
 
-    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    void do_push_bracket(bracket_type type, const char *text) {
-        (void) type;
-        (void) text;
+    uint64_t log_read_reg(machine_reg reg) const {
+        touch_page(machine_reg_address(reg));
+        return m_m.read_reg(reg);
     }
 
-    int do_make_scoped_note(const char *text) { // NOLINT(readability-convert-member-functions-to-static)
-        (void) text;
-        return 0;
+    void log_write_reg(machine_reg reg, uint64_t val) {
+        touch_page(machine_reg_address(reg));
+        m_m.write_reg(reg, val);
     }
 
-    uint64_t do_read_x(int reg) const {
-        touch_page(machine_reg_address(machine_reg::x0, reg));
-        return m_m.get_state().x[reg];
+    uint64_t log_read_tlb(TLB_set_index set_index, uint64_t slot_index, shadow_tlb_what what) {
+        touch_page(shadow_tlb_get_abs_addr(set_index, slot_index, what));
+        return m_m.read_shadow_tlb(set_index, slot_index, what);
     }
 
-    void do_write_x(int reg, uint64_t val) {
-        assert(reg != 0);
-        touch_page(machine_reg_address(machine_reg::x0, reg));
-        m_m.get_state().x[reg] = val;
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    void do_push_begin_bracket(const char * /*text*/) {}
+
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    void do_push_end_bracket(const char * /*text*/) {}
+
+#ifdef DUMP_STATE_ACCESS
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    auto do_make_scoped_note([[maybe_unused]] const char *text) {
+        return scoped_note<record_step_state_access>{*this, text};
+    }
+#endif
+
+    uint64_t do_read_x(int i) const {
+        return log_read_reg(machine_reg_enum(machine_reg::x0, i));
+    }
+
+    void do_write_x(int i, uint64_t val) {
+        assert(i != 0);
+        log_write_reg(machine_reg_enum(machine_reg::x0, i), val);
     }
 
-    uint64_t do_read_f(int reg) const {
-        touch_page(machine_reg_address(machine_reg::f0, reg));
-        return m_m.get_state().f[reg];
+    uint64_t do_read_f(int i) const {
+        return log_read_reg(machine_reg_enum(machine_reg::f0, i));
     }
 
-    void do_write_f(int reg, uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::f0, reg));
-        m_m.get_state().f[reg] = val;
+    void do_write_f(int i, uint64_t val) {
+        log_write_reg(machine_reg_enum(machine_reg::f0, i), val);
     }
 
     uint64_t do_read_pc() const {
-        // get phys address of pc in dhadow
-        touch_page(machine_reg_address(machine_reg::pc));
-        return m_m.get_state().pc;
+        return log_read_reg(machine_reg::pc);
     }
 
     void do_write_pc(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::pc));
-        m_m.get_state().pc = val;
+        log_write_reg(machine_reg::pc, val);
     }
 
     uint64_t do_read_fcsr() const {
-        touch_page(machine_reg_address(machine_reg::fcsr));
-        return m_m.get_state().fcsr;
+        return log_read_reg(machine_reg::fcsr);
     }
 
     void do_write_fcsr(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::fcsr));
-        m_m.get_state().fcsr = val;
+        log_write_reg(machine_reg::fcsr, val);
     }
 
     uint64_t do_read_icycleinstret() const {
-        touch_page(machine_reg_address(machine_reg::icycleinstret));
-        return m_m.get_state().icycleinstret;
+        return log_read_reg(machine_reg::icycleinstret);
     }
 
     void do_write_icycleinstret(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::icycleinstret));
-        m_m.get_state().icycleinstret = val;
+        log_write_reg(machine_reg::icycleinstret, val);
     }
 
-    uint64_t do_read_mvendorid() const { // NOLINT(readability-convert-member-functions-to-static)
-        touch_page(machine_reg_address(machine_reg::mvendorid));
-        return MVENDORID_INIT;
+    uint64_t do_read_mvendorid() const {
+        return log_read_reg(machine_reg::mvendorid);
     }
 
-    uint64_t do_read_marchid() const { // NOLINT(readability-convert-member-functions-to-static)
-        touch_page(machine_reg_address(machine_reg::marchid));
-        return MARCHID_INIT;
+    uint64_t do_read_marchid() const {
+        return log_read_reg(machine_reg::marchid);
     }
 
-    uint64_t do_read_mimpid() const { // NOLINT(readability-convert-member-functions-to-static)
-        touch_page(machine_reg_address(machine_reg::mimpid));
-        return MIMPID_INIT;
+    uint64_t do_read_mimpid() const {
+        return log_read_reg(machine_reg::mimpid);
     }
 
     uint64_t do_read_mcycle() const {
-        touch_page(machine_reg_address(machine_reg::mcycle));
-        return m_m.get_state().mcycle;
+        return log_read_reg(machine_reg::mcycle);
     }
 
     void do_write_mcycle(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::mcycle));
-        m_m.get_state().mcycle = val;
+        log_write_reg(machine_reg::mcycle, val);
     }
 
     uint64_t do_read_mstatus() const {
-        touch_page(machine_reg_address(machine_reg::mstatus));
-        return m_m.get_state().mstatus;
+        return log_read_reg(machine_reg::mstatus);
     }
 
     void do_write_mstatus(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::mstatus));
-        m_m.get_state().mstatus = val;
+        log_write_reg(machine_reg::mstatus, val);
     }
 
     uint64_t do_read_menvcfg() const {
-        touch_page(machine_reg_address(machine_reg::menvcfg));
-        return m_m.get_state().menvcfg;
+        return log_read_reg(machine_reg::menvcfg);
     }
 
     void do_write_menvcfg(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::menvcfg));
-        m_m.get_state().menvcfg = val;
+        log_write_reg(machine_reg::menvcfg, val);
     }
 
     uint64_t do_read_mtvec() const {
-        touch_page(machine_reg_address(machine_reg::mtvec));
-        return m_m.get_state().mtvec;
+        return log_read_reg(machine_reg::mtvec);
     }
 
     void do_write_mtvec(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::mtvec));
-        m_m.get_state().mtvec = val;
+        log_write_reg(machine_reg::mtvec, val);
     }
 
     uint64_t do_read_mscratch() const {
-        touch_page(machine_reg_address(machine_reg::mscratch));
-        return m_m.get_state().mscratch;
+        return log_read_reg(machine_reg::mscratch);
     }
 
     void do_write_mscratch(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::mscratch));
-        m_m.get_state().mscratch = val;
+        log_write_reg(machine_reg::mscratch, val);
     }
 
     uint64_t do_read_mepc() const {
-        touch_page(machine_reg_address(machine_reg::mepc));
-        return m_m.get_state().mepc;
+        return log_read_reg(machine_reg::mepc);
     }
 
     void do_write_mepc(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::mepc));
-        m_m.get_state().mepc = val;
+        log_write_reg(machine_reg::mepc, val);
     }
 
     uint64_t do_read_mcause() const {
-        touch_page(machine_reg_address(machine_reg::mcause));
-        return m_m.get_state().mcause;
+        return log_read_reg(machine_reg::mcause);
     }
 
     void do_write_mcause(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::mcause));
-        m_m.get_state().mcause = val;
+        log_write_reg(machine_reg::mcause, val);
     }
 
     uint64_t do_read_mtval() const {
-        touch_page(machine_reg_address(machine_reg::mtval));
-        return m_m.get_state().mtval;
+        return log_read_reg(machine_reg::mtval);
     }
 
     void do_write_mtval(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::mtval));
-        m_m.get_state().mtval = val;
+        log_write_reg(machine_reg::mtval, val);
     }
 
     uint64_t do_read_misa() const {
-        touch_page(machine_reg_address(machine_reg::misa));
-        return m_m.get_state().misa;
+        return log_read_reg(machine_reg::misa);
     }
 
     void do_write_misa(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::misa));
-        m_m.get_state().misa = val;
+        log_write_reg(machine_reg::misa, val);
     }
 
     uint64_t do_read_mie() const {
-        touch_page(machine_reg_address(machine_reg::mie));
-        return m_m.get_state().mie;
+        return log_read_reg(machine_reg::mie);
     }
 
     void do_write_mie(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::mie));
-        m_m.get_state().mie = val;
+        log_write_reg(machine_reg::mie, val);
     }
 
     uint64_t do_read_mip() const {
-        touch_page(machine_reg_address(machine_reg::mip));
-        return m_m.get_state().mip;
+        return log_read_reg(machine_reg::mip);
     }
 
     void do_write_mip(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::mip));
-        m_m.get_state().mip = val;
+        log_write_reg(machine_reg::mip, val);
     }
 
     uint64_t do_read_medeleg() const {
-        touch_page(machine_reg_address(machine_reg::medeleg));
-        return m_m.get_state().medeleg;
+        return log_read_reg(machine_reg::medeleg);
     }
 
     void do_write_medeleg(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::medeleg));
-        m_m.get_state().medeleg = val;
+        log_write_reg(machine_reg::medeleg, val);
     }
 
     uint64_t do_read_mideleg() const {
-        touch_page(machine_reg_address(machine_reg::mideleg));
-        return m_m.get_state().mideleg;
+        return log_read_reg(machine_reg::mideleg);
     }
 
     void do_write_mideleg(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::mideleg));
-        m_m.get_state().mideleg = val;
+        log_write_reg(machine_reg::mideleg, val);
     }
 
     uint64_t do_read_mcounteren() const {
-        touch_page(machine_reg_address(machine_reg::mcounteren));
-        return m_m.get_state().mcounteren;
+        return log_read_reg(machine_reg::mcounteren);
     }
 
     void do_write_mcounteren(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::mcounteren));
-        m_m.get_state().mcounteren = val;
+        log_write_reg(machine_reg::mcounteren, val);
     }
 
     uint64_t do_read_senvcfg() const {
-        touch_page(machine_reg_address(machine_reg::senvcfg));
-        return m_m.get_state().senvcfg;
+        return log_read_reg(machine_reg::senvcfg);
     }
 
     void do_write_senvcfg(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::senvcfg));
-        m_m.get_state().senvcfg = val;
+        log_write_reg(machine_reg::senvcfg, val);
     }
 
     uint64_t do_read_stvec() const {
-        touch_page(machine_reg_address(machine_reg::stvec));
-        return m_m.get_state().stvec;
+        return log_read_reg(machine_reg::stvec);
     }
 
     void do_write_stvec(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::stvec));
-        m_m.get_state().stvec = val;
+        log_write_reg(machine_reg::stvec, val);
     }
 
     uint64_t do_read_sscratch() const {
-        touch_page(machine_reg_address(machine_reg::sscratch));
-        return m_m.get_state().sscratch;
+        return log_read_reg(machine_reg::sscratch);
     }
 
     void do_write_sscratch(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::sscratch));
-        m_m.get_state().sscratch = val;
+        log_write_reg(machine_reg::sscratch, val);
     }
 
     uint64_t do_read_sepc() const {
-        touch_page(machine_reg_address(machine_reg::sepc));
-        return m_m.get_state().sepc;
+        return log_read_reg(machine_reg::sepc);
     }
 
     void do_write_sepc(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::sepc));
-        m_m.get_state().sepc = val;
+        log_write_reg(machine_reg::sepc, val);
     }
 
     uint64_t do_read_scause() const {
-        touch_page(machine_reg_address(machine_reg::scause));
-        return m_m.get_state().scause;
+        return log_read_reg(machine_reg::scause);
     }
 
     void do_write_scause(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::scause));
-        m_m.get_state().scause = val;
+        log_write_reg(machine_reg::scause, val);
     }
 
     uint64_t do_read_stval() const {
-        touch_page(machine_reg_address(machine_reg::stval));
-        return m_m.get_state().stval;
+        return log_read_reg(machine_reg::stval);
     }
 
     void do_write_stval(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::stval));
-        m_m.get_state().stval = val;
+        log_write_reg(machine_reg::stval, val);
     }
 
     uint64_t do_read_satp() const {
-        touch_page(machine_reg_address(machine_reg::satp));
-        return m_m.get_state().satp;
+        return log_read_reg(machine_reg::satp);
     }
 
     void do_write_satp(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::satp));
-        m_m.get_state().satp = val;
+        log_write_reg(machine_reg::satp, val);
     }
 
     uint64_t do_read_scounteren() const {
-        touch_page(machine_reg_address(machine_reg::scounteren));
-        return m_m.get_state().scounteren;
+        return log_read_reg(machine_reg::scounteren);
     }
 
     void do_write_scounteren(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::scounteren));
-        m_m.get_state().scounteren = val;
+        log_write_reg(machine_reg::scounteren, val);
     }
 
     uint64_t do_read_ilrsc() const {
-        touch_page(machine_reg_address(machine_reg::ilrsc));
-        return m_m.get_state().ilrsc;
+        return log_read_reg(machine_reg::ilrsc);
     }
 
     void do_write_ilrsc(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::ilrsc));
-        m_m.get_state().ilrsc = val;
+        log_write_reg(machine_reg::ilrsc, val);
     }
 
     uint64_t do_read_iprv() const {
-        touch_page(machine_reg_address(machine_reg::iprv));
-        return m_m.get_state().iprv;
+        return log_read_reg(machine_reg::iprv);
     }
 
     void do_write_iprv(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::iprv));
-        m_m.get_state().iprv = val;
+        log_write_reg(machine_reg::iprv, val);
     }
 
     void do_write_iflags_X(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::iflags_X));
-        m_m.get_state().iflags.X = val;
+        log_write_reg(machine_reg::iflags_X, val);
     }
 
     uint64_t do_read_iflags_X() const {
-        touch_page(machine_reg_address(machine_reg::iflags_X));
-        return m_m.get_state().iflags.X;
+        return log_read_reg(machine_reg::iflags_X);
     }
 
     void do_write_iflags_Y(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::iflags_Y));
-        m_m.get_state().iflags.Y = val;
+        log_write_reg(machine_reg::iflags_Y, val);
     }
 
     uint64_t do_read_iflags_Y() const {
-        touch_page(machine_reg_address(machine_reg::iflags_Y));
-        return m_m.get_state().iflags.Y;
+        return log_read_reg(machine_reg::iflags_Y);
     }
 
     void do_write_iflags_H(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::iflags_H));
-        m_m.get_state().iflags.H = val;
+        log_write_reg(machine_reg::iflags_H, val);
     }
 
     uint64_t do_read_iflags_H() const {
-        touch_page(machine_reg_address(machine_reg::iflags_H));
-        return m_m.get_state().iflags.H;
+        return log_read_reg(machine_reg::iflags_H);
     }
 
     uint64_t do_read_iunrep() const {
-        touch_page(machine_reg_address(machine_reg::iunrep));
-        return m_m.get_state().iunrep;
+        return log_read_reg(machine_reg::iunrep);
     }
 
     void do_write_iunrep(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::iunrep));
-        m_m.get_state().iunrep = val;
+        log_write_reg(machine_reg::iunrep, val);
     }
 
     uint64_t do_read_clint_mtimecmp() const {
-        touch_page(machine_reg_address(machine_reg::clint_mtimecmp));
-        return m_m.get_state().clint.mtimecmp;
+        return log_read_reg(machine_reg::clint_mtimecmp);
     }
 
     void do_write_clint_mtimecmp(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::clint_mtimecmp));
-        m_m.get_state().clint.mtimecmp = val;
+        log_write_reg(machine_reg::clint_mtimecmp, val);
     }
 
     uint64_t do_read_plic_girqpend() const {
-        touch_page(machine_reg_address(machine_reg::plic_girqpend));
-        return m_m.get_state().plic.girqpend;
+        return log_read_reg(machine_reg::plic_girqpend);
     }
 
     void do_write_plic_girqpend(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::plic_girqpend));
-        m_m.get_state().plic.girqpend = val;
+        log_write_reg(machine_reg::plic_girqpend, val);
     }
 
     uint64_t do_read_plic_girqsrvd() const {
-        touch_page(machine_reg_address(machine_reg::plic_girqsrvd));
-        return m_m.get_state().plic.girqsrvd;
+        return log_read_reg(machine_reg::plic_girqsrvd);
     }
 
     void do_write_plic_girqsrvd(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::plic_girqsrvd));
-        m_m.get_state().plic.girqsrvd = val;
+        log_write_reg(machine_reg::plic_girqsrvd, val);
     }
 
     uint64_t do_read_htif_fromhost() const {
-        touch_page(machine_reg_address(machine_reg::htif_fromhost));
-        return m_m.get_state().htif.fromhost;
+        return log_read_reg(machine_reg::htif_fromhost);
     }
 
     void do_write_htif_fromhost(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::htif_fromhost));
-        m_m.get_state().htif.fromhost = val;
+        log_write_reg(machine_reg::htif_fromhost, val);
     }
 
     uint64_t do_read_htif_tohost() const {
-        touch_page(machine_reg_address(machine_reg::htif_tohost));
-        return m_m.get_state().htif.tohost;
+        return log_read_reg(machine_reg::htif_tohost);
     }
 
     void do_write_htif_tohost(uint64_t val) {
-        touch_page(machine_reg_address(machine_reg::htif_tohost));
-        m_m.get_state().htif.tohost = val;
+        log_write_reg(machine_reg::htif_tohost, val);
     }
 
     uint64_t do_read_htif_ihalt() const {
-        touch_page(machine_reg_address(machine_reg::htif_ihalt));
-        return m_m.get_state().htif.ihalt;
+        return log_read_reg(machine_reg::htif_ihalt);
     }
 
     uint64_t do_read_htif_iconsole() const {
-        touch_page(machine_reg_address(machine_reg::htif_iconsole));
-        return m_m.get_state().htif.iconsole;
+        return log_read_reg(machine_reg::htif_iconsole);
     }
 
     uint64_t do_read_htif_iyield() const {
-        touch_page(machine_reg_address(machine_reg::htif_iyield));
-        return m_m.get_state().htif.iyield;
+        return log_read_reg(machine_reg::htif_iyield);
     }
 
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
@@ -628,8 +566,8 @@ class record_step_state_access : public i_state_access<record_step_state_access>
         // replay_step_state_access reconstructs a mock_pma_entry from the
         // corresponding istart and ilength fields in the shadow pmas
         // so we mark the page where they live here
-        touch_page(shadow_pmas_get_pma_istart_abs_addr(index));
-        touch_page(shadow_pmas_get_pma_ilength_abs_addr(index));
+        touch_page(shadow_pmas_get_pma_abs_addr(index, shadow_pmas_what::istart));
+        touch_page(shadow_pmas_get_pma_abs_addr(index, shadow_pmas_what::ilength));
         // NOLINTNEXTLINE(bugprone-narrowing-conversions)
         return m_m.get_state().pmas[static_cast<int>(index)];
     }
@@ -646,27 +584,32 @@ class record_step_state_access : public i_state_access<record_step_state_access>
         aliased_aligned_write<T, A>(haddr, val);
     }
 
-    template <TLB_set_use USE>
+    template <TLB_set_index SET>
     uint64_t do_read_tlb_vaddr_page(uint64_t slot_index) {
-        touch_page(shadow_tlb_get_vaddr_page_abs_addr<USE>(slot_index));
-        return m_m.get_state().tlb.hot[USE][slot_index].vaddr_page;
+        return log_read_tlb(SET, slot_index, shadow_tlb_what::vaddr_page);
     }
 
-    template <TLB_set_use USE>
+    template <TLB_set_index SET>
+    uint64_t do_read_tlb_pma_index(uint64_t slot_index) {
+        return log_read_tlb(SET, slot_index, shadow_tlb_what::pma_index);
+    }
+
+    template <TLB_set_index SET>
     host_addr do_read_tlb_vp_offset(uint64_t slot_index) {
         // During initialization, replay_step_state_access translates all vp_offset to corresponding vh_offset
         // At deinitialization, it translates them back
         // To do that, it needs the corresponding paddr_page = vaddr_page + vp_offset, and page data itself
-        // It will only do the translation if the slot is valid and it has access to all required fields
-        // Obviously, the slot we are reading will be needed during replay, so we touch all the pages involved here.
-        touch_page(shadow_tlb_get_vaddr_page_abs_addr<USE>(slot_index));
-        touch_page(shadow_tlb_get_vp_offset_abs_addr<USE>(slot_index));
-        touch_page(shadow_tlb_get_pma_index_abs_addr<USE>(slot_index));
-        // writes to the TLB slot are atomic, so we know the values in a slot are ALWAYS internally consistent
-        const auto vaddr_page = m_m.get_state().tlb.hot[USE][slot_index].vaddr_page;
-        const auto vh_offset = m_m.get_state().tlb.hot[USE][slot_index].vh_offset;
+        // It will only do the translation if the slot is valid and the log has all required fields
+        // Obviously, the slot we are reading will be needed during replay
+        // vaddr_page, vp_offset, and pma_index are on the same page, so we only need touch one of them.
+        touch_page(shadow_tlb_get_abs_addr(SET, slot_index, shadow_tlb_what::vaddr_page));
+        // We still need to touch the page data
+        // Writes to the TLB slot are atomic, so we know the values in a slot are ALWAYS internally consistent.
+        // This means we can safely use all other fields to find paddr_page.
+        const auto vaddr_page = m_m.get_state().tlb.hot[SET][slot_index].vaddr_page;
+        const auto vh_offset = m_m.get_state().tlb.hot[SET][slot_index].vh_offset;
         if (vaddr_page != TLB_INVALID_PAGE) {
-            const auto pma_index = m_m.get_state().tlb.cold[USE][slot_index].pma_index;
+            const auto pma_index = m_m.get_state().tlb.cold[SET][slot_index].pma_index;
             const auto haddr_page = vaddr_page + vh_offset;
             auto paddr_page = m_m.get_paddr(haddr_page, pma_index);
             touch_page(paddr_page);
@@ -674,30 +617,24 @@ class record_step_state_access : public i_state_access<record_step_state_access>
         return vh_offset;
     }
 
-    template <TLB_set_use USE>
-    uint64_t do_read_tlb_pma_index(uint64_t slot_index) {
-        touch_page(shadow_tlb_get_pma_index_abs_addr<USE>(slot_index));
-        return m_m.get_state().tlb.cold[USE][slot_index].pma_index;
-    }
-
-    template <TLB_set_use USE>
+    template <TLB_set_index SET>
     void do_write_tlb(uint64_t slot_index, uint64_t vaddr_page, host_addr vh_offset, uint64_t pma_index) {
         // During initialization, replay_step_state_access translates all vp_offset to corresponding vh_offset
         // At deinitialization, it translates them back
         // To do that, it needs the corresponding paddr_page = vaddr_page + vp_offset, and page data itself
-        // It will only do the translation if the slot is valid and it has access to all required fields
-        // Obviously, the slot we are modifying will be needed during replay, so we touch all the pages involved here.
-        touch_page(shadow_tlb_get_vaddr_page_abs_addr<USE>(slot_index));
-        touch_page(shadow_tlb_get_vp_offset_abs_addr<USE>(slot_index));
-        touch_page(shadow_tlb_get_pma_index_abs_addr<USE>(slot_index));
-        m_m.get_state().tlb.hot[USE][slot_index].vaddr_page = vaddr_page;
-        m_m.get_state().tlb.hot[USE][slot_index].vh_offset = vh_offset;
-        m_m.get_state().tlb.cold[USE][slot_index].pma_index = pma_index;
+        // It will only do the translation if the slot is valid and the log has all required fields
+        // Obviously, the slot we are writing will be needed during replay
+        // vaddr_page, vp_offset, and pma_index are on the same page, so we only need touch one of them.
+        touch_page(shadow_tlb_get_abs_addr(SET, slot_index, shadow_tlb_what::vaddr_page));
+        // We still need to touch the page data
         if (vaddr_page != TLB_INVALID_PAGE) {
             const auto haddr_page = vaddr_page + vh_offset;
             auto paddr_page = m_m.get_paddr(haddr_page, pma_index);
             touch_page(paddr_page);
         }
+        m_m.get_state().tlb.hot[SET][slot_index].vaddr_page = vaddr_page;
+        m_m.get_state().tlb.hot[SET][slot_index].vh_offset = vh_offset;
+        m_m.get_state().tlb.cold[SET][slot_index].pma_index = pma_index;
     }
 
     fast_addr do_get_faddr(uint64_t paddr, uint64_t pma_index) const {
@@ -716,6 +653,10 @@ class record_step_state_access : public i_state_access<record_step_state_access>
         os_putchar(c);
     }
 
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    constexpr const char *do_get_name() const { // NOLINT(readability-convert-member-functions-to-static)
+        return "record_step_state_access";
+    }
 };
 
 } // namespace cartesi
diff --git a/src/replay-send-cmio-state-access.h b/src/replay-send-cmio-state-access.h
index 155c3a909..418f5ef9e 100644
--- a/src/replay-send-cmio-state-access.h
+++ b/src/replay-send-cmio-state-access.h
@@ -362,6 +362,11 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
         m_context.root_hash = proof.bubble_up(m_context.hasher, written_hash);
         m_context.next_access++;
     }
+
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    constexpr const char *do_get_name() const {
+        return "replay_send_cmio_state_access";
+    }
 };
 
 } // namespace cartesi
diff --git a/src/replay-step-state-access.h b/src/replay-step-state-access.h
index 0d757ac41..483840f5d 100644
--- a/src/replay-step-state-access.h
+++ b/src/replay-step-state-access.h
@@ -36,6 +36,10 @@
 #include "uarch-constants.h"
 #include "uarch-defines.h"
 
+#if DUMP_STATE_ACCESS
+#include "scoped-note.h"
+#endif
+
 namespace cartesi {
 
 // \file this code is designed to be compiled for a free-standing environment.
@@ -158,11 +162,16 @@ class replay_step_state_access : public i_state_access<replay_step_state_access>
             if (i > 0 && m_context.pages[i - 1].index >= m_context.pages[i].index) {
                 interop_throw_runtime_error("invalid log format: page index is not in increasing order");
             }
+            // In the current implementaiton, this check is unecessary
+            // But we may in the future change the data field to point to independently allocated pages
+            // This would break the code that uses binary search to find the page based on the address of its data
+            if (i > 0 && +m_context.pages[i - 1].data >= +m_context.pages[i].data) {
+                interop_throw_runtime_error("invalid log format: page data is not in increasing order");
+            }
             if (m_context.pages[i].hash != all_zeros) {
                 interop_throw_runtime_error("invalid log format: page scratch hash area is not zero");
             }
         }
-
         // compute  and check the machine root hash before the replay
         auto computed_root_hash_before = compute_root_hash();
         if (computed_root_hash_before != root_hash_before) {
@@ -193,6 +202,10 @@ class replay_step_state_access : public i_state_access<replay_step_state_access>
 private:
     friend i_state_access<replay_step_state_access>;
 
+    void do_putchar(uint8_t /*c*/) { // NOLINT(readability-convert-member-functions-to-static)
+        ;                            // do nothing
+    }
+
     /// \brief Try to find a page in the logged data by its physical address
     /// \param paddr The physical address of the page
     /// \return A pointer to the page_type structure if found, nullptr otherwise
@@ -237,12 +250,12 @@ class replay_step_state_access : public i_state_access<replay_step_state_access>
 
     // \brief Relocate all TLB vp_offset fields to vh_offset
     // \details This makes the translation point directly to logged page data
-    template <TLB_set_use USE>
+    template <TLB_set_index SET>
     void relocate_tlb_vp_offset_to_vh_offset() {
         for (uint64_t slot_index = 0; slot_index < TLB_SET_SIZE; ++slot_index) {
-            const auto vp_offset_field_addr = shadow_tlb_get_vp_offset_abs_addr<USE>(slot_index);
+            const auto vp_offset_field_addr = shadow_tlb_get_abs_addr(SET, slot_index, shadow_tlb_what::vp_offset);
             auto *vp_offset_log = try_find_page(vp_offset_field_addr & ~PAGE_OFFSET_MASK);
-            const auto vaddr_page_field_addr = shadow_tlb_get_vaddr_page_abs_addr<USE>(slot_index);
+            const auto vaddr_page_field_addr = shadow_tlb_get_abs_addr(SET, slot_index, shadow_tlb_what::vaddr_page);
             auto *vaddr_page_log = try_find_page(vaddr_page_field_addr & ~PAGE_OFFSET_MASK);
             // If vp_offset was accessed during record, both it and vaddr_apge will appear in the log
             // (record_step_state_access makes sure of it)
@@ -274,12 +287,12 @@ class replay_step_state_access : public i_state_access<replay_step_state_access>
 
     // \brief Reverses changes to TLB so we have vp_offset fields again instead of vh_offset
     // \details This makes the translation point back to target physical addresses
-    template <TLB_set_use USE>
+    template <TLB_set_index SET>
     void relocate_tlb_vh_offset_to_vp_offset() {
         for (uint64_t slot_index = 0; slot_index < TLB_SET_SIZE; ++slot_index) {
-            const auto vp_offset_field_addr = shadow_tlb_get_vp_offset_abs_addr<USE>(slot_index);
+            const auto vp_offset_field_addr = shadow_tlb_get_abs_addr(SET, slot_index, shadow_tlb_what::vp_offset);
             auto *vp_offset_log = try_find_page(vp_offset_field_addr & ~PAGE_OFFSET_MASK);
-            const auto vaddr_page_field_addr = shadow_tlb_get_vaddr_page_abs_addr<USE>(slot_index);
+            const auto vaddr_page_field_addr = shadow_tlb_get_abs_addr(SET, slot_index, shadow_tlb_what::vaddr_page);
             auto *vaddr_page_log = try_find_page(vaddr_page_field_addr & ~PAGE_OFFSET_MASK);
             // If vp_offset was accessed during record, both it and vaddr_apge will appear in the log
             // (record_step_state_access makes sure of it)
@@ -313,7 +326,7 @@ class replay_step_state_access : public i_state_access<replay_step_state_access>
     page_type *find_page(uint64_t paddr_page) const {
         auto *page_log = try_find_page(paddr_page);
         if (page_log == nullptr) {
-            interop_throw_runtime_error("find_page: page not found");
+            interop_throw_runtime_error("required page not found");
         }
         return page_log;
     }
@@ -321,7 +334,7 @@ class replay_step_state_access : public i_state_access<replay_step_state_access>
     page_type *find_page(host_addr haddr_page) const {
         auto *page_log = try_find_page(haddr_page);
         if (page_log == nullptr) {
-            interop_throw_runtime_error("find_page: page not found");
+            interop_throw_runtime_error("required page not found");
         }
         return page_log;
     }
@@ -340,46 +353,48 @@ class replay_step_state_access : public i_state_access<replay_step_state_access>
 
     // \brief Compute the current machine root hash
     hash_type compute_root_hash() {
+        //??D Here we should only do this for dirty pages, right?
+        //??D Initially, all pages are dirty, because we don't know their hashes
+        //??D But in the end, we should only update those pages that we touched
+        //??D May improve performance when we are running this on ZK
         for (uint64_t i = 0; i < m_context.page_count; i++) {
             interop_merkle_tree_hash(m_context.pages[i].data, PMA_PAGE_SIZE,
                 // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
                 reinterpret_cast<interop_hash_type>(&m_context.pages[i].hash));
         }
-
         size_t next_page = 0;
         size_t next_sibling = 0;
         auto root_hash =
             compute_root_hash_impl(0, interop_log2_root_size - PMA_PAGE_SIZE_LOG2, next_page, next_sibling);
         if (next_page != m_context.page_count) {
-            interop_throw_runtime_error("compute_root_hash: next_page != m_context.page_count");
+            interop_throw_runtime_error("too many pages in log");
         }
         if (next_sibling != m_context.sibling_count) {
-            interop_throw_runtime_error("compute_root_hash: sibling hashes not totally consumed");
+            interop_throw_runtime_error("too many sibling hashes in log");
         }
         return root_hash;
     }
 
     // \brief Compute the root hash of a memory range recursively
     // \param page_index Index of the first page in the range
-    // \param page_count_log2_size Log2 of the size of number of pages in the range
+    // \param log2_page_count Log2 of the size of number of pages in the range
     // \param next_page Index of the next page to be visited
     // \param next_sibling Index of the next sibling hash to be visited
     // \return Resulting root hash of the range
-    hash_type compute_root_hash_impl(address_type page_index, int page_count_log2_size, size_t &next_page,
+    hash_type compute_root_hash_impl(address_type page_index, int log2_page_count, size_t &next_page,
         size_t &next_sibling) {
         // NOLINTBEGIN(cppcoreguidelines-pro-type-reinterpret-cast))
-        auto page_count = UINT64_C(1) << page_count_log2_size;
+        auto page_count = UINT64_C(1) << log2_page_count;
         if (next_page >= m_context.page_count || page_index + page_count <= m_context.pages[next_page].index) {
             if (next_sibling >= m_context.sibling_count) {
-                interop_throw_runtime_error(
-                    "compute_root_hash_impl: trying to access beyond sibling count while skipping range");
+                interop_throw_runtime_error("too few sibling hashes in log");
             }
             return m_context.sibling_hashes[next_sibling++];
         }
-        if (page_count_log2_size > 0) {
-            auto left = compute_root_hash_impl(page_index, page_count_log2_size - 1, next_page, next_sibling);
-            auto right = compute_root_hash_impl(page_index + (UINT64_C(1) << (page_count_log2_size - 1)),
-                page_count_log2_size - 1, next_page, next_sibling);
+        if (log2_page_count > 0) {
+            auto left = compute_root_hash_impl(page_index, log2_page_count - 1, next_page, next_sibling);
+            const auto halfway_page_index = page_index + (page_count >> 1);
+            auto right = compute_root_hash_impl(halfway_page_index, log2_page_count - 1, next_page, next_sibling);
             hash_type hash{};
             interop_concat_hash(reinterpret_cast<interop_hash_type>(&left), reinterpret_cast<interop_hash_type>(&right),
                 reinterpret_cast<interop_hash_type>(&hash));
@@ -389,434 +404,362 @@ class replay_step_state_access : public i_state_access<replay_step_state_access>
             return m_context.pages[next_page++].hash;
         }
         if (next_sibling >= m_context.sibling_count) {
-            interop_throw_runtime_error("compute_root_hash_impl: trying to access beyond sibling count");
+            interop_throw_runtime_error("too few sibling hashes in log");
         }
         return m_context.sibling_hashes[next_sibling++];
         // NOLINTEND(cppcoreguidelines-pro-type-reinterpret-cast))
     }
 
+#ifdef DUMP_STATE_ACCESS
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    void do_push_bracket(bracket_type type, const char *text) {
-        (void) type;
-        (void) text;
-    }
-
-    int do_make_scoped_note(const char *text) { // NOLINT(readability-convert-member-functions-to-static)
-        (void) text;
-        return 0;
+    auto do_make_scoped_note([[maybe_unused]] const char *text) {
+        return scoped_note<replay_step_state_access>{*this, text};
     }
+#endif
 
     //??D we should probably optimize access to the shadow so it doesn't perform a translation every time
     // We can do this by caching the vh_offset trasnslation of the processor shadow page. This is easy if
     // static_assert(sizeof(shadow_state) <= PMA_PAGE_SIZE, "shadow state must fit in single page");
-    uint64_t do_read_x(int reg) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::x0, reg));
+    uint64_t check_read_reg(machine_reg reg) const {
+        const auto haddr = do_get_faddr(machine_reg_address(reg));
         return aliased_aligned_read<uint64_t>(haddr);
     }
 
-    void do_write_x(int reg, uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::x0, reg));
+    //??D we should probably optimize access to the shadow so it doesn't perform a translation every time
+    // We can do this by caching the vh_offset trasnslation of the processor shadow page. This is easy if
+    // static_assert(sizeof(shadow_state) <= PMA_PAGE_SIZE, "shadow state must fit in single page");
+    void check_write_reg(machine_reg reg, uint64_t val) {
+        const auto haddr = do_get_faddr(machine_reg_address(reg));
         aliased_aligned_write<uint64_t>(haddr, val);
     }
 
-    uint64_t do_read_f(int reg) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::f0, reg));
-        return aliased_aligned_read<uint64_t>(haddr);
+    uint64_t do_read_x(int i) {
+        return check_read_reg(machine_reg_enum(machine_reg::x0, i));
     }
 
-    void do_write_f(int reg, uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::f0, reg));
-        aliased_aligned_write<uint64_t>(haddr, val);
+    void do_write_x(int i, uint64_t val) {
+        assert(i != 0);
+        check_write_reg(machine_reg_enum(machine_reg::x0, i), val);
+    }
+
+    uint64_t do_read_f(int i) {
+        return check_read_reg(machine_reg_enum(machine_reg::f0, i));
+    }
+
+    void do_write_f(int i, uint64_t val) {
+        check_write_reg(machine_reg_enum(machine_reg::f0, i), val);
     }
 
     uint64_t do_read_pc() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::pc));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::pc);
     }
 
     void do_write_pc(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::pc));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::pc, val);
     }
 
     uint64_t do_read_fcsr() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::fcsr));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::fcsr);
     }
 
     void do_write_fcsr(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::fcsr));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::fcsr, val);
     }
 
     uint64_t do_read_icycleinstret() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::icycleinstret));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::icycleinstret);
     }
 
     void do_write_icycleinstret(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::icycleinstret));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::icycleinstret, val);
     }
 
     uint64_t do_read_mvendorid() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mvendorid));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::mvendorid);
     }
 
     uint64_t do_read_marchid() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::marchid));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::marchid);
     }
 
     uint64_t do_read_mimpid() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mimpid));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::mimpid);
     }
 
     uint64_t do_read_mcycle() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mcycle));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::mcycle);
     }
 
     void do_write_mcycle(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mcycle));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::mcycle, val);
     }
 
     uint64_t do_read_mstatus() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mstatus));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::mstatus);
     }
 
     void do_write_mstatus(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mstatus));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::mstatus, val);
     }
 
     uint64_t do_read_mtvec() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mtvec));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::mtvec);
     }
 
     void do_write_mtvec(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mtvec));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::mtvec, val);
     }
 
     uint64_t do_read_mscratch() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mscratch));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::mscratch);
     }
 
     void do_write_mscratch(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mscratch));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::mscratch, val);
     }
 
     uint64_t do_read_mepc() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mepc));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::mepc);
     }
 
     void do_write_mepc(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mepc));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::mepc, val);
     }
 
     uint64_t do_read_mcause() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mcause));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::mcause);
     }
 
     void do_write_mcause(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mcause));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::mcause, val);
     }
 
     uint64_t do_read_mtval() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mtval));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::mtval);
     }
 
     void do_write_mtval(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mtval));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::mtval, val);
     }
 
     uint64_t do_read_misa() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::misa));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::misa);
     }
 
     void do_write_misa(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::misa));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::misa, val);
     }
 
     uint64_t do_read_mie() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mie));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::mie);
     }
 
     void do_write_mie(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mie));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::mie, val);
     }
 
     uint64_t do_read_mip() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mip));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::mip);
     }
 
     void do_write_mip(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mip));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::mip, val);
     }
 
     uint64_t do_read_medeleg() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::medeleg));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::medeleg);
     }
 
     void do_write_medeleg(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::medeleg));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::medeleg, val);
     }
 
     uint64_t do_read_mideleg() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mideleg));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::mideleg);
     }
 
     void do_write_mideleg(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mideleg));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::mideleg, val);
     }
 
     uint64_t do_read_mcounteren() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mcounteren));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::mcounteren);
     }
 
     void do_write_mcounteren(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::mcounteren));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::mcounteren, val);
     }
 
-    uint64_t do_read_senvcfg() const {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::senvcfg));
-        return aliased_aligned_read<uint64_t>(haddr);
+    uint64_t do_read_senvcfg() {
+        return check_read_reg(machine_reg::senvcfg);
     }
 
     void do_write_senvcfg(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::senvcfg));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::senvcfg, val);
     }
 
-    uint64_t do_read_menvcfg() const {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::menvcfg));
-        return aliased_aligned_read<uint64_t>(haddr);
+    uint64_t do_read_menvcfg() {
+        return check_read_reg(machine_reg::menvcfg);
     }
 
     void do_write_menvcfg(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::menvcfg));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::menvcfg, val);
     }
 
     uint64_t do_read_stvec() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::stvec));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::stvec);
     }
 
     void do_write_stvec(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::stvec));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::stvec, val);
     }
 
     uint64_t do_read_sscratch() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::sscratch));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::sscratch);
     }
 
     void do_write_sscratch(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::sscratch));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::sscratch, val);
     }
 
     uint64_t do_read_sepc() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::sepc));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::sepc);
     }
 
     void do_write_sepc(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::sepc));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::sepc, val);
     }
 
     uint64_t do_read_scause() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::scause));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::scause);
     }
 
     void do_write_scause(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::scause));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::scause, val);
     }
 
     uint64_t do_read_stval() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::stval));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::stval);
     }
 
     void do_write_stval(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::stval));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::stval, val);
     }
 
     uint64_t do_read_satp() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::satp));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::satp);
     }
 
     void do_write_satp(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::satp));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::satp, val);
     }
 
     uint64_t do_read_scounteren() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::scounteren));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::scounteren);
     }
 
     void do_write_scounteren(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::scounteren));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::scounteren, val);
     }
 
     uint64_t do_read_ilrsc() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::ilrsc));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::ilrsc);
     }
 
     void do_write_ilrsc(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::ilrsc));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::ilrsc, val);
     }
 
     uint64_t do_read_iprv() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::iprv));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::iprv);
     }
 
     void do_write_iprv(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::iprv));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::iprv, val);
     }
 
     uint64_t do_read_iflags_X() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::iflags_X));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::iflags_X);
     }
 
     void do_write_iflags_X(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::iflags_X));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::iflags_X, val);
     }
 
     uint64_t do_read_iflags_Y() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::iflags_Y));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::iflags_Y);
     }
 
     void do_write_iflags_Y(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::iflags_Y));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::iflags_Y, val);
     }
 
     uint64_t do_read_iflags_H() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::iflags_H));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::iflags_H);
     }
 
     void do_write_iflags_H(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::iflags_H));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::iflags_H, val);
     }
 
     uint64_t do_read_iunrep() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::iunrep));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::iunrep);
     }
 
     void do_write_iunrep(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::iunrep));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::iunrep, val);
     }
 
     uint64_t do_read_clint_mtimecmp() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::clint_mtimecmp));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::clint_mtimecmp);
     }
 
     void do_write_clint_mtimecmp(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::clint_mtimecmp));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::clint_mtimecmp, val);
     }
 
     uint64_t do_read_plic_girqpend() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::plic_girqpend));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::plic_girqpend);
     }
 
     void do_write_plic_girqpend(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::plic_girqpend));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::plic_girqpend, val);
     }
 
     uint64_t do_read_plic_girqsrvd() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::plic_girqsrvd));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::plic_girqsrvd);
     }
 
     void do_write_plic_girqsrvd(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::plic_girqsrvd));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::plic_girqsrvd, val);
     }
 
     uint64_t do_read_htif_fromhost() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::htif_fromhost));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::htif_fromhost);
     }
 
     void do_write_htif_fromhost(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::htif_fromhost));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::htif_fromhost, val);
     }
 
     uint64_t do_read_htif_tohost() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::htif_tohost));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::htif_tohost);
     }
 
     void do_write_htif_tohost(uint64_t val) {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::htif_tohost));
-        aliased_aligned_write<uint64_t>(haddr, val);
+        check_write_reg(machine_reg::htif_tohost, val);
     }
 
     uint64_t do_read_htif_ihalt() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::htif_ihalt));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::htif_ihalt);
     }
 
     uint64_t do_read_htif_iconsole() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::htif_iconsole));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::htif_iconsole);
     }
 
     uint64_t do_read_htif_iyield() {
-        const auto haddr = do_get_faddr(machine_reg_address(machine_reg::htif_iyield));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_reg(machine_reg::htif_iyield);
     }
 
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
@@ -836,12 +779,12 @@ class replay_step_state_access : public i_state_access<replay_step_state_access>
     }
 
     uint64_t read_pma_istart(uint64_t index) {
-        const auto haddr = do_get_faddr(shadow_pmas_get_pma_istart_abs_addr(index));
+        const auto haddr = do_get_faddr(shadow_pmas_get_pma_abs_addr(index, shadow_pmas_what::istart));
         return aliased_aligned_read<uint64_t>(haddr);
     }
 
     uint64_t read_pma_ilength(uint64_t index) {
-        const auto haddr = do_get_faddr(shadow_pmas_get_pma_ilength_abs_addr(index));
+        const auto haddr = do_get_faddr(shadow_pmas_get_pma_abs_addr(index, shadow_pmas_what::ilength));
         return aliased_aligned_read<uint64_t>(haddr);
     }
 
@@ -871,32 +814,38 @@ class replay_step_state_access : public i_state_access<replay_step_state_access>
         aliased_aligned_write<T, A>(haddr, val);
     }
 
-    template <TLB_set_use USE>
+    template <typename TYPE>
+    auto check_read_tlb(TLB_set_index set_index, uint64_t slot_index, shadow_tlb_what what) {
+        const auto haddr = do_get_faddr(shadow_tlb_get_abs_addr(set_index, slot_index, what));
+        return aliased_aligned_read<TYPE>(haddr);
+    }
+
+    template <TLB_set_index SET>
     uint64_t do_read_tlb_vaddr_page(uint64_t slot_index) {
-        const auto haddr = do_get_faddr(shadow_tlb_get_vaddr_page_abs_addr<USE>(slot_index));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_tlb<uint64_t>(SET, slot_index, shadow_tlb_what::vaddr_page);
     }
 
-    template <TLB_set_use USE>
+    template <TLB_set_index SET>
     host_addr do_read_tlb_vp_offset(uint64_t slot_index) {
-        const auto haddr = do_get_faddr(shadow_tlb_get_vp_offset_abs_addr<USE>(slot_index));
-        return aliased_aligned_read<host_addr>(haddr);
+        return check_read_tlb<host_addr>(SET, slot_index, shadow_tlb_what::vp_offset);
     }
 
-    template <TLB_set_use USE>
+    template <TLB_set_index SET>
     uint64_t do_read_tlb_pma_index(uint64_t slot_index) {
-        const auto haddr = do_get_faddr(shadow_tlb_get_pma_index_abs_addr<USE>(slot_index));
-        return aliased_aligned_read<uint64_t>(haddr);
+        return check_read_tlb<uint64_t>(SET, slot_index, shadow_tlb_what::pma_index);
     }
 
-    template <TLB_set_use USE>
+    template <typename TYPE>
+    auto check_write_tlb(TLB_set_index set_index, uint64_t slot_index, shadow_tlb_what what, TYPE val) {
+        const auto haddr = do_get_faddr(shadow_tlb_get_abs_addr(set_index, slot_index, what));
+        aliased_aligned_write<TYPE>(haddr, val);
+    }
+
+    template <TLB_set_index SET>
     void do_write_tlb(uint64_t slot_index, uint64_t vaddr_page, host_addr vh_offset, uint64_t pma_index) {
-        const auto haddr_vaddr_page = do_get_faddr(shadow_tlb_get_vaddr_page_abs_addr<USE>(slot_index));
-        aliased_aligned_write<uint64_t>(haddr_vaddr_page, vaddr_page);
-        const auto haddr_vp_offset = do_get_faddr(shadow_tlb_get_vp_offset_abs_addr<USE>(slot_index));
-        aliased_aligned_write<host_addr>(haddr_vp_offset, vh_offset);
-        const auto haddr_pma_index = do_get_faddr(shadow_tlb_get_pma_index_abs_addr<USE>(slot_index));
-        aliased_aligned_write<uint64_t>(haddr_pma_index, pma_index);
+        check_write_tlb(SET, slot_index, shadow_tlb_what::vaddr_page, vaddr_page);
+        check_write_tlb(SET, slot_index, shadow_tlb_what::vp_offset, vh_offset);
+        check_write_tlb(SET, slot_index, shadow_tlb_what::pma_index, pma_index);
     }
 
     void do_mark_dirty_page(host_addr /* haddr */, uint64_t /* pma_index */) {
@@ -904,11 +853,9 @@ class replay_step_state_access : public i_state_access<replay_step_state_access>
     }
 
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    std::pair<uint64_t, bool> do_poll_external_interrupts(uint64_t mcycle, uint64_t mcycle_max) {
-        (void) mcycle_max;
-        return {mcycle, false};
+    constexpr const char *do_get_name() const { // NOLINT(readability-convert-member-functions-to-static)
+        return "replay_step_state_access";
     }
-
 };
 
 } // namespace cartesi
diff --git a/src/scoped-note.h b/src/scoped-note.h
new file mode 100644
index 000000000..b5286b092
--- /dev/null
+++ b/src/scoped-note.h
@@ -0,0 +1,52 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef SCOPED_NOTE_H
+#define SCOPED_NOTE_H
+
+namespace cartesi {
+
+/// \brief Adds annotations to the state, bracketing a scope
+template <typename STATE_ACCESS>
+class scoped_note {
+
+    STATE_ACCESS &m_a;
+    const char *const m_text; ///< String with the text for the annotation
+
+public:
+    /// \brief Constructor adds the "begin" bracketing note
+    /// \param a State access receiving annotations
+    /// \param text Pointer to annotation text (must be valid until destruction)
+    /// \details A note is added at the moment of construction and destruction
+    scoped_note(STATE_ACCESS &a, const char *text) : m_a{a}, m_text(text) {
+        m_a.push_begin_bracket(m_text);
+    }
+
+    /// \brief No assignments/copies
+    scoped_note(const scoped_note &) = delete;
+    scoped_note &operator=(const scoped_note &) = delete;
+    scoped_note(scoped_note &&) = delete;
+    scoped_note &operator=(scoped_note &&) = delete;
+
+    /// \brief Destructor adds the "end" bracketing note
+    ~scoped_note() {
+        m_a.push_end_bracket(m_text);
+    }
+};
+
+} // namespace cartesi
+
+#endif // SCOPED_NOTE_H
diff --git a/src/shadow-peek.h b/src/shadow-peek.h
new file mode 100644
index 000000000..9275edfda
--- /dev/null
+++ b/src/shadow-peek.h
@@ -0,0 +1,68 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef SHADOW_PEEK_H
+#define SHADOW_PEEK_H
+
+#include <cstdint>
+#include <cstring>
+
+#include "machine-reg.h"
+#include "machine.h"
+#include "pma.h"
+
+namespace cartesi {
+
+/// \file
+/// \brief Peeks part of a shadow
+template <typename READ_REG_F>
+static bool shadow_peek(READ_REG_F read_reg, const pma_entry &pma, const machine &m, uint64_t offset, uint64_t length,
+    const unsigned char **data, unsigned char *scratch) {
+    // Must be inside range
+    if (!pma.contains(pma.get_start() + offset, length)) {
+        *data = nullptr;
+        return false;
+    }
+    // Initial, potentially partial register read
+    const uint64_t offset_aligned = offset & ~(sizeof(uint64_t) - 1);
+    if (offset > offset_aligned) {
+        const auto val = read_reg(m, pma.get_start() + offset_aligned);
+        const auto partial = offset - offset_aligned;
+        memcpy(scratch, &val, partial);
+        length -= partial;
+        offset += partial;
+    }
+    // Now we are aligned, do all complete registers
+    const uint64_t paddr_start = pma.get_start() + offset;
+    const uint64_t length_aligned = length & ~(sizeof(uint64_t) - 1);
+    const uint64_t paddr_end = paddr_start + length_aligned;
+    for (uint64_t paddr = paddr_start; paddr < paddr_end; paddr += sizeof(uint64_t)) {
+        const auto val = read_reg(m, paddr);
+        aliased_aligned_write<uint64_t>(scratch + (paddr - paddr_start), val);
+    }
+    // Final, potentially partial register read
+    if (length > length_aligned) {
+        const auto partial = length - length_aligned;
+        const auto val = read_reg(m, paddr_end);
+        memcpy(scratch + length_aligned, &val, partial);
+    }
+    *data = scratch;
+    return true;
+}
+
+} // namespace cartesi
+
+#endif
diff --git a/src/shadow-pmas-factory.h b/src/shadow-pmas-factory.h
index 35514872f..008f37bed 100644
--- a/src/shadow-pmas-factory.h
+++ b/src/shadow-pmas-factory.h
@@ -31,11 +31,15 @@ pma_entry make_shadow_pmas_pma_entry(uint64_t start, uint64_t length);
 
 template <typename PMAS>
 void populate_shadow_pmas_state(const PMAS &pmas, shadow_pmas_state *shadow) {
-    static_assert(PMA_SHADOW_PMAS_LENGTH >= sizeof(shadow_pmas_state), "shadow PMAs length is too small");
+    static_assert(sizeof(shadow_pmas_state) == PMA_MAX * 2 * sizeof(uint64_t), "inconsistent shadow PMAs length");
+    static_assert(PMA_SHADOW_PMAS_LENGTH >= sizeof(shadow_pmas_state), "shadow PMAs not long enough");
+    if (pmas.size() > PMA_MAX) {
+        throw std::invalid_argument{"more PMAs than shadow PMAs can hold"};
+    }
     unsigned index = 0;
     for (const auto &pma : pmas) {
-        shadow->pmas[index].istart = pma.get_istart();
-        shadow->pmas[index].ilength = pma.get_ilength();
+        (*shadow)[index].istart = pma.get_istart();
+        (*shadow)[index].ilength = pma.get_ilength();
         ++index;
     }
 }
diff --git a/src/shadow-pmas.h b/src/shadow-pmas.h
index 60a2df6df..662d0fcd5 100644
--- a/src/shadow-pmas.h
+++ b/src/shadow-pmas.h
@@ -17,6 +17,7 @@
 #ifndef SHADOW_PMAS_H
 #define SHADOW_PMAS_H
 
+#include <array>
 #include <cassert>
 #include <cstdint>
 
@@ -36,31 +37,60 @@ struct PACKED shadow_pma_entry {
     uint64_t ilength;
 };
 
-struct PACKED shadow_pmas_state {
-    shadow_pma_entry pmas[PMA_MAX];
+using shadow_pmas_state = std::array<shadow_pma_entry, PMA_MAX>;
+
+/// \brief List of field types
+enum class shadow_pmas_what : uint64_t {
+    istart = offsetof(shadow_pma_entry, istart),
+    ilength = offsetof(shadow_pma_entry, ilength),
+    unknown_ = UINT64_C(1) << 63, // Outside of RISC-V address space
 };
 
-/// \brief Obtains the relative address of a PMA entry in shadow memory.
-/// \param p Index of desired shadow PMA entry, in 0..31.
+/// \brief Obtains the absolute address of a PMA entry in shadow memory.
+/// \param p Index of desired shadow PMA entry
 /// \returns The address.
-static inline uint64_t shadow_pmas_get_pma_rel_addr(uint64_t p) {
-    assert(p < (int) PMA_MAX);
-    return p * sizeof(shadow_pma_entry);
+static constexpr uint64_t shadow_pmas_get_pma_abs_addr(uint64_t p) {
+    return PMA_SHADOW_PMAS_START + p * sizeof(shadow_pma_entry);
 }
 
 /// \brief Obtains the absolute address of a PMA entry in shadow memory.
-static inline uint64_t shadow_pmas_get_pma_abs_addr(uint64_t p) {
-    return PMA_SHADOW_PMAS_START + shadow_pmas_get_pma_rel_addr(p);
+/// \param p Index of desired shadow PMA entry
+/// \param what Desired field
+/// \returns The address.
+static constexpr uint64_t shadow_pmas_get_pma_abs_addr(uint64_t p, shadow_pmas_what what) {
+    return shadow_pmas_get_pma_abs_addr(p) + static_cast<uint64_t>(what);
 }
 
-/// \brief Obtains the absolute address of the istart field in a PMA entry in shadow memory.
-static inline uint64_t shadow_pmas_get_pma_istart_abs_addr(uint64_t p) {
-    return shadow_pmas_get_pma_abs_addr(p) + offsetof(shadow_pma_entry, istart);
+static constexpr shadow_pmas_what shadow_pmas_get_what(uint64_t paddr) {
+    if (paddr < PMA_SHADOW_PMAS_START || paddr - PMA_SHADOW_PMAS_START >= sizeof(shadow_pmas_state) ||
+        (paddr & (sizeof(uint64_t) - 1)) != 0) {
+        return shadow_pmas_what::unknown_;
+    }
+    //??D First condition ensures offset = (paddr-PMA_SHADOW_PMAS_START) >= 0
+    //??D Second ensures offset < sizeof(shadow_pmas_state)
+    //??D Third ensures offset is aligned to sizeof(uint64_t)
+    //??D shadow_pma_entry only contains uint64_t fields
+    //??D shadow_pmas_state_what contains one entry with the offset of each field in shadow_pma_entry
+    //??D I don't see how the cast can produce something outside the enum...
+    // NOLINTNEXTLINE(clang-analyzer-optin.core.EnumCastOutOfRange)
+    return shadow_pmas_what{(paddr - PMA_SHADOW_PMAS_START) % sizeof(shadow_pma_entry)};
 }
 
-/// \brief Obtains the absolute address of the ilength field in a PMA entry in shadow memory.
-static inline uint64_t shadow_pmas_get_pma_ilength_abs_addr(uint64_t p) {
-    return shadow_pmas_get_pma_abs_addr(p) + offsetof(shadow_pma_entry, ilength);
+static constexpr const char *shadow_pmas_get_what_name(shadow_pmas_what what) {
+    const auto paddr = static_cast<uint64_t>(what);
+    if (paddr < PMA_SHADOW_PMAS_START || paddr - PMA_SHADOW_PMAS_START >= sizeof(shadow_pmas_state) ||
+        (paddr & (sizeof(uint64_t) - 1)) != 0) {
+        return "pma.unknown";
+    }
+    using reg = shadow_pmas_what;
+    switch (what) {
+        case reg::istart:
+            return "pma.istart";
+        case reg::ilength:
+            return "pma.ilength";
+        case reg::unknown_:
+            return "pma.unknown";
+    }
 }
 
 } // namespace cartesi
diff --git a/src/shadow-state-factory.cpp b/src/shadow-state-factory.cpp
index d055a63da..e87c975f1 100644
--- a/src/shadow-state-factory.cpp
+++ b/src/shadow-state-factory.cpp
@@ -14,91 +14,36 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#include "shadow-state-factory.h"
-
 #include <cstdint>
-#include <cstring>
 
 #include "machine.h"
 #include "pma-constants.h"
 #include "pma.h"
-#include "riscv-constants.h"
+#include "shadow-peek.h"
+#include "shadow-state-factory.h"
 #include "shadow-state.h"
 
 namespace cartesi {
 
 /// \brief Shadow device peek callback. See ::pma_peek.
-static bool shadow_state_peek(const pma_entry & /*pma*/, const machine &m, uint64_t page_offset,
-    const unsigned char **page_data, unsigned char *scratch) {
-    static_assert(sizeof(shadow_state) <= PMA_PAGE_SIZE);
-
-    // There is only one page: 0
-    if (page_offset != 0) {
-        *page_data = nullptr;
-        return false;
-    }
-    // Clear page
-    memset(scratch, 0, PMA_PAGE_SIZE);
-
-    // The page will reflect the shadow structure
-    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-    auto *s = reinterpret_cast<shadow_state *>(scratch);
-
-    // Copy general-purpose registers
-    for (int i = 0; i < X_REG_COUNT; ++i) {
-        s->x[i] = m.read_reg(machine_reg_enum(machine_reg::x0, i));
+static bool shadow_state_peek(const pma_entry &pma, const machine &m, uint64_t offset, uint64_t length,
+    const unsigned char **data, unsigned char *scratch) {
+    // If past useful range
+    if (offset >= sizeof(shadow_state)) {
+        *data = nullptr;
+        return length <= pma.get_length() && offset <= pma.get_length() - length;
     }
-
-    // Copy floating-point registers
-    for (int i = 0; i < F_REG_COUNT; ++i) {
-        s->f[i] = m.read_reg(machine_reg_enum(machine_reg::f0, i));
-    }
-
-    // Copy named registers
-    s->pc = m.read_reg(machine_reg::pc);
-    s->fcsr = m.read_reg(machine_reg::fcsr);
-    s->mvendorid = m.read_reg(machine_reg::mvendorid);
-    s->marchid = m.read_reg(machine_reg::marchid);
-    s->mimpid = m.read_reg(machine_reg::mimpid);
-    s->mcycle = m.read_reg(machine_reg::mcycle);
-    s->icycleinstret = m.read_reg(machine_reg::icycleinstret);
-    s->mstatus = m.read_reg(machine_reg::mstatus);
-    s->mtvec = m.read_reg(machine_reg::mtvec);
-    s->mscratch = m.read_reg(machine_reg::mscratch);
-    s->mepc = m.read_reg(machine_reg::mepc);
-    s->mcause = m.read_reg(machine_reg::mcause);
-    s->mtval = m.read_reg(machine_reg::mtval);
-    s->misa = m.read_reg(machine_reg::misa);
-    s->mie = m.read_reg(machine_reg::mie);
-    s->mip = m.read_reg(machine_reg::mip);
-    s->medeleg = m.read_reg(machine_reg::medeleg);
-    s->mideleg = m.read_reg(machine_reg::mideleg);
-    s->mcounteren = m.read_reg(machine_reg::mcounteren);
-    s->menvcfg = m.read_reg(machine_reg::menvcfg);
-    s->stvec = m.read_reg(machine_reg::stvec);
-    s->sscratch = m.read_reg(machine_reg::sscratch);
-    s->sepc = m.read_reg(machine_reg::sepc);
-    s->scause = m.read_reg(machine_reg::scause);
-    s->stval = m.read_reg(machine_reg::stval);
-    s->satp = m.read_reg(machine_reg::satp);
-    s->scounteren = m.read_reg(machine_reg::scounteren);
-    s->senvcfg = m.read_reg(machine_reg::senvcfg);
-    s->ilrsc = m.read_reg(machine_reg::ilrsc);
-    s->iprv = m.read_reg(machine_reg::iprv);
-    s->iflags_X = m.read_reg(machine_reg::iflags_X);
-    s->iflags_Y = m.read_reg(machine_reg::iflags_Y);
-    s->iflags_H = m.read_reg(machine_reg::iflags_H);
-    s->iunrep = m.read_reg(machine_reg::iunrep);
-    s->clint_mtimecmp = m.read_reg(machine_reg::clint_mtimecmp);
-    s->plic_girqpend = m.read_reg(machine_reg::plic_girqpend);
-    s->plic_girqsrvd = m.read_reg(machine_reg::plic_girqsrvd);
-    s->htif_tohost = m.read_reg(machine_reg::htif_tohost);
-    s->htif_fromhost = m.read_reg(machine_reg::htif_fromhost);
-    s->htif_ihalt = m.read_reg(machine_reg::htif_ihalt);
-    s->htif_iconsole = m.read_reg(machine_reg::htif_iconsole);
-    s->htif_iyield = m.read_reg(machine_reg::htif_iyield);
-    *page_data = scratch;
-    return true;
+    // Otherwise, copy and return register data
+    return shadow_peek(
+        [](const machine &m, uint64_t paddr) {
+            auto reg = shadow_state_get_what(paddr);
+            uint64_t val = 0;
+            if (reg != shadow_state_what::unknown_) {
+                val = m.read_reg(machine_reg_enum(reg));
+            }
+            return val;
+        },
+        pma, m, offset, length, data, scratch);
 }
 
 pma_entry make_shadow_state_pma_entry(uint64_t start, uint64_t length) {
@@ -108,8 +53,7 @@ pma_entry make_shadow_state_pma_entry(uint64_t start, uint64_t length) {
         .IR = false,
         .IW = false,
         .DID = PMA_ISTART_DID::shadow_state};
-    return make_device_pma_entry("shadow state device", start, length, shadow_state_peek, &shadow_state_driver)
-        .set_flags(f);
+    return make_device_pma_entry("shadow state", start, length, shadow_state_peek, &shadow_state_driver).set_flags(f);
 }
 
 } // namespace cartesi
diff --git a/src/shadow-state.h b/src/shadow-state.h
index 720112679..0d22ea2c6 100644
--- a/src/shadow-state.h
+++ b/src/shadow-state.h
@@ -79,6 +79,351 @@ struct PACKED shadow_state {
     uint64_t htif_iyield;
 };
 
+enum class shadow_state_what : uint64_t {
+    x0 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[0]),
+    x1 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[1]),
+    x2 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[2]),
+    x3 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[3]),
+    x4 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[4]),
+    x5 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[5]),
+    x6 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[6]),
+    x7 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[7]),
+    x8 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[8]),
+    x9 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[9]),
+    x10 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[10]),
+    x11 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[11]),
+    x12 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[12]),
+    x13 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[13]),
+    x14 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[14]),
+    x15 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[15]),
+    x16 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[16]),
+    x17 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[17]),
+    x18 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[18]),
+    x19 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[19]),
+    x20 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[20]),
+    x21 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[21]),
+    x22 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[22]),
+    x23 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[23]),
+    x24 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[24]),
+    x25 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[25]),
+    x26 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[26]),
+    x27 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[27]),
+    x28 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[28]),
+    x29 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[29]),
+    x30 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[30]),
+    x31 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[31]),
+    f0 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[0]),
+    f1 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[1]),
+    f2 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[2]),
+    f3 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[3]),
+    f4 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[4]),
+    f5 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[5]),
+    f6 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[6]),
+    f7 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[7]),
+    f8 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[8]),
+    f9 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[9]),
+    f10 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[10]),
+    f11 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[11]),
+    f12 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[12]),
+    f13 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[13]),
+    f14 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[14]),
+    f15 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[15]),
+    f16 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[16]),
+    f17 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[17]),
+    f18 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[18]),
+    f19 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[19]),
+    f20 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[20]),
+    f21 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[21]),
+    f22 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[22]),
+    f23 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[23]),
+    f24 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[24]),
+    f25 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[25]),
+    f26 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[26]),
+    f27 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[27]),
+    f28 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[28]),
+    f29 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[29]),
+    f30 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[30]),
+    f31 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[31]),
+    pc = PMA_SHADOW_STATE_START + offsetof(shadow_state, pc),
+    fcsr = PMA_SHADOW_STATE_START + offsetof(shadow_state, fcsr),
+    mvendorid = PMA_SHADOW_STATE_START + offsetof(shadow_state, mvendorid),
+    marchid = PMA_SHADOW_STATE_START + offsetof(shadow_state, marchid),
+    mimpid = PMA_SHADOW_STATE_START + offsetof(shadow_state, mimpid),
+    mcycle = PMA_SHADOW_STATE_START + offsetof(shadow_state, mcycle),
+    icycleinstret = PMA_SHADOW_STATE_START + offsetof(shadow_state, icycleinstret),
+    mstatus = PMA_SHADOW_STATE_START + offsetof(shadow_state, mstatus),
+    mtvec = PMA_SHADOW_STATE_START + offsetof(shadow_state, mtvec),
+    mscratch = PMA_SHADOW_STATE_START + offsetof(shadow_state, mscratch),
+    mepc = PMA_SHADOW_STATE_START + offsetof(shadow_state, mepc),
+    mcause = PMA_SHADOW_STATE_START + offsetof(shadow_state, mcause),
+    mtval = PMA_SHADOW_STATE_START + offsetof(shadow_state, mtval),
+    misa = PMA_SHADOW_STATE_START + offsetof(shadow_state, misa),
+    mie = PMA_SHADOW_STATE_START + offsetof(shadow_state, mie),
+    mip = PMA_SHADOW_STATE_START + offsetof(shadow_state, mip),
+    medeleg = PMA_SHADOW_STATE_START + offsetof(shadow_state, medeleg),
+    mideleg = PMA_SHADOW_STATE_START + offsetof(shadow_state, mideleg),
+    mcounteren = PMA_SHADOW_STATE_START + offsetof(shadow_state, mcounteren),
+    menvcfg = PMA_SHADOW_STATE_START + offsetof(shadow_state, menvcfg),
+    stvec = PMA_SHADOW_STATE_START + offsetof(shadow_state, stvec),
+    sscratch = PMA_SHADOW_STATE_START + offsetof(shadow_state, sscratch),
+    sepc = PMA_SHADOW_STATE_START + offsetof(shadow_state, sepc),
+    scause = PMA_SHADOW_STATE_START + offsetof(shadow_state, scause),
+    stval = PMA_SHADOW_STATE_START + offsetof(shadow_state, stval),
+    satp = PMA_SHADOW_STATE_START + offsetof(shadow_state, satp),
+    scounteren = PMA_SHADOW_STATE_START + offsetof(shadow_state, scounteren),
+    senvcfg = PMA_SHADOW_STATE_START + offsetof(shadow_state, senvcfg),
+    ilrsc = PMA_SHADOW_STATE_START + offsetof(shadow_state, ilrsc),
+    iprv = PMA_SHADOW_STATE_START + offsetof(shadow_state, iprv),
+    iflags_X = PMA_SHADOW_STATE_START + offsetof(shadow_state, iflags_X),
+    iflags_Y = PMA_SHADOW_STATE_START + offsetof(shadow_state, iflags_Y),
+    iflags_H = PMA_SHADOW_STATE_START + offsetof(shadow_state, iflags_H),
+    iunrep = PMA_SHADOW_STATE_START + offsetof(shadow_state, iunrep),
+    clint_mtimecmp = PMA_SHADOW_STATE_START + offsetof(shadow_state, clint_mtimecmp),
+    plic_girqpend = PMA_SHADOW_STATE_START + offsetof(shadow_state, plic_girqpend),
+    plic_girqsrvd = PMA_SHADOW_STATE_START + offsetof(shadow_state, plic_girqsrvd),
+    htif_tohost = PMA_SHADOW_STATE_START + offsetof(shadow_state, htif_tohost),
+    htif_fromhost = PMA_SHADOW_STATE_START + offsetof(shadow_state, htif_fromhost),
+    htif_ihalt = PMA_SHADOW_STATE_START + offsetof(shadow_state, htif_ihalt),
+    htif_iconsole = PMA_SHADOW_STATE_START + offsetof(shadow_state, htif_iconsole),
+    htif_iyield = PMA_SHADOW_STATE_START + offsetof(shadow_state, htif_iyield),
+    unknown_ = UINT64_C(1) << 63, // Outside of RISC-V address space
+};
+
+static constexpr shadow_state_what shadow_state_get_what(uint64_t paddr) {
+    if (paddr < PMA_SHADOW_STATE_START || paddr - PMA_SHADOW_STATE_START >= sizeof(shadow_state) ||
+        (paddr & (sizeof(uint64_t) - 1)) != 0) {
+        return shadow_state_what::unknown_;
+    }
+    return static_cast<shadow_state_what>(paddr);
+}
+
+static constexpr const char *shadow_state_get_what_name(shadow_state_what what) {
+    const auto paddr = static_cast<uint64_t>(what);
+    if (paddr < PMA_SHADOW_STATE_START || paddr - PMA_SHADOW_STATE_START >= sizeof(shadow_state) ||
+        (paddr & (sizeof(uint64_t) - 1)) != 0) {
+        return "state.unknown";
+    }
+    using reg = shadow_state_what;
+    switch (what) {
+        case reg::x0:
+            return "x0";
+        case reg::x1:
+            return "x1";
+        case reg::x2:
+            return "x2";
+        case reg::x3:
+            return "x3";
+        case reg::x4:
+            return "x4";
+        case reg::x5:
+            return "x5";
+        case reg::x6:
+            return "x6";
+        case reg::x7:
+            return "x7";
+        case reg::x8:
+            return "x8";
+        case reg::x9:
+            return "x9";
+        case reg::x10:
+            return "x10";
+        case reg::x11:
+            return "x11";
+        case reg::x12:
+            return "x12";
+        case reg::x13:
+            return "x13";
+        case reg::x14:
+            return "x14";
+        case reg::x15:
+            return "x15";
+        case reg::x16:
+            return "x16";
+        case reg::x17:
+            return "x17";
+        case reg::x18:
+            return "x18";
+        case reg::x19:
+            return "x19";
+        case reg::x20:
+            return "x20";
+        case reg::x21:
+            return "x21";
+        case reg::x22:
+            return "x22";
+        case reg::x23:
+            return "x23";
+        case reg::x24:
+            return "x24";
+        case reg::x25:
+            return "x25";
+        case reg::x26:
+            return "x26";
+        case reg::x27:
+            return "x27";
+        case reg::x28:
+            return "x28";
+        case reg::x29:
+            return "x29";
+        case reg::x30:
+            return "x30";
+        case reg::x31:
+            return "x31";
+        case reg::f0:
+            return "f0";
+        case reg::f1:
+            return "f1";
+        case reg::f2:
+            return "f2";
+        case reg::f3:
+            return "f3";
+        case reg::f4:
+            return "f4";
+        case reg::f5:
+            return "f5";
+        case reg::f6:
+            return "f6";
+        case reg::f7:
+            return "f7";
+        case reg::f8:
+            return "f8";
+        case reg::f9:
+            return "f9";
+        case reg::f10:
+            return "f10";
+        case reg::f11:
+            return "f11";
+        case reg::f12:
+            return "f12";
+        case reg::f13:
+            return "f13";
+        case reg::f14:
+            return "f14";
+        case reg::f15:
+            return "f15";
+        case reg::f16:
+            return "f16";
+        case reg::f17:
+            return "f17";
+        case reg::f18:
+            return "f18";
+        case reg::f19:
+            return "f19";
+        case reg::f20:
+            return "f20";
+        case reg::f21:
+            return "f21";
+        case reg::f22:
+            return "f22";
+        case reg::f23:
+            return "f23";
+        case reg::f24:
+            return "f24";
+        case reg::f25:
+            return "f25";
+        case reg::f26:
+            return "f26";
+        case reg::f27:
+            return "f27";
+        case reg::f28:
+            return "f28";
+        case reg::f29:
+            return "f29";
+        case reg::f30:
+            return "f30";
+        case reg::f31:
+            return "f31";
+        case reg::pc:
+            return "pc";
+        case reg::fcsr:
+            return "fcsr";
+        case reg::mvendorid:
+            return "mvendorid";
+        case reg::marchid:
+            return "marchid";
+        case reg::mimpid:
+            return "mimpid";
+        case reg::mcycle:
+            return "mcycle";
+        case reg::icycleinstret:
+            return "icycleinstret";
+        case reg::mstatus:
+            return "mstatus";
+        case reg::mtvec:
+            return "mtvec";
+        case reg::mscratch:
+            return "mscratch";
+        case reg::mepc:
+            return "mepc";
+        case reg::mcause:
+            return "mcause";
+        case reg::mtval:
+            return "mtval";
+        case reg::misa:
+            return "misa";
+        case reg::mie:
+            return "mie";
+        case reg::mip:
+            return "mip";
+        case reg::medeleg:
+            return "medeleg";
+        case reg::mideleg:
+            return "mideleg";
+        case reg::mcounteren:
+            return "mcounteren";
+        case reg::menvcfg:
+            return "menvcfg";
+        case reg::stvec:
+            return "stvec";
+        case reg::sscratch:
+            return "sscratch";
+        case reg::sepc:
+            return "sepc";
+        case reg::scause:
+            return "scause";
+        case reg::stval:
+            return "stval";
+        case reg::satp:
+            return "satp";
+        case reg::scounteren:
+            return "scounteren";
+        case reg::senvcfg:
+            return "senvcfg";
+        case reg::ilrsc:
+            return "ilrsc";
+        case reg::iprv:
+            return "iprv";
+        case reg::iflags_X:
+            return "iflags.X";
+        case reg::iflags_Y:
+            return "iflags.Y";
+        case reg::iflags_H:
+            return "iflags.H";
+        case reg::iunrep:
+            return "iunrep";
+        case reg::clint_mtimecmp:
+            return "clint.mtimecmp";
+        case reg::plic_girqpend:
+            return "plic.girqpend";
+        case reg::plic_girqsrvd:
+            return "plic.girqsrvd";
+        case reg::htif_tohost:
+            return "htif.tohost";
+        case reg::htif_fromhost:
+            return "htif.fromhost";
+        case reg::htif_ihalt:
+            return "htif.ihalt";
+        case reg::htif_iconsole:
+            return "htif.iconsole";
+        case reg::htif_iyield:
+            return "htif.iyield";
+        case reg::unknown_:
+            [[fallthrough]];
+        default:
+            return "state.unknown";
+    }
+}
+
 /// \brief Global instance of the processor shadow device driver.
 extern const pma_driver shadow_state_driver;
 
diff --git a/src/shadow-tlb-factory.cpp b/src/shadow-tlb-factory.cpp
index c59cd2686..915cfb99d 100644
--- a/src/shadow-tlb-factory.cpp
+++ b/src/shadow-tlb-factory.cpp
@@ -14,67 +14,38 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#include "shadow-tlb-factory.h"
-
-#include <array>
-#include <cstddef>
 #include <cstdint>
-#include <cstring>
 
 #include "machine.h"
 #include "pma-constants.h"
 #include "pma.h"
+#include "shadow-peek.h"
+#include "shadow-tlb-factory.h"
 #include "shadow-tlb.h"
-#include "strict-aliasing.h"
 
 namespace cartesi {
 
 /// \brief TLB device peek callback. See ::pma_peek.
-static bool shadow_tlb_peek(const pma_entry &pma, const machine &m, uint64_t page_offset,
-    const unsigned char **page_data, unsigned char *scratch) {
-    // Check for alignment and range
-    if (page_offset % PMA_PAGE_SIZE != 0 || page_offset >= pma.get_length()) {
-        *page_data = nullptr;
-        return false;
+static bool shadow_tlb_peek(const pma_entry &pma, const machine &m, uint64_t offset, uint64_t length,
+    const unsigned char **data, unsigned char *scratch) {
+    // If past useful range
+    if (offset >= sizeof(shadow_tlb_state)) {
+        *data = nullptr;
+        return length <= pma.get_length() && offset <= pma.get_length() - length;
     }
-    // Clear page
-    memset(scratch, 0, PMA_PAGE_SIZE);
-    // Copy relevant TLB entries to the page
-    const auto &tlb = m.get_state().tlb;
-    for (uint64_t offset = 0; offset < PMA_PAGE_SIZE; offset += sizeof(uint64_t)) {
-        uint64_t val = 0;
-        if (offset < sizeof(shadow_tlb_state)) {
-            // Figure out in which set (code/read/write) the offset falls
-            const uint64_t set_index = offset / sizeof(shadow_tlb_set);
-            const uint64_t slot_offset = offset % sizeof(shadow_tlb_set);
-            // Figure out in which slot index the offset falls
-            const uint64_t slot_index = slot_offset / sizeof(shadow_tlb_slot);
-            const uint64_t field_offset = slot_offset % sizeof(shadow_tlb_slot);
-            switch (field_offset) {
-                case offsetof(shadow_tlb_slot, vaddr_page):
-                    val = tlb.hot[set_index][slot_index].vaddr_page;
-                    break;
-                case offsetof(shadow_tlb_slot, vp_offset): {
-                    auto vaddr_page = tlb.hot[set_index][slot_index].vaddr_page;
-                    auto vh_offset = tlb.hot[set_index][slot_index].vh_offset;
-                    auto haddr_page = vaddr_page + vh_offset;
-                    auto pma_index = tlb.cold[set_index][slot_index].pma_index;
-                    auto paddr_page = m.get_paddr(haddr_page, pma_index);
-                    val = paddr_page - vaddr_page;
-                    break;
-                }
-                case offsetof(shadow_tlb_slot, pma_index):
-                    val = tlb.cold[set_index][slot_index].pma_index;
-                    break;
-                default:
-                    val = 0;
-                    break;
+    // Otherwise, copy and return register data
+    return shadow_peek(
+        [](const machine &m, uint64_t paddr) {
+            TLB_set_index set_index{};
+            uint64_t slot_index{};
+            auto reg = shadow_tlb_get_what(paddr, set_index, slot_index);
+            uint64_t val = 0;
+            if (reg != shadow_tlb_what::unknown_) {
+                val = m.read_shadow_tlb(set_index, slot_index, reg);
             }
-        }
-        aliased_aligned_write<uint64_t>(scratch + offset, val);
-    }
-    *page_data = scratch;
-    return true;
+            return val;
+        },
+        pma, m, offset, length, data, scratch);
 }
 
 pma_entry make_shadow_tlb_pma_entry(uint64_t start, uint64_t length) {
@@ -84,7 +55,7 @@ pma_entry make_shadow_tlb_pma_entry(uint64_t start, uint64_t length) {
         .IR = false,
         .IW = false,
         .DID = PMA_ISTART_DID::shadow_TLB};
-    return make_device_pma_entry("shadow TLB device", start, length, shadow_tlb_peek, &shadow_tlb_driver).set_flags(f);
+    return make_device_pma_entry("shadow TLB", start, length, shadow_tlb_peek, &shadow_tlb_driver).set_flags(f);
 }
 
 } // namespace cartesi
diff --git a/src/shadow-tlb.h b/src/shadow-tlb.h
index c088aff9f..36d8f82d0 100644
--- a/src/shadow-tlb.h
+++ b/src/shadow-tlb.h
@@ -32,12 +32,21 @@
 namespace cartesi {
 
 /// \brief Shadow TLB slot
+// Writes to TLB slots have to be atomic.
+// We can only do /aligned/ atomic writes.
+// Therefore, TLB slot cannot be misaligned.
 struct PACKED shadow_tlb_slot {
-    uint64_t vaddr_page; ///< Tag is target virtual address of start of page
-    uint64_t vp_offset;  ///< Value is offset from target virtual address to target physical address within page
-    uint64_t pma_index;  ///< Index of PMA where physical page falls
+    uint64_t vaddr_page;    ///< Tag is target virtual address of start of page
+    uint64_t vp_offset;     ///< Value is offset from target virtual address to target physical address within page
+    uint64_t pma_index;     ///< Index of PMA where physical page falls
+    uint64_t zero_padding_; ///< Padding to make sure the sizeof(shadow_tlb_slot) is a power of 2
 };
 
+constexpr uint64_t SHADOW_TLB_SLOT_SIZE = sizeof(shadow_tlb_slot);
+static_assert((SHADOW_TLB_SLOT_SIZE & (SHADOW_TLB_SLOT_SIZE - 1)) == 0, "shadow TLB slot size must be power of two");
+constexpr uint64_t SHADOW_TLB_SLOT_LOG2_SIZE = 5;
+static_assert((UINT64_C(1) << SHADOW_TLB_SLOT_LOG2_SIZE) == SHADOW_TLB_SLOT_SIZE, "shadow TLB slot log2 size is wrong");
+
 /// \brief Shadow TLB set
 using shadow_tlb_set = std::array<shadow_tlb_slot, TLB_SET_SIZE>;
 
@@ -48,24 +57,60 @@ static_assert(PMA_SHADOW_TLB_LENGTH >= sizeof(shadow_tlb_state), "TLB state must
 
 extern const pma_driver shadow_tlb_driver;
 
-template <TLB_set_use USE>
-constexpr uint64_t shadow_tlb_get_slot_abs_addr(uint64_t slot_index) {
-    return PMA_SHADOW_TLB_START + USE * sizeof(shadow_tlb_set) + slot_index * sizeof(shadow_tlb_slot);
+/// \brief List of field types
+enum class shadow_tlb_what : uint64_t {
+    vaddr_page = offsetof(shadow_tlb_slot, vaddr_page),
+    vp_offset = offsetof(shadow_tlb_slot, vp_offset),
+    pma_index = offsetof(shadow_tlb_slot, pma_index),
+    zero_padding_ = offsetof(shadow_tlb_slot, zero_padding_),
+    unknown_ = UINT64_C(1) << 63, // Outside of RISC-V address space
+};
+
+static constexpr uint64_t shadow_tlb_get_abs_addr(TLB_set_index set_index, uint64_t slot_index) {
+    return PMA_SHADOW_TLB_START + set_index * sizeof(shadow_tlb_set) + slot_index * sizeof(shadow_tlb_slot);
+}
+
+static constexpr uint64_t shadow_tlb_get_abs_addr(TLB_set_index set_index, uint64_t slot_index, shadow_tlb_what what) {
+    return shadow_tlb_get_abs_addr(set_index, slot_index) + static_cast<uint64_t>(what);
 }
 
-template <TLB_set_use USE>
-constexpr uint64_t shadow_tlb_get_vaddr_page_abs_addr(uint64_t slot_index) {
-    return shadow_tlb_get_slot_abs_addr<USE>(slot_index) + offsetof(shadow_tlb_slot, vaddr_page);
+static constexpr shadow_tlb_what shadow_tlb_get_what(uint64_t paddr, TLB_set_index &set_index, uint64_t &slot_index) {
+    if (paddr < PMA_SHADOW_TLB_START || paddr - PMA_SHADOW_TLB_START >= sizeof(shadow_tlb_state) ||
+        (paddr & (sizeof(uint64_t) - 1)) != 0) {
+        return shadow_tlb_what::unknown_;
+    }
+    paddr -= PMA_SHADOW_TLB_START;
+    set_index = TLB_set_index{paddr / sizeof(shadow_tlb_set)};
+    slot_index = (paddr % sizeof(shadow_tlb_set)) / sizeof(shadow_tlb_slot);
+    return shadow_tlb_what{paddr % sizeof(shadow_tlb_slot)};
 }
 
-template <TLB_set_use USE>
-constexpr uint64_t shadow_tlb_get_vp_offset_abs_addr(uint64_t slot_index) {
-    return shadow_tlb_get_slot_abs_addr<USE>(slot_index) + offsetof(shadow_tlb_slot, vp_offset);
+static constexpr const char *shadow_tlb_get_what_name(shadow_tlb_what what) {
+    const auto offset = static_cast<uint64_t>(what);
+    using reg = shadow_tlb_what;
+    if (offset > static_cast<uint64_t>(reg::unknown_) || (offset & (sizeof(uint64_t) - 1)) != 0) {
+        return "tlb.unknown";
+    }
+    switch (what) {
+        case reg::vaddr_page:
+            return "tlb.slot.vaddr_page";
+        case reg::vp_offset:
+            return "tlb.slot.vp_offset";
+        case reg::pma_index:
+            return "tlb.slot.pma_index";
+        case reg::zero_padding_:
+            return "tlb.slot.zero_padding_";
+        case reg::unknown_:
+            return "tlb.unknown";
+    }
 }
 
-template <TLB_set_use USE>
-constexpr uint64_t shadow_tlb_get_pma_index_abs_addr(uint64_t slot_index) {
-    return shadow_tlb_get_slot_abs_addr<USE>(slot_index) + offsetof(shadow_tlb_slot, pma_index);
+[[maybe_unused]] static void shadow_tlb_fill_slot(uint64_t vaddr_page, uint64_t vp_offset, uint64_t pma_index,
+    shadow_tlb_slot &slot) {
+    slot.vaddr_page = vaddr_page;
+    slot.vp_offset = vp_offset;
+    slot.pma_index = pma_index;
+    slot.zero_padding_ = 0;
 }
 
 } // namespace cartesi
diff --git a/src/shadow-uarch-state-factory.cpp b/src/shadow-uarch-state-factory.cpp
index 376ad69ee..de98f4a6f 100644
--- a/src/shadow-uarch-state-factory.cpp
+++ b/src/shadow-uarch-state-factory.cpp
@@ -14,44 +14,36 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#include "shadow-uarch-state-factory.h"
+#include <cstdint>
 
+#include "machine.h"
 #include "pma-constants.h"
 #include "pma.h"
-#include "riscv-constants.h"
+#include "shadow-peek.h"
+#include "shadow-uarch-state-factory.h"
 #include "shadow-uarch-state.h"
-#include <cstdint>
-#include <cstring>
-
-#include "machine.h"
 
 namespace cartesi {
 
 /// \brief Shadow uarch state device peek callback. See ::pma_peek.
-static bool shadow_uarch_state_peek(const pma_entry & /*pma*/, const machine &m, uint64_t page_offset,
-    const unsigned char **page_data, unsigned char *scratch) {
-    static_assert(sizeof(shadow_uarch_state) <= PMA_PAGE_SIZE);
-
-    // There is only one page: 0
-    if (page_offset != 0) {
-        *page_data = nullptr;
-        return false;
-    }
-    // Clear page
-    memset(scratch, 0, PMA_PAGE_SIZE);
-
-    // The page will reflect the shadow uarch state structure
-    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-    auto *s = reinterpret_cast<shadow_uarch_state *>(scratch);
-
-    s->halt_flag = m.read_reg(machine_reg::uarch_halt_flag);
-    s->cycle = m.read_reg(machine_reg::uarch_cycle);
-    s->pc = m.read_reg(machine_reg::uarch_pc);
-    for (int i = 0; i < UARCH_X_REG_COUNT; ++i) {
-        s->x[i] = m.read_reg(machine_reg_enum(machine_reg::uarch_x0, i));
+static bool shadow_uarch_state_peek(const pma_entry &pma, const machine &m, uint64_t offset, uint64_t length,
+    const unsigned char **data, unsigned char *scratch) {
+    // If past useful range
+    if (offset >= sizeof(shadow_uarch_state)) {
+        *data = nullptr;
+        return length <= pma.get_length() && offset <= pma.get_length() - length;
     }
-    *page_data = scratch;
-    return true;
+    // Otherwise, copy and return register data
+    return shadow_peek(
+        [](const machine &m, uint64_t paddr) {
+            const auto reg = shadow_uarch_state_get_what(paddr);
+            uint64_t val = 0;
+            if (reg != shadow_uarch_state_what::unknown_) {
+                val = m.read_reg(machine_reg_enum(reg));
+            }
+            return val;
+        },
+        pma, m, offset, length, data, scratch);
 }
 
 pma_entry make_shadow_uarch_state_pma_entry(uint64_t start, uint64_t length) {
@@ -61,7 +53,7 @@ pma_entry make_shadow_uarch_state_pma_entry(uint64_t start, uint64_t length) {
         .IR = false,
         .IW = false,
         .DID = PMA_ISTART_DID::shadow_uarch};
-    return make_device_pma_entry("shadow uarch state device", start, length, shadow_uarch_state_peek,
+    return make_device_pma_entry("shadow uarch state", start, length, shadow_uarch_state_peek,
         &shadow_uarch_state_driver)
         .set_flags(f);
 }
diff --git a/src/shadow-uarch-state.h b/src/shadow-uarch-state.h
index 36c7ea34f..efcc72c73 100644
--- a/src/shadow-uarch-state.h
+++ b/src/shadow-uarch-state.h
@@ -38,6 +38,136 @@ struct PACKED shadow_uarch_state {
     uint64_t x[UARCH_X_REG_COUNT];
 };
 
+enum class shadow_uarch_state_what : uint64_t {
+    uarch_halt_flag = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, halt_flag),
+    uarch_cycle = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, cycle),
+    uarch_pc = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, pc),
+    uarch_x0 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[0]),
+    uarch_x1 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[1]),
+    uarch_x2 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[2]),
+    uarch_x3 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[3]),
+    uarch_x4 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[4]),
+    uarch_x5 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[5]),
+    uarch_x6 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[6]),
+    uarch_x7 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[7]),
+    uarch_x8 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[8]),
+    uarch_x9 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[9]),
+    uarch_x10 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[10]),
+    uarch_x11 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[11]),
+    uarch_x12 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[12]),
+    uarch_x13 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[13]),
+    uarch_x14 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[14]),
+    uarch_x15 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[15]),
+    uarch_x16 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[16]),
+    uarch_x17 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[17]),
+    uarch_x18 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[18]),
+    uarch_x19 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[19]),
+    uarch_x20 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[20]),
+    uarch_x21 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[21]),
+    uarch_x22 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[22]),
+    uarch_x23 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[23]),
+    uarch_x24 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[24]),
+    uarch_x25 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[25]),
+    uarch_x26 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[26]),
+    uarch_x27 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[27]),
+    uarch_x28 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[28]),
+    uarch_x29 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[29]),
+    uarch_x30 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[30]),
+    uarch_x31 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[31]),
+    unknown_ = UINT64_C(1) << 63, // Outside of RISC-V address space
+};
+
+static constexpr shadow_uarch_state_what shadow_uarch_state_get_what(uint64_t paddr) {
+    if (paddr < PMA_SHADOW_UARCH_STATE_START || paddr - PMA_SHADOW_UARCH_STATE_START >= sizeof(shadow_uarch_state) ||
+        (paddr & (sizeof(uint64_t) - 1)) != 0) {
+        return shadow_uarch_state_what::unknown_;
+    }
+    return static_cast<shadow_uarch_state_what>(paddr);
+}
+
+static constexpr const char *shadow_uarch_state_get_what_name(shadow_uarch_state_what what) {
+    const auto paddr = static_cast<uint64_t>(what);
+    if (paddr < PMA_SHADOW_UARCH_STATE_START || paddr - PMA_SHADOW_UARCH_STATE_START >= sizeof(shadow_uarch_state) ||
+        (paddr & (sizeof(uint64_t) - 1)) != 0) {
+        return "uarch.unknown";
+    }
+    using reg = shadow_uarch_state_what;
+    switch (what) {
+        case reg::uarch_halt_flag:
+            return "uarch.halt_flag";
+        case reg::uarch_cycle:
+            return "uarch.cycle";
+        case reg::uarch_pc:
+            return "uarch.pc";
+        case reg::uarch_x0:
+            return "uarch.x0";
+        case reg::uarch_x1:
+            return "uarch.x1";
+        case reg::uarch_x2:
+            return "uarch.x2";
+        case reg::uarch_x3:
+            return "uarch.x3";
+        case reg::uarch_x4:
+            return "uarch.x4";
+        case reg::uarch_x5:
+            return "uarch.x5";
+        case reg::uarch_x6:
+            return "uarch.x6";
+        case reg::uarch_x7:
+            return "uarch.x7";
+        case reg::uarch_x8:
+            return "uarch.x8";
+        case reg::uarch_x9:
+            return "uarch.x9";
+        case reg::uarch_x10:
+            return "uarch.x10";
+        case reg::uarch_x11:
+            return "uarch.x11";
+        case reg::uarch_x12:
+            return "uarch.x12";
+        case reg::uarch_x13:
+            return "uarch.x13";
+        case reg::uarch_x14:
+            return "uarch.x14";
+        case reg::uarch_x15:
+            return "uarch.x15";
+        case reg::uarch_x16:
+            return "uarch.x16";
+        case reg::uarch_x17:
+            return "uarch.x17";
+        case reg::uarch_x18:
+            return "uarch.x18";
+        case reg::uarch_x19:
+            return "uarch.x19";
+        case reg::uarch_x20:
+            return "uarch.x20";
+        case reg::uarch_x21:
+            return "uarch.x21";
+        case reg::uarch_x22:
+            return "uarch.x22";
+        case reg::uarch_x23:
+            return "uarch.x23";
+        case reg::uarch_x24:
+            return "uarch.x24";
+        case reg::uarch_x25:
+            return "uarch.x25";
+        case reg::uarch_x26:
+            return "uarch.x26";
+        case reg::uarch_x27:
+            return "uarch.x27";
+        case reg::uarch_x28:
+            return "uarch.x28";
+        case reg::uarch_x29:
+            return "uarch.x29";
+        case reg::uarch_x30:
+            return "uarch.x30";
+        case reg::uarch_x31:
+            return "uarch.x31";
+        case reg::unknown_:
+            return "uarch.unknown_";
+    }
+}
+
 /// \brief Global instance of  theprocessor shadow uarch state device driver.
 extern const pma_driver shadow_uarch_state_driver;
 
diff --git a/src/state-access.h b/src/state-access.h
index 91fc81511..5a8540bcb 100644
--- a/src/state-access.h
+++ b/src/state-access.h
@@ -41,6 +41,10 @@
 #include "shadow-tlb.h"
 #include "strict-aliasing.h"
 
+#if DUMP_STATE_ACCESS
+#include "scoped-note.h"
+#endif
+
 namespace cartesi {
 
 class state_access;
@@ -85,29 +89,28 @@ class state_access : public i_state_access<state_access> {
         return m_m.get_state();
     }
 
+#ifdef DUMP_STATE_ACCESS
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    void do_push_bracket(bracket_type /*type*/, const char * /*text*/) {}
-
-    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    int do_make_scoped_note(const char * /*text*/) {
-        return 0;
+    auto do_make_scoped_note([[maybe_unused]] const char *text) {
+        return scoped_note<state_access>{*this, text};
     }
+#endif
 
-    uint64_t do_read_x(int reg) const {
-        return m_m.get_state().x[reg];
+    uint64_t do_read_x(int i) const {
+        return m_m.get_state().x[i];
     }
 
-    void do_write_x(int reg, uint64_t val) {
-        assert(reg != 0);
-        m_m.get_state().x[reg] = val;
+    void do_write_x(int i, uint64_t val) {
+        assert(i != 0);
+        m_m.get_state().x[i] = val;
     }
 
-    uint64_t do_read_f(int reg) const {
-        return m_m.get_state().f[reg];
+    uint64_t do_read_f(int i) const {
+        return m_m.get_state().f[i];
     }
 
-    void do_write_f(int reg, uint64_t val) {
-        m_m.get_state().f[reg] = val;
+    void do_write_f(int i, uint64_t val) {
+        m_m.get_state().f[i] = val;
     }
 
     uint64_t do_read_pc() const {
@@ -475,26 +478,24 @@ class state_access : public i_state_access<state_access> {
         aliased_aligned_write<T, A>(haddr, val);
     }
 
-    template <TLB_set_use USE>
+    template <TLB_set_index SET>
     uint64_t do_read_tlb_vaddr_page(uint64_t slot_index) {
-        return m_m.get_state().tlb.hot[USE][slot_index].vaddr_page;
+        return m_m.get_state().tlb.hot[SET][slot_index].vaddr_page;
     }
 
-    template <TLB_set_use USE>
+    template <TLB_set_index SET>
     host_addr do_read_tlb_vp_offset(uint64_t slot_index) {
-        return m_m.get_state().tlb.hot[USE][slot_index].vh_offset;
+        return m_m.get_state().tlb.hot[SET][slot_index].vh_offset;
     }
 
-    template <TLB_set_use USE>
+    template <TLB_set_index SET>
     uint64_t do_read_tlb_pma_index(uint64_t slot_index) {
-        return m_m.get_state().tlb.cold[USE][slot_index].pma_index;
+        return m_m.get_state().tlb.cold[SET][slot_index].pma_index;
     }
 
-    template <TLB_set_use USE>
+    template <TLB_set_index SET>
     void do_write_tlb(uint64_t slot_index, uint64_t vaddr_page, host_addr vh_offset, uint64_t pma_index) {
-        m_m.get_state().tlb.hot[USE][slot_index].vaddr_page = vaddr_page;
-        m_m.get_state().tlb.hot[USE][slot_index].vh_offset = vh_offset;
-        m_m.get_state().tlb.cold[USE][slot_index].pma_index = pma_index;
+        m_m.write_tlb(SET, slot_index, vaddr_page, vh_offset, pma_index);
     }
 
     fast_addr do_get_faddr(uint64_t paddr, uint64_t pma_index) const {
@@ -558,6 +559,11 @@ class state_access : public i_state_access<state_access> {
         return os_getchar();
     }
 
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    constexpr const char *do_get_name() const {
+        return "state_access";
+    }
+
 #ifdef DUMP_COUNTERS
     machine_statistics &do_get_statistics() {
         return m_m.get_state().stats;
diff --git a/src/tlb.h b/src/tlb.h
index 991f67d32..ab7336bcf 100644
--- a/src/tlb.h
+++ b/src/tlb.h
@@ -32,8 +32,8 @@
 
 namespace cartesi {
 
-/// \brief TLB set mode.
-enum TLB_set_use : uint64_t { TLB_CODE, TLB_READ, TLB_WRITE, TLB_LAST_ = TLB_WRITE };
+/// \brief Index of TLB set
+enum TLB_set_index : uint64_t { TLB_CODE, TLB_READ, TLB_WRITE, TLB_LAST_ = TLB_WRITE };
 
 /// \brief TLB constants.
 enum TLB_constants : uint64_t {
diff --git a/src/uarch-bridge.h b/src/uarch-bridge.h
deleted file mode 100644
index 423a2ead2..000000000
--- a/src/uarch-bridge.h
+++ /dev/null
@@ -1,1038 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef UARCH_BRIDGE_H
-#define UARCH_BRIDGE_H
-
-#include <array>
-#include <cassert>
-#include <cstddef>
-#include <cstdint>
-#include <stdexcept>
-
-#include "machine-reg.h"
-#include "machine-state.h"
-#include "pma-constants.h"
-#include "riscv-constants.h"
-#include "shadow-pmas.h"
-#include "shadow-state.h"
-#include "shadow-tlb.h"
-#include "strict-aliasing.h"
-
-namespace cartesi {
-
-/// \brief Allows microarchitecture code to access the machine state
-class uarch_bridge {
-public:
-    /// \brief Updates the value of a machine state register.
-    /// \param s Machine state.
-    /// \param paddr Address that identifies the machine register to be written.
-    /// \param data Data to write.
-    /// \details \{
-    /// An exception is thrown if paddr can't me mapped to a valid state register.
-    //// \}
-    static void write_register(uint64_t paddr, machine_state &s, uint64_t data) {
-        using reg = machine_reg;
-        switch (static_cast<reg>(paddr)) {
-            case reg::x0:
-                s.x[0] = data;
-                return;
-            case reg::x1:
-                s.x[1] = data;
-                return;
-            case reg::x2:
-                s.x[2] = data;
-                return;
-            case reg::x3:
-                s.x[3] = data;
-                return;
-            case reg::x4:
-                s.x[4] = data;
-                return;
-            case reg::x5:
-                s.x[5] = data;
-                return;
-            case reg::x6:
-                s.x[6] = data;
-                return;
-            case reg::x7:
-                s.x[7] = data;
-                return;
-            case reg::x8:
-                s.x[8] = data;
-                return;
-            case reg::x9:
-                s.x[9] = data;
-                return;
-            case reg::x10:
-                s.x[10] = data;
-                return;
-            case reg::x11:
-                s.x[11] = data;
-                return;
-            case reg::x12:
-                s.x[12] = data;
-                return;
-            case reg::x13:
-                s.x[13] = data;
-                return;
-            case reg::x14:
-                s.x[14] = data;
-                return;
-            case reg::x15:
-                s.x[15] = data;
-                return;
-            case reg::x16:
-                s.x[16] = data;
-                return;
-            case reg::x17:
-                s.x[17] = data;
-                return;
-            case reg::x18:
-                s.x[18] = data;
-                return;
-            case reg::x19:
-                s.x[19] = data;
-                return;
-            case reg::x20:
-                s.x[20] = data;
-                return;
-            case reg::x21:
-                s.x[21] = data;
-                return;
-            case reg::x22:
-                s.x[22] = data;
-                return;
-            case reg::x23:
-                s.x[23] = data;
-                return;
-            case reg::x24:
-                s.x[24] = data;
-                return;
-            case reg::x25:
-                s.x[25] = data;
-                return;
-            case reg::x26:
-                s.x[26] = data;
-                return;
-            case reg::x27:
-                s.x[27] = data;
-                return;
-            case reg::x28:
-                s.x[28] = data;
-                return;
-            case reg::x29:
-                s.x[29] = data;
-                return;
-            case reg::x30:
-                s.x[30] = data;
-                return;
-            case reg::x31:
-                s.x[31] = data;
-                return;
-            case reg::f0:
-                s.f[0] = data;
-                return;
-            case reg::f1:
-                s.f[1] = data;
-                return;
-            case reg::f2:
-                s.f[2] = data;
-                return;
-            case reg::f3:
-                s.f[3] = data;
-                return;
-            case reg::f4:
-                s.f[4] = data;
-                return;
-            case reg::f5:
-                s.f[5] = data;
-                return;
-            case reg::f6:
-                s.f[6] = data;
-                return;
-            case reg::f7:
-                s.f[7] = data;
-                return;
-            case reg::f8:
-                s.f[8] = data;
-                return;
-            case reg::f9:
-                s.f[9] = data;
-                return;
-            case reg::f10:
-                s.f[10] = data;
-                return;
-            case reg::f11:
-                s.f[11] = data;
-                return;
-            case reg::f12:
-                s.f[12] = data;
-                return;
-            case reg::f13:
-                s.f[13] = data;
-                return;
-            case reg::f14:
-                s.f[14] = data;
-                return;
-            case reg::f15:
-                s.f[15] = data;
-                return;
-            case reg::f16:
-                s.f[16] = data;
-                return;
-            case reg::f17:
-                s.f[17] = data;
-                return;
-            case reg::f18:
-                s.f[18] = data;
-                return;
-            case reg::f19:
-                s.f[19] = data;
-                return;
-            case reg::f20:
-                s.f[20] = data;
-                return;
-            case reg::f21:
-                s.f[21] = data;
-                return;
-            case reg::f22:
-                s.f[22] = data;
-                return;
-            case reg::f23:
-                s.f[23] = data;
-                return;
-            case reg::f24:
-                s.f[24] = data;
-                return;
-            case reg::f25:
-                s.f[25] = data;
-                return;
-            case reg::f26:
-                s.f[26] = data;
-                return;
-            case reg::f27:
-                s.f[27] = data;
-                return;
-            case reg::f28:
-                s.f[28] = data;
-                return;
-            case reg::f29:
-                s.f[29] = data;
-                return;
-            case reg::f30:
-                s.f[30] = data;
-                return;
-            case reg::f31:
-                s.f[31] = data;
-                return;
-            case reg::pc:
-                s.pc = data;
-                return;
-            case reg::fcsr:
-                s.fcsr = data;
-                return;
-            case reg::mcycle:
-                s.mcycle = data;
-                return;
-            case reg::icycleinstret:
-                s.icycleinstret = data;
-                return;
-            case reg::mstatus:
-                s.mstatus = data;
-                return;
-            case reg::mtvec:
-                s.mtvec = data;
-                return;
-            case reg::mscratch:
-                s.mscratch = data;
-                return;
-            case reg::mepc:
-                s.mepc = data;
-                return;
-            case reg::mcause:
-                s.mcause = data;
-                return;
-            case reg::mtval:
-                s.mtval = data;
-                return;
-            case reg::misa:
-                s.misa = data;
-                return;
-            case reg::mie:
-                s.mie = data;
-                return;
-            case reg::mip:
-                s.mip = data;
-                return;
-            case reg::medeleg:
-                s.medeleg = data;
-                return;
-            case reg::mideleg:
-                s.mideleg = data;
-                return;
-            case reg::mcounteren:
-                s.mcounteren = data;
-                return;
-            case reg::menvcfg:
-                s.menvcfg = data;
-                return;
-            case reg::stvec:
-                s.stvec = data;
-                return;
-            case reg::sscratch:
-                s.sscratch = data;
-                return;
-            case reg::sepc:
-                s.sepc = data;
-                return;
-            case reg::scause:
-                s.scause = data;
-                return;
-            case reg::stval:
-                s.stval = data;
-                return;
-            case reg::satp:
-                s.satp = data;
-                return;
-            case reg::scounteren:
-                s.scounteren = data;
-                return;
-            case reg::senvcfg:
-                s.senvcfg = data;
-                return;
-            case reg::ilrsc:
-                s.ilrsc = data;
-                return;
-            case reg::iprv:
-                s.iprv = data;
-                return;
-            case reg::iflags_X:
-                s.iflags.X = data;
-                return;
-            case reg::iflags_Y:
-                s.iflags.Y = data;
-                return;
-            case reg::iflags_H:
-                s.iflags.H = data;
-                return;
-            case reg::clint_mtimecmp:
-                s.clint.mtimecmp = data;
-                return;
-            case reg::plic_girqpend:
-                s.plic.girqpend = data;
-                return;
-            case reg::plic_girqsrvd:
-                s.plic.girqsrvd = data;
-                return;
-            case reg::htif_tohost:
-                s.htif.tohost = data;
-                return;
-            case reg::htif_fromhost:
-                s.htif.fromhost = data;
-                return;
-            default:
-                break;
-        }
-        if (try_write_tlb(s, paddr, data)) {
-            return;
-        }
-        throw std::runtime_error("invalid write memory access from microarchitecture");
-    }
-
-    /// \brief Reads a machine state register.
-    /// \param s Machine state.
-    /// \param paddr Address that identifies the machine register to be read.
-    /// \param data Receives the state register value.
-    /// \details \{
-    /// An exception is thrown if paddr can't me mapped to a valid state register.
-    //// \}
-    static uint64_t read_register(uint64_t paddr, machine_state &s) {
-        using reg = machine_reg;
-        switch (static_cast<reg>(paddr)) {
-            case reg::x0:
-                return s.x[0];
-            case reg::x1:
-                return s.x[1];
-            case reg::x2:
-                return s.x[2];
-            case reg::x3:
-                return s.x[3];
-            case reg::x4:
-                return s.x[4];
-            case reg::x5:
-                return s.x[5];
-            case reg::x6:
-                return s.x[6];
-            case reg::x7:
-                return s.x[7];
-            case reg::x8:
-                return s.x[8];
-            case reg::x9:
-                return s.x[9];
-            case reg::x10:
-                return s.x[10];
-            case reg::x11:
-                return s.x[11];
-            case reg::x12:
-                return s.x[12];
-            case reg::x13:
-                return s.x[13];
-            case reg::x14:
-                return s.x[14];
-            case reg::x15:
-                return s.x[15];
-            case reg::x16:
-                return s.x[16];
-            case reg::x17:
-                return s.x[17];
-            case reg::x18:
-                return s.x[18];
-            case reg::x19:
-                return s.x[19];
-            case reg::x20:
-                return s.x[20];
-            case reg::x21:
-                return s.x[21];
-            case reg::x22:
-                return s.x[22];
-            case reg::x23:
-                return s.x[23];
-            case reg::x24:
-                return s.x[24];
-            case reg::x25:
-                return s.x[25];
-            case reg::x26:
-                return s.x[26];
-            case reg::x27:
-                return s.x[27];
-            case reg::x28:
-                return s.x[28];
-            case reg::x29:
-                return s.x[29];
-            case reg::x30:
-                return s.x[30];
-            case reg::x31:
-                return s.x[31];
-            case reg::f0:
-                return s.f[0];
-            case reg::f1:
-                return s.f[1];
-            case reg::f2:
-                return s.f[2];
-            case reg::f3:
-                return s.f[3];
-            case reg::f4:
-                return s.f[4];
-            case reg::f5:
-                return s.f[5];
-            case reg::f6:
-                return s.f[6];
-            case reg::f7:
-                return s.f[7];
-            case reg::f8:
-                return s.f[8];
-            case reg::f9:
-                return s.f[9];
-            case reg::f10:
-                return s.f[10];
-            case reg::f11:
-                return s.f[11];
-            case reg::f12:
-                return s.f[12];
-            case reg::f13:
-                return s.f[13];
-            case reg::f14:
-                return s.f[14];
-            case reg::f15:
-                return s.f[15];
-            case reg::f16:
-                return s.f[16];
-            case reg::f17:
-                return s.f[17];
-            case reg::f18:
-                return s.f[18];
-            case reg::f19:
-                return s.f[19];
-            case reg::f20:
-                return s.f[20];
-            case reg::f21:
-                return s.f[21];
-            case reg::f22:
-                return s.f[22];
-            case reg::f23:
-                return s.f[23];
-            case reg::f24:
-                return s.f[24];
-            case reg::f25:
-                return s.f[25];
-            case reg::f26:
-                return s.f[26];
-            case reg::f27:
-                return s.f[27];
-            case reg::f28:
-                return s.f[28];
-            case reg::f29:
-                return s.f[29];
-            case reg::f30:
-                return s.f[30];
-            case reg::f31:
-                return s.f[31];
-            case reg::pc:
-                return s.pc;
-            case reg::fcsr:
-                return s.fcsr;
-            case reg::mvendorid:
-                return MVENDORID_INIT;
-            case reg::marchid:
-                return MARCHID_INIT;
-            case reg::mimpid:
-                return MIMPID_INIT;
-            case reg::mcycle:
-                return s.mcycle;
-            case reg::icycleinstret:
-                return s.icycleinstret;
-            case reg::mstatus:
-                return s.mstatus;
-            case reg::mtvec:
-                return s.mtvec;
-            case reg::mscratch:
-                return s.mscratch;
-            case reg::mepc:
-                return s.mepc;
-            case reg::mcause:
-                return s.mcause;
-            case reg::mtval:
-                return s.mtval;
-            case reg::misa:
-                return s.misa;
-            case reg::mie:
-                return s.mie;
-            case reg::mip:
-                return s.mip;
-            case reg::medeleg:
-                return s.medeleg;
-            case reg::mideleg:
-                return s.mideleg;
-            case reg::mcounteren:
-                return s.mcounteren;
-            case reg::menvcfg:
-                return s.menvcfg;
-            case reg::stvec:
-                return s.stvec;
-            case reg::sscratch:
-                return s.sscratch;
-            case reg::sepc:
-                return s.sepc;
-            case reg::scause:
-                return s.scause;
-            case reg::stval:
-                return s.stval;
-            case reg::satp:
-                return s.satp;
-            case reg::scounteren:
-                return s.scounteren;
-            case reg::senvcfg:
-                return s.senvcfg;
-            case reg::ilrsc:
-                return s.ilrsc;
-            case reg::iprv:
-                return s.iprv;
-            case reg::iflags_X:
-                return s.iflags.X;
-            case reg::iflags_Y:
-                return s.iflags.Y;
-            case reg::iflags_H:
-                return s.iflags.H;
-            case reg::clint_mtimecmp:
-                return s.clint.mtimecmp;
-            case reg::plic_girqpend:
-                return s.plic.girqpend;
-            case reg::plic_girqsrvd:
-                return s.plic.girqsrvd;
-            case reg::htif_tohost:
-                return s.htif.tohost;
-            case reg::htif_fromhost:
-                return s.htif.fromhost;
-            case reg::htif_ihalt:
-                return s.htif.ihalt;
-            case reg::htif_iconsole:
-                return s.htif.iconsole;
-            case reg::htif_iyield:
-                return s.htif.iyield;
-            default:
-                break;
-        }
-        uint64_t data = 0;
-        if (try_read_tlb(s, paddr, &data)) {
-            return data;
-        }
-        if (try_read_pma(s, paddr, &data)) {
-            return data;
-        }
-        throw std::runtime_error("invalid read memory access from microarchitecture");
-    }
-
-    /// \brief Reads the name of a machine state register.
-    /// \param paddr Address of the state register.
-    /// \returns The register name, if paddr maps to a register, or nullptr otherwise.
-    static const char *get_register_name(uint64_t paddr) {
-        using reg = machine_reg;
-        switch (static_cast<reg>(paddr)) {
-            case reg::x0:
-                return "x0";
-            case reg::x1:
-                return "x1";
-            case reg::x2:
-                return "x2";
-            case reg::x3:
-                return "x3";
-            case reg::x4:
-                return "x4";
-            case reg::x5:
-                return "x5";
-            case reg::x6:
-                return "x6";
-            case reg::x7:
-                return "x7";
-            case reg::x8:
-                return "x8";
-            case reg::x9:
-                return "x9";
-            case reg::x10:
-                return "x10";
-            case reg::x11:
-                return "x11";
-            case reg::x12:
-                return "x12";
-            case reg::x13:
-                return "x13";
-            case reg::x14:
-                return "x14";
-            case reg::x15:
-                return "x15";
-            case reg::x16:
-                return "x16";
-            case reg::x17:
-                return "x17";
-            case reg::x18:
-                return "x18";
-            case reg::x19:
-                return "x19";
-            case reg::x20:
-                return "x20";
-            case reg::x21:
-                return "x21";
-            case reg::x22:
-                return "x22";
-            case reg::x23:
-                return "x23";
-            case reg::x24:
-                return "x24";
-            case reg::x25:
-                return "x25";
-            case reg::x26:
-                return "x26";
-            case reg::x27:
-                return "x27";
-            case reg::x28:
-                return "x28";
-            case reg::x29:
-                return "x29";
-            case reg::x30:
-                return "x30";
-            case reg::x31:
-                return "x31";
-            case reg::f0:
-                return "f0";
-            case reg::f1:
-                return "f1";
-            case reg::f2:
-                return "f2";
-            case reg::f3:
-                return "f3";
-            case reg::f4:
-                return "f4";
-            case reg::f5:
-                return "f5";
-            case reg::f6:
-                return "f6";
-            case reg::f7:
-                return "f7";
-            case reg::f8:
-                return "f8";
-            case reg::f9:
-                return "f9";
-            case reg::f10:
-                return "f10";
-            case reg::f11:
-                return "f11";
-            case reg::f12:
-                return "f12";
-            case reg::f13:
-                return "f13";
-            case reg::f14:
-                return "f14";
-            case reg::f15:
-                return "f15";
-            case reg::f16:
-                return "f16";
-            case reg::f17:
-                return "f17";
-            case reg::f18:
-                return "f18";
-            case reg::f19:
-                return "f19";
-            case reg::f20:
-                return "f20";
-            case reg::f21:
-                return "f21";
-            case reg::f22:
-                return "f22";
-            case reg::f23:
-                return "f23";
-            case reg::f24:
-                return "f24";
-            case reg::f25:
-                return "f25";
-            case reg::f26:
-                return "f26";
-            case reg::f27:
-                return "f27";
-            case reg::f28:
-                return "f28";
-            case reg::f29:
-                return "f29";
-            case reg::f30:
-                return "f30";
-            case reg::f31:
-                return "f31";
-            case reg::pc:
-                return "pc";
-            case reg::fcsr:
-                return "fcsr";
-            case reg::mvendorid:
-                return "mvendorid";
-            case reg::marchid:
-                return "marchid";
-            case reg::mimpid:
-                return "mimpid";
-            case reg::mcycle:
-                return "mcycle";
-            case reg::icycleinstret:
-                return "icycleinstret";
-            case reg::mstatus:
-                return "mstatus";
-            case reg::mtvec:
-                return "mtvec";
-            case reg::mscratch:
-                return "mscratch";
-            case reg::mepc:
-                return "mepc";
-            case reg::mcause:
-                return "mcause";
-            case reg::mtval:
-                return "mtval";
-            case reg::misa:
-                return "misa";
-            case reg::mie:
-                return "mie";
-            case reg::mip:
-                return "mip";
-            case reg::medeleg:
-                return "medeleg";
-            case reg::mideleg:
-                return "mideleg";
-            case reg::mcounteren:
-                return "mcounteren";
-            case reg::menvcfg:
-                return "menvcfg";
-            case reg::stvec:
-                return "stvec";
-            case reg::sscratch:
-                return "sscratch";
-            case reg::sepc:
-                return "sepc";
-            case reg::scause:
-                return "scause";
-            case reg::stval:
-                return "stval";
-            case reg::satp:
-                return "satp";
-            case reg::scounteren:
-                return "scounteren";
-            case reg::senvcfg:
-                return "senvcfg";
-            case reg::ilrsc:
-                return "ilrsc";
-            case reg::iprv:
-                return "iprv";
-            case reg::iflags_X:
-                return "iflags.X";
-            case reg::iflags_Y:
-                return "iflags.Y";
-            case reg::iflags_H:
-                return "iflags.H";
-            case reg::clint_mtimecmp:
-                return "clint.mtimecmp";
-            case reg::plic_girqpend:
-                return "plic.girqpend";
-            case reg::plic_girqsrvd:
-                return "plic.girqsrvd";
-            case reg::htif_tohost:
-                return "htif.tohost";
-            case reg::htif_fromhost:
-                return "htif.fromhost";
-            case reg::htif_ihalt:
-                return "htif.ihalt";
-            case reg::htif_iconsole:
-                return "htif.iconsole";
-            case reg::htif_iyield:
-                return "htif.iyield";
-            default:
-                break;
-        }
-        if (paddr >= machine_reg_address(machine_reg::x0) && paddr <= machine_reg_address(machine_reg::x31) &&
-            (paddr & 0b111) == 0) {
-            return "x";
-        }
-
-        if (paddr >= machine_reg_address(machine_reg::f0) && paddr <= machine_reg_address(machine_reg::f31) &&
-            (paddr & 0b111) == 0) {
-            return "f";
-        }
-
-        if (paddr >= shadow_pmas_get_pma_abs_addr(0) && paddr < shadow_pmas_get_pma_abs_addr(PMA_MAX)) {
-            if ((paddr & 0b1111) == 0) {
-                return "pma.istart";
-            }
-            if ((paddr & 0b1111) == 0b1000) {
-                return "pma.ilength";
-            }
-        }
-
-        if (paddr % sizeof(uint64_t) == 0) {
-            if (paddr >= shadow_tlb_get_slot_abs_addr<TLB_WRITE>(0) &&
-                paddr < shadow_tlb_get_slot_abs_addr<TLB_WRITE>(TLB_SET_SIZE)) {
-                return "write tlb";
-            }
-            if (paddr >= shadow_tlb_get_slot_abs_addr<TLB_READ>(0) &&
-                paddr < shadow_tlb_get_slot_abs_addr<TLB_READ>(TLB_SET_SIZE)) {
-                return "read tlb";
-            }
-            if (paddr >= shadow_tlb_get_slot_abs_addr<TLB_READ>(0) &&
-                paddr < shadow_tlb_get_slot_abs_addr<TLB_READ>(TLB_SET_SIZE)) {
-                return "code tlb";
-            }
-        }
-
-        return nullptr;
-    }
-
-private:
-    /// \brief Tries to read a PMA entry field.
-    /// \param s Machine state.
-    /// \param paddr Absolute address of the PMA entry field within shadow PMAs range
-    /// \param data Pointer to word receiving value.
-    /// \return true if the register was successfully read
-    static bool try_read_pma(machine_state &s, uint64_t paddr, uint64_t *data) {
-        if (paddr < PMA_SHADOW_PMAS_START || paddr >= PMA_SHADOW_PMAS_START + (PMA_MAX * PMA_WORD_SIZE * 2)) {
-            return false;
-        }
-        auto word_index = (paddr - PMA_SHADOW_PMAS_START) >> 3;
-        auto pma_index = word_index >> 1;
-        if (pma_index >= s.pmas.size()) {
-            *data = 0;
-            return true;
-        }
-        auto &pma = s.pmas[pma_index];
-        if ((word_index & 1) == 0) {
-            *data = pma.get_istart();
-        } else {
-            *data = pma.get_ilength();
-        }
-        return true;
-    }
-
-    /// \brief Tries to read a TLB entry field.
-    /// \param s Machine state.
-    /// \param paddr Absolute address of the TLB entry fieldwithin shadow TLB range
-    /// \param data Pointer to word receiving value.
-    /// \return true if the register was successfully read
-    static bool try_read_tlb(machine_state &s, uint64_t paddr, uint64_t *data) {
-        if (paddr < PMA_SHADOW_TLB_START ||
-            paddr >= PMA_SHADOW_TLB_START + PMA_SHADOW_TLB_LENGTH) { // In PMA TLB range?
-            return false;
-        }
-        if (paddr % sizeof(uint64_t) != 0) { // Misaligned field?
-            return false;
-        }
-        const uint64_t tlboff = paddr - PMA_SHADOW_TLB_START;
-        if (tlboff < offsetof(shadow_tlb_state, cold)) { // Hot entry
-            const uint64_t etype = tlboff / sizeof(std::array<tlb_hot_entry, PMA_TLB_SIZE>);
-            const uint64_t etypeoff = tlboff % sizeof(std::array<tlb_hot_entry, PMA_TLB_SIZE>);
-            const uint64_t eidx = etypeoff / sizeof(tlb_hot_entry);
-            const uint64_t fieldoff = etypeoff % sizeof(tlb_hot_entry);
-            return read_tlb_entry_field(s, true, etype, eidx, fieldoff, data);
-        }
-        if (tlboff < sizeof(shadow_tlb_state)) { // Cold entry
-            const uint64_t coldoff = tlboff - offsetof(shadow_tlb_state, cold);
-            const uint64_t etype = coldoff / sizeof(std::array<tlb_cold_entry, PMA_TLB_SIZE>);
-            const uint64_t etypeoff = coldoff % sizeof(std::array<tlb_cold_entry, PMA_TLB_SIZE>);
-            const uint64_t eidx = etypeoff / sizeof(tlb_cold_entry);
-            const uint64_t fieldoff = etypeoff % sizeof(tlb_cold_entry);
-            return read_tlb_entry_field(s, false, etype, eidx, fieldoff, data);
-        }
-        return false;
-    }
-
-    /// \brief Tries to update a PMA entry field.
-    /// \param s Machine state.
-    /// \param paddr Absolute address of the PMA entry property within shadow PMAs range
-    /// \param data Data to write
-    /// \return true if the register was successfully written
-    static bool try_write_tlb(machine_state &s, uint64_t paddr, uint64_t data) {
-        if (paddr < PMA_SHADOW_TLB_START ||
-            paddr >= PMA_SHADOW_TLB_START + PMA_SHADOW_TLB_LENGTH) { // In PMA TLB range?
-            return false;
-        }
-        if (paddr % sizeof(uint64_t) != 0) { // Misaligned field?
-            return false;
-        }
-        const uint64_t tlboff = paddr - PMA_SHADOW_TLB_START;
-        if (tlboff < offsetof(shadow_tlb_state, cold)) { // Hot entry
-            const uint64_t etype = tlboff / sizeof(std::array<tlb_hot_entry, PMA_TLB_SIZE>);
-            const uint64_t etypeoff = tlboff % sizeof(std::array<tlb_hot_entry, PMA_TLB_SIZE>);
-            const uint64_t eidx = etypeoff / sizeof(tlb_hot_entry);
-            const uint64_t fieldoff = etypeoff % sizeof(tlb_hot_entry);
-            return write_tlb_entry_field(s, true, etype, eidx, fieldoff, data);
-        }
-        if (tlboff < sizeof(shadow_tlb_state)) { // Cold entry
-            const uint64_t coldoff = tlboff - offsetof(shadow_tlb_state, cold);
-            const uint64_t etype = coldoff / sizeof(std::array<tlb_cold_entry, PMA_TLB_SIZE>);
-            const uint64_t etypeoff = coldoff % sizeof(std::array<tlb_cold_entry, PMA_TLB_SIZE>);
-            const uint64_t eidx = etypeoff / sizeof(tlb_cold_entry);
-            const uint64_t fieldoff = etypeoff % sizeof(tlb_cold_entry);
-            return write_tlb_entry_field(s, false, etype, eidx, fieldoff, data);
-        }
-        return false;
-    }
-
-    /// \brief Reads a field of a TLB entry.
-    /// \param s Machine state.
-    /// \param hot If true read from hot TLB entries, otherwise from cold TLB entries.
-    /// \param etype TLB entry type.
-    /// \param eidx TLB entry index.
-    /// \param fieldoff TLB entry field offset.
-    /// \param pval Pointer to word receiving value.
-    /// \returns True if the field was read, false otherwise.
-    static bool read_tlb_entry_field(machine_state &s, bool hot, uint64_t etype, uint64_t eidx, uint64_t fieldoff,
-        uint64_t *pval) {
-        if (etype > TLB_WRITE || eidx >= PMA_TLB_SIZE) {
-            return false;
-        }
-        const tlb_hot_entry &tlbhe = s.tlb.hot[etype][eidx];
-        const tlb_cold_entry &tlbce = s.tlb.cold[etype][eidx];
-        if (hot) {
-            if (fieldoff == offsetof(tlb_hot_entry, vaddr_page)) {
-                *pval = tlbhe.vaddr_page;
-                return true;
-            }
-            // Other fields like vh_offset contains host data, and cannot be read
-            return false;
-        }
-        // Cold
-        switch (fieldoff) {
-            case offsetof(tlb_cold_entry, paddr_page):
-                *pval = tlbce.paddr_page;
-                return true;
-            case offsetof(tlb_cold_entry, pma_index):
-                *pval = tlbce.pma_index;
-                return true;
-            default:
-                return false;
-        }
-    }
-
-    /// \brief Writes a field of a TLB entry.
-    /// \param s Machine state.
-    /// \param hot If true write to hot TLB entries, otherwise to cold TLB entries.
-    /// \param etype TLB entry type.
-    /// \param eidx TLB entry index.
-    /// \param fieldoff TLB entry field offset.
-    /// \param val Value to be written.
-    /// \returns True if the field was written, false otherwise.
-    static bool write_tlb_entry_field(machine_state &s, bool hot, uint64_t etype, uint64_t eidx, uint64_t fieldoff,
-        uint64_t val) {
-        if (etype > TLB_WRITE || eidx >= PMA_TLB_SIZE) {
-            return false;
-        }
-        tlb_hot_entry &tlbhe = s.tlb.hot[etype][eidx];
-        tlb_cold_entry &tlbce = s.tlb.cold[etype][eidx];
-        if (hot) {
-            if (fieldoff == offsetof(tlb_hot_entry, vaddr_page)) {
-                tlbhe.vaddr_page = val;
-                // Update vh_offset
-                if (val != TLB_INVALID_PAGE) {
-                    const pma_entry &pma = find_pma_entry<uint64_t>(s, tlbce.paddr_page);
-                    assert(pma.get_istart_M()); // TLB only works for memory mapped PMAs
-                    const unsigned char *hpage =
-                        pma.get_memory().get_host_memory() + (tlbce.paddr_page - pma.get_start());
-                    tlbhe.vh_offset = cast_ptr_to_addr<uint64_t>(hpage) - tlbhe.vaddr_page;
-                }
-                return true;
-            }
-            // Other fields like vh_offset contains host data, and cannot be written
-            return false;
-        }
-        // Cold
-        switch (fieldoff) {
-            case offsetof(tlb_cold_entry, paddr_page):
-                tlbce.paddr_page = val;
-                return true;
-            case offsetof(tlb_cold_entry, pma_index):
-                tlbce.pma_index = val;
-                return true;
-            default:
-                return false;
-        }
-    }
-
-    /// \brief Obtain PMA entry that covers a given physical memory region
-    /// \tparam T Type of word.
-    /// \param s Mmachine state.
-    /// \param paddr Start of physical memory region.
-    /// \returns Corresponding entry if found, or a sentinel entry
-    /// for an empty range.
-    template <typename T>
-    static const pma_entry &find_pma_entry(machine_state &s, uint64_t paddr) {
-        for (const auto &pma : s.pmas) {
-            // Stop at first empty PMA
-            if (pma.get_length() == 0) {
-                return pma;
-            }
-            if (pma.contains(paddr, sizeof(T))) {
-                return pma;
-            }
-        }
-        // Last PMA is always the empty range
-        return s.pmas.back();
-    }
-};
-
-} // namespace cartesi
-
-#endif
diff --git a/src/uarch-config.h b/src/uarch-config.h
index 42333e059..6e1e29871 100644
--- a/src/uarch-config.h
+++ b/src/uarch-config.h
@@ -35,7 +35,7 @@ struct uarch_processor_config final {
     std::array<uint64_t, UARCH_X_REG_COUNT> x{}; ///< Value of general-purpose registers
     uint64_t pc{UARCH_PC_INIT};                  ///< Value of pc
     uint64_t cycle{UARCH_CYCLE_INIT};            ///< Value of ucycle counter
-    bool halt_flag{};
+    uint64_t halt_flag{};
 };
 
 /// \brief Microarchitecture configuration
diff --git a/src/uarch-constants.h b/src/uarch-constants.h
index 34a597cab..da52db2e2 100644
--- a/src/uarch-constants.h
+++ b/src/uarch-constants.h
@@ -64,8 +64,10 @@ static_assert((UARCH_RAM_LENGTH & (PMA_PAGE_SIZE - 1)) == 0, "UARCH_RAM_LENGTH m
 
 /// \brief ecall function codes
 enum uarch_ecall_functions : uint64_t {
-    UARCH_ECALL_FN_HALT = EXPAND_UINT64_C(UARCH_ECALL_FN_HALT_DEF),       ///< halt  uarch execution
-    UARCH_ECALL_FN_PUTCHAR = EXPAND_UINT64_C(UARCH_ECALL_FN_PUTCHAR_DEF), //< putchar
+    UARCH_ECALL_FN_HALT = EXPAND_UINT64_C(UARCH_ECALL_FN_HALT_DEF),                       ///< halt uarch execution
+    UARCH_ECALL_FN_PUTCHAR = EXPAND_UINT64_C(UARCH_ECALL_FN_PUTCHAR_DEF),                 ///< putchar
+    UARCH_ECALL_FN_MARK_DIRTY_PAGE = EXPAND_UINT64_C(UARCH_ECALL_FN_MARK_DIRTY_PAGE_DEF), ///< mark_dirty_page
+    UARCH_ECALL_FN_WRITE_TLB = EXPAND_UINT64_C(UARCH_ECALL_FN_WRITE_TLB_DEF),             ///< write_tlb
 };
 
 } // namespace cartesi
diff --git a/src/uarch-defines.h b/src/uarch-defines.h
index 855bfbbba..c5d3abb8b 100644
--- a/src/uarch-defines.h
+++ b/src/uarch-defines.h
@@ -26,8 +26,10 @@
 #define UARCH_STATE_LOG2_SIZE_DEF 22
 
 // microarchitecture ecall function codes
-#define UARCH_ECALL_FN_HALT_DEF 1    // halt uarch
-#define UARCH_ECALL_FN_PUTCHAR_DEF 2 // putchar
+#define UARCH_ECALL_FN_HALT_DEF 1            // halt uarch
+#define UARCH_ECALL_FN_PUTCHAR_DEF 2         // putchar
+#define UARCH_ECALL_FN_MARK_DIRTY_PAGE_DEF 3 // mark_dirty_page
+#define UARCH_ECALL_FN_WRITE_TLB_DEF 4       // write_tlb
 
 // NOLINTEND(cppcoreguidelines-macro-usage,cppcoreguidelines-macro-to-enum,modernize-macro-to-enum)
 #endif /* end of include guard: UARCH_DEFINES_H */
diff --git a/src/uarch-interpret.h b/src/uarch-interpret.h
index 00c676529..295822394 100644
--- a/src/uarch-interpret.h
+++ b/src/uarch-interpret.h
@@ -19,10 +19,11 @@
 
 #include <cstdint>
 
-#include "uarch-state-access.h"
-
 namespace cartesi {
 
+// Forward declaration
+class uarch_state_access;
+
 enum class uarch_interpreter_break_reason : int { reached_target_cycle, uarch_halted };
 
 // Run the microarchitecture interpreter until cycle hits a target or a fixed point is reached
diff --git a/src/uarch-machine-bridge.cpp b/src/uarch-machine-bridge.cpp
new file mode 100644
index 000000000..4583230b0
--- /dev/null
+++ b/src/uarch-machine-bridge.cpp
@@ -0,0 +1,170 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#include <ios>
+#include <sstream>
+
+#include "machine.h"
+#include "riscv-constants.h"
+#include "shadow-pmas.h"
+#include "shadow-state.h"
+#include "shadow-tlb.h"
+#include "strict-aliasing.h"
+#include "uarch-machine-bridge.h"
+
+namespace cartesi {
+
+const char *uarch_machine_bridge::get_what_name(uint64_t paddr) {
+    if (paddr >= PMA_UARCH_RAM_START && paddr - PMA_UARCH_RAM_START < PMA_UARCH_RAM_LENGTH) {
+        return "uarch.ram";
+    }
+    // If in shadow, return refined name
+    if (paddr >= PMA_SHADOW_TLB_START && paddr - PMA_SHADOW_TLB_START < PMA_SHADOW_TLB_LENGTH) {
+        [[maybe_unused]] TLB_set_index set_index{};
+        [[maybe_unused]] uint64_t slot_index{};
+        return shadow_tlb_get_what_name(shadow_tlb_get_what(paddr, set_index, slot_index));
+    }
+    if (paddr >= PMA_SHADOW_STATE_START && paddr - PMA_SHADOW_STATE_START < PMA_SHADOW_STATE_LENGTH) {
+        return shadow_state_get_what_name(shadow_state_get_what(paddr));
+    }
+    if (paddr >= PMA_SHADOW_PMAS_START && paddr - PMA_SHADOW_PMAS_START < PMA_SHADOW_PMAS_LENGTH) {
+        return shadow_pmas_get_what_name(shadow_pmas_get_what(paddr));
+    }
+    if (paddr >= PMA_SHADOW_UARCH_STATE_START && paddr - PMA_SHADOW_UARCH_STATE_START < PMA_SHADOW_UARCH_STATE_LENGTH) {
+        return shadow_uarch_state_get_what_name(shadow_uarch_state_get_what(paddr));
+    }
+    return "memory";
+}
+
+void uarch_machine_bridge::write_word(uint64_t paddr, uint64_t val) {
+    if ((paddr & (sizeof(uint64_t) - 1)) != 0) {
+        throw std::runtime_error("misaligned write via uarch-machine bridge");
+    }
+    if (paddr >= PMA_UARCH_RAM_START && paddr - PMA_UARCH_RAM_START < PMA_UARCH_RAM_LENGTH) {
+        write_uarch_memory_word(paddr, val);
+        return;
+    }
+    if (paddr >= PMA_SHADOW_STATE_START && paddr - PMA_SHADOW_STATE_START < PMA_SHADOW_STATE_LENGTH) {
+        write_shadow_state(paddr, val);
+        return;
+    }
+    write_memory_word(paddr, val);
+}
+
+uint64_t uarch_machine_bridge::read_word(uint64_t paddr) const {
+    if ((paddr & (sizeof(uint64_t) - 1)) != 0) {
+        throw std::runtime_error("misaligned read via uarch-machine bridge");
+    }
+    if (paddr >= PMA_UARCH_RAM_START && paddr - PMA_UARCH_RAM_START < PMA_UARCH_RAM_LENGTH) {
+        return read_uarch_memory_word(paddr);
+    }
+    if (paddr >= PMA_SHADOW_STATE_START && paddr - PMA_SHADOW_STATE_START < PMA_SHADOW_STATE_LENGTH) {
+        return read_shadow_state(paddr);
+    }
+    if (paddr >= PMA_SHADOW_TLB_START && paddr - PMA_SHADOW_TLB_START < PMA_SHADOW_TLB_LENGTH) {
+        return read_shadow_tlb(paddr);
+    }
+    return read_memory_word(paddr);
+}
+
+uint64_t uarch_machine_bridge::read_memory_word(uint64_t paddr) const {
+    const auto &pma = m_m.find_pma_entry(paddr, sizeof(uint64_t));
+    if (pma.get_istart_E() || !pma.get_istart_M()) {
+        std::ostringstream err;
+        err << "unhandled memory read from " << pma.get_description() << " at address 0x" << std::hex << paddr << "("
+            << std::dec << paddr << ")";
+    }
+    if (!pma.get_istart_R()) {
+        std::ostringstream err;
+        err << "attempted memory read from (non-readable) " << pma.get_description() << " at address 0x" << std::hex
+            << paddr << "(" << std::dec << paddr << ")";
+        throw std::runtime_error{err.str()};
+    }
+    const auto offset = paddr - pma.get_start();
+    return aliased_aligned_read<uint64_t>(pma.get_memory().get_host_memory() + offset);
+}
+
+uint64_t uarch_machine_bridge::read_uarch_memory_word(uint64_t paddr) const {
+    const auto &pma = m_m.get_uarch_state().ram;
+    const auto offset = paddr - pma.get_start();
+    return aliased_aligned_read<uint64_t>(pma.get_memory().get_host_memory() + offset);
+}
+
+void uarch_machine_bridge::write_uarch_memory_word(uint64_t paddr, uint64_t val) {
+    auto &pma = m_m.get_uarch_state().ram;
+    const auto offset = paddr - pma.get_start();
+    aliased_aligned_write<uint64_t>(pma.get_memory().get_host_memory() + offset, val);
+}
+
+uint64_t uarch_machine_bridge::read_shadow_state(uint64_t paddr) const {
+    auto reg = shadow_state_get_what(paddr);
+    if (reg == shadow_state_what::unknown_) {
+        throw std::runtime_error("unhandled shadow state read via uarch-machine bridge");
+    }
+    return m_m.read_reg(machine_reg_enum(reg));
+}
+
+uint64_t uarch_machine_bridge::read_shadow_tlb(uint64_t paddr) const {
+    TLB_set_index set_index{};
+    uint64_t slot_index{};
+    auto reg = shadow_tlb_get_what(paddr, set_index, slot_index);
+    if (reg == shadow_tlb_what::unknown_) {
+        throw std::runtime_error("unhandled shadow TLB read via uarch-machine bridge");
+    }
+    return m_m.read_shadow_tlb(set_index, slot_index, reg);
+}
+
+void uarch_machine_bridge::write_shadow_state(uint64_t paddr, uint64_t val) {
+    auto reg = shadow_state_get_what(paddr);
+    if (reg == shadow_state_what::unknown_) {
+        throw std::runtime_error("unhandled shadow state write via uarch-machine bridge");
+    }
+    if (reg == shadow_state_what::x0) {
+        throw std::runtime_error("invalid write to shadow state x0 via uarch-machine bridge");
+    }
+    m_m.write_reg(machine_reg_enum(reg), val);
+}
+
+void uarch_machine_bridge::mark_dirty_page(uint64_t paddr, uint64_t pma_index) {
+    m_m.mark_dirty_page(paddr, pma_index);
+}
+
+void uarch_machine_bridge::write_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page,
+    uint64_t vp_offset, uint64_t pma_index) {
+    m_m.check_shadow_tlb(set_index, slot_index, vaddr_page, vp_offset, pma_index,
+        "invalid write to shadow TLB via uarch-machine bridge: ");
+    m_m.write_shadow_tlb(set_index, slot_index, vaddr_page, vp_offset, pma_index);
+}
+
+void uarch_machine_bridge::write_memory_word(uint64_t paddr, uint64_t val) {
+    auto &pma = m_m.find_pma_entry(paddr, sizeof(uint64_t));
+    if (pma.get_istart_E() || !pma.get_istart_M()) {
+        std::ostringstream err;
+        err << "unhandled memory write to " << pma.get_description() << " at address 0x" << std::hex << paddr << "("
+            << std::dec << paddr << ")";
+        throw std::runtime_error{err.str()};
+    }
+    if (!pma.get_istart_W()) {
+        std::ostringstream err;
+        err << "attempted memory write to (non-writeable) " << pma.get_description() << " at address 0x" << std::hex
+            << paddr << "(" << std::dec << paddr << ")";
+        throw std::runtime_error{err.str()};
+    }
+    const auto offset = paddr - pma.get_start();
+    aliased_aligned_write<uint64_t>(pma.get_memory().get_host_memory() + offset, val);
+}
+
+} // namespace cartesi
diff --git a/src/uarch-machine-bridge.h b/src/uarch-machine-bridge.h
new file mode 100644
index 000000000..0525f0d45
--- /dev/null
+++ b/src/uarch-machine-bridge.h
@@ -0,0 +1,57 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef UARCH_MACHINE_BRIDGE_H
+#define UARCH_MACHINE_BRIDGE_H
+
+#include <cstddef>
+#include <cstdint>
+
+#include "tlb.h"
+
+namespace cartesi {
+
+class machine;
+
+/// \brief Allows microarchitecture code to access the machine state
+class uarch_machine_bridge {
+
+    machine &m_m; // NOLINT(cppcoreguidelines-avoid-const-or-ref-data-members)
+
+public:
+    explicit uarch_machine_bridge(machine &m) : m_m(m) {
+        ;
+    }
+    uint64_t read_word(uint64_t paddr) const;
+    void write_word(uint64_t paddr, uint64_t val);
+    void mark_dirty_page(uint64_t paddr, uint64_t pma_index);
+    void write_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset,
+        uint64_t pma_index);
+    static const char *get_what_name(uint64_t paddr);
+
+private:
+    void write_shadow_state(uint64_t paddr, uint64_t val);
+    void write_memory_word(uint64_t paddr, uint64_t val);
+    void write_uarch_memory_word(uint64_t paddr, uint64_t val);
+    uint64_t read_shadow_state(uint64_t paddr) const;
+    uint64_t read_memory_word(uint64_t paddr) const;
+    uint64_t read_uarch_memory_word(uint64_t paddr) const;
+    uint64_t read_shadow_tlb(uint64_t paddr) const;
+};
+
+} // namespace cartesi
+
+#endif
diff --git a/src/uarch-machine.cpp b/src/uarch-machine.cpp
deleted file mode 100644
index dbff4c580..000000000
--- a/src/uarch-machine.cpp
+++ /dev/null
@@ -1,83 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#include "uarch-machine.h"
-
-#include <cstdint>
-#include <cstring>
-#include <stdexcept>
-#include <utility>
-
-#include "pma-constants.h"
-#include "pma.h"
-#include "riscv-constants.h"
-#include "shadow-uarch-state-factory.h"
-#include "uarch-config.h"
-#include "uarch-constants.h"
-#include "uarch-pristine.h"
-
-namespace cartesi {
-
-using namespace std::string_literals;
-
-const pma_entry::flags ram_flags{.R = true,
-    .W = true,
-    .X = true,
-    .IR = true,
-    .IW = true,
-    .DID = PMA_ISTART_DID::memory};
-
-uarch_machine::uarch_machine(uarch_config c) : m_c{c} {
-    m_s.pc = c.processor.pc;
-    m_s.cycle = c.processor.cycle;
-    m_s.halt_flag = c.processor.halt_flag;
-    // General purpose registers
-    for (int i = 1; i < UARCH_X_REG_COUNT; i++) {
-        m_s.x[i] = c.processor.x[i];
-    }
-    // Register shadow state
-    m_s.shadow_state = make_shadow_uarch_state_pma_entry(PMA_SHADOW_UARCH_STATE_START, PMA_SHADOW_UARCH_STATE_LENGTH);
-    // Register RAM
-    constexpr auto ram_description = "uarch RAM";
-    if (!c.ram.image_filename.empty()) {
-        // Load RAM image from file
-        m_s.ram =
-            make_callocd_memory_pma_entry(ram_description, PMA_UARCH_RAM_START, UARCH_RAM_LENGTH, c.ram.image_filename)
-                .set_flags(ram_flags);
-    } else {
-        // Load embedded pristine RAM image
-        m_s.ram = make_callocd_memory_pma_entry(ram_description, PMA_UARCH_RAM_START, PMA_UARCH_RAM_LENGTH)
-                      .set_flags(ram_flags);
-        if (uarch_pristine_ram_len > m_s.ram.get_length()) {
-            throw std::runtime_error("embedded uarch ram image does not fit in uarch ram pma");
-        }
-        memcpy(m_s.ram.get_memory().get_host_memory(), uarch_pristine_ram, uarch_pristine_ram_len);
-    }
-}
-
-pma_entry &uarch_machine::find_pma_entry(uint64_t paddr, uint64_t length) {
-    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-const-cast): remove const to reuse code
-    return const_cast<pma_entry &>(std::as_const(*this).find_pma_entry(paddr, length));
-}
-
-const pma_entry &uarch_machine::find_pma_entry(uint64_t paddr, uint64_t length) const {
-    if (m_s.ram.contains(paddr, length)) {
-        return m_s.ram;
-    }
-    return m_s.empty_pma;
-}
-
-} // namespace cartesi
diff --git a/src/uarch-machine.h b/src/uarch-machine.h
deleted file mode 100644
index 33e2a7f34..000000000
--- a/src/uarch-machine.h
+++ /dev/null
@@ -1,83 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef UARCH_MACHINE_H
-#define UARCH_MACHINE_H
-
-/// \file
-/// \brief Cartesi microarchitecture machine
-#include <cstdint>
-
-#include "pma.h"
-#include "uarch-config.h"
-#include "uarch-state.h"
-
-namespace cartesi {
-
-/// \class uarch_machine
-/// \brief Cartesi Machine Microarchitecture implementation
-class uarch_machine final {
-    uarch_state m_s;  ///< Opaque microarchitecture machine state
-    uarch_config m_c; ///< Copy of initialization config
-
-public:
-    /// \brief Constructor from machine configuration
-    // I will deal with clang-tidy later.
-    explicit uarch_machine(uarch_config c);
-    /// \brief Destructor.
-    ~uarch_machine() = default;
-
-    /// \brief No default constructor
-    uarch_machine() = delete;
-    /// \brief No copy constructor
-    uarch_machine(const uarch_machine &other) = delete;
-    /// \brief No move constructor
-    uarch_machine(uarch_machine &&other) = delete;
-    /// \brief No copy assignment
-    uarch_machine &operator=(const uarch_machine &other) = delete;
-    /// \brief No move assignment
-    uarch_machine &operator=(uarch_machine &&other) = delete;
-
-    /// \brief Returns machine state for direct access.
-    uarch_state &get_state() {
-        return m_s;
-    }
-
-    /// \brief Returns machine state for direct read-only access.
-    const uarch_state &get_state() const {
-        return m_s;
-    }
-
-    /// \brief Obtain PMA entry that covers a given physical memory region
-    /// \param s Pointer to machine state.
-    /// \param paddr Start of physical memory region.
-    /// \param length Length of physical memory region.
-    /// \returns Corresponding entry if found, or a sentinel entry
-    /// for an empty range.
-    pma_entry &find_pma_entry(uint64_t paddr, uint64_t length);
-
-    /// \brief Obtain PMA entry that covers a given physical memory region
-    const pma_entry &find_pma_entry(uint64_t paddr, uint64_t length) const;
-
-    /// \brief Returns copy of initialization config.
-    const uarch_config &get_initial_config() const {
-        return m_c;
-    }
-};
-
-} // namespace cartesi
-
-#endif
diff --git a/src/uarch-record-state-access.h b/src/uarch-record-state-access.h
index f73c313f2..7a8176650 100644
--- a/src/uarch-record-state-access.h
+++ b/src/uarch-record-state-access.h
@@ -28,66 +28,46 @@
 #include <utility>
 
 #include "access-log.h"
+#include "host-addr.h"
 #include "i-hasher.h"
 #include "i-state-access.h"
 #include "i-uarch-state-access.h"
 #include "machine-merkle-tree.h"
-#include "machine-state.h"
 #include "machine.h"
 #include "meta.h"
 #include "pma.h"
 #include "riscv-constants.h"
+#include "scoped-note.h"
+#include "shadow-tlb.h"
 #include "shadow-uarch-state.h"
 #include "strict-aliasing.h"
-#include "uarch-bridge.h"
 #include "uarch-constants.h"
+#include "uarch-machine-bridge.h"
 #include "uarch-pristine-state-hash.h"
 #include "uarch-pristine.h"
 #include "uarch-state.h"
 
 namespace cartesi {
 
+using namespace std::string_literals;
+
 /// \details The uarch_record_state_access logs all access to the machine state.
 class uarch_record_state_access : public i_uarch_state_access<uarch_record_state_access> {
+
     using hasher_type = machine_merkle_tree::hasher_type;
     using hash_type = machine_merkle_tree::hash_type;
 
     // NOLINTBEGIN(cppcoreguidelines-avoid-const-or-ref-data-members)
     uarch_state &m_us;
     machine &m_m; ///< Macro machine
-    machine_state &m_s;
+    uarch_machine_bridge m_b;
     // NOLINTEND(cppcoreguidelines-avoid-const-or-ref-data-members)
     std::shared_ptr<access_log> m_log; ///< Pointer to access log
 
-    /// \brief Obtain Memory PMA entry that covers a given physical memory region
-    /// \param paddr Start of physical memory region.
-    /// \param length Length of physical memory region.
-    /// \returns Corresponding entry if found, or a sentinel entry
-    /// for an empty range.
-    pma_entry &find_memory_pma_entry(uint64_t paddr, uint64_t length) {
-        // First, search microarchitecture's private PMA entries
-        if (m_us.ram.contains(paddr, length)) {
-            return m_us.ram;
-        }
-        int i = 0;
-        // Search machine memory PMA entries (not devices or anything else)
-        while (true) {
-            auto &pma = m_s.pmas[i];
-            // The pmas array always contain a sentinel. It is an entry with
-            // zero length. If we hit it, return it
-            if (pma.get_length() == 0) {
-                return pma;
-            }
-            if (pma.get_istart_M() && pma.contains(paddr, length)) {
-                return pma;
-            }
-            i++;
-        }
-    }
-
-    static void get_hash(const access_data &data, hash_type &hash) {
-        hasher_type hasher;
+    static auto get_hash(hasher_type &hasher, const access_data &data) {
+        hash_type hash{};
         get_merkle_tree_hash(hasher, data.data(), data.size(), machine_merkle_tree::get_word_size(), hash);
+        return hash;
     }
 
 public:
@@ -97,7 +77,7 @@ class uarch_record_state_access : public i_uarch_state_access<uarch_record_state
     explicit uarch_record_state_access(uarch_state &us, machine &m, access_log::type log_type) :
         m_us(us),
         m_m(m),
-        m_s(m.get_state()),
+        m_b(m),
         m_log(std::make_shared<access_log>(log_type)) {
         ;
     }
@@ -123,356 +103,253 @@ class uarch_record_state_access : public i_uarch_state_access<uarch_record_state
         return m_log;
     }
 
-    /// \brief Adds annotations to the state, bracketing a scope
-    class scoped_note {
-        std::shared_ptr<access_log> m_log; ///< Pointer to log receiving annotations
-        std::string m_text;                ///< String with the text for the annotation
-
-    public:
-        /// \brief Constructor adds the "begin" bracketing note
-        /// \param log Pointer to access log receiving annotations
-        /// \param text Pointer to annotation text
-        /// \details A note is added at the moment of construction
-        scoped_note(std::shared_ptr<access_log> log, const char *text) : m_log(std::move(log)), m_text(text) {
-            if (m_log) {
-                m_log->push_bracket(bracket_type::begin, text);
-            }
-        }
+private:
+    void do_push_begin_bracket(const char *text) {
+        m_log->push_begin_bracket(text);
+    }
 
-        /// \brief No copy constructors
-        scoped_note(const scoped_note &) = delete;
-
-        /// \brief No copy assignment
-        scoped_note &operator=(const scoped_note &) = delete;
-
-        /// \brief Default move constructor
-        /// \details This is OK because the shared_ptr to log will be
-        /// empty afterwards and we explicitly test for this
-        /// condition before writing the "end" bracketing note
-        scoped_note(scoped_note &&) = default;
-
-        /// \brief Default move assignment
-        /// \details This is OK because the shared_ptr to log will be
-        /// empty afterwards and we explicitly test for this
-        /// condition before writing the "end" bracketing note
-        scoped_note &operator=(scoped_note &&) = default;
-
-        /// \brief Destructor adds the "end" bracketing note
-        /// if the log shared_ptr is not empty
-        ~scoped_note() {
-            if (m_log) {
-                try {
-                    m_log->push_bracket(bracket_type::end, m_text.c_str());
-                } catch (...) { // NOLINT(bugprone-empty-catch)
-                    // push_bracket with type begin always reserves space for the end bracket
-                    // so either the user using unbalanced with begin/end, or there
-                    // is no way we ran out of memory. therefore, if we did run out of
-                    // memory, it was because the system is completely screwed anyway *and* the
-                    // user is using unbalanced brackets. it's ok to quietly ignore, as the user's
-                    // brackets were already unbalanced anyway...
-                }
-            }
-        }
-    };
+    void do_push_end_bracket(const char *text) {
+        m_log->push_end_bracket(text);
+    }
 
-private:
-    /// \brief Logs a read access of a uint64_t word from the machine state.
-    /// \param paligned Physical address in the machine state, aligned to a 64-bit word.
-    /// \param val Value read.
-    /// \param text Textual description of the access.
-    uint64_t log_read(uint64_t paligned, uint64_t val, const char *text) const {
-        static_assert(machine_merkle_tree::get_log2_word_size() >= log2_size<uint64_t>::value,
-            "Merkle tree word size must be at least as large as a machine word");
-        if ((paligned & (sizeof(uint64_t) - 1)) != 0) {
-            throw std::invalid_argument{"paligned is not aligned to word size"};
+    auto do_make_scoped_note(const char *text) {
+        return scoped_note<uarch_record_state_access>{*this, text};
+    }
+
+    static std::pair<uint64_t, int> adjust_access(uint64_t paddr, int log2_size) {
+        static_assert(cartesi::log2_size<uint64_t>::value <= machine_merkle_tree::get_log2_word_size(),
+            "Merkle tree word size must not be smaller than machine word size");
+        if (((paddr >> log2_size) << log2_size) != paddr) {
+            throw std::invalid_argument{"misaligned access"};
         }
-        const uint64_t pleaf_aligned = paligned & ~(machine_merkle_tree::get_word_size() - 1);
-        access a;
+        const auto log2_word_size = machine_merkle_tree::get_log2_word_size();
+        const auto log2_access_size = std::max(log2_size, log2_word_size);
+        const auto access_paddr = (paddr >> log2_access_size) << log2_access_size;
+        return {access_paddr, log2_access_size};
+    }
+
+    void log_access(access &&a, const char *text) const {
+        m_log->push_access(std::move(a), text);
+    }
 
-        // We can skip updating the merkle tree while getting the proof because we assume that:
-        // 1) A full merkle tree update was called at the beginning of machine::log_step_uarch()
-        // 2) We called update_merkle_tree_page on all write accesses
-        const auto proof =
-            m_m.get_proof(pleaf_aligned, machine_merkle_tree::get_log2_word_size(), skip_merkle_tree_update);
-        // We just store the sibling hashes in the access because this is the only missing piece of data needed to
-        // reconstruct the proof
+    static void log_access_type(access &a, access_type type) {
+        a.set_type(type);
+    }
+
+    static void log_access_range(access &a, uint64_t paddr, int log2_size) {
+        a.set_address(paddr);
+        a.set_log2_size(log2_size);
+    }
+
+    void log_access_siblings_and_read_hash(access &a, uint64_t paddr, int log2_size) const {
+        // Since the tree was updated before we started collecting the log, we only update after writes
+        const auto proof = m_m.get_proof(paddr, log2_size, skip_merkle_tree_update);
+        // The only pieces of data we use from the proof are the target hash and the siblings
         a.set_sibling_hashes(proof.get_sibling_hashes());
+        a.set_read_hash(proof.get_target_hash());
+    }
+
+    static void log_written_hash(access &a, const hash_type &written_hash) {
+        a.get_written_hash().emplace(written_hash);
+    }
 
-        a.set_type(access_type::read);
-        a.set_address(paligned);
-        a.set_log2_size(log2_size<uint64_t>::value);
+    const auto &log_read_data(access &a, uint64_t paddr, int log2_size) const {
         // NOLINTBEGIN(bugprone-unchecked-optional-access)
-        // we log the leaf data at pleaf_aligned that contains the word at paligned
+        const auto size = UINT64_C(1) << log2_size;
         a.get_read().emplace();
-        a.get_read().value().resize(machine_merkle_tree::get_word_size());
-        // read the entire leaf where the word is located
-        m_m.read_memory(pleaf_aligned, a.get_read().value().data(), machine_merkle_tree::get_word_size());
-        get_hash(a.get_read().value(), a.get_read_hash());
-        // ensure that the read data is the same as the value read
-        const int word_offset = static_cast<int>(paligned - pleaf_aligned); // offset of word in leaf
-        const uint64_t logged_val = get_word_access_data(a.get_read().value(), word_offset);
-        if (val != logged_val) {
-            throw std::runtime_error("read value does not match logged value");
-        }
+        a.get_read().value().resize(size);
+        m_m.read_memory(paddr, a.get_read().value().data(), size);
+        return a.get_read().value();
         // NOLINTEND(bugprone-unchecked-optional-access)
-        m_log->push_access(std::move(a), text);
-        return val;
     }
 
-    /// \brief Logs a write access to a uint64_t word before it happens.
-    /// \param paligned Physical address of the word in the machine state (Must be aligned to a 64-bit word).
-    /// \param val Value to write.
-    /// \param text Textual description of the access.
-    void log_before_write(uint64_t paligned, uint64_t word, const char *text) {
-        static_assert(machine_merkle_tree::get_log2_word_size() >= log2_size<uint64_t>::value,
-            "Merkle tree word size must be at least as large as a machine word");
-        if ((paligned & (sizeof(uint64_t) - 1)) != 0) {
-            throw std::invalid_argument{"paligned is not aligned to word size"};
+    void log_read_data_if_requested(access &a, uint64_t paddr, int log2_size) const {
+        if (m_log->get_log_type().has_large_data()) {
+            std::ignore = log_read_data(a, paddr, log2_size);
         }
-        const uint64_t pleaf_aligned = paligned & ~(machine_merkle_tree::get_word_size() - 1);
-        access a;
-
-        // We can skip updating the merkle tree while getting the proof because we assume that:
-        // 1) A full merkle tree update was called at the beginning of machine::log_step_uarch()
-        // 2) We called update_merkle_tree_page on all write accesses
-        const auto proof =
-            m_m.get_proof(pleaf_aligned, machine_merkle_tree::get_log2_word_size(), skip_merkle_tree_update);
-        // We just store the sibling hashes in the access because this is the only missing piece of data needed to
-        // reconstruct the proof
-        a.set_sibling_hashes(proof.get_sibling_hashes());
+    }
 
-        a.set_type(access_type::write);
-        a.set_address(paligned);
-        a.set_log2_size(log2_size<uint64_t>::value);
+    void log_written_data(access &a, uint64_t paddr, int log2_size) const {
         // NOLINTBEGIN(bugprone-unchecked-optional-access)
-        // we log the leaf data at pleaf_aligned that contains the word at paligned
-        a.get_read().emplace();
-        a.get_read().value().resize(machine_merkle_tree::get_word_size());
-        m_m.read_memory(pleaf_aligned, a.get_read().value().data(), machine_merkle_tree::get_word_size());
-        get_hash(a.get_read().value(), a.get_read_hash());
-        // the logged written data is the same as the read data, but with the word at paligned replaced by word
-        a.set_written(access_data(a.get_read().value()));                     // copy the read data
-        const int word_offset = static_cast<int>(paligned - pleaf_aligned);   // offset of word in leaf
-        replace_word_access_data(word, a.get_written().value(), word_offset); // replace the word
-        // compute the hash of the written data
-        a.get_written_hash().emplace();
-        get_hash(a.get_written().value(), a.get_written_hash().value());
+        const auto size = UINT64_C(1) << log2_size;
+        a.get_written().emplace();
+        a.get_written().value().resize(size);
+        m_m.read_memory(paddr, a.get_written().value().data(), size);
         // NOLINTEND(bugprone-unchecked-optional-access)
-        m_log->push_access(std::move(a), text);
     }
 
-    /// \brief Updates the Merkle tree after the modification of a word in the machine state.
-    /// \param paligned Physical address in the machine state, aligned to a 64-bit word.
-    void update_after_write(uint64_t paligned) {
-        assert((paligned & (sizeof(uint64_t) - 1)) == 0);
-        [[maybe_unused]] const bool updated = m_m.update_merkle_tree_page(paligned);
-        assert(updated);
+    void log_written_data_if_requested(access &a, uint64_t paddr, int log2_size) const {
+        if (m_log->get_log_type().has_large_data()) {
+            log_written_data(a, paddr, log2_size);
+        }
     }
 
-    /// \brief Logs a write access before it happens, writes, and then update the Merkle tree.
-    /// \param paligned Physical address of the word in the machine state (Must be aligned to a 64-bit word).
-    /// \param dest Reference to value before writing.
-    /// \param val Value to write to \p dest.
-    /// \param text Textual description of the access.
-    void log_before_write_write_and_update(uint64_t paligned, uint64_t &dest, uint64_t word, const char *text) {
-        assert((paligned & (sizeof(uint64_t) - 1)) == 0);
-        log_before_write(paligned, word, text);
-        dest = word;
-        update_after_write(paligned);
+    uint64_t log_read_word_access(uint64_t paddr, const char *text) const {
+        const auto log2_size = cartesi::log2_size<uint64_t>::value;
+        access a;
+        log_access_type(a, access_type::read);
+        log_access_range(a, paddr, log2_size);
+        const auto [access_paddr, access_log2_size] = adjust_access(paddr, log2_size);
+        log_access_siblings_and_read_hash(a, access_paddr, access_log2_size);
+        const auto &read_data = log_read_data(a, access_paddr, access_log2_size);
+        const auto val_offset = paddr - access_paddr;
+        const auto val = get_word_access_data(read_data, val_offset);
+        log_access(std::move(a), text);
+        return val;
     }
 
-    void log_before_write_write_and_update(uint64_t paligned, bool &dest, bool val, const char *text) {
-        auto dest64 = static_cast<uint64_t>(dest);
-        log_before_write_write_and_update(paligned, dest64, static_cast<uint64_t>(val), text);
-        dest = (dest64 != 0);
-        update_after_write(paligned);
+    uint64_t log_read_reg_access(machine_reg reg) const {
+        return log_read_word_access(machine_reg_address(reg), machine_reg_get_name(reg));
     }
 
-    // Declare interface as friend to it can forward calls to the "overridden" methods.
-    friend i_uarch_state_access<uarch_record_state_access>;
-
-    void do_push_bracket(bracket_type &type, const char *text) {
-        m_log->push_bracket(type, text);
+    template <typename WRITE_UPDATE_F>
+    void log_write_access(uint64_t paddr, int log2_size, WRITE_UPDATE_F write_and_update, const char *text) {
+        access a;
+        log_access_type(a, access_type::write);
+        log_access_range(a, paddr, log2_size);
+        const auto [access_paddr, access_log2_size] = adjust_access(paddr, log2_size);
+        log_access_siblings_and_read_hash(a, access_paddr, access_log2_size);
+        // We *need* the read data for small writes, because we splice the written into it
+        if (log2_size < machine_merkle_tree::get_log2_word_size()) {
+            std::ignore = log_read_data(a, access_paddr, access_log2_size);
+        } else {
+            log_read_data_if_requested(a, access_paddr, access_log2_size);
+        }
+        // Call functor to perform the write and update the tree
+        write_and_update();
+        // The functor updated the tree, so we don't do it again
+        log_written_hash(a, m_m.get_merkle_tree_node_hash(access_paddr, access_log2_size, skip_merkle_tree_update));
+        // We don't *need* the written for small writes, but it is convenient to always have it (for debugging purposes)
+        if (log2_size < machine_merkle_tree::get_log2_word_size()) {
+            log_written_data(a, access_paddr, access_log2_size);
+        } else {
+            log_written_data_if_requested(a, access_paddr, access_log2_size);
+        }
+        log_access(std::move(a), text);
     }
 
-    scoped_note do_make_scoped_note(const char *text) {
-        return scoped_note{m_log, text};
+    void log_write_reg_access(machine_reg reg, uint64_t val) {
+        log_write_access(
+            machine_reg_address(reg), cartesi::log2_size<uint64_t>::value,
+            [this, reg, val]() {
+                m_m.write_reg(reg, val);
+                if (!m_m.update_merkle_tree_page(machine_reg_address(reg))) {
+                    throw std::invalid_argument{"error updating Merkle tree"};
+                };
+            },
+            machine_reg_get_name(reg));
     }
 
-    uint64_t do_read_x(int reg) const {
-        return log_read(machine_reg_address(machine_reg::uarch_x0, reg), m_us.x[reg], "uarch.x");
+    // Declare interface as friend to it can forward calls to the "overridden" methods.
+    friend i_uarch_state_access<uarch_record_state_access>;
+
+    uint64_t do_read_x(int i) const {
+        return log_read_reg_access(machine_reg_enum(machine_reg::uarch_x0, i));
     }
 
-    void do_write_x(int reg, uint64_t val) {
-        assert(reg != 0);
-        log_before_write_write_and_update(machine_reg_address(machine_reg::uarch_x0, reg), m_us.x[reg], val, "uarch.x");
+    void do_write_x(int i, uint64_t val) {
+        assert(i != 0);
+        log_write_reg_access(machine_reg_enum(machine_reg::uarch_x0, i), val);
     }
 
     uint64_t do_read_pc() const {
-        return log_read(machine_reg_address(machine_reg::uarch_pc), m_us.pc, "uarch.pc");
+        return log_read_reg_access(machine_reg::uarch_pc);
     }
 
     void do_write_pc(uint64_t val) {
-        log_before_write_write_and_update(machine_reg_address(machine_reg::uarch_pc), m_us.pc, val, "uarch.pc");
+        log_write_reg_access(machine_reg::uarch_pc, val);
     }
 
     uint64_t do_read_cycle() const {
-        return log_read(machine_reg_address(machine_reg::uarch_cycle), m_us.cycle, "uarch.cycle");
+        return log_read_reg_access(machine_reg::uarch_cycle);
     }
 
     void do_write_cycle(uint64_t val) {
-        log_before_write_write_and_update(machine_reg_address(machine_reg::uarch_cycle), m_us.cycle, val,
-            "uarch.cycle");
-    }
-
-    bool do_read_halt_flag() const {
-        return log_read(machine_reg_address(machine_reg::uarch_halt_flag), static_cast<uint64_t>(m_us.halt_flag),
-                   "uarch.halt_flag") != 0;
+        log_write_reg_access(machine_reg::uarch_cycle, val);
     }
 
-    void do_set_halt_flag() {
-        log_before_write_write_and_update(machine_reg_address(machine_reg::uarch_halt_flag), m_us.halt_flag, true,
-            "uarch.halt_flag");
+    uint64_t do_read_halt_flag() const {
+        return log_read_reg_access(machine_reg::uarch_halt_flag);
     }
 
-    void do_reset_halt_flag() {
-        log_before_write_write_and_update(machine_reg_address(machine_reg::uarch_halt_flag), m_us.halt_flag, false,
-            "uarch.halt_flag");
+    void do_write_halt_flag(uint64_t val) {
+        log_write_reg_access(machine_reg::uarch_halt_flag, val);
     }
 
-    uint64_t do_read_word(uint64_t paddr) {
-        assert((paddr & (sizeof(uint64_t) - 1)) == 0);
-        // Find a memory range that contains the specified address
-        auto &pma = find_memory_pma_entry(paddr, sizeof(uint64_t));
-        if (pma.get_istart_E()) {
-            // Memory not found. Try reading a machine state register
-            return read_register(paddr);
-        }
-        if (!pma.get_istart_R()) {
-            throw std::runtime_error("pma is not readable");
+    uint64_t do_read_word(uint64_t paddr) const {
+        if ((paddr & (sizeof(uint64_t) - 1)) != 0) {
+            throw std::runtime_error("misaligned read from uarch");
         }
-        // Found a readable memory range. Access host memory accordingly.
-        const uint64_t hoffset = paddr - pma.get_start();
-        auto *hmem = pma.get_memory().get_host_memory();
-        auto data = aliased_aligned_read<uint64_t>(hmem + hoffset);
-        log_read(paddr, data, "memory");
-        return data;
-    }
-
-    /// \brief Reads a uint64 machine state register mapped to a memory address
-    /// \param paddr Address of the state register
-    /// \param data Pointer receiving register value
-    uint64_t read_register(uint64_t paddr) {
-        auto data = uarch_bridge::read_register(paddr, m_s);
-        const auto *name = uarch_bridge::get_register_name(paddr);
-        log_read(paddr, data, name);
-        return data;
-    }
-
-    void do_write_word(uint64_t paddr, uint64_t data) {
-        assert((paddr & (sizeof(uint64_t) - 1)) == 0);
-        // Find a memory range that contains the specified address
-        auto &pma = find_memory_pma_entry(paddr, sizeof(uint64_t));
-        if (pma.get_istart_E()) {
-            // Memory not found. Try to write a machine state register
-            write_register(paddr, data);
-            return;
-        }
-        if (!pma.get_istart_W()) {
-            throw std::runtime_error("pma is not writable");
-        }
-        // Found a writable memory range. Access host memory accordingly.
-
-        // The proof in the log uses the Merkle tree before the state is modified.
-        // But log needs the word value before and after the change.
-        // So we first get value before the write
-        const uint64_t hoffset = paddr - pma.get_start();
-        unsigned char *hmem = pma.get_memory().get_host_memory();
-        void *hdata = hmem + hoffset;
-        // Log the write access
-        log_before_write(paddr, data, "memory");
-        // Actually modify the state
-        aliased_aligned_write<uint64_t>(hdata, data);
-
-        // When proofs are requested, we always want to update the Merkle tree
-        update_after_write(paddr);
+        return log_read_word_access(paddr, uarch_machine_bridge::get_what_name(paddr));
     }
 
-    /// \brief Writes a uint64 machine state register mapped to a memory address
-    /// \param paddr Address of the state register
-    /// \param data New register value
-    void write_register(uint64_t paddr, uint64_t data) {
-        const auto *name = uarch_bridge::get_register_name(paddr);
-        log_before_write(paddr, data, name);
-        uarch_bridge::write_register(paddr, m_s, data);
-        update_after_write(paddr);
+    void do_write_word(uint64_t paddr, uint64_t val) {
+        if ((paddr & (sizeof(uint64_t) - 1)) != 0) {
+            throw std::runtime_error("misaligned write to uarch");
+        }
+        log_write_access(
+            paddr, cartesi::log2_size<uint64_t>::value,
+            [this, paddr, val]() {
+                m_b.write_word(paddr, val);
+                if (!m_m.update_merkle_tree_page(paddr)) {
+                    throw std::invalid_argument{"error updating Merkle tree"};
+                };
+            },
+            uarch_machine_bridge::get_what_name(paddr));
     }
 
-    /// \brief Fallback to error on all other word sizes
-    template <typename T>
-    void write_register(uint64_t /*paddr*/, T /*data*/) {
-        throw std::runtime_error("invalid memory write access from microarchitecture");
+    void do_write_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset,
+        uint64_t pma_index) {
+        const auto slot_paddr = shadow_tlb_get_abs_addr(set_index, slot_index);
+        log_write_access(
+            slot_paddr, SHADOW_TLB_SLOT_LOG2_SIZE,
+            [this, set_index, slot_index, vaddr_page, vp_offset, pma_index]() {
+                m_b.write_shadow_tlb(set_index, slot_index, vaddr_page, vp_offset, pma_index);
+                // Entire slot is in a single page
+                if (!m_m.update_merkle_tree_page(shadow_tlb_get_abs_addr(set_index, slot_index))) {
+                    throw std::invalid_argument{"error updating Merkle tree"};
+                };
+            },
+            "tlb.slot");
+        // Writes to TLB slots have to be atomic.
+        // We can only do atomic writes of entire Merkle tree nodes.
+        // Therefore, TLB slot must have a power-of-two size, or at least be aligned to it.
+        static_assert(SHADOW_TLB_SLOT_SIZE == sizeof(shadow_tlb_slot), "shadow TLB slot size is wrong");
+        static_assert((UINT64_C(1) << SHADOW_TLB_SLOT_LOG2_SIZE) == SHADOW_TLB_SLOT_SIZE,
+            "shadow TLB slot log2 size is wrong");
+        static_assert(SHADOW_TLB_SLOT_LOG2_SIZE >= machine_merkle_tree::get_log2_word_size(),
+            "shadow TLB slot must fill at least an entire Merkle tree word");
     }
 
     void do_reset_state() {
-        // The pristine uarch state decided at compile time and never changes.
-        // We set all uarch registers and RAM to their initial values and
-        // log a single write access to the entire uarch memory range.
-        // This write access does not contain any data, just hashes, unless log_type.large_data is enabled.
-        access a;
-        a.set_type(access_type::write);
-        a.set_address(UARCH_STATE_START_ADDRESS);
-        a.set_log2_size(UARCH_STATE_LOG2_SIZE);
-
-        // Always compute the proof, even if we are not logging it, because:
-        // (1) we always need to compute read_hash.
-        // (2) Depending on the log type, we may also need to compute the proof.
-        // (3) proof.target_hash is the  value that we  need for a.read_hash in (1).
-        auto proof = m_m.get_proof(UARCH_STATE_START_ADDRESS, UARCH_STATE_LOG2_SIZE);
-        a.set_read_hash(proof.get_target_hash());
-        if (m_log->get_log_type().has_large_data()) {
-            // log read data, if debug info is enabled
-            a.get_read().emplace(get_uarch_state_image());
-        }
+        //??D I'd like to add an static_assert or some other guard mechanism to
+        // guarantee that uarch.ram and uarch.shadow are alone in the entire
+        // span of their common Merkle tree parent node
+        log_write_access(
+            UARCH_STATE_START_ADDRESS, UARCH_STATE_LOG2_SIZE,
+            [this]() {
+                m_m.reset_uarch();
+                // reset_uarch() marks all modified pages as dirty
+                if (!m_m.update_merkle_tree()) {
+                    throw std::invalid_argument{"error updating Merkle tree"};
+                }
+            },
+            "uarch.state");
+    }
 
-        // We just store the sibling hashes in the access because this is the only missing piece of data needed to
-        // reconstruct the proof
-        a.set_sibling_hashes(proof.get_sibling_hashes());
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    void do_putchar(uint8_t c) {
+        os_putchar(c);
+    }
 
-        a.set_written_hash(get_uarch_pristine_state_hash());
+    void do_mark_dirty_page(uint64_t paddr, uint64_t pma_index) {
+        // forward to bridge, and no need to log
+        m_b.mark_dirty_page(paddr, pma_index);
+    }
 
-        // Restore uarch to pristine state
-        m_us.halt_flag = false;
-        m_us.pc = UARCH_PC_INIT;
-        m_us.cycle = UARCH_CYCLE_INIT;
-        for (int i = 1; i < UARCH_X_REG_COUNT; i++) {
-            m_us.x[i] = UARCH_X_INIT;
-        }
-        m_us.ram.write_memory(m_us.ram.get_start(), uarch_pristine_ram, uarch_pristine_ram_len);
-        m_us.ram.fill_memory(m_us.ram.get_start() + uarch_pristine_ram_len, 0,
-            m_us.ram.get_length() - uarch_pristine_ram_len);
-        if (m_log->get_log_type().has_large_data()) {
-            // log written data, if debug info is enabled
-            a.get_written().emplace(get_uarch_state_image());
-        }
-        m_log->push_access(a, "uarch_state");
-    }
-
-    /// \brief Returns the image of the entire uarch state
-    /// \return access_data containing the image of the current uarch state
-    access_data get_uarch_state_image() {
-        constexpr int uarch_data_len = uint64_t{1} << UARCH_STATE_LOG2_SIZE;
-        access_data data(uarch_data_len, 0);
-        constexpr auto ram_offset = UARCH_RAM_START_ADDRESS - UARCH_STATE_START_ADDRESS;
-        // copy shadow state data
-        const unsigned char *page_data = nullptr;
-        auto peek = m_us.shadow_state.get_peek();
-        if (!peek(m_us.shadow_state, m_m, 0, &page_data, data.data())) {
-            throw std::runtime_error{"peek failed"};
-        }
-        // copy ram data
-        memcpy(data.data() + ram_offset, m_us.ram.get_memory().get_host_memory(), m_us.ram.get_length());
-        return data;
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    constexpr const char *do_get_name() const {
+        return "uarch_record_state_access";
     }
 };
 
diff --git a/src/uarch-replay-state-access.h b/src/uarch-replay-state-access.h
index 437ff40c1..3f2d3e35c 100644
--- a/src/uarch-replay-state-access.h
+++ b/src/uarch-replay-state-access.h
@@ -34,8 +34,8 @@
 #include "i-uarch-state-access.h"
 #include "machine-merkle-tree.h"
 #include "meta.h"
+#include "shadow-tlb.h"
 #include "shadow-uarch-state.h"
-#include "uarch-bridge.h"
 #include "uarch-constants.h"
 #include "uarch-pristine-state-hash.h"
 
@@ -64,9 +64,7 @@ class uarch_replay_state_access : public i_uarch_state_access<uarch_replay_state
     explicit uarch_replay_state_access(const access_log &log, const hash_type &initial_hash) :
         m_accesses(log.get_accesses()),
         m_root_hash{initial_hash} {
-        if (m_accesses.empty()) {
-            throw std::invalid_argument{"the access log has no accesses"};
-        }
+        ;
     }
 
     /// \brief No copy constructor
@@ -91,168 +89,193 @@ class uarch_replay_state_access : public i_uarch_state_access<uarch_replay_state
     }
 
 private:
+    static auto get_hash(hasher_type &hasher, const access_data &data) {
+        hash_type hash{};
+        get_merkle_tree_hash(hasher, data.data(), data.size(), machine_merkle_tree::get_word_size(), hash);
+        return hash;
+    }
+
     std::string access_to_report() const {
         auto index = m_next_access + 1;
-        switch (index) {
+        auto digit = index % 10;
+        const char *suffix = nullptr;
+        switch (digit) {
             case 1:
-                return "1st access";
+                suffix = "st";
+                break;
             case 2:
-                return "2nd access";
+                suffix = "nd";
+                break;
             case 3:
-                return "3rd access";
+                suffix = "rd";
+                break;
             default:
-                return std::to_string(index) + "th access";
+                suffix = "th";
+                break;
         }
+        return std::to_string(index) + suffix + " access";
     }
 
-    static void get_hash(hasher_type &hasher, const access_data &data, hash_type &hash) {
-        get_merkle_tree_hash(hasher, data.data(), data.size(), machine_merkle_tree::get_word_size(), hash);
+    static constexpr const char *access_type_name(access_type type) {
+        switch (type) {
+            case access_type::read:
+                return "read";
+            case access_type::write:
+                return "write";
+        }
     }
 
-    /// \brief Checks a logged word read and advances log.
-    /// \param paligned Physical address in the machine state,
-    /// aligned to 64-bits.
-    /// \param text Textual description of the access.
-    /// \returns Value read.
-    uint64_t check_read(uint64_t paligned, const char *text) {
-        static_assert(machine_merkle_tree::get_log2_word_size() >= log2_size<uint64_t>::value,
-            "Merkle tree word size must be at least as large as a machine word");
-        if ((paligned & (sizeof(uint64_t) - 1)) != 0) {
-            throw std::invalid_argument{"address not aligned to word size"};
-        }
+    static std::pair<uint64_t, int> adjust_access(uint64_t paddr, int log2_size) {
+        static_assert(cartesi::log2_size<uint64_t>::value <= machine_merkle_tree::get_log2_word_size(),
+            "Merkle tree word size must not be smaller than machine word size");
+        const auto log2_word_size = machine_merkle_tree::get_log2_word_size();
+        const auto log2_access_size = std::max(log2_size, log2_word_size);
+        const auto access_paddr = (paddr >> log2_access_size) << log2_access_size;
+        return {access_paddr, log2_access_size};
+    }
+
+    const access &check_access(const char *text) {
         if (m_next_access >= m_accesses.size()) {
-            throw std::invalid_argument{"too few accesses in log"};
+            throw std::invalid_argument{"log is missing access " + access_to_report() + " to " + text};
+        }
+        return m_accesses[m_next_access];
+    }
+
+    void check_access_type(const access &a, access_type type, const char *text) {
+        if (a.get_type() != type) {
+            throw std::invalid_argument{
+                "expected " + access_to_report() + " to " + access_type_name(type) + " " + text};
         }
-        const auto &access = m_accesses[m_next_access];
-        if (access.get_type() != access_type::read) {
-            throw std::invalid_argument{"expected " + access_to_report() + " to read " + text};
+        if (type == access_type::read) {
+            if (a.get_written().has_value()) {
+                throw std::invalid_argument{
+                    "unexpected written data in " + access_to_report() + " read access to " + text};
+            }
+            if (a.get_written_hash().has_value()) {
+                throw std::invalid_argument{
+                    "unexpected written hash in " + access_to_report() + " read access to " + text};
+            }
         }
-        if (access.get_address() != paligned) {
+    }
+
+    void check_access_range(const access &a, access_type type, uint64_t paddr, uint64_t log2_size, const char *text) {
+        if (a.get_address() != paddr) {
             std::ostringstream err;
-            err << "expected " << access_to_report() << " to read " << text << " address 0x" << std::hex << paligned
-                << "(" << std::dec << paligned << ")";
+            err << "expected " << access_to_report() << " to " << access_type_name(type) << " " << text
+                << " at address 0x" << std::hex << paddr << "(" << std::dec << paddr << ")";
             throw std::invalid_argument{err.str()};
         }
-        if (access.get_log2_size() != log2_size<uint64_t>::value) {
-            throw std::invalid_argument{"expected " + access_to_report() + " to read 2^" +
-                std::to_string(machine_merkle_tree::get_log2_word_size()) + " bytes from " + text};
-        }
-        if (!access.get_read().has_value()) {
-            throw std::invalid_argument{"missing read " + std::string(text) + " data at " + access_to_report()};
+        if (a.get_log2_size() != static_cast<int>(log2_size)) {
+            throw std::invalid_argument{"expected " + access_to_report() + " to " + text + " to " +
+                access_type_name(type) + " 2^" + std::to_string(log2_size) + " bytes"};
         }
-        // NOLINTBEGIN(bugprone-unchecked-optional-access)
-        const auto &read_data = access.get_read().value();
-        if (read_data.size() != machine_merkle_tree::get_word_size()) {
-            throw std::invalid_argument{"expected read " + std::string(text) + " data to contain 2^" +
-                std::to_string(machine_merkle_tree::get_log2_word_size()) + " bytes at " + access_to_report()};
-        }
-        // check if logged read data hashes to the logged read hash
-        hash_type computed_read_hash{};
-        get_hash(m_hasher, read_data, computed_read_hash);
-        if (access.get_read_hash() != computed_read_hash) {
-            throw std::invalid_argument{"logged read data of " + std::string(text) +
-                " data does not hash to the logged read hash at " + access_to_report()};
-        }
-        auto proof = access.make_proof(m_root_hash);
+    }
+
+    auto check_access_siblings_and_read_hash(const access &a, const char *text) {
+        const auto proof = a.make_proof(m_root_hash);
         if (!proof.verify(m_hasher)) {
-            throw std::invalid_argument{"Mismatch in root hash of " + access_to_report()};
+            throw std::invalid_argument{
+                "siblings and read hash do not match root hash before " + access_to_report() + " to " + text};
         }
-        m_next_access++;
-        const uint64_t pleaf_aligned = paligned & ~(machine_merkle_tree::get_word_size() - 1);
-        const int word_offset = static_cast<int>(paligned - pleaf_aligned);
-        return get_word_access_data(read_data, word_offset);
-        // NOLINTEND(bugprone-unchecked-optional-access)
+        return proof;
     }
 
-    /// \brief Checks a logged word write and advances log.
-    /// \param paligned Physical address in the machine state,
-    /// aligned to a 64-bit word.
-    /// \param word Word value to write.
-    /// \param text Textual description of the access.
-    void check_write(uint64_t paligned, uint64_t word, const char *text) {
-        static_assert(machine_merkle_tree::get_log2_word_size() >= log2_size<uint64_t>::value,
-            "Merkle tree word size must be at least as large as a machine word");
-        if ((paligned & (sizeof(uint64_t) - 1)) != 0) {
-            throw std::invalid_argument{"paligned not aligned to word size"};
-        }
-        if (m_next_access >= m_accesses.size()) {
-            throw std::invalid_argument{"too few accesses in log"};
-        }
-        const auto &access = m_accesses[m_next_access];
-        if (access.get_type() != access_type::write) {
-            throw std::invalid_argument{"expected " + access_to_report() + " to write " + text};
-        }
-        if (access.get_address() != paligned) {
-            std::ostringstream err;
-            err << "expected " << access_to_report() << " to write " << text << " to address 0x" << std::hex << paligned
-                << "(" << std::dec << paligned << ")";
-            throw std::invalid_argument{err.str()};
-        }
-        if (access.get_log2_size() != log2_size<uint64_t>::value) {
-            throw std::invalid_argument{"expected " + access_to_report() + " to write 2^" +
-                std::to_string(machine_merkle_tree::get_log2_word_size()) + " bytes to " + text};
+    const auto &check_written_hash(const access &a, const hash_type &expected_hash, const char *text) {
+        if (!a.get_written_hash().has_value()) {
+            throw std::invalid_argument{"missing written hash of " + std::string(text) + " in " + access_to_report()};
         }
         // NOLINTBEGIN(bugprone-unchecked-optional-access)
-        // check read
-        if (!access.get_read().has_value()) {
-            throw std::invalid_argument{"missing read " + std::string(text) + " data at " + access_to_report()};
-        }
-        const auto &read_data = access.get_read().value();
-        if (read_data.size() != machine_merkle_tree::get_word_size()) {
-            throw std::invalid_argument{"expected overwritten data from " + std::string(text) + " to contain 2^" +
-                std::to_string(access.get_log2_size()) + " bytes at " + access_to_report()};
-        }
-        // check if read data hashes to the logged read hash
-        hash_type computed_read_hash{};
-        get_hash(m_hasher, read_data, computed_read_hash);
-        if (access.get_read_hash() != computed_read_hash) {
-            throw std::invalid_argument{"logged read data of " + std::string(text) +
-                " does not hash to the logged read hash at " + access_to_report()};
+        if (a.get_written_hash().value() != expected_hash) {
+            throw std::invalid_argument{
+                "written hash for " + std::string(text) + " does not match expected hash in " + access_to_report()};
         }
-        // check write
-        if (!access.get_written_hash().has_value()) {
-            throw std::invalid_argument{"missing written " + std::string(text) + " hash at " + access_to_report()};
+        return a.get_written_hash().value();
+        // NOLINTEND(bugprone-unchecked-optional-access)
+    }
+
+    const auto &check_read_data(const access &a, const char *text) {
+        if (!a.get_read().has_value()) {
+            throw std::invalid_argument{"missing read data for " + std::string(text) + " in " + access_to_report()};
         }
-        const auto &written_hash = access.get_written_hash().value();
-        if (!access.get_written().has_value()) {
-            throw std::invalid_argument{"missing written " + std::string(text) + " data at " + access_to_report()};
+        // check if logged read data hashes to the logged read hash
+        // NOLINTBEGIN(bugprone-unchecked-optional-access)
+        const auto computed_read_hash = get_hash(m_hasher, a.get_read().value());
+        if (a.get_read_hash() != computed_read_hash) {
+            throw std::invalid_argument{
+                "read data for " + std::string(text) + " does not match read hash in " + access_to_report()};
         }
-        const auto &written_data = access.get_written().value();
-        if (written_data.size() != read_data.size()) {
-            throw std::invalid_argument{"expected written " + std::string(text) + " data to contain 2^" +
-                std::to_string(access.get_log2_size()) + " bytes at " + access_to_report()};
+        return a.get_read().value();
+        // NOLINTEND(bugprone-unchecked-optional-access)
+    }
+
+    void check_written_data_if_there(const access &a, const hash_type &written_hash, const char *text) {
+        if (!a.get_written().has_value()) {
+            return;
         }
-        // check if written data hashes to the logged written hash
-        hash_type computed_written_hash{};
-        get_hash(m_hasher, written_data, computed_written_hash);
-        if (written_hash != computed_written_hash) {
-            throw std::invalid_argument{"logged written data of " + std::string(text) +
-                " does not hash to the logged written hash at " + access_to_report()};
+        // NOLINTBEGIN(bugprone-unchecked-optional-access)
+        if (written_hash != get_hash(m_hasher, a.get_written().value())) {
+            throw std::invalid_argument{
+                "written data for " + std::string(text) + " does not match written hash in " + access_to_report()};
         }
-        // check if word being written matches the logged data
-        const uint64_t pleaf_aligned = paligned & ~(machine_merkle_tree::get_word_size() - 1);
-        const int word_offset = static_cast<int>(paligned - pleaf_aligned);
-        const uint64_t logged_word = get_word_access_data(written_data, word_offset);
-        if (word != logged_word) {
-            throw std::invalid_argument{"value being written to " + std::string(text) +
-                " does not match the logged written value at " + access_to_report()};
+        // NOLINTEND(bugprone-unchecked-optional-access)
+    }
+
+    void check_read_data_if_there(const access &a, const char *text) {
+        if (!a.get_read().has_value()) {
+            return;
         }
-        // check if logged written data differs from the logged read data only by the written word
-        access_data expected_written_data(read_data);                       // make a copy of read data
-        replace_word_access_data(word, expected_written_data, word_offset); // patch with written word
-        if (written_data != expected_written_data) {
-            throw std::invalid_argument{"logged written data of " + std::string(text) +
-                " doesn't differ from the logged read data only by the written word at " + access_to_report()};
+        // NOLINTBEGIN(bugprone-unchecked-optional-access)
+        if (a.get_read_hash() != get_hash(m_hasher, a.get_read().value())) {
+            throw std::invalid_argument{
+                "read data for " + std::string(text) + " does not match read hash in " + access_to_report()};
         }
         // NOLINTEND(bugprone-unchecked-optional-access)
-        // check proof
-        auto proof = access.make_proof(m_root_hash);
-        if (!proof.verify(m_hasher)) {
-            throw std::invalid_argument{"Mismatch in root hash of " + access_to_report()};
-        }
-        // Update root hash to reflect the data written by this access
+    }
+
+    void update_root_hash(const proof_type &proof, const hash_type &written_hash) {
         m_root_hash = proof.bubble_up(m_hasher, written_hash);
+    }
+
+    void check_write_access(uint64_t paddr, uint64_t log2_size, const hash_type &expected_hash, const char *text) {
+        const auto &a = check_access(text);
+        check_access_type(a, access_type::write, text);
+        check_access_range(a, access_type::write, paddr, log2_size, text);
+        const auto proof = check_access_siblings_and_read_hash(a, text);
+        const auto &written_hash = check_written_hash(a, expected_hash, text);
+        check_read_data_if_there(a, text);
+        check_written_data_if_there(a, written_hash, text);
+        update_root_hash(proof, written_hash);
+        m_next_access++;
+    }
+
+    void check_write_word_access(uint64_t paddr, uint64_t val, const char *text) {
+        const auto log2_size = cartesi::log2_size<uint64_t>::value;
+        const auto &a = check_access(text);
+        check_access_type(a, access_type::write, text);
+        check_access_range(a, access_type::write, paddr, log2_size, text);
+        const auto proof = check_access_siblings_and_read_hash(a, text);
+        auto written_data = check_read_data(a, text);
+        [[maybe_unused]] const auto [access_paddr, access_log2_size] = adjust_access(paddr, log2_size);
+        const auto val_offset = paddr - access_paddr;
+        replace_word_access_data(val, written_data, val_offset);
+        const auto &written_hash = check_written_hash(a, get_hash(m_hasher, written_data), text);
+        check_written_data_if_there(a, written_hash, text);
+        update_root_hash(proof, written_hash);
+        m_next_access++;
+    }
+
+    uint64_t check_read_word_access(uint64_t paddr, const char *text) {
+        const auto log2_size = cartesi::log2_size<uint64_t>::value;
+        const auto &a = check_access(text);
+        check_access_type(a, access_type::read, text);
+        check_access_range(a, access_type::read, paddr, log2_size, text);
+        std::ignore = check_access_siblings_and_read_hash(a, text);
+        const auto &read_data = check_read_data(a, text);
+        [[maybe_unused]] const auto [access_paddr, access_log2_size] = adjust_access(paddr, log2_size);
+        const auto val_offset = paddr - access_paddr;
+        const auto val = get_word_access_data(read_data, val_offset);
         m_next_access++;
+        return val;
     }
 
     friend i_uarch_state_access<uarch_replay_state_access>;
@@ -260,123 +283,105 @@ class uarch_replay_state_access : public i_uarch_state_access<uarch_replay_state
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
     void do_push_bracket(bracket_type /*type*/, const char * /*text*/) {}
 
+#ifdef DUMP_UARCH_STATE_ACCESS
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    int do_make_scoped_note(const char * /*text*/) {
-        return 0;
+    auto do_make_scoped_note([[maybe_unused]] const char *text) {
+        return scoped_note<uarch_replay_state_access>{*this, text};
     }
+#endif
 
-    uint64_t do_read_x(int reg) {
-        return check_read(machine_reg_address(machine_reg::uarch_x0, reg), "uarch.x");
+    uint64_t do_read_x(int i) {
+        const auto reg = machine_reg_enum(machine_reg::uarch_x0, i);
+        return check_read_word_access(machine_reg_address(reg), machine_reg_get_name(reg));
     }
 
-    void do_write_x(int reg, uint64_t val) {
-        assert(reg != 0);
-        check_write(machine_reg_address(machine_reg::uarch_x0, reg), val, "uarch.x");
+    void do_write_x(int i, uint64_t val) {
+        assert(i != 0);
+        const auto reg = machine_reg_enum(machine_reg::uarch_x0, i);
+        check_write_word_access(machine_reg_address(reg), val, machine_reg_get_name(reg));
     }
 
     uint64_t do_read_pc() {
-        return check_read(machine_reg_address(machine_reg::uarch_pc), "uarch.pc");
+        const auto reg = machine_reg::uarch_pc;
+        return check_read_word_access(machine_reg_address(reg), machine_reg_get_name(reg));
     }
 
     void do_write_pc(uint64_t val) {
-        check_write(machine_reg_address(machine_reg::uarch_pc), val, "uarch.pc");
+        const auto reg = machine_reg::uarch_pc;
+        check_write_word_access(machine_reg_address(reg), val, machine_reg_get_name(reg));
     }
 
     uint64_t do_read_cycle() {
-        return check_read(machine_reg_address(machine_reg::uarch_cycle), "uarch.uarch_cycle");
+        const auto reg = machine_reg::uarch_cycle;
+        return check_read_word_access(machine_reg_address(reg), machine_reg_get_name(reg));
     }
 
     void do_write_cycle(uint64_t val) {
-        check_write(machine_reg_address(machine_reg::uarch_cycle), val, "uarch.cycle");
+        const auto reg = machine_reg::uarch_cycle;
+        check_write_word_access(machine_reg_address(reg), val, machine_reg_get_name(reg));
     }
 
-    bool do_read_halt_flag() {
-        return check_read(machine_reg_address(machine_reg::uarch_halt_flag), "uarch.halt_flag") != 0;
+    uint64_t do_read_halt_flag() {
+        const auto reg = machine_reg::uarch_halt_flag;
+        return check_read_word_access(machine_reg_address(reg), machine_reg_get_name(reg));
     }
 
-    void do_set_halt_flag() {
-        check_write(machine_reg_address(machine_reg::uarch_halt_flag), static_cast<uint64_t>(true), "uarch.halt_flag");
+    void do_write_halt_flag(uint64_t val) {
+        const auto reg = machine_reg::uarch_halt_flag;
+        check_write_word_access(machine_reg_address(reg), val, machine_reg_get_name(reg));
     }
 
-    void do_reset_halt_flag() {
-        check_write(machine_reg_address(machine_reg::uarch_halt_flag), static_cast<uint64_t>(false), "uarch.halt_flag");
+    uint64_t do_read_word(uint64_t paddr) {
+        return check_read_word_access(paddr, uarch_machine_bridge::get_what_name(paddr));
     }
 
-    uint64_t do_read_word(uint64_t paddr) {
-        assert((paddr & (sizeof(uint64_t) - 1)) == 0);
-        // Get the name of the state register identified by this address
-        const auto *name = uarch_bridge::get_register_name(paddr);
-        if (name == nullptr) {
-            // this is a regular memory access
-            name = "memory";
-        }
-        return check_read(paddr, name);
+    void do_write_word(uint64_t paddr, uint64_t val) {
+        check_write_word_access(paddr, val, uarch_machine_bridge::get_what_name(paddr));
     }
 
-    void do_write_word(uint64_t paddr, uint64_t data) {
-        assert((paddr & (sizeof(uint64_t) - 1)) == 0);
-        // Get the name of the state register identified by this address
-        const auto *name = uarch_bridge::get_register_name(paddr);
-        if (name == nullptr) {
-            // this is a regular memory access
-            name = "memory";
-        }
-        check_write(paddr, data, name);
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    void do_putchar(uint8_t /*c*/) {
+        ; // do nothing
+    }
+
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    void do_mark_dirty_page(uint64_t /*paddr*/, uint64_t /*pma_index*/) {
+        ; // do nothing
     }
 
     void do_reset_state() {
-        hasher_type hasher;
-        auto text = std::string("uarchState");
-        if (m_next_access >= m_accesses.size()) {
-            throw std::invalid_argument{"too few accesses in log"};
-        }
-        const auto &access = m_accesses[m_next_access];
-        if (access.get_address() != UARCH_STATE_START_ADDRESS) {
-            throw std::invalid_argument{
-                "expected address of " + access_to_report() + " to be the start address of the uarch state"};
-        }
-        if (access.get_log2_size() != UARCH_STATE_LOG2_SIZE) {
-            throw std::invalid_argument{"expected " + access_to_report() + " to write 2^" +
-                std::to_string(UARCH_STATE_LOG2_SIZE) + " bytes to " + text};
-        }
-        if (access.get_type() != access_type::write) {
-            throw std::invalid_argument{"expected " + access_to_report() + " to write " + text};
-        }
-        // NOLINTBEGIN(bugprone-unchecked-optional-access)
-        if (access.get_read().has_value()) {
-            // if read data is available then its hash and the logged read hash must match
-            hash_type computed_hash;
-            get_hash(hasher, access.get_read().value(), computed_hash);
-            if (computed_hash != access.get_read_hash()) {
-                throw std::invalid_argument{
-                    "hash of read data and read hash at " + access_to_report() + " does not match read hash"};
-            }
-        }
-        if (!access.get_written_hash().has_value()) {
-            throw std::invalid_argument{"write " + access_to_report() + " has no written hash"};
-        }
-        const auto &written_hash = access.get_written_hash().value();
-        if (written_hash != get_uarch_pristine_state_hash()) {
-            throw std::invalid_argument{
-                "expected written hash of " + access_to_report() + " to be the start hash of the pristine uarch state"};
-        }
-        if (access.get_written().has_value()) {
-            // if written data is available then its hash and the logged written hash must match
-            hash_type computed_hash;
-            get_hash(hasher, access.get_written().value(), computed_hash);
-            if (computed_hash != written_hash) {
-                throw std::invalid_argument{"written hash and written data mismatch at " + access_to_report()};
-            }
-        }
-        // NOLINTEND(bugprone-unchecked-optional-access)
-        // check proof
-        auto proof = access.make_proof(m_root_hash);
-        if (!proof.verify(m_hasher)) {
-            throw std::invalid_argument{"Mismatch in root hash of " + access_to_report()};
-        }
-        // Update root hash to reflect the data written by this access
-        m_root_hash = proof.bubble_up(m_hasher, written_hash);
-        m_next_access++;
+        check_write_access(UARCH_STATE_START_ADDRESS, UARCH_STATE_LOG2_SIZE, uarch_pristine_state_hash, "uarch.state");
+    }
+
+    auto get_write_tlb_slot_hash(uint64_t vaddr_page, uint64_t vp_offset, uint64_t pma_index) {
+        // Writes to TLB slots have to be atomic.
+        // We can only do atomic writes of entire Merkle tree nodes.
+        // Therefore, TLB slot must have a power-of-two size, or at least be aligned to it.
+        static_assert(SHADOW_TLB_SLOT_SIZE == sizeof(shadow_tlb_slot), "shadow TLB slot size is wrong");
+        static_assert((UINT64_C(1) << SHADOW_TLB_SLOT_LOG2_SIZE) == SHADOW_TLB_SLOT_SIZE,
+            "shadow TLB slot log2 size is wrong");
+        static_assert(SHADOW_TLB_SLOT_LOG2_SIZE >= machine_merkle_tree::get_log2_word_size(),
+            "shadow TLB slot must fill at least an entire Merkle tree word");
+        shadow_tlb_slot slot_data{};
+        shadow_tlb_fill_slot(vaddr_page, vp_offset, pma_index, slot_data);
+        hash_type slot_hash{};
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        get_merkle_tree_hash(m_hasher, reinterpret_cast<uint8_t *>(&slot_data), sizeof(slot_data),
+            machine_merkle_tree::get_word_size(), slot_hash);
+        return slot_hash;
+    }
+
+    void do_write_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset,
+        uint64_t pma_index) {
+        const auto slot_paddr = shadow_tlb_get_abs_addr(set_index, slot_index);
+        const auto slot_hash = get_write_tlb_slot_hash(vaddr_page, vp_offset, pma_index);
+        check_write_access(slot_paddr, SHADOW_TLB_SLOT_LOG2_SIZE, slot_hash, "tlb.slot");
+    }
+
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    constexpr const char *do_get_name() const {
+        return "uarch_replay_state_access";
+>>>>>>> 1e5dc22 (refactor: clean up uarch state access mechanism)
     }
 };
 
diff --git a/src/uarch-solidity-compat.h b/src/uarch-solidity-compat.h
index 4cc48266f..1be7df99c 100644
--- a/src/uarch-solidity-compat.h
+++ b/src/uarch-solidity-compat.h
@@ -17,11 +17,13 @@
 #ifndef UARCH_INTERPRET_SOLIDITY_COMPAT_H
 #define UARCH_INTERPRET_SOLIDITY_COMPAT_H
 
-#include "os.h"
 #include <cassert>
 #include <cmath>
 #include <cstdint>
 #include <stdexcept>
+#ifdef DUMP_INSN
+#include <cinttypes>
+#endif
 
 /// \file
 /// \brief Solidity Compatibility Layer
@@ -66,13 +68,13 @@ static inline void writeCycle(UarchState &a, uint64 val) {
 }
 
 template <typename UarchState>
-static inline bool readHaltFlag(UarchState &a) {
+static inline uint64 readHaltFlag(UarchState &a) {
     return a.read_halt_flag();
 }
 
 template <typename UarchState>
-static inline void setHaltFlag(UarchState &a) {
-    return a.set_halt_flag();
+static inline void writeHaltFlag(UarchState &a, uint64 val) {
+    a.write_halt_flag(val);
 }
 
 template <typename UarchState>
@@ -105,7 +107,7 @@ static inline uint64 readIflagsY(State &a) {
     return a.read_iflags_Y();
 }
 
-template <typename UarchState>
+template <typename State>
 static inline void writeIflagsY(State &a, uint64 val) {
     a.write_iflags_Y(val);
 }
@@ -127,17 +129,19 @@ static inline void throwRuntimeError(UarchState & /*a*/, const char *message) {
 }
 
 template <typename UarchState>
-static inline void putChar(UarchState & /*a*/, unsigned char c) {
-    os_putchar(c);
+static inline void putCharECALL(UarchState &a, uint8 c) {
+    a.putchar(c);
 }
 
 template <typename UarchState>
-static inline void markDirtyPage(UarchState &a, uint64 paddr, uint64 pma_index) {
+static inline void markDirtyPageECALL(UarchState &a, uint64 paddr, uint64 pma_index) {
     a.mark_dirty_page(paddr, pma_index);
 }
 
-static inline void writeTlbVpOffset(UarchState &a, uint64 use, uint64 vp_offset, uint64 pma_index) {
-    a.write_tlb_vp_offset(use, slot_index, vp_offset, pma_index);
+template <typename UarchState>
+static inline void writeTlbECALL(UarchState &a, uint64 set_index, uint64 slot_index, uint64 vaddr_page,
+    uint64 vp_offset, uint64 pma_index) {
+    a.write_tlb(static_cast<TLB_set_index>(set_index), slot_index, vaddr_page, vp_offset, pma_index);
 }
 
 // Conversions and arithmetic functions
diff --git a/src/uarch-state-access.h b/src/uarch-state-access.h
index c840da29c..94d66784b 100644
--- a/src/uarch-state-access.h
+++ b/src/uarch-state-access.h
@@ -22,58 +22,38 @@
 #include <stdexcept>
 
 #include "bracket-note.h"
+#include "host-addr.h"
 #include "i-uarch-state-access.h"
-#include "machine-state.h"
-#include "pma.h"
+#include "machine.h"
+#include "os.h"
 #include "riscv-constants.h"
 #include "strict-aliasing.h"
-#if OKUARCH
-#include "uarch-bridge.h"
+#include "uarch-machine-bridge.h"
 #include "uarch-pristine.h"
-#include "uarch-state.h"
+
+#if DUMP_UARCH_STATE_ACCESS
+#include "scoped-note.h"
 #endif
 
 namespace cartesi {
 
 class uarch_state_access : public i_uarch_state_access<uarch_state_access> {
-#ifdef OKUARCH
     // NOLINTBEGIN(cppcoreguidelines-avoid-const-or-ref-data-members)
-    uarch_state &m_us;
-    machine_state &m_s;
+    machine &m_m;
+    uarch_machine_bridge m_b;
+    host_addr m_uram_ph_offset;
     // NOLINTEND(cppcoreguidelines-avoid-const-or-ref-data-members)1
 
-    /// \brief Obtain Memory PMA entry that covers a given physical memory region
-    /// \param paddr Start of physical memory region.
-    /// \param length Length of physical memory region.
-    /// \returns Corresponding entry if found, or a sentinel entry
-    /// for an empty range.
-    pma_entry &find_memory_pma_entry(uint64_t paddr, uint64_t length) {
-        // First, search microarchitecture private PMA entries
-        if (m_us.ram.contains(paddr, length)) {
-            return m_us.ram;
-        }
-        int i = 0;
-        // Search machine memory PMA entries (not devices or anything else)
-        while (true) {
-            auto &pma = m_s.pmas[i];
-            // The pmas array always contain a sentinel. It is an entry with
-            // zero length. If we hit it, return it
-            if (pma.get_length() == 0) {
-                return pma;
-            }
-            if (pma.get_istart_M() && pma.contains(paddr, length)) {
-                return pma;
-            }
-            i++;
-        }
-    }
-
 public:
     /// \brief Constructor from machine and uarch states.
     /// \param um Reference to uarch state.
     /// \param m Reference to machine state.
-    explicit uarch_state_access(uarch_state &us, machine_state &s) : m_us(us), m_s(s) {
-        ;
+    explicit uarch_state_access(machine &m) : m_m(m), m_b(m) {
+        const auto &uram = m_m.get_uarch_state().ram;
+        const auto haddr = cast_ptr_to_host_addr(uram.get_memory_noexcept().get_host_memory());
+        const auto paddr = uram.get_start();
+        // initialize translation cache from paddr in uarch RAM to host address
+        m_uram_ph_offset = haddr - paddr;
     }
 
     /// \brief No copy constructor
@@ -90,119 +70,98 @@ class uarch_state_access : public i_uarch_state_access<uarch_state_access> {
 private:
     friend i_uarch_state_access<uarch_state_access>;
 
+#ifdef DUMP_UARCH_STATE_ACCESS
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    void do_push_bracket(bracket_type /*type*/, const char * /*text*/) {}
-
-    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    int do_make_scoped_note(const char * /*text*/) {
-        return 0;
+    auto do_make_scoped_note([[maybe_unused]] const char *text) {
+        return scoped_note<uarch_state_access>{*this, text};
     }
+#endif
 
-    uint64_t do_read_x(int reg) const {
-        return m_us.x[reg];
+    uint64_t do_read_x(int i) const {
+        return m_m.get_uarch_state().x[i];
     }
 
-    void do_write_x(int reg, uint64_t val) {
-        assert(reg != 0);
-        m_us.x[reg] = val;
+    void do_write_x(int i, uint64_t val) {
+        assert(i != 0);
+        m_m.get_uarch_state().x[i] = val;
     }
 
     uint64_t do_read_pc() const {
-        return m_us.pc;
+        return m_m.get_uarch_state().pc;
     }
 
     void do_write_pc(uint64_t val) {
-        m_us.pc = val;
+        m_m.get_uarch_state().pc = val;
     }
 
     uint64_t do_read_cycle() const {
-        return m_us.cycle;
+        return m_m.get_uarch_state().cycle;
     }
 
     void do_write_cycle(uint64_t val) {
-        m_us.cycle = val;
-    }
-
-    bool do_read_halt_flag() const {
-        return m_us.halt_flag;
+        m_m.get_uarch_state().cycle = val;
     }
 
-    void do_set_halt_flag() {
-        m_us.halt_flag = true;
+    uint64_t do_read_halt_flag() const {
+        return m_m.get_uarch_state().halt_flag;
     }
 
-    void do_reset_halt_flag() {
-        m_us.halt_flag = false;
+    void do_write_halt_flag(uint64_t v) {
+        m_m.get_uarch_state().halt_flag = v;
     }
 
     uint64_t do_read_word(uint64_t paddr) {
-        // Find a memory range that contains the specified address
-        auto &pma = find_memory_pma_entry(paddr, sizeof(uint64_t));
-        if (pma.get_istart_E()) {
-            // This word doesn't fall within any memory PMA range.
-            // Check if uarch is trying to access a machine state register
-            return read_register(paddr);
+        if ((paddr & (sizeof(uint64_t) - 1)) != 0) {
+            throw std::runtime_error("misaligned read from uarch");
         }
-        if (!pma.get_istart_R()) {
-            throw std::runtime_error("pma is not readable");
+        // If the word is in UARCH_RAM, read it
+        if (m_m.get_uarch_state().ram.contains(paddr, sizeof(uint64_t))) {
+            auto haddr = m_uram_ph_offset + paddr;
+            return aliased_aligned_read<uint64_t>(haddr);
         }
-        // Found a writable memory range. Access host memory accordingly.
-        const uint64_t hoffset = paddr - pma.get_start();
-        unsigned char *hmem = pma.get_memory().get_host_memory() + hoffset;
-        return aliased_aligned_read<uint64_t>(hmem);
-    }
-
-    /// \brief Reads a uint64 machine state register mapped to a memory address
-    /// \param paddr Address of the state register
-    /// \param data Pointer receiving register value
-    uint64_t read_register(uint64_t paddr) {
-        return uarch_bridge::read_register(paddr, m_s);
-    }
-
-    /// \brief Fallback to error on all other word sizes
-    void do_write_word(uint64_t paddr, uint64_t data) {
-        // Find a memory range that contains the specified address
-        auto &pma = find_memory_pma_entry(paddr, sizeof(uint64_t));
-        if (pma.get_istart_E()) {
-            // This word doesn't fall within any memory PMA range.
-            // Check if uarch is trying to access a machine state register
-            write_register(paddr, data);
-            return;
+        // Otherwise, forward to bridge
+        return m_b.read_word(paddr);
+    }
+
+    void do_write_word(uint64_t paddr, uint64_t val) {
+        if ((paddr & (sizeof(uint64_t) - 1)) != 0) {
+            throw std::runtime_error("misaligned write to uarch");
         }
-        if (!pma.get_istart_W()) {
-            throw std::runtime_error("pma is not writable");
+        // If the word is in UARCH_RAM, write it
+        if (m_m.get_uarch_state().ram.contains(paddr, sizeof(uint64_t))) {
+            auto haddr = m_uram_ph_offset + paddr;
+            aliased_aligned_write<uint64_t>(haddr, val);
+            return;
         }
-        // Found a writable memory range. Access host memory accordingly.
-        const uint64_t hoffset = paddr - pma.get_start();
-        unsigned char *hmem = pma.get_memory().get_host_memory() + hoffset;
-        aliased_aligned_write(hmem, data);
-        const uint64_t paddr_page = paddr & ~PAGE_OFFSET_MASK;
-        pma.mark_dirty_page(paddr_page - pma.get_start());
+        // Otherwise, forward to bridge
+        m_b.write_word(paddr, val);
+    }
+
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    void do_putchar(uint8_t c) {
+        os_putchar(c);
+    }
+
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    void do_mark_dirty_page(uint64_t paddr, uint64_t pma_index) {
+        // forward to bridge
+        m_b.mark_dirty_page(paddr, pma_index);
     }
 
-    /// \brief Writes a uint64 machine state register mapped to a memory address
-    /// \param paddr Address of the state register
-    /// \param data New register value
-    void write_register(uint64_t paddr, uint64_t data) {
-        uarch_bridge::write_register(paddr, m_s, data);
+    void do_write_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset,
+        uint64_t pma_index) {
+        // forward to bridge
+        m_b.write_shadow_tlb(set_index, slot_index, vaddr_page, vp_offset, pma_index);
     }
 
     void do_reset_state() {
-        m_us.halt_flag = false;
-        m_us.pc = UARCH_PC_INIT;
-        m_us.cycle = UARCH_CYCLE_INIT;
-        for (int i = 1; i < UARCH_X_REG_COUNT; i++) {
-            m_us.x[i] = UARCH_X_INIT;
-        }
-        // Load embedded pristine RAM image
-        if (uarch_pristine_ram_len > m_us.ram.get_length()) {
-            throw std::runtime_error("embedded uarch ram image does not fit in uarch ram pma");
-        }
-        m_us.ram.write_memory(m_us.ram.get_start(), uarch_pristine_ram, uarch_pristine_ram_len);
-        m_us.ram.fill_memory(m_us.ram.get_start() + uarch_pristine_ram_len, 0,
-            m_us.ram.get_length() - uarch_pristine_ram_len);
+        m_m.reset_uarch();
+    }
+
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    constexpr const char *do_get_name() const {
+        return "uarch_state_access";
     }
-#endif
 };
 
 } // namespace cartesi
diff --git a/src/uarch-state.h b/src/uarch-state.h
index 3c4e0f18a..f028c5027 100644
--- a/src/uarch-state.h
+++ b/src/uarch-state.h
@@ -41,7 +41,7 @@ struct uarch_state {
     uint64_t pc{};                               ///< Program counter.
     std::array<uint64_t, UARCH_X_REG_COUNT> x{}; ///< Register file.
     uint64_t cycle{};                            ///< Cycles counter
-    bool halt_flag{};
+    uint64_t halt_flag{};
     pma_entry shadow_state; ///< Shadow uarch state
     pma_entry ram;          ///< Memory range for micro RAM
     pma_entry empty_pma;    ///< Empty range fallback
diff --git a/src/uarch-step.cpp b/src/uarch-step.cpp
index b7dbd9f4e..6e2466aff 100644
--- a/src/uarch-step.cpp
+++ b/src/uarch-step.cpp
@@ -872,25 +872,27 @@ static inline void executeECALL(UarchState &a, uint64 pc) {
     // return value is in a0 (and maybe also in a1)
     uint64 fn = readX(a, 17); // a7 contains the function number
     if (fn == UARCH_ECALL_FN_HALT) {
-        return setHaltFlag(a);
+        return writeHaltFlag(a, 1);
     }
     if (fn == UARCH_ECALL_FN_PUTCHAR) {
-        uint64 character = readX(a, 10); // a0 contains the character to print
-        putChar(a, uint8(character));
+        uint64 c = readX(a, 10);   // a0 contains the character to print
+        putCharECALL(a, uint8(c)); // Can be a NOOP in Solidity
         return advancePc(a, pc);
     }
     if (fn == UARCH_ECALL_FN_MARK_DIRTY_PAGE) {
-        uint64 paddr = readX(a, 10);     // a0 contains physical address in page to be marked dirty
-        uint64 pma_index = readX(a, 11); // a1 contains a index of PMA where page falls
-        markDirtyPage(a, paddr, pma_index);
+        uint64 paddr = readX(a, 10);             // a0 contains physical address in page to be marked dirty
+        uint64 pma_index = readX(a, 11);         // a1 contains a index of PMA where page falls
+        markDirtyPageECALL(a, paddr, pma_index); // This MUST be be a NOOP in Solidity
         return advancePc(a, pc);
     }
-    if (fn == UARCH_ECALL_FN_WRITE_TLB_VP_OFFSET) {
-        uint64 use = readX(a, 10);        // a0 contains TLB set (code, read, write)
+    if (fn == UARCH_ECALL_FN_WRITE_TLB) {
+        uint64 set_index = readX(a, 10);  // a0 contains TLB set (code, read, write)
         uint64 slot_index = readX(a, 11); // a1 contains slot_index to modify
-        uint64 vp_offset = readX(a, 12);  // a2 contains vp_offset to write
-        uint64 pma_index = readX(a, 13);  // a3 contains index of PMA where page falls
-        writeTlbVpOffset(a, use, slot_index, vp_offset, pma_index);
+        uint64 vaddr_page = readX(a, 12); // a2 contains vaddr_page to write
+        uint64 vp_offset = readX(a, 13);  // a3 contains vp_offset to write
+        uint64 pma_index = readX(a, 14);  // a4 contains index of PMA where page falls
+        writeTlbECALL(a, set_index, slot_index, vaddr_page, vp_offset,
+            pma_index); // WARNING: This CANNOT be a NOOP in Solidity
         return advancePc(a, pc);
     }
     throwRuntimeError(a, "unsupported ecall function");
@@ -1097,7 +1099,7 @@ UArchStepStatus uarch_step(UarchState &a) {
         return UArchStepStatus::CycleOverflow;
     }
     // do not advance if machine is halted
-    if (readHaltFlag(a)) {
+    if (readHaltFlag(a) != 0) {
         return UArchStepStatus::UArchHalted;
     }
     // execute next instruction
diff --git a/tests/Makefile b/tests/Makefile
index e54068cdd..fadc12612 100644
--- a/tests/Makefile
+++ b/tests/Makefile
@@ -44,12 +44,12 @@ ifeq ($(TARGET_OS),Darwin)
 LIBCARTESI_SO=libcartesi-$(MACHINE_EMULATOR_SO_VERSION).dylib
 LIBCARTESI_SO_JSONRPC=libcartesi_jsonrpc-$(MACHINE_EMULATOR_SO_VERSION).dylib
 
-NUM_JOBS := $(shell sysctl -n hw.ncpu)
+NUM_JOBS ?= $(shell sysctl -n hw.ncpu)
 else
 LIBCARTESI_SO=libcartesi-$(MACHINE_EMULATOR_SO_VERSION).so
 LIBCARTESI_SO_JSONRPC=libcartesi_jsonrpc-$(MACHINE_EMULATOR_SO_VERSION).so
 
-NUM_JOBS := $(shell nproc)
+NUM_JOBS ?= $(shell nproc)
 endif
 
 ifeq ($(coverage),yes)
diff --git a/tests/lua/cartesi/tests/util.lua b/tests/lua/cartesi/tests/util.lua
index c98e13138..b63eac9b6 100644
--- a/tests/lua/cartesi/tests/util.lua
+++ b/tests/lua/cartesi/tests/util.lua
@@ -26,10 +26,10 @@ local function adjust_path(path)
 end
 
 local test_util = {
-    images_path = adjust_path(assert(os.getenv("CARTESI_IMAGES_PATH"))),
-    tests_path = adjust_path(assert(os.getenv("CARTESI_TESTS_PATH"))),
-    cmio_path = adjust_path(assert(os.getenv("CARTESI_CMIO_PATH"))),
-    tests_uarch_path = adjust_path(assert(os.getenv("CARTESI_TESTS_UARCH_PATH"))),
+    images_path = adjust_path(assert(os.getenv("CARTESI_IMAGES_PATH"), "must set CARTESI_IMAGES_PATH")),
+    tests_path = adjust_path(assert(os.getenv("CARTESI_TESTS_PATH"), "must set CARTESI_TESTS_PATH")),
+    cmio_path = adjust_path(assert(os.getenv("CARTESI_CMIO_PATH"), "must set CARTESI_CMIO_PATH")),
+    tests_uarch_path = adjust_path(assert(os.getenv("CARTESI_TESTS_UARCH_PATH"), "must set CARTESI_TESTS_UARCH_PATH")),
 }
 
 local zero_keccak_hash_table = {
@@ -60,9 +60,7 @@ test_util.uarch_programs.default = {
 }
 
 function test_util.create_test_uarch_program(instructions)
-    if not instructions then
-        instructions = test_util.uarch_programs.default
-    end
+    assert(instructions, "missing instructions")
     local file_path = os.tmpname()
     local f <close> = assert(io.open(file_path, "wb"))
     for _, insn in pairs(instructions) do
diff --git a/tests/lua/log-with-mtime-transition.lua b/tests/lua/log-with-mtime-transition.lua
index ba402519d..4d3298952 100755
--- a/tests/lua/log-with-mtime-transition.lua
+++ b/tests/lua/log-with-mtime-transition.lua
@@ -12,8 +12,12 @@ local config = {
 }
 local machine <close> = cartesi.machine(config)
 
+io.stderr:write("getting root hash\n")
 local old_hash = machine:get_root_hash()
+io.stderr:write("getting uarch step log\n")
 local access_log = machine:log_step_uarch()
+io.stderr:write("getting new root hash\n")
 local new_hash = machine:get_root_hash()
+io.stderr:write("verifying step log\n")
 cartesi.machine:verify_step_uarch(old_hash, access_log, new_hash, {})
 print("ok")
diff --git a/tests/lua/machine-bind.lua b/tests/lua/machine-bind.lua
index c4259c1f2..8e050748b 100755
--- a/tests/lua/machine-bind.lua
+++ b/tests/lua/machine-bind.lua
@@ -242,6 +242,15 @@ local function get_cpu_reg_test_values()
     return reg_values
 end
 
+local function check_error_find(err, expected_err)
+    if not err then
+        error("expected error with '" .. expected_err .. "' (got no error)")
+    end
+    if not err:find(expected_err, 1, true) then
+        error("expected error with '" .. expected_err .. "' (got '" .. tostring(err) .. "')")
+    end
+end
+
 local machine_type = assert(arguments[1], "missing machine type")
 assert(machine_type == "local" or machine_type == "jsonrpc", "unknown machine type, should be 'local' or 'jsonrpc'")
 local to_shutdown -- luacheck: no unused
@@ -268,7 +277,7 @@ local function build_machine_config(config_options)
             processor = get_uarch_cpu_reg_test_values(),
             ram = {
                 length = 0x1000,
-                image_filename = test_util.create_test_uarch_program(),
+                image_filename = test_util.create_test_uarch_program(test_util.uarch_programs.default),
             },
         },
     }
@@ -551,7 +560,7 @@ do_test("should error if target mcycle is smaller than current mcycle", function
         machine:run(MAX_MCYCLE - 1)
     end)
     assert(success == false)
-    assert(err and err:match("mcycle is past"))
+    check_error_find(err, "mcycle is past")
     assert(machine:read_reg("mcycle") == MAX_MCYCLE)
 end)
 
@@ -562,7 +571,7 @@ do_test("should error if target uarch_cycle is smaller than current uarch_cycle"
         machine:run_uarch(MAX_UARCH_CYCLE - 1)
     end)
     assert(success == false)
-    assert(err and err:match("uarch_cycle is past"))
+    check_error_find(err, "uarch_cycle is past")
     assert(machine:read_reg("uarch_cycle") == MAX_UARCH_CYCLE)
 end)
 
@@ -638,9 +647,9 @@ do_test("written and read values should match", function(machine)
     assert(memory_read == "mydataol12345678")
 end)
 
-print("\n\n dump step log  to console")
+print("\n\n dump step log to console")
 do_test("dumped step log content should match", function(machine)
-    local log = machine:log_step_uarch(cartesi.ACCESS_LOG_TYPE_ANNOTATIONS)
+    local log = machine:log_step_uarch(cartesi.ACCESS_LOG_TYPE_ANNOTATIONS | cartesi.ACCESS_LOG_TYPE_LARGE_DATA)
     local temp_file <close> = test_util.new_temp_file()
     util.dump_log(log, temp_file)
     local log_output = temp_file:read_all()
@@ -649,10 +658,10 @@ do_test("dumped step log content should match", function(machine)
         .. "  1: read uarch.cycle@0x400008(4194312): 0x0(0)\n"
         .. "  2: read uarch.halt_flag@0x400000(4194304): 0x0(0)\n"
         .. "  3: read uarch.pc@0x400010(4194320): 0x600000(6291456)\n"
-        .. "  4: read memory@0x600000(6291456): 0x10089307b00513(4513027209561363)\n"
+        .. "  4: read uarch.ram@0x600000(6291456): 0x10089307b00513(4513027209561363)\n"
         .. "  begin addi\n"
-        .. "    5: read uarch.x@0x400018(4194328): 0x0(0)\n"
-        .. "    6: write uarch.x@0x400068(4194408): 0x10050(65616) -> 0x7b(123)\n"
+        .. "    5: read uarch.x0@0x400018(4194328): 0x0(0)\n"
+        .. "    6: write uarch.x10@0x400068(4194408): 0x10050(65616) -> 0x7b(123)\n"
         .. "    7: write uarch.pc@0x400010(4194320): 0x600000(6291456) -> 0x600004(6291460)\n"
         .. "  end addi\n"
         .. "  8: write uarch.cycle@0x400008(4194312): 0x0(0) -> 0x1(1)\n"
@@ -686,7 +695,7 @@ do_test("Step log must contain conssitent data hashes", function(machine)
     -- ensure that verification fails with wrong read hash
     read_access.read_hash = wrong_hash
     local _, err = pcall(machine.verify_step_uarch, machine, initial_hash, log, final_hash)
-    assert(err:match("logged read data of uarch.uarch_cycle data does not hash to the logged read hash at 1st access"))
+    check_error_find(err, "siblings and read hash do not match root hash before 1st access to uarch.cycle")
     read_access.read_hash = read_hash -- restore correct value
 
     -- ensure that verification fails with wrong read hash
@@ -695,13 +704,13 @@ do_test("Step log must contain conssitent data hashes", function(machine)
     read_hash = write_access.read_hash
     write_access.read_hash = wrong_hash
     _, err = pcall(machine.verify_step_uarch, machine, initial_hash, log, final_hash)
-    assert(err:match("logged read data of uarch.cycle does not hash to the logged read hash at 8th access"))
+    check_error_find(err, "siblings and read hash do not match root hash before 8th access to uarch.cycle")
     write_access.read_hash = read_hash -- restore correct value
 
     -- ensure that verification fails with wrong written hash
     write_access.written_hash = wrong_hash
     _, err = pcall(machine.verify_step_uarch, machine, initial_hash, log, final_hash)
-    assert(err:match("logged written data of uarch.cycle does not hash to the logged written hash at 8th access"))
+    check_error_find(err, "written hash for uarch.cycle does not match expected hash in 8th access")
 end)
 
 do_test("step when uarch cycle is max", function(machine)
@@ -819,7 +828,7 @@ test_util.make_do_test(build_machine, machine_type, { uarch = {} })(
 
 local test_reset_uarch_config = {
     processor = {
-        halt_flag = true,
+        halt_flag = 1,
         cycle = 1,
         pc = 0,
     },
@@ -901,10 +910,10 @@ test_util.make_do_test(build_machine, machine_type, { uarch = test_reset_uarch_c
         -- verifying incorrect initial hash
         local wrong_hash = string.rep("0", cartesi.HASH_SIZE)
         local _, err = pcall(machine.verify_reset_uarch, machine, wrong_hash, log, final_hash)
-        assert(err:match("Mismatch in root hash of 1st access"))
+        check_error_find(err, "siblings and read hash do not match root hash before 1st access to uarch.state")
         -- verifying incorrect final hash
         _, err = pcall(machine.verify_reset_uarch, machine, initial_hash, log, wrong_hash)
-        assert(err:match("mismatch in root hash after replay"))
+        check_error_find(err, "mismatch in root hash after replay")
     end
 )
 
@@ -922,10 +931,10 @@ test_util.make_do_test(build_machine, machine_type, { uarch = test_reset_uarch_c
     "Dump of log produced by log_reset_uarch should match",
     function(machine)
         local log = machine:log_reset_uarch(cartesi.ACCESS_LOG_TYPE_ANNOTATIONS)
-        local expected_dump_pattern = "begin reset uarch state\n"
-            .. "  1: write uarch_state@0x400000%(4194304%): "
+        local expected_dump_pattern = "begin reset_uarch_state\n"
+            .. "  1: write uarch.state@0x400000%(4194304%): "
             .. 'hash:"[0-9a-f]+"%(2%^22 bytes%) %-> hash:"[0-9a-fA-F]+"%(2%^22 bytes%)\n'
-            .. "end reset uarch state\n"
+            .. "end reset_uarch_state\n"
 
         local tmpname = os.tmpname()
         local deleter = {}
@@ -959,7 +968,7 @@ test_util.make_do_test(build_machine, machine_type, { uarch = test_reset_uarch_c
         local final_hash = machine:get_root_hash()
         assert(#log.accesses == 1, "log should have 1 access")
         local access = log.accesses[1]
-        -- in debug mode, the log must include read and written data
+        -- when large data is requested, the log must include read and written data
         assert(access.read ~= nil, "read data should not be nil")
         assert(access.written ~= nil, "written data should not be nil")
         -- verify returned log
@@ -969,13 +978,13 @@ test_util.make_do_test(build_machine, machine_type, { uarch = test_reset_uarch_c
         -- tamper with read data to produce a hash mismatch
         access.read = "X" .. access.read:sub(2)
         local _, err = pcall(machine.verify_reset_uarch, machine, initial_hash, log, final_hash)
-        assert(err:match("hash of read data and read hash at 1st access does not match read hash"))
+        check_error_find(err, "read data for uarch.state does not match read hash in 1st access")
         -- restore correct read
         access.read = original_read
         --  change written data to produce a hash mismatch
         access.written = "X" .. access.written:sub(2)
         _, err = pcall(machine.verify_reset_uarch, machine, initial_hash, log, final_hash)
-        assert(err:match("written hash and written data mismatch at 1st access"))
+        check_error_find(err, "written data for uarch.state does not match written hash in 1st access")
     end
 )
 
@@ -988,41 +997,38 @@ do_test("Test unhappy paths of verify_reset_uarch", function(machine)
         local final_hash = machine:get_root_hash()
         callback(log)
         local _, err = pcall(machine.verify_reset_uarch, machine, initial_hash, log, final_hash)
-        assert(
-            err:match(expected_error),
-            'Error text "' .. err .. '"  does not match expected "' .. expected_error .. '"'
-        )
+        check_error_find(err, expected_error)
     end
-    assert_error("too few accesses in log", function(log)
+    assert_error("log is missing access 1st access to uarch.state", function(log)
         log.accesses = {}
     end)
-    assert_error("expected address of 1st access to be the start address of the uarch state", function(log)
+    assert_error("expected 1st access to write uarch.state at address 0x400000(4194304)", function(log)
         log.accesses[1].address = 0
     end)
 
-    assert_error("is out of bounds", function(log)
+    assert_error('field "value/accesses/0/log2_size" is out of bounds', function(log)
         log.accesses[1].log2_size = 64
     end)
 
-    assert_error("missing field", function(log)
+    assert_error('missing field "value/accesses/0/read_hash"', function(log)
         log.accesses[#log.accesses].read_hash = nil
     end)
-    assert_error("Mismatch in root hash of 1st access", function(log)
+    assert_error("siblings and read hash do not match root hash before 1st access to uarch.state", function(log)
         log.accesses[1].read_hash = bad_hash
     end)
     assert_error("access log was not fully consumed", function(log)
         log.accesses[#log.accesses + 1] = log.accesses[1]
     end)
-    assert_error("write 1st access has no written hash", function(log)
+    assert_error("missing written hash of uarch.state in 1st access", function(log)
         log.accesses[#log.accesses].written_hash = nil
     end)
-    assert_error("has wrong length", function(log)
+    assert_error('field "value/accesses/0/written" has wrong length', function(log)
         log.accesses[#log.accesses].written = "\0"
     end)
-    assert_error("written hash and written data mismatch at 1st access", function(log)
+    assert_error("written data for uarch.state does not match written hash in 1st access", function(log)
         log.accesses[#log.accesses].written = string.rep("\0", 2 ^ 22)
     end)
-    assert_error("Mismatch in root hash of 1st access", function(log)
+    assert_error("siblings and read hash do not match root hash before 1st access to uarch.state", function(log)
         log.accesses[1].sibling_hashes[1] = bad_hash
     end)
 end)
@@ -1036,54 +1042,45 @@ do_test("Test unhappy paths of verify_step_uarch", function(machine)
         local final_hash = machine:get_root_hash()
         callback(log)
         local _, err = pcall(machine.verify_step_uarch, machine, initial_hash, log, final_hash)
-        assert(
-            err:match(expected_error),
-            'Error text "' .. err .. '"  does not match expected "' .. expected_error .. '"'
-        )
+        check_error_find(err, expected_error)
     end
-    assert_error("too few accesses in log", function(log)
+    assert_error("log is missing access 1st access to uarch.cycle", function(log)
         log.accesses = {}
     end)
-    assert_error("expected 1st access to read uarch.uarch_cycle", function(log)
+    assert_error("expected 1st access to read uarch.cycle", function(log)
         log.accesses[1].address = 0
     end)
-    assert_error("expected 1st access to read 2%^5 bytes from uarch.uarch_cycle", function(log)
+    assert_error("expected 1st access to uarch.cycle to read 2^3 bytes", function(log)
         log.accesses[1].log2_size = 2
     end)
     assert_error("is out of bounds", function(log)
         log.accesses[1].log2_size = 65
     end)
-    assert_error("missing read uarch.uarch_cycle data at 1st access", function(log)
+    assert_error("missing read data for uarch.cycle in 1st access", function(log)
         log.accesses[1].read = nil
     end)
     assert_error("has wrong length", function(log)
         log.accesses[1].read = "\0"
     end)
-    assert_error(
-        "logged read data of uarch.uarch_cycle data does not hash to the logged read hash at 1st access",
-        function(log)
-            log.accesses[1].read_hash = bad_hash
-        end
-    )
+    assert_error("siblings and read hash do not match root hash before 1st access to uarch.cycle", function(log)
+        log.accesses[1].read_hash = bad_hash
+    end)
     assert_error("missing field", function(log)
         log.accesses[#log.accesses].read_hash = nil
     end)
     assert_error("access log was not fully consumed", function(log)
         log.accesses[#log.accesses + 1] = log.accesses[1]
     end)
-    assert_error("missing written uarch.cycle hash at 7th access", function(log)
+    assert_error("missing written hash of uarch.cycle in 7th access", function(log)
         log.accesses[#log.accesses].written_hash = nil
     end)
     assert_error("has wrong length", function(log)
         log.accesses[#log.accesses].written = "\0"
     end)
-    assert_error(
-        "logged written data of uarch.cycle does not hash to the logged written hash at 7th access",
-        function(log)
-            log.accesses[#log.accesses].written = string.rep("\0", cartesi.HASH_SIZE)
-        end
-    )
-    assert_error("Mismatch in root hash of 1st access", function(log)
+    assert_error("written data for uarch.cycle does not match written hash in 7th access", function(log)
+        log.accesses[#log.accesses].written = string.rep("\0", cartesi.HASH_SIZE)
+    end)
+    assert_error("siblings and read hash do not match root hash before 1st access to uarch.cycle", function(log)
         log.accesses[1].sibling_hashes[1] = bad_hash
     end)
 end)
@@ -1101,7 +1098,7 @@ test_util.make_do_test(build_machine, machine_type, {
 })("Detect illegal instruction", function(machine)
     local success, err = pcall(machine.run_uarch, machine)
     assert(success == false)
-    assert(err:match("illegal instruction"))
+    check_error_find(err, "illegal instruction")
 end)
 
 --[==[
@@ -1261,12 +1258,12 @@ do_test("Dump of log produced by send_cmio_response should match", function(mach
     local reason = 7
     local log = machine:log_send_cmio_response(reason, data, cartesi.ACCESS_LOG_TYPE_ANNOTATIONS)
     -- luacheck: push no max line length
-    local expected_dump = "begin send cmio response\n"
+    local expected_dump = "begin send_cmio_response\n"
         .. "  1: read iflags.Y@0x2f8(760): 0x1(1)\n"
         .. '  2: write cmio rx buffer@0x60000000(1610612736): hash:"290decd9"(2^5 bytes) -> hash:"555b1f6d"(2^5 bytes)\n'
         .. "  3: write htif.fromhost@0x330(816): 0x0(0) -> 0x70000000a(30064771082)\n"
         .. "  4: write iflags.Y@0x2f8(760): 0x1(1) -> 0x0(0)\n"
-        .. "end send cmio response\n"
+        .. "end send_cmio_response\n"
     -- luacheck: pop
     local temp_file <close> = test_util.new_temp_file()
     util.dump_log(log, temp_file)
@@ -1459,7 +1456,14 @@ test_util.make_do_test(build_machine, machine_type, {
     machine:write_reg("uarch_x" .. t1, leaf_address)
     machine:write_reg("uarch_x" .. t0, 0xaaaaaaaaaaaaaaaa)
     local log, dump = log_step()
-    assert(dump:match("7: write memory@0x%x+%(%d+%): 0x1111111111111111%(%d+%) %-> 0xaaaaaaaaaaaaaaaa%(%d+%)"))
+    assert(
+        dump:find(
+            "write uarch.ram@0x600020(6291488): 0x1111111111111111(1229782938247303441)"
+                .. " -> 0xaaaaaaaaaaaaaaaa(12297829382473034410)",
+            1,
+            true
+        )
+    )
     assert(log.accesses[7].read == leaf_data)
     leaf_data = machine:read_memory(leaf_address, leaf_size) -- read and check written data
     assert(leaf_data == make_leaf("\xaa", "\x22", "\x33", "\x44"))
@@ -1470,7 +1474,14 @@ test_util.make_do_test(build_machine, machine_type, {
     machine:write_reg("uarch_x" .. t1, machine:read_reg("uarch_x" .. t1) + word_size)
     machine:write_reg("uarch_x" .. t0, 0xbbbbbbbbbbbbbbbb)
     log, dump = log_step()
-    assert(dump:match("7: write memory@0x%x+%(%d+%): 0x2222222222222222%(%d+%) %-> 0xbbbbbbbbbbbbbbbb%(%d+%)"))
+    assert(
+        dump:find(
+            "write uarch.ram@0x600028(6291496): 0x2222222222222222(2459565876494606882)"
+                .. " -> 0xbbbbbbbbbbbbbbbb(13527612320720337851)",
+            1,
+            true
+        )
+    )
     assert(log.accesses[7].read == leaf_data)
     leaf_data = machine:read_memory(leaf_address, leaf_size)
     assert(leaf_data == make_leaf("\xaa", "\xbb", "\x33", "\x44"))
@@ -1481,7 +1492,14 @@ test_util.make_do_test(build_machine, machine_type, {
     machine:write_reg("uarch_x" .. t1, machine:read_reg("uarch_x" .. t1) + word_size)
     machine:write_reg("uarch_x" .. t0, 0xcccccccccccccccc)
     log, dump = log_step()
-    assert(dump:match("7: write memory@0x%x+%(%d+%): 0x3333333333333333%(%d+%) %-> 0xcccccccccccccccc%(%d+%)"))
+    assert(
+        dump:find(
+            "7: write uarch.ram@0x600030(6291504): 0x3333333333333333(3689348814741910323)"
+                .. " -> 0xcccccccccccccccc(14757395258967641292)",
+            1,
+            true
+        )
+    )
     assert(log.accesses[7].read == leaf_data)
     leaf_data = machine:read_memory(leaf_address, leaf_size)
     assert(leaf_data == make_leaf("\xaa", "\xbb", "\xcc", "\x44"))
@@ -1492,7 +1510,14 @@ test_util.make_do_test(build_machine, machine_type, {
     machine:write_reg("uarch_x" .. t1, machine:read_reg("uarch_x" .. t1) + word_size)
     machine:write_reg("uarch_x" .. t0, 0xdddddddddddddddd)
     log, dump = log_step()
-    assert(dump:match("7: write memory@0x%x+%(%d+%): 0x4444444444444444%(%d+%) %-> 0xdddddddddddddddd%(%d+%)"))
+    assert(
+        dump:find(
+            "7: write uarch.ram@0x600038(6291512): 0x4444444444444444(4919131752989213764)"
+                .. " -> 0xdddddddddddddddd(15987178197214944733)",
+            1,
+            true
+        )
+    )
     assert(log.accesses[7].read == leaf_data)
     leaf_data = machine:read_memory(leaf_address, leaf_size)
     assert(leaf_data == make_leaf("\xaa", "\xbb", "\xcc", "\xdd"))
@@ -1568,7 +1593,7 @@ test_util.make_do_test(build_machine, machine_type, { uarch = {} })("log_step sa
         machine:log_step(1, filename1)
     end)
     assert(not success)
-    assert(err:match("file already exists"))
+    check_error_find(err, "file already exists")
     -- delete file and confirm that machine is on same mcycle
     os.remove(filename1)
     assert(machine:read_reg("mcycle") == 0)
@@ -1588,11 +1613,11 @@ test_util.make_do_test(build_machine, machine_type, { uarch = {} })("log_step sa
     _, err = pcall(function()
         machine:verify_step(bad_hash, filename1, mcycle_count, root_hash_after)
     end)
-    assert(err:match("initial root hash mismatch"))
+    check_error_find(err, "initial root hash mismatch")
     _, err = pcall(function()
         machine:verify_step(root_hash_before, filename1, mcycle_count, bad_hash)
     end)
-    assert(err:match("final root hash mismatch"))
+    check_error_find(err, "final root hash mismatch")
     -- ensure that copy_step_log() works
     copy_step_log(filename1, filename2, function()
         -- copy original file without modifications
@@ -1605,7 +1630,7 @@ test_util.make_do_test(build_machine, machine_type, { uarch = {} })("log_step sa
     _, err = pcall(function()
         machine:verify_step(root_hash_before, filename2, mcycle_count, root_hash_after)
     end)
-    assert(err:match("initial root hash mismatch"))
+    check_error_find(err, "initial root hash mismatch")
     -- page indices not in ascending order should fail
     copy_step_log(filename1, filename2, function(log_data)
         log_data.pages[2].index = log_data.pages[1].index
@@ -1613,7 +1638,7 @@ test_util.make_do_test(build_machine, machine_type, { uarch = {} })("log_step sa
     _, err = pcall(function()
         machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
     end)
-    assert(err:match("invalid log format: page index is not in increasing order"))
+    check_error_find(err, "invalid log format: page index is not in increasing order")
     -- page scratch hash area not zeroed
     copy_step_log(filename1, filename2, function(log_data)
         log_data.pages[1].hash = string.rep("\1", 32)
@@ -1621,7 +1646,7 @@ test_util.make_do_test(build_machine, machine_type, { uarch = {} })("log_step sa
     _, err = pcall(function()
         machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
     end)
-    assert(err:match("invalid log format: page scratch hash area is not zero"))
+    check_error_find(err, "invalid log format: page scratch hash area is not zero")
     -- add one extra page
     copy_step_log(filename1, filename2, function(log_data)
         table.insert(log_data.pages, {
@@ -1633,7 +1658,7 @@ test_util.make_do_test(build_machine, machine_type, { uarch = {} })("log_step sa
     _, err = pcall(function()
         machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
     end)
-    assert(err:match("trying to access beyond sibling count while skipping range"))
+    check_error_find(err, "too many sibling hashes in log")
     -- remove one page
     copy_step_log(filename1, filename2, function(log_data)
         table.remove(log_data.pages)
@@ -1641,7 +1666,7 @@ test_util.make_do_test(build_machine, machine_type, { uarch = {} })("log_step sa
     _, err = pcall(function()
         machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
     end)
-    assert(err:match("initial root hash mismatch"))
+    check_error_find(err, "too many sibling hashes in log")
     -- override page count to zero
     copy_step_log(filename1, filename2, function(log_data)
         log_data.override_page_count = 0
@@ -1649,7 +1674,7 @@ test_util.make_do_test(build_machine, machine_type, { uarch = {} })("log_step sa
     _, err = pcall(function()
         machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
     end)
-    assert(err:match("page count is zero"))
+    check_error_find(err, "page count is zero")
     -- override page count to overflow
     copy_step_log(filename1, filename2, function(log_data)
         -- There is no UINT64_MAX in Lua, so we have to use the signed representation
@@ -1659,7 +1684,7 @@ test_util.make_do_test(build_machine, machine_type, { uarch = {} })("log_step sa
     _, err = pcall(function()
         machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
     end)
-    assert(err:match("page data past end of step log"))
+    check_error_find(err, "page data past end of step log")
     -- remove one sibling
     copy_step_log(filename1, filename2, function(log_data)
         table.remove(log_data.siblings)
@@ -1667,7 +1692,7 @@ test_util.make_do_test(build_machine, machine_type, { uarch = {} })("log_step sa
     _, err = pcall(function()
         machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
     end)
-    assert(err:match("trying to access beyond sibling count while skipping range"))
+    check_error_find(err, "too few sibling hashes in log")
     -- add an extra sibling
     copy_step_log(filename1, filename2, function(log_data)
         table.insert(log_data.siblings, bad_hash)
@@ -1675,7 +1700,7 @@ test_util.make_do_test(build_machine, machine_type, { uarch = {} })("log_step sa
     _, err = pcall(function()
         machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
     end)
-    assert(err:match("sibling hashes not totally consumed"))
+    check_error_find(err, "too many sibling hashes in log")
     -- modify one sibling hash
     copy_step_log(filename1, filename2, function(log_data)
         log_data.siblings[1] = bad_hash
@@ -1683,7 +1708,7 @@ test_util.make_do_test(build_machine, machine_type, { uarch = {} })("log_step sa
     _, err = pcall(function()
         machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
     end)
-    assert(err:match("initial root hash mismatch"))
+    check_error_find(err, "initial root hash mismatch")
     -- empty siblings
     copy_step_log(filename1, filename2, function(log_data)
         log_data.siblings = {}
@@ -1691,7 +1716,7 @@ test_util.make_do_test(build_machine, machine_type, { uarch = {} })("log_step sa
     _, err = pcall(function()
         machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
     end)
-    assert(err:match("compute_root_hash_impl: trying to access beyond sibling count while skipping range"))
+    check_error_find(err, "too few sibling hashes in log")
     -- override sibling count to overflow
     copy_step_log(filename1, filename2, function(log_data)
         log_data.override_sibling_count = 0xffffffff
@@ -1699,14 +1724,14 @@ test_util.make_do_test(build_machine, machine_type, { uarch = {} })("log_step sa
     _, err = pcall(function()
         machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
     end)
-    assert(err:match("sibling hashes past end of step log"))
+    check_error_find(err, "sibling hashes past end of step log")
     -- log_step should fail if uarch is not reset
     machine:run_uarch(1) -- advance 1 micro step 0< uarch is not reset
     os.remove(filename1)
     _, err = pcall(function()
         machine:log_step(1, filename1)
     end)
-    assert(err:match("microarchitecture is not reset"))
+    check_error_find(err, "microarchitecture is not reset")
     -- after uarch is reset, log_step should work
     machine:reset_uarch()
     status = machine:log_step(1, filename1)
diff --git a/tests/misc/test-machine-c-api.cpp b/tests/misc/test-machine-c-api.cpp
index 313eb0e3d..980d4d595 100644
--- a/tests/misc/test-machine-c-api.cpp
+++ b/tests/misc/test-machine-c-api.cpp
@@ -390,7 +390,7 @@ BOOST_AUTO_TEST_CASE_NOLINT(get_proof_null_machine_test) {
 BOOST_FIXTURE_TEST_CASE_NOLINT(get_proof_invalid_address_test, ordinary_machine_fixture) {
     const char *proof{};
     cm_error error_code = cm_get_proof(_machine, 1, 12, &proof);
-    BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
+    BOOST_CHECK_EQUAL(error_code, CM_ERROR_DOMAIN_ERROR);
 
     std::string result = cm_get_last_error_message();
     std::string origin("address not aligned to log2_size");
@@ -460,7 +460,7 @@ BOOST_AUTO_TEST_CASE_NOLINT(read_word_null_machine_test) {
 BOOST_FIXTURE_TEST_CASE_NOLINT(read_word_invalid_address_test, ordinary_machine_fixture) {
     uint64_t word_value = 0;
     cm_error error_code = cm_read_word(_machine, 0xffffffff, &word_value);
-    BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
+    BOOST_CHECK_EQUAL(error_code, CM_ERROR_DOMAIN_ERROR);
 
     std::string result = cm_get_last_error_message();
     std::string origin("address not aligned");
@@ -538,7 +538,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(write_memory_invalid_address_range_test, ordinary
     cm_error error_code = cm_write_memory(_machine, address, write_data.data(), write_data.size());
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
     std::string result = cm_get_last_error_message();
-    std::string origin("address range not entirely in memory PMA");
+    std::string origin("attempted write to device memory range");
     BOOST_CHECK_EQUAL(origin, result);
 }
 
@@ -631,7 +631,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(write_virtual_memory_invalid_address_range_test,
     cm_error error_code = cm_write_virtual_memory(_machine, address, write_data.data(), write_data.size());
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
     std::string result = cm_get_last_error_message();
-    std::string origin("address range not entirely in memory PMA");
+    std::string origin("attempted write to device memory range");
     BOOST_CHECK_EQUAL(origin, result);
 }
 
diff --git a/uarch/Makefile b/uarch/Makefile
index 392642d7c..273811c30 100644
--- a/uarch/Makefile
+++ b/uarch/Makefile
@@ -53,6 +53,7 @@ CFLAGS := -march=rv64i -mabi=lp64 -Wl,--gc-sections $(OPTFLAGS) $(UBFLAGS) $(WAR
 	-I. \
 	-I$(THIRD_PARTY_DIR)/llvm-flang-uint128 \
 	-I$(EMULATOR_SRC_DIR) \
+	$(UARCH_DEFS) \
 	$(TOOLCHAIN_INCS)
 
 CXXFLAGS := -std=c++20 -fno-rtti
@@ -60,6 +61,7 @@ CXXFLAGS := -std=c++20 -fno-rtti
 UARCH_SOURCES=\
 	uarch-printf.c \
 	uarch-run.cpp \
+	uarch-ecall.c \
 	uarch-runtime.cpp
 
 EMULATOR_SOURCES=\
@@ -79,6 +81,7 @@ COMPUTE_UARCH_CPP_SOURCES=\
 	$(EMULATOR_SRC_DIR)/pristine-merkle-tree.cpp \
 	$(EMULATOR_SRC_DIR)/complete-merkle-tree.cpp \
 	$(EMULATOR_SRC_DIR)/full-merkle-tree.cpp
+
 COMPUTE_UARCH_C_SOURCES=\
 	$(THIRD_PARTY_DIR)/tiny_sha3/sha3.c \
 	uarch-pristine-ram.c
diff --git a/uarch/machine-uarch-bridge-state-access.h b/uarch/machine-uarch-bridge-state-access.h
new file mode 100644
index 000000000..bf08fb53a
--- /dev/null
+++ b/uarch/machine-uarch-bridge-state-access.h
@@ -0,0 +1,507 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef MACHINE_UARCH_BRIDGE_STATE_ACCESS_H
+#define MACHINE_UARCH_BRIDGE_STATE_ACCESS_H
+
+#include "uarch-runtime.h" // must be included first, because of assert
+
+#include <optional>
+
+#include "compiler-defines.h"
+#include "device-state-access.h"
+#include "i-state-access.h"
+#include "machine-reg.h"
+#include "mock-pma-entry.h"
+#include "pma-constants.h"
+#include "riscv-constants.h"
+#include "shadow-pmas.h"
+#include "uarch-constants.h"
+#include "uarch-defines.h"
+#include "uarch-ecall.h"
+#include "uarch-strict-aliasing.h"
+
+#if DUMP_UARCH_STATE_ACCESS
+#include "scoped-note.h"
+#endif
+
+namespace cartesi {
+
+class machine_uarch_bridge_state_access;
+
+// Type trait that should return the pma_entry type for a state access class
+template <>
+struct i_state_access_pma_entry<machine_uarch_bridge_state_access> {
+    using type = mock_pma_entry;
+};
+// Type trait that should return the fast_addr type for a state access class
+template <>
+struct i_state_access_fast_addr<machine_uarch_bridge_state_access> {
+    using type = uint64_t;
+};
+
+// Provides access to the state of the big emulator from microcode
+class machine_uarch_bridge_state_access : public i_state_access<machine_uarch_bridge_state_access> {
+
+    //NOLINTNEXTLINE(cppcoreguidelines-avoid-const-or-ref-data-members)
+    std::array<std::optional<mock_pma_entry>, PMA_MAX> &m_pmas;
+
+public:
+    machine_uarch_bridge_state_access(std::array<std::optional<mock_pma_entry>, PMA_MAX> &pmas): m_pmas(pmas) {}
+    machine_uarch_bridge_state_access(const machine_uarch_bridge_state_access &other) = default;
+    machine_uarch_bridge_state_access(machine_uarch_bridge_state_access &&other) = default;
+    machine_uarch_bridge_state_access &operator=(const machine_uarch_bridge_state_access &other) = delete;
+    machine_uarch_bridge_state_access &operator=(machine_uarch_bridge_state_access &&other) = delete;
+    ~machine_uarch_bridge_state_access() = default;
+
+private:
+    friend i_state_access<machine_uarch_bridge_state_access>;
+
+#ifdef DUMP_UARCH_STATE_ACCESS
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    auto do_make_scoped_note([[maybe_unused]] const char *text) {
+        return scoped_note<machine_uarch_bridge_state_access>{*this, text};
+    }
+#endif
+
+    uint64_t bridge_read_reg(machine_reg reg) {
+        return ua_aliased_aligned_read<uint64_t>(machine_reg_address(reg));
+    }
+
+    void bridge_write_reg(machine_reg reg, uint64_t val) {
+        ua_aliased_aligned_write<uint64_t>(machine_reg_address(reg), val);
+    }
+
+    uint64_t do_read_x(int i) {
+        return bridge_read_reg(machine_reg_enum(machine_reg::x0, i));
+    }
+
+    void do_write_x(int i, uint64_t val) {
+        bridge_write_reg(machine_reg_enum(machine_reg::x0, i), val);
+    }
+
+    uint64_t do_read_f(int i) {
+        return bridge_read_reg(machine_reg_enum(machine_reg::f0, i));
+    }
+
+    void do_write_f(int i, uint64_t val) {
+        bridge_write_reg(machine_reg_enum(machine_reg::f0, i), val);
+    }
+
+    uint64_t do_read_pc() {
+        return bridge_read_reg(machine_reg::pc);
+    }
+
+    void do_write_pc(uint64_t val) {
+        bridge_write_reg(machine_reg::pc, val);
+    }
+
+    uint64_t do_read_fcsr() {
+        return bridge_read_reg(machine_reg::fcsr);
+    }
+
+    void do_write_fcsr(uint64_t val) {
+        bridge_write_reg(machine_reg::fcsr, val);
+    }
+
+    uint64_t do_read_icycleinstret() {
+        return bridge_read_reg(machine_reg::icycleinstret);
+    }
+
+    void do_write_icycleinstret(uint64_t val) {
+        bridge_write_reg(machine_reg::icycleinstret, val);
+    }
+
+    uint64_t do_read_mvendorid() {
+        return bridge_read_reg(machine_reg::mvendorid);
+    }
+
+    uint64_t do_read_marchid() {
+        return bridge_read_reg(machine_reg::marchid);
+    }
+
+    uint64_t do_read_mimpid() {
+        return bridge_read_reg(machine_reg::mimpid);
+    }
+
+    uint64_t do_read_mcycle() {
+        return bridge_read_reg(machine_reg::mcycle);
+    }
+
+    void do_write_mcycle(uint64_t val) {
+        bridge_write_reg(machine_reg::mcycle, val);
+    }
+
+    uint64_t do_read_mstatus() {
+        return bridge_read_reg(machine_reg::mstatus);
+    }
+
+    void do_write_mstatus(uint64_t val) {
+        bridge_write_reg(machine_reg::mstatus, val);
+    }
+
+    uint64_t do_read_mtvec() {
+        return bridge_read_reg(machine_reg::mtvec);
+    }
+
+    void do_write_mtvec(uint64_t val) {
+        bridge_write_reg(machine_reg::mtvec, val);
+    }
+
+    uint64_t do_read_mscratch() {
+        return bridge_read_reg(machine_reg::mscratch);
+    }
+
+    void do_write_mscratch(uint64_t val) {
+        bridge_write_reg(machine_reg::mscratch, val);
+    }
+
+    uint64_t do_read_mepc() {
+        return bridge_read_reg(machine_reg::mepc);
+    }
+
+    void do_write_mepc(uint64_t val) {
+        bridge_write_reg(machine_reg::mepc, val);
+    }
+
+    uint64_t do_read_mcause() {
+        return bridge_read_reg(machine_reg::mcause);
+    }
+
+    void do_write_mcause(uint64_t val) {
+        bridge_write_reg(machine_reg::mcause, val);
+    }
+
+    uint64_t do_read_mtval() {
+        return bridge_read_reg(machine_reg::mtval);
+    }
+
+    void do_write_mtval(uint64_t val) {
+        bridge_write_reg(machine_reg::mtval, val);
+    }
+
+    uint64_t do_read_misa() {
+        return bridge_read_reg(machine_reg::misa);
+    }
+
+    void do_write_misa(uint64_t val) {
+        bridge_write_reg(machine_reg::misa, val);
+    }
+
+    uint64_t do_read_mie() {
+        return bridge_read_reg(machine_reg::mie);
+    }
+
+    void do_write_mie(uint64_t val) {
+        bridge_write_reg(machine_reg::mie, val);
+    }
+
+    uint64_t do_read_mip() {
+        return bridge_read_reg(machine_reg::mip);
+    }
+
+    void do_write_mip(uint64_t val) {
+        bridge_write_reg(machine_reg::mip, val);
+    }
+
+    uint64_t do_read_medeleg() {
+        return bridge_read_reg(machine_reg::medeleg);
+    }
+
+    void do_write_medeleg(uint64_t val) {
+        bridge_write_reg(machine_reg::medeleg, val);
+    }
+
+    uint64_t do_read_mideleg() {
+        return bridge_read_reg(machine_reg::mideleg);
+    }
+
+    void do_write_mideleg(uint64_t val) {
+        bridge_write_reg(machine_reg::mideleg, val);
+    }
+
+    uint64_t do_read_mcounteren() {
+        return bridge_read_reg(machine_reg::mcounteren);
+    }
+
+    void do_write_mcounteren(uint64_t val) {
+        bridge_write_reg(machine_reg::mcounteren, val);
+    }
+
+    uint64_t do_read_senvcfg() {
+        return bridge_read_reg(machine_reg::senvcfg);
+    }
+
+    void do_write_senvcfg(uint64_t val) {
+        bridge_write_reg(machine_reg::senvcfg, val);
+    }
+
+    uint64_t do_read_menvcfg() {
+        return bridge_read_reg(machine_reg::menvcfg);
+    }
+
+    void do_write_menvcfg(uint64_t val) {
+        bridge_write_reg(machine_reg::menvcfg, val);
+    }
+
+    uint64_t do_read_stvec() {
+        return bridge_read_reg(machine_reg::stvec);
+    }
+
+    void do_write_stvec(uint64_t val) {
+        bridge_write_reg(machine_reg::stvec, val);
+    }
+
+    uint64_t do_read_sscratch() {
+        return bridge_read_reg(machine_reg::sscratch);
+    }
+
+    void do_write_sscratch(uint64_t val) {
+        bridge_write_reg(machine_reg::sscratch, val);
+    }
+
+    uint64_t do_read_sepc() {
+        return bridge_read_reg(machine_reg::sepc);
+    }
+
+    void do_write_sepc(uint64_t val) {
+        bridge_write_reg(machine_reg::sepc, val);
+    }
+
+    uint64_t do_read_scause() {
+        return bridge_read_reg(machine_reg::scause);
+    }
+
+    void do_write_scause(uint64_t val) {
+        bridge_write_reg(machine_reg::scause, val);
+    }
+
+    uint64_t do_read_stval() {
+        return bridge_read_reg(machine_reg::stval);
+    }
+
+    void do_write_stval(uint64_t val) {
+        bridge_write_reg(machine_reg::stval, val);
+    }
+
+    uint64_t do_read_satp() {
+        return bridge_read_reg(machine_reg::satp);
+    }
+
+    void do_write_satp(uint64_t val) {
+        bridge_write_reg(machine_reg::satp, val);
+    }
+
+    uint64_t do_read_scounteren() {
+        return bridge_read_reg(machine_reg::scounteren);
+    }
+
+    void do_write_scounteren(uint64_t val) {
+        bridge_write_reg(machine_reg::scounteren, val);
+    }
+
+    uint64_t do_read_ilrsc() {
+        return bridge_read_reg(machine_reg::ilrsc);
+    }
+
+    void do_write_ilrsc(uint64_t val) {
+        bridge_write_reg(machine_reg::ilrsc, val);
+    }
+
+    uint64_t do_read_iprv() {
+        return bridge_read_reg(machine_reg::iprv);
+    }
+
+    void do_write_iprv(uint64_t val) {
+        bridge_write_reg(machine_reg::iprv, val);
+    }
+
+    uint64_t do_read_iflags_X() {
+        return bridge_read_reg(machine_reg::iflags_X);
+    }
+
+    void do_write_iflags_X(uint64_t val) {
+        bridge_write_reg(machine_reg::iflags_X, val);
+    }
+
+    uint64_t do_read_iflags_Y() {
+        return bridge_read_reg(machine_reg::iflags_Y);
+    }
+
+    void do_write_iflags_Y(uint64_t val) {
+        bridge_write_reg(machine_reg::iflags_Y, val);
+    }
+
+    uint64_t do_read_iflags_H() {
+        return bridge_read_reg(machine_reg::iflags_H);
+    }
+
+    void do_write_iflags_H(uint64_t val) {
+        bridge_write_reg(machine_reg::iflags_H, val);
+    }
+
+    uint64_t do_read_iunrep() {
+        return bridge_read_reg(machine_reg::iunrep);
+    }
+
+    void do_write_iunrep(uint64_t val) {
+        bridge_write_reg(machine_reg::iunrep, val);
+    }
+
+    uint64_t do_read_clint_mtimecmp() {
+        return bridge_read_reg(machine_reg::clint_mtimecmp);
+    }
+
+    void do_write_clint_mtimecmp(uint64_t val) {
+        bridge_write_reg(machine_reg::clint_mtimecmp, val);
+    }
+
+    uint64_t do_read_plic_girqpend() {
+        return bridge_read_reg(machine_reg::plic_girqpend);
+    }
+
+    void do_write_plic_girqpend(uint64_t val) {
+        bridge_write_reg(machine_reg::plic_girqpend, val);
+    }
+
+    uint64_t do_read_plic_girqsrvd() {
+        return bridge_read_reg(machine_reg::plic_girqsrvd);
+    }
+
+    void do_write_plic_girqsrvd(uint64_t val) {
+        bridge_write_reg(machine_reg::plic_girqsrvd, val);
+    }
+
+    uint64_t do_read_htif_fromhost() {
+        return bridge_read_reg(machine_reg::htif_fromhost);
+    }
+
+    void do_write_htif_fromhost(uint64_t val) {
+        bridge_write_reg(machine_reg::htif_fromhost, val);
+    }
+
+    uint64_t do_read_htif_tohost() {
+        return bridge_read_reg(machine_reg::htif_tohost);
+    }
+
+    void do_write_htif_tohost(uint64_t val) {
+        bridge_write_reg(machine_reg::htif_tohost, val);
+    }
+
+    uint64_t do_read_htif_ihalt() {
+        return bridge_read_reg(machine_reg::htif_ihalt);
+    }
+
+    uint64_t do_read_htif_iconsole() {
+        return bridge_read_reg(machine_reg::htif_iconsole);
+    }
+
+    uint64_t do_read_htif_iyield() {
+        return bridge_read_reg(machine_reg::htif_iyield);
+    }
+
+    std::pair<uint64_t, bool> do_poll_external_interrupts(uint64_t mcycle, uint64_t /*mcycle_max*/) {
+        return {mcycle, false};
+    }
+
+    template <typename T, typename A>
+    void do_read_memory_word(uint64_t paddr, uint64_t /* pma_index */, T *pval) {
+        *pval = ua_aliased_aligned_read<T, A>(paddr);
+    }
+
+    template <typename T, typename A>
+    void do_write_memory_word(uint64_t paddr, uint64_t /* pma_index */, T val) {
+        ua_aliased_aligned_write<T, A>(paddr, val);
+    }
+
+    bool do_read_memory(uint64_t /*paddr*/, unsigned char * /*data*/, uint64_t /*length*/) {
+        // This is not implemented yet because it's not being used
+        abort();
+        return false;
+    }
+
+    bool do_write_memory(uint64_t /*paddr*/, const unsigned char * /*data*/, uint64_t /*length*/) {
+        // This is not implemented yet because it's not being used
+        abort();
+        return false;
+    }
+
+    uint64_t read_pma_istart(int i) {
+        return ua_aliased_aligned_read<uint64_t>(shadow_pmas_get_pma_abs_addr(i, shadow_pmas_what::istart));
+    }
+
+    uint64_t read_pma_ilength(int i) {
+        return ua_aliased_aligned_read<uint64_t>(shadow_pmas_get_pma_abs_addr(i, shadow_pmas_what::ilength));
+    }
+
+    mock_pma_entry &do_read_pma_entry(uint64_t index) {
+        const uint64_t istart = read_pma_istart(index);
+        const uint64_t ilength = read_pma_ilength(index);
+        // NOLINTNEXTLINE(bugprone-narrowing-conversions)
+        int i = static_cast<int>(index);
+        if (!m_pmas[i]) {
+            m_pmas[i] = make_mock_pma_entry(index, istart, ilength, [](const char * /*err*/) { abort(); });
+        }
+        // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
+        return m_pmas[i].value();
+    }
+
+    uint64_t do_get_faddr(uint64_t paddr, uint64_t /* pma_index */) const {
+        return paddr;
+    }
+
+    uint64_t bridge_read_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, shadow_tlb_what what) {
+        return ua_aliased_aligned_read<uint64_t>(shadow_tlb_get_abs_addr(set_index, slot_index, what));
+    }
+
+    template <TLB_set_index SET>
+    uint64_t do_read_tlb_vaddr_page(uint64_t slot_index) {
+        return bridge_read_shadow_tlb(SET, slot_index, shadow_tlb_what::vaddr_page);
+    }
+
+    template <TLB_set_index SET>
+    uint64_t do_read_tlb_vp_offset(uint64_t slot_index) {
+        return bridge_read_shadow_tlb(SET, slot_index, shadow_tlb_what::vp_offset);
+    }
+
+    template <TLB_set_index SET>
+    uint64_t do_read_tlb_pma_index(uint64_t slot_index) {
+        return bridge_read_shadow_tlb(SET, slot_index, shadow_tlb_what::pma_index);
+    }
+
+    template <TLB_set_index SET>
+    void do_write_tlb(uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset, uint64_t pma_index) {
+        ua_write_tlb_ECALL(SET, slot_index, vaddr_page, vp_offset, pma_index);
+    }
+
+    void do_putchar(uint8_t c) {
+        ua_putchar_ECALL(c);
+    }
+
+    void do_mark_dirty_page(uint64_t paddr, uint64_t pma_index) {
+        ua_mark_dirty_page_ECALL(paddr, pma_index);
+    }
+
+    constexpr const char *do_get_name() const { // NOLINT(readability-convert-member-functions-to-static)
+        return "machine_uarch_bridge_state_access";
+    }
+
+    // NOLINTEND(readability-convert-member-functions-to-static)
+};
+
+} // namespace cartesi
+
+#endif
diff --git a/uarch/uarch-ecall.c b/uarch/uarch-ecall.c
new file mode 100644
index 000000000..33dc8790c
--- /dev/null
+++ b/uarch/uarch-ecall.c
@@ -0,0 +1,73 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#include "uarch-ecall.h"
+#include "compiler-defines.h"
+#include "uarch-defines.h"
+
+#include <stddef.h>
+#include <stdint.h>
+
+void ua_halt_ECALL() {
+    // NOLINTNEXTLINE(hicpp-no-assembler)
+    asm volatile("mv a7, %0\n"
+                 "ecall\n"
+                 : // no output
+                 : "r"(UARCH_ECALL_FN_HALT_DEF)
+                 : "a7" // modified registers
+    );
+}
+
+void ua_putchar_ECALL(uint8_t c) {
+    // NOLINTNEXTLINE(hicpp-no-assembler)
+    asm volatile("mv a7, %0\n"
+                 "mv a0, %1\n"
+                 "ecall\n"
+                 : // no output
+                 : "r"(UARCH_ECALL_FN_PUTCHAR_DEF),
+                 "r"(c)       // character to print
+                 : "a7", "a0" // clobbered registers
+    );
+}
+
+void ua_mark_dirty_page_ECALL(uint64_t paddr, uint64_t pma_index) {
+    // NOLINTNEXTLINE(hicpp-no-assembler)
+    asm volatile("mv a7, %0\n"
+                 "mv a0, %1\n"
+                 "mv a1, %2\n"
+                 "ecall\n"
+                 : // no output
+                 : "r"(UARCH_ECALL_FN_MARK_DIRTY_PAGE_DEF), "r"(paddr), "r"(pma_index)
+                 : "a7", "a0", "a1" // clobbered registers
+    );
+}
+
+void ua_write_tlb_ECALL(uint64_t use, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset,
+    uint64_t pma_index) {
+    // NOLINTNEXTLINE(hicpp-no-assembler)
+    asm volatile("mv a7, %0\n"
+                 "mv a0, %1\n"
+                 "mv a1, %2\n"
+                 "mv a2, %3\n"
+                 "mv a3, %4\n"
+                 "mv a4, %5\n"
+                 "ecall\n"
+                 : // no output
+                 : "r"(UARCH_ECALL_FN_WRITE_TLB_DEF), "r"(use), "r"(slot_index),
+                 "r"(vaddr_page), "r"(vp_offset), "r"(pma_index)
+                 : "a7", "a0", "a1", "a2", "a3", "a4" // clobbered registers
+    );
+}
diff --git a/uarch/uarch-ecall.h b/uarch/uarch-ecall.h
new file mode 100644
index 000000000..08bdc27af
--- /dev/null
+++ b/uarch/uarch-ecall.h
@@ -0,0 +1,36 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef UARCH_ECALL_H
+#define UARCH_ECALL_H
+
+#ifdef __cplusplus
+#include <cstdint>
+extern "C" {
+#else
+#include <stdint.h>
+#endif
+
+void ua_halt_ECALL();
+void ua_putchar_ECALL(uint8_t c);
+void ua_mark_dirty_page_ECALL(uint64_t paddr, uint64_t pma_index);
+void ua_write_tlb_ECALL(uint64_t use, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset, uint64_t pma_index);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif
diff --git a/uarch/uarch-machine-state-access.h b/uarch/uarch-machine-state-access.h
deleted file mode 100644
index 6d21dae88..000000000
--- a/uarch/uarch-machine-state-access.h
+++ /dev/null
@@ -1,586 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef UARCH_MACHINE_STATE_ACCESS_H
-#define UARCH_MACHINE_STATE_ACCESS_H
-
-#include "uarch-runtime.h" // must be included first, because of assert
-
-#define MOCK_THROW_RUNTIME_ERROR(err) abort()
-#include "compiler-defines.h"
-#include "device-state-access.h"
-#include "i-state-access.h"
-#include "machine-reg.h"
-#include "mock-pma-entry.h"
-#include "pma-constants.h"
-#include "riscv-constants.h"
-#include "shadow-pmas.h"
-#include "strict-aliasing.h"
-#include "uarch-constants.h"
-#include "uarch-defines.h"
-#include <optional>
-
-namespace cartesi {
-
-template <typename T>
-static T raw_read_memory(uint64_t paddr) {
-    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast,performance-no-int-to-ptr)
-    volatile T *p = reinterpret_cast<T *>(paddr);
-    return *p;
-}
-
-template <typename T>
-static void raw_write_memory(uint64_t paddr, T val) {
-    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast,performance-no-int-to-ptr)
-    volatile T *p = reinterpret_cast<T *>(paddr);
-    *p = val;
-}
-
-// Provides access to the state of the big emulator from microcode
-class uarch_machine_state_access : public i_state_access<uarch_machine_state_access, mock_pma_entry> {
-    std::array<std::optional<mock_pma_entry>, PMA_MAX> m_pmas;
-
-public:
-    explicit uarch_machine_state_access(std::array<std::optional<uarch_pma_entry>, PMA_MAX>& pmas) : m_pmas(pmas) {}
-    uarch_machine_state_access(const uarch_machine_state_access &other) = default;
-    uarch_machine_state_access(uarch_machine_state_access &&other) = default;
-    uarch_machine_state_access &operator=(const uarch_machine_state_access &other) = delete;
-    uarch_machine_state_access &operator=(uarch_machine_state_access &&other) = delete;
-    ~uarch_machine_state_access() = default;
-
-private:
-    friend i_state_access<uarch_machine_state_access, mock_pma_entry>;
-
-    // NOLINTBEGIN(readability-convert-member-functions-to-static)
-
-    void do_push_bracket(bracket_type /*type*/, const char * /*text*/) {}
-
-    int do_make_scoped_note(const char * /*text*/) {
-        return 0;
-    }
-
-    uint64_t do_read_x(int reg) {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::x0, reg));
-    }
-
-    void do_write_x(int reg, uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::x0, reg), val);
-    }
-
-    uint64_t do_read_f(int reg) {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::f0, reg));
-    }
-
-    void do_write_f(int reg, uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::f0, reg), val);
-    }
-
-    uint64_t do_read_pc() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::pc));
-    }
-
-    void do_write_pc(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::pc), val);
-    }
-
-    uint64_t do_read_fcsr() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::fcsr));
-    }
-
-    void do_write_fcsr(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::fcsr), val);
-    }
-
-    uint64_t do_read_icycleinstret() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::icycleinstret));
-    }
-
-    void do_write_icycleinstret(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::icycleinstret), val);
-    }
-
-    uint64_t do_read_mvendorid() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::mvendorid));
-    }
-
-    uint64_t do_read_marchid() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::marchid));
-    }
-
-    uint64_t do_read_mimpid() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::mimpid));
-    }
-
-    uint64_t do_read_mcycle() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::mcycle));
-    }
-
-    void do_write_mcycle(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::mcycle), val);
-    }
-
-    uint64_t do_read_mstatus() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::mstatus));
-    }
-
-    void do_write_mstatus(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::mstatus), val);
-    }
-
-    uint64_t do_read_mtvec() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::mtvec));
-    }
-
-    void do_write_mtvec(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::mtvec), val);
-    }
-
-    uint64_t do_read_mscratch() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::mscratch));
-    }
-
-    void do_write_mscratch(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::mscratch), val);
-    }
-
-    uint64_t do_read_mepc() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::mepc));
-    }
-
-    void do_write_mepc(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::mepc), val);
-    }
-
-    uint64_t do_read_mcause() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::mcause));
-    }
-
-    void do_write_mcause(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::mcause), val);
-    }
-
-    uint64_t do_read_mtval() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::mtval));
-    }
-
-    void do_write_mtval(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::mtval), val);
-    }
-
-    uint64_t do_read_misa() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::misa));
-    }
-
-    void do_write_misa(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::misa), val);
-    }
-
-    uint64_t do_read_mie() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::mie));
-    }
-
-    void do_write_mie(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::mie), val);
-    }
-
-    uint64_t do_read_mip() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::mip));
-    }
-
-    void do_write_mip(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::mip), val);
-    }
-
-    uint64_t do_read_medeleg() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::medeleg));
-    }
-
-    void do_write_medeleg(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::medeleg), val);
-    }
-
-    uint64_t do_read_mideleg() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::mideleg));
-    }
-
-    void do_write_mideleg(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::mideleg), val);
-    }
-
-    uint64_t do_read_mcounteren() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::mcounteren));
-    }
-
-    void do_write_mcounteren(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::mcounteren), val);
-    }
-
-    uint64_t do_read_senvcfg() const {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::senvcfg));
-    }
-
-    void do_write_senvcfg(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::senvcfg), val);
-    }
-
-    uint64_t do_read_menvcfg() const {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::menvcfg));
-    }
-
-    void do_write_menvcfg(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::menvcfg), val);
-    }
-
-    uint64_t do_read_stvec() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::stvec));
-    }
-
-    void do_write_stvec(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::stvec), val);
-    }
-
-    uint64_t do_read_sscratch() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::sscratch));
-    }
-
-    void do_write_sscratch(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::sscratch), val);
-    }
-
-    uint64_t do_read_sepc() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::sepc));
-    }
-
-    void do_write_sepc(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::sepc), val);
-    }
-
-    uint64_t do_read_scause() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::scause));
-    }
-
-    void do_write_scause(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::scause), val);
-    }
-
-    uint64_t do_read_stval() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::stval));
-    }
-
-    void do_write_stval(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::stval), val);
-    }
-
-    uint64_t do_read_satp() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::satp));
-    }
-
-    void do_write_satp(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::satp), val);
-    }
-
-    uint64_t do_read_scounteren() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::scounteren));
-    }
-
-    void do_write_scounteren(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::scounteren), val);
-    }
-
-    uint64_t do_read_ilrsc() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::ilrsc));
-    }
-
-    void do_write_ilrsc(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::ilrsc), val);
-    }
-
-    uint64_t do_read_iprv() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::iprv));
-    }
-
-    void do_write_iprv(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::iprv), val);
-    }
-
-    uint64_t do_read_iflags_X() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::iflags_X));
-    }
-
-    void do_write_iflags_X(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::iflags_X), val);
-    }
-
-    uint64_t do_read_iflags_Y() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::iflags_Y));
-    }
-
-    void do_write_iflags_Y(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::iflags_Y), val);
-    }
-
-    uint64_t do_read_iflags_H() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::iflags_H));
-    }
-
-    void do_write_iflags_H(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::iflags_H), val);
-    }
-
-    uint64_t do_read_iunrep() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::iunrep));
-    }
-
-    void do_write_iunrep(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::iunrep), val);
-    }
-
-    uint64_t do_read_clint_mtimecmp() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::clint_mtimecmp));
-    }
-
-    void do_write_clint_mtimecmp(uint64_t val) {
-        raw_write_memory<uint64_t>(machine_reg_address(machine_reg::clint_mtimecmp), val);
-    }
-
-    uint64_t do_read_plic_girqpend() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::plic_girqpend));
-    }
-
-    void do_write_plic_girqpend(uint64_t val) {
-        raw_write_memory<uint64_t>(machine_reg_address(machine_reg::plic_girqpend), val);
-    }
-
-    uint64_t do_read_plic_girqsrvd() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::plic_girqsrvd));
-    }
-
-    void do_write_plic_girqsrvd(uint64_t val) {
-        raw_write_memory<uint64_t>(machine_reg_address(machine_reg::plic_girqsrvd), val);
-    }
-
-    uint64_t do_read_htif_fromhost() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::htif_fromhost));
-    }
-
-    void do_write_htif_fromhost(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::htif_fromhost), val);
-    }
-
-    uint64_t do_read_htif_tohost() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::htif_tohost));
-    }
-
-    void do_write_htif_tohost(uint64_t val) {
-        raw_write_memory(machine_reg_address(machine_reg::htif_tohost), val);
-    }
-
-    uint64_t do_read_htif_ihalt() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::htif_ihalt));
-    }
-
-    uint64_t do_read_htif_iconsole() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::htif_iconsole));
-    }
-
-    uint64_t do_read_htif_iyield() {
-        return raw_read_memory<uint64_t>(machine_reg_address(machine_reg::htif_iyield));
-    }
-
-    std::pair<uint64_t, bool> do_poll_external_interrupts(uint64_t mcycle, uint64_t /*mcycle_max*/) {
-        return {mcycle, false};
-    }
-
-    uint64_t read_pma_istart(uint64_t i) {
-        return raw_read_memory<uint64_t>(shadow_pmas_get_pma_abs_addr(i));
-    }
-
-    uint64_t read_pma_ilength(uint64_t i) {
-        return raw_read_memory<uint64_t>(shadow_pmas_get_pma_abs_addr(i) + sizeof(uint64_t));
-    }
-
-    template <typename T>
-    void do_read_memory_word(uint64_t paddr, const unsigned char * /*hpage*/, uint64_t /*hoffset*/, T *pval) {
-        *pval = raw_read_memory<T>(paddr);
-    }
-
-    bool do_read_memory(uint64_t /*paddr*/, unsigned char * /*data*/, uint64_t /*length*/) {
-        // This is not implemented yet because it's not being used
-        abort();
-        return false;
-    }
-
-    bool do_write_memory(uint64_t /*paddr*/, const unsigned char * /*data*/, uint64_t /*length*/) {
-        // This is not implemented yet because it's not being used
-        abort();
-        return false;
-    }
-
-    template <typename T>
-    void do_write_memory_word(uint64_t paddr, const unsigned char * /*hpage*/, uint64_t /*hoffset*/, T val) {
-        raw_write_memory(paddr, val);
-    }
-
-    mock_pma_entry &do_read_pma_entry(uint64_t index) {
-        const uint64_t istart = read_pma_istart(index);
-        const uint64_t ilength = read_pma_ilength(index);
-        // NOLINTNEXTLINE(bugprone-narrowing-conversions)
-        int i = static_cast<int>(index);
-        if (!m_pmas[i]) {
-            m_pmas[i] = make_mock_pma_entry(index, istart, ilength, [](const char * /*err*/) { abort(); });
-        }
-        // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
-        return m_pmas[index].value();
-    }
-
-    unsigned char *do_get_host_memory(mock_pma_entry & /*pma*/) {
-        return nullptr;
-    }
-
-    template <TLB_entry_type ETYPE>
-    volatile tlb_hot_entry &do_get_tlb_hot_entry(uint64_t eidx) {
-        // Volatile is used, so the compiler does not optimize out, or do of order writes.
-        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast,performance-no-int-to-ptr)
-        volatile tlb_hot_entry *tlbe = reinterpret_cast<tlb_hot_entry *>(tlb_get_entry_hot_abs_addr<ETYPE>(eidx));
-        return *tlbe;
-    }
-
-    template <TLB_entry_type ETYPE>
-    volatile tlb_cold_entry &do_get_tlb_entry_cold(uint64_t eidx) {
-        // Volatile is used, so the compiler does not optimize out, or do of order writes.
-        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast,performance-no-int-to-ptr)
-        volatile tlb_cold_entry *tlbe = reinterpret_cast<tlb_cold_entry *>(tlb_get_entry_cold_abs_addr<ETYPE>(eidx));
-        return *tlbe;
-    }
-
-    template <TLB_entry_type ETYPE, typename T>
-    bool do_translate_vaddr_via_tlb(uint64_t vaddr, unsigned char **phptr) {
-        uint64_t eidx = tlb_get_entry_index(vaddr);
-        const volatile tlb_hot_entry &tlbhe = do_get_tlb_hot_entry<ETYPE>(eidx);
-        if (tlb_is_hit<T>(tlbhe.vaddr_page, vaddr)) {
-            const uint64_t poffset = vaddr & PAGE_OFFSET_MASK;
-            const volatile tlb_cold_entry &tlbce = do_get_tlb_entry_cold<ETYPE>(eidx);
-            *phptr = cast_addr_to_ptr<unsigned char *>(tlbce.paddr_page + poffset);
-            return true;
-        }
-        return false;
-    }
-
-    template <TLB_entry_type ETYPE, typename T>
-    bool do_read_memory_word_via_tlb(uint64_t vaddr, T *pval) {
-        uint64_t eidx = tlb_get_entry_index(vaddr);
-        const volatile tlb_hot_entry &tlbhe = do_get_tlb_hot_entry<ETYPE>(eidx);
-        if (tlb_is_hit<T>(tlbhe.vaddr_page, vaddr)) {
-            const uint64_t poffset = vaddr & PAGE_OFFSET_MASK;
-            const volatile tlb_cold_entry &tlbce = do_get_tlb_entry_cold<ETYPE>(eidx);
-            *pval = raw_read_memory<T>(tlbce.paddr_page + poffset);
-            return true;
-        }
-        return false;
-    }
-
-    template <TLB_entry_type ETYPE, typename T>
-    bool do_write_memory_word_via_tlb(uint64_t vaddr, T val) {
-        uint64_t eidx = tlb_get_entry_index(vaddr);
-        volatile tlb_hot_entry &tlbhe = do_get_tlb_hot_entry<ETYPE>(eidx);
-        if (tlb_is_hit<T>(tlbhe.vaddr_page, vaddr)) {
-            const uint64_t poffset = vaddr & PAGE_OFFSET_MASK;
-            const volatile tlb_cold_entry &tlbce = do_get_tlb_entry_cold<ETYPE>(eidx);
-            raw_write_memory(tlbce.paddr_page + poffset, val);
-            return true;
-        }
-        return false;
-    }
-
-    template <TLB_entry_type ETYPE>
-    unsigned char *do_replace_tlb_entry(uint64_t vaddr, uint64_t paddr, mock_pma_entry &pma) {
-        uint64_t eidx = tlb_get_entry_index(vaddr);
-        volatile tlb_cold_entry &tlbce = do_get_tlb_entry_cold<ETYPE>(eidx);
-        volatile tlb_hot_entry &tlbhe = do_get_tlb_hot_entry<ETYPE>(eidx);
-        // Mark page that was on TLB as dirty so we know to update the Merkle tree
-        if constexpr (ETYPE == TLB_WRITE) {
-            if (tlbhe.vaddr_page != TLB_INVALID_PAGE) {
-                mock_pma_entry &pma = do_read_pma_entry(tlbce.pma_index);
-                pma.mark_dirty_page(tlbce.paddr_page - pma.get_start());
-            }
-        }
-        const uint64_t vaddr_page = vaddr & ~PAGE_OFFSET_MASK;
-        const uint64_t paddr_page = paddr & ~PAGE_OFFSET_MASK;
-        // Both pma_index and paddr_page MUST BE written while its state is invalidated,
-        // otherwise TLB entry may be read in an incomplete state when computing root hash
-        // while stepping over this function.
-        // To do this we first invalidate TLB state before these fields are written to "lock",
-        // and "unlock" by writing a valid vaddr_page.
-        tlbhe.vaddr_page = TLB_INVALID_PAGE; // "lock", DO NOT OPTIMIZE OUT THIS LINE
-        tlbce.pma_index = pma.get_index();
-        tlbce.paddr_page = paddr_page;
-        // The write to vaddr_page MUST BE the last TLB entry write.
-        tlbhe.vaddr_page = vaddr_page; // "unlock"
-        // Note that we can't write here the correct vh_offset value, because it depends in a host pointer,
-        // however the uarch memory bridge will take care of updating it.
-        return cast_addr_to_ptr<unsigned char *>(paddr_page);
-    }
-
-    template <TLB_entry_type ETYPE>
-    void do_flush_tlb_entry(uint64_t eidx) {
-        volatile tlb_hot_entry &tlbhe = do_get_tlb_hot_entry<ETYPE>(eidx);
-        // Mark page that was on TLB as dirty so we know to update the Merkle tree
-        if constexpr (ETYPE == TLB_WRITE) {
-            if (tlbhe.vaddr_page != TLB_INVALID_PAGE) {
-                tlbhe.vaddr_page = TLB_INVALID_PAGE;
-                const volatile tlb_cold_entry &tlbce = do_get_tlb_entry_cold<ETYPE>(eidx);
-                mock_pma_entry &pma = do_read_pma_entry(tlbce.pma_index);
-                pma.mark_dirty_page(tlbce.paddr_page - pma.get_start());
-            } else {
-                tlbhe.vaddr_page = TLB_INVALID_PAGE;
-            }
-        } else {
-            tlbhe.vaddr_page = TLB_INVALID_PAGE;
-        }
-    }
-
-    template <TLB_entry_type ETYPE>
-    void do_flush_tlb_type() {
-        for (uint64_t i = 0; i < PMA_TLB_SIZE; ++i) {
-            do_flush_tlb_entry<ETYPE>(i);
-        }
-    }
-
-    void do_flush_tlb_vaddr(uint64_t /*vaddr*/) {
-        do_flush_tlb_type<TLB_CODE>();
-        do_flush_tlb_type<TLB_READ>();
-        do_flush_tlb_type<TLB_WRITE>();
-    }
-
-    bool do_get_soft_yield() {
-        // Soft yield is meaningless in microarchitecture
-        return false;
-    }
-
-    void do_putchar(uint8_t c) {
-        _putchar(c);
-    }
-
-    int do_getchar() {
-        return -1;
-    }
-
-    // NOLINTEND(readability-convert-member-functions-to-static)
-};
-
-} // namespace cartesi
-
-#endif
diff --git a/uarch/uarch-printf.c b/uarch/uarch-printf.c
index d328b95c0..70254e586 100644
--- a/uarch/uarch-printf.c
+++ b/uarch/uarch-printf.c
@@ -37,7 +37,7 @@
 #include <stdint.h>
 
 #include "uarch-printf.h"
-
+#include "uarch-ecall.h"
 
 // define this globally (e.g. gcc -DPRINTF_INCLUDE_CONFIG_H ...) to include the
 // printf_config.h header file
@@ -153,7 +153,7 @@ static inline void _out_char(char character, void* buffer, size_t idx, size_t ma
 {
   (void)buffer; (void)idx; (void)maxlen;
   if (character) {
-    _putchar(character);
+    ua_putchar_ECALL(character);
   }
 }
 
diff --git a/uarch/uarch-printf.h b/uarch/uarch-printf.h
index 43341e9ef..a68a6141b 100644
--- a/uarch/uarch-printf.h
+++ b/uarch/uarch-printf.h
@@ -39,13 +39,6 @@
 extern "C" {
 #endif
 
-/**
- * Output a character to a custom device like UART, used by the printf() function
- * This function is declared here only. You have to write your custom implementation somewhere
- * \param character Character to output
- */
-void _putchar(char character);
-
 /**
  * Tiny printf implementation
  * You have to implement _putchar if you use printf()
diff --git a/uarch/uarch-ram-entry.S b/uarch/uarch-ram-entry.S
index 81fc85960..f8fca7184 100644
--- a/uarch/uarch-ram-entry.S
+++ b/uarch/uarch-ram-entry.S
@@ -20,9 +20,9 @@
 .section .text.init;
 .align 3;
 .global _start;
-_start:    
+_start:
     // Initialize stack
-    li sp, PMA_UARCH_RAM_START_DEF  
+    li sp, PMA_UARCH_RAM_START_DEF
     li t0, PMA_UARCH_RAM_LENGTH_DEF
     add sp, sp, t0 // stack pointer at the end of RAM
     call interpret_next_mcycle_with_uarch
diff --git a/uarch/uarch-run.cpp b/uarch/uarch-run.cpp
index e3871095a..1248daa0f 100644
--- a/uarch/uarch-run.cpp
+++ b/uarch/uarch-run.cpp
@@ -18,40 +18,36 @@
 
 #include "compiler-defines.h"
 #include "interpret.h"
+#include "mock-pma-entry.h"
+#include "machine-uarch-bridge-state-access.h"
 #include "uarch-constants.h"
-#include "uarch-machine-state-access.h"
+#include "uarch-ecall.h"
 
+#include <array>
+#include <optional>
 #include <cstdint>
 
 using namespace cartesi;
 
-static void set_uarch_halt_flag() {
-    // NOLINTNEXTLINE(hicpp-no-assembler)
-    asm volatile("mv a7, %0\n"
-                 "ecall\n"
-        : // no output
-        : "r"(cartesi::uarch_ecall_functions::UARCH_ECALL_FN_HALT)
-        : "a7" // modified registers
-    );
-}
+// Let the state accessor be on static memory storage to speed up uarch initialization
+// NOLINTNEXTLINE(cppcoreguidelines-avoid-non-const-global-variables)
+std::array<std::optional<mock_pma_entry>, PMA_MAX> pmas;
 
 namespace cartesi {
 
 // Declaration of explicit instantiation in module interpret.cpp when compiled with microarchitecture
-extern template interpreter_break_reason interpret(uarch_machine_state_access a, uint64_t mcycle_end);
+extern template interpreter_break_reason interpret(machine_uarch_bridge_state_access a, uint64_t mcycle_end);
 
 } // namespace cartesi
 
 /// \brief  Advances one mcycle by executing the "big machine interpreter" compiled to the microarchitecture
 /// \return This function never returns
 extern "C" NO_RETURN void interpret_next_mcycle_with_uarch() {
-    // Let the state accessor be on static memory storage to speed up uarch initialization
-    static std::array<std::optional<uarch_pma_entry>, PMA_MAX> pmas;
-    uarch_machine_state_access a(pmas);
+    machine_uarch_bridge_state_access a(pmas);
     const uint64_t mcycle_end = a.read_mcycle() + 1;
     interpret(a, mcycle_end);
     // Finished executing a whole mcycle: halt the microarchitecture
-    set_uarch_halt_flag();
+    ua_halt_ECALL();
     // The micro interpreter will never execute this line because the micro machine is halted
     __builtin_trap();
 }
diff --git a/uarch/uarch-runtime.cpp b/uarch/uarch-runtime.cpp
index bb8758875..932544cef 100644
--- a/uarch/uarch-runtime.cpp
+++ b/uarch/uarch-runtime.cpp
@@ -21,8 +21,6 @@
 #include <cstddef>
 #include <cstdint>
 
-using namespace cartesi;
-
 // NOLINTNEXTLINE(bugprone-reserved-identifier,cert-dcl37-c,cert-dcl51-cpp)
 extern "C" void __cxa_pure_virtual() {
     abort();
@@ -81,18 +79,6 @@ extern "C" void *memset(void *ptr, int value, size_t num) {
     return ptr;
 }
 
-extern "C" void _putchar(char c) {
-    // NOLINTNEXTLINE(hicpp-no-assembler)
-    asm volatile("mv a7, %0\n"
-                 "mv a6, %1\n"
-                 "ecall\n"
-        : // no output
-        : "r"(cartesi::uarch_ecall_functions::UARCH_ECALL_FN_PUTCHAR),
-        "r"(c)       // character to print
-        : "a7", "a6" // modified registers
-    );
-}
-
 extern "C" NO_RETURN void abort() {
     // NOLINTNEXTLINE(hicpp-no-assembler)
     asm volatile("ebreak"
diff --git a/uarch/uarch-strict-aliasing.h b/uarch/uarch-strict-aliasing.h
new file mode 100644
index 000000000..7b166eb90
--- /dev/null
+++ b/uarch/uarch-strict-aliasing.h
@@ -0,0 +1,92 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef UARCH_STRICT_ALIASING_H
+#define UARCH_STRICT_ALIASING_H
+
+#include "compiler-defines.h"
+#include <inttypes.h>
+
+template <typename T, typename A = T>
+static inline void ua_aliased_aligned_write(uint64_t paddr, T val);
+
+template <typename T, typename A = T>
+static inline T ua_aliased_aligned_read(uint64_t paddr);
+
+#define UA_ALIASED_ALIGNED_WRITE(TYPE, INSN)                                                                           \
+    template <>                                                                                                        \
+    [[maybe_unused]] void ua_aliased_aligned_write<TYPE, TYPE>(uint64_t paddr, TYPE val) {                             \
+        /* NOLINTNEXTLINE(hicpp-no-assembler) */                                                                       \
+        asm volatile("mv a0, %0\n"                                                                                     \
+                     "mv a1, %1\n" INSN " a1, (a0)\n"                                                                  \
+                     : /* no output */                                                                                 \
+                     : "r"(paddr), "r"(val)                                                                            \
+                     : "a0", "a1" /* clobbered registers */                                                            \
+        );                                                                                                             \
+    }
+
+UA_ALIASED_ALIGNED_WRITE(uint64_t, "sd")
+UA_ALIASED_ALIGNED_WRITE(int64_t, "sd")
+UA_ALIASED_ALIGNED_WRITE(uint32_t, "sw")
+UA_ALIASED_ALIGNED_WRITE(int32_t, "sw")
+UA_ALIASED_ALIGNED_WRITE(uint16_t, "sh")
+UA_ALIASED_ALIGNED_WRITE(int16_t, "sh")
+UA_ALIASED_ALIGNED_WRITE(uint8_t, "sb")
+UA_ALIASED_ALIGNED_WRITE(int8_t, "sb")
+
+//??D see if this is the best we can do
+#define UA_ALIASED_ALIGNED_READ(TYPE, INSN)                                                                            \
+    template <>                                                                                                        \
+    [[maybe_unused]] TYPE ua_aliased_aligned_read<TYPE, TYPE>(uint64_t paddr) {                                        \
+        /* NOLINTNEXTLINE(hicpp-no-assembler) */                                                                       \
+        TYPE ret = 0;                                                                                                  \
+        asm volatile("mv a0, %1\n" INSN " a1, (a0)\n"                                                                  \
+                     "mv %0, a1\n"                                                                                     \
+                     : "=r"(ret)                                                                                       \
+                     : "r"(paddr), "r"(ret)                                                                            \
+                     : "a0", "a1" /* clobbered registers */                                                            \
+        );                                                                                                             \
+        return ret;                                                                                                    \
+    }
+
+UA_ALIASED_ALIGNED_READ(uint64_t, "ld")
+UA_ALIASED_ALIGNED_READ(int64_t, "ld")
+UA_ALIASED_ALIGNED_READ(uint32_t, "lwu")
+UA_ALIASED_ALIGNED_READ(int32_t, "lw")
+UA_ALIASED_ALIGNED_READ(uint16_t, "lhu")
+UA_ALIASED_ALIGNED_READ(int16_t, "lh")
+UA_ALIASED_ALIGNED_READ(uint8_t, "lbu")
+UA_ALIASED_ALIGNED_READ(int8_t, "lb")
+
+//??D see if this is the best we can do
+template <>
+[[maybe_unused]] uint32_t ua_aliased_aligned_read<uint32_t, uint16_t>(uint64_t paddr) {
+    // NOLINTNEXTLINE(hicpp-no-assembler)
+    uint32_t ret = 0;
+    asm volatile("mv a0, %1\n"
+                 "lhu a1, (a0)\n"
+                 "lhu a2, 2(a0)\n"
+                 "slli a2, a2, 16\n"
+                 "or a1, a2, a1\n"
+                 "mv %0, a1\n"
+                 : "=r"(ret)
+                 : "r"(paddr), "r"(ret)
+                 : "a0", "a1", "a2" // clobbered registers
+    );
+    return ret;
+}
+
+#endif

From b3190aa0d94e6a5b5551b8ac7ddb83668c32a209 Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Sat, 1 Feb 2025 22:46:16 +0000
Subject: [PATCH 05/82] refactor: remove some inline asm from uarch

Using __builtin_memcpy instead.
---
 src/host-addr.h               |  22 +++++++
 src/strict-aliasing.h         |  28 +--------
 uarch/uarch-strict-aliasing.h | 111 ++++++++++++++--------------------
 3 files changed, 70 insertions(+), 91 deletions(-)

diff --git a/src/host-addr.h b/src/host-addr.h
index b6a33f6d1..af5f70dbd 100644
--- a/src/host-addr.h
+++ b/src/host-addr.h
@@ -17,6 +17,8 @@
 #ifndef HOST_ADDR_H
 #define HOST_ADDR_H
 
+#include "strict-aliasing.h"
+
 namespace cartesi {
 
 // This is simply an uint64_t as a separate type, not automatically convertible to uint64_t
@@ -93,6 +95,26 @@ static inline void *cast_host_addr_to_ptr(host_addr host_addr) {
     return reinterpret_cast<void *>(static_cast<uintptr_t>(host_addr));
 }
 
+/// \brief Writes a value to memory.
+/// \tparam T Type of value.
+/// \tparam A Type to which \p haddr is aligned.
+/// \param haddr Where to write. Must be aligned to sizeof(A).
+/// \param v Value to write.
+template <typename T, typename A = T>
+static inline void aliased_aligned_write(host_addr haddr, T v) {
+    aliased_aligned_write<T, A>(cast_host_addr_to_ptr(haddr), v);
+}
+
+/// \brief Reads a value from memory.
+/// \tparam T Type of value.
+/// \tparam A Type to which \p haddr is aligned.
+/// \param haddr Where to find value. Must be aligned to sizeof(A).
+/// \returns Value read.
+template <typename T, typename A = T>
+static inline T aliased_aligned_read(host_addr haddr) {
+    return aliased_aligned_read<T, A>(cast_host_addr_to_ptr(haddr));
+}
+
 } // namespace cartesi
 
 #endif
diff --git a/src/strict-aliasing.h b/src/strict-aliasing.h
index 5313f427c..a35becf52 100644
--- a/src/strict-aliasing.h
+++ b/src/strict-aliasing.h
@@ -21,35 +21,11 @@
 #include <cstring>
 #include <type_traits>
 
-#include "host-addr.h"
-
 /// \file
 /// \brief Enforcement of the strict aliasing rule
 
 namespace cartesi {
 
-/// \brief Writes a value to memory.
-/// \tparam T Type of value.
-/// \tparam A Type to which \p haddr is aligned.
-/// \param haddr Where to write. Must be aligned to sizeof(A).
-/// \param v Value to write.
-template <typename T, typename A = T>
-static inline void aliased_aligned_write(host_addr haddr, T v) {
-    memcpy(__builtin_assume_aligned(cast_host_addr_to_ptr(haddr), sizeof(A)), &v, sizeof(T));
-}
-
-/// \brief Reads a value from memory.
-/// \tparam T Type of value.
-/// \tparam A Type to which \p haddr is aligned.
-/// \param haddr Where to find value. Must be aligned to sizeof(A).
-/// \returns Value read.
-template <typename T, typename A = T>
-static inline T aliased_aligned_read(host_addr haddr) {
-    T v;
-    memcpy(&v, __builtin_assume_aligned(cast_host_addr_to_ptr(haddr), sizeof(A)), sizeof(T));
-    return v;
-}
-
 /// \brief Writes a value to memory.
 /// \tparam T Type of value.
 /// \tparam A Type to which \p haddr is aligned.
@@ -57,7 +33,7 @@ static inline T aliased_aligned_read(host_addr haddr) {
 /// \param v Value to write.
 template <typename T, typename A = T>
 static inline void aliased_aligned_write(void *p, T v) {
-    memcpy(__builtin_assume_aligned(p, sizeof(A)), &v, sizeof(T));
+    __builtin_memcpy(__builtin_assume_aligned(p, sizeof(A)), &v, sizeof(T));
 }
 
 /// \brief Reads a value from memory.
@@ -68,7 +44,7 @@ static inline void aliased_aligned_write(void *p, T v) {
 template <typename T, typename A = T>
 static inline T aliased_aligned_read(const void *p) {
     T v;
-    memcpy(&v, __builtin_assume_aligned(p, sizeof(A)), sizeof(T));
+    __builtin_memcpy(&v, __builtin_assume_aligned(p, sizeof(A)), sizeof(T));
     return v;
 }
 
diff --git a/uarch/uarch-strict-aliasing.h b/uarch/uarch-strict-aliasing.h
index 7b166eb90..c3bfb2ffc 100644
--- a/uarch/uarch-strict-aliasing.h
+++ b/uarch/uarch-strict-aliasing.h
@@ -17,76 +17,57 @@
 #ifndef UARCH_STRICT_ALIASING_H
 #define UARCH_STRICT_ALIASING_H
 
-#include "compiler-defines.h"
-#include <inttypes.h>
-
-template <typename T, typename A = T>
-static inline void ua_aliased_aligned_write(uint64_t paddr, T val);
+/// \file
+/// \brief Enforcement of the strict aliasing rule
 
-template <typename T, typename A = T>
-static inline T ua_aliased_aligned_read(uint64_t paddr);
-
-#define UA_ALIASED_ALIGNED_WRITE(TYPE, INSN)                                                                           \
-    template <>                                                                                                        \
-    [[maybe_unused]] void ua_aliased_aligned_write<TYPE, TYPE>(uint64_t paddr, TYPE val) {                             \
-        /* NOLINTNEXTLINE(hicpp-no-assembler) */                                                                       \
-        asm volatile("mv a0, %0\n"                                                                                     \
-                     "mv a1, %1\n" INSN " a1, (a0)\n"                                                                  \
-                     : /* no output */                                                                                 \
-                     : "r"(paddr), "r"(val)                                                                            \
-                     : "a0", "a1" /* clobbered registers */                                                            \
-        );                                                                                                             \
-    }
+#include "compiler-defines.h"
+#include "strict-aliasing.h"
 
-UA_ALIASED_ALIGNED_WRITE(uint64_t, "sd")
-UA_ALIASED_ALIGNED_WRITE(int64_t, "sd")
-UA_ALIASED_ALIGNED_WRITE(uint32_t, "sw")
-UA_ALIASED_ALIGNED_WRITE(int32_t, "sw")
-UA_ALIASED_ALIGNED_WRITE(uint16_t, "sh")
-UA_ALIASED_ALIGNED_WRITE(int16_t, "sh")
-UA_ALIASED_ALIGNED_WRITE(uint8_t, "sb")
-UA_ALIASED_ALIGNED_WRITE(int8_t, "sb")
+namespace cartesi {
 
-//??D see if this is the best we can do
-#define UA_ALIASED_ALIGNED_READ(TYPE, INSN)                                                                            \
-    template <>                                                                                                        \
-    [[maybe_unused]] TYPE ua_aliased_aligned_read<TYPE, TYPE>(uint64_t paddr) {                                        \
-        /* NOLINTNEXTLINE(hicpp-no-assembler) */                                                                       \
-        TYPE ret = 0;                                                                                                  \
-        asm volatile("mv a0, %1\n" INSN " a1, (a0)\n"                                                                  \
-                     "mv %0, a1\n"                                                                                     \
-                     : "=r"(ret)                                                                                       \
-                     : "r"(paddr), "r"(ret)                                                                            \
-                     : "a0", "a1" /* clobbered registers */                                                            \
-        );                                                                                                             \
-        return ret;                                                                                                    \
-    }
+/// \brief Casts a pointer to an unsigned integer.
+/// \details The pointer returned by this function
+/// must only be read/written using aliased_aligned_read/aliased_aligned_write,
+/// otherwise strict aliasing rules may be violated.
+/// \tparam T Unsigned integer type to cast to.
+/// \tparam PTR Pointer type to perform the cast.
+/// \param addr The address of the pointer represented by an unsigned integer.
+/// \returns A pointer.
+static inline void *cast_phys_addr_to_ptr(uint64_t paddr) {
+    // Enforcement on type arguments
+    static_assert(sizeof(void *) == sizeof(uintptr_t));
+    static_assert(sizeof(paddr) >= sizeof(uintptr_t));
+    // Note that bellow we cast the address to void* first,
+    // according to the C spec this is required is to ensure the same presentation, before casting to PTR
+    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast,bugprone-casting-through-void,performance-no-int-to-ptr)
+    return reinterpret_cast<void *>(static_cast<uintptr_t>(paddr));
+}
 
-UA_ALIASED_ALIGNED_READ(uint64_t, "ld")
-UA_ALIASED_ALIGNED_READ(int64_t, "ld")
-UA_ALIASED_ALIGNED_READ(uint32_t, "lwu")
-UA_ALIASED_ALIGNED_READ(int32_t, "lw")
-UA_ALIASED_ALIGNED_READ(uint16_t, "lhu")
-UA_ALIASED_ALIGNED_READ(int16_t, "lh")
-UA_ALIASED_ALIGNED_READ(uint8_t, "lbu")
-UA_ALIASED_ALIGNED_READ(int8_t, "lb")
+//??D I don't know why GCC warns about this overflow when there is none.
+//??D The code generated seems to be pretty good as well.
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wstringop-overflow"
+/// \brief Writes a value to memory.
+/// \tparam T Type of value.
+/// \tparam A Type to which \p paddr is aligned.
+/// \param paddr Where to write. Must be aligned to sizeof(A).
+/// \param v Value to write.
+template <typename T, typename A = T>
+static inline void ua_aliased_aligned_write(uint64_t paddr, T v) {
+    aliased_aligned_write<T, A>(cast_phys_addr_to_ptr(paddr), v);
+}
 
-//??D see if this is the best we can do
-template <>
-[[maybe_unused]] uint32_t ua_aliased_aligned_read<uint32_t, uint16_t>(uint64_t paddr) {
-    // NOLINTNEXTLINE(hicpp-no-assembler)
-    uint32_t ret = 0;
-    asm volatile("mv a0, %1\n"
-                 "lhu a1, (a0)\n"
-                 "lhu a2, 2(a0)\n"
-                 "slli a2, a2, 16\n"
-                 "or a1, a2, a1\n"
-                 "mv %0, a1\n"
-                 : "=r"(ret)
-                 : "r"(paddr), "r"(ret)
-                 : "a0", "a1", "a2" // clobbered registers
-    );
-    return ret;
+/// \brief Reads a value from memory.
+/// \tparam T Type of value.
+/// \tparam A Type to which \p paddr is aligned.
+/// \param paddr Where to find value. Must be aligned to sizeof(A).
+/// \returns Value read.
+template <typename T, typename A = T>
+static inline T ua_aliased_aligned_read(uint64_t paddr) {
+    return aliased_aligned_read<T, A>(cast_phys_addr_to_ptr(paddr));
 }
+#pragma GCC diagnostic pop
+
+} // namespace cartesi
 
 #endif

From 9dd83e0e74977ab1387356aaf42fb3230eb99c3a Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Mon, 3 Feb 2025 09:04:04 +0000
Subject: [PATCH 06/82] refactor: remove machine bridge

The machine class took over the role.
---
 src/Makefile                              |   1 -
 src/machine.cpp                           |  75 +++++++++-
 src/machine.h                             |  14 +-
 src/uarch-machine-bridge.cpp              | 170 ----------------------
 src/uarch-machine-bridge.h                |  57 --------
 src/uarch-record-state-access.h           |  19 +--
 src/uarch-replay-state-access.h           |   4 +-
 src/uarch-state-access.h                  |  31 ++--
 tests/misc/test-machine-c-api.cpp         |   2 +-
 uarch/machine-uarch-bridge-state-access.h |   4 -
 10 files changed, 111 insertions(+), 266 deletions(-)
 delete mode 100644 src/uarch-machine-bridge.cpp
 delete mode 100644 src/uarch-machine-bridge.h

diff --git a/src/Makefile b/src/Makefile
index 53c30cb7b..08b00ae82 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -388,7 +388,6 @@ LIBCARTESI_OBJS:= \
 	uarch-pristine-hash.o \
     uarch-interpret.o \
 	uarch-step.o \
-	uarch-machine-bridge.o \
 	uarch-reset-state.o \
 	send-cmio-response.o \
 	replay-step-state-access-interop.o
diff --git a/src/machine.cpp b/src/machine.cpp
index b3f101340..68447e514 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -1987,6 +1987,28 @@ machine::hash_type machine::get_merkle_tree_node_hash(uint64_t address, int log2
     return hash;
 }
 
+const char *machine::get_what_name(uint64_t paddr) {
+    if (paddr >= PMA_UARCH_RAM_START && paddr - PMA_UARCH_RAM_START < PMA_UARCH_RAM_LENGTH) {
+        return "uarch.ram";
+    }
+    // If in shadow, return refined name
+    if (paddr >= PMA_SHADOW_TLB_START && paddr - PMA_SHADOW_TLB_START < PMA_SHADOW_TLB_LENGTH) {
+        [[maybe_unused]] TLB_set_index set_index{};
+        [[maybe_unused]] uint64_t slot_index{};
+        return shadow_tlb_get_what_name(shadow_tlb_get_what(paddr, set_index, slot_index));
+    }
+    if (paddr >= PMA_SHADOW_STATE_START && paddr - PMA_SHADOW_STATE_START < PMA_SHADOW_STATE_LENGTH) {
+        return shadow_state_get_what_name(shadow_state_get_what(paddr));
+    }
+    if (paddr >= PMA_SHADOW_PMAS_START && paddr - PMA_SHADOW_PMAS_START < PMA_SHADOW_PMAS_LENGTH) {
+        return shadow_pmas_get_what_name(shadow_pmas_get_what(paddr));
+    }
+    if (paddr >= PMA_SHADOW_UARCH_STATE_START && paddr - PMA_SHADOW_UARCH_STATE_START < PMA_SHADOW_UARCH_STATE_LENGTH) {
+        return shadow_uarch_state_get_what_name(shadow_uarch_state_get_what(paddr));
+    }
+    return "memory";
+}
+
 machine::hash_type machine::get_merkle_tree_node_hash(uint64_t address, int log2_size) const {
     if (!update_merkle_tree()) {
         throw std::runtime_error{"error updating Merkle tree"};
@@ -2224,7 +2246,7 @@ uint64_t machine::translate_virtual_address(uint64_t vaddr) {
 uint64_t machine::read_word(uint64_t paddr) const {
     // Make sure address is aligned
     if ((paddr & (sizeof(uint64_t) - 1)) != 0) {
-        throw std::domain_error{"address not aligned"};
+        throw std::domain_error{"attempted misaligned read from word"};
     }
     // Use read_memory
     alignas(sizeof(uint64_t)) std::array<unsigned char, sizeof(uint64_t)> scratch{};
@@ -2232,6 +2254,53 @@ uint64_t machine::read_word(uint64_t paddr) const {
     return aliased_aligned_read<uint64_t>(scratch.data());
 }
 
+void machine::write_word(uint64_t paddr, uint64_t val) {
+    // Make sure address is aligned
+    if ((paddr & (sizeof(uint64_t) - 1)) != 0) {
+        throw std::domain_error{"attempted misaligned write to word"};
+    }
+    // If in shadow, forward to write_reg
+    if (paddr >= PMA_SHADOW_STATE_START && paddr - PMA_SHADOW_STATE_START < PMA_SHADOW_STATE_LENGTH) {
+        auto reg = shadow_state_get_what(paddr);
+        if (reg == shadow_state_what::unknown_) {
+            throw std::runtime_error("unhandled write to shadow state");
+        }
+        if (reg == shadow_state_what::x0) {
+            throw std::runtime_error("invalid shadow state write to x0");
+        }
+        write_reg(machine_reg_enum(reg), val);
+        return;
+    }
+    // If in uarch shadow, forward to write_reg
+    if (paddr >= PMA_SHADOW_UARCH_STATE_START && paddr - PMA_SHADOW_UARCH_STATE_START < PMA_SHADOW_UARCH_STATE_LENGTH) {
+        auto reg = shadow_uarch_state_get_what(paddr);
+        if (reg == shadow_uarch_state_what::unknown_) {
+            throw std::runtime_error("unhandled write to shadow uarch state");
+        }
+        if (reg == shadow_uarch_state_what::uarch_x0) {
+            throw std::runtime_error("invalid shadow state write to uarch.x0");
+        }
+        write_reg(machine_reg_enum(reg), val);
+        return;
+    }
+    // Otherwise, try the slow path
+    auto &pma = find_pma_entry(m_merkle_pmas, paddr, sizeof(uint64_t));
+    if (pma.get_istart_E() || !pma.get_istart_M()) {
+        std::ostringstream err;
+        err << "attempted memory write to " << pma.get_description() << " at address 0x" << std::hex << paddr << "("
+            << std::dec << paddr << ")";
+        throw std::runtime_error{err.str()};
+    }
+    if (!pma.get_istart_W()) {
+        std::ostringstream err;
+        err << "attempted memory write to (non-writeable) " << pma.get_description() << " at address 0x" << std::hex
+            << paddr << "(" << std::dec << paddr << ")";
+        throw std::runtime_error{err.str()};
+    }
+    const auto offset = paddr - pma.get_start();
+    aliased_aligned_write<uint64_t>(pma.get_memory().get_host_memory() + offset, val);
+}
+
 void machine::send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length) {
     const state_access a(*this);
     cartesi::send_cmio_response(a, reason, data, length);
@@ -2293,7 +2362,7 @@ access_log machine::log_reset_uarch(const access_log::type &log_type) {
     hash_type root_hash_before;
     get_root_hash(root_hash_before);
     // Call uarch_reset_state with a uarch_record_state_access object
-    uarch_record_state_access a(m_us, *this, log_type);
+    uarch_record_state_access a(*this, log_type);
     {
         [[maybe_unused]] auto note = a.make_scoped_note("reset_uarch_state");
         uarch_reset_state(a);
@@ -2330,7 +2399,7 @@ access_log machine::log_step_uarch(const access_log::type &log_type) {
     hash_type root_hash_before;
     get_root_hash(root_hash_before);
     // Call interpret with a logged state access object
-    uarch_record_state_access a(m_us, *this, log_type);
+    uarch_record_state_access a(*this, log_type);
     {
         [[maybe_unused]] auto note = a.make_scoped_note("step");
         uarch_step(a);
diff --git a/src/machine.h b/src/machine.h
index 31b7a7063..5ea27047f 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -344,12 +344,19 @@ class machine final {
     /// \returns The address of the register
     static uint64_t get_reg_address(reg r);
 
-    /// \brief Read the value of a word in the machine state.
+    /// \brief Read the value of a word from the machine state.
     /// \param paddr Word address (aligned to 64-bit boundary).
     /// \returns The value of word at address.
     /// \details The word can be anywhere in the entire address space.
     uint64_t read_word(uint64_t paddr) const;
 
+    /// \brief Writes the value of a word to the machine state.
+    /// \param paddr Word address (aligned to 64-bit boundary).
+    /// \details The word can be in a writeable area of the address space.
+    /// This includes the shadow state and the shadow uarch state.
+    /// (But does NOT include memory-mapped devices, the shadow tlb, shadow PMAs, or unnocupied memory regions.)
+    void write_word(uint64_t paddr, uint64_t val);
+
     /// \brief Reads a chunk of data, by its target physical address and length.
     /// \param paddr Target physical address to start reading from.
     /// \param data Buffer that receives data to read. Must be at least \p length bytes long.
@@ -524,6 +531,11 @@ class machine final {
     /// \param root_hash_after State hash after response was sent.
     static void verify_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
         const hash_type &root_hash_before, const access_log &log, const hash_type &root_hash_after);
+
+    /// \brief Returns a description of what is at a given target physical address
+    /// \param paddr Target physical address of interest
+    /// \returns Description of what is at that address
+    static const char *get_what_name(uint64_t paddr);
 };
 
 } // namespace cartesi
diff --git a/src/uarch-machine-bridge.cpp b/src/uarch-machine-bridge.cpp
deleted file mode 100644
index 4583230b0..000000000
--- a/src/uarch-machine-bridge.cpp
+++ /dev/null
@@ -1,170 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#include <ios>
-#include <sstream>
-
-#include "machine.h"
-#include "riscv-constants.h"
-#include "shadow-pmas.h"
-#include "shadow-state.h"
-#include "shadow-tlb.h"
-#include "strict-aliasing.h"
-#include "uarch-machine-bridge.h"
-
-namespace cartesi {
-
-const char *uarch_machine_bridge::get_what_name(uint64_t paddr) {
-    if (paddr >= PMA_UARCH_RAM_START && paddr - PMA_UARCH_RAM_START < PMA_UARCH_RAM_LENGTH) {
-        return "uarch.ram";
-    }
-    // If in shadow, return refined name
-    if (paddr >= PMA_SHADOW_TLB_START && paddr - PMA_SHADOW_TLB_START < PMA_SHADOW_TLB_LENGTH) {
-        [[maybe_unused]] TLB_set_index set_index{};
-        [[maybe_unused]] uint64_t slot_index{};
-        return shadow_tlb_get_what_name(shadow_tlb_get_what(paddr, set_index, slot_index));
-    }
-    if (paddr >= PMA_SHADOW_STATE_START && paddr - PMA_SHADOW_STATE_START < PMA_SHADOW_STATE_LENGTH) {
-        return shadow_state_get_what_name(shadow_state_get_what(paddr));
-    }
-    if (paddr >= PMA_SHADOW_PMAS_START && paddr - PMA_SHADOW_PMAS_START < PMA_SHADOW_PMAS_LENGTH) {
-        return shadow_pmas_get_what_name(shadow_pmas_get_what(paddr));
-    }
-    if (paddr >= PMA_SHADOW_UARCH_STATE_START && paddr - PMA_SHADOW_UARCH_STATE_START < PMA_SHADOW_UARCH_STATE_LENGTH) {
-        return shadow_uarch_state_get_what_name(shadow_uarch_state_get_what(paddr));
-    }
-    return "memory";
-}
-
-void uarch_machine_bridge::write_word(uint64_t paddr, uint64_t val) {
-    if ((paddr & (sizeof(uint64_t) - 1)) != 0) {
-        throw std::runtime_error("misaligned write via uarch-machine bridge");
-    }
-    if (paddr >= PMA_UARCH_RAM_START && paddr - PMA_UARCH_RAM_START < PMA_UARCH_RAM_LENGTH) {
-        write_uarch_memory_word(paddr, val);
-        return;
-    }
-    if (paddr >= PMA_SHADOW_STATE_START && paddr - PMA_SHADOW_STATE_START < PMA_SHADOW_STATE_LENGTH) {
-        write_shadow_state(paddr, val);
-        return;
-    }
-    write_memory_word(paddr, val);
-}
-
-uint64_t uarch_machine_bridge::read_word(uint64_t paddr) const {
-    if ((paddr & (sizeof(uint64_t) - 1)) != 0) {
-        throw std::runtime_error("misaligned read via uarch-machine bridge");
-    }
-    if (paddr >= PMA_UARCH_RAM_START && paddr - PMA_UARCH_RAM_START < PMA_UARCH_RAM_LENGTH) {
-        return read_uarch_memory_word(paddr);
-    }
-    if (paddr >= PMA_SHADOW_STATE_START && paddr - PMA_SHADOW_STATE_START < PMA_SHADOW_STATE_LENGTH) {
-        return read_shadow_state(paddr);
-    }
-    if (paddr >= PMA_SHADOW_TLB_START && paddr - PMA_SHADOW_TLB_START < PMA_SHADOW_TLB_LENGTH) {
-        return read_shadow_tlb(paddr);
-    }
-    return read_memory_word(paddr);
-}
-
-uint64_t uarch_machine_bridge::read_memory_word(uint64_t paddr) const {
-    const auto &pma = m_m.find_pma_entry(paddr, sizeof(uint64_t));
-    if (pma.get_istart_E() || !pma.get_istart_M()) {
-        std::ostringstream err;
-        err << "unhandled memory read from " << pma.get_description() << " at address 0x" << std::hex << paddr << "("
-            << std::dec << paddr << ")";
-    }
-    if (!pma.get_istart_R()) {
-        std::ostringstream err;
-        err << "attempted memory read from (non-readable) " << pma.get_description() << " at address 0x" << std::hex
-            << paddr << "(" << std::dec << paddr << ")";
-        throw std::runtime_error{err.str()};
-    }
-    const auto offset = paddr - pma.get_start();
-    return aliased_aligned_read<uint64_t>(pma.get_memory().get_host_memory() + offset);
-}
-
-uint64_t uarch_machine_bridge::read_uarch_memory_word(uint64_t paddr) const {
-    const auto &pma = m_m.get_uarch_state().ram;
-    const auto offset = paddr - pma.get_start();
-    return aliased_aligned_read<uint64_t>(pma.get_memory().get_host_memory() + offset);
-}
-
-void uarch_machine_bridge::write_uarch_memory_word(uint64_t paddr, uint64_t val) {
-    auto &pma = m_m.get_uarch_state().ram;
-    const auto offset = paddr - pma.get_start();
-    aliased_aligned_write<uint64_t>(pma.get_memory().get_host_memory() + offset, val);
-}
-
-uint64_t uarch_machine_bridge::read_shadow_state(uint64_t paddr) const {
-    auto reg = shadow_state_get_what(paddr);
-    if (reg == shadow_state_what::unknown_) {
-        throw std::runtime_error("unhandled shadow state read via uarch-machine bridge");
-    }
-    return m_m.read_reg(machine_reg_enum(reg));
-}
-
-uint64_t uarch_machine_bridge::read_shadow_tlb(uint64_t paddr) const {
-    TLB_set_index set_index{};
-    uint64_t slot_index{};
-    auto reg = shadow_tlb_get_what(paddr, set_index, slot_index);
-    if (reg == shadow_tlb_what::unknown_) {
-        throw std::runtime_error("unhandled shadow TLB read via uarch-machine bridge");
-    }
-    return m_m.read_shadow_tlb(set_index, slot_index, reg);
-}
-
-void uarch_machine_bridge::write_shadow_state(uint64_t paddr, uint64_t val) {
-    auto reg = shadow_state_get_what(paddr);
-    if (reg == shadow_state_what::unknown_) {
-        throw std::runtime_error("unhandled shadow state write via uarch-machine bridge");
-    }
-    if (reg == shadow_state_what::x0) {
-        throw std::runtime_error("invalid write to shadow state x0 via uarch-machine bridge");
-    }
-    m_m.write_reg(machine_reg_enum(reg), val);
-}
-
-void uarch_machine_bridge::mark_dirty_page(uint64_t paddr, uint64_t pma_index) {
-    m_m.mark_dirty_page(paddr, pma_index);
-}
-
-void uarch_machine_bridge::write_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page,
-    uint64_t vp_offset, uint64_t pma_index) {
-    m_m.check_shadow_tlb(set_index, slot_index, vaddr_page, vp_offset, pma_index,
-        "invalid write to shadow TLB via uarch-machine bridge: ");
-    m_m.write_shadow_tlb(set_index, slot_index, vaddr_page, vp_offset, pma_index);
-}
-
-void uarch_machine_bridge::write_memory_word(uint64_t paddr, uint64_t val) {
-    auto &pma = m_m.find_pma_entry(paddr, sizeof(uint64_t));
-    if (pma.get_istart_E() || !pma.get_istart_M()) {
-        std::ostringstream err;
-        err << "unhandled memory write to " << pma.get_description() << " at address 0x" << std::hex << paddr << "("
-            << std::dec << paddr << ")";
-        throw std::runtime_error{err.str()};
-    }
-    if (!pma.get_istart_W()) {
-        std::ostringstream err;
-        err << "attempted memory write to (non-writeable) " << pma.get_description() << " at address 0x" << std::hex
-            << paddr << "(" << std::dec << paddr << ")";
-        throw std::runtime_error{err.str()};
-    }
-    const auto offset = paddr - pma.get_start();
-    aliased_aligned_write<uint64_t>(pma.get_memory().get_host_memory() + offset, val);
-}
-
-} // namespace cartesi
diff --git a/src/uarch-machine-bridge.h b/src/uarch-machine-bridge.h
deleted file mode 100644
index 0525f0d45..000000000
--- a/src/uarch-machine-bridge.h
+++ /dev/null
@@ -1,57 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef UARCH_MACHINE_BRIDGE_H
-#define UARCH_MACHINE_BRIDGE_H
-
-#include <cstddef>
-#include <cstdint>
-
-#include "tlb.h"
-
-namespace cartesi {
-
-class machine;
-
-/// \brief Allows microarchitecture code to access the machine state
-class uarch_machine_bridge {
-
-    machine &m_m; // NOLINT(cppcoreguidelines-avoid-const-or-ref-data-members)
-
-public:
-    explicit uarch_machine_bridge(machine &m) : m_m(m) {
-        ;
-    }
-    uint64_t read_word(uint64_t paddr) const;
-    void write_word(uint64_t paddr, uint64_t val);
-    void mark_dirty_page(uint64_t paddr, uint64_t pma_index);
-    void write_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset,
-        uint64_t pma_index);
-    static const char *get_what_name(uint64_t paddr);
-
-private:
-    void write_shadow_state(uint64_t paddr, uint64_t val);
-    void write_memory_word(uint64_t paddr, uint64_t val);
-    void write_uarch_memory_word(uint64_t paddr, uint64_t val);
-    uint64_t read_shadow_state(uint64_t paddr) const;
-    uint64_t read_memory_word(uint64_t paddr) const;
-    uint64_t read_uarch_memory_word(uint64_t paddr) const;
-    uint64_t read_shadow_tlb(uint64_t paddr) const;
-};
-
-} // namespace cartesi
-
-#endif
diff --git a/src/uarch-record-state-access.h b/src/uarch-record-state-access.h
index 7a8176650..c6ad12cef 100644
--- a/src/uarch-record-state-access.h
+++ b/src/uarch-record-state-access.h
@@ -42,7 +42,6 @@
 #include "shadow-uarch-state.h"
 #include "strict-aliasing.h"
 #include "uarch-constants.h"
-#include "uarch-machine-bridge.h"
 #include "uarch-pristine-state-hash.h"
 #include "uarch-pristine.h"
 #include "uarch-state.h"
@@ -58,9 +57,7 @@ class uarch_record_state_access : public i_uarch_state_access<uarch_record_state
     using hash_type = machine_merkle_tree::hash_type;
 
     // NOLINTBEGIN(cppcoreguidelines-avoid-const-or-ref-data-members)
-    uarch_state &m_us;
     machine &m_m; ///< Macro machine
-    uarch_machine_bridge m_b;
     // NOLINTEND(cppcoreguidelines-avoid-const-or-ref-data-members)
     std::shared_ptr<access_log> m_log; ///< Pointer to access log
 
@@ -74,10 +71,8 @@ class uarch_record_state_access : public i_uarch_state_access<uarch_record_state
     /// \brief Constructor from machine and uarch states.
     /// \param um Reference to uarch state.
     /// \param m Reference to machine state.
-    explicit uarch_record_state_access(uarch_state &us, machine &m, access_log::type log_type) :
-        m_us(us),
+    explicit uarch_record_state_access(machine &m, access_log::type log_type) :
         m_m(m),
-        m_b(m),
         m_log(std::make_shared<access_log>(log_type)) {
         ;
     }
@@ -280,7 +275,7 @@ class uarch_record_state_access : public i_uarch_state_access<uarch_record_state
         if ((paddr & (sizeof(uint64_t) - 1)) != 0) {
             throw std::runtime_error("misaligned read from uarch");
         }
-        return log_read_word_access(paddr, uarch_machine_bridge::get_what_name(paddr));
+        return log_read_word_access(paddr, machine::get_what_name(paddr));
     }
 
     void do_write_word(uint64_t paddr, uint64_t val) {
@@ -290,12 +285,12 @@ class uarch_record_state_access : public i_uarch_state_access<uarch_record_state
         log_write_access(
             paddr, cartesi::log2_size<uint64_t>::value,
             [this, paddr, val]() {
-                m_b.write_word(paddr, val);
+                m_m.write_word(paddr, val);
                 if (!m_m.update_merkle_tree_page(paddr)) {
                     throw std::invalid_argument{"error updating Merkle tree"};
                 };
             },
-            uarch_machine_bridge::get_what_name(paddr));
+            machine::get_what_name(paddr));
     }
 
     void do_write_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset,
@@ -304,7 +299,7 @@ class uarch_record_state_access : public i_uarch_state_access<uarch_record_state
         log_write_access(
             slot_paddr, SHADOW_TLB_SLOT_LOG2_SIZE,
             [this, set_index, slot_index, vaddr_page, vp_offset, pma_index]() {
-                m_b.write_shadow_tlb(set_index, slot_index, vaddr_page, vp_offset, pma_index);
+                m_m.write_shadow_tlb(set_index, slot_index, vaddr_page, vp_offset, pma_index);
                 // Entire slot is in a single page
                 if (!m_m.update_merkle_tree_page(shadow_tlb_get_abs_addr(set_index, slot_index))) {
                     throw std::invalid_argument{"error updating Merkle tree"};
@@ -343,8 +338,8 @@ class uarch_record_state_access : public i_uarch_state_access<uarch_record_state
     }
 
     void do_mark_dirty_page(uint64_t paddr, uint64_t pma_index) {
-        // forward to bridge, and no need to log
-        m_b.mark_dirty_page(paddr, pma_index);
+        // Forward to machine and no need to log
+        m_m.mark_dirty_page(paddr, pma_index);
     }
 
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
diff --git a/src/uarch-replay-state-access.h b/src/uarch-replay-state-access.h
index 3f2d3e35c..eb604e54c 100644
--- a/src/uarch-replay-state-access.h
+++ b/src/uarch-replay-state-access.h
@@ -332,11 +332,11 @@ class uarch_replay_state_access : public i_uarch_state_access<uarch_replay_state
     }
 
     uint64_t do_read_word(uint64_t paddr) {
-        return check_read_word_access(paddr, uarch_machine_bridge::get_what_name(paddr));
+        return check_read_word_access(paddr, machine::get_what_name(paddr));
     }
 
     void do_write_word(uint64_t paddr, uint64_t val) {
-        check_write_word_access(paddr, val, uarch_machine_bridge::get_what_name(paddr));
+        check_write_word_access(paddr, val, machine::get_what_name(paddr));
     }
 
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
diff --git a/src/uarch-state-access.h b/src/uarch-state-access.h
index 94d66784b..0a84017e8 100644
--- a/src/uarch-state-access.h
+++ b/src/uarch-state-access.h
@@ -28,7 +28,6 @@
 #include "os.h"
 #include "riscv-constants.h"
 #include "strict-aliasing.h"
-#include "uarch-machine-bridge.h"
 #include "uarch-pristine.h"
 
 #if DUMP_UARCH_STATE_ACCESS
@@ -40,15 +39,14 @@ namespace cartesi {
 class uarch_state_access : public i_uarch_state_access<uarch_state_access> {
     // NOLINTBEGIN(cppcoreguidelines-avoid-const-or-ref-data-members)
     machine &m_m;
-    uarch_machine_bridge m_b;
+    // NOLINTEND(cppcoreguidelines-avoid-const-or-ref-data-members)
     host_addr m_uram_ph_offset;
-    // NOLINTEND(cppcoreguidelines-avoid-const-or-ref-data-members)1
 
 public:
     /// \brief Constructor from machine and uarch states.
     /// \param um Reference to uarch state.
     /// \param m Reference to machine state.
-    explicit uarch_state_access(machine &m) : m_m(m), m_b(m) {
+    explicit uarch_state_access(machine &m) : m_m(m) {
         const auto &uram = m_m.get_uarch_state().ram;
         const auto haddr = cast_ptr_to_host_addr(uram.get_memory_noexcept().get_host_memory());
         const auto paddr = uram.get_start();
@@ -114,27 +112,29 @@ class uarch_state_access : public i_uarch_state_access<uarch_state_access> {
         if ((paddr & (sizeof(uint64_t) - 1)) != 0) {
             throw std::runtime_error("misaligned read from uarch");
         }
-        // If the word is in UARCH_RAM, read it
+        // If the word is in UARCH_RAM, read it directly
+        // ??D This is an optimization that makes 15% difference in run_uarch tests
         if (m_m.get_uarch_state().ram.contains(paddr, sizeof(uint64_t))) {
             auto haddr = m_uram_ph_offset + paddr;
             return aliased_aligned_read<uint64_t>(haddr);
         }
-        // Otherwise, forward to bridge
-        return m_b.read_word(paddr);
+        // Forward to machine
+        return m_m.read_word(paddr);
     }
 
     void do_write_word(uint64_t paddr, uint64_t val) {
         if ((paddr & (sizeof(uint64_t) - 1)) != 0) {
-            throw std::runtime_error("misaligned write to uarch");
+            throw std::runtime_error("misaligned read from uarch");
         }
-        // If the word is in UARCH_RAM, write it
+        // If the word is in UARCH_RAM, write it directly
+        // ??D This is an optimization that makes 15% difference in run_uarch tests
         if (m_m.get_uarch_state().ram.contains(paddr, sizeof(uint64_t))) {
             auto haddr = m_uram_ph_offset + paddr;
             aliased_aligned_write<uint64_t>(haddr, val);
             return;
         }
-        // Otherwise, forward to bridge
-        m_b.write_word(paddr, val);
+        // Forward to machine
+        m_m.write_word(paddr, val);
     }
 
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
@@ -144,17 +144,18 @@ class uarch_state_access : public i_uarch_state_access<uarch_state_access> {
 
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
     void do_mark_dirty_page(uint64_t paddr, uint64_t pma_index) {
-        // forward to bridge
-        m_b.mark_dirty_page(paddr, pma_index);
+        // Forward to machine
+        m_m.mark_dirty_page(paddr, pma_index);
     }
 
     void do_write_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset,
         uint64_t pma_index) {
-        // forward to bridge
-        m_b.write_shadow_tlb(set_index, slot_index, vaddr_page, vp_offset, pma_index);
+        // Forward to machine
+        m_m.write_shadow_tlb(set_index, slot_index, vaddr_page, vp_offset, pma_index);
     }
 
     void do_reset_state() {
+        // Forward to machine
         m_m.reset_uarch();
     }
 
diff --git a/tests/misc/test-machine-c-api.cpp b/tests/misc/test-machine-c-api.cpp
index 980d4d595..2be54e96c 100644
--- a/tests/misc/test-machine-c-api.cpp
+++ b/tests/misc/test-machine-c-api.cpp
@@ -463,7 +463,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(read_word_invalid_address_test, ordinary_machine_
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_DOMAIN_ERROR);
 
     std::string result = cm_get_last_error_message();
-    std::string origin("address not aligned");
+    std::string origin("attempted misaligned read from word");
     BOOST_CHECK_EQUAL(origin, result);
 }
 
diff --git a/uarch/machine-uarch-bridge-state-access.h b/uarch/machine-uarch-bridge-state-access.h
index bf08fb53a..e0fcac1fe 100644
--- a/uarch/machine-uarch-bridge-state-access.h
+++ b/uarch/machine-uarch-bridge-state-access.h
@@ -413,10 +413,6 @@ class machine_uarch_bridge_state_access : public i_state_access<machine_uarch_br
         return bridge_read_reg(machine_reg::htif_iyield);
     }
 
-    std::pair<uint64_t, bool> do_poll_external_interrupts(uint64_t mcycle, uint64_t /*mcycle_max*/) {
-        return {mcycle, false};
-    }
-
     template <typename T, typename A>
     void do_read_memory_word(uint64_t paddr, uint64_t /* pma_index */, T *pval) {
         *pval = ua_aliased_aligned_read<T, A>(paddr);

From e83beaa64ba77788ae8d87317bc0e2c7c4638e99 Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Mon, 3 Feb 2025 11:54:19 +0000
Subject: [PATCH 07/82] refactor: split out i-interactive-state-access.h

---
 src/complete-merkle-tree.h          |  2 +-
 src/device-state-access.h           | 17 +++---
 src/i-hasher.h                      | 10 ++--
 src/i-interactive-state-access.h    | 80 +++++++++++++++++++++++++++++
 src/i-state-access.h                | 52 +++----------------
 src/interpret.cpp                   | 38 ++++++++------
 src/machine.cpp                     | 43 +++++++++++++++-
 src/machine.h                       | 10 ++++
 src/merkle-tree-proof.h             |  8 +--
 src/meta.h                          | 14 +++--
 src/record-send-cmio-state-access.h |  8 +--
 src/record-step-state-access.h      |  1 -
 src/replay-send-cmio-state-access.h |  8 +--
 src/replay-step-state-access.h      |  1 -
 src/state-access.h                  | 72 ++++++++------------------
 src/uarch-record-state-access.h     |  8 +--
 src/uarch-replay-state-access.h     |  6 +--
 uarch/Makefile                      | 53 ++++++++++---------
 18 files changed, 251 insertions(+), 180 deletions(-)
 create mode 100644 src/i-interactive-state-access.h

diff --git a/src/complete-merkle-tree.h b/src/complete-merkle-tree.h
index f56783bc3..72d3e8fea 100644
--- a/src/complete-merkle-tree.h
+++ b/src/complete-merkle-tree.h
@@ -66,7 +66,7 @@ class complete_merkle_tree {
     template <typename L>
     complete_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size, L &&leaves) :
         complete_merkle_tree{log2_root_size, log2_leaf_size, log2_word_size} {
-        static_assert(std::is_same_v<level_type, typename remove_cvref<L>::type>, "not a leaves vector");
+        static_assert(std::is_same_v<level_type, std::remove_cvref_t<L>>, "not a leaves vector");
         get_level(get_log2_leaf_size()) = std::forward<L>(leaves);
         bubble_up();
     }
diff --git a/src/device-state-access.h b/src/device-state-access.h
index 812d2c1cb..b424470c4 100644
--- a/src/device-state-access.h
+++ b/src/device-state-access.h
@@ -23,21 +23,19 @@
 #include <cstdint>
 
 #include "i-device-state-access.h"
+#include "i-interactive-state-access.h"
 #include "i-state-access.h"
 
 namespace cartesi {
 
-/// \details The device_state_access class implements a
-/// virtual interface to the state on top of the static
-/// interface provided by any class implementing the
-/// i_state_access interface.
-/// \tparam STATE_ACCESS Class implementing the
-/// i_state_access interface.
+/// \details The device_state_access class implements a virtual interface to the state on top of the static
+/// interface provided by any class implementing the i_state_access interface.
+/// \tparam STATE_ACCESS Class implementing the i_state_access interface.
 template <typename STATE_ACCESS>
 class device_state_access : public i_device_state_access {
 public:
     explicit device_state_access(STATE_ACCESS a, uint64_t mcycle) : m_a(a), m_mcycle(mcycle) {
-        static_assert(is_an_i_state_access<STATE_ACCESS>::value, "not an i_state_access");
+        static_assert(is_an_i_state_access_v<STATE_ACCESS>, "not an i_state_access");
     }
 
     /// \brief No copy constructor
@@ -152,7 +150,10 @@ class device_state_access : public i_device_state_access {
     }
 
     int do_getchar() override {
-        return m_a.getchar();
+        if constexpr (is_an_i_interactive_state_access_v<STATE_ACCESS>) {
+            return m_a.getchar();
+        }
+        return -1;
     }
 };
 
diff --git a/src/i-hasher.h b/src/i-hasher.h
index 70fc17390..790d98b2f 100644
--- a/src/i-hasher.h
+++ b/src/i-hasher.h
@@ -67,8 +67,10 @@ class i_hasher { // CRTP
 };
 
 template <typename DERIVED>
-using is_an_i_hasher =
-    std::integral_constant<bool, is_template_base_of<i_hasher, typename remove_cvref<DERIVED>::type>::value>;
+using is_an_i_hasher = std::integral_constant<bool, is_template_base_of_v<i_hasher, std::remove_cvref_t<DERIVED>>>;
+
+template <typename DERIVED>
+constexpr bool is_an_i_hasher_v = is_an_i_hasher<DERIVED>::value;
 
 /// \brief Computes the hash of concatenated hashes
 /// \tparam H Hasher class
@@ -79,7 +81,7 @@ using is_an_i_hasher =
 template <typename H>
 inline static void get_concat_hash(H &h, const typename H::hash_type &left, const typename H::hash_type &right,
     typename H::hash_type &result) {
-    static_assert(is_an_i_hasher<H>::value, "not an i_hasher");
+    static_assert(is_an_i_hasher_v<H>, "not an i_hasher");
     h.begin();
     h.add_data(left.data(), static_cast<int>(left.size()));
     h.add_data(right.data(), static_cast<int>(right.size()));
@@ -95,7 +97,7 @@ inline static void get_concat_hash(H &h, const typename H::hash_type &left, cons
 template <typename H>
 inline static typename H::hash_type get_concat_hash(H &h, const typename H::hash_type &left,
     const typename H::hash_type &right) {
-    static_assert(is_an_i_hasher<H>::value, "not an i_hasher");
+    static_assert(is_an_i_hasher_v<H>, "not an i_hasher");
     h.begin();
     h.add_data(left.data(), left.size());
     h.add_data(right.data(), right.size());
diff --git a/src/i-interactive-state-access.h b/src/i-interactive-state-access.h
new file mode 100644
index 000000000..f08450857
--- /dev/null
+++ b/src/i-interactive-state-access.h
@@ -0,0 +1,80 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef I_INTERACTIVE_STATE_ACCESS_H
+#define I_INTERACTIVE_STATE_ACCESS_H
+
+/// \file
+/// \brief State access interface
+
+#include <cstdint>
+#include <type_traits>
+
+#include "meta.h"
+
+namespace cartesi {
+
+/// \class i_interactive_state_access
+/// \brief Interface for interactive machine state access.
+/// \tparam DERIVED Derived class implementing the interface. (An example of CRTP.)
+template <typename DERIVED>
+class i_interactive_state_access { // CRTP
+
+    /// \brief Returns object cast as the derived class
+    DERIVED &derived() {
+        return *static_cast<DERIVED *>(this);
+    }
+
+    /// \brief Returns object cast as the derived class
+    const DERIVED &derived() const {
+        return *static_cast<const DERIVED *>(this);
+    }
+
+public:
+    /// \brief Wait for external interrupts requests.
+    /// \param mcycle Current value of mcycle.
+    /// \param mcycle_max Maximum mcycle after wait.
+    auto poll_external_interrupts(uint64_t mcycle, uint64_t mcycle_max) {
+        return derived().do_poll_external_interrupts(mcycle, mcycle_max);
+    }
+
+    /// \brief Returns true if soft yield HINT instruction is enabled at runtime
+    bool get_soft_yield() {
+        return derived().do_get_soft_yield();
+    }
+
+    /// \brief Reads a character from the console
+    /// \returns Character read if any, -1 otherwise
+    int getchar() {
+        return derived().do_getchar();
+    }
+
+    constexpr const char *get_name() const {
+        return derived().do_get_name();
+    }
+};
+
+/// \brief SFINAE test implementation of the i_state_access interface
+template <typename DERIVED>
+using is_an_i_interactive_state_access =
+    std::integral_constant<bool, is_template_base_of_v<i_interactive_state_access, std::remove_cvref_t<DERIVED>>>;
+
+template <typename DERIVED>
+constexpr bool is_an_i_interactive_state_access_v = is_an_i_interactive_state_access<DERIVED>::value;
+
+} // namespace cartesi
+
+#endif
diff --git a/src/i-state-access.h b/src/i-state-access.h
index 104e27d57..053330297 100644
--- a/src/i-state-access.h
+++ b/src/i-state-access.h
@@ -1070,7 +1070,7 @@ class i_state_access { // CRTP
     /// \warning T may or may not cross a Merkle tree word boundary starting from \p faddr!
     template <typename T, typename A = T>
     void read_memory_word(fast_addr faddr, uint64_t pma_index, T *pval) {
-        static_assert(std::is_integral<T>::value && sizeof(T) <= sizeof(uint64_t), "unsupported type");
+        static_assert(std::is_integral_v<T> && sizeof(T) <= sizeof(uint64_t), "unsupported type");
 #ifdef DUMP_STATE_ACCESS
         derived().template do_read_memory_word<T, A>(faddr, pma_index, pval);
         const char *fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
@@ -1093,7 +1093,7 @@ class i_state_access { // CRTP
     /// \warning T may or may not cross a Merkle tree word boundary starting from \p faddr!
     template <typename T, typename A = T>
     void write_memory_word(fast_addr faddr, uint64_t pma_index, T val) {
-        static_assert(std::is_integral<T>::value && sizeof(T) <= sizeof(uint64_t), "unsupported type");
+        static_assert(std::is_integral_v<T> && sizeof(T) <= sizeof(uint64_t), "unsupported type");
         derived().template do_write_memory_word<T, A>(faddr, pma_index, val);
 #ifdef DUMP_STATE_ACCESS
         const char *fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
@@ -1186,33 +1186,6 @@ class i_state_access { // CRTP
         derived().do_putchar(c);
     }
 
-    // ---
-    // These methods ONLY need to be implemented when state belongs to non-reproducible host machines
-    // ---
-
-    /// \brief Poll for external interrupts.
-    /// \param mcycle Current machine mcycle.
-    /// \param mcycle_max Maximum mcycle to wait for interrupts.
-    /// \returns A pair, the first value is the new machine mcycle advanced by the relative elapsed time while
-    /// polling, the second value is a boolean that is true when the poll is stopped due do an external interrupt
-    /// request.
-    /// \details When mcycle_max is greater than mcycle, this function will sleep until an external interrupt
-    /// is triggered or mcycle_max relative elapsed time is reached.
-    std::pair<uint64_t, bool> poll_external_interrupts(uint64_t mcycle, uint64_t mcycle_max) {
-        return derived().do_poll_external_interrupts(mcycle, mcycle_max);
-    }
-
-    /// \brief Returns true if soft yield HINT instruction is enabled at runtime
-    bool get_soft_yield() {
-        return derived().do_get_soft_yield();
-    }
-
-    /// \brief Reads a character from the console
-    /// \returns Character read if any, -1 otherwise
-    int getchar() {
-        return derived().do_getchar();
-    }
-
 #ifdef DUMP_COUNTERS
     //??D we should probably remove this from the interface
     auto &get_statistics() {
@@ -1225,22 +1198,6 @@ class i_state_access { // CRTP
     }
 
 protected:
-    /// \brief Default implementation when state does not belong to non-reproducible host machine
-    bool do_get_soft_yield() { // NOLINT(readability-convert-member-functions-to-static)
-        return false;
-    }
-
-    /// \brief Default implementation when state does not belong to non-reproducible host machine
-    std::pair<uint64_t, bool> do_poll_external_interrupts(uint64_t mcycle,
-        uint64_t /* mcycle_max */) { // NOLINT(readability-convert-member-functions-to-static)
-        return {mcycle, false};
-    }
-
-    /// \brief Default implementation when state does not belong to non-reproducible host machine
-    int do_getchar() { // NOLINT(readability-convert-member-functions-to-static)
-        return -1;
-    }
-
     /// \brief For state access classes that do not need annotations
     void do_push_begin_bracket(const char * /*text*/) {}
 
@@ -1258,7 +1215,10 @@ class i_state_access { // CRTP
 /// \brief SFINAE test implementation of the i_state_access interface
 template <typename DERIVED>
 using is_an_i_state_access =
-    std::integral_constant<bool, is_template_base_of<i_state_access, typename remove_cvref<DERIVED>::type>::value>;
+    std::integral_constant<bool, is_template_base_of_v<i_state_access, std::remove_cvref_t<DERIVED>>>;
+
+template <typename DERIVED>
+constexpr bool is_an_i_state_access_v = is_an_i_state_access<DERIVED>::value;
 
 } // namespace cartesi
 
diff --git a/src/interpret.cpp b/src/interpret.cpp
index 42a879860..442926ada 100644
--- a/src/interpret.cpp
+++ b/src/interpret.cpp
@@ -17,6 +17,7 @@
 #include <algorithm>
 #include <array>
 #include <cstdint>
+#include <tuple>
 #include <type_traits>
 #include <utility>
 
@@ -32,6 +33,7 @@
 
 #include "compiler-defines.h"
 #include "device-state-access.h"
+#include "i-interactive-state-access.h"
 #include "i-state-access.h"
 #include "machine-statistics.h"
 #include "tlb.h"
@@ -971,7 +973,7 @@ static NO_INLINE std::pair<bool, uint64_t> read_virtual_memory_slow(STATE_ACCESS
             device_state_access da(a, mcycle);
             // If we do not know how to read, we treat this as a PMA violation
             const bool status = pma.get_device_noexcept().get_driver()->read(pma.get_device_noexcept().get_context(),
-                &da, offset, &val, log2_size<U>::value);
+                &da, offset, &val, log2_size_v<U>);
             if (likely(status)) {
                 *pval = static_cast<T>(val);
                 // device logs its own state accesses
@@ -1058,7 +1060,7 @@ static NO_INLINE std::pair<execute_status, uint64_t> write_virtual_memory_slow(S
             const uint64_t offset = paddr - pma.get_start();
             device_state_access da(a, mcycle);
             auto status = pma.get_device_noexcept().get_driver()->write(pma.get_device_noexcept().get_context(), &da,
-                offset, static_cast<U>(static_cast<T>(val64)), log2_size<U>::value);
+                offset, static_cast<U>(static_cast<T>(val64)), log2_size_v<U>);
             // If we do not know how to write, we treat this as a PMA violation
             if (likely(status != execute_status::failure)) {
                 return {status, pc};
@@ -2757,6 +2759,7 @@ static FORCE_INLINE execute_status execute_MRET(STATE_ACCESS a, uint64_t &pc, ui
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_WFI(STATE_ACCESS a, uint64_t &pc, uint64_t &mcycle, uint32_t insn) {
     dump_insn(a, pc, insn, "wfi");
+    auto status = execute_status::success;
     // Check privileges and do nothing else
     auto prv = a.read_iprv();
     const uint64_t mstatus = a.read_mstatus();
@@ -2766,14 +2769,11 @@ static FORCE_INLINE execute_status execute_WFI(STATE_ACCESS a, uint64_t &pc, uin
     }
     // We wait for interrupts until the next timer interrupt.
     const uint64_t mcycle_max = rtc_time_to_cycle(a.read_clint_mtimecmp());
-    execute_status status = execute_status::success;
-    if (mcycle_max > mcycle) {
-        // Poll for external interrupts (e.g console or network),
-        // this may advance mcycle only when interactive mode is enabled
-        const auto [next_mcycle, interrupted] = a.poll_external_interrupts(mcycle, mcycle_max);
-        mcycle = next_mcycle;
-        if (interrupted) {
-            status = execute_status::success_and_serve_interrupts;
+    if constexpr (is_an_i_interactive_state_access_v<STATE_ACCESS>) {
+        if (mcycle_max > mcycle) {
+            // Poll for external interrupts (e.g console or network),
+            // this may advance mcycle only when interactive mode is enabled
+            std::tie(mcycle, status) = a.poll_external_interrupts(mcycle, mcycle_max);
         }
     }
     return advance_to_next_insn(a, pc, status);
@@ -3215,11 +3215,13 @@ static FORCE_INLINE execute_status execute_SRLIW(STATE_ACCESS a, uint64_t &pc, u
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_SRAIW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     dump_insn(a, pc, insn, "sraiw");
+    // When rd=0 the instruction is a HINT, and we consider it as a soft yield when rs1 == 31
     if constexpr (rd_kind == rd_kind::x0) {
-        // When rd=0 the instruction is a HINT, and we consider it as a soft yield when rs1 == 31
-        if (unlikely(insn_get_rs1(insn) == 31 && a.get_soft_yield())) {
-            // Force the main interpreter loop to break
-            return advance_to_next_insn(a, pc, execute_status::success_and_yield);
+        if constexpr (is_an_i_interactive_state_access_v<STATE_ACCESS>) {
+            if (unlikely(insn_get_rd(insn) == 0 && insn_get_rs1(insn) == 31 && a.get_soft_yield())) {
+                // Force the main interpreter loop to break
+                return advance_to_next_insn(a, pc, execute_status::success_and_yield);
+            }
         }
         return advance_to_next_insn(a, pc);
     }
@@ -5485,8 +5487,10 @@ static NO_INLINE execute_status interpret_loop(STATE_ACCESS a, uint64_t mcycle_e
             // Polling external interrupts only in WFI instructions is not enough
             // because Linux won't execute WFI instructions while under heavy load,
             // yet external interrupts still need to be triggered.
-            // Therefore we poll for external interrupt once a while in the interpreter loop.
-            a.poll_external_interrupts(mcycle, mcycle);
+            // Therefore we poll for external interrupt once in a while in the interpreter loop.
+            if constexpr (is_an_i_interactive_state_access_v<STATE_ACCESS>) {
+                a.poll_external_interrupts(mcycle, mcycle);
+            }
         }
 
         // Raise the highest priority pending interrupt, if any
@@ -6013,7 +6017,7 @@ static NO_INLINE execute_status interpret_loop(STATE_ACCESS a, uint64_t mcycle_e
 template <typename STATE_ACCESS>
 interpreter_break_reason interpret(STATE_ACCESS a, uint64_t mcycle_end) {
     static_assert(__BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__, "code assumes little-endian byte ordering");
-    static_assert(is_an_i_state_access<STATE_ACCESS>::value, "not an i_state_access");
+    static_assert(is_an_i_state_access_v<STATE_ACCESS>, "not an i_state_access");
 
     const uint64_t mcycle = a.read_mcycle();
 
diff --git a/src/machine.cpp b/src/machine.cpp
index 68447e514..26052f4cd 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -37,10 +37,10 @@
 #include "access-log.h"
 #include "bracket-note.h"
 #include "clint-factory.h"
+#include "device-state-access.h"
 #include "dtb.h"
 #include "htif-factory.h"
 #include "htif.h"
-#include "i-device-state-access.h"
 #include "interpret.h"
 #include "is-pristine.h"
 #include "machine-config.h"
@@ -56,6 +56,7 @@
 #include "replay-send-cmio-state-access.h"
 #include "replay-step-state-access.h"
 #include "riscv-constants.h"
+#include "rtc.h"
 #include "send-cmio-response.h"
 #include "shadow-pmas-factory.h"
 #include "shadow-state-factory.h"
@@ -2495,4 +2496,44 @@ interpreter_break_reason machine::run(uint64_t mcycle_end) {
     return interpret(a, mcycle_end);
 }
 
+//??D How come this function seems to never signal we have an inteerrupt???
+std::pair<uint64_t, execute_status> machine::poll_external_interrupts(uint64_t mcycle, uint64_t mcycle_max) {
+    const auto status = execute_status::success;
+    // Only poll external interrupts if we are in unreproducible mode
+    if (unlikely(m_s.iunrep)) {
+        // Convert the relative interval of cycles we can wait to the interval of host time we can wait
+        uint64_t timeout_us = (mcycle_max - mcycle) / RTC_CYCLES_PER_US;
+        int64_t start_us = 0;
+        if (timeout_us > 0) {
+            start_us = os_now_us();
+        }
+        state_access a(*this);
+        device_state_access da(a, mcycle);
+        // Poll virtio for events (e.g console stdin, network sockets)
+        // Timeout may be decremented in case a device has deadline timers (e.g network device)
+        if (has_virtio_devices() && has_virtio_console()) { // VirtIO + VirtIO console
+            poll_virtio_devices(&timeout_us, &da);
+            // VirtIO console device will poll TTY
+        } else if (has_virtio_devices()) { // VirtIO without a console
+            poll_virtio_devices(&timeout_us, &da);
+            if (has_htif_console()) { // VirtIO + HTIF console
+                // Poll tty without waiting more time, because the pool above should have waited enough time
+                os_poll_tty(0);
+            }
+        } else if (has_htif_console()) { // Only HTIF console
+            os_poll_tty(timeout_us);
+        } else if (timeout_us > 0) { // No interrupts to check, just keep the CPU idle
+            os_sleep_us(timeout_us);
+        }
+        // If timeout is greater than zero, we should also increment mcycle relative to the elapsed time
+        if (timeout_us > 0) {
+            const int64_t end_us = os_now_us();
+            const uint64_t elapsed_us = static_cast<uint64_t>(std::max(end_us - start_us, INT64_C(0)));
+            const uint64_t next_mcycle = mcycle + (elapsed_us * RTC_CYCLES_PER_US);
+            mcycle = std::min(std::max(next_mcycle, mcycle), mcycle_max);
+        }
+    }
+    return {mcycle, status};
+}
+
 } // namespace cartesi
diff --git a/src/machine.h b/src/machine.h
index 5ea27047f..26eca98aa 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -248,6 +248,16 @@ class machine final {
         return m_mrds;
     }
 
+    /// \brief Wait for external interrupts requests.
+    /// \param mcycle Current value of mcycle.
+    /// \param mcycle_max Maximum mcycle after wait.
+    /// \returns A pair {new_mcycle, status}, where new_mcycle gives new value for mcycle after wait,
+    /// and status will be execute_status::success_and_serve_interrupts if wait was stopped by an
+    /// external interrupt resquest.
+    /// \details When mcycle_max is greater than mcycle, this function will sleep until an external interrupt
+    /// is triggered or until the amount of time estimated for mcycle to reach mcycle_max has elapsed.
+    std::pair<uint64_t, execute_status> poll_external_interrupts(uint64_t mcycle, uint64_t mcycle_max);
+
     /// \brief Destructor.
     ~machine();
 
diff --git a/src/merkle-tree-proof.h b/src/merkle-tree-proof.h
index 14de54041..29d7597e5 100644
--- a/src/merkle-tree-proof.h
+++ b/src/merkle-tree-proof.h
@@ -191,8 +191,8 @@ class merkle_tree_proof final {
     ///< \return New root hash
     template <typename HASHER_TYPE>
     hash_type bubble_up(HASHER_TYPE &h, const hash_type &new_target_hash) const {
-        static_assert(is_an_i_hasher<HASHER_TYPE>::value, "not an i_hasher");
-        static_assert(std::is_same_v<typename remove_cvref<HASHER_TYPE>::type::hash_type, hash_type>,
+        static_assert(is_an_i_hasher_v<HASHER_TYPE>, "not an i_hasher");
+        static_assert(std::is_same_v<typename std::remove_cvref_t<HASHER_TYPE>::hash_type, hash_type>,
             "incompatible hash types");
         hash_type hash = new_target_hash;
         for (int log2_size = get_log2_target_size(); log2_size < get_log2_root_size(); ++log2_size) {
@@ -209,8 +209,8 @@ class merkle_tree_proof final {
     template <typename HASHER_TYPE>
     merkle_tree_proof<hash_type, address_type> slice(HASHER_TYPE &h, int new_log2_root_size,
         int new_log2_target_size) const {
-        static_assert(is_an_i_hasher<HASHER_TYPE>::value, "not an i_hasher");
-        static_assert(std::is_same_v<typename remove_cvref<HASHER_TYPE>::type::hash_type, hash_type>,
+        static_assert(is_an_i_hasher_v<HASHER_TYPE>, "not an i_hasher");
+        static_assert(std::is_same_v<typename std::remove_cvref_t<HASHER_TYPE>::hash_type, hash_type>,
             "incompatible hash types");
         if (new_log2_root_size <= 0) {
             throw std::out_of_range{"log2_root_size is not positive"};
diff --git a/src/meta.h b/src/meta.h
index c0d5023d7..1a1f28a10 100644
--- a/src/meta.h
+++ b/src/meta.h
@@ -42,14 +42,6 @@ struct is_template_base_of_helper {
 };
 } // namespace detail
 
-/// \class remove_cvref
-/// \brief Provides a member typedef type with reference and topmost cv-qualifiers removed.
-/// \note (This is directly available in C++20.)
-template <typename T>
-struct remove_cvref {
-    using type = std::remove_reference_t<std::remove_cv_t<T>>;
-};
-
 /// \class is_template_base_of
 /// \brief SFINAE test if class is derived from from a base template class.
 /// \tparam BASE Base template.
@@ -59,12 +51,18 @@ using is_template_base_of = std::integral_constant<bool,
     std::is_same_v<std::invoke_result_t<detail::is_template_base_of_helper<BASE, DERIVED>, const DERIVED &>,
         typename detail::is_template_base_of_helper<BASE, DERIVED>::yes>>;
 
+template <template <typename...> class BASE, typename DERIVED>
+constexpr bool is_template_base_of_v = is_template_base_of<BASE, DERIVED>::value;
+
 /// \class log2_size
 /// \brief Provides an int member value with the log<sub>2</sub> of size of \p T
 /// \param T Type from which the size is needed.
 template <typename T>
 struct log2_size {};
 
+template <typename T>
+constexpr int log2_size_v = log2_size<T>::value;
+
 /// \cond HIDDEN_SYMBOLS
 
 template <>
diff --git a/src/record-send-cmio-state-access.h b/src/record-send-cmio-state-access.h
index f9964a5f5..2c4be6565 100644
--- a/src/record-send-cmio-state-access.h
+++ b/src/record-send-cmio-state-access.h
@@ -84,7 +84,7 @@ class record_send_cmio_state_access : public i_state_access<record_send_cmio_sta
     /// \param paligned Physical address in the machine state, aligned to a 64-bit word.
     /// \param text Textual description of the access.
     void log_read(uint64_t paligned, const char *text) const {
-        static_assert(machine_merkle_tree::get_log2_word_size() >= log2_size<uint64_t>::value,
+        static_assert(machine_merkle_tree::get_log2_word_size() >= log2_size_v<uint64_t>,
             "Merkle tree word size must be at least as large as a machine word");
         if ((paligned & (sizeof(uint64_t) - 1)) != 0) {
             throw std::invalid_argument{"paligned is not aligned to word size"};
@@ -103,7 +103,7 @@ class record_send_cmio_state_access : public i_state_access<record_send_cmio_sta
 
         a.set_type(access_type::read);
         a.set_address(paligned);
-        a.set_log2_size(log2_size<uint64_t>::value);
+        a.set_log2_size(log2_size_v<uint64_t>);
         // NOLINTBEGIN(bugprone-unchecked-optional-access)
         // we log the leaf data at pleaf_aligned that contains the word at paligned
         a.get_read().emplace();
@@ -120,7 +120,7 @@ class record_send_cmio_state_access : public i_state_access<record_send_cmio_sta
     /// \param val Value to write.
     /// \param text Textual description of the access.
     void log_before_write(uint64_t paligned, uint64_t val, const char *text) {
-        static_assert(machine_merkle_tree::get_log2_word_size() >= log2_size<uint64_t>::value,
+        static_assert(machine_merkle_tree::get_log2_word_size() >= log2_size_v<uint64_t>,
             "Merkle tree word size must be at least as large as a machine word");
         if ((paligned & (sizeof(uint64_t) - 1)) != 0) {
             throw std::invalid_argument{"paligned is not aligned to word size"};
@@ -140,7 +140,7 @@ class record_send_cmio_state_access : public i_state_access<record_send_cmio_sta
 
         a.set_type(access_type::write);
         a.set_address(paligned);
-        a.set_log2_size(log2_size<uint64_t>::value);
+        a.set_log2_size(log2_size_v<uint64_t>);
         // NOLINTBEGIN(bugprone-unchecked-optional-access)
         // we log the entire leaf where the word is located
         a.get_read().emplace();
diff --git a/src/record-step-state-access.h b/src/record-step-state-access.h
index 626afe5f2..bc849acbf 100644
--- a/src/record-step-state-access.h
+++ b/src/record-step-state-access.h
@@ -22,7 +22,6 @@
 #include <vector>
 
 #include "compiler-defines.h"
-#include "device-state-access.h"
 #include "i-state-access.h"
 #include "machine.h"
 #include "shadow-pmas.h"
diff --git a/src/replay-send-cmio-state-access.h b/src/replay-send-cmio-state-access.h
index 418f5ef9e..36a028b9b 100644
--- a/src/replay-send-cmio-state-access.h
+++ b/src/replay-send-cmio-state-access.h
@@ -133,7 +133,7 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
     /// \param text Textual description of the access.
     /// \returns Value read.
     uint64_t check_read(uint64_t paligned, const char *text) {
-        static_assert(machine_merkle_tree::get_log2_word_size() >= log2_size<uint64_t>::value,
+        static_assert(machine_merkle_tree::get_log2_word_size() >= log2_size_v<uint64_t>,
             "Merkle tree word size must be at least as large as a machine word");
         if ((paligned & (sizeof(uint64_t) - 1)) != 0) {
             throw std::invalid_argument{"address not aligned to word size"};
@@ -151,7 +151,7 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
                 << "(" << std::dec << paligned << ")";
             throw std::invalid_argument{err.str()};
         }
-        if (access.get_log2_size() != log2_size<uint64_t>::value) {
+        if (access.get_log2_size() != log2_size_v<uint64_t>) {
             throw std::invalid_argument{"expected " + access_to_report() + " to read 2^" +
                 std::to_string(machine_merkle_tree::get_log2_word_size()) + " bytes from " + text};
         }
@@ -189,7 +189,7 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
     /// \param word Word value to write.
     /// \param text Textual description of the access.
     void check_write(uint64_t paligned, uint64_t word, const char *text) {
-        static_assert(machine_merkle_tree::get_log2_word_size() >= log2_size<uint64_t>::value,
+        static_assert(machine_merkle_tree::get_log2_word_size() >= log2_size_v<uint64_t>,
             "Merkle tree word size must be at least as large as a machine word");
         if ((paligned & (sizeof(uint64_t) - 1)) != 0) {
             throw std::invalid_argument{"paligned not aligned to word size"};
@@ -207,7 +207,7 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
                 << "(" << std::dec << paligned << ")";
             throw std::invalid_argument{err.str()};
         }
-        if (access.get_log2_size() != log2_size<uint64_t>::value) {
+        if (access.get_log2_size() != log2_size_v<uint64_t>) {
             throw std::invalid_argument{"expected " + access_to_report() + " to write 2^" +
                 std::to_string(machine_merkle_tree::get_log2_word_size()) + " bytes to " + text};
         }
diff --git a/src/replay-step-state-access.h b/src/replay-step-state-access.h
index 483840f5d..ff91d69f1 100644
--- a/src/replay-step-state-access.h
+++ b/src/replay-step-state-access.h
@@ -21,7 +21,6 @@
 #include <optional>
 
 #include "compiler-defines.h"
-#include "device-state-access.h"
 #include "host-addr.h"
 #include "i-state-access.h"
 #include "mock-pma-entry.h"
diff --git a/src/state-access.h b/src/state-access.h
index 5a8540bcb..aea1edf5f 100644
--- a/src/state-access.h
+++ b/src/state-access.h
@@ -27,8 +27,8 @@
 #include <utility>
 
 #include "compiler-defines.h"
-#include "device-state-access.h"
 #include "host-addr.h"
+#include "i-interactive-state-access.h"
 #include "i-state-access.h"
 #include "interpret.h"
 #include "machine-state.h"
@@ -37,7 +37,6 @@
 #include "pma-constants.h"
 #include "pma.h"
 #include "riscv-constants.h"
-#include "rtc.h"
 #include "shadow-tlb.h"
 #include "strict-aliasing.h"
 
@@ -63,7 +62,7 @@ struct i_state_access_fast_addr<state_access> {
 /// \class state_access
 /// \details The state_access class implements fast, direct
 /// access to the machine state. No logs are kept.
-class state_access : public i_state_access<state_access> {
+class state_access : public i_state_access<state_access>, public i_interactive_state_access<state_access> {
     // NOLINTNEXTLINE(cppcoreguidelines-avoid-const-or-ref-data-members)
     machine &m_m; ///< Associated machine
 
@@ -84,6 +83,7 @@ class state_access : public i_state_access<state_access> {
 
 private:
     friend i_state_access<state_access>;
+    friend i_interactive_state_access<state_access>;
 
     machine_state &do_get_naked_state() {
         return m_m.get_state();
@@ -506,59 +506,11 @@ class state_access : public i_state_access<state_access> {
         m_m.mark_dirty_page(haddr, pma_index);
     }
 
-    NO_INLINE std::pair<uint64_t, bool> do_poll_external_interrupts(uint64_t mcycle, uint64_t mcycle_max) {
-        bool interrupt_raised = false;
-        // Only poll external interrupts if we are in unreproducible mode
-        if (unlikely(do_read_iunrep())) {
-            // Convert the relative interval of cycles we can wait to the interval of host time we can wait
-            uint64_t timeout_us = (mcycle_max - mcycle) / RTC_CYCLES_PER_US;
-            int64_t start_us = 0;
-            if (timeout_us > 0) {
-                start_us = os_now_us();
-            }
-            device_state_access da(*this, mcycle);
-            // Poll virtio for events (e.g console stdin, network sockets)
-            // Timeout may be decremented in case a device has deadline timers (e.g network device)
-            if (m_m.has_virtio_devices() && m_m.has_virtio_console()) { // VirtIO + VirtIO console
-                interrupt_raised |= m_m.poll_virtio_devices(&timeout_us, &da);
-                // VirtIO console device will poll TTY
-            } else if (m_m.has_virtio_devices()) { // VirtIO without a console
-                interrupt_raised |= m_m.poll_virtio_devices(&timeout_us, &da);
-                if (m_m.has_htif_console()) { // VirtIO + HTIF console
-                    // Poll tty without waiting more time, because the pool above should have waited enough time
-                    interrupt_raised |= os_poll_tty(0);
-                }
-            } else if (m_m.has_htif_console()) { // Only HTIF console
-                interrupt_raised |= os_poll_tty(timeout_us);
-            } else if (timeout_us > 0) { // No interrupts to check, just keep the CPU idle
-                os_sleep_us(timeout_us);
-            }
-            // If timeout is greater than zero, we should also increment mcycle relative to the elapsed time
-            if (timeout_us > 0) {
-                const int64_t end_us = os_now_us();
-                const uint64_t elapsed_us = static_cast<uint64_t>(std::max(end_us - start_us, INT64_C(0)));
-                const uint64_t next_mcycle = mcycle + (elapsed_us * RTC_CYCLES_PER_US);
-                mcycle = std::min(std::max(next_mcycle, mcycle), mcycle_max);
-            }
-        }
-        return {mcycle, interrupt_raised};
-    }
-
-    bool do_get_soft_yield() {
-        return m_m.get_state().soft_yield;
-    }
-
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
     void do_putchar(uint8_t c) {
         os_putchar(c);
     }
 
-    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    int do_getchar() {
-        os_poll_tty(0);
-        return os_getchar();
-    }
-
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
     constexpr const char *do_get_name() const {
         return "state_access";
@@ -569,6 +521,24 @@ class state_access : public i_state_access<state_access> {
         return m_m.get_state().stats;
     }
 #endif
+
+    // -----
+    // i_intereactive_state_access interface implementation
+    // -----
+
+    NO_INLINE auto do_poll_external_interrupts(uint64_t mcycle, uint64_t mcycle_max) {
+        return m_m.poll_external_interrupts(mcycle, mcycle_max);
+    }
+
+    bool do_get_soft_yield() {
+        return m_m.get_state().soft_yield;
+    }
+
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    int do_getchar() {
+        os_poll_tty(0);
+        return os_getchar();
+    }
 };
 
 } // namespace cartesi
diff --git a/src/uarch-record-state-access.h b/src/uarch-record-state-access.h
index c6ad12cef..c4a1bd1d3 100644
--- a/src/uarch-record-state-access.h
+++ b/src/uarch-record-state-access.h
@@ -112,7 +112,7 @@ class uarch_record_state_access : public i_uarch_state_access<uarch_record_state
     }
 
     static std::pair<uint64_t, int> adjust_access(uint64_t paddr, int log2_size) {
-        static_assert(cartesi::log2_size<uint64_t>::value <= machine_merkle_tree::get_log2_word_size(),
+        static_assert(cartesi::log2_size_v<uint64_t> <= machine_merkle_tree::get_log2_word_size(),
             "Merkle tree word size must not be smaller than machine word size");
         if (((paddr >> log2_size) << log2_size) != paddr) {
             throw std::invalid_argument{"misaligned access"};
@@ -180,7 +180,7 @@ class uarch_record_state_access : public i_uarch_state_access<uarch_record_state
     }
 
     uint64_t log_read_word_access(uint64_t paddr, const char *text) const {
-        const auto log2_size = cartesi::log2_size<uint64_t>::value;
+        const auto log2_size = log2_size_v<uint64_t>;
         access a;
         log_access_type(a, access_type::read);
         log_access_range(a, paddr, log2_size);
@@ -225,7 +225,7 @@ class uarch_record_state_access : public i_uarch_state_access<uarch_record_state
 
     void log_write_reg_access(machine_reg reg, uint64_t val) {
         log_write_access(
-            machine_reg_address(reg), cartesi::log2_size<uint64_t>::value,
+            machine_reg_address(reg), log2_size_v<uint64_t>,
             [this, reg, val]() {
                 m_m.write_reg(reg, val);
                 if (!m_m.update_merkle_tree_page(machine_reg_address(reg))) {
@@ -283,7 +283,7 @@ class uarch_record_state_access : public i_uarch_state_access<uarch_record_state
             throw std::runtime_error("misaligned write to uarch");
         }
         log_write_access(
-            paddr, cartesi::log2_size<uint64_t>::value,
+            paddr, log2_size_v<uint64_t>,
             [this, paddr, val]() {
                 m_m.write_word(paddr, val);
                 if (!m_m.update_merkle_tree_page(paddr)) {
diff --git a/src/uarch-replay-state-access.h b/src/uarch-replay-state-access.h
index eb604e54c..a72b612e4 100644
--- a/src/uarch-replay-state-access.h
+++ b/src/uarch-replay-state-access.h
@@ -126,7 +126,7 @@ class uarch_replay_state_access : public i_uarch_state_access<uarch_replay_state
     }
 
     static std::pair<uint64_t, int> adjust_access(uint64_t paddr, int log2_size) {
-        static_assert(cartesi::log2_size<uint64_t>::value <= machine_merkle_tree::get_log2_word_size(),
+        static_assert(cartesi::log2_size_v<uint64_t> <= machine_merkle_tree::get_log2_word_size(),
             "Merkle tree word size must not be smaller than machine word size");
         const auto log2_word_size = machine_merkle_tree::get_log2_word_size();
         const auto log2_access_size = std::max(log2_size, log2_word_size);
@@ -249,7 +249,7 @@ class uarch_replay_state_access : public i_uarch_state_access<uarch_replay_state
     }
 
     void check_write_word_access(uint64_t paddr, uint64_t val, const char *text) {
-        const auto log2_size = cartesi::log2_size<uint64_t>::value;
+        const auto log2_size = log2_size_v<uint64_t>;
         const auto &a = check_access(text);
         check_access_type(a, access_type::write, text);
         check_access_range(a, access_type::write, paddr, log2_size, text);
@@ -265,7 +265,7 @@ class uarch_replay_state_access : public i_uarch_state_access<uarch_replay_state
     }
 
     uint64_t check_read_word_access(uint64_t paddr, const char *text) {
-        const auto log2_size = cartesi::log2_size<uint64_t>::value;
+        const auto log2_size = log2_size_v<uint64_t>;
         const auto &a = check_access(text);
         check_access_type(a, access_type::read, text);
         check_access_range(a, access_type::read, paddr, log2_size, text);
diff --git a/uarch/Makefile b/uarch/Makefile
index 273811c30..ba20dd7cb 100644
--- a/uarch/Makefile
+++ b/uarch/Makefile
@@ -15,11 +15,13 @@ THIRD_PARTY_DIR := ../third-party
 
 ifeq ($(UNAME),Darwin)
 HOST_CXX := clang++
+HOST_CC := clang
 else
 HOST_CXX := g++
+HOST_CC := gcc
 endif
-
 HOST_CFLAGS := -I$(THIRD_PARTY_DIR)/tiny_sha3 -I$(EMULATOR_SRC_DIR)
+HOST_CXXFLAGS := -std=c++20
 
 CC := $(TOOLCHAIN_PREFIX)gcc
 LD := $(TOOLCHAIN_PREFIX)ld
@@ -65,29 +67,28 @@ UARCH_SOURCES=\
 	uarch-runtime.cpp
 
 EMULATOR_SOURCES=\
-	interpret.cpp \
-	pma-driver.cpp \
-	htif.cpp \
-	shadow-tlb.cpp \
-	shadow-state.cpp \
-	shadow-uarch-state.cpp \
-	plic.cpp \
-	clint.cpp
-
-COMPUTE_UARCH_CPP_SOURCES=\
+	$(EMULATOR_SRC_DIR)/interpret.cpp \
+	$(EMULATOR_SRC_DIR)/pma-driver.cpp \
+	$(EMULATOR_SRC_DIR)/htif.cpp \
+	$(EMULATOR_SRC_DIR)/shadow-tlb.cpp \
+	$(EMULATOR_SRC_DIR)/shadow-state.cpp \
+	$(EMULATOR_SRC_DIR)/shadow-uarch-state.cpp \
+	$(EMULATOR_SRC_DIR)/plic.cpp \
+	$(EMULATOR_SRC_DIR)/clint.cpp
+
+COMPUTE_SOURCES=\
 	compute-uarch-pristine-hash.cpp \
 	$(EMULATOR_SRC_DIR)/machine-merkle-tree.cpp \
 	$(EMULATOR_SRC_DIR)/back-merkle-tree.cpp \
 	$(EMULATOR_SRC_DIR)/pristine-merkle-tree.cpp \
 	$(EMULATOR_SRC_DIR)/complete-merkle-tree.cpp \
-	$(EMULATOR_SRC_DIR)/full-merkle-tree.cpp
-
-COMPUTE_UARCH_C_SOURCES=\
+	$(EMULATOR_SRC_DIR)/full-merkle-tree.cpp \
 	$(THIRD_PARTY_DIR)/tiny_sha3/sha3.c \
 	uarch-pristine-ram.c
 
 UARCH_OBJS = $(patsubst %.c,%.uarch_c.o,$(patsubst %.cpp,%.uarch_cpp.o,$(UARCH_SOURCES)))
 EMULATOR_OBJS = $(patsubst %.c,%.emulator_c.o,$(patsubst %.cpp,%.emulator_cpp.o,$(EMULATOR_SOURCES)))
+COMPUTE_OBJS = $(patsubst %.c,%.compute_c.o,$(patsubst %.cpp,%.compute_cpp.o,$(COMPUTE_SOURCES)))
 
 LINTER_IGNORE_SOURCES=uarch-printf.c uarch-pristine-hash.c uarch-pristine-ram.c
 LINTER_IGNORE_HEADERS=uarch-printf.h
@@ -103,10 +104,10 @@ CLANG_TIDY_TARGETS=$(patsubst %.cpp,%.clang-tidy,$(patsubst %.c,%.clang-tidy,$(L
 
 all: uarch-ram.bin uarch-pristine-ram.c uarch-pristine-hash.c validate-instruction-set
 
-compute-uarch-pristine-hash: $(COMPUTE_UARCH_CPP_SOURCES) $(COMPUTE_UARCH_C_SOURCES)
-	$(HOST_CXX) $(HOST_CFLAGS) -o $@ -x c $(COMPUTE_UARCH_C_SOURCES) -x c++ $(COMPUTE_UARCH_CPP_SOURCES)
+compute-uarch-pristine-hash: $(COMPUTE_OBJS)
+	$(HOST_CXX) $(HOST_CFLAGS) $(HOST_CXXFLAGS) -o $@ $^
 
-uarch-pristine-hash.c:  compute-uarch-pristine-hash
+uarch-pristine-hash.c: compute-uarch-pristine-hash
 	./compute-uarch-pristine-hash > $@
 
 uarch-pristine-ram.c: uarch-ram.bin
@@ -134,16 +135,22 @@ uarch-ram.elf: $(EMULATOR_OBJS) $(UARCH_OBJS) uarch-ram-entry.o uarch-ram.ld
 	$(CXX) $(CFLAGS) $(CXXFLAGS) -Wl,-Tuarch-ram.ld  -o $@ $(EMULATOR_OBJS) $(UARCH_OBJS) uarch-ram-entry.o $(TOOLCHAIN_LIBS)
 
 uarch-ram-entry.o: uarch-ram-entry.S
-	$(CC) $(CFLAGS) -c -o $@ $(<F)
+	$(CC) $(CFLAGS) -c -o $@ $<
+
+%.compute_cpp.o: %.cpp
+	$(HOST_CXX) $(HOST_CFLAGS) $(HOST_CXXFLAGS) -c -o $@ $<
+
+%.compute_c.o: %.c
+	$(HOST_CC) $(HOST_CFLAGS) -c -o $@ $<
 
-%.emulator_cpp.o: $(EMULATOR_SRC_DIR)/%.cpp
-	$(CXX) $(CFLAGS) $(CXXFLAGS) -c -o $@ $(EMULATOR_SRC_DIR)/$(<F)
+%.emulator_cpp.o: %.cpp
+	$(CXX) $(CFLAGS) $(CXXFLAGS) -c -o $@ $<
 
 %.uarch_c.o: %.c
-	$(CC) $(CFLAGS) -c -o $@ $(<F)
+	$(CC) $(CFLAGS) -c -o $@ $<
 
 %.uarch_cpp.o: %.cpp
-	$(CXX) $(CFLAGS) $(CXXFLAGS) -c -o $@ $(<F)
+	$(CXX) $(CFLAGS) $(CXXFLAGS) -c -o $@ $<
 
 %.ld: %.ld.in
 	$(CC) -o $(@F).tmp -x c $(CFLAGS) -E $(^F)
@@ -162,4 +169,4 @@ clean-auto-generated:
 	@rm -f uarch-pristine-hash.c uarch-pristine-ram.c
 
 clean: clean-executables clean-auto-generated
-	@rm -f *.ld *.elf *.bin *.tmp link.ld *.o *.clang-tidy *.insn.txt *.objdump
+	@rm -f *.ld *.elf *.bin *.tmp link.ld $(UARCH_OBJS) $(EMULATOR_OBJS) $(COMPUTE_OBJS) *.clang-tidy *.insn.txt *.objdump

From 63bc215384b08365f8ec5e84a8c4e4c68d8cc73d Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Mon, 3 Feb 2025 17:01:37 +0000
Subject: [PATCH 08/82] refactor: split out i-accept-scoped-note.h

---
 src/Makefile                              |   1 +
 src/i-accept-scoped-note.h                | 103 ++++++++++++++++++++++
 src/i-interactive-state-access.h          |   4 -
 src/i-state-access.h                      |  39 --------
 src/i-uarch-state-access.h                |  40 ---------
 src/interpret.cpp                         |   3 +-
 src/record-send-cmio-state-access.h       |  40 +++++----
 src/record-step-state-access.h            |  28 +++---
 src/replay-step-state-access.h            |  51 +++++------
 src/state-access.h                        |  24 +++--
 src/uarch-record-state-access.h           |  40 +++++----
 src/uarch-replay-state-access.h           |  52 ++++++-----
 src/uarch-state-access.h                  |  20 ++---
 uarch/machine-uarch-bridge-state-access.h |  52 +++++------
 14 files changed, 253 insertions(+), 244 deletions(-)
 create mode 100644 src/i-accept-scoped-note.h

diff --git a/src/Makefile b/src/Makefile
index 08b00ae82..542ee0c9a 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -183,6 +183,7 @@ ifeq ($(dump),yes)
 #DUMP_DEFS+=-DDUMP_INVALID_MEM_ACCESS
 #DUMP_DEFS+=-DDUMP_INVALID_CSR
 #DUMP_DEFS+=-DDUMP_INSN
+DUMP_DEFS+=-DDUMP_SCOPED_NOTE
 DUMP_DEFS+=-DDUMP_STATE_ACCESS
 DUMP_DEFS+=-DDUMP_UARCH_STATE_ACCESS
 #DUMP_DEFS+=-DDUMP_REGS
diff --git a/src/i-accept-scoped-note.h b/src/i-accept-scoped-note.h
new file mode 100644
index 000000000..a812a3a4d
--- /dev/null
+++ b/src/i-accept-scoped-note.h
@@ -0,0 +1,103 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef I_ACCEPT_SCOPED_NOTE_H
+#define I_ACCEPT_SCOPED_NOTE_H
+
+/// \file
+/// \brief State access interface
+
+#include <cstdint>
+#include <type_traits>
+
+#include "meta.h"
+#include "scoped-note.h"
+
+namespace cartesi {
+
+/// \class i_accept_scoped_note
+/// \brief Interface that lets a state access accept scoped notes.
+/// \tparam DERIVED Derived class implementing the interface. (An example of CRTP.)
+template <typename DERIVED>
+class i_accept_scoped_note { // CRTP
+
+    /// \brief Returns object cast as the derived class
+    DERIVED &derived() {
+        return *static_cast<DERIVED *>(this);
+    }
+
+    /// \brief Returns object cast as the derived class
+    const DERIVED &derived() const {
+        return *static_cast<const DERIVED *>(this);
+    }
+
+public:
+    /// \brief Adds a begin bracket annotation to the log
+    /// \param text String with the text for the annotation
+    void push_begin_bracket(const char *text) {
+#ifdef DUMP_SCOPED_NOTE
+        fprintf(stderr, "----> begin %s (%s)\n", text, derived().get_name());
+#endif
+        return derived().do_push_begin_bracket(text);
+    }
+
+    /// \brief Adds an end bracket annotation to the log
+    /// \param text String with the text for the annotation
+    void push_end_bracket(const char *text) {
+#ifdef DUMP_SCOPED_NOTE
+        fprintf(stderr, "<---- end %s (%s)\n", text, derived().get_name());
+#endif
+        return derived().do_push_end_bracket(text);
+    }
+
+    /// \brief Adds annotations to the state, bracketing a scope
+    /// \param text String with the text for the annotation
+    /// \returns An object that, when constructed and destroyed issues an annonation.
+    auto make_scoped_note(const char *text) {
+        return derived().do_make_scoped_note(text);
+    }
+
+protected:
+    // Default implementation for classes that do not use scoped notes
+    // (It still will dump the scoped notes when requested)
+    auto do_make_scoped_note([[maybe_unused]] const char *text) {
+#ifdef DUMP_SCOPED_NOTE
+        return scoped_note{*this, text};
+#else
+        return 0;
+#endif
+    }
+
+    void do_push_begin_bracket(const char * /*text*/) {
+        ;
+    }
+
+    void do_push_end_bracket(const char * /*text*/) {
+        ;
+    }
+};
+
+/// \brief SFINAE test implementation of the i_state_access interface
+template <typename DERIVED>
+using is_an_i_accept_scoped_note =
+    std::integral_constant<bool, is_template_base_of_v<i_accept_scoped_note, std::remove_cvref_t<DERIVED>>>;
+
+template <typename DERIVED>
+constexpr bool is_an_i_accept_scoped_note_v = is_an_i_accept_scoped_note<DERIVED>::value;
+
+} // namespace cartesi
+
+#endif
diff --git a/src/i-interactive-state-access.h b/src/i-interactive-state-access.h
index f08450857..3b1024be3 100644
--- a/src/i-interactive-state-access.h
+++ b/src/i-interactive-state-access.h
@@ -61,10 +61,6 @@ class i_interactive_state_access { // CRTP
     int getchar() {
         return derived().do_getchar();
     }
-
-    constexpr const char *get_name() const {
-        return derived().do_get_name();
-    }
 };
 
 /// \brief SFINAE test implementation of the i_state_access interface
diff --git a/src/i-state-access.h b/src/i-state-access.h
index 053330297..29b0c17d9 100644
--- a/src/i-state-access.h
+++ b/src/i-state-access.h
@@ -95,31 +95,6 @@ class i_state_access { // CRTP
         return derived().do_get_naked_state();
     }
 
-    /// \brief Adds a begin bracket annotation to the log
-    /// \param text String with the text for the annotation
-    void push_begin_bracket(const char *text) {
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "----> begin %s (%s)\n", text, get_name());
-#endif
-        return derived().do_push_begin_bracket(text);
-    }
-
-    /// \brief Adds an end bracket annotation to the log
-    /// \param text String with the text for the annotation
-    void push_end_bracket(const char *text) {
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "<---- end %s (%s)\n", text, get_name());
-#endif
-        return derived().do_push_end_bracket(text);
-    }
-
-    /// \brief Adds annotations to the state, bracketing a scope
-    /// \param text String with the text for the annotation
-    /// \returns An object that, when constructed and destroyed issues an annonation.
-    auto make_scoped_note(const char *text) {
-        return derived().do_make_scoped_note(text);
-    }
-
     /// \brief Reads from general-purpose register.
     /// \param i Register index.
     /// \returns Register value.
@@ -1196,20 +1171,6 @@ class i_state_access { // CRTP
     constexpr const char *get_name() const {
         return derived().do_get_name();
     }
-
-protected:
-    /// \brief For state access classes that do not need annotations
-    void do_push_begin_bracket(const char * /*text*/) {}
-
-    /// \brief For state access classes that do not need annotations
-    void do_push_end_bracket(const char * /*text*/) {}
-
-#ifndef DUMP_STATE_ACCESS
-    /// \brief For state access classes that do not need annotations
-    int do_make_scoped_note(const char * /*text*/) {
-        return 0;
-    }
-#endif
 };
 
 /// \brief SFINAE test implementation of the i_state_access interface
diff --git a/src/i-uarch-state-access.h b/src/i-uarch-state-access.h
index 875fe7f35..c0dd46bda 100644
--- a/src/i-uarch-state-access.h
+++ b/src/i-uarch-state-access.h
@@ -19,7 +19,6 @@
 
 #include <cstdint>
 
-#include "bracket-note.h"
 #include "tlb.h"
 
 namespace cartesi {
@@ -39,31 +38,6 @@ class i_uarch_state_access { // CRTP
     }
 
 public:
-    /// \brief Adds a begin bracket annotation to the log
-    /// \param text String with the text for the annotation
-    void push_begin_bracket(const char *text) {
-#ifdef DUMP_UARCH_STATE_ACCESS
-        printf("----> begin %s (%s)\n", text, get_name());
-#endif
-        return derived().do_push_begin_bracket(text);
-    }
-
-    /// \brief Adds an end bracket annotation to the log
-    /// \param text String with the text for the annotation
-    void push_end_bracket(const char *text) {
-#ifdef DUMP_UARCH_STATE_ACCESS
-        printf("<---- end %s (%s)\n", text, get_name());
-#endif
-        return derived().do_push_end_bracket(text);
-    }
-
-    /// \brief Adds annotations to the state, bracketing a scope
-    /// \param text String with the text for the annotation
-    /// \returns An object that, when constructed and destroyed issues an annonation.
-    auto make_scoped_note(const char *text) {
-        return derived().do_make_scoped_note(text);
-    }
-
     auto read_x(int i) {
 #ifdef DUMP_UARCH_STATE_ACCESS
         const auto val = derived().do_read_x(i);
@@ -170,20 +144,6 @@ class i_uarch_state_access { // CRTP
     constexpr const char *get_name() const {
         return derived().do_get_name();
     }
-
-private:
-    /// \brief For state access classes that do not need annotations
-    void do_push_begin_bracket(const char * /*text*/) {}
-
-    /// \brief For state access classes that do not need annotations
-    void do_push_end_bracket(const char * /*text*/) {}
-
-#ifndef DUMP_UARCH_STATE_ACCESS
-    /// \brief For state access classes that do not need annotations
-    int do_make_scoped_note(const char * /*text*/) {
-        return 0;
-    }
-#endif
 };
 
 } // namespace cartesi
diff --git a/src/interpret.cpp b/src/interpret.cpp
index 442926ada..bd8f418de 100644
--- a/src/interpret.cpp
+++ b/src/interpret.cpp
@@ -6018,6 +6018,7 @@ template <typename STATE_ACCESS>
 interpreter_break_reason interpret(STATE_ACCESS a, uint64_t mcycle_end) {
     static_assert(__BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__, "code assumes little-endian byte ordering");
     static_assert(is_an_i_state_access_v<STATE_ACCESS>, "not an i_state_access");
+    static_assert(is_an_i_accept_scoped_note_v<STATE_ACCESS>, "not an i_accept_scoped_note");
 
     const uint64_t mcycle = a.read_mcycle();
 
@@ -6055,7 +6056,7 @@ interpreter_break_reason interpret(STATE_ACCESS a, uint64_t mcycle_end) {
     }
     if (status == execute_status::success_and_yield) {
         return interpreter_break_reason::yielded_softly;
-    } // Reached mcycle_end
+    }                                      // Reached mcycle_end
     assert(a.read_mcycle() == mcycle_end); // LCOV_EXCL_LINE
     return interpreter_break_reason::reached_target_mcycle;
 }
diff --git a/src/record-send-cmio-state-access.h b/src/record-send-cmio-state-access.h
index 2c4be6565..093bc0abb 100644
--- a/src/record-send-cmio-state-access.h
+++ b/src/record-send-cmio-state-access.h
@@ -28,6 +28,7 @@
 
 #include "access-log.h"
 #include "host-addr.h"
+#include "i-accept-scoped-note.h"
 #include "i-hasher.h"
 #include "i-state-access.h"
 #include "machine-merkle-tree.h"
@@ -35,7 +36,6 @@
 #include "machine.h"
 #include "meta.h"
 #include "pma.h"
-#include "scoped-note.h"
 #include "shadow-state.h"
 
 namespace cartesi {
@@ -56,7 +56,9 @@ struct i_state_access_fast_addr<record_send_cmio_state_access> {
 /// \class record_send_cmio_state_access
 /// \details This records all state accesses that happen during the execution of
 /// a machine::send_cmio_response() function call
-class record_send_cmio_state_access : public i_state_access<record_send_cmio_state_access> {
+class record_send_cmio_state_access :
+    public i_state_access<record_send_cmio_state_access>,
+    public i_accept_scoped_note<record_send_cmio_state_access> {
     using hasher_type = machine_merkle_tree::hasher_type;
     using hash_type = machine_merkle_tree::hash_type;
     // NOLINTBEGIN(cppcoreguidelines-avoid-const-or-ref-data-members)
@@ -78,8 +80,6 @@ class record_send_cmio_state_access : public i_state_access<record_send_cmio_sta
     }
 
 private:
-    friend i_state_access<record_send_cmio_state_access>;
-
     /// \brief Logs a read access of a uint64_t word from the machine state.
     /// \param paligned Physical address in the machine state, aligned to a 64-bit word.
     /// \param text Textual description of the access.
@@ -185,17 +185,10 @@ class record_send_cmio_state_access : public i_state_access<record_send_cmio_sta
         update_after_write(paligned);
     }
 
-    void do_push_begin_bracket(const char *text) {
-        m_log.push_begin_bracket(text);
-    }
-
-    void do_push_end_bracket(const char *text) {
-        m_log.push_end_bracket(text);
-    }
-
-    auto do_make_scoped_note(const char *text) {
-        return scoped_note<record_send_cmio_state_access>{*this, text};
-    }
+    // -----
+    // i_state_access interface implementation
+    // -----
+    friend i_state_access<record_send_cmio_state_access>;
 
     void do_write_iflags_Y(uint64_t val) {
         log_before_write_write_and_update(machine_reg_address(machine_reg::iflags_Y), m_m.get_state().iflags.Y, val,
@@ -276,6 +269,23 @@ class record_send_cmio_state_access : public i_state_access<record_send_cmio_sta
     constexpr const char *do_get_name() const {
         return "record_send_cmio_state_access";
     }
+
+    // -----
+    // i_accept_scoped_note interface implementation
+    // -----
+    friend i_accept_scoped_note<record_send_cmio_state_access>;
+
+    void do_push_begin_bracket(const char *text) {
+        m_log.push_begin_bracket(text);
+    }
+
+    void do_push_end_bracket(const char *text) {
+        m_log.push_end_bracket(text);
+    }
+
+    auto do_make_scoped_note(const char *text) {
+        return scoped_note{*this, text};
+    }
 };
 
 } // namespace cartesi
diff --git a/src/record-step-state-access.h b/src/record-step-state-access.h
index bc849acbf..6c06adce7 100644
--- a/src/record-step-state-access.h
+++ b/src/record-step-state-access.h
@@ -22,16 +22,13 @@
 #include <vector>
 
 #include "compiler-defines.h"
+#include "i-accept-scoped-note.h"
 #include "i-state-access.h"
 #include "machine.h"
 #include "shadow-pmas.h"
 #include "shadow-tlb.h"
 #include "unique-c-ptr.h"
 
-#if DUMP_STATE_ACCESS
-#include "scoped-note.h"
-#endif
-
 namespace cartesi {
 
 class record_step_state_access;
@@ -49,7 +46,9 @@ struct i_state_access_fast_addr<record_step_state_access> {
 
 /// \class record_step_state_access
 /// \brief Records machine state access into a step log file
-class record_step_state_access : public i_state_access<record_step_state_access> {
+class record_step_state_access :
+    public i_state_access<record_step_state_access>,
+    public i_accept_scoped_note<record_step_state_access> {
     constexpr static int TREE_LOG2_ROOT_SIZE = machine_merkle_tree::get_log2_root_size();
     constexpr static int TREE_LOG2_PAGE_SIZE = machine_merkle_tree::get_log2_page_size();
     constexpr static uint64_t TREE_PAGE_SIZE = UINT64_C(1) << LOG2_PAGE_SIZE;
@@ -133,7 +132,6 @@ class record_step_state_access : public i_state_access<record_step_state_access>
 private:
     using pma_entry_type = pma_entry;
     using fast_addr_type = host_addr;
-    friend i_state_access<record_step_state_access>;
 
     /// \brief Mark a page as touched and save its contents
     /// \param address address of the page
@@ -202,18 +200,10 @@ class record_step_state_access : public i_state_access<record_step_state_access>
         return m_m.read_shadow_tlb(set_index, slot_index, what);
     }
 
-    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    void do_push_begin_bracket(const char * /*text*/) {}
-
-    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    void do_push_end_bracket(const char * /*text*/) {}
-
-#ifdef DUMP_STATE_ACCESS
-    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    auto do_make_scoped_note([[maybe_unused]] const char *text) {
-        return scoped_note<record_step_state_access>{*this, text};
-    }
-#endif
+    // -----
+    // i_state_access interface implementation
+    // -----
+    friend i_state_access<record_step_state_access>;
 
     uint64_t do_read_x(int i) const {
         return log_read_reg(machine_reg_enum(machine_reg::x0, i));
@@ -593,6 +583,7 @@ class record_step_state_access : public i_state_access<record_step_state_access>
         return log_read_tlb(SET, slot_index, shadow_tlb_what::pma_index);
     }
 
+    //??D This is still a bit too complicated for my taste
     template <TLB_set_index SET>
     host_addr do_read_tlb_vp_offset(uint64_t slot_index) {
         // During initialization, replay_step_state_access translates all vp_offset to corresponding vh_offset
@@ -616,6 +607,7 @@ class record_step_state_access : public i_state_access<record_step_state_access>
         return vh_offset;
     }
 
+    //??D This is still a bit too complicated for my taste
     template <TLB_set_index SET>
     void do_write_tlb(uint64_t slot_index, uint64_t vaddr_page, host_addr vh_offset, uint64_t pma_index) {
         // During initialization, replay_step_state_access translates all vp_offset to corresponding vh_offset
diff --git a/src/replay-step-state-access.h b/src/replay-step-state-access.h
index ff91d69f1..a51f915c6 100644
--- a/src/replay-step-state-access.h
+++ b/src/replay-step-state-access.h
@@ -22,6 +22,7 @@
 
 #include "compiler-defines.h"
 #include "host-addr.h"
+#include "i-accept-scoped-note.h"
 #include "i-state-access.h"
 #include "mock-pma-entry.h"
 #include "pma-constants.h"
@@ -35,10 +36,6 @@
 #include "uarch-constants.h"
 #include "uarch-defines.h"
 
-#if DUMP_STATE_ACCESS
-#include "scoped-note.h"
-#endif
-
 namespace cartesi {
 
 // \file this code is designed to be compiled for a free-standing environment.
@@ -77,7 +74,9 @@ static inline bool validate_and_advance_offset(uint64_t max, uint64_t current, u
 }
 
 // \brief Provides machine state from a step log file
-class replay_step_state_access : public i_state_access<replay_step_state_access> {
+class replay_step_state_access :
+    public i_state_access<replay_step_state_access>,
+    public i_accept_scoped_note<replay_step_state_access> {
 public:
     using address_type = uint64_t;
     using data_type = unsigned char[PMA_PAGE_SIZE];
@@ -199,12 +198,6 @@ class replay_step_state_access : public i_state_access<replay_step_state_access>
     }
 
 private:
-    friend i_state_access<replay_step_state_access>;
-
-    void do_putchar(uint8_t /*c*/) { // NOLINT(readability-convert-member-functions-to-static)
-        ;                            // do nothing
-    }
-
     /// \brief Try to find a page in the logged data by its physical address
     /// \param paddr The physical address of the page
     /// \return A pointer to the page_type structure if found, nullptr otherwise
@@ -409,13 +402,6 @@ class replay_step_state_access : public i_state_access<replay_step_state_access>
         // NOLINTEND(cppcoreguidelines-pro-type-reinterpret-cast))
     }
 
-#ifdef DUMP_STATE_ACCESS
-    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    auto do_make_scoped_note([[maybe_unused]] const char *text) {
-        return scoped_note<replay_step_state_access>{*this, text};
-    }
-#endif
-
     //??D we should probably optimize access to the shadow so it doesn't perform a translation every time
     // We can do this by caching the vh_offset trasnslation of the processor shadow page. This is easy if
     // static_assert(sizeof(shadow_state) <= PMA_PAGE_SIZE, "shadow state must fit in single page");
@@ -432,6 +418,21 @@ class replay_step_state_access : public i_state_access<replay_step_state_access>
         aliased_aligned_write<uint64_t>(haddr, val);
     }
 
+    uint64_t read_pma_istart(uint64_t index) {
+        const auto haddr = do_get_faddr(shadow_pmas_get_pma_abs_addr(index, shadow_pmas_what::istart));
+        return aliased_aligned_read<uint64_t>(haddr);
+    }
+
+    uint64_t read_pma_ilength(uint64_t index) {
+        const auto haddr = do_get_faddr(shadow_pmas_get_pma_abs_addr(index, shadow_pmas_what::ilength));
+        return aliased_aligned_read<uint64_t>(haddr);
+    }
+
+    // -----
+    // i_state_access interface implementation
+    // -----
+    friend i_state_access<replay_step_state_access>;
+
     uint64_t do_read_x(int i) {
         return check_read_reg(machine_reg_enum(machine_reg::x0, i));
     }
@@ -777,16 +778,6 @@ class replay_step_state_access : public i_state_access<replay_step_state_access>
         return false;
     }
 
-    uint64_t read_pma_istart(uint64_t index) {
-        const auto haddr = do_get_faddr(shadow_pmas_get_pma_abs_addr(index, shadow_pmas_what::istart));
-        return aliased_aligned_read<uint64_t>(haddr);
-    }
-
-    uint64_t read_pma_ilength(uint64_t index) {
-        const auto haddr = do_get_faddr(shadow_pmas_get_pma_abs_addr(index, shadow_pmas_what::ilength));
-        return aliased_aligned_read<uint64_t>(haddr);
-    }
-
     mock_pma_entry &do_read_pma_entry(uint64_t index) {
         assert(index < PMA_MAX);
         // record_step_state_access will have recorded the access to istart and
@@ -847,6 +838,10 @@ class replay_step_state_access : public i_state_access<replay_step_state_access>
         check_write_tlb(SET, slot_index, shadow_tlb_what::pma_index, pma_index);
     }
 
+    void do_putchar(uint8_t /*c*/) { // NOLINT(readability-convert-member-functions-to-static)
+        ;                            // do nothing
+    }
+
     void do_mark_dirty_page(host_addr /* haddr */, uint64_t /* pma_index */) {
         // this is a noop since we have no host machine
     }
diff --git a/src/state-access.h b/src/state-access.h
index aea1edf5f..ffa98c7b2 100644
--- a/src/state-access.h
+++ b/src/state-access.h
@@ -28,6 +28,7 @@
 
 #include "compiler-defines.h"
 #include "host-addr.h"
+#include "i-accept-scoped-note.h"
 #include "i-interactive-state-access.h"
 #include "i-state-access.h"
 #include "interpret.h"
@@ -40,10 +41,6 @@
 #include "shadow-tlb.h"
 #include "strict-aliasing.h"
 
-#if DUMP_STATE_ACCESS
-#include "scoped-note.h"
-#endif
-
 namespace cartesi {
 
 class state_access;
@@ -62,7 +59,10 @@ struct i_state_access_fast_addr<state_access> {
 /// \class state_access
 /// \details The state_access class implements fast, direct
 /// access to the machine state. No logs are kept.
-class state_access : public i_state_access<state_access>, public i_interactive_state_access<state_access> {
+class state_access :
+    public i_state_access<state_access>,
+    public i_interactive_state_access<state_access>,
+    public i_accept_scoped_note<state_access> {
     // NOLINTNEXTLINE(cppcoreguidelines-avoid-const-or-ref-data-members)
     machine &m_m; ///< Associated machine
 
@@ -82,19 +82,14 @@ class state_access : public i_state_access<state_access>, public i_interactive_s
     }
 
 private:
-    friend i_state_access<state_access>;
-    friend i_interactive_state_access<state_access>;
-
     machine_state &do_get_naked_state() {
         return m_m.get_state();
     }
 
-#ifdef DUMP_STATE_ACCESS
-    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    auto do_make_scoped_note([[maybe_unused]] const char *text) {
-        return scoped_note<state_access>{*this, text};
-    }
-#endif
+    // -----
+    // i_state_access interface implementation
+    // -----
+    friend i_state_access<state_access>;
 
     uint64_t do_read_x(int i) const {
         return m_m.get_state().x[i];
@@ -525,6 +520,7 @@ class state_access : public i_state_access<state_access>, public i_interactive_s
     // -----
     // i_intereactive_state_access interface implementation
     // -----
+    friend i_interactive_state_access<state_access>;
 
     NO_INLINE auto do_poll_external_interrupts(uint64_t mcycle, uint64_t mcycle_max) {
         return m_m.poll_external_interrupts(mcycle, mcycle_max);
diff --git a/src/uarch-record-state-access.h b/src/uarch-record-state-access.h
index c4a1bd1d3..5d0398c93 100644
--- a/src/uarch-record-state-access.h
+++ b/src/uarch-record-state-access.h
@@ -29,15 +29,14 @@
 
 #include "access-log.h"
 #include "host-addr.h"
+#include "i-accept-scoped-note.h"
 #include "i-hasher.h"
-#include "i-state-access.h"
 #include "i-uarch-state-access.h"
 #include "machine-merkle-tree.h"
 #include "machine.h"
 #include "meta.h"
 #include "pma.h"
 #include "riscv-constants.h"
-#include "scoped-note.h"
 #include "shadow-tlb.h"
 #include "shadow-uarch-state.h"
 #include "strict-aliasing.h"
@@ -51,7 +50,9 @@ namespace cartesi {
 using namespace std::string_literals;
 
 /// \details The uarch_record_state_access logs all access to the machine state.
-class uarch_record_state_access : public i_uarch_state_access<uarch_record_state_access> {
+class uarch_record_state_access :
+    public i_uarch_state_access<uarch_record_state_access>,
+    public i_accept_scoped_note<uarch_record_state_access> {
 
     using hasher_type = machine_merkle_tree::hasher_type;
     using hash_type = machine_merkle_tree::hash_type;
@@ -99,18 +100,6 @@ class uarch_record_state_access : public i_uarch_state_access<uarch_record_state
     }
 
 private:
-    void do_push_begin_bracket(const char *text) {
-        m_log->push_begin_bracket(text);
-    }
-
-    void do_push_end_bracket(const char *text) {
-        m_log->push_end_bracket(text);
-    }
-
-    auto do_make_scoped_note(const char *text) {
-        return scoped_note<uarch_record_state_access>{*this, text};
-    }
-
     static std::pair<uint64_t, int> adjust_access(uint64_t paddr, int log2_size) {
         static_assert(cartesi::log2_size_v<uint64_t> <= machine_merkle_tree::get_log2_word_size(),
             "Merkle tree word size must not be smaller than machine word size");
@@ -235,7 +224,9 @@ class uarch_record_state_access : public i_uarch_state_access<uarch_record_state
             machine_reg_get_name(reg));
     }
 
-    // Declare interface as friend to it can forward calls to the "overridden" methods.
+    // -----
+    // i_uarch_state_access interface implementation
+    // -----
     friend i_uarch_state_access<uarch_record_state_access>;
 
     uint64_t do_read_x(int i) const {
@@ -346,6 +337,23 @@ class uarch_record_state_access : public i_uarch_state_access<uarch_record_state
     constexpr const char *do_get_name() const {
         return "uarch_record_state_access";
     }
+
+    // -----
+    // i_accept_scoped_note interface implementation
+    // -----
+    friend i_accept_scoped_note<uarch_record_state_access>;
+
+    void do_push_begin_bracket(const char *text) {
+        m_log->push_begin_bracket(text);
+    }
+
+    void do_push_end_bracket(const char *text) {
+        m_log->push_end_bracket(text);
+    }
+
+    auto do_make_scoped_note(const char *text) {
+        return scoped_note{*this, text};
+    }
 };
 
 } // namespace cartesi
diff --git a/src/uarch-replay-state-access.h b/src/uarch-replay-state-access.h
index a72b612e4..250e5180c 100644
--- a/src/uarch-replay-state-access.h
+++ b/src/uarch-replay-state-access.h
@@ -29,8 +29,8 @@
 #include <vector>
 
 #include "access-log.h"
+#include "i-accept-scoped-note.h"
 #include "i-hasher.h"
-#include "i-state-access.h"
 #include "i-uarch-state-access.h"
 #include "machine-merkle-tree.h"
 #include "meta.h"
@@ -41,7 +41,9 @@
 
 namespace cartesi {
 
-class uarch_replay_state_access : public i_uarch_state_access<uarch_replay_state_access> {
+class uarch_replay_state_access :
+    public i_uarch_state_access<uarch_replay_state_access>,
+    public i_accept_scoped_note<uarch_replay_state_access> {
     using tree_type = machine_merkle_tree;
     using hash_type = tree_type::hash_type;
     using hasher_type = tree_type::hasher_type;
@@ -278,18 +280,32 @@ class uarch_replay_state_access : public i_uarch_state_access<uarch_replay_state
         return val;
     }
 
+    auto get_write_tlb_slot_hash(uint64_t vaddr_page, uint64_t vp_offset, uint64_t pma_index) {
+        // Writes to TLB slots have to be atomic.
+        // We can only do atomic writes of entire Merkle tree nodes.
+        // Therefore, TLB slot must have a power-of-two size, or at least be aligned to it.
+        static_assert(SHADOW_TLB_SLOT_SIZE == sizeof(shadow_tlb_slot), "shadow TLB slot size is wrong");
+        static_assert((UINT64_C(1) << SHADOW_TLB_SLOT_LOG2_SIZE) == SHADOW_TLB_SLOT_SIZE,
+            "shadow TLB slot log2 size is wrong");
+        static_assert(SHADOW_TLB_SLOT_LOG2_SIZE >= machine_merkle_tree::get_log2_word_size(),
+            "shadow TLB slot must fill at least an entire Merkle tree word");
+        shadow_tlb_slot slot_data{};
+        shadow_tlb_fill_slot(vaddr_page, vp_offset, pma_index, slot_data);
+        hash_type slot_hash{};
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        get_merkle_tree_hash(m_hasher, reinterpret_cast<uint8_t *>(&slot_data), sizeof(slot_data),
+            machine_merkle_tree::get_word_size(), slot_hash);
+        return slot_hash;
+    }
+
+    // -----
+    // i_uarch_state_access interface implementation
+    // -----
     friend i_uarch_state_access<uarch_replay_state_access>;
 
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
     void do_push_bracket(bracket_type /*type*/, const char * /*text*/) {}
 
-#ifdef DUMP_UARCH_STATE_ACCESS
-    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    auto do_make_scoped_note([[maybe_unused]] const char *text) {
-        return scoped_note<uarch_replay_state_access>{*this, text};
-    }
-#endif
-
     uint64_t do_read_x(int i) {
         const auto reg = machine_reg_enum(machine_reg::uarch_x0, i);
         return check_read_word_access(machine_reg_address(reg), machine_reg_get_name(reg));
@@ -353,24 +369,6 @@ class uarch_replay_state_access : public i_uarch_state_access<uarch_replay_state
         check_write_access(UARCH_STATE_START_ADDRESS, UARCH_STATE_LOG2_SIZE, uarch_pristine_state_hash, "uarch.state");
     }
 
-    auto get_write_tlb_slot_hash(uint64_t vaddr_page, uint64_t vp_offset, uint64_t pma_index) {
-        // Writes to TLB slots have to be atomic.
-        // We can only do atomic writes of entire Merkle tree nodes.
-        // Therefore, TLB slot must have a power-of-two size, or at least be aligned to it.
-        static_assert(SHADOW_TLB_SLOT_SIZE == sizeof(shadow_tlb_slot), "shadow TLB slot size is wrong");
-        static_assert((UINT64_C(1) << SHADOW_TLB_SLOT_LOG2_SIZE) == SHADOW_TLB_SLOT_SIZE,
-            "shadow TLB slot log2 size is wrong");
-        static_assert(SHADOW_TLB_SLOT_LOG2_SIZE >= machine_merkle_tree::get_log2_word_size(),
-            "shadow TLB slot must fill at least an entire Merkle tree word");
-        shadow_tlb_slot slot_data{};
-        shadow_tlb_fill_slot(vaddr_page, vp_offset, pma_index, slot_data);
-        hash_type slot_hash{};
-        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        get_merkle_tree_hash(m_hasher, reinterpret_cast<uint8_t *>(&slot_data), sizeof(slot_data),
-            machine_merkle_tree::get_word_size(), slot_hash);
-        return slot_hash;
-    }
-
     void do_write_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset,
         uint64_t pma_index) {
         const auto slot_paddr = shadow_tlb_get_abs_addr(set_index, slot_index);
diff --git a/src/uarch-state-access.h b/src/uarch-state-access.h
index 0a84017e8..32782f5d6 100644
--- a/src/uarch-state-access.h
+++ b/src/uarch-state-access.h
@@ -21,8 +21,8 @@
 #include <cstdint>
 #include <stdexcept>
 
-#include "bracket-note.h"
 #include "host-addr.h"
+#include "i-accept-scoped-note.h"
 #include "i-uarch-state-access.h"
 #include "machine.h"
 #include "os.h"
@@ -30,13 +30,11 @@
 #include "strict-aliasing.h"
 #include "uarch-pristine.h"
 
-#if DUMP_UARCH_STATE_ACCESS
-#include "scoped-note.h"
-#endif
-
 namespace cartesi {
 
-class uarch_state_access : public i_uarch_state_access<uarch_state_access> {
+class uarch_state_access :
+    public i_uarch_state_access<uarch_state_access>,
+    public i_accept_scoped_note<uarch_state_access> {
     // NOLINTBEGIN(cppcoreguidelines-avoid-const-or-ref-data-members)
     machine &m_m;
     // NOLINTEND(cppcoreguidelines-avoid-const-or-ref-data-members)
@@ -66,15 +64,11 @@ class uarch_state_access : public i_uarch_state_access<uarch_state_access> {
     ~uarch_state_access() = default;
 
 private:
+    // -----
+    // i_uarch_state_access interface implementation
+    // -----
     friend i_uarch_state_access<uarch_state_access>;
 
-#ifdef DUMP_UARCH_STATE_ACCESS
-    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    auto do_make_scoped_note([[maybe_unused]] const char *text) {
-        return scoped_note<uarch_state_access>{*this, text};
-    }
-#endif
-
     uint64_t do_read_x(int i) const {
         return m_m.get_uarch_state().x[i];
     }
diff --git a/uarch/machine-uarch-bridge-state-access.h b/uarch/machine-uarch-bridge-state-access.h
index e0fcac1fe..c0af3bb25 100644
--- a/uarch/machine-uarch-bridge-state-access.h
+++ b/uarch/machine-uarch-bridge-state-access.h
@@ -22,7 +22,7 @@
 #include <optional>
 
 #include "compiler-defines.h"
-#include "device-state-access.h"
+#include "i-accept-scoped-note.h"
 #include "i-state-access.h"
 #include "machine-reg.h"
 #include "mock-pma-entry.h"
@@ -34,10 +34,6 @@
 #include "uarch-ecall.h"
 #include "uarch-strict-aliasing.h"
 
-#if DUMP_UARCH_STATE_ACCESS
-#include "scoped-note.h"
-#endif
-
 namespace cartesi {
 
 class machine_uarch_bridge_state_access;
@@ -54,7 +50,9 @@ struct i_state_access_fast_addr<machine_uarch_bridge_state_access> {
 };
 
 // Provides access to the state of the big emulator from microcode
-class machine_uarch_bridge_state_access : public i_state_access<machine_uarch_bridge_state_access> {
+class machine_uarch_bridge_state_access :
+    public i_state_access<machine_uarch_bridge_state_access>,
+    public i_accept_scoped_note<machine_uarch_bridge_state_access> {
 
     //NOLINTNEXTLINE(cppcoreguidelines-avoid-const-or-ref-data-members)
     std::array<std::optional<mock_pma_entry>, PMA_MAX> &m_pmas;
@@ -68,15 +66,6 @@ class machine_uarch_bridge_state_access : public i_state_access<machine_uarch_br
     ~machine_uarch_bridge_state_access() = default;
 
 private:
-    friend i_state_access<machine_uarch_bridge_state_access>;
-
-#ifdef DUMP_UARCH_STATE_ACCESS
-    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    auto do_make_scoped_note([[maybe_unused]] const char *text) {
-        return scoped_note<machine_uarch_bridge_state_access>{*this, text};
-    }
-#endif
-
     uint64_t bridge_read_reg(machine_reg reg) {
         return ua_aliased_aligned_read<uint64_t>(machine_reg_address(reg));
     }
@@ -85,6 +74,23 @@ class machine_uarch_bridge_state_access : public i_state_access<machine_uarch_br
         ua_aliased_aligned_write<uint64_t>(machine_reg_address(reg), val);
     }
 
+    uint64_t bridge_read_pma_istart(int i) {
+        return ua_aliased_aligned_read<uint64_t>(shadow_pmas_get_pma_abs_addr(i, shadow_pmas_what::istart));
+    }
+
+    uint64_t bridge_read_pma_ilength(int i) {
+        return ua_aliased_aligned_read<uint64_t>(shadow_pmas_get_pma_abs_addr(i, shadow_pmas_what::ilength));
+    }
+
+    uint64_t bridge_read_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, shadow_tlb_what what) {
+        return ua_aliased_aligned_read<uint64_t>(shadow_tlb_get_abs_addr(set_index, slot_index, what));
+    }
+
+    // -----
+    // i_state_access interface implementation
+    // -----
+    friend i_state_access<machine_uarch_bridge_state_access>;
+
     uint64_t do_read_x(int i) {
         return bridge_read_reg(machine_reg_enum(machine_reg::x0, i));
     }
@@ -435,17 +441,9 @@ class machine_uarch_bridge_state_access : public i_state_access<machine_uarch_br
         return false;
     }
 
-    uint64_t read_pma_istart(int i) {
-        return ua_aliased_aligned_read<uint64_t>(shadow_pmas_get_pma_abs_addr(i, shadow_pmas_what::istart));
-    }
-
-    uint64_t read_pma_ilength(int i) {
-        return ua_aliased_aligned_read<uint64_t>(shadow_pmas_get_pma_abs_addr(i, shadow_pmas_what::ilength));
-    }
-
     mock_pma_entry &do_read_pma_entry(uint64_t index) {
-        const uint64_t istart = read_pma_istart(index);
-        const uint64_t ilength = read_pma_ilength(index);
+        const uint64_t istart = bridge_read_pma_istart(index);
+        const uint64_t ilength = bridge_read_pma_ilength(index);
         // NOLINTNEXTLINE(bugprone-narrowing-conversions)
         int i = static_cast<int>(index);
         if (!m_pmas[i]) {
@@ -459,10 +457,6 @@ class machine_uarch_bridge_state_access : public i_state_access<machine_uarch_br
         return paddr;
     }
 
-    uint64_t bridge_read_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, shadow_tlb_what what) {
-        return ua_aliased_aligned_read<uint64_t>(shadow_tlb_get_abs_addr(set_index, slot_index, what));
-    }
-
     template <TLB_set_index SET>
     uint64_t do_read_tlb_vaddr_page(uint64_t slot_index) {
         return bridge_read_shadow_tlb(SET, slot_index, shadow_tlb_what::vaddr_page);

From 5e119852ec0677baa9f2d95a7895bf31130f1f4b Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Tue, 4 Feb 2025 21:19:03 +0000
Subject: [PATCH 09/82] refactor: split out i-prefer-state-access.h

And also i-prefer-uarch-state-access.h
---
 src/dump-state-access.h                   |   32 +
 src/dump-uarch-state-access.h             |   32 +
 src/i-prefer-shadow-state.h               |   76 ++
 src/i-prefer-shadow-uarch-state.h         |   76 ++
 src/i-state-access.h                      | 1061 +++------------------
 src/i-uarch-state-access.h                |  143 ++-
 src/interpret.cpp                         |    2 +-
 src/pm-type-name.h                        |    2 +
 src/record-step-state-access.h            |  340 +------
 src/replay-step-state-access.h            |  360 +------
 src/shadow-state.h                        |    4 +
 src/shadow-uarch-state.h                  |    4 +
 src/uarch-interpret.cpp                   |    2 +-
 src/uarch-record-state-access.h           |   52 +-
 src/uarch-replay-state-access.h           |   65 +-
 src/uarch-solidity-compat.h               |   18 +-
 src/uarch-state-access.h                  |   18 +-
 uarch/machine-uarch-bridge-state-access.h |  339 +------
 18 files changed, 554 insertions(+), 2072 deletions(-)
 create mode 100644 src/dump-state-access.h
 create mode 100644 src/dump-uarch-state-access.h
 create mode 100644 src/i-prefer-shadow-state.h
 create mode 100644 src/i-prefer-shadow-uarch-state.h

diff --git a/src/dump-state-access.h b/src/dump-state-access.h
new file mode 100644
index 000000000..4d90c7239
--- /dev/null
+++ b/src/dump-state-access.h
@@ -0,0 +1,32 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef DUMP_STATE_ACCESS_H
+#define DUMP_STATE_ACCESS_H
+
+#ifdef DUMP_STATE_ACCESS
+template <typename... ARGS>
+static inline auto DSA_PRINTF(ARGS... args) {
+    return fprintf(stderr, args...);
+}
+#else
+template <typename... ARGS>
+static inline auto DSA_PRINTF(ARGS... /*args*/) {
+    return 0;
+}
+#endif
+
+#endif
diff --git a/src/dump-uarch-state-access.h b/src/dump-uarch-state-access.h
new file mode 100644
index 000000000..7d6b14ec4
--- /dev/null
+++ b/src/dump-uarch-state-access.h
@@ -0,0 +1,32 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef DUMP_UARCH_STATE_ACCESS_H
+#define DUMP_UARCH_STATE_ACCESS_H
+
+#ifdef DUMP_UARCH_STATE_ACCESS
+template <typename... ARGS>
+static inline auto DUSA_PRINTF(ARGS... args) {
+    return printf(args...);
+}
+#else
+template <typename... ARGS>
+static inline auto DUSA_PRINTF(ARGS... /*args*/) {
+    return 0;
+}
+#endif
+
+#endif
diff --git a/src/i-prefer-shadow-state.h b/src/i-prefer-shadow-state.h
new file mode 100644
index 000000000..38990ccb9
--- /dev/null
+++ b/src/i-prefer-shadow-state.h
@@ -0,0 +1,76 @@
+
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef I_PREFER_SHADOW_STATE_H
+#define I_PREFER_SHADOW_STATE_H
+
+/// \file
+/// \brief Interface for state access that prefers to go through shadow state
+
+#include <cstdint>
+#include <type_traits>
+
+#include "dump-state-access.h"
+#include "meta.h"
+#include "shadow-state.h"
+#include "tlb.h"
+
+namespace cartesi {
+
+/// \class i_prefer_shadow_state
+/// \brief Interface for multiplexed access to shadow state.
+/// \tparam DERIVED Derived class implementing the interface. (An example of CRTP.)
+/// \detail This is for state access methods that do not need individualized access to machine registers
+template <typename DERIVED>
+class i_prefer_shadow_state { // CRTP
+
+    /// \brief Returns object cast as the derived class
+    DERIVED &derived() {
+        return *static_cast<DERIVED *>(this);
+    }
+
+    /// \brief Returns object cast as the derived class
+    const DERIVED &derived() const {
+        return *static_cast<const DERIVED *>(this);
+    }
+
+public:
+    uint64_t read_shadow_state(shadow_state_what what) {
+        const auto val = derived().do_read_shadow_state(what);
+        [[maybe_unused]] const auto *const what_name = shadow_state_get_what_name(what);
+        DSA_PRINTF("%s::read_shadow_state(%s) = %llu(0x%llx)\n", derived().get_name(), what_name, val, val);
+        return val;
+    }
+
+    void write_shadow_state(shadow_state_what what, uint64_t val) {
+        derived().do_write_shadow_state(what, val);
+        [[maybe_unused]] const auto *const what_name = shadow_state_get_what_name(what);
+        DSA_PRINTF("%s::write_shadow_state(%s, %llu(0x%llx))\n", derived().get_name(), what_name, val, val);
+    }
+};
+
+/// \brief SFINAE test implementation of the i_state_access interface
+template <typename DERIVED>
+using is_an_i_prefer_shadow_state =
+    std::integral_constant<bool, is_template_base_of_v<i_prefer_shadow_state, std::remove_cvref_t<DERIVED>>>;
+
+template <typename DERIVED>
+constexpr bool is_an_i_prefer_shadow_state_v = is_an_i_prefer_shadow_state<DERIVED>::value;
+
+} // namespace cartesi
+
+#endif
diff --git a/src/i-prefer-shadow-uarch-state.h b/src/i-prefer-shadow-uarch-state.h
new file mode 100644
index 000000000..b4492a59f
--- /dev/null
+++ b/src/i-prefer-shadow-uarch-state.h
@@ -0,0 +1,76 @@
+
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef I_PREFER_SHADOW_UARCH_STATE_H
+#define I_PREFER_SHADOW_UARCH_STATE_H
+
+/// \file
+/// \brief Interface for state access that prefers to go through shadow uarch state
+
+#include <cstdint>
+#include <type_traits>
+
+#include "dump-uarch-state-access.h"
+#include "meta.h"
+#include "shadow-uarch-state.h"
+#include "tlb.h"
+
+namespace cartesi {
+
+/// \class i_prefer_shadow_uarch_state
+/// \brief Interface for multiplexed access to shadow uarch state.
+/// \tparam DERIVED Derived class implementing the interface. (An example of CRTP.)
+/// \detail This is for state access methods that do not need individualized access to uarch registers
+template <typename DERIVED>
+class i_prefer_shadow_uarch_state { // CRTP
+
+    /// \brief Returns object cast as the derived class
+    DERIVED &derived() {
+        return *static_cast<DERIVED *>(this);
+    }
+
+    /// \brief Returns object cast as the derived class
+    const DERIVED &derived() const {
+        return *static_cast<const DERIVED *>(this);
+    }
+
+public:
+    uint64_t read_shadow_uarch_state(shadow_uarch_state_what what) {
+        const auto val = derived().do_read_shadow_uarch_state(what);
+        [[maybe_unused]] const auto *const what_name = shadow_uarch_state_get_what_name(what);
+        DUSA_PRINTF("%s::read_shadow_uarch_state(%s) = %llu(0x%llx)\n", derived().get_name(), what_name, val, val);
+        return val;
+    }
+
+    void write_shadow_uarch_state(shadow_uarch_state_what what, uint64_t val) {
+        derived().do_write_shadow_uarch_state(what, val);
+        [[maybe_unused]] const auto *const what_name = shadow_uarch_state_get_what_name(what);
+        DUSA_PRINTF("%s::write_shadow_uarch_state(%s, %llu(0x%llx))\n", derived().get_name(), what_name, val, val);
+    }
+};
+
+/// \brief SFINAE test implementation of the i_state_access interface
+template <typename DERIVED>
+using is_an_i_prefer_shadow_uarch_state =
+    std::integral_constant<bool, is_template_base_of_v<i_prefer_shadow_uarch_state, std::remove_cvref_t<DERIVED>>>;
+
+template <typename DERIVED>
+constexpr bool is_an_i_prefer_shadow_uarch_state_v = is_an_i_prefer_shadow_uarch_state<DERIVED>::value;
+
+} // namespace cartesi
+
+#endif
diff --git a/src/i-state-access.h b/src/i-state-access.h
index 29b0c17d9..30243dcb4 100644
--- a/src/i-state-access.h
+++ b/src/i-state-access.h
@@ -24,13 +24,11 @@
 #include <type_traits>
 #include <utility>
 
-#include "compiler-defines.h"
+#include "dump-state-access.h"
+#include "i-prefer-shadow-state.h"
 #include "meta.h"
-#include "tlb.h"
-
-#ifdef DUMP_STATE_ACCESS
 #include "pm-type-name.h"
-#endif
+#include "tlb.h"
 
 namespace cartesi {
 
@@ -49,6 +47,29 @@ struct i_state_access_fast_addr {};
 template <typename STATE_ACCESS>
 using i_state_access_fast_addr_t = typename i_state_access_fast_addr<STATE_ACCESS>::type;
 
+// NOLINTBEGIN(cppcoreguidelines-macro-usage)
+#define DEFINE_SA_READ(REG)                                                                                            \
+    uint64_t read_##REG() {                                                                                            \
+        if constexpr (!is_an_i_prefer_shadow_state_v<DERIVED>) {                                                       \
+            const auto val = derived().do_read_##REG();                                                                \
+            DSA_PRINTF("%s::read_" #REG "() = %llu(0x%llx)\n", get_name(), val, val);                                  \
+            return val;                                                                                                \
+        } else {                                                                                                       \
+            return derived().read_shadow_state(shadow_state_what::REG);                                                \
+        }                                                                                                              \
+    }
+
+#define DEFINE_SA_WRITE(REG)                                                                                           \
+    void write_##REG(uint64_t val) {                                                                                   \
+        if constexpr (!is_an_i_prefer_shadow_state_v<DERIVED>) {                                                       \
+            derived().do_write_##REG(val);                                                                             \
+            DSA_PRINTF("%s::write_" #REG "(%llu(0x%llx))\n", get_name(), val, val);                                    \
+        } else {                                                                                                       \
+            derived().write_shadow_state(shadow_state_what::REG, val);                                                 \
+        }                                                                                                              \
+    }
+// NOLINTEND(cppcoreguidelines-macro-usage)
+
 /// \class i_state_access
 /// \brief Interface for machine state access.
 /// \details \{
@@ -99,13 +120,13 @@ class i_state_access { // CRTP
     /// \param i Register index.
     /// \returns Register value.
     uint64_t read_x(int i) {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_x(i);
-        fprintf(stderr, "%s::read_x(%d) = %llu(0x%llx)\n", get_name(), i, val, val);
-        return val;
-#else
-        return derived().do_read_x(i);
-#endif
+        if constexpr (!is_an_i_prefer_shadow_state_v<DERIVED>) {
+            const auto val = derived().do_read_x(i);
+            DSA_PRINTF("%s::read_x(%d) = %llu(0x%llx)\n", get_name(), i, val, val);
+            return val;
+        } else {
+            return derived().read_shadow_state(shadow_state_get_what(shadow_state_what::x0, i));
+        }
     }
 
     /// \brief Writes register to general-purpose register.
@@ -114,878 +135,134 @@ class i_state_access { // CRTP
     /// \details Writes to register zero *break* the machine.
     /// There is an assertion to catch this, but NDEBUG will let the value pass through.
     void write_x(int i, uint64_t val) {
-        derived().do_write_x(i, val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_x(%d, %llu(0x%llx))\n", get_name(), i, val, val);
-#endif
+        if constexpr (!is_an_i_prefer_shadow_state_v<DERIVED>) {
+            derived().do_write_x(i, val);
+            DSA_PRINTF("%s::write_x(%d, %llu(0x%llx))\n", get_name(), i, val, val);
+        } else {
+            derived().write_shadow_state(shadow_state_get_what(shadow_state_what::x0, i), val);
+        }
     }
 
     /// \brief Reads from floating-point register.
     /// \param i Register index.
     /// \returns Register value.
     uint64_t read_f(int i) {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_f(i);
-        fprintf(stderr, "%s::read_f(%d) = %llu(0x%llx)\n", get_name(), i, val, val);
-        return val;
-#else
-        return derived().do_read_f(i);
-#endif
+        if constexpr (!is_an_i_prefer_shadow_state_v<DERIVED>) {
+            const auto val = derived().do_read_f(i);
+            DSA_PRINTF("%s::read_f(%d) = %llu(0x%llx)\n", get_name(), i, val, val);
+            return val;
+        } else {
+            return derived().read_shadow_state(shadow_state_get_what(shadow_state_what::f0, i));
+        }
     }
 
     /// \brief Writes register to floating-point register.
     /// \param i Register index.
     /// \param val New register value.
     void write_f(int i, uint64_t val) {
-        derived().do_write_f(i, val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_f(%d, %llu(%llx))\n", get_name(), i, val, val);
-#endif
-    }
-
-    /// \brief Reads the program counter.
-    /// \returns Register value.
-    uint64_t read_pc() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_pc();
-        fprintf(stderr, "%s::read_pc() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_pc();
-#endif
-    }
-
-    /// \brief Writes the program counter.
-    /// \param val New register value.
-    void write_pc(uint64_t val) {
-        derived().do_write_pc(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_pc(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Writes CSR fcsr.
-    /// \param val New register value.
-    void write_fcsr(uint64_t val) {
-        derived().do_write_fcsr(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_fcsr(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR fcsr.
-    /// \returns Register value.
-    uint64_t read_fcsr() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_fcsr();
-        fprintf(stderr, "%s::read_fcsr() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_fcsr();
-#endif
-    }
-
-    /// \brief Reads CSR icycleinstret.
-    /// \returns Register value.
-    uint64_t read_icycleinstret() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_icycleinstret();
-        fprintf(stderr, "%s::read_icycleinstret() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_icycleinstret();
-#endif
-    }
-
-    /// \brief Writes CSR icycleinstret.
-    /// \param val New register value.
-    void write_icycleinstret(uint64_t val) {
-        derived().do_write_icycleinstret(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_icycleinstret(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR mvendorid.
-    /// \returns Register value.
-    uint64_t read_mvendorid() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_mvendorid();
-        fprintf(stderr, "%s::read_mvendorid() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_mvendorid();
-#endif
-    }
-
-    /// \brief Reads CSR marchid.
-    /// \returns Register value.
-    uint64_t read_marchid() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_marchid();
-        fprintf(stderr, "%s::read_marchid() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_marchid();
-#endif
-    }
-
-    /// \brief Reads CSR mimpid.
-    /// \returns Register value.
-    uint64_t read_mimpid() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_mimpid();
-        fprintf(stderr, "%s::read_mimpid() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_mimpid();
-#endif
-    }
-
-    /// \brief Reads CSR mcycle.
-    /// \returns Register value.
-    uint64_t read_mcycle() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_mcycle();
-        fprintf(stderr, "%s::read_mcycle() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_mcycle();
-#endif
-    }
-
-    /// \brief Writes CSR mcycle.
-    /// \param val New register value.
-    void write_mcycle(uint64_t val) {
-        derived().do_write_mcycle(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_mcycle(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR mstatus.
-    /// \returns Register value.
-    uint64_t read_mstatus() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_mstatus();
-        fprintf(stderr, "%s::read_mstatus() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_mstatus();
-#endif
-    }
-
-    /// \brief Writes CSR mstatus.
-    /// \param val New register value.
-    void write_mstatus(uint64_t val) {
-        derived().do_write_mstatus(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_mstatus(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR menvcfg.
-    /// \returns Register value.
-    uint64_t read_menvcfg() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_menvcfg();
-        fprintf(stderr, "%s::read_menvcfg() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_menvcfg();
-#endif
-    }
-
-    /// \brief Writes CSR menvcfg.
-    /// \param val New register value.
-    void write_menvcfg(uint64_t val) {
-        derived().do_write_menvcfg(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_menvcfg(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR mtvec.
-    /// \returns Register value.
-    uint64_t read_mtvec() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_mtvec();
-        fprintf(stderr, "%s::read_mtvec() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_mtvec();
-#endif
-    }
-
-    /// \brief Writes CSR mtvec.
-    /// \param val New register value.
-    void write_mtvec(uint64_t val) {
-        derived().do_write_mtvec(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_mtvec(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR mscratch.
-    /// \returns Register value.
-    uint64_t read_mscratch() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_mscratch();
-        fprintf(stderr, "%s::read_mscratch() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_mscratch();
-#endif
-    }
-
-    /// \brief Writes CSR mscratch.
-    /// \param val New register value.
-    void write_mscratch(uint64_t val) {
-        derived().do_write_mscratch(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_mscratch(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR mepc.
-    /// \returns Register value.
-    uint64_t read_mepc() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_mepc();
-        fprintf(stderr, "%s::read_mepc() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_mepc();
-#endif
-    }
-
-    /// \brief Writes CSR mepc.
-    /// \param val New register value.
-    void write_mepc(uint64_t val) {
-        derived().do_write_mepc(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_mepc(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR mcause.
-    /// \returns Register value.
-    uint64_t read_mcause() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_mcause();
-        fprintf(stderr, "%s::read_mcause() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_mcause();
-#endif
-    }
-
-    /// \brief Writes CSR mcause.
-    /// \param val New register value.
-    void write_mcause(uint64_t val) {
-        derived().do_write_mcause(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_mcause(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR mtval.
-    /// \returns Register value.
-    uint64_t read_mtval() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_mtval();
-        fprintf(stderr, "%s::read_mtval() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_mtval();
-#endif
-    }
-
-    /// \brief Writes CSR mtval.
-    /// \param val New register value.
-    void write_mtval(uint64_t val) {
-        derived().do_write_mtval(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_mtval(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR misa.
-    /// \returns Register value.
-    uint64_t read_misa() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_misa();
-        fprintf(stderr, "%s::read_misa() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_misa();
-#endif
-    }
-
-    /// \brief Writes CSR misa.
-    /// \param val New register value.
-    void write_misa(uint64_t val) {
-        derived().do_write_misa(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_misa(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR mie.
-    /// \returns Register value.
-    uint64_t read_mie() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_mie();
-        fprintf(stderr, "%s::read_mie() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_mie();
-#endif
-    }
-
-    /// \brief Writes CSR mie.
-    /// \param val New register value.
-    void write_mie(uint64_t val) {
-        derived().do_write_mie(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_mie(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR mip.
-    /// \returns Register value.
-    uint64_t read_mip() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_mip();
-        fprintf(stderr, "%s::read_mip() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_mip();
-#endif
-    }
-
-    /// \brief Writes CSR mip.
-    /// \param val New register value.
-    void write_mip(uint64_t val) {
-        derived().do_write_mip(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_mip(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR medeleg.
-    /// \returns Register value.
-    uint64_t read_medeleg() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_medeleg();
-        fprintf(stderr, "%s::read_medeleg() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_medeleg();
-#endif
-    }
-
-    /// \brief Writes CSR medeleg.
-    /// \param val New register value.
-    void write_medeleg(uint64_t val) {
-        derived().do_write_medeleg(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_medeleg(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR mideleg.
-    /// \returns Register value.
-    uint64_t read_mideleg() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_mideleg();
-        fprintf(stderr, "%s::read_mideleg() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_mideleg();
-#endif
-    }
-
-    /// \brief Writes CSR mideleg.
-    /// \param val New register value.
-    void write_mideleg(uint64_t val) {
-        derived().do_write_mideleg(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_mideleg(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR iprv.
-    /// \returns Register value.
-    uint64_t read_iprv() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_iprv();
-        fprintf(stderr, "%s::read_iprv() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_iprv();
-#endif
-    }
-
-    /// \brief Writes CSR iprv.
-    /// \param val New register value.
-    void write_iprv(uint64_t val) {
-        derived().do_write_iprv(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_iprv(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR iflags_X.
-    /// \returns Register value.
-    uint64_t read_iflags_X() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_iflags_X();
-        fprintf(stderr, "%s::read_iflags_X() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_iflags_X();
-#endif
-    }
-
-    /// \brief Writes CSR iflags_X.
-    /// \param val New register value.
-    void write_iflags_X(uint64_t val) {
-        derived().do_write_iflags_X(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_iflags_X(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR iflags_Y.
-    /// \returns Register value.
-    uint64_t read_iflags_Y() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_iflags_Y();
-        fprintf(stderr, "%s::read_iflags_Y() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_iflags_Y();
-#endif
-    }
-
-    /// \brief Writes CSR iflags_Y.
-    /// \param val New register value.
-    void write_iflags_Y(uint64_t val) {
-        derived().do_write_iflags_Y(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_iflags_Y(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR iflags_H.
-    /// \returns Register value.
-    uint64_t read_iflags_H() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_iflags_H();
-        fprintf(stderr, "%s::read_iflags_H() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_iflags_H();
-#endif
-    }
-
-    /// \brief Writes CSR iflags_H.
-    /// \param val New register value.
-    void write_iflags_H(uint64_t val) {
-        derived().do_write_iflags_H(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_iflags_H(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR mcounteren.
-    /// \returns Register value.
-    uint64_t read_mcounteren() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_mcounteren();
-        fprintf(stderr, "%s::read_mcounteren() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_mcounteren();
-#endif
-    }
-
-    /// \brief Writes CSR mcounteren.
-    /// \param val New register value.
-    void write_mcounteren(uint64_t val) {
-        derived().do_write_mcounteren(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_mcounteren(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR senvcfg.
-    /// \returns Register value.
-    uint64_t read_senvcfg() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_senvcfg();
-        fprintf(stderr, "%s::read_senvcfg() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_senvcfg();
-#endif
-    }
-
-    /// \brief Writes CSR senvcfg.
-    /// \param val New register value.
-    void write_senvcfg(uint64_t val) {
-        derived().do_write_senvcfg(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_senvcfg(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR stvec.
-    /// \returns Register value.
-    uint64_t read_stvec() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_stvec();
-        fprintf(stderr, "%s::read_stvec() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_stvec();
-#endif
-    }
-
-    /// \brief Writes CSR stvec.
-    /// \param val New register value.
-    void write_stvec(uint64_t val) {
-        derived().do_write_stvec(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_stvec(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR sscratch.
-    /// \returns Register value.
-    uint64_t read_sscratch() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_sscratch();
-        fprintf(stderr, "%s::read_sscratch() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_sscratch();
-#endif
-    }
-
-    /// \brief Writes CSR sscratch.
-    /// \param val New register value.
-    void write_sscratch(uint64_t val) {
-        derived().do_write_sscratch(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_sscratch(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR sepc.
-    /// \returns Register value.
-    uint64_t read_sepc() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_sepc();
-        fprintf(stderr, "%s::read_sepc() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_sepc();
-#endif
-    }
-
-    /// \brief Writes CSR sepc.
-    /// \param val New register value.
-    void write_sepc(uint64_t val) {
-        derived().do_write_sepc(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_sepc(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR scause.
-    /// \returns Register value.
-    uint64_t read_scause() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_scause();
-        fprintf(stderr, "%s::read_scause() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_scause();
-#endif
-    }
-
-    /// \brief Writes CSR scause.
-    /// \param val New register value.
-    void write_scause(uint64_t val) {
-        derived().do_write_scause(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_scause(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR stval.
-    /// \returns Register value.
-    uint64_t read_stval() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_stval();
-        fprintf(stderr, "%s::read_stval() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_stval();
-#endif
-    }
-
-    /// \brief Writes CSR stval.
-    /// \param val New register value.
-    void write_stval(uint64_t val) {
-        derived().do_write_stval(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_stval(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR satp.
-    /// \returns Register value.
-    uint64_t read_satp() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_satp();
-        fprintf(stderr, "%s::read_satp() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_satp();
-#endif
-    }
-
-    /// \brief Writes CSR satp.
-    /// \param val New register value.
-    void write_satp(uint64_t val) {
-        derived().do_write_satp(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_satp(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR scounteren.
-    /// \returns Register value.
-    uint64_t read_scounteren() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_scounteren();
-        fprintf(stderr, "%s::read_scounteren() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_scounteren();
-#endif
-    }
-
-    /// \brief Writes CSR scounteren.
-    /// \param val New register value.
-    void write_scounteren(uint64_t val) {
-        derived().do_write_scounteren(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_scounteren(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR ilrsc.
-    /// \returns Register value.
-    /// \details This is Cartesi-specific.
-    uint64_t read_ilrsc() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_ilrsc();
-        fprintf(stderr, "%s::read_ilrsc() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_ilrsc();
-#endif
-    }
-
-    /// \brief Writes CSR ilrsc.
-    /// \param val New register value.
-    /// \details This is Cartesi-specific.
-    void write_ilrsc(uint64_t val) {
-        derived().do_write_ilrsc(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_ilrsc(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CSR iunrep.
-    /// \returns Register value.
-    /// \details This is Cartesi-specific.
-    uint64_t read_iunrep() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_iunrep();
-        fprintf(stderr, "%s::read_iunrep() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_iunrep();
-#endif
-    }
-
-    /// \brief Writes CSR iunrep.
-    /// \param val New register value.
-    /// \details This is Cartesi-specific.
-    void write_iunrep(uint64_t val) {
-        derived().do_write_iunrep(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_iunrep(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads CLINT's mtimecmp.
-    /// \returns Register value.
-    uint64_t read_clint_mtimecmp() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_clint_mtimecmp();
-        fprintf(stderr, "%s::read_clint_mtimecmp() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_clint_mtimecmp();
-#endif
-    }
-
-    /// \brief Writes CLINT's mtimecmp.
-    /// \param val New register value.
-    void write_clint_mtimecmp(uint64_t val) {
-        derived().do_write_clint_mtimecmp(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_clint_mtimecmp(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads PLIC's girqpend.
-    /// \returns Register value.
-    uint64_t read_plic_girqpend() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_plic_girqpend();
-        fprintf(stderr, "%s::read_plic_girqpend() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_plic_girqpend();
-#endif
-    }
-
-    /// \brief Writes PLIC's girqpend.
-    /// \param val New register value.
-    void write_plic_girqpend(uint64_t val) {
-        derived().do_write_plic_girqpend(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_plic_girqpend(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads PLIC's girqsrvd.
-    /// \returns Register value.
-    uint64_t read_plic_girqsrvd() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_plic_girqsrvd();
-        fprintf(stderr, "%s::read_plic_girqsrvd() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_plic_girqsrvd();
-#endif
-    }
-
-    /// \brief Writes PLIC's girqsrvd.
-    /// \param val New register value.
-    void write_plic_girqsrvd(uint64_t val) {
-        derived().do_write_plic_girqsrvd(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_plic_girqsrvd(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads HTIF's fromhost.
-    /// \returns Register value.
-    uint64_t read_htif_fromhost() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_htif_fromhost();
-        fprintf(stderr, "%s::read_htif_fromhost() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_htif_fromhost();
-#endif
-    }
-
-    /// \brief Writes HTIF's fromhost.
-    /// \param val New register value.
-    void write_htif_fromhost(uint64_t val) {
-        derived().do_write_htif_fromhost(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_htif_fromhost(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads HTIF's tohost.
-    /// \returns Register value.
-    uint64_t read_htif_tohost() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_htif_tohost();
-        fprintf(stderr, "%s::read_htif_tohost() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_htif_tohost();
-#endif
-    }
-
-    /// \brief Writes HTIF's tohost.
-    /// \param val New register value.
-    void write_htif_tohost(uint64_t val) {
-        derived().do_write_htif_tohost(val);
-#ifdef DUMP_STATE_ACCESS
-        fprintf(stderr, "%s::write_htif_tohost(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    /// \brief Reads HTIF's ihalt.
-    /// \returns Register value.
-    uint64_t read_htif_ihalt() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_htif_ihalt();
-        fprintf(stderr, "%s::read_htif_ihalt() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_htif_ihalt();
-#endif
-    }
-
-    /// \brief Reads HTIF's iconsole.
-    /// \returns Register value.
-    uint64_t read_htif_iconsole() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_htif_iconsole();
-        fprintf(stderr, "%s::read_htif_iconsole() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_htif_iconsole();
-#endif
-    }
-
-    /// \brief Reads HTIF's iyield.
-    /// \returns Register value.
-    uint64_t read_htif_iyield() {
-#ifdef DUMP_STATE_ACCESS
-        const auto val = derived().do_read_htif_iyield();
-        fprintf(stderr, "%s::read_htif_iyield() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_htif_iyield();
-#endif
-    }
+        if constexpr (!is_an_i_prefer_shadow_state_v<DERIVED>) {
+            derived().do_write_f(i, val);
+            DSA_PRINTF("%s::write_f(%d, %llu(%llx))\n", get_name(), i, val, val);
+        } else {
+            derived().write_shadow_state(shadow_state_get_what(shadow_state_what::f0, i), val);
+        }
+    }
+
+    // Define read and write methods for each register in the shadow state
+    // NOLINTBEGIN(cppcoreguidelines-macro-usage)
+    DEFINE_SA_READ(pc)
+    DEFINE_SA_WRITE(pc)
+    DEFINE_SA_READ(fcsr)
+    DEFINE_SA_WRITE(fcsr)
+    DEFINE_SA_READ(mvendorid)
+    DEFINE_SA_WRITE(mvendorid)
+    DEFINE_SA_READ(marchid)
+    DEFINE_SA_WRITE(marchid)
+    DEFINE_SA_READ(mimpid)
+    DEFINE_SA_WRITE(mimpid)
+    DEFINE_SA_READ(mcycle)
+    DEFINE_SA_WRITE(mcycle)
+    DEFINE_SA_READ(icycleinstret)
+    DEFINE_SA_WRITE(icycleinstret)
+    DEFINE_SA_READ(mstatus)
+    DEFINE_SA_WRITE(mstatus)
+    DEFINE_SA_READ(mtvec)
+    DEFINE_SA_WRITE(mtvec)
+    DEFINE_SA_READ(mscratch)
+    DEFINE_SA_WRITE(mscratch)
+    DEFINE_SA_READ(mepc)
+    DEFINE_SA_WRITE(mepc)
+    DEFINE_SA_READ(mcause)
+    DEFINE_SA_WRITE(mcause)
+    DEFINE_SA_READ(mtval)
+    DEFINE_SA_WRITE(mtval)
+    DEFINE_SA_READ(misa)
+    DEFINE_SA_WRITE(misa)
+    DEFINE_SA_READ(mie)
+    DEFINE_SA_WRITE(mie)
+    DEFINE_SA_READ(mip)
+    DEFINE_SA_WRITE(mip)
+    DEFINE_SA_READ(medeleg)
+    DEFINE_SA_WRITE(medeleg)
+    DEFINE_SA_READ(mideleg)
+    DEFINE_SA_WRITE(mideleg)
+    DEFINE_SA_READ(mcounteren)
+    DEFINE_SA_WRITE(mcounteren)
+    DEFINE_SA_READ(menvcfg)
+    DEFINE_SA_WRITE(menvcfg)
+    DEFINE_SA_READ(stvec)
+    DEFINE_SA_WRITE(stvec)
+    DEFINE_SA_READ(sscratch)
+    DEFINE_SA_WRITE(sscratch)
+    DEFINE_SA_READ(sepc)
+    DEFINE_SA_WRITE(sepc)
+    DEFINE_SA_READ(scause)
+    DEFINE_SA_WRITE(scause)
+    DEFINE_SA_READ(stval)
+    DEFINE_SA_WRITE(stval)
+    DEFINE_SA_READ(satp)
+    DEFINE_SA_WRITE(satp)
+    DEFINE_SA_READ(scounteren)
+    DEFINE_SA_WRITE(scounteren)
+    DEFINE_SA_READ(senvcfg)
+    DEFINE_SA_WRITE(senvcfg)
+    DEFINE_SA_READ(ilrsc)
+    DEFINE_SA_WRITE(ilrsc)
+    DEFINE_SA_READ(iprv)
+    DEFINE_SA_WRITE(iprv)
+    DEFINE_SA_READ(iflags_X)
+    DEFINE_SA_WRITE(iflags_X)
+    DEFINE_SA_READ(iflags_Y)
+    DEFINE_SA_WRITE(iflags_Y)
+    DEFINE_SA_READ(iflags_H)
+    DEFINE_SA_WRITE(iflags_H)
+    DEFINE_SA_READ(iunrep)
+    DEFINE_SA_WRITE(iunrep)
+    DEFINE_SA_READ(clint_mtimecmp)
+    DEFINE_SA_WRITE(clint_mtimecmp)
+    DEFINE_SA_READ(plic_girqpend)
+    DEFINE_SA_WRITE(plic_girqpend)
+    DEFINE_SA_READ(plic_girqsrvd)
+    DEFINE_SA_WRITE(plic_girqsrvd)
+    DEFINE_SA_READ(htif_tohost)
+    DEFINE_SA_WRITE(htif_tohost)
+    DEFINE_SA_READ(htif_fromhost)
+    DEFINE_SA_WRITE(htif_fromhost)
+    DEFINE_SA_READ(htif_ihalt)
+    DEFINE_SA_WRITE(htif_ihalt)
+    DEFINE_SA_READ(htif_iconsole)
+    DEFINE_SA_WRITE(htif_iconsole)
+    DEFINE_SA_READ(htif_iyield)
+    DEFINE_SA_WRITE(htif_iyield)
+    // NOLINTEND(cppcoreguidelines-macro-usage)
 
     /// \brief Reads PMA entry at a given index.
     /// \param index Index of PMA
     pma_entry &read_pma_entry(uint64_t index) {
-#ifdef DUMP_STATE_ACCESS
         auto &pma = derived().do_read_pma_entry(index);
-        fprintf(stderr, "%s::read_pma_entry(%llu) = {%s, 0x%llx, 0x%llx}\n", get_name(), index,
+        DSA_PRINTF("%s::read_pma_entry(%llu) = {%s, 0x%llx, 0x%llx}\n", get_name(), index,
             pma_get_DID_name(pma.get_istart_DID()), pma.get_start(), pma.get_length());
         return pma;
-#else
-        return derived().do_read_pma_entry(index);
-#endif
     }
 
     /// \brief Converts a target physical address to the implementation-defined fast address
@@ -993,15 +270,11 @@ class i_state_access { // CRTP
     /// \param pma_index Index of PMA where address falls
     /// \returns Corresponding implementation-defined fast address
     fast_addr get_faddr(uint64_t paddr, uint64_t pma_index) const {
-#ifdef DUMP_STATE_ACCESS
         const auto val = derived().do_get_faddr(paddr, pma_index);
-        const char *fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
-        fprintf(stderr, "%s::get_faddr(%llu(0x%llx)) = %s{%llu(0x%llx)}\n", get_name(), paddr, paddr, fast_addr_name,
-            val, val);
+        [[maybe_unused]] const auto fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
+        DSA_PRINTF("%s::get_faddr(%llu(0x%llx)) = %s{%llu(0x%llx)}\n", get_name(), paddr, paddr, fast_addr_name, val,
+            val);
         return val;
-#else
-        return derived().do_get_faddr(paddr, pma_index);
-#endif
     }
 
     /// \brief Reads a chunk of data from a memory PMA range.
@@ -1046,15 +319,11 @@ class i_state_access { // CRTP
     template <typename T, typename A = T>
     void read_memory_word(fast_addr faddr, uint64_t pma_index, T *pval) {
         static_assert(std::is_integral_v<T> && sizeof(T) <= sizeof(uint64_t), "unsupported type");
-#ifdef DUMP_STATE_ACCESS
         derived().template do_read_memory_word<T, A>(faddr, pma_index, pval);
-        const char *fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
-        fprintf(stderr, "%s::read_memory_word<%s,%s>(%s{0x%llx}, %llu) = %llu(0x%llx)\n", get_name(), pm_type_name_v<T>,
+        [[maybe_unused]] const auto fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
+        DSA_PRINTF("%s::read_memory_word<%s,%s>(%s{0x%llx}, %llu) = %llu(0x%llx)\n", get_name(), pm_type_name_v<T>,
             pm_type_name_v<A>, fast_addr_name, faddr, pma_index, static_cast<uint64_t>(*pval),
             static_cast<uint64_t>(*pval));
-#else
-        derived().template do_read_memory_word<T, A>(faddr, pma_index, pval);
-#endif
     }
 
     /// \brief Writes a word to memory.
@@ -1070,12 +339,10 @@ class i_state_access { // CRTP
     void write_memory_word(fast_addr faddr, uint64_t pma_index, T val) {
         static_assert(std::is_integral_v<T> && sizeof(T) <= sizeof(uint64_t), "unsupported type");
         derived().template do_write_memory_word<T, A>(faddr, pma_index, val);
-#ifdef DUMP_STATE_ACCESS
-        const char *fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
-        fprintf(stderr, "%s::write_memory_word<%s,%s>(%s{0x%llx}, %llu, %llu(0x%llx))\n", get_name(), pm_type_name_v<T>,
+        [[maybe_unused]] const auto fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
+        DSA_PRINTF("%s::write_memory_word<%s,%s>(%s{0x%llx}, %llu, %llu(0x%llx))\n", get_name(), pm_type_name_v<T>,
             pm_type_name_v<A>, fast_addr_name, faddr, pma_index, static_cast<uint64_t>(val),
             static_cast<uint64_t>(val));
-#endif
     }
 
     /// \brief Reads TLB's vaddr_page
@@ -1084,13 +351,9 @@ class i_state_access { // CRTP
     /// \returns Value in slot.
     template <TLB_set_index SET>
     uint64_t read_tlb_vaddr_page(uint64_t slot_index) {
-#ifdef DUMP_STATE_ACCESS
         const auto val = derived().template do_read_tlb_vaddr_page<SET>(slot_index);
-        fprintf(stderr, "%s::read_tlb_vaddr_page<%llu>(%llu) = 0x%llx\n", get_name(), SET, slot_index, val);
+        DSA_PRINTF("%s::read_tlb_vaddr_page<%llu>(%llu) = 0x%llx\n", get_name(), SET, slot_index, val);
         return val;
-#else
-        return derived().template do_read_tlb_vaddr_page<SET>(slot_index);
-#endif
     }
 
     /// \brief Reads TLB's vp_offset
@@ -1099,15 +362,11 @@ class i_state_access { // CRTP
     /// \returns Value in slot.
     template <TLB_set_index SET>
     fast_addr read_tlb_vp_offset(uint64_t slot_index) {
-#ifdef DUMP_STATE_ACCESS
-        const char *fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
+        [[maybe_unused]] const auto fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
         const auto val = derived().template do_read_tlb_vp_offset<SET>(slot_index);
-        fprintf(stderr, "%s::read_tlb_vp_offset<%llu>(%llu) = %s{0x%llx}\n", get_name(), SET, slot_index,
-            fast_addr_name, val);
+        DSA_PRINTF("%s::read_tlb_vp_offset<%llu>(%llu) = %s{0x%llx}\n", get_name(), SET, slot_index, fast_addr_name,
+            val);
         return val;
-#else
-        return derived().template do_read_tlb_vp_offset<SET>(slot_index);
-#endif
     }
 
     /// \brief Reads TLB's pma_index
@@ -1116,13 +375,9 @@ class i_state_access { // CRTP
     /// \returns Value in slot.
     template <TLB_set_index SET>
     uint64_t read_tlb_pma_index(uint64_t slot_index) {
-#ifdef DUMP_STATE_ACCESS
         const auto val = derived().template do_read_tlb_pma_index<SET>(slot_index);
-        fprintf(stderr, "%s::read_tlb_pma_index<%llu>(%llu) = %llu(0x%llx)\n", get_name(), SET, slot_index, val, val);
+        DSA_PRINTF("%s::read_tlb_pma_index<%llu>(%llu) = %llu(0x%llx)\n", get_name(), SET, slot_index, val, val);
         return val;
-#else
-        return derived().template do_read_tlb_pma_index<SET>(slot_index);
-#endif
     }
 
     /// \brief Writes to a TLB slot
@@ -1136,11 +391,9 @@ class i_state_access { // CRTP
     template <TLB_set_index SET>
     void write_tlb(uint64_t slot_index, uint64_t vaddr_page, fast_addr vp_offset, uint64_t pma_index) {
         derived().template do_write_tlb<SET>(slot_index, vaddr_page, vp_offset, pma_index);
-#ifdef DUMP_STATE_ACCESS
-        const char *fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
-        fprintf(stderr, "%s::write_tlb<%llu>(%llu, 0x%llx, %s{0x%llx}, %llu)\n", get_name(), SET, slot_index,
-            vaddr_page, fast_addr_name, vp_offset, pma_index);
-#endif
+        [[maybe_unused]] const auto fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
+        DSA_PRINTF("%s::write_tlb<%llu>(%llu, 0x%llx, %s{0x%llx}, %llu)\n", get_name(), SET, slot_index, vaddr_page,
+            fast_addr_name, vp_offset, pma_index);
     }
 
     /// \brief Marks a page as dirty
diff --git a/src/i-uarch-state-access.h b/src/i-uarch-state-access.h
index c0dd46bda..d9a3d593a 100644
--- a/src/i-uarch-state-access.h
+++ b/src/i-uarch-state-access.h
@@ -19,8 +19,34 @@
 
 #include <cstdint>
 
+#include "dump-uarch-state-access.h"
+#include "i-prefer-shadow-uarch-state.h"
+#include "meta.h"
 #include "tlb.h"
 
+// NOLINTBEGIN(cppcoreguidelines-macro-usage)
+#define DEFINE_USA_READ(REG)                                                                                           \
+    uint64_t read_##REG() {                                                                                            \
+        if constexpr (!is_an_i_prefer_shadow_uarch_state_v<DERIVED>) {                                                 \
+            const auto val = derived().do_read_##REG();                                                                \
+            DUSA_PRINTF("%s::read_" #REG "() = %llu(0x%llx)\n", get_name(), val, val);                                 \
+            return val;                                                                                                \
+        } else {                                                                                                       \
+            return derived().read_shadow_uarch_state(shadow_uarch_state_what::REG);                                    \
+        }                                                                                                              \
+    }
+
+#define DEFINE_USA_WRITE(REG)                                                                                          \
+    void write_##REG(uint64_t val) {                                                                                   \
+        if constexpr (!is_an_i_prefer_shadow_uarch_state_v<DERIVED>) {                                                 \
+            derived().do_write_##REG(val);                                                                             \
+            DUSA_PRINTF("%s::write_" #REG "(%llu(0x%llx))\n", get_name(), val, val);                                   \
+        } else {                                                                                                       \
+            derived().write_shadow_uarch_state(shadow_uarch_state_what::REG, val);                                     \
+        }                                                                                                              \
+    }
+// NOLINTEND(cppcoreguidelines-macro-usage)
+
 namespace cartesi {
 
 // Interface for microarchitecture state access
@@ -38,94 +64,49 @@ class i_uarch_state_access { // CRTP
     }
 
 public:
-    auto read_x(int i) {
-#ifdef DUMP_UARCH_STATE_ACCESS
-        const auto val = derived().do_read_x(i);
-        printf("%s::read_x(%d) = %llu(0x%llx)\n", get_name(), i, val, val);
-        return val;
-#else
-        return derived().do_read_x(i);
-#endif
-    }
-
-    auto write_x(int i, uint64_t val) {
-        derived().do_write_x(i, val);
-#ifdef DUMP_UARCH_STATE_ACCESS
-        printf("%s::write_x(%d, %llu)\n", get_name(), i, val);
-#endif
-    }
-
-    auto read_pc() {
-#ifdef DUMP_UARCH_STATE_ACCESS
-        const auto val = derived().do_read_pc();
-        printf("%s::read_pc() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_pc();
-#endif
-    }
-
-    auto write_pc(uint64_t val) {
-        derived().do_write_pc(val);
-#ifdef DUMP_UARCH_STATE_ACCESS
-        printf("%s::write_pc(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    auto read_cycle() {
-#ifdef DUMP_UARCH_STATE_ACCESS
-        const auto val = derived().do_read_cycle();
-        printf("%s::read_cycle() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_cycle();
-#endif
-    }
-
-    auto read_halt_flag() {
-#ifdef DUMP_UARCH_STATE_ACCESS
-        const auto val = derived().do_read_halt_flag();
-        printf("%s::read_halt_flag() = %llu(0x%llx)\n", get_name(), val, val);
-        return val;
-#else
-        return derived().do_read_halt_flag();
-#endif
-    }
-
-    auto write_halt_flag(uint64_t val) {
-        derived().do_write_halt_flag(val);
-#ifdef DUMP_UARCH_STATE_ACCESS
-        printf("%s::write_halt_flag(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
-
-    auto write_cycle(uint64_t val) {
-        derived().do_write_cycle(val);
-#ifdef DUMP_UARCH_STATE_ACCESS
-        printf("%s::write_cycle(%llu(0x%llx))\n", get_name(), val, val);
-#endif
-    }
+    uint64_t read_uarch_x(int i) {
+        if constexpr (!is_an_i_prefer_shadow_uarch_state_v<DERIVED>) {
+            const auto val = derived().do_read_uarch_x(i);
+            DUSA_PRINTF("%s::read_uarch_x(%d) = %llu(0x%llx)\n", get_name(), i, val, val);
+            return val;
+        } else {
+            return derived().read_shadow_uarch_state(shadow_uarch_state_get_what(shadow_uarch_state_what::uarch_x0, i));
+        }
+    }
+
+    void write_uarch_x(int i, uint64_t val) {
+        if constexpr (!is_an_i_prefer_shadow_uarch_state_v<DERIVED>) {
+            derived().do_write_uarch_x(i, val);
+            DUSA_PRINTF("%s::write_uarch_x(%d, %llu)\n", get_name(), i, val);
+        } else {
+            derived().write_shadow_uarch_state(shadow_uarch_state_get_what(shadow_uarch_state_what::uarch_x0, i), val);
+        }
+    }
+
+    // Define read and write methods for each register in the shadow uarch state
+    // NOLINTBEGIN(cppcoreguidelines-macro-usage)
+    DEFINE_USA_READ(uarch_halt_flag)
+    DEFINE_USA_WRITE(uarch_halt_flag)
+    DEFINE_USA_READ(uarch_cycle)
+    DEFINE_USA_WRITE(uarch_cycle)
+    DEFINE_USA_READ(uarch_pc)
+    DEFINE_USA_WRITE(uarch_pc)
+    // NOLINTEND(cppcoreguidelines-macro-usage)
 
     uint64_t read_word(uint64_t paddr) {
-#ifdef DUMP_UARCH_STATE_ACCESS
         const auto val = derived().do_read_word(paddr);
-        printf("%s::read_word(phys_addr{0x%llx}) = %llu(0x%llx)\n", get_name(), paddr, val, val);
+        DUSA_PRINTF("%s::read_word(phys_addr{0x%llx}) = %llu(0x%llx)\n", get_name(), paddr, val, val);
         return val;
-#else
-        return derived().do_read_word(paddr);
-#endif
     }
 
     void write_word(uint64_t paddr, uint64_t val) {
         derived().do_write_word(paddr, val);
-#ifdef DUMP_UARCH_STATE_ACCESS
-        printf("%s::write_word(phys_addr{0x%llx}, %llu(0x%llx))\n", get_name(), paddr, val, val);
-#endif
+        DUSA_PRINTF("%s::write_word(phys_addr{0x%llx}, %llu(0x%llx))\n", get_name(), paddr, val, val);
     }
 
     /// \brief Resets uarch to pristine state
-    void reset_state() {
-        return derived().do_reset_state();
+    void reset_uarch() {
+        return derived().do_reset_uarch();
     }
 
     void putchar(uint8_t c) {
@@ -146,6 +127,14 @@ class i_uarch_state_access { // CRTP
     }
 };
 
+/// \brief SFINAE test implementation of the i_uarch_state_access interface
+template <typename DERIVED>
+using is_an_i_uarch_state_access =
+    std::integral_constant<bool, is_template_base_of_v<i_uarch_state_access, std::remove_cvref_t<DERIVED>>>;
+
+template <typename DERIVED>
+constexpr bool is_an_i_uarch_state_access_v = is_an_i_uarch_state_access<DERIVED>::value;
+
 } // namespace cartesi
 
 #endif
diff --git a/src/interpret.cpp b/src/interpret.cpp
index bd8f418de..26923c98f 100644
--- a/src/interpret.cpp
+++ b/src/interpret.cpp
@@ -6056,7 +6056,7 @@ interpreter_break_reason interpret(STATE_ACCESS a, uint64_t mcycle_end) {
     }
     if (status == execute_status::success_and_yield) {
         return interpreter_break_reason::yielded_softly;
-    }                                      // Reached mcycle_end
+    } // Reached mcycle_end
     assert(a.read_mcycle() == mcycle_end); // LCOV_EXCL_LINE
     return interpreter_break_reason::reached_target_mcycle;
 }
diff --git a/src/pm-type-name.h b/src/pm-type-name.h
index 6f3d61e92..d93024277 100644
--- a/src/pm-type-name.h
+++ b/src/pm-type-name.h
@@ -28,6 +28,7 @@ struct pm_type_name {
 template <typename T>
 constexpr const char *pm_type_name_v = pm_type_name<T>::value;
 
+// NOLINTBEGIN(cppcoreguidelines-macro-usage)
 #define PM_TYPE_NAME(type)                                                                                             \
     template <>                                                                                                        \
     struct pm_type_name<type> {                                                                                        \
@@ -42,6 +43,7 @@ PM_TYPE_NAME(uint32_t);
 PM_TYPE_NAME(int32_t);
 PM_TYPE_NAME(uint64_t);
 PM_TYPE_NAME(int64_t);
+// NOLINTEND(cppcoreguidelines-macro-usage)
 
 } // namespace cartesi
 
diff --git a/src/record-step-state-access.h b/src/record-step-state-access.h
index 6c06adce7..b238a864a 100644
--- a/src/record-step-state-access.h
+++ b/src/record-step-state-access.h
@@ -23,6 +23,7 @@
 
 #include "compiler-defines.h"
 #include "i-accept-scoped-note.h"
+#include "i-prefer-shadow-state.h"
 #include "i-state-access.h"
 #include "machine.h"
 #include "shadow-pmas.h"
@@ -48,7 +49,8 @@ struct i_state_access_fast_addr<record_step_state_access> {
 /// \brief Records machine state access into a step log file
 class record_step_state_access :
     public i_state_access<record_step_state_access>,
-    public i_accept_scoped_note<record_step_state_access> {
+    public i_accept_scoped_note<record_step_state_access>,
+    public i_prefer_shadow_state<record_step_state_access> {
     constexpr static int TREE_LOG2_ROOT_SIZE = machine_merkle_tree::get_log2_root_size();
     constexpr static int TREE_LOG2_PAGE_SIZE = machine_merkle_tree::get_log2_page_size();
     constexpr static uint64_t TREE_PAGE_SIZE = UINT64_C(1) << LOG2_PAGE_SIZE;
@@ -201,338 +203,22 @@ class record_step_state_access :
     }
 
     // -----
-    // i_state_access interface implementation
+    // i_prefer_shadow_state interface implementation
     // -----
-    friend i_state_access<record_step_state_access>;
-
-    uint64_t do_read_x(int i) const {
-        return log_read_reg(machine_reg_enum(machine_reg::x0, i));
-    }
-
-    void do_write_x(int i, uint64_t val) {
-        assert(i != 0);
-        log_write_reg(machine_reg_enum(machine_reg::x0, i), val);
-    }
-
-    uint64_t do_read_f(int i) const {
-        return log_read_reg(machine_reg_enum(machine_reg::f0, i));
-    }
-
-    void do_write_f(int i, uint64_t val) {
-        log_write_reg(machine_reg_enum(machine_reg::f0, i), val);
-    }
-
-    uint64_t do_read_pc() const {
-        return log_read_reg(machine_reg::pc);
-    }
-
-    void do_write_pc(uint64_t val) {
-        log_write_reg(machine_reg::pc, val);
-    }
-
-    uint64_t do_read_fcsr() const {
-        return log_read_reg(machine_reg::fcsr);
-    }
-
-    void do_write_fcsr(uint64_t val) {
-        log_write_reg(machine_reg::fcsr, val);
-    }
-
-    uint64_t do_read_icycleinstret() const {
-        return log_read_reg(machine_reg::icycleinstret);
-    }
-
-    void do_write_icycleinstret(uint64_t val) {
-        log_write_reg(machine_reg::icycleinstret, val);
-    }
-
-    uint64_t do_read_mvendorid() const {
-        return log_read_reg(machine_reg::mvendorid);
-    }
-
-    uint64_t do_read_marchid() const {
-        return log_read_reg(machine_reg::marchid);
-    }
-
-    uint64_t do_read_mimpid() const {
-        return log_read_reg(machine_reg::mimpid);
-    }
-
-    uint64_t do_read_mcycle() const {
-        return log_read_reg(machine_reg::mcycle);
-    }
-
-    void do_write_mcycle(uint64_t val) {
-        log_write_reg(machine_reg::mcycle, val);
-    }
-
-    uint64_t do_read_mstatus() const {
-        return log_read_reg(machine_reg::mstatus);
-    }
-
-    void do_write_mstatus(uint64_t val) {
-        log_write_reg(machine_reg::mstatus, val);
-    }
-
-    uint64_t do_read_menvcfg() const {
-        return log_read_reg(machine_reg::menvcfg);
-    }
-
-    void do_write_menvcfg(uint64_t val) {
-        log_write_reg(machine_reg::menvcfg, val);
-    }
-
-    uint64_t do_read_mtvec() const {
-        return log_read_reg(machine_reg::mtvec);
-    }
+    friend i_prefer_shadow_state<record_step_state_access>;
 
-    void do_write_mtvec(uint64_t val) {
-        log_write_reg(machine_reg::mtvec, val);
+    uint64_t do_read_shadow_state(shadow_state_what what) {
+        return log_read_reg(machine_reg_enum(what));
     }
 
-    uint64_t do_read_mscratch() const {
-        return log_read_reg(machine_reg::mscratch);
+    void do_write_shadow_state(shadow_state_what what, uint64_t val) {
+        log_write_reg(machine_reg_enum(what), val);
     }
 
-    void do_write_mscratch(uint64_t val) {
-        log_write_reg(machine_reg::mscratch, val);
-    }
-
-    uint64_t do_read_mepc() const {
-        return log_read_reg(machine_reg::mepc);
-    }
-
-    void do_write_mepc(uint64_t val) {
-        log_write_reg(machine_reg::mepc, val);
-    }
-
-    uint64_t do_read_mcause() const {
-        return log_read_reg(machine_reg::mcause);
-    }
-
-    void do_write_mcause(uint64_t val) {
-        log_write_reg(machine_reg::mcause, val);
-    }
-
-    uint64_t do_read_mtval() const {
-        return log_read_reg(machine_reg::mtval);
-    }
-
-    void do_write_mtval(uint64_t val) {
-        log_write_reg(machine_reg::mtval, val);
-    }
-
-    uint64_t do_read_misa() const {
-        return log_read_reg(machine_reg::misa);
-    }
-
-    void do_write_misa(uint64_t val) {
-        log_write_reg(machine_reg::misa, val);
-    }
-
-    uint64_t do_read_mie() const {
-        return log_read_reg(machine_reg::mie);
-    }
-
-    void do_write_mie(uint64_t val) {
-        log_write_reg(machine_reg::mie, val);
-    }
-
-    uint64_t do_read_mip() const {
-        return log_read_reg(machine_reg::mip);
-    }
-
-    void do_write_mip(uint64_t val) {
-        log_write_reg(machine_reg::mip, val);
-    }
-
-    uint64_t do_read_medeleg() const {
-        return log_read_reg(machine_reg::medeleg);
-    }
-
-    void do_write_medeleg(uint64_t val) {
-        log_write_reg(machine_reg::medeleg, val);
-    }
-
-    uint64_t do_read_mideleg() const {
-        return log_read_reg(machine_reg::mideleg);
-    }
-
-    void do_write_mideleg(uint64_t val) {
-        log_write_reg(machine_reg::mideleg, val);
-    }
-
-    uint64_t do_read_mcounteren() const {
-        return log_read_reg(machine_reg::mcounteren);
-    }
-
-    void do_write_mcounteren(uint64_t val) {
-        log_write_reg(machine_reg::mcounteren, val);
-    }
-
-    uint64_t do_read_senvcfg() const {
-        return log_read_reg(machine_reg::senvcfg);
-    }
-
-    void do_write_senvcfg(uint64_t val) {
-        log_write_reg(machine_reg::senvcfg, val);
-    }
-
-    uint64_t do_read_stvec() const {
-        return log_read_reg(machine_reg::stvec);
-    }
-
-    void do_write_stvec(uint64_t val) {
-        log_write_reg(machine_reg::stvec, val);
-    }
-
-    uint64_t do_read_sscratch() const {
-        return log_read_reg(machine_reg::sscratch);
-    }
-
-    void do_write_sscratch(uint64_t val) {
-        log_write_reg(machine_reg::sscratch, val);
-    }
-
-    uint64_t do_read_sepc() const {
-        return log_read_reg(machine_reg::sepc);
-    }
-
-    void do_write_sepc(uint64_t val) {
-        log_write_reg(machine_reg::sepc, val);
-    }
-
-    uint64_t do_read_scause() const {
-        return log_read_reg(machine_reg::scause);
-    }
-
-    void do_write_scause(uint64_t val) {
-        log_write_reg(machine_reg::scause, val);
-    }
-
-    uint64_t do_read_stval() const {
-        return log_read_reg(machine_reg::stval);
-    }
-
-    void do_write_stval(uint64_t val) {
-        log_write_reg(machine_reg::stval, val);
-    }
-
-    uint64_t do_read_satp() const {
-        return log_read_reg(machine_reg::satp);
-    }
-
-    void do_write_satp(uint64_t val) {
-        log_write_reg(machine_reg::satp, val);
-    }
-
-    uint64_t do_read_scounteren() const {
-        return log_read_reg(machine_reg::scounteren);
-    }
-
-    void do_write_scounteren(uint64_t val) {
-        log_write_reg(machine_reg::scounteren, val);
-    }
-
-    uint64_t do_read_ilrsc() const {
-        return log_read_reg(machine_reg::ilrsc);
-    }
-
-    void do_write_ilrsc(uint64_t val) {
-        log_write_reg(machine_reg::ilrsc, val);
-    }
-
-    uint64_t do_read_iprv() const {
-        return log_read_reg(machine_reg::iprv);
-    }
-
-    void do_write_iprv(uint64_t val) {
-        log_write_reg(machine_reg::iprv, val);
-    }
-
-    void do_write_iflags_X(uint64_t val) {
-        log_write_reg(machine_reg::iflags_X, val);
-    }
-
-    uint64_t do_read_iflags_X() const {
-        return log_read_reg(machine_reg::iflags_X);
-    }
-
-    void do_write_iflags_Y(uint64_t val) {
-        log_write_reg(machine_reg::iflags_Y, val);
-    }
-
-    uint64_t do_read_iflags_Y() const {
-        return log_read_reg(machine_reg::iflags_Y);
-    }
-
-    void do_write_iflags_H(uint64_t val) {
-        log_write_reg(machine_reg::iflags_H, val);
-    }
-
-    uint64_t do_read_iflags_H() const {
-        return log_read_reg(machine_reg::iflags_H);
-    }
-
-    uint64_t do_read_iunrep() const {
-        return log_read_reg(machine_reg::iunrep);
-    }
-
-    void do_write_iunrep(uint64_t val) {
-        log_write_reg(machine_reg::iunrep, val);
-    }
-
-    uint64_t do_read_clint_mtimecmp() const {
-        return log_read_reg(machine_reg::clint_mtimecmp);
-    }
-
-    void do_write_clint_mtimecmp(uint64_t val) {
-        log_write_reg(machine_reg::clint_mtimecmp, val);
-    }
-
-    uint64_t do_read_plic_girqpend() const {
-        return log_read_reg(machine_reg::plic_girqpend);
-    }
-
-    void do_write_plic_girqpend(uint64_t val) {
-        log_write_reg(machine_reg::plic_girqpend, val);
-    }
-
-    uint64_t do_read_plic_girqsrvd() const {
-        return log_read_reg(machine_reg::plic_girqsrvd);
-    }
-
-    void do_write_plic_girqsrvd(uint64_t val) {
-        log_write_reg(machine_reg::plic_girqsrvd, val);
-    }
-
-    uint64_t do_read_htif_fromhost() const {
-        return log_read_reg(machine_reg::htif_fromhost);
-    }
-
-    void do_write_htif_fromhost(uint64_t val) {
-        log_write_reg(machine_reg::htif_fromhost, val);
-    }
-
-    uint64_t do_read_htif_tohost() const {
-        return log_read_reg(machine_reg::htif_tohost);
-    }
-
-    void do_write_htif_tohost(uint64_t val) {
-        log_write_reg(machine_reg::htif_tohost, val);
-    }
-
-    uint64_t do_read_htif_ihalt() const {
-        return log_read_reg(machine_reg::htif_ihalt);
-    }
-
-    uint64_t do_read_htif_iconsole() const {
-        return log_read_reg(machine_reg::htif_iconsole);
-    }
-
-    uint64_t do_read_htif_iyield() const {
-        return log_read_reg(machine_reg::htif_iyield);
-    }
+    // -----
+    // i_state_access interface implementation
+    // -----
+    friend i_state_access<record_step_state_access>;
 
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
     bool do_read_memory(uint64_t paddr, const unsigned char *data, uint64_t length) const {
diff --git a/src/replay-step-state-access.h b/src/replay-step-state-access.h
index a51f915c6..622335cbd 100644
--- a/src/replay-step-state-access.h
+++ b/src/replay-step-state-access.h
@@ -23,6 +23,7 @@
 #include "compiler-defines.h"
 #include "host-addr.h"
 #include "i-accept-scoped-note.h"
+#include "i-prefer-shadow-state.h"
 #include "i-state-access.h"
 #include "mock-pma-entry.h"
 #include "pma-constants.h"
@@ -76,7 +77,8 @@ static inline bool validate_and_advance_offset(uint64_t max, uint64_t current, u
 // \brief Provides machine state from a step log file
 class replay_step_state_access :
     public i_state_access<replay_step_state_access>,
-    public i_accept_scoped_note<replay_step_state_access> {
+    public i_accept_scoped_note<replay_step_state_access>,
+    public i_prefer_shadow_state<replay_step_state_access> {
 public:
     using address_type = uint64_t;
     using data_type = unsigned char[PMA_PAGE_SIZE];
@@ -331,18 +333,6 @@ class replay_step_state_access :
         return page_log;
     }
 
-    /// \brief Convert physical address to host address
-    /// \param paddr The physical address
-    /// \return Host address
-    host_addr do_get_faddr(uint64_t paddr, uint64_t /* pma_index */ = 0) const {
-        // This assumes the corresponding page has been touched
-        // (replay_step_state_access makes sure of it for any address we try to convert)
-        const auto paddr_page = paddr & ~PAGE_OFFSET_MASK;
-        auto *page_log = find_page(paddr_page);
-        const auto offset = paddr & PAGE_OFFSET_MASK;
-        return cast_ptr_to_host_addr(page_log->data) + offset;
-    }
-
     // \brief Compute the current machine root hash
     hash_type compute_root_hash() {
         //??D Here we should only do this for dirty pages, right?
@@ -429,337 +419,33 @@ class replay_step_state_access :
     }
 
     // -----
-    // i_state_access interface implementation
+    // i_prefer_shadow_state interface implementation
     // -----
-    friend i_state_access<replay_step_state_access>;
-
-    uint64_t do_read_x(int i) {
-        return check_read_reg(machine_reg_enum(machine_reg::x0, i));
-    }
-
-    void do_write_x(int i, uint64_t val) {
-        assert(i != 0);
-        check_write_reg(machine_reg_enum(machine_reg::x0, i), val);
-    }
-
-    uint64_t do_read_f(int i) {
-        return check_read_reg(machine_reg_enum(machine_reg::f0, i));
-    }
-
-    void do_write_f(int i, uint64_t val) {
-        check_write_reg(machine_reg_enum(machine_reg::f0, i), val);
-    }
-
-    uint64_t do_read_pc() {
-        return check_read_reg(machine_reg::pc);
-    }
+    friend i_prefer_shadow_state<replay_step_state_access>;
 
-    void do_write_pc(uint64_t val) {
-        check_write_reg(machine_reg::pc, val);
+    uint64_t do_read_shadow_state(shadow_state_what what) {
+        return check_read_reg(machine_reg_enum(what));
     }
 
-    uint64_t do_read_fcsr() {
-        return check_read_reg(machine_reg::fcsr);
+    void do_write_shadow_state(shadow_state_what what, uint64_t val) {
+        check_write_reg(machine_reg_enum(what), val);
     }
 
-    void do_write_fcsr(uint64_t val) {
-        check_write_reg(machine_reg::fcsr, val);
-    }
-
-    uint64_t do_read_icycleinstret() {
-        return check_read_reg(machine_reg::icycleinstret);
-    }
-
-    void do_write_icycleinstret(uint64_t val) {
-        check_write_reg(machine_reg::icycleinstret, val);
-    }
-
-    uint64_t do_read_mvendorid() {
-        return check_read_reg(machine_reg::mvendorid);
-    }
-
-    uint64_t do_read_marchid() {
-        return check_read_reg(machine_reg::marchid);
-    }
-
-    uint64_t do_read_mimpid() {
-        return check_read_reg(machine_reg::mimpid);
-    }
-
-    uint64_t do_read_mcycle() {
-        return check_read_reg(machine_reg::mcycle);
-    }
-
-    void do_write_mcycle(uint64_t val) {
-        check_write_reg(machine_reg::mcycle, val);
-    }
-
-    uint64_t do_read_mstatus() {
-        return check_read_reg(machine_reg::mstatus);
-    }
-
-    void do_write_mstatus(uint64_t val) {
-        check_write_reg(machine_reg::mstatus, val);
-    }
-
-    uint64_t do_read_mtvec() {
-        return check_read_reg(machine_reg::mtvec);
-    }
-
-    void do_write_mtvec(uint64_t val) {
-        check_write_reg(machine_reg::mtvec, val);
-    }
-
-    uint64_t do_read_mscratch() {
-        return check_read_reg(machine_reg::mscratch);
-    }
-
-    void do_write_mscratch(uint64_t val) {
-        check_write_reg(machine_reg::mscratch, val);
-    }
-
-    uint64_t do_read_mepc() {
-        return check_read_reg(machine_reg::mepc);
-    }
-
-    void do_write_mepc(uint64_t val) {
-        check_write_reg(machine_reg::mepc, val);
-    }
-
-    uint64_t do_read_mcause() {
-        return check_read_reg(machine_reg::mcause);
-    }
-
-    void do_write_mcause(uint64_t val) {
-        check_write_reg(machine_reg::mcause, val);
-    }
-
-    uint64_t do_read_mtval() {
-        return check_read_reg(machine_reg::mtval);
-    }
-
-    void do_write_mtval(uint64_t val) {
-        check_write_reg(machine_reg::mtval, val);
-    }
-
-    uint64_t do_read_misa() {
-        return check_read_reg(machine_reg::misa);
-    }
-
-    void do_write_misa(uint64_t val) {
-        check_write_reg(machine_reg::misa, val);
-    }
-
-    uint64_t do_read_mie() {
-        return check_read_reg(machine_reg::mie);
-    }
-
-    void do_write_mie(uint64_t val) {
-        check_write_reg(machine_reg::mie, val);
-    }
-
-    uint64_t do_read_mip() {
-        return check_read_reg(machine_reg::mip);
-    }
-
-    void do_write_mip(uint64_t val) {
-        check_write_reg(machine_reg::mip, val);
-    }
-
-    uint64_t do_read_medeleg() {
-        return check_read_reg(machine_reg::medeleg);
-    }
-
-    void do_write_medeleg(uint64_t val) {
-        check_write_reg(machine_reg::medeleg, val);
-    }
-
-    uint64_t do_read_mideleg() {
-        return check_read_reg(machine_reg::mideleg);
-    }
-
-    void do_write_mideleg(uint64_t val) {
-        check_write_reg(machine_reg::mideleg, val);
-    }
-
-    uint64_t do_read_mcounteren() {
-        return check_read_reg(machine_reg::mcounteren);
-    }
-
-    void do_write_mcounteren(uint64_t val) {
-        check_write_reg(machine_reg::mcounteren, val);
-    }
-
-    uint64_t do_read_senvcfg() {
-        return check_read_reg(machine_reg::senvcfg);
-    }
-
-    void do_write_senvcfg(uint64_t val) {
-        check_write_reg(machine_reg::senvcfg, val);
-    }
-
-    uint64_t do_read_menvcfg() {
-        return check_read_reg(machine_reg::menvcfg);
-    }
-
-    void do_write_menvcfg(uint64_t val) {
-        check_write_reg(machine_reg::menvcfg, val);
-    }
-
-    uint64_t do_read_stvec() {
-        return check_read_reg(machine_reg::stvec);
-    }
-
-    void do_write_stvec(uint64_t val) {
-        check_write_reg(machine_reg::stvec, val);
-    }
-
-    uint64_t do_read_sscratch() {
-        return check_read_reg(machine_reg::sscratch);
-    }
-
-    void do_write_sscratch(uint64_t val) {
-        check_write_reg(machine_reg::sscratch, val);
-    }
-
-    uint64_t do_read_sepc() {
-        return check_read_reg(machine_reg::sepc);
-    }
-
-    void do_write_sepc(uint64_t val) {
-        check_write_reg(machine_reg::sepc, val);
-    }
-
-    uint64_t do_read_scause() {
-        return check_read_reg(machine_reg::scause);
-    }
-
-    void do_write_scause(uint64_t val) {
-        check_write_reg(machine_reg::scause, val);
-    }
-
-    uint64_t do_read_stval() {
-        return check_read_reg(machine_reg::stval);
-    }
-
-    void do_write_stval(uint64_t val) {
-        check_write_reg(machine_reg::stval, val);
-    }
-
-    uint64_t do_read_satp() {
-        return check_read_reg(machine_reg::satp);
-    }
-
-    void do_write_satp(uint64_t val) {
-        check_write_reg(machine_reg::satp, val);
-    }
-
-    uint64_t do_read_scounteren() {
-        return check_read_reg(machine_reg::scounteren);
-    }
-
-    void do_write_scounteren(uint64_t val) {
-        check_write_reg(machine_reg::scounteren, val);
-    }
-
-    uint64_t do_read_ilrsc() {
-        return check_read_reg(machine_reg::ilrsc);
-    }
-
-    void do_write_ilrsc(uint64_t val) {
-        check_write_reg(machine_reg::ilrsc, val);
-    }
-
-    uint64_t do_read_iprv() {
-        return check_read_reg(machine_reg::iprv);
-    }
-
-    void do_write_iprv(uint64_t val) {
-        check_write_reg(machine_reg::iprv, val);
-    }
-
-    uint64_t do_read_iflags_X() {
-        return check_read_reg(machine_reg::iflags_X);
-    }
-
-    void do_write_iflags_X(uint64_t val) {
-        check_write_reg(machine_reg::iflags_X, val);
-    }
-
-    uint64_t do_read_iflags_Y() {
-        return check_read_reg(machine_reg::iflags_Y);
-    }
-
-    void do_write_iflags_Y(uint64_t val) {
-        check_write_reg(machine_reg::iflags_Y, val);
-    }
-
-    uint64_t do_read_iflags_H() {
-        return check_read_reg(machine_reg::iflags_H);
-    }
-
-    void do_write_iflags_H(uint64_t val) {
-        check_write_reg(machine_reg::iflags_H, val);
-    }
-
-    uint64_t do_read_iunrep() {
-        return check_read_reg(machine_reg::iunrep);
-    }
-
-    void do_write_iunrep(uint64_t val) {
-        check_write_reg(machine_reg::iunrep, val);
-    }
-
-    uint64_t do_read_clint_mtimecmp() {
-        return check_read_reg(machine_reg::clint_mtimecmp);
-    }
-
-    void do_write_clint_mtimecmp(uint64_t val) {
-        check_write_reg(machine_reg::clint_mtimecmp, val);
-    }
-
-    uint64_t do_read_plic_girqpend() {
-        return check_read_reg(machine_reg::plic_girqpend);
-    }
-
-    void do_write_plic_girqpend(uint64_t val) {
-        check_write_reg(machine_reg::plic_girqpend, val);
-    }
-
-    uint64_t do_read_plic_girqsrvd() {
-        return check_read_reg(machine_reg::plic_girqsrvd);
-    }
-
-    void do_write_plic_girqsrvd(uint64_t val) {
-        check_write_reg(machine_reg::plic_girqsrvd, val);
-    }
-
-    uint64_t do_read_htif_fromhost() {
-        return check_read_reg(machine_reg::htif_fromhost);
-    }
-
-    void do_write_htif_fromhost(uint64_t val) {
-        check_write_reg(machine_reg::htif_fromhost, val);
-    }
-
-    uint64_t do_read_htif_tohost() {
-        return check_read_reg(machine_reg::htif_tohost);
-    }
-
-    void do_write_htif_tohost(uint64_t val) {
-        check_write_reg(machine_reg::htif_tohost, val);
-    }
-
-    uint64_t do_read_htif_ihalt() {
-        return check_read_reg(machine_reg::htif_ihalt);
-    }
-
-    uint64_t do_read_htif_iconsole() {
-        return check_read_reg(machine_reg::htif_iconsole);
-    }
+    // -----
+    // i_state_access interface implementation
+    // -----
+    friend i_state_access<replay_step_state_access>;
 
-    uint64_t do_read_htif_iyield() {
-        return check_read_reg(machine_reg::htif_iyield);
+    /// \brief Convert physical address to host address
+    /// \param paddr The physical address
+    /// \return Host address
+    host_addr do_get_faddr(uint64_t paddr, uint64_t /* pma_index */ = 0) const {
+        // This assumes the corresponding page has been touched
+        // (replay_step_state_access makes sure of it for any address we try to convert)
+        const auto paddr_page = paddr & ~PAGE_OFFSET_MASK;
+        auto *page_log = find_page(paddr_page);
+        const auto offset = paddr & PAGE_OFFSET_MASK;
+        return cast_ptr_to_host_addr(page_log->data) + offset;
     }
 
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
diff --git a/src/shadow-state.h b/src/shadow-state.h
index 0d22ea2c6..60dd9691b 100644
--- a/src/shadow-state.h
+++ b/src/shadow-state.h
@@ -197,6 +197,10 @@ static constexpr shadow_state_what shadow_state_get_what(uint64_t paddr) {
     return static_cast<shadow_state_what>(paddr);
 }
 
+static constexpr shadow_state_what shadow_state_get_what(shadow_state_what what, int i) {
+    return static_cast<shadow_state_what>(static_cast<uint64_t>(what) + i * sizeof(uint64_t));
+}
+
 static constexpr const char *shadow_state_get_what_name(shadow_state_what what) {
     const auto paddr = static_cast<uint64_t>(what);
     if (paddr < PMA_SHADOW_STATE_START || paddr - PMA_SHADOW_STATE_START >= sizeof(shadow_state) ||
diff --git a/src/shadow-uarch-state.h b/src/shadow-uarch-state.h
index efcc72c73..bc92c2573 100644
--- a/src/shadow-uarch-state.h
+++ b/src/shadow-uarch-state.h
@@ -85,6 +85,10 @@ static constexpr shadow_uarch_state_what shadow_uarch_state_get_what(uint64_t pa
     return static_cast<shadow_uarch_state_what>(paddr);
 }
 
+static constexpr shadow_uarch_state_what shadow_uarch_state_get_what(shadow_uarch_state_what what, int i) {
+    return static_cast<shadow_uarch_state_what>(static_cast<uint64_t>(what) + i * sizeof(uint64_t));
+}
+
 static constexpr const char *shadow_uarch_state_get_what_name(shadow_uarch_state_what what) {
     const auto paddr = static_cast<uint64_t>(what);
     if (paddr < PMA_SHADOW_UARCH_STATE_START || paddr - PMA_SHADOW_UARCH_STATE_START >= sizeof(shadow_uarch_state) ||
diff --git a/src/uarch-interpret.cpp b/src/uarch-interpret.cpp
index 8a3d4409e..4dcfa9c68 100644
--- a/src/uarch-interpret.cpp
+++ b/src/uarch-interpret.cpp
@@ -27,7 +27,7 @@ namespace cartesi {
 extern template UArchStepStatus uarch_step(uarch_state_access &a);
 
 uarch_interpreter_break_reason uarch_interpret(uarch_state_access &a, uint64_t cycle_end) {
-    uint64_t cycle = a.read_cycle();
+    uint64_t cycle = a.read_uarch_cycle();
     if (cycle_end < cycle) {
         throw std::invalid_argument{"uarch_cycle is past"};
     }
diff --git a/src/uarch-record-state-access.h b/src/uarch-record-state-access.h
index 5d0398c93..d7bad6ad1 100644
--- a/src/uarch-record-state-access.h
+++ b/src/uarch-record-state-access.h
@@ -31,6 +31,7 @@
 #include "host-addr.h"
 #include "i-accept-scoped-note.h"
 #include "i-hasher.h"
+#include "i-prefer-shadow-uarch-state.h"
 #include "i-uarch-state-access.h"
 #include "machine-merkle-tree.h"
 #include "machine.h"
@@ -52,7 +53,8 @@ using namespace std::string_literals;
 /// \details The uarch_record_state_access logs all access to the machine state.
 class uarch_record_state_access :
     public i_uarch_state_access<uarch_record_state_access>,
-    public i_accept_scoped_note<uarch_record_state_access> {
+    public i_accept_scoped_note<uarch_record_state_access>,
+    public i_prefer_shadow_uarch_state<uarch_record_state_access> {
 
     using hasher_type = machine_merkle_tree::hasher_type;
     using hash_type = machine_merkle_tree::hash_type;
@@ -225,54 +227,28 @@ class uarch_record_state_access :
     }
 
     // -----
-    // i_uarch_state_access interface implementation
+    // i_prefer_shadow_uarch_state interface implementation
     // -----
-    friend i_uarch_state_access<uarch_record_state_access>;
-
-    uint64_t do_read_x(int i) const {
-        return log_read_reg_access(machine_reg_enum(machine_reg::uarch_x0, i));
-    }
-
-    void do_write_x(int i, uint64_t val) {
-        assert(i != 0);
-        log_write_reg_access(machine_reg_enum(machine_reg::uarch_x0, i), val);
-    }
-
-    uint64_t do_read_pc() const {
-        return log_read_reg_access(machine_reg::uarch_pc);
-    }
-
-    void do_write_pc(uint64_t val) {
-        log_write_reg_access(machine_reg::uarch_pc, val);
-    }
+    friend i_prefer_shadow_uarch_state<uarch_record_state_access>;
 
-    uint64_t do_read_cycle() const {
-        return log_read_reg_access(machine_reg::uarch_cycle);
+    uint64_t do_read_shadow_uarch_state(shadow_uarch_state_what what) const {
+        return log_read_reg_access(machine_reg_enum(what));
     }
 
-    void do_write_cycle(uint64_t val) {
-        log_write_reg_access(machine_reg::uarch_cycle, val);
+    void do_write_shadow_uarch_state(shadow_uarch_state_what what, uint64_t val) {
+        log_write_reg_access(machine_reg_enum(what), val);
     }
 
-    uint64_t do_read_halt_flag() const {
-        return log_read_reg_access(machine_reg::uarch_halt_flag);
-    }
-
-    void do_write_halt_flag(uint64_t val) {
-        log_write_reg_access(machine_reg::uarch_halt_flag, val);
-    }
+    // -----
+    // i_uarch_state_access interface implementation
+    // -----
+    friend i_uarch_state_access<uarch_record_state_access>;
 
     uint64_t do_read_word(uint64_t paddr) const {
-        if ((paddr & (sizeof(uint64_t) - 1)) != 0) {
-            throw std::runtime_error("misaligned read from uarch");
-        }
         return log_read_word_access(paddr, machine::get_what_name(paddr));
     }
 
     void do_write_word(uint64_t paddr, uint64_t val) {
-        if ((paddr & (sizeof(uint64_t) - 1)) != 0) {
-            throw std::runtime_error("misaligned write to uarch");
-        }
         log_write_access(
             paddr, log2_size_v<uint64_t>,
             [this, paddr, val]() {
@@ -307,7 +283,7 @@ class uarch_record_state_access :
             "shadow TLB slot must fill at least an entire Merkle tree word");
     }
 
-    void do_reset_state() {
+    void do_reset_uarch() {
         //??D I'd like to add an static_assert or some other guard mechanism to
         // guarantee that uarch.ram and uarch.shadow are alone in the entire
         // span of their common Merkle tree parent node
diff --git a/src/uarch-replay-state-access.h b/src/uarch-replay-state-access.h
index 250e5180c..64a25bfd5 100644
--- a/src/uarch-replay-state-access.h
+++ b/src/uarch-replay-state-access.h
@@ -31,6 +31,7 @@
 #include "access-log.h"
 #include "i-accept-scoped-note.h"
 #include "i-hasher.h"
+#include "i-prefer-shadow-uarch-state.h"
 #include "i-uarch-state-access.h"
 #include "machine-merkle-tree.h"
 #include "meta.h"
@@ -43,7 +44,8 @@ namespace cartesi {
 
 class uarch_replay_state_access :
     public i_uarch_state_access<uarch_replay_state_access>,
-    public i_accept_scoped_note<uarch_replay_state_access> {
+    public i_accept_scoped_note<uarch_replay_state_access>,
+    public i_prefer_shadow_uarch_state<uarch_replay_state_access> {
     using tree_type = machine_merkle_tree;
     using hash_type = tree_type::hash_type;
     using hasher_type = tree_type::hasher_type;
@@ -266,6 +268,10 @@ class uarch_replay_state_access :
         m_next_access++;
     }
 
+    void check_write_reg_access(machine_reg reg, uint64_t val) {
+        check_write_word_access(machine_reg_address(reg), val, machine_reg_get_name(reg));
+    }
+
     uint64_t check_read_word_access(uint64_t paddr, const char *text) {
         const auto log2_size = log2_size_v<uint64_t>;
         const auto &a = check_access(text);
@@ -280,6 +286,10 @@ class uarch_replay_state_access :
         return val;
     }
 
+    uint64_t check_read_reg_access(machine_reg reg) {
+        return check_read_word_access(machine_reg_address(reg), machine_reg_get_name(reg));
+    }
+
     auto get_write_tlb_slot_hash(uint64_t vaddr_page, uint64_t vp_offset, uint64_t pma_index) {
         // Writes to TLB slots have to be atomic.
         // We can only do atomic writes of entire Merkle tree nodes.
@@ -299,53 +309,22 @@ class uarch_replay_state_access :
     }
 
     // -----
-    // i_uarch_state_access interface implementation
+    // i_prefer_shadow_uarch_state interface implementation
     // -----
-    friend i_uarch_state_access<uarch_replay_state_access>;
+    friend i_prefer_shadow_uarch_state<uarch_replay_state_access>;
 
-    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    void do_push_bracket(bracket_type /*type*/, const char * /*text*/) {}
-
-    uint64_t do_read_x(int i) {
-        const auto reg = machine_reg_enum(machine_reg::uarch_x0, i);
-        return check_read_word_access(machine_reg_address(reg), machine_reg_get_name(reg));
-    }
-
-    void do_write_x(int i, uint64_t val) {
-        assert(i != 0);
-        const auto reg = machine_reg_enum(machine_reg::uarch_x0, i);
-        check_write_word_access(machine_reg_address(reg), val, machine_reg_get_name(reg));
+    uint64_t do_read_shadow_uarch_state(shadow_uarch_state_what what) {
+        return check_read_reg_access(machine_reg_enum(what));
     }
 
-    uint64_t do_read_pc() {
-        const auto reg = machine_reg::uarch_pc;
-        return check_read_word_access(machine_reg_address(reg), machine_reg_get_name(reg));
+    void do_write_shadow_uarch_state(shadow_uarch_state_what what, uint64_t val) {
+        check_write_reg_access(machine_reg_enum(what), val);
     }
 
-    void do_write_pc(uint64_t val) {
-        const auto reg = machine_reg::uarch_pc;
-        check_write_word_access(machine_reg_address(reg), val, machine_reg_get_name(reg));
-    }
-
-    uint64_t do_read_cycle() {
-        const auto reg = machine_reg::uarch_cycle;
-        return check_read_word_access(machine_reg_address(reg), machine_reg_get_name(reg));
-    }
-
-    void do_write_cycle(uint64_t val) {
-        const auto reg = machine_reg::uarch_cycle;
-        check_write_word_access(machine_reg_address(reg), val, machine_reg_get_name(reg));
-    }
-
-    uint64_t do_read_halt_flag() {
-        const auto reg = machine_reg::uarch_halt_flag;
-        return check_read_word_access(machine_reg_address(reg), machine_reg_get_name(reg));
-    }
-
-    void do_write_halt_flag(uint64_t val) {
-        const auto reg = machine_reg::uarch_halt_flag;
-        check_write_word_access(machine_reg_address(reg), val, machine_reg_get_name(reg));
-    }
+    // -----
+    // i_uarch_state_access interface implementation
+    // -----
+    friend i_uarch_state_access<uarch_replay_state_access>;
 
     uint64_t do_read_word(uint64_t paddr) {
         return check_read_word_access(paddr, machine::get_what_name(paddr));
@@ -365,7 +344,7 @@ class uarch_replay_state_access :
         ; // do nothing
     }
 
-    void do_reset_state() {
+    void do_reset_uarch() {
         check_write_access(UARCH_STATE_START_ADDRESS, UARCH_STATE_LOG2_SIZE, uarch_pristine_state_hash, "uarch.state");
     }
 
diff --git a/src/uarch-solidity-compat.h b/src/uarch-solidity-compat.h
index 1be7df99c..6f66278d0 100644
--- a/src/uarch-solidity-compat.h
+++ b/src/uarch-solidity-compat.h
@@ -59,47 +59,47 @@ static inline void writeWord(UarchState &a, uint64 paddr, uint64 val) {
 
 template <typename UarchState>
 static inline uint64 readCycle(UarchState &a) {
-    return a.read_cycle();
+    return a.read_uarch_cycle();
 }
 
 template <typename UarchState>
 static inline void writeCycle(UarchState &a, uint64 val) {
-    a.write_cycle(val);
+    a.write_uarch_cycle(val);
 }
 
 template <typename UarchState>
 static inline uint64 readHaltFlag(UarchState &a) {
-    return a.read_halt_flag();
+    return a.read_uarch_halt_flag();
 }
 
 template <typename UarchState>
 static inline void writeHaltFlag(UarchState &a, uint64 val) {
-    a.write_halt_flag(val);
+    a.write_uarch_halt_flag(val);
 }
 
 template <typename UarchState>
 static inline uint64 readPc(UarchState &a) {
-    return a.read_pc();
+    return a.read_uarch_pc();
 }
 
 template <typename UarchState>
 static inline void writePc(UarchState &a, uint64 val) {
-    a.write_pc(val);
+    a.write_uarch_pc(val);
 }
 
 template <typename UarchState>
 static inline uint64 readX(UarchState &a, uint8 reg) {
-    return a.read_x(reg);
+    return a.read_uarch_x(reg);
 }
 
 template <typename UarchState>
 static inline void writeX(UarchState &a, uint8 reg, uint64 val) {
-    a.write_x(reg, val);
+    a.write_uarch_x(reg, val);
 }
 
 template <typename UarchState>
 static inline void resetState(UarchState &a) {
-    a.reset_state();
+    a.reset_uarch();
 }
 
 template <typename State>
diff --git a/src/uarch-state-access.h b/src/uarch-state-access.h
index 32782f5d6..8c1821951 100644
--- a/src/uarch-state-access.h
+++ b/src/uarch-state-access.h
@@ -69,36 +69,36 @@ class uarch_state_access :
     // -----
     friend i_uarch_state_access<uarch_state_access>;
 
-    uint64_t do_read_x(int i) const {
+    uint64_t do_read_uarch_x(int i) const {
         return m_m.get_uarch_state().x[i];
     }
 
-    void do_write_x(int i, uint64_t val) {
+    void do_write_uarch_x(int i, uint64_t val) {
         assert(i != 0);
         m_m.get_uarch_state().x[i] = val;
     }
 
-    uint64_t do_read_pc() const {
+    uint64_t do_read_uarch_pc() const {
         return m_m.get_uarch_state().pc;
     }
 
-    void do_write_pc(uint64_t val) {
+    void do_write_uarch_pc(uint64_t val) {
         m_m.get_uarch_state().pc = val;
     }
 
-    uint64_t do_read_cycle() const {
+    uint64_t do_read_uarch_cycle() const {
         return m_m.get_uarch_state().cycle;
     }
 
-    void do_write_cycle(uint64_t val) {
+    void do_write_uarch_cycle(uint64_t val) {
         m_m.get_uarch_state().cycle = val;
     }
 
-    uint64_t do_read_halt_flag() const {
+    uint64_t do_read_uarch_halt_flag() const {
         return m_m.get_uarch_state().halt_flag;
     }
 
-    void do_write_halt_flag(uint64_t v) {
+    void do_write_uarch_halt_flag(uint64_t v) {
         m_m.get_uarch_state().halt_flag = v;
     }
 
@@ -148,7 +148,7 @@ class uarch_state_access :
         m_m.write_shadow_tlb(set_index, slot_index, vaddr_page, vp_offset, pma_index);
     }
 
-    void do_reset_state() {
+    void do_reset_uarch() {
         // Forward to machine
         m_m.reset_uarch();
     }
diff --git a/uarch/machine-uarch-bridge-state-access.h b/uarch/machine-uarch-bridge-state-access.h
index c0af3bb25..f5dfc0b84 100644
--- a/uarch/machine-uarch-bridge-state-access.h
+++ b/uarch/machine-uarch-bridge-state-access.h
@@ -23,6 +23,7 @@
 
 #include "compiler-defines.h"
 #include "i-accept-scoped-note.h"
+#include "i-prefer-shadow-state.h"
 #include "i-state-access.h"
 #include "machine-reg.h"
 #include "mock-pma-entry.h"
@@ -52,7 +53,8 @@ struct i_state_access_fast_addr<machine_uarch_bridge_state_access> {
 // Provides access to the state of the big emulator from microcode
 class machine_uarch_bridge_state_access :
     public i_state_access<machine_uarch_bridge_state_access>,
-    public i_accept_scoped_note<machine_uarch_bridge_state_access> {
+    public i_accept_scoped_note<machine_uarch_bridge_state_access>,
+    public i_prefer_shadow_state<machine_uarch_bridge_state_access> {
 
     //NOLINTNEXTLINE(cppcoreguidelines-avoid-const-or-ref-data-members)
     std::array<std::optional<mock_pma_entry>, PMA_MAX> &m_pmas;
@@ -87,337 +89,22 @@ class machine_uarch_bridge_state_access :
     }
 
     // -----
-    // i_state_access interface implementation
+    // i_prefer_shadow_state interface implementation
     // -----
-    friend i_state_access<machine_uarch_bridge_state_access>;
-
-    uint64_t do_read_x(int i) {
-        return bridge_read_reg(machine_reg_enum(machine_reg::x0, i));
-    }
-
-    void do_write_x(int i, uint64_t val) {
-        bridge_write_reg(machine_reg_enum(machine_reg::x0, i), val);
-    }
-
-    uint64_t do_read_f(int i) {
-        return bridge_read_reg(machine_reg_enum(machine_reg::f0, i));
-    }
-
-    void do_write_f(int i, uint64_t val) {
-        bridge_write_reg(machine_reg_enum(machine_reg::f0, i), val);
-    }
-
-    uint64_t do_read_pc() {
-        return bridge_read_reg(machine_reg::pc);
-    }
-
-    void do_write_pc(uint64_t val) {
-        bridge_write_reg(machine_reg::pc, val);
-    }
-
-    uint64_t do_read_fcsr() {
-        return bridge_read_reg(machine_reg::fcsr);
-    }
-
-    void do_write_fcsr(uint64_t val) {
-        bridge_write_reg(machine_reg::fcsr, val);
-    }
-
-    uint64_t do_read_icycleinstret() {
-        return bridge_read_reg(machine_reg::icycleinstret);
-    }
-
-    void do_write_icycleinstret(uint64_t val) {
-        bridge_write_reg(machine_reg::icycleinstret, val);
-    }
-
-    uint64_t do_read_mvendorid() {
-        return bridge_read_reg(machine_reg::mvendorid);
-    }
-
-    uint64_t do_read_marchid() {
-        return bridge_read_reg(machine_reg::marchid);
-    }
-
-    uint64_t do_read_mimpid() {
-        return bridge_read_reg(machine_reg::mimpid);
-    }
-
-    uint64_t do_read_mcycle() {
-        return bridge_read_reg(machine_reg::mcycle);
-    }
-
-    void do_write_mcycle(uint64_t val) {
-        bridge_write_reg(machine_reg::mcycle, val);
-    }
-
-    uint64_t do_read_mstatus() {
-        return bridge_read_reg(machine_reg::mstatus);
-    }
-
-    void do_write_mstatus(uint64_t val) {
-        bridge_write_reg(machine_reg::mstatus, val);
-    }
-
-    uint64_t do_read_mtvec() {
-        return bridge_read_reg(machine_reg::mtvec);
-    }
-
-    void do_write_mtvec(uint64_t val) {
-        bridge_write_reg(machine_reg::mtvec, val);
-    }
-
-    uint64_t do_read_mscratch() {
-        return bridge_read_reg(machine_reg::mscratch);
-    }
+    friend i_prefer_shadow_state<machine_uarch_bridge_state_access>;
 
-    void do_write_mscratch(uint64_t val) {
-        bridge_write_reg(machine_reg::mscratch, val);
+    uint64_t do_read_shadow_state(shadow_state_what what) {
+        return bridge_read_reg(machine_reg_enum(what));
     }
 
-    uint64_t do_read_mepc() {
-        return bridge_read_reg(machine_reg::mepc);
+    void do_write_shadow_state(shadow_state_what what, uint64_t val) {
+        bridge_write_reg(machine_reg_enum(what), val);
     }
 
-    void do_write_mepc(uint64_t val) {
-        bridge_write_reg(machine_reg::mepc, val);
-    }
-
-    uint64_t do_read_mcause() {
-        return bridge_read_reg(machine_reg::mcause);
-    }
-
-    void do_write_mcause(uint64_t val) {
-        bridge_write_reg(machine_reg::mcause, val);
-    }
-
-    uint64_t do_read_mtval() {
-        return bridge_read_reg(machine_reg::mtval);
-    }
-
-    void do_write_mtval(uint64_t val) {
-        bridge_write_reg(machine_reg::mtval, val);
-    }
-
-    uint64_t do_read_misa() {
-        return bridge_read_reg(machine_reg::misa);
-    }
-
-    void do_write_misa(uint64_t val) {
-        bridge_write_reg(machine_reg::misa, val);
-    }
-
-    uint64_t do_read_mie() {
-        return bridge_read_reg(machine_reg::mie);
-    }
-
-    void do_write_mie(uint64_t val) {
-        bridge_write_reg(machine_reg::mie, val);
-    }
-
-    uint64_t do_read_mip() {
-        return bridge_read_reg(machine_reg::mip);
-    }
-
-    void do_write_mip(uint64_t val) {
-        bridge_write_reg(machine_reg::mip, val);
-    }
-
-    uint64_t do_read_medeleg() {
-        return bridge_read_reg(machine_reg::medeleg);
-    }
-
-    void do_write_medeleg(uint64_t val) {
-        bridge_write_reg(machine_reg::medeleg, val);
-    }
-
-    uint64_t do_read_mideleg() {
-        return bridge_read_reg(machine_reg::mideleg);
-    }
-
-    void do_write_mideleg(uint64_t val) {
-        bridge_write_reg(machine_reg::mideleg, val);
-    }
-
-    uint64_t do_read_mcounteren() {
-        return bridge_read_reg(machine_reg::mcounteren);
-    }
-
-    void do_write_mcounteren(uint64_t val) {
-        bridge_write_reg(machine_reg::mcounteren, val);
-    }
-
-    uint64_t do_read_senvcfg() {
-        return bridge_read_reg(machine_reg::senvcfg);
-    }
-
-    void do_write_senvcfg(uint64_t val) {
-        bridge_write_reg(machine_reg::senvcfg, val);
-    }
-
-    uint64_t do_read_menvcfg() {
-        return bridge_read_reg(machine_reg::menvcfg);
-    }
-
-    void do_write_menvcfg(uint64_t val) {
-        bridge_write_reg(machine_reg::menvcfg, val);
-    }
-
-    uint64_t do_read_stvec() {
-        return bridge_read_reg(machine_reg::stvec);
-    }
-
-    void do_write_stvec(uint64_t val) {
-        bridge_write_reg(machine_reg::stvec, val);
-    }
-
-    uint64_t do_read_sscratch() {
-        return bridge_read_reg(machine_reg::sscratch);
-    }
-
-    void do_write_sscratch(uint64_t val) {
-        bridge_write_reg(machine_reg::sscratch, val);
-    }
-
-    uint64_t do_read_sepc() {
-        return bridge_read_reg(machine_reg::sepc);
-    }
-
-    void do_write_sepc(uint64_t val) {
-        bridge_write_reg(machine_reg::sepc, val);
-    }
-
-    uint64_t do_read_scause() {
-        return bridge_read_reg(machine_reg::scause);
-    }
-
-    void do_write_scause(uint64_t val) {
-        bridge_write_reg(machine_reg::scause, val);
-    }
-
-    uint64_t do_read_stval() {
-        return bridge_read_reg(machine_reg::stval);
-    }
-
-    void do_write_stval(uint64_t val) {
-        bridge_write_reg(machine_reg::stval, val);
-    }
-
-    uint64_t do_read_satp() {
-        return bridge_read_reg(machine_reg::satp);
-    }
-
-    void do_write_satp(uint64_t val) {
-        bridge_write_reg(machine_reg::satp, val);
-    }
-
-    uint64_t do_read_scounteren() {
-        return bridge_read_reg(machine_reg::scounteren);
-    }
-
-    void do_write_scounteren(uint64_t val) {
-        bridge_write_reg(machine_reg::scounteren, val);
-    }
-
-    uint64_t do_read_ilrsc() {
-        return bridge_read_reg(machine_reg::ilrsc);
-    }
-
-    void do_write_ilrsc(uint64_t val) {
-        bridge_write_reg(machine_reg::ilrsc, val);
-    }
-
-    uint64_t do_read_iprv() {
-        return bridge_read_reg(machine_reg::iprv);
-    }
-
-    void do_write_iprv(uint64_t val) {
-        bridge_write_reg(machine_reg::iprv, val);
-    }
-
-    uint64_t do_read_iflags_X() {
-        return bridge_read_reg(machine_reg::iflags_X);
-    }
-
-    void do_write_iflags_X(uint64_t val) {
-        bridge_write_reg(machine_reg::iflags_X, val);
-    }
-
-    uint64_t do_read_iflags_Y() {
-        return bridge_read_reg(machine_reg::iflags_Y);
-    }
-
-    void do_write_iflags_Y(uint64_t val) {
-        bridge_write_reg(machine_reg::iflags_Y, val);
-    }
-
-    uint64_t do_read_iflags_H() {
-        return bridge_read_reg(machine_reg::iflags_H);
-    }
-
-    void do_write_iflags_H(uint64_t val) {
-        bridge_write_reg(machine_reg::iflags_H, val);
-    }
-
-    uint64_t do_read_iunrep() {
-        return bridge_read_reg(machine_reg::iunrep);
-    }
-
-    void do_write_iunrep(uint64_t val) {
-        bridge_write_reg(machine_reg::iunrep, val);
-    }
-
-    uint64_t do_read_clint_mtimecmp() {
-        return bridge_read_reg(machine_reg::clint_mtimecmp);
-    }
-
-    void do_write_clint_mtimecmp(uint64_t val) {
-        bridge_write_reg(machine_reg::clint_mtimecmp, val);
-    }
-
-    uint64_t do_read_plic_girqpend() {
-        return bridge_read_reg(machine_reg::plic_girqpend);
-    }
-
-    void do_write_plic_girqpend(uint64_t val) {
-        bridge_write_reg(machine_reg::plic_girqpend, val);
-    }
-
-    uint64_t do_read_plic_girqsrvd() {
-        return bridge_read_reg(machine_reg::plic_girqsrvd);
-    }
-
-    void do_write_plic_girqsrvd(uint64_t val) {
-        bridge_write_reg(machine_reg::plic_girqsrvd, val);
-    }
-
-    uint64_t do_read_htif_fromhost() {
-        return bridge_read_reg(machine_reg::htif_fromhost);
-    }
-
-    void do_write_htif_fromhost(uint64_t val) {
-        bridge_write_reg(machine_reg::htif_fromhost, val);
-    }
-
-    uint64_t do_read_htif_tohost() {
-        return bridge_read_reg(machine_reg::htif_tohost);
-    }
-
-    void do_write_htif_tohost(uint64_t val) {
-        bridge_write_reg(machine_reg::htif_tohost, val);
-    }
-
-    uint64_t do_read_htif_ihalt() {
-        return bridge_read_reg(machine_reg::htif_ihalt);
-    }
-
-    uint64_t do_read_htif_iconsole() {
-        return bridge_read_reg(machine_reg::htif_iconsole);
-    }
-
-    uint64_t do_read_htif_iyield() {
-        return bridge_read_reg(machine_reg::htif_iyield);
-    }
+    // -----
+    // i_state_access interface implementation
+    // -----
+    friend i_state_access<machine_uarch_bridge_state_access>;
 
     template <typename T, typename A>
     void do_read_memory_word(uint64_t paddr, uint64_t /* pma_index */, T *pval) {

From 70876010aa667f39875365abb6507a31ea97ea39 Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Thu, 6 Feb 2025 10:13:52 +0000
Subject: [PATCH 10/82] fix: format, typos, warnings, and cinttypes macros

---
 src/dump-state-access.h           |  4 ++-
 src/dump-uarch-state-access.h     |  4 ++-
 src/dump.h                        | 33 +++++++++++++++++++++++
 src/i-accept-scoped-note.h        | 28 +++++++++++++------
 src/i-prefer-shadow-state.h       |  7 +++--
 src/i-prefer-shadow-uarch-state.h |  7 +++--
 src/i-state-access.h              | 45 ++++++++++++++++---------------
 src/i-uarch-state-access.h        | 15 ++++++-----
 src/interpret.cpp                 |  2 +-
 src/jsonrpc-remote-machine.cpp    |  1 +
 src/jsonrpc-virtual-machine.cpp   |  1 +
 src/machine-reg.h                 |  2 +-
 src/machine.h                     |  2 +-
 src/pm-type-name.h                |  2 +-
 src/pma-constants.h               |  2 +-
 src/replay-step-state-access.h    |  2 +-
 src/shadow-pmas.h                 | 24 ++++++++---------
 src/shadow-state.h                |  7 +++--
 src/shadow-tlb.h                  |  5 ++--
 src/shadow-uarch-state.h          |  3 ++-
 src/uarch-replay-state-access.h   |  1 +
 21 files changed, 131 insertions(+), 66 deletions(-)
 create mode 100644 src/dump.h

diff --git a/src/dump-state-access.h b/src/dump-state-access.h
index 4d90c7239..c359de1fa 100644
--- a/src/dump-state-access.h
+++ b/src/dump-state-access.h
@@ -17,10 +17,12 @@
 #ifndef DUMP_STATE_ACCESS_H
 #define DUMP_STATE_ACCESS_H
 
+#include "dump.h"
+
 #ifdef DUMP_STATE_ACCESS
 template <typename... ARGS>
 static inline auto DSA_PRINTF(ARGS... args) {
-    return fprintf(stderr, args...);
+    return D_PRINTF(args...);
 }
 #else
 template <typename... ARGS>
diff --git a/src/dump-uarch-state-access.h b/src/dump-uarch-state-access.h
index 7d6b14ec4..6389574dc 100644
--- a/src/dump-uarch-state-access.h
+++ b/src/dump-uarch-state-access.h
@@ -17,10 +17,12 @@
 #ifndef DUMP_UARCH_STATE_ACCESS_H
 #define DUMP_UARCH_STATE_ACCESS_H
 
+#include "dump.h"
+
 #ifdef DUMP_UARCH_STATE_ACCESS
 template <typename... ARGS>
 static inline auto DUSA_PRINTF(ARGS... args) {
-    return printf(args...);
+    return D_PRINTF(args...);
 }
 #else
 template <typename... ARGS>
diff --git a/src/dump.h b/src/dump.h
new file mode 100644
index 000000000..5281519f4
--- /dev/null
+++ b/src/dump.h
@@ -0,0 +1,33 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef DUMP__H
+#define DUMP__H
+
+#ifdef MICROARCHITECTURE
+template <typename... ARGS>
+static inline auto D_PRINTF(ARGS... args) {
+    return printf(args...);
+}
+#else
+#include <cstdio>
+template <typename... ARGS>
+static inline auto D_PRINTF(ARGS... args) {
+    return fprintf(stderr, args...);
+}
+#endif
+
+#endif
diff --git a/src/i-accept-scoped-note.h b/src/i-accept-scoped-note.h
index a812a3a4d..6c9dd3ad7 100644
--- a/src/i-accept-scoped-note.h
+++ b/src/i-accept-scoped-note.h
@@ -23,11 +23,27 @@
 #include <cstdint>
 #include <type_traits>
 
+#ifdef DUMP_SCOPED_NOTE
+#include "dump.h"
+#endif
+
 #include "meta.h"
 #include "scoped-note.h"
 
 namespace cartesi {
 
+#ifdef DUMP_SCOPED_NOTE
+template <typename... ARGS>
+static inline auto DSN_PRINTF(ARGS... args) {
+    return D_PRINTF(args...);
+}
+#else
+template <typename... ARGS>
+static inline auto DSN_PRINTF(ARGS... /*args*/) {
+    return 0;
+}
+#endif
+
 /// \class i_accept_scoped_note
 /// \brief Interface that lets a state access accept scoped notes.
 /// \tparam DERIVED Derived class implementing the interface. (An example of CRTP.)
@@ -48,19 +64,15 @@ class i_accept_scoped_note { // CRTP
     /// \brief Adds a begin bracket annotation to the log
     /// \param text String with the text for the annotation
     void push_begin_bracket(const char *text) {
-#ifdef DUMP_SCOPED_NOTE
-        fprintf(stderr, "----> begin %s (%s)\n", text, derived().get_name());
-#endif
-        return derived().do_push_begin_bracket(text);
+        derived().do_push_begin_bracket(text);
+        DSN_PRINTF("----> begin %s (%s)\n", text, derived().get_name());
     }
 
     /// \brief Adds an end bracket annotation to the log
     /// \param text String with the text for the annotation
     void push_end_bracket(const char *text) {
-#ifdef DUMP_SCOPED_NOTE
-        fprintf(stderr, "<---- end %s (%s)\n", text, derived().get_name());
-#endif
-        return derived().do_push_end_bracket(text);
+        derived().do_push_end_bracket(text);
+        DSN_PRINTF("<---- end %s (%s)\n", text, derived().get_name());
     }
 
     /// \brief Adds annotations to the state, bracketing a scope
diff --git a/src/i-prefer-shadow-state.h b/src/i-prefer-shadow-state.h
index 38990ccb9..4ae0fe637 100644
--- a/src/i-prefer-shadow-state.h
+++ b/src/i-prefer-shadow-state.h
@@ -21,6 +21,7 @@
 /// \file
 /// \brief Interface for state access that prefers to go through shadow state
 
+#include <cinttypes>
 #include <cstdint>
 #include <type_traits>
 
@@ -52,14 +53,16 @@ class i_prefer_shadow_state { // CRTP
     uint64_t read_shadow_state(shadow_state_what what) {
         const auto val = derived().do_read_shadow_state(what);
         [[maybe_unused]] const auto *const what_name = shadow_state_get_what_name(what);
-        DSA_PRINTF("%s::read_shadow_state(%s) = %llu(0x%llx)\n", derived().get_name(), what_name, val, val);
+        DSA_PRINTF("%s::read_shadow_state(%s) = %" PRIu64 "(0x%" PRIx64 ")\n", derived().get_name(), what_name, val,
+            val);
         return val;
     }
 
     void write_shadow_state(shadow_state_what what, uint64_t val) {
         derived().do_write_shadow_state(what, val);
         [[maybe_unused]] const auto *const what_name = shadow_state_get_what_name(what);
-        DSA_PRINTF("%s::write_shadow_state(%s, %llu(0x%llx))\n", derived().get_name(), what_name, val, val);
+        DSA_PRINTF("%s::write_shadow_state(%s, %" PRIu64 "(0x%" PRIx64 "))\n", derived().get_name(), what_name, val,
+            val);
     }
 };
 
diff --git a/src/i-prefer-shadow-uarch-state.h b/src/i-prefer-shadow-uarch-state.h
index b4492a59f..53f95dda9 100644
--- a/src/i-prefer-shadow-uarch-state.h
+++ b/src/i-prefer-shadow-uarch-state.h
@@ -21,6 +21,7 @@
 /// \file
 /// \brief Interface for state access that prefers to go through shadow uarch state
 
+#include <cinttypes>
 #include <cstdint>
 #include <type_traits>
 
@@ -52,14 +53,16 @@ class i_prefer_shadow_uarch_state { // CRTP
     uint64_t read_shadow_uarch_state(shadow_uarch_state_what what) {
         const auto val = derived().do_read_shadow_uarch_state(what);
         [[maybe_unused]] const auto *const what_name = shadow_uarch_state_get_what_name(what);
-        DUSA_PRINTF("%s::read_shadow_uarch_state(%s) = %llu(0x%llx)\n", derived().get_name(), what_name, val, val);
+        DUSA_PRINTF("%s::read_shadow_uarch_state(%s) = %" PRIu64 "(0x%" PRIx64 ")\n", derived().get_name(), what_name,
+            val, val);
         return val;
     }
 
     void write_shadow_uarch_state(shadow_uarch_state_what what, uint64_t val) {
         derived().do_write_shadow_uarch_state(what, val);
         [[maybe_unused]] const auto *const what_name = shadow_uarch_state_get_what_name(what);
-        DUSA_PRINTF("%s::write_shadow_uarch_state(%s, %llu(0x%llx))\n", derived().get_name(), what_name, val, val);
+        DUSA_PRINTF("%s::write_shadow_uarch_state(%s, %" PRIu64 "(0x%" PRIx64 "))\n", derived().get_name(), what_name,
+            val, val);
     }
 };
 
diff --git a/src/i-state-access.h b/src/i-state-access.h
index 30243dcb4..d8eafe2bd 100644
--- a/src/i-state-access.h
+++ b/src/i-state-access.h
@@ -20,6 +20,7 @@
 /// \file
 /// \brief State access interface
 
+#include <cinttypes>
 #include <cstdint>
 #include <type_traits>
 #include <utility>
@@ -52,7 +53,7 @@ using i_state_access_fast_addr_t = typename i_state_access_fast_addr<STATE_ACCES
     uint64_t read_##REG() {                                                                                            \
         if constexpr (!is_an_i_prefer_shadow_state_v<DERIVED>) {                                                       \
             const auto val = derived().do_read_##REG();                                                                \
-            DSA_PRINTF("%s::read_" #REG "() = %llu(0x%llx)\n", get_name(), val, val);                                  \
+            DSA_PRINTF("%s::read_" #REG "() = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), val, val);                    \
             return val;                                                                                                \
         } else {                                                                                                       \
             return derived().read_shadow_state(shadow_state_what::REG);                                                \
@@ -63,7 +64,7 @@ using i_state_access_fast_addr_t = typename i_state_access_fast_addr<STATE_ACCES
     void write_##REG(uint64_t val) {                                                                                   \
         if constexpr (!is_an_i_prefer_shadow_state_v<DERIVED>) {                                                       \
             derived().do_write_##REG(val);                                                                             \
-            DSA_PRINTF("%s::write_" #REG "(%llu(0x%llx))\n", get_name(), val, val);                                    \
+            DSA_PRINTF("%s::write_" #REG "(%" PRIu64 "(0x%" PRIx64 "))\n", get_name(), val, val);                      \
         } else {                                                                                                       \
             derived().write_shadow_state(shadow_state_what::REG, val);                                                 \
         }                                                                                                              \
@@ -122,7 +123,7 @@ class i_state_access { // CRTP
     uint64_t read_x(int i) {
         if constexpr (!is_an_i_prefer_shadow_state_v<DERIVED>) {
             const auto val = derived().do_read_x(i);
-            DSA_PRINTF("%s::read_x(%d) = %llu(0x%llx)\n", get_name(), i, val, val);
+            DSA_PRINTF("%s::read_x(%d) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), i, val, val);
             return val;
         } else {
             return derived().read_shadow_state(shadow_state_get_what(shadow_state_what::x0, i));
@@ -137,7 +138,7 @@ class i_state_access { // CRTP
     void write_x(int i, uint64_t val) {
         if constexpr (!is_an_i_prefer_shadow_state_v<DERIVED>) {
             derived().do_write_x(i, val);
-            DSA_PRINTF("%s::write_x(%d, %llu(0x%llx))\n", get_name(), i, val, val);
+            DSA_PRINTF("%s::write_x(%d, %" PRIu64 "(0x%" PRIx64 "))\n", get_name(), i, val, val);
         } else {
             derived().write_shadow_state(shadow_state_get_what(shadow_state_what::x0, i), val);
         }
@@ -149,7 +150,7 @@ class i_state_access { // CRTP
     uint64_t read_f(int i) {
         if constexpr (!is_an_i_prefer_shadow_state_v<DERIVED>) {
             const auto val = derived().do_read_f(i);
-            DSA_PRINTF("%s::read_f(%d) = %llu(0x%llx)\n", get_name(), i, val, val);
+            DSA_PRINTF("%s::read_f(%d) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), i, val, val);
             return val;
         } else {
             return derived().read_shadow_state(shadow_state_get_what(shadow_state_what::f0, i));
@@ -162,7 +163,7 @@ class i_state_access { // CRTP
     void write_f(int i, uint64_t val) {
         if constexpr (!is_an_i_prefer_shadow_state_v<DERIVED>) {
             derived().do_write_f(i, val);
-            DSA_PRINTF("%s::write_f(%d, %llu(%llx))\n", get_name(), i, val, val);
+            DSA_PRINTF("%s::write_f(%d, %" PRIu64 "(%" PRIx64 "))\n", get_name(), i, val, val);
         } else {
             derived().write_shadow_state(shadow_state_get_what(shadow_state_what::f0, i), val);
         }
@@ -260,7 +261,7 @@ class i_state_access { // CRTP
     /// \param index Index of PMA
     pma_entry &read_pma_entry(uint64_t index) {
         auto &pma = derived().do_read_pma_entry(index);
-        DSA_PRINTF("%s::read_pma_entry(%llu) = {%s, 0x%llx, 0x%llx}\n", get_name(), index,
+        DSA_PRINTF("%s::read_pma_entry(%" PRIu64 ") = {%s, 0x%" PRIx64 ", 0x%" PRIx64 "}\n", get_name(), index,
             pma_get_DID_name(pma.get_istart_DID()), pma.get_start(), pma.get_length());
         return pma;
     }
@@ -272,8 +273,8 @@ class i_state_access { // CRTP
     fast_addr get_faddr(uint64_t paddr, uint64_t pma_index) const {
         const auto val = derived().do_get_faddr(paddr, pma_index);
         [[maybe_unused]] const auto fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
-        DSA_PRINTF("%s::get_faddr(%llu(0x%llx)) = %s{%llu(0x%llx)}\n", get_name(), paddr, paddr, fast_addr_name, val,
-            val);
+        DSA_PRINTF("%s::get_faddr(%" PRIu64 "(0x%" PRIx64 ")) = %s{%" PRIu64 "(0x%" PRIx64 ")}\n", get_name(), paddr,
+            paddr, fast_addr_name, val, val);
         return val;
     }
 
@@ -321,9 +322,9 @@ class i_state_access { // CRTP
         static_assert(std::is_integral_v<T> && sizeof(T) <= sizeof(uint64_t), "unsupported type");
         derived().template do_read_memory_word<T, A>(faddr, pma_index, pval);
         [[maybe_unused]] const auto fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
-        DSA_PRINTF("%s::read_memory_word<%s,%s>(%s{0x%llx}, %llu) = %llu(0x%llx)\n", get_name(), pm_type_name_v<T>,
-            pm_type_name_v<A>, fast_addr_name, faddr, pma_index, static_cast<uint64_t>(*pval),
-            static_cast<uint64_t>(*pval));
+        DSA_PRINTF("%s::read_memory_word<%s,%s>(%s{0x%" PRIx64 "}, %" PRIu64 ") = %" PRIu64 "(0x%" PRIx64 ")\n",
+            get_name(), pm_type_name_v<T>, pm_type_name_v<A>, fast_addr_name, faddr, pma_index,
+            static_cast<uint64_t>(*pval), static_cast<uint64_t>(*pval));
     }
 
     /// \brief Writes a word to memory.
@@ -340,9 +341,9 @@ class i_state_access { // CRTP
         static_assert(std::is_integral_v<T> && sizeof(T) <= sizeof(uint64_t), "unsupported type");
         derived().template do_write_memory_word<T, A>(faddr, pma_index, val);
         [[maybe_unused]] const auto fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
-        DSA_PRINTF("%s::write_memory_word<%s,%s>(%s{0x%llx}, %llu, %llu(0x%llx))\n", get_name(), pm_type_name_v<T>,
-            pm_type_name_v<A>, fast_addr_name, faddr, pma_index, static_cast<uint64_t>(val),
-            static_cast<uint64_t>(val));
+        DSA_PRINTF("%s::write_memory_word<%s,%s>(%s{0x%" PRIx64 "}, %" PRIu64 ", %" PRIu64 "(0x%" PRIx64 "))\n",
+            get_name(), pm_type_name_v<T>, pm_type_name_v<A>, fast_addr_name, faddr, pma_index,
+            static_cast<uint64_t>(val), static_cast<uint64_t>(val));
     }
 
     /// \brief Reads TLB's vaddr_page
@@ -352,7 +353,8 @@ class i_state_access { // CRTP
     template <TLB_set_index SET>
     uint64_t read_tlb_vaddr_page(uint64_t slot_index) {
         const auto val = derived().template do_read_tlb_vaddr_page<SET>(slot_index);
-        DSA_PRINTF("%s::read_tlb_vaddr_page<%llu>(%llu) = 0x%llx\n", get_name(), SET, slot_index, val);
+        DSA_PRINTF("%s::read_tlb_vaddr_page<%" PRIu64 ">(%" PRIu64 ") = 0x%" PRIx64 "\n", get_name(), SET, slot_index,
+            val);
         return val;
     }
 
@@ -364,8 +366,8 @@ class i_state_access { // CRTP
     fast_addr read_tlb_vp_offset(uint64_t slot_index) {
         [[maybe_unused]] const auto fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
         const auto val = derived().template do_read_tlb_vp_offset<SET>(slot_index);
-        DSA_PRINTF("%s::read_tlb_vp_offset<%llu>(%llu) = %s{0x%llx}\n", get_name(), SET, slot_index, fast_addr_name,
-            val);
+        DSA_PRINTF("%s::read_tlb_vp_offset<%" PRIu64 ">(%" PRIu64 ") = %s{0x%" PRIx64 "}\n", get_name(), SET,
+            slot_index, fast_addr_name, val);
         return val;
     }
 
@@ -376,7 +378,8 @@ class i_state_access { // CRTP
     template <TLB_set_index SET>
     uint64_t read_tlb_pma_index(uint64_t slot_index) {
         const auto val = derived().template do_read_tlb_pma_index<SET>(slot_index);
-        DSA_PRINTF("%s::read_tlb_pma_index<%llu>(%llu) = %llu(0x%llx)\n", get_name(), SET, slot_index, val, val);
+        DSA_PRINTF("%s::read_tlb_pma_index<%" PRIu64 ">(%" PRIu64 ") = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), SET,
+            slot_index, val, val);
         return val;
     }
 
@@ -392,8 +395,8 @@ class i_state_access { // CRTP
     void write_tlb(uint64_t slot_index, uint64_t vaddr_page, fast_addr vp_offset, uint64_t pma_index) {
         derived().template do_write_tlb<SET>(slot_index, vaddr_page, vp_offset, pma_index);
         [[maybe_unused]] const auto fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
-        DSA_PRINTF("%s::write_tlb<%llu>(%llu, 0x%llx, %s{0x%llx}, %llu)\n", get_name(), SET, slot_index, vaddr_page,
-            fast_addr_name, vp_offset, pma_index);
+        DSA_PRINTF("%s::write_tlb<%" PRIu64 ">(%" PRIu64 ", 0x%" PRIx64 ", %s{0x%" PRIx64 "}, %" PRIu64 ")\n",
+            get_name(), SET, slot_index, vaddr_page, fast_addr_name, vp_offset, pma_index);
     }
 
     /// \brief Marks a page as dirty
diff --git a/src/i-uarch-state-access.h b/src/i-uarch-state-access.h
index d9a3d593a..be9dfd175 100644
--- a/src/i-uarch-state-access.h
+++ b/src/i-uarch-state-access.h
@@ -17,6 +17,7 @@
 #ifndef I_UARCH_STATE_ACCESS_H
 #define I_UARCH_STATE_ACCESS_H
 
+#include <cinttypes>
 #include <cstdint>
 
 #include "dump-uarch-state-access.h"
@@ -29,7 +30,7 @@
     uint64_t read_##REG() {                                                                                            \
         if constexpr (!is_an_i_prefer_shadow_uarch_state_v<DERIVED>) {                                                 \
             const auto val = derived().do_read_##REG();                                                                \
-            DUSA_PRINTF("%s::read_" #REG "() = %llu(0x%llx)\n", get_name(), val, val);                                 \
+            DUSA_PRINTF("%s::read_" #REG "() = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), val, val);                   \
             return val;                                                                                                \
         } else {                                                                                                       \
             return derived().read_shadow_uarch_state(shadow_uarch_state_what::REG);                                    \
@@ -40,7 +41,7 @@
     void write_##REG(uint64_t val) {                                                                                   \
         if constexpr (!is_an_i_prefer_shadow_uarch_state_v<DERIVED>) {                                                 \
             derived().do_write_##REG(val);                                                                             \
-            DUSA_PRINTF("%s::write_" #REG "(%llu(0x%llx))\n", get_name(), val, val);                                   \
+            DUSA_PRINTF("%s::write_" #REG "(%" PRIu64 "(0x%" PRIx64 "))\n", get_name(), val, val);                     \
         } else {                                                                                                       \
             derived().write_shadow_uarch_state(shadow_uarch_state_what::REG, val);                                     \
         }                                                                                                              \
@@ -67,7 +68,7 @@ class i_uarch_state_access { // CRTP
     uint64_t read_uarch_x(int i) {
         if constexpr (!is_an_i_prefer_shadow_uarch_state_v<DERIVED>) {
             const auto val = derived().do_read_uarch_x(i);
-            DUSA_PRINTF("%s::read_uarch_x(%d) = %llu(0x%llx)\n", get_name(), i, val, val);
+            DUSA_PRINTF("%s::read_uarch_x(%d) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), i, val, val);
             return val;
         } else {
             return derived().read_shadow_uarch_state(shadow_uarch_state_get_what(shadow_uarch_state_what::uarch_x0, i));
@@ -77,7 +78,7 @@ class i_uarch_state_access { // CRTP
     void write_uarch_x(int i, uint64_t val) {
         if constexpr (!is_an_i_prefer_shadow_uarch_state_v<DERIVED>) {
             derived().do_write_uarch_x(i, val);
-            DUSA_PRINTF("%s::write_uarch_x(%d, %llu)\n", get_name(), i, val);
+            DUSA_PRINTF("%s::write_uarch_x(%d, %" PRIu64 ")\n", get_name(), i, val);
         } else {
             derived().write_shadow_uarch_state(shadow_uarch_state_get_what(shadow_uarch_state_what::uarch_x0, i), val);
         }
@@ -95,13 +96,15 @@ class i_uarch_state_access { // CRTP
 
     uint64_t read_word(uint64_t paddr) {
         const auto val = derived().do_read_word(paddr);
-        DUSA_PRINTF("%s::read_word(phys_addr{0x%llx}) = %llu(0x%llx)\n", get_name(), paddr, val, val);
+        DUSA_PRINTF("%s::read_word(phys_addr{0x%" PRIx64 "}) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), paddr, val,
+            val);
         return val;
     }
 
     void write_word(uint64_t paddr, uint64_t val) {
         derived().do_write_word(paddr, val);
-        DUSA_PRINTF("%s::write_word(phys_addr{0x%llx}, %llu(0x%llx))\n", get_name(), paddr, val, val);
+        DUSA_PRINTF("%s::write_word(phys_addr{0x%" PRIx64 "}, %" PRIu64 "(0x%" PRIx64 "))\n", get_name(), paddr, val,
+            val);
     }
 
     /// \brief Resets uarch to pristine state
diff --git a/src/interpret.cpp b/src/interpret.cpp
index 26923c98f..bd8f418de 100644
--- a/src/interpret.cpp
+++ b/src/interpret.cpp
@@ -6056,7 +6056,7 @@ interpreter_break_reason interpret(STATE_ACCESS a, uint64_t mcycle_end) {
     }
     if (status == execute_status::success_and_yield) {
         return interpreter_break_reason::yielded_softly;
-    } // Reached mcycle_end
+    }                                      // Reached mcycle_end
     assert(a.read_mcycle() == mcycle_end); // LCOV_EXCL_LINE
     return interpreter_break_reason::reached_target_mcycle;
 }
diff --git a/src/jsonrpc-remote-machine.cpp b/src/jsonrpc-remote-machine.cpp
index 99473ff60..b1d7c30ec 100644
--- a/src/jsonrpc-remote-machine.cpp
+++ b/src/jsonrpc-remote-machine.cpp
@@ -54,6 +54,7 @@
 
 #pragma GCC diagnostic push
 #pragma GCC diagnostic ignored "-Wdeprecated-declarations"
+#pragma GCC diagnostic ignored "-Wunused-but-set-variable"
 #include <boost/asio/signal_set.hpp>
 #include <boost/beast/core.hpp>
 #include <boost/beast/http.hpp>
diff --git a/src/jsonrpc-virtual-machine.cpp b/src/jsonrpc-virtual-machine.cpp
index 1ba209e08..dbb253e65 100644
--- a/src/jsonrpc-virtual-machine.cpp
+++ b/src/jsonrpc-virtual-machine.cpp
@@ -48,6 +48,7 @@
 
 #pragma GCC diagnostic push
 #pragma GCC diagnostic ignored "-Wdeprecated-declarations"
+#pragma GCC diagnostic ignored "-Wunused-but-set-variable"
 #include <boost/asio/connect.hpp>
 #include <boost/asio/ip/address.hpp>
 #include <boost/asio/ip/tcp.hpp>
diff --git a/src/machine-reg.h b/src/machine-reg.h
index be84ae758..57765353e 100644
--- a/src/machine-reg.h
+++ b/src/machine-reg.h
@@ -175,7 +175,7 @@ enum class machine_reg : uint64_t {
     uarch_first_ = uarch_halt_flag,
     uarch_last_ = uarch_x31,
 
-    // Something unkonwn
+    // Something unknown
     unknown_ = UINT64_C(1) << 63, // Outside of RISC-V address space
 
     // Views of registers
diff --git a/src/machine.h b/src/machine.h
index 26eca98aa..8bc7e98cc 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -253,7 +253,7 @@ class machine final {
     /// \param mcycle_max Maximum mcycle after wait.
     /// \returns A pair {new_mcycle, status}, where new_mcycle gives new value for mcycle after wait,
     /// and status will be execute_status::success_and_serve_interrupts if wait was stopped by an
-    /// external interrupt resquest.
+    /// external interrupt request.
     /// \details When mcycle_max is greater than mcycle, this function will sleep until an external interrupt
     /// is triggered or until the amount of time estimated for mcycle to reach mcycle_max has elapsed.
     std::pair<uint64_t, execute_status> poll_external_interrupts(uint64_t mcycle, uint64_t mcycle_max);
diff --git a/src/pm-type-name.h b/src/pm-type-name.h
index d93024277..9ecb4241c 100644
--- a/src/pm-type-name.h
+++ b/src/pm-type-name.h
@@ -22,7 +22,7 @@ namespace cartesi {
 //?DD Poor man's rtti that works in microarchitecture
 template <typename T>
 struct pm_type_name {
-    static constexpr const char *value = "unknown type";
+    static constexpr const char *value = "unknown";
 };
 
 template <typename T>
diff --git a/src/pma-constants.h b/src/pma-constants.h
index 8be8edd4a..6e105ccdd 100644
--- a/src/pma-constants.h
+++ b/src/pma-constants.h
@@ -159,7 +159,7 @@ static constexpr const char *pma_get_DID_name(PMA_ISTART_DID did) {
         case PMA_ISTART_DID::shadow_uarch:
             return "DID.shadow_uarch";
         default:
-            return "DID.unkown";
+            return "DID.unknown";
     }
 }
 
diff --git a/src/replay-step-state-access.h b/src/replay-step-state-access.h
index 622335cbd..d86714766 100644
--- a/src/replay-step-state-access.h
+++ b/src/replay-step-state-access.h
@@ -162,7 +162,7 @@ class replay_step_state_access :
             if (i > 0 && m_context.pages[i - 1].index >= m_context.pages[i].index) {
                 interop_throw_runtime_error("invalid log format: page index is not in increasing order");
             }
-            // In the current implementaiton, this check is unecessary
+            // In the current implementation, this check is unnecessary
             // But we may in the future change the data field to point to independently allocated pages
             // This would break the code that uses binary search to find the page based on the address of its data
             if (i > 0 && +m_context.pages[i - 1].data >= +m_context.pages[i].data) {
diff --git a/src/shadow-pmas.h b/src/shadow-pmas.h
index 662d0fcd5..523db548e 100644
--- a/src/shadow-pmas.h
+++ b/src/shadow-pmas.h
@@ -32,17 +32,17 @@ namespace cartesi {
 
 /// \brief Shadow memory layout
 
-struct PACKED shadow_pma_entry {
+struct PACKED shadow_pmas_entry {
     uint64_t istart;
     uint64_t ilength;
 };
 
-using shadow_pmas_state = std::array<shadow_pma_entry, PMA_MAX>;
+using shadow_pmas_state = std::array<shadow_pmas_entry, PMA_MAX>;
 
 /// \brief List of field types
 enum class shadow_pmas_what : uint64_t {
-    istart = offsetof(shadow_pma_entry, istart),
-    ilength = offsetof(shadow_pma_entry, ilength),
+    istart = offsetof(shadow_pmas_entry, istart),
+    ilength = offsetof(shadow_pmas_entry, ilength),
     unknown_ = UINT64_C(1) << 63, // Outside of RISC-V address space
 };
 
@@ -50,7 +50,7 @@ enum class shadow_pmas_what : uint64_t {
 /// \param p Index of desired shadow PMA entry
 /// \returns The address.
 static constexpr uint64_t shadow_pmas_get_pma_abs_addr(uint64_t p) {
-    return PMA_SHADOW_PMAS_START + p * sizeof(shadow_pma_entry);
+    return PMA_SHADOW_PMAS_START + p * sizeof(shadow_pmas_entry);
 }
 
 /// \brief Obtains the absolute address of a PMA entry in shadow memory.
@@ -69,18 +69,17 @@ static constexpr shadow_pmas_what shadow_pmas_get_what(uint64_t paddr) {
     //??D First condition ensures offset = (paddr-PMA_SHADOW_PMAS_START) >= 0
     //??D Second ensures offset < sizeof(shadow_pmas_state)
     //??D Third ensures offset is aligned to sizeof(uint64_t)
-    //??D shadow_pma_entry only contains uint64_t fields
-    //??D shadow_pmas_state_what contains one entry with the offset of each field in shadow_pma_entry
+    //??D shadow_pmas_entry only contains uint64_t fields
+    //??D shadow_pmas_state_what contains one entry with the offset of each field in shadow_pmas_entry
     //??D I don't see how the cast can produce something outside the enum...
     // NOLINTNEXTLINE(clang-analyzer-optin.core.EnumCastOutOfRange)
-    return shadow_pmas_what{(paddr - PMA_SHADOW_PMAS_START) % sizeof(shadow_pma_entry)};
+    return shadow_pmas_what{(paddr - PMA_SHADOW_PMAS_START) % sizeof(shadow_pmas_entry)};
 }
 
 static constexpr const char *shadow_pmas_get_what_name(shadow_pmas_what what) {
     const auto paddr = static_cast<uint64_t>(what);
-    if (paddr < PMA_SHADOW_PMAS_START || paddr - PMA_SHADOW_PMAS_START >= sizeof(shadow_pmas_state) ||
-        (paddr & (sizeof(uint64_t) - 1)) != 0) {
-        return "pma.unknown";
+    if (paddr >= sizeof(shadow_pmas_entry) || (paddr & (sizeof(uint64_t) - 1)) != 0) {
+        return "pma.unknown_";
     }
     using reg = shadow_pmas_what;
     switch (what) {
@@ -89,8 +88,9 @@ static constexpr const char *shadow_pmas_get_what_name(shadow_pmas_what what) {
         case reg::ilength:
             return "pma.ilength";
         case reg::unknown_:
-            return "pma.unknown";
+            return "pma.unknown_";
     }
+    return "pmas.unknown_";
 }
 
 } // namespace cartesi
diff --git a/src/shadow-state.h b/src/shadow-state.h
index 60dd9691b..8a02d2fa4 100644
--- a/src/shadow-state.h
+++ b/src/shadow-state.h
@@ -205,7 +205,7 @@ static constexpr const char *shadow_state_get_what_name(shadow_state_what what)
     const auto paddr = static_cast<uint64_t>(what);
     if (paddr < PMA_SHADOW_STATE_START || paddr - PMA_SHADOW_STATE_START >= sizeof(shadow_state) ||
         (paddr & (sizeof(uint64_t) - 1)) != 0) {
-        return "state.unknown";
+        return "state.unknown_";
     }
     using reg = shadow_state_what;
     switch (what) {
@@ -422,10 +422,9 @@ static constexpr const char *shadow_state_get_what_name(shadow_state_what what)
         case reg::htif_iyield:
             return "htif.iyield";
         case reg::unknown_:
-            [[fallthrough]];
-        default:
-            return "state.unknown";
+            return "state.unknown_";
     }
+    return "state.unknown_";
 }
 
 /// \brief Global instance of the processor shadow device driver.
diff --git a/src/shadow-tlb.h b/src/shadow-tlb.h
index 36d8f82d0..52a5d66e0 100644
--- a/src/shadow-tlb.h
+++ b/src/shadow-tlb.h
@@ -89,7 +89,7 @@ static constexpr const char *shadow_tlb_get_what_name(shadow_tlb_what what) {
     const auto offset = static_cast<uint64_t>(what);
     using reg = shadow_tlb_what;
     if (offset > static_cast<uint64_t>(reg::unknown_) || (offset & (sizeof(uint64_t) - 1)) != 0) {
-        return "tlb.unknown";
+        return "tlb.unknown_";
     }
     switch (what) {
         case reg::vaddr_page:
@@ -101,8 +101,9 @@ static constexpr const char *shadow_tlb_get_what_name(shadow_tlb_what what) {
         case reg::zero_padding_:
             return "tlb.slot.zero_padding_";
         case reg::unknown_:
-            return "tlb.unknown";
+            return "tlb.unknown_";
     }
+    return "tlb.unknown_";
 }
 
 [[maybe_unused]] static void shadow_tlb_fill_slot(uint64_t vaddr_page, uint64_t vp_offset, uint64_t pma_index,
diff --git a/src/shadow-uarch-state.h b/src/shadow-uarch-state.h
index bc92c2573..b30762861 100644
--- a/src/shadow-uarch-state.h
+++ b/src/shadow-uarch-state.h
@@ -93,7 +93,7 @@ static constexpr const char *shadow_uarch_state_get_what_name(shadow_uarch_state
     const auto paddr = static_cast<uint64_t>(what);
     if (paddr < PMA_SHADOW_UARCH_STATE_START || paddr - PMA_SHADOW_UARCH_STATE_START >= sizeof(shadow_uarch_state) ||
         (paddr & (sizeof(uint64_t) - 1)) != 0) {
-        return "uarch.unknown";
+        return "uarch.unknown_";
     }
     using reg = shadow_uarch_state_what;
     switch (what) {
@@ -170,6 +170,7 @@ static constexpr const char *shadow_uarch_state_get_what_name(shadow_uarch_state
         case reg::unknown_:
             return "uarch.unknown_";
     }
+    return "uarch.unknown_";
 }
 
 /// \brief Global instance of  theprocessor shadow uarch state device driver.
diff --git a/src/uarch-replay-state-access.h b/src/uarch-replay-state-access.h
index 64a25bfd5..01a2e4fc8 100644
--- a/src/uarch-replay-state-access.h
+++ b/src/uarch-replay-state-access.h
@@ -127,6 +127,7 @@ class uarch_replay_state_access :
             case access_type::write:
                 return "write";
         }
+        return "unknown_";
     }
 
     static std::pair<uint64_t, int> adjust_access(uint64_t paddr, int log2_size) {

From 45f9ea3f0f6c8ce3209a23aee4c46431fa4513dc Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Thu, 6 Feb 2025 14:25:00 +0000
Subject: [PATCH 11/82] refactor: split out i-counters.h

Cleanup several of the DUMP_*.* implementations
---
 src/Makefile                      |   9 +-
 src/dump-state-access.h           |  34 --
 src/dump-uarch-state-access.h     |  34 --
 src/dump.h                        |  18 +-
 src/i-accept-scoped-note.h        |  31 +-
 src/i-counters.h                  |  70 ++++
 src/i-prefer-shadow-state.h       |  11 +-
 src/i-prefer-shadow-uarch-state.h |  11 +-
 src/i-state-access.h              |  44 +-
 src/i-uarch-state-access.h        |  31 +-
 src/interpret.cpp                 | 671 ++++++++++++++++--------------
 src/machine-state.h               |  14 -
 src/machine-statistics.h          |  78 ----
 src/machine.cpp                   | 128 ++++--
 src/machine.h                     |  39 ++
 src/state-access.h                |  40 +-
 src/uarch-solidity-compat.h       |  15 +-
 src/uarch-step.cpp                | 116 +++---
 18 files changed, 717 insertions(+), 677 deletions(-)
 delete mode 100644 src/dump-state-access.h
 delete mode 100644 src/dump-uarch-state-access.h
 create mode 100644 src/i-counters.h
 delete mode 100644 src/machine-statistics.h

diff --git a/src/Makefile b/src/Makefile
index 542ee0c9a..409571a41 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -178,16 +178,17 @@ ifeq ($(dump),yes)
 #DUMP_DEFS+=-DDUMP_ILLEGAL_INSN_EXCEPTIONS
 #DUMP_DEFS+=-DDUMP_EXCEPTIONS
 #DUMP_DEFS+=-DDUMP_INTERRUPTS
-#DUMP_DEFS+=-DDUMP_HIST
 #DUMP_DEFS+=-DDUMP_MMU_EXCEPTIONS
 #DUMP_DEFS+=-DDUMP_INVALID_MEM_ACCESS
 #DUMP_DEFS+=-DDUMP_INVALID_CSR
-#DUMP_DEFS+=-DDUMP_INSN
+#DUMP_DEFS+=-DDUMP_REGS
+DUMP_DEFS+=-DDUMP_INSN_HIST
+DUMP_DEFS+=-DDUMP_STATS
+DUMP_DEFS+=-DDUMP_INSN
+DUMP_DEFS+=-DDUMP_UARCH_INSN
 DUMP_DEFS+=-DDUMP_SCOPED_NOTE
 DUMP_DEFS+=-DDUMP_STATE_ACCESS
 DUMP_DEFS+=-DDUMP_UARCH_STATE_ACCESS
-#DUMP_DEFS+=-DDUMP_REGS
-#DUMP_DEFS+=-DDUMP_COUNTERS
 endif
 DEFS += $(DUMP_DEFS)
 # Pass down UARCH_DEFS to sub-makefiles
diff --git a/src/dump-state-access.h b/src/dump-state-access.h
deleted file mode 100644
index c359de1fa..000000000
--- a/src/dump-state-access.h
+++ /dev/null
@@ -1,34 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef DUMP_STATE_ACCESS_H
-#define DUMP_STATE_ACCESS_H
-
-#include "dump.h"
-
-#ifdef DUMP_STATE_ACCESS
-template <typename... ARGS>
-static inline auto DSA_PRINTF(ARGS... args) {
-    return D_PRINTF(args...);
-}
-#else
-template <typename... ARGS>
-static inline auto DSA_PRINTF(ARGS... /*args*/) {
-    return 0;
-}
-#endif
-
-#endif
diff --git a/src/dump-uarch-state-access.h b/src/dump-uarch-state-access.h
deleted file mode 100644
index 6389574dc..000000000
--- a/src/dump-uarch-state-access.h
+++ /dev/null
@@ -1,34 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef DUMP_UARCH_STATE_ACCESS_H
-#define DUMP_UARCH_STATE_ACCESS_H
-
-#include "dump.h"
-
-#ifdef DUMP_UARCH_STATE_ACCESS
-template <typename... ARGS>
-static inline auto DUSA_PRINTF(ARGS... args) {
-    return D_PRINTF(args...);
-}
-#else
-template <typename... ARGS>
-static inline auto DUSA_PRINTF(ARGS... /*args*/) {
-    return 0;
-}
-#endif
-
-#endif
diff --git a/src/dump.h b/src/dump.h
index 5281519f4..507d18538 100644
--- a/src/dump.h
+++ b/src/dump.h
@@ -14,19 +14,21 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#ifndef DUMP__H
-#define DUMP__H
+#include <tuple>
+
+#ifndef DUMP_H
+#define DUMP_H
 
 #ifdef MICROARCHITECTURE
-template <typename... ARGS>
-static inline auto D_PRINTF(ARGS... args) {
-    return printf(args...);
+template <size_t N, typename... ARGS>
+static inline void D_PRINTF(const char (&fmt)[N], ARGS... args) {
+    std::ignore = printf(fmt, args...);
 }
 #else
 #include <cstdio>
-template <typename... ARGS>
-static inline auto D_PRINTF(ARGS... args) {
-    return fprintf(stderr, args...);
+template <size_t N, typename... ARGS>
+static inline auto D_PRINTF(const char (&fmt)[N], ARGS... args) {
+    std::ignore = fprintf(stderr, fmt, args...);
 }
 #endif
 
diff --git a/src/i-accept-scoped-note.h b/src/i-accept-scoped-note.h
index 6c9dd3ad7..e05124135 100644
--- a/src/i-accept-scoped-note.h
+++ b/src/i-accept-scoped-note.h
@@ -23,27 +23,14 @@
 #include <cstdint>
 #include <type_traits>
 
-#ifdef DUMP_SCOPED_NOTE
 #include "dump.h"
-#endif
-
+#include "i-state-access.h"
+#include "i-uarch-state-access.h"
 #include "meta.h"
 #include "scoped-note.h"
 
 namespace cartesi {
 
-#ifdef DUMP_SCOPED_NOTE
-template <typename... ARGS>
-static inline auto DSN_PRINTF(ARGS... args) {
-    return D_PRINTF(args...);
-}
-#else
-template <typename... ARGS>
-static inline auto DSN_PRINTF(ARGS... /*args*/) {
-    return 0;
-}
-#endif
-
 /// \class i_accept_scoped_note
 /// \brief Interface that lets a state access accept scoped notes.
 /// \tparam DERIVED Derived class implementing the interface. (An example of CRTP.)
@@ -61,6 +48,20 @@ class i_accept_scoped_note { // CRTP
     }
 
 public:
+    /// \brief Works as printf if we are dumping scoped notes, otherwise does nothing
+    template <size_t N, typename... ARGS>
+    static void DSN_PRINTF([[maybe_unused]] const char (&fmt)[N], [[maybe_unused]] ARGS... args) {
+#ifdef DUMP_SCOPED_NOTE
+        if constexpr (is_an_i_state_access_v<DERIVED>) {
+            DERIVED::DSA_PRINTF(fmt, args...);
+        } else if (is_an_i_uarch_state_access_v<DERIVED>) {
+            DERIVED::DUSA_PRINTF(fmt, args...);
+        } else {
+            D_PRINTF(fmt, args...);
+        }
+#endif
+    }
+
     /// \brief Adds a begin bracket annotation to the log
     /// \param text String with the text for the annotation
     void push_begin_bracket(const char *text) {
diff --git a/src/i-counters.h b/src/i-counters.h
new file mode 100644
index 000000000..32078c6ea
--- /dev/null
+++ b/src/i-counters.h
@@ -0,0 +1,70 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef I_COUNTERS_H
+#define I_COUNTERS_H
+
+/// \file
+/// \brief Interface for state access that prefers to go thrhough shadow state
+
+#include <cstdint>
+#include <type_traits>
+
+#include "meta.h"
+
+namespace cartesi {
+
+/// \class i_counters
+/// \brief Interface for multiplexed access to shadow state.
+/// \tparam DERIVED Derived class implementing the interface. (An example of CRTP.)
+/// \detail This is for state access methods that do not need individualized access to machine registers
+template <typename DERIVED>
+class i_counters { // CRTP
+
+    /// \brief Returns object cast as the derived class
+    DERIVED &derived() {
+        return *static_cast<DERIVED *>(this);
+    }
+
+    /// \brief Returns object cast as the derived class
+    const DERIVED &derived() const {
+        return *static_cast<const DERIVED *>(this);
+    }
+
+public:
+    void increment_counter(const char *name, const char *domain = nullptr) {
+        derived().do_increment_counter(name, domain);
+    }
+
+    uint64_t read_counter(const char *name, const char *domain = nullptr) {
+        return derived().do_read_counter(name, domain);
+    }
+
+    void write_counter(uint64_t val, const char *name, const char *domain = nullptr) {
+        derived().do_write_counter(val, name, domain);
+    }
+};
+
+/// \brief SFINAE test implementation of the i_state_access interface
+template <typename DERIVED>
+using is_an_i_counters = std::integral_constant<bool, is_template_base_of_v<i_counters, std::remove_cvref_t<DERIVED>>>;
+
+template <typename DERIVED>
+constexpr bool is_an_i_counters_v = is_an_i_counters<DERIVED>::value;
+
+} // namespace cartesi
+
+#endif
diff --git a/src/i-prefer-shadow-state.h b/src/i-prefer-shadow-state.h
index 4ae0fe637..a1d6b78d8 100644
--- a/src/i-prefer-shadow-state.h
+++ b/src/i-prefer-shadow-state.h
@@ -21,11 +21,9 @@
 /// \file
 /// \brief Interface for state access that prefers to go through shadow state
 
-#include <cinttypes>
 #include <cstdint>
 #include <type_traits>
 
-#include "dump-state-access.h"
 #include "meta.h"
 #include "shadow-state.h"
 #include "tlb.h"
@@ -51,18 +49,11 @@ class i_prefer_shadow_state { // CRTP
 
 public:
     uint64_t read_shadow_state(shadow_state_what what) {
-        const auto val = derived().do_read_shadow_state(what);
-        [[maybe_unused]] const auto *const what_name = shadow_state_get_what_name(what);
-        DSA_PRINTF("%s::read_shadow_state(%s) = %" PRIu64 "(0x%" PRIx64 ")\n", derived().get_name(), what_name, val,
-            val);
-        return val;
+        return derived().do_read_shadow_state(what);
     }
 
     void write_shadow_state(shadow_state_what what, uint64_t val) {
         derived().do_write_shadow_state(what, val);
-        [[maybe_unused]] const auto *const what_name = shadow_state_get_what_name(what);
-        DSA_PRINTF("%s::write_shadow_state(%s, %" PRIu64 "(0x%" PRIx64 "))\n", derived().get_name(), what_name, val,
-            val);
     }
 };
 
diff --git a/src/i-prefer-shadow-uarch-state.h b/src/i-prefer-shadow-uarch-state.h
index 53f95dda9..69faa875c 100644
--- a/src/i-prefer-shadow-uarch-state.h
+++ b/src/i-prefer-shadow-uarch-state.h
@@ -21,11 +21,9 @@
 /// \file
 /// \brief Interface for state access that prefers to go through shadow uarch state
 
-#include <cinttypes>
 #include <cstdint>
 #include <type_traits>
 
-#include "dump-uarch-state-access.h"
 #include "meta.h"
 #include "shadow-uarch-state.h"
 #include "tlb.h"
@@ -51,18 +49,11 @@ class i_prefer_shadow_uarch_state { // CRTP
 
 public:
     uint64_t read_shadow_uarch_state(shadow_uarch_state_what what) {
-        const auto val = derived().do_read_shadow_uarch_state(what);
-        [[maybe_unused]] const auto *const what_name = shadow_uarch_state_get_what_name(what);
-        DUSA_PRINTF("%s::read_shadow_uarch_state(%s) = %" PRIu64 "(0x%" PRIx64 ")\n", derived().get_name(), what_name,
-            val, val);
-        return val;
+        return derived().do_read_shadow_uarch_state(what);
     }
 
     void write_shadow_uarch_state(shadow_uarch_state_what what, uint64_t val) {
         derived().do_write_shadow_uarch_state(what, val);
-        [[maybe_unused]] const auto *const what_name = shadow_uarch_state_get_what_name(what);
-        DUSA_PRINTF("%s::write_shadow_uarch_state(%s, %" PRIu64 "(0x%" PRIx64 "))\n", derived().get_name(), what_name,
-            val, val);
     }
 };
 
diff --git a/src/i-state-access.h b/src/i-state-access.h
index d8eafe2bd..d8d90f17f 100644
--- a/src/i-state-access.h
+++ b/src/i-state-access.h
@@ -25,7 +25,7 @@
 #include <type_traits>
 #include <utility>
 
-#include "dump-state-access.h"
+#include "dump.h"
 #include "i-prefer-shadow-state.h"
 #include "meta.h"
 #include "pm-type-name.h"
@@ -56,7 +56,7 @@ using i_state_access_fast_addr_t = typename i_state_access_fast_addr<STATE_ACCES
             DSA_PRINTF("%s::read_" #REG "() = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), val, val);                    \
             return val;                                                                                                \
         } else {                                                                                                       \
-            return derived().read_shadow_state(shadow_state_what::REG);                                                \
+            return prefer_read_shadow_state(shadow_state_what::REG);                                                   \
         }                                                                                                              \
     }
 
@@ -66,7 +66,7 @@ using i_state_access_fast_addr_t = typename i_state_access_fast_addr<STATE_ACCES
             derived().do_write_##REG(val);                                                                             \
             DSA_PRINTF("%s::write_" #REG "(%" PRIu64 "(0x%" PRIx64 "))\n", get_name(), val, val);                      \
         } else {                                                                                                       \
-            derived().write_shadow_state(shadow_state_what::REG, val);                                                 \
+            prefer_write_shadow_state(shadow_state_what::REG, val);                                                    \
         }                                                                                                              \
     }
 // NOLINTEND(cppcoreguidelines-macro-usage)
@@ -107,14 +107,29 @@ class i_state_access { // CRTP
         return *static_cast<const DERIVED *>(this);
     }
 
+    uint64_t prefer_read_shadow_state(shadow_state_what what) {
+        const auto val = derived().read_shadow_state(what);
+        [[maybe_unused]] const auto *const what_name = shadow_state_get_what_name(what);
+        DSA_PRINTF("%s::read_shadow_state(%s) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), what_name, val, val);
+        return val;
+    }
+
+    void prefer_write_shadow_state(shadow_state_what what, uint64_t val) {
+        derived().write_shadow_state(what, val);
+        [[maybe_unused]] const auto *const what_name = shadow_state_get_what_name(what);
+        DSA_PRINTF("%s::write_shadow_state(%s, %" PRIu64 "(0x%" PRIx64 "))\n", get_name(), what_name, val, val);
+    }
+
 public:
     using pma_entry = i_state_access_pma_entry_t<DERIVED>;
     using fast_addr = i_state_access_fast_addr_t<DERIVED>;
 
-    //??D We should probably remove this from the interface
-    /// \brief Returns machine state for direct access.
-    auto &get_naked_state() {
-        return derived().do_get_naked_state();
+    /// \brief Works as printf if we are dumping state accesses, otherwise does nothing
+    template <size_t N, typename... ARGS>
+    static void DSA_PRINTF([[maybe_unused]] const char (&fmt)[N], [[maybe_unused]] ARGS... args) {
+#ifdef DUMP_STATE_ACCESS
+        D_PRINTF(fmt, args...);
+#endif
     }
 
     /// \brief Reads from general-purpose register.
@@ -126,7 +141,7 @@ class i_state_access { // CRTP
             DSA_PRINTF("%s::read_x(%d) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), i, val, val);
             return val;
         } else {
-            return derived().read_shadow_state(shadow_state_get_what(shadow_state_what::x0, i));
+            return prefer_read_shadow_state(shadow_state_get_what(shadow_state_what::x0, i));
         }
     }
 
@@ -140,7 +155,7 @@ class i_state_access { // CRTP
             derived().do_write_x(i, val);
             DSA_PRINTF("%s::write_x(%d, %" PRIu64 "(0x%" PRIx64 "))\n", get_name(), i, val, val);
         } else {
-            derived().write_shadow_state(shadow_state_get_what(shadow_state_what::x0, i), val);
+            prefer_write_shadow_state(shadow_state_get_what(shadow_state_what::x0, i), val);
         }
     }
 
@@ -153,7 +168,7 @@ class i_state_access { // CRTP
             DSA_PRINTF("%s::read_f(%d) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), i, val, val);
             return val;
         } else {
-            return derived().read_shadow_state(shadow_state_get_what(shadow_state_what::f0, i));
+            return prefer_read_shadow_state(shadow_state_get_what(shadow_state_what::f0, i));
         }
     }
 
@@ -165,7 +180,7 @@ class i_state_access { // CRTP
             derived().do_write_f(i, val);
             DSA_PRINTF("%s::write_f(%d, %" PRIu64 "(%" PRIx64 "))\n", get_name(), i, val, val);
         } else {
-            derived().write_shadow_state(shadow_state_get_what(shadow_state_what::f0, i), val);
+            prefer_write_shadow_state(shadow_state_get_what(shadow_state_what::f0, i), val);
         }
     }
 
@@ -417,13 +432,6 @@ class i_state_access { // CRTP
         derived().do_putchar(c);
     }
 
-#ifdef DUMP_COUNTERS
-    //??D we should probably remove this from the interface
-    auto &get_statistics() {
-        return derived().do_get_statistics();
-    }
-#endif
-
     constexpr const char *get_name() const {
         return derived().do_get_name();
     }
diff --git a/src/i-uarch-state-access.h b/src/i-uarch-state-access.h
index be9dfd175..183874100 100644
--- a/src/i-uarch-state-access.h
+++ b/src/i-uarch-state-access.h
@@ -20,7 +20,7 @@
 #include <cinttypes>
 #include <cstdint>
 
-#include "dump-uarch-state-access.h"
+#include "dump.h"
 #include "i-prefer-shadow-uarch-state.h"
 #include "meta.h"
 #include "tlb.h"
@@ -33,7 +33,7 @@
             DUSA_PRINTF("%s::read_" #REG "() = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), val, val);                   \
             return val;                                                                                                \
         } else {                                                                                                       \
-            return derived().read_shadow_uarch_state(shadow_uarch_state_what::REG);                                    \
+            return prefer_read_shadow_uarch_state(shadow_uarch_state_what::REG);                                       \
         }                                                                                                              \
     }
 
@@ -43,7 +43,7 @@
             derived().do_write_##REG(val);                                                                             \
             DUSA_PRINTF("%s::write_" #REG "(%" PRIu64 "(0x%" PRIx64 "))\n", get_name(), val, val);                     \
         } else {                                                                                                       \
-            derived().write_shadow_uarch_state(shadow_uarch_state_what::REG, val);                                     \
+            prefer_write_shadow_uarch_state(shadow_uarch_state_what::REG, val);                                        \
         }                                                                                                              \
     }
 // NOLINTEND(cppcoreguidelines-macro-usage)
@@ -64,14 +64,35 @@ class i_uarch_state_access { // CRTP
         return *static_cast<const DERIVED *>(this);
     }
 
+    uint64_t prefer_read_shadow_uarch_state(shadow_uarch_state_what what) {
+        const auto val = derived().read_shadow_uarch_state(what);
+        [[maybe_unused]] const auto *const what_name = shadow_uarch_state_get_what_name(what);
+        DUSA_PRINTF("%s::read_shadow_uarch_state(%s) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), what_name, val, val);
+        return val;
+    }
+
+    void prefer_write_shadow_uarch_state(shadow_uarch_state_what what, uint64_t val) {
+        derived().write_shadow_uarch_state(what, val);
+        [[maybe_unused]] const auto *const what_name = shadow_uarch_state_get_what_name(what);
+        DUSA_PRINTF("%s::write_shadow_uarch_state(%s, %" PRIu64 "(0x%" PRIx64 "))\n", get_name(), what_name, val, val);
+    }
+
 public:
+    /// \brief Works as printf if we are dumping uarch state accesses, otherwise does nothing
+    template <size_t N, typename... ARGS>
+    static void DUSA_PRINTF([[maybe_unused]] const char (&fmt)[N], [[maybe_unused]] ARGS... args) {
+#ifdef DUMP_UARCH_STATE_ACCESS
+        D_PRINTF(fmt, args...);
+#endif
+    }
+
     uint64_t read_uarch_x(int i) {
         if constexpr (!is_an_i_prefer_shadow_uarch_state_v<DERIVED>) {
             const auto val = derived().do_read_uarch_x(i);
             DUSA_PRINTF("%s::read_uarch_x(%d) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), i, val, val);
             return val;
         } else {
-            return derived().read_shadow_uarch_state(shadow_uarch_state_get_what(shadow_uarch_state_what::uarch_x0, i));
+            return prefer_read_shadow_uarch_state(shadow_uarch_state_get_what(shadow_uarch_state_what::uarch_x0, i));
         }
     }
 
@@ -80,7 +101,7 @@ class i_uarch_state_access { // CRTP
             derived().do_write_uarch_x(i, val);
             DUSA_PRINTF("%s::write_uarch_x(%d, %" PRIu64 ")\n", get_name(), i, val);
         } else {
-            derived().write_shadow_uarch_state(shadow_uarch_state_get_what(shadow_uarch_state_what::uarch_x0, i), val);
+            prefer_write_shadow_uarch_state(shadow_uarch_state_get_what(shadow_uarch_state_what::uarch_x0, i), val);
         }
     }
 
diff --git a/src/interpret.cpp b/src/interpret.cpp
index bd8f418de..6fb4809ff 100644
--- a/src/interpret.cpp
+++ b/src/interpret.cpp
@@ -33,9 +33,10 @@
 
 #include "compiler-defines.h"
 #include "device-state-access.h"
+#include "dump.h"
+#include "i-counters.h"
 #include "i-interactive-state-access.h"
 #include "i-state-access.h"
-#include "machine-statistics.h"
 #include "tlb.h"
 
 /// \file
@@ -122,6 +123,24 @@ enum class rd_kind {
     xN, // rd is a positive natural number (1, 2, 3 ... 31)
 };
 
+template <typename STATE_ACCESS>
+static inline void DUMP_STATS_INCR([[maybe_unused]] STATE_ACCESS a, [[maybe_unused]] const char *name) {
+#ifdef DUMP_STATS
+    if constexpr (is_an_i_counters_v<STATE_ACCESS>) {
+        a.increment_counter(name, "stats.");
+    }
+#endif
+}
+
+template <typename STATE_ACCESS>
+static inline void DUMP_INSN_HIST_INCR([[maybe_unused]] STATE_ACCESS a, [[maybe_unused]] const char *name) {
+#ifdef DUMP_INSN_HIST
+    if constexpr (is_an_i_counters_v<STATE_ACCESS>) {
+        a.increment_counter(name, "insn.");
+    }
+#endif
+}
+
 #ifdef DUMP_REGS
 static const std::array<const char *, X_REG_COUNT> reg_name{"zero", "ra", "sp", "gp", "tp", "t0", "t1", "t2", "s0",
     "s1", "a0", "a1", "a2", "a3", "a4", "a5", "a6", "a7", "s2", "s3", "s4", "s5", "s6", "s7", "s8", "s9", "s10", "s11",
@@ -132,7 +151,7 @@ static const std::array<const char *, F_REG_COUNT> f_reg_name{"ft0", "ft1", "ft2
     "fs8", "fs9", "fs10", "fs11", "ft8", "ft9", "ft10", "ft11"};
 
 static void print_uint64_t(uint64_t a) {
-    std::ignore = fprintf(stderr, "%016" PRIx64, a);
+    D_PRINTF("%016" PRIx64, a);
 }
 #endif
 
@@ -169,94 +188,94 @@ static void dump_exception_or_interrupt(uint64_t cause, STATE &s) {
     if ((cause & MCAUSE_INTERRUPT_FLAG) != 0) {
         switch (cause & ~MCAUSE_INTERRUPT_FLAG) {
             case 0:
-                std::ignore = fprintf(stderr, "reserved software interrupt");
+                D_PRINTF("reserved software interrupt");
                 break;
             case 1:
-                std::ignore = fprintf(stderr, "supervisor software interrupt");
+                D_PRINTF("supervisor software interrupt");
                 break;
             case 2:
-                std::ignore = fprintf(stderr, "reserved software interrupt");
+                D_PRINTF("reserved software interrupt");
                 break;
             case 3:
-                std::ignore = fprintf(stderr, "machine software interrupt");
+                D_PRINTF("machine software interrupt");
                 break;
             case 4:
-                std::ignore = fprintf(stderr, "reserved timer interrupt");
+                D_PRINTF("reserved timer interrupt");
                 break;
             case 5:
-                std::ignore = fprintf(stderr, "supervisor timer interrupt");
+                D_PRINTF("supervisor timer interrupt");
                 break;
             case 6:
-                std::ignore = fprintf(stderr, "reserved timer interrupt");
+                D_PRINTF("reserved timer interrupt");
                 break;
             case 7:
-                std::ignore = fprintf(stderr, "machine timer interrupt");
+                D_PRINTF("machine timer interrupt");
                 break;
             case 8:
-                std::ignore = fprintf(stderr, "reserved external interrupt");
+                D_PRINTF("reserved external interrupt");
                 break;
             case 9:
-                std::ignore = fprintf(stderr, "supervisor external interrupt");
+                D_PRINTF("supervisor external interrupt");
                 break;
             case 10:
-                std::ignore = fprintf(stderr, "reserved external interrupt");
+                D_PRINTF("reserved external interrupt");
                 break;
             case 11:
-                std::ignore = fprintf(stderr, "machine external interrupt");
+                D_PRINTF("machine external interrupt");
                 break;
             default:
-                std::ignore = fprintf(stderr, "unknown interrupt");
+                D_PRINTF("unknown interrupt");
                 break;
         }
     } else {
         switch (cause) {
             case 0:
-                std::ignore = fprintf(stderr, "instruction address misaligned");
+                D_PRINTF("instruction address misaligned");
                 break;
             case 1:
-                std::ignore = fprintf(stderr, "instruction access fault");
+                D_PRINTF("instruction access fault");
                 break;
             case 2:
-                std::ignore = fprintf(stderr, "illegal instruction");
+                D_PRINTF("illegal instruction");
                 break;
             case 3:
-                std::ignore = fprintf(stderr, "breakpoint");
+                D_PRINTF("breakpoint");
                 break;
             case 4:
-                std::ignore = fprintf(stderr, "load address misaligned");
+                D_PRINTF("load address misaligned");
                 break;
             case 5:
-                std::ignore = fprintf(stderr, "load access fault");
+                D_PRINTF("load access fault");
                 break;
             case 6:
-                std::ignore = fprintf(stderr, "store/amo address misaligned");
+                D_PRINTF("store/amo address misaligned");
                 break;
             case 7:
-                std::ignore = fprintf(stderr, "store/amo access fault");
+                D_PRINTF("store/amo access fault");
                 break;
             case 8:
-                std::ignore = fprintf(stderr, "ecall %d from u-mode", static_cast<int>(a7));
+                D_PRINTF("ecall %d from u-mode", static_cast<int>(a7));
                 break;
             case 9:
-                std::ignore = fprintf(stderr, "ecall %s(%d) from s-mode", sbi_ecall_name(a7), static_cast<int>(a7));
+                D_PRINTF("ecall %s(%d) from s-mode", sbi_ecall_name(a7), static_cast<int>(a7));
                 break;
             case 10:
-                std::ignore = fprintf(stderr, "ecall %d reserved", static_cast<int>(a7));
+                D_PRINTF("ecall %d reserved", static_cast<int>(a7));
                 break;
             case 11:
-                std::ignore = fprintf(stderr, "ecall %s(%d) from m-mode", sbi_ecall_name(a7), static_cast<int>(a7));
+                D_PRINTF("ecall %s(%d) from m-mode", sbi_ecall_name(a7), static_cast<int>(a7));
                 break;
             case 12:
-                std::ignore = fprintf(stderr, "instruction page fault");
+                D_PRINTF("instruction page fault");
                 break;
             case 13:
-                std::ignore = fprintf(stderr, "load page fault");
+                D_PRINTF("load page fault");
                 break;
             case 15:
-                std::ignore = fprintf(stderr, "store/amo page fault");
+                D_PRINTF("store/amo page fault");
                 break;
             default:
-                std::ignore = fprintf(stderr, "reserved");
+                D_PRINTF("reserved");
                 break;
         }
     }
@@ -268,40 +287,40 @@ template <typename STATE>
 static void dump_regs(const STATE &s) {
     const std::array<char, 5> prv_str{"USHM"};
     int cols = 256 / XLEN;
-    std::ignore = fprintf(stderr, "pc = ");
+    D_PRINTF("pc = ");
     print_uint64_t(s.pc);
-    std::ignore = fprintf(stderr, " ");
+    D_PRINTF(" ");
     for (int i = 1; i < X_REG_COUNT; i++) {
-        std::ignore = fprintf(stderr, "%-3s= ", reg_name[i]);
+        D_PRINTF("%-3s= ", reg_name[i]);
         print_uint64_t(s.x[i]);
         if ((i & (cols - 1)) == (cols - 1)) {
-            std::ignore = fprintf(stderr, "\n");
+            D_PRINTF("\n");
         } else {
-            std::ignore = fprintf(stderr, " ");
+            D_PRINTF(" ");
         }
     }
     for (int i = 0; i < F_REG_COUNT; i++) {
-        std::ignore = fprintf(stderr, "%-3s= ", f_reg_name[i]);
+        D_PRINTF("%-3s= ", f_reg_name[i]);
         print_uint64_t(s.f[i]);
         if ((i & (cols - 1)) == (cols - 1)) {
-            std::ignore = fprintf(stderr, "\n");
+            D_PRINTF("\n");
         } else {
-            std::ignore = fprintf(stderr, " ");
+            D_PRINTF(" ");
         }
     }
-    std::ignore = fprintf(stderr, "prv=%c", prv_str[s.iprv]);
-    std::ignore = fprintf(stderr, " mstatus=");
+    D_PRINTF("prv=%c", prv_str[s.iprv]);
+    D_PRINTF(" mstatus=");
     print_uint64_t(s.mstatus);
-    std::ignore = fprintf(stderr, " cycles=%" PRId64, s.mcycle);
-    std::ignore = fprintf(stderr, " insns=%" PRId64, s.mcycle - s.icycleinstret);
-    std::ignore = fprintf(stderr, "\n");
-    std::ignore = fprintf(stderr, "mideleg=");
+    D_PRINTF(" cycles=%" PRId64, s.mcycle);
+    D_PRINTF(" insns=%" PRId64, s.mcycle - s.icycleinstret);
+    D_PRINTF("\n");
+    D_PRINTF("mideleg=");
     print_uint64_t(s.mideleg);
-    std::ignore = fprintf(stderr, " mie=");
+    D_PRINTF(" mie=");
     print_uint64_t(s.mie);
-    std::ignore = fprintf(stderr, " mip=");
+    D_PRINTF(" mip=");
     print_uint64_t(s.mip);
-    std::ignore = fprintf(stderr, "\n");
+    D_PRINTF("\n");
 }
 #endif
 
@@ -327,19 +346,36 @@ static inline uint32_t csr_prv(CSR_address csr) {
     return (to_underlying(csr) >> 8) & 3;
 }
 
+/// \brief Returns the statistic name for a change to a given privilege level
+/// \param prv Privilege level
+constexpr const char *prv_stat(uint64_t prv) {
+    switch (prv) {
+        case PRV_U:
+            return "prv.U";
+        case PRV_S:
+            return "prv.S";
+        case PRV_HS:
+            return "prv.HS";
+        case PRV_M:
+            return "prv.M";
+        default:
+            return "prv.unknown";
+    }
+}
+
 /// \brief Changes privilege level.
 /// \param a Machine state accessor object.
 /// \param previous_prv Previous privilege level.
 /// \param new_prv New privilege level.
 /// \details This function is outlined to minimize host CPU code cache pressure.
 template <typename STATE_ACCESS>
-static FORCE_INLINE void set_prv(STATE_ACCESS a, int new_prv) {
-    INC_COUNTER(a.get_statistics(), priv_level[new_prv]);
+static FORCE_INLINE void set_prv(STATE_ACCESS a, uint64_t new_prv) {
+    DUMP_STATS_INCR(a, prv_stat(new_prv));
     a.write_iprv(new_prv);
     // Invalidate all TLB entries
     flush_all_tlb(a);
-    INC_COUNTER(a.get_statistics(), tlb_flush_all);
-    INC_COUNTER(a.get_statistics(), tlb_flush_set_prv);
+    DUMP_STATS_INCR(a, "tlb.flush_all");
+    DUMP_STATS_INCR(a, "tlb.flush_set_prv");
     //??D new privileged 1.11 draft says invalidation should
     // happen within a trap handler, although it could
     // also happen in xRET insn.
@@ -382,13 +418,13 @@ static NO_INLINE uint64_t raise_exception(STATE_ACCESS a, uint64_t pc, uint64_t
             flag = 1;
 #endif
         if (flag) {
-            std::ignore = fprintf(stderr, "raise_exception: cause=0x");
+            D_PRINTF("raise_exception: cause=0x");
             print_uint64_t(cause);
-            std::ignore = fprintf(stderr, " tval=0x");
+            D_PRINTF(" tval=0x");
             print_uint64_t(tval);
-            std::ignore = fprintf(stderr, " (");
+            D_PRINTF(" (");
             dump_exception_or_interrupt(cause, a.get_naked_state());
-            std::ignore = fprintf(stderr, ")\n");
+            D_PRINTF(")\n");
 #ifdef DUMP_REGS
             dump_regs(a.get_naked_state());
 #endif
@@ -427,11 +463,12 @@ static NO_INLINE uint64_t raise_exception(STATE_ACCESS a, uint64_t pc, uint64_t
             set_prv(a, PRV_S);
         }
         new_pc = a.read_stvec();
-#ifdef DUMP_COUNTERS
+#ifdef DUMP_STATS
         if (cause & MCAUSE_INTERRUPT_FLAG) {
-            INC_COUNTER(a.get_statistics(), sv_int);
-        } else if (cause >= MCAUSE_ECALL_BASE && cause <= MCAUSE_ECALL_BASE + PRV_M) { // Do not count environment calls
-            INC_COUNTER(a.get_statistics(), sv_ex);
+            DUMP_STATS_INCR(a, "sv_int");
+        } else if (cause >= MCAUSE_ECALL_BASE &&
+            cause <= +MCAUSE_ECALL_BASE + +PRV_M) { // Do not count environment calls
+            DUMP_STATS_INCR(a, "sv_ex");
         }
 #endif
     } else {
@@ -447,11 +484,12 @@ static NO_INLINE uint64_t raise_exception(STATE_ACCESS a, uint64_t pc, uint64_t
             set_prv(a, PRV_M);
         }
         new_pc = a.read_mtvec();
-#ifdef DUMP_COUNTERS
+#ifdef DUMP_STATS
         if (cause & MCAUSE_INTERRUPT_FLAG) {
-            INC_COUNTER(a.get_statistics(), m_int);
-        } else if (cause >= MCAUSE_ECALL_BASE && cause <= MCAUSE_ECALL_BASE + PRV_M) { // Do not count environment calls
-            INC_COUNTER(a.get_statistics(), m_ex);
+            DUMP_STATS_INCR(a, "m_int");
+        } else if (cause >= MCAUSE_ECALL_BASE &&
+            cause <= +MCAUSE_ECALL_BASE + +PRV_M) { // Do not count environment calls
+            DUMP_STATS_INCR(a, "m_ex");
         }
 #endif
     }
@@ -831,7 +869,7 @@ static FORCE_INLINE int32_t insn_get_C_SWSP_imm(uint32_t insn) {
 /// \param a Machine state accessor object.
 /// \param slot_index Slot index
 template <TLB_set_index SET, typename STATE_ACCESS>
-static void flush_tlb_slot(STATE_ACCESS &a, uint64_t slot_index) {
+static void flush_tlb_slot(STATE_ACCESS a, uint64_t slot_index) {
     // Make sure a valid page leaving the write TLB is marked as dirty
     // We must do this BEFORE we modify the TLB entries themselves
     // (Otherwise, we could stop uarch before it marks the page dirty but after
@@ -858,7 +896,7 @@ static void flush_tlb_slot(STATE_ACCESS &a, uint64_t slot_index) {
 /// \tparam STATE_ACCESS Class of machine state accessor object.
 /// \param a Machine state accessor object.
 template <TLB_set_index SET, typename STATE_ACCESS>
-static void flush_tlb_set(STATE_ACCESS &a) {
+static void flush_tlb_set(STATE_ACCESS a) {
     for (uint64_t slot_index = 0; slot_index < PMA_TLB_SIZE; ++slot_index) {
         flush_tlb_slot<SET>(a, slot_index);
     }
@@ -868,7 +906,7 @@ static void flush_tlb_set(STATE_ACCESS &a) {
 /// \tparam STATE_ACCESS Class of machine state accessor object.
 /// \param a Machine state accessor object.
 template <typename STATE_ACCESS>
-static void flush_all_tlb(STATE_ACCESS &a) {
+static void flush_all_tlb(STATE_ACCESS a) {
     flush_tlb_set<TLB_CODE>(a);
     flush_tlb_set<TLB_READ>(a);
     flush_tlb_set<TLB_WRITE>(a);
@@ -879,7 +917,7 @@ static void flush_all_tlb(STATE_ACCESS &a) {
 /// \param a Machine state accessor object.
 /// \param vaddr Virtual address to remove form mapping
 template <typename STATE_ACCESS>
-static void flush_tlb_vaddr(STATE_ACCESS &a, uint64_t /* vaddr */) {
+static void flush_tlb_vaddr(STATE_ACCESS a, uint64_t /* vaddr */) {
     // We can't flush just one TLB entry for that specific virtual address,
     // because megapages/gigapages may be in use while this TLB implementation ignores it,
     // so we have to flush all addresses.
@@ -898,7 +936,7 @@ static void flush_tlb_vaddr(STATE_ACCESS &a, uint64_t /* vaddr */) {
 /// \param vp_offset Receives the new vp_offset that will be stored in the slot
 /// \returns The implementation-defined fast address corresponding to paddr
 template <TLB_set_index SET, typename STATE_ACCESS>
-static i_state_access_fast_addr_t<STATE_ACCESS> replace_tlb_entry(STATE_ACCESS &a, uint64_t vaddr, uint64_t paddr,
+static i_state_access_fast_addr_t<STATE_ACCESS> replace_tlb_entry(STATE_ACCESS a, uint64_t vaddr, uint64_t paddr,
     uint64_t pma_index, i_state_access_fast_addr_t<STATE_ACCESS> &vp_offset) {
     [[maybe_unused]] auto note = a.make_scoped_note("replace_tlb_entry");
     const auto slot_index = tlb_slot_index(vaddr);
@@ -919,7 +957,7 @@ static i_state_access_fast_addr_t<STATE_ACCESS> replace_tlb_entry(STATE_ACCESS &
 /// \param paddr Index of PMA where paddr falls
 /// \returns The implementation-defined fast address corresponding to paddr
 template <TLB_set_index SET, typename STATE_ACCESS>
-static FORCE_INLINE auto replace_tlb_entry(STATE_ACCESS &a, uint64_t vaddr, uint64_t paddr, uint64_t pma_index) {
+static FORCE_INLINE auto replace_tlb_entry(STATE_ACCESS a, uint64_t vaddr, uint64_t paddr, uint64_t pma_index) {
     i_state_access_fast_addr_t<STATE_ACCESS> vp_offset{0};
     return replace_tlb_entry<SET>(a, vaddr, paddr, pma_index, vp_offset);
 }
@@ -1002,8 +1040,8 @@ static FORCE_INLINE bool read_virtual_memory(STATE_ACCESS a, uint64_t &pc, uint6
     const auto slot_vaddr_page = a.template read_tlb_vaddr_page<TLB_READ>(slot_index);
     if (unlikely(!tlb_is_hit<T>(slot_vaddr_page, vaddr))) {
         // Outline the slow path into a function call to minimize host CPU code cache pressure
-        INC_COUNTER(a.get_statistics(), tlb_rmiss);
         T val = 0; // Don't pass pval reference directly so the compiler can store it in a register
+        DUMP_STATS_INCR(a, "tlb.rmiss");
         auto [status, new_pc] =
             read_virtual_memory_slow<T, STATE_ACCESS, RAISE_STORE_EXCEPTIONS>(a, pc, mcycle, vaddr, &val);
         *pval = val;
@@ -1014,7 +1052,7 @@ static FORCE_INLINE bool read_virtual_memory(STATE_ACCESS a, uint64_t &pc, uint6
     const auto vp_offset = a.template read_tlb_vp_offset<TLB_READ>(slot_index);
     const auto faddr = vaddr + vp_offset;
     a.template read_memory_word<T>(faddr, pma_index, pval);
-    INC_COUNTER(a.get_statistics(), tlb_rhit);
+    DUMP_STATS_INCR(a, "tlb.rhit");
     return true;
 }
 
@@ -1088,7 +1126,7 @@ static FORCE_INLINE execute_status write_virtual_memory(STATE_ACCESS a, uint64_t
     const uint64_t slot_vaddr_page = a.template read_tlb_vaddr_page<TLB_WRITE>(slot_index);
     if (unlikely(!tlb_is_hit<T>(slot_vaddr_page, vaddr))) {
         // Outline the slow path into a function call to minimize host CPU code cache pressure
-        INC_COUNTER(a.get_statistics(), tlb_wmiss);
+        DUMP_STATS_INCR(a, "tlb.wmiss");
         auto [status, new_pc] = write_virtual_memory_slow<T>(a, pc, mcycle, vaddr, val64);
         pc = new_pc;
         return status;
@@ -1097,30 +1135,29 @@ static FORCE_INLINE execute_status write_virtual_memory(STATE_ACCESS a, uint64_t
     const auto vp_offset = a.template read_tlb_vp_offset<TLB_WRITE>(slot_index);
     const auto faddr = vaddr + vp_offset;
     a.template write_memory_word<T>(faddr, pma_index, static_cast<T>(val64));
-    INC_COUNTER(a.get_statistics(), tlb_whit);
+    DUMP_STATS_INCR(a, "tlb.whit");
     return execute_status::success;
 }
 
 template <typename STATE_ACCESS>
-static void dump_insn([[maybe_unused]] STATE_ACCESS a, [[maybe_unused]] uint64_t pc, [[maybe_unused]] uint32_t insn,
+static auto dump_insn([[maybe_unused]] STATE_ACCESS a, [[maybe_unused]] uint64_t pc, [[maybe_unused]] uint32_t insn,
     [[maybe_unused]] const char *name) {
-    [[maybe_unused]] auto note = a.make_scoped_note("dump_insn");
-#ifdef DUMP_HIST
-    a.get_naked_state().insn_hist[name]++;
-#endif
+    DUMP_INSN_HIST_INCR(a, name);
 #ifdef DUMP_REGS
     dump_regs(a.get_naked_state());
 #endif
 #ifdef DUMP_INSN
+    [[maybe_unused]] auto note = a.make_scoped_note("dump_insn");
     uint64_t ppc = pc;
     if (!translate_virtual_address<STATE_ACCESS, false>(a, &ppc, pc, PTE_XWR_X_SHIFT)) {
-        fprintf(stderr, "v    %08" PRIx64, ppc);
+        D_PRINTF("v    %08" PRIx64, ppc);
     } else {
-        fprintf(stderr, "p    %08" PRIx64, ppc);
+        D_PRINTF("p    %08" PRIx64, ppc);
     }
-    fprintf(stderr, ":   %08" PRIx32 "   ", insn);
-    fprintf(stderr, "%s\n", name);
+    D_PRINTF(":   %08" PRIx32 "   ", insn);
+    D_PRINTF("%s\n", name);
 #endif
+    return a.make_scoped_note(name);
 }
 
 /// \brief Raises an illegal instruction exception, updating the pc.
@@ -1241,14 +1278,14 @@ static FORCE_INLINE execute_status execute_LR_W(STATE_ACCESS a, uint64_t &pc, ui
     if (unlikely((insn & 0b00000001111100000000000000000000) != 0)) {
         return raise_illegal_insn_exception(a, pc, insn);
     }
-    dump_insn(a, pc, insn, "lr.w");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "lr.w");
     return execute_LR<int32_t>(a, pc, mcycle, insn);
 }
 
 /// \brief Implementation of the SC.W instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_SC_W(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "sc.w");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sc.w");
     return execute_SC<int32_t>(a, pc, mcycle, insn);
 }
 
@@ -1279,14 +1316,14 @@ static FORCE_INLINE execute_status execute_AMO(STATE_ACCESS a, uint64_t &pc, uin
 /// \brief Implementation of the AMOSWAP.W instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_AMOSWAP_W(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "amoswap.w");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amoswap.w");
     return execute_AMO<int32_t>(a, pc, mcycle, insn, [](int32_t /*valm*/, int32_t valr) -> int32_t { return valr; });
 }
 
 /// \brief Implementation of the AMOADD.W instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_AMOADD_W(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "amoadd.w");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amoadd.w");
     return execute_AMO<int32_t>(a, pc, mcycle, insn, [](int32_t valm, int32_t valr) -> int32_t {
         int32_t val = 0;
         __builtin_add_overflow(valm, valr, &val);
@@ -1296,28 +1333,28 @@ static FORCE_INLINE execute_status execute_AMOADD_W(STATE_ACCESS a, uint64_t &pc
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_AMOXOR_W(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "amoxor.w");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amoxor.w");
     return execute_AMO<int32_t>(a, pc, mcycle, insn, [](int32_t valm, int32_t valr) -> int32_t { return valm ^ valr; });
 }
 
 /// \brief Implementation of the AMOAND.W instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_AMOAND_W(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "amoand.w");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amoand.w");
     return execute_AMO<int32_t>(a, pc, mcycle, insn, [](int32_t valm, int32_t valr) -> int32_t { return valm & valr; });
 }
 
 /// \brief Implementation of the AMOOR.W instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_AMOOR_W(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "amoor.w");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amoor.w");
     return execute_AMO<int32_t>(a, pc, mcycle, insn, [](int32_t valm, int32_t valr) -> int32_t { return valm | valr; });
 }
 
 /// \brief Implementation of the AMOMIN.W instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_AMOMIN_W(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "amomin.w");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amomin.w");
     return execute_AMO<int32_t>(a, pc, mcycle, insn, [](int32_t valm, int32_t valr) -> int32_t {
         if (valm < valr) {
             return valm;
@@ -1329,7 +1366,7 @@ static FORCE_INLINE execute_status execute_AMOMIN_W(STATE_ACCESS a, uint64_t &pc
 /// \brief Implementation of the AMOMAX.W instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_AMOMAX_W(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "amomax.w");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amomax.w");
     return execute_AMO<int32_t>(a, pc, mcycle, insn, [](int32_t valm, int32_t valr) -> int32_t {
         if (valm > valr) {
             return valm;
@@ -1341,7 +1378,7 @@ static FORCE_INLINE execute_status execute_AMOMAX_W(STATE_ACCESS a, uint64_t &pc
 /// \brief Implementation of the AMOMINU.W instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_AMOMINU_W(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "amominu.w");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amominu.w");
     return execute_AMO<int32_t>(a, pc, mcycle, insn, [](int32_t valm, int32_t valr) -> int32_t {
         if (static_cast<uint32_t>(valm) < static_cast<uint32_t>(valr)) {
             return valm;
@@ -1353,7 +1390,7 @@ static FORCE_INLINE execute_status execute_AMOMINU_W(STATE_ACCESS a, uint64_t &p
 /// \brief Implementation of the AMOMAXU.W instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_AMOMAXU_W(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "amomaxu.w");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amomaxu.w");
     return execute_AMO<int32_t>(a, pc, mcycle, insn, [](int32_t valm, int32_t valr) -> int32_t {
         if (static_cast<uint32_t>(valm) > static_cast<uint32_t>(valr)) {
             return valm;
@@ -1368,28 +1405,28 @@ static FORCE_INLINE execute_status execute_LR_D(STATE_ACCESS a, uint64_t &pc, ui
     if (unlikely((insn & 0b00000001111100000000000000000000) != 0)) {
         return raise_illegal_insn_exception(a, pc, insn);
     }
-    dump_insn(a, pc, insn, "lr.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "lr.d");
     return execute_LR<uint64_t>(a, pc, mcycle, insn);
 }
 
 /// \brief Implementation of the SC.D instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_SC_D(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "sc.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sc.d");
     return execute_SC<uint64_t>(a, pc, mcycle, insn);
 }
 
 /// \brief Implementation of the AMOSWAP.D instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_AMOSWAP_D(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "amoswap.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amoswap.d");
     return execute_AMO<int64_t>(a, pc, mcycle, insn, [](int64_t /*valm*/, int64_t valr) -> int64_t { return valr; });
 }
 
 /// \brief Implementation of the AMOADD.D instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_AMOADD_D(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "amoadd.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amoadd.d");
     return execute_AMO<int64_t>(a, pc, mcycle, insn, [](int64_t valm, int64_t valr) -> int64_t {
         int64_t val = 0;
         __builtin_add_overflow(valm, valr, &val);
@@ -1399,28 +1436,28 @@ static FORCE_INLINE execute_status execute_AMOADD_D(STATE_ACCESS a, uint64_t &pc
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_AMOXOR_D(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "amoxor.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amoxor.d");
     return execute_AMO<int64_t>(a, pc, mcycle, insn, [](int64_t valm, int64_t valr) -> int64_t { return valm ^ valr; });
 }
 
 /// \brief Implementation of the AMOAND.D instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_AMOAND_D(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "amoand.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amoand.d");
     return execute_AMO<int64_t>(a, pc, mcycle, insn, [](int64_t valm, int64_t valr) -> int64_t { return valm & valr; });
 }
 
 /// \brief Implementation of the AMOOR.D instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_AMOOR_D(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "amoor.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amoor.d");
     return execute_AMO<int64_t>(a, pc, mcycle, insn, [](int64_t valm, int64_t valr) -> int64_t { return valm | valr; });
 }
 
 /// \brief Implementation of the AMOMIN.D instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_AMOMIN_D(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "amomin.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amomin.d");
     return execute_AMO<int64_t>(a, pc, mcycle, insn, [](int64_t valm, int64_t valr) -> int64_t {
         if (valm < valr) {
             return valm;
@@ -1432,7 +1469,7 @@ static FORCE_INLINE execute_status execute_AMOMIN_D(STATE_ACCESS a, uint64_t &pc
 /// \brief Implementation of the AMOMAX.D instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_AMOMAX_D(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "amomax.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amomax.d");
     return execute_AMO<int64_t>(a, pc, mcycle, insn, [](int64_t valm, int64_t valr) -> int64_t {
         if (valm > valr) {
             return valm;
@@ -1444,7 +1481,7 @@ static FORCE_INLINE execute_status execute_AMOMAX_D(STATE_ACCESS a, uint64_t &pc
 /// \brief Implementation of the AMOMINU.D instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_AMOMINU_D(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "amominu.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amominu.d");
     return execute_AMO<uint64_t>(a, pc, mcycle, insn, [](uint64_t valm, uint64_t valr) -> uint64_t {
         if (valm < valr) {
             return valm;
@@ -1456,7 +1493,7 @@ static FORCE_INLINE execute_status execute_AMOMINU_D(STATE_ACCESS a, uint64_t &p
 /// \brief Implementation of the AMOMAXU.D instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_AMOMAXU_D(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "amomaxu.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amomaxu.d");
     return execute_AMO<uint64_t>(a, pc, mcycle, insn, [](uint64_t valm, uint64_t valr) -> uint64_t {
         if (valm > valr) {
             return valm;
@@ -1468,7 +1505,7 @@ static FORCE_INLINE execute_status execute_AMOMAXU_D(STATE_ACCESS a, uint64_t &p
 /// \brief Implementation of the ADDW instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_ADDW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "addw");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "addw");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -1485,7 +1522,7 @@ static FORCE_INLINE execute_status execute_ADDW(STATE_ACCESS a, uint64_t &pc, ui
 /// \brief Implementation of the SUBW instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_SUBW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "subw");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "subw");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -1505,7 +1542,7 @@ static FORCE_INLINE execute_status execute_SLLW(STATE_ACCESS a, uint64_t &pc, ui
     if (unlikely((insn & 0b11111110000000000111000001111111) != 0b00000000000000000001000000111011)) {
         return raise_illegal_insn_exception(a, pc, insn);
     }
-    dump_insn(a, pc, insn, "sllw");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sllw");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -1518,7 +1555,7 @@ static FORCE_INLINE execute_status execute_SLLW(STATE_ACCESS a, uint64_t &pc, ui
 /// \brief Implementation of the SRLW instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_SRLW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "srlw");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "srlw");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -1531,7 +1568,7 @@ static FORCE_INLINE execute_status execute_SRLW(STATE_ACCESS a, uint64_t &pc, ui
 /// \brief Implementation of the SRAW instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_SRAW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "sraw");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sraw");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -1544,7 +1581,7 @@ static FORCE_INLINE execute_status execute_SRAW(STATE_ACCESS a, uint64_t &pc, ui
 /// \brief Implementation of the MULW instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_MULW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "mulw");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "mulw");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -1563,7 +1600,7 @@ static FORCE_INLINE execute_status execute_DIVW(STATE_ACCESS a, uint64_t &pc, ui
     if (unlikely((insn & 0b11111110000000000111000001111111) != 0b00000010000000000100000000111011)) {
         return raise_illegal_insn_exception(a, pc, insn);
     }
-    dump_insn(a, pc, insn, "divw");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "divw");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -1583,7 +1620,7 @@ static FORCE_INLINE execute_status execute_DIVW(STATE_ACCESS a, uint64_t &pc, ui
 /// \brief Implementation of the DIVUW instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_DIVUW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "divuw");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "divuw");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -1603,7 +1640,7 @@ static FORCE_INLINE execute_status execute_REMW(STATE_ACCESS a, uint64_t &pc, ui
     if (unlikely((insn & 0b11111110000000000111000001111111) != 0b00000010000000000110000000111011)) {
         return raise_illegal_insn_exception(a, pc, insn);
     }
-    dump_insn(a, pc, insn, "remw");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "remw");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -1626,7 +1663,7 @@ static FORCE_INLINE execute_status execute_REMUW(STATE_ACCESS a, uint64_t &pc, u
     if (unlikely((insn & 0b11111110000000000111000001111111) != 0b00000010000000000111000000111011)) {
         return raise_illegal_insn_exception(a, pc, insn);
     }
-    dump_insn(a, pc, insn, "remuw");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "remuw");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -2038,7 +2075,7 @@ static NO_INLINE uint64_t read_csr(STATE_ACCESS a, uint64_t mcycle, CSR_address
         default:
             // Invalid CSRs
 #ifdef DUMP_INVALID_CSR
-            fprintf(stderr, "csr_read: invalid CSR=0x%x\n", static_cast<int>(csraddr));
+            D_PRINTF("csr_read: invalid CSR=0x%x\n", static_cast<int>(csraddr));
 #endif
             return read_csr_fail(status);
     }
@@ -2144,10 +2181,12 @@ static NO_INLINE execute_status write_csr_satp(STATE_ACCESS a, uint64_t val) {
     }
     a.write_satp(stap);
 
-#ifdef DUMP_COUNTERS
-    uint64_t asid = (stap & SATP_ASID_MASK) >> SATP_ASID_SHIFT;
-    if (asid != ASID_MAX_MASK) { // Software is not testing ASID bits
-        a.get_statistics().max_asid = std::max(a.get_statistics().max_asid, asid);
+#ifdef DUMP_STATS
+    if constexpr (is_an_i_counters_v<STATE_ACCESS>) {
+        const uint64_t asid = (stap & SATP_ASID_MASK) >> SATP_ASID_SHIFT;
+        if (asid != ASID_MAX_MASK) { // Software is not testing ASID bits
+            a.write_counter(std::max(a.read_counter("stats.max_asid"), asid), "stats.max_asid");
+        }
     }
 #endif
 
@@ -2157,8 +2196,8 @@ static NO_INLINE execute_status write_csr_satp(STATE_ACCESS a, uint64_t val) {
     const uint64_t mod = old_satp ^ stap;
     if (mod & (SATP_ASID_MASK | SATP_MODE_MASK)) {
         flush_all_tlb(a);
-        INC_COUNTER(a.get_statistics(), tlb_flush_all);
-        INC_COUNTER(a.get_statistics(), tlb_flush_satp);
+        DUMP_STATS_INCR(a, "tlb.flush_all");
+        DUMP_STATS_INCR(a, "tlb.flush_satp");
         return execute_status::success_and_flush_fetch;
     }
     return execute_status::success;
@@ -2219,14 +2258,14 @@ static NO_INLINE execute_status write_csr_mstatus(STATE_ACCESS a, uint64_t val)
     // Flush TLBs when needed
     if (flush_tlb_read) {
         flush_tlb_set<TLB_READ>(a);
-        INC_COUNTER(a.get_statistics(), tlb_flush_read);
+        DUMP_STATS_INCR(a, "tlb.flush_read");
     }
     if (flush_tlb_write) {
         flush_tlb_set<TLB_WRITE>(a);
-        INC_COUNTER(a.get_statistics(), tlb_flush_write);
+        DUMP_STATS_INCR(a, "tlb.flush_write");
     }
     if (flush_tlb_read || flush_tlb_write) {
-        INC_COUNTER(a.get_statistics(), tlb_flush_mstatus);
+        DUMP_STATS_INCR(a, "tlb.flush_mstatus");
     }
 
     // When changing an interrupt enabled bit, we may have to service any pending interrupt
@@ -2384,9 +2423,9 @@ static inline execute_status write_csr_fcsr(STATE_ACCESS a, uint64_t val) {
 template <typename STATE_ACCESS>
 static NO_INLINE execute_status write_csr(STATE_ACCESS a, uint64_t mcycle, CSR_address csraddr, uint64_t val) {
 #if defined(DUMP_CSR)
-    fprintf(stderr, "csr_write: csr=0x%03x val=0x", static_cast<int>(csraddr));
+    D_PRINTF("csr_write: csr=0x%03x val=0x", static_cast<int>(csraddr));
     print_uint64_t(val);
-    fprintf(stderr, "\n");
+    D_PRINTF("\n");
 #endif
     if (unlikely(csr_is_read_only(csraddr))) {
         return execute_status::failure;
@@ -2529,7 +2568,7 @@ static NO_INLINE execute_status write_csr(STATE_ACCESS a, uint64_t mcycle, CSR_a
         default:
             // Invalid CSRs
 #ifdef DUMP_INVALID_CSR
-            fprintf(stderr, "csr_write: invalid CSR=0x%x\n", static_cast<int>(csraddr));
+            D_PRINTF("csr_write: invalid CSR=0x%x\n", static_cast<int>(csraddr));
 #endif
             return execute_status::failure;
     }
@@ -2570,7 +2609,7 @@ static FORCE_INLINE execute_status execute_csr_RW(STATE_ACCESS a, uint64_t &pc,
 /// \brief Implementation of the CSRRW instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_CSRRW(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "csrrw");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "csrrw");
     return execute_csr_RW(a, pc, mcycle, insn,
         [](STATE_ACCESS a, uint32_t insn) -> uint64_t { return a.read_x(insn_get_rs1(insn)); });
 }
@@ -2578,7 +2617,7 @@ static FORCE_INLINE execute_status execute_CSRRW(STATE_ACCESS a, uint64_t &pc, u
 /// \brief Implementation of the CSRRWI instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_CSRRWI(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "csrrwi");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "csrrwi");
     return execute_csr_RW(a, pc, mcycle, insn,
         [](STATE_ACCESS, uint32_t insn) -> uint64_t { return static_cast<uint64_t>(insn_get_rs1(insn)); });
 }
@@ -2620,14 +2659,14 @@ static FORCE_INLINE execute_status execute_csr_SC(STATE_ACCESS a, uint64_t &pc,
 /// \brief Implementation of the CSRRS instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_CSRRS(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "csrrs");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "csrrs");
     return execute_csr_SC(a, pc, mcycle, insn, [](uint64_t csr, uint64_t rs1) -> uint64_t { return csr | rs1; });
 }
 
 /// \brief Implementation of the CSRRC instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_CSRRC(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "csrrc");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "csrrc");
     return execute_csr_SC(a, pc, mcycle, insn, [](uint64_t csr, uint64_t rs1) -> uint64_t { return csr & ~rs1; });
 }
 
@@ -2665,21 +2704,21 @@ static FORCE_INLINE execute_status execute_csr_SCI(STATE_ACCESS a, uint64_t &pc,
 /// \brief Implementation of the CSRRSI instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_CSRRSI(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "csrrsi");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "csrrsi");
     return execute_csr_SCI(a, pc, mcycle, insn, [](uint64_t csr, uint32_t rs1) -> uint64_t { return csr | rs1; });
 }
 
 /// \brief Implementation of the CSRRCI instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_CSRRCI(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "csrrci");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "csrrci");
     return execute_csr_SCI(a, pc, mcycle, insn, [](uint64_t csr, uint32_t rs1) -> uint64_t { return csr & ~rs1; });
 }
 
 /// \brief Implementation of the ECALL instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_ECALL(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "ecall");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "ecall");
     auto prv = a.read_iprv();
     pc = raise_exception(a, pc, MCAUSE_ECALL_BASE + prv, 0);
     return execute_status::failure;
@@ -2688,7 +2727,7 @@ static FORCE_INLINE execute_status execute_ECALL(STATE_ACCESS a, uint64_t &pc, u
 /// \brief Implementation of the EBREAK instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_EBREAK(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "ebreak");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "ebreak");
     pc = raise_exception(a, pc, MCAUSE_BREAKPOINT, pc);
     return execute_status::failure;
 }
@@ -2696,7 +2735,7 @@ static FORCE_INLINE execute_status execute_EBREAK(STATE_ACCESS a, uint64_t &pc,
 /// \brief Implementation of the SRET instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_SRET(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "sret");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sret");
     auto prv = a.read_iprv();
     uint64_t mstatus = a.read_mstatus();
     if (unlikely(prv < PRV_S || (prv == PRV_S && (mstatus & MSTATUS_TSR_MASK)))) {
@@ -2726,7 +2765,7 @@ static FORCE_INLINE execute_status execute_SRET(STATE_ACCESS a, uint64_t &pc, ui
 /// \brief Implementation of the MRET instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_MRET(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "mret");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "mret");
     auto prv = a.read_iprv();
     if (unlikely(prv < PRV_M)) {
         return raise_illegal_insn_exception(a, pc, insn);
@@ -2758,7 +2797,7 @@ static FORCE_INLINE execute_status execute_MRET(STATE_ACCESS a, uint64_t &pc, ui
 /// \details This function is outlined to minimize host CPU code cache pressure.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_WFI(STATE_ACCESS a, uint64_t &pc, uint64_t &mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "wfi");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "wfi");
     auto status = execute_status::success;
     // Check privileges and do nothing else
     auto prv = a.read_iprv();
@@ -2782,8 +2821,8 @@ static FORCE_INLINE execute_status execute_WFI(STATE_ACCESS a, uint64_t &pc, uin
 /// \brief Implementation of the FENCE instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FENCE(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    INC_COUNTER(a.get_statistics(), fence);
-    dump_insn(a, pc, insn, "fence");
+    DUMP_STATS_INCR(a, "fence");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fence");
     // Really do nothing
     return advance_to_next_insn(a, pc);
 }
@@ -2791,8 +2830,8 @@ static FORCE_INLINE execute_status execute_FENCE(STATE_ACCESS a, uint64_t &pc, u
 /// \brief Implementation of the FENCE.I instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FENCE_I(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    INC_COUNTER(a.get_statistics(), fence_i);
-    dump_insn(a, pc, insn, "fence.i");
+    DUMP_STATS_INCR(a, "fence.i");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fence.i");
     // Really do nothing
     return advance_to_next_insn(a, pc);
 }
@@ -2812,7 +2851,7 @@ static FORCE_INLINE execute_status execute_arithmetic(STATE_ACCESS a, uint64_t &
 /// \brief Implementation of the ADD instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_ADD(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "add");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "add");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -2826,7 +2865,7 @@ static FORCE_INLINE execute_status execute_ADD(STATE_ACCESS a, uint64_t &pc, uin
 /// \brief Implementation of the SUB instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_SUB(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "sub");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sub");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -2840,7 +2879,7 @@ static FORCE_INLINE execute_status execute_SUB(STATE_ACCESS a, uint64_t &pc, uin
 /// \brief Implementation of the SLL instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_SLL(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "sll");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sll");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -2851,7 +2890,7 @@ static FORCE_INLINE execute_status execute_SLL(STATE_ACCESS a, uint64_t &pc, uin
 /// \brief Implementation of the SLT instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_SLT(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "slt");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "slt");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -2862,7 +2901,7 @@ static FORCE_INLINE execute_status execute_SLT(STATE_ACCESS a, uint64_t &pc, uin
 /// \brief Implementation of the SLTU instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_SLTU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "sltu");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sltu");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -2872,7 +2911,7 @@ static FORCE_INLINE execute_status execute_SLTU(STATE_ACCESS a, uint64_t &pc, ui
 /// \brief Implementation of the XOR instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_XOR(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "xor");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "xor");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -2882,7 +2921,7 @@ static FORCE_INLINE execute_status execute_XOR(STATE_ACCESS a, uint64_t &pc, uin
 /// \brief Implementation of the SRL instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_SRL(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "srl");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "srl");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -2893,7 +2932,7 @@ static FORCE_INLINE execute_status execute_SRL(STATE_ACCESS a, uint64_t &pc, uin
 /// \brief Implementation of the SRA instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_SRA(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "sra");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sra");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -2905,7 +2944,7 @@ static FORCE_INLINE execute_status execute_SRA(STATE_ACCESS a, uint64_t &pc, uin
 /// \brief Implementation of the OR instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_OR(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "or");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "or");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -2915,7 +2954,7 @@ static FORCE_INLINE execute_status execute_OR(STATE_ACCESS a, uint64_t &pc, uint
 /// \brief Implementation of the AND instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_AND(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "and");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "and");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -2925,7 +2964,7 @@ static FORCE_INLINE execute_status execute_AND(STATE_ACCESS a, uint64_t &pc, uin
 /// \brief Implementation of the MUL instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_MUL(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "mul");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "mul");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -2941,7 +2980,7 @@ static FORCE_INLINE execute_status execute_MUL(STATE_ACCESS a, uint64_t &pc, uin
 /// \brief Implementation of the MULH instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_MULH(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "mulh");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "mulh");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -2955,7 +2994,7 @@ static FORCE_INLINE execute_status execute_MULH(STATE_ACCESS a, uint64_t &pc, ui
 /// \brief Implementation of the MULHSU instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_MULHSU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "mulhsu");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "mulhsu");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -2969,7 +3008,7 @@ static FORCE_INLINE execute_status execute_MULHSU(STATE_ACCESS a, uint64_t &pc,
 /// \brief Implementation of the MULHU instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_MULHU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "mulhu");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "mulhu");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -2981,7 +3020,7 @@ static FORCE_INLINE execute_status execute_MULHU(STATE_ACCESS a, uint64_t &pc, u
 /// \brief Implementation of the DIV instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_DIV(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "div");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "div");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -3001,7 +3040,7 @@ static FORCE_INLINE execute_status execute_DIV(STATE_ACCESS a, uint64_t &pc, uin
 /// \brief Implementation of the DIVU instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_DIVU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "divu");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "divu");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -3016,7 +3055,7 @@ static FORCE_INLINE execute_status execute_DIVU(STATE_ACCESS a, uint64_t &pc, ui
 /// \brief Implementation of the REM instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_REM(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "rem");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "rem");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -3036,7 +3075,7 @@ static FORCE_INLINE execute_status execute_REM(STATE_ACCESS a, uint64_t &pc, uin
 /// \brief Implementation of the REMU instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_REMU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "remu");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "remu");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -3061,7 +3100,7 @@ static FORCE_INLINE execute_status execute_arithmetic_immediate(STATE_ACCESS a,
 /// \brief Implementation of the SRLI instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_SRLI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "srli");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "srli");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -3072,7 +3111,7 @@ static FORCE_INLINE execute_status execute_SRLI(STATE_ACCESS a, uint64_t &pc, ui
 /// \brief Implementation of the SRAI instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_SRAI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "srai");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "srai");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -3084,7 +3123,7 @@ static FORCE_INLINE execute_status execute_SRAI(STATE_ACCESS a, uint64_t &pc, ui
 /// \brief Implementation of the ADDI instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_ADDI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "addi");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "addi");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -3098,7 +3137,7 @@ static FORCE_INLINE execute_status execute_ADDI(STATE_ACCESS a, uint64_t &pc, ui
 /// \brief Implementation of the SLTI instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_SLTI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "slti");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "slti");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -3109,7 +3148,7 @@ static FORCE_INLINE execute_status execute_SLTI(STATE_ACCESS a, uint64_t &pc, ui
 /// \brief Implementation of the SLTIU instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_SLTIU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "sltiu");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sltiu");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -3120,7 +3159,7 @@ static FORCE_INLINE execute_status execute_SLTIU(STATE_ACCESS a, uint64_t &pc, u
 /// \brief Implementation of the XORI instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_XORI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "xori");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "xori");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -3130,7 +3169,7 @@ static FORCE_INLINE execute_status execute_XORI(STATE_ACCESS a, uint64_t &pc, ui
 /// \brief Implementation of the ORI instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_ORI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "ori");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "ori");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -3140,7 +3179,7 @@ static FORCE_INLINE execute_status execute_ORI(STATE_ACCESS a, uint64_t &pc, uin
 /// \brief Implementation of the ANDI instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_ANDI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "andi");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "andi");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -3153,7 +3192,7 @@ static FORCE_INLINE execute_status execute_SLLI(STATE_ACCESS a, uint64_t &pc, ui
     if (unlikely((insn & (0b111111 << 26)) != 0)) {
         return raise_illegal_insn_exception(a, pc, insn);
     }
-    dump_insn(a, pc, insn, "slli");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "slli");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -3167,7 +3206,7 @@ static FORCE_INLINE execute_status execute_SLLI(STATE_ACCESS a, uint64_t &pc, ui
 /// \brief Implementation of the ADDIW instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_ADDIW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "addiw");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "addiw");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -3184,7 +3223,7 @@ static FORCE_INLINE execute_status execute_SLLIW(STATE_ACCESS a, uint64_t &pc, u
     if (unlikely(insn_get_funct7(insn) != 0)) {
         return raise_illegal_insn_exception(a, pc, insn);
     }
-    dump_insn(a, pc, insn, "slliw");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "slliw");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -3199,7 +3238,7 @@ static FORCE_INLINE execute_status execute_SLLIW(STATE_ACCESS a, uint64_t &pc, u
 /// \brief Implementation of the SRLIW instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_SRLIW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "srliw");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "srliw");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -3214,11 +3253,11 @@ static FORCE_INLINE execute_status execute_SRLIW(STATE_ACCESS a, uint64_t &pc, u
 /// \brief Implementation of the SRAIW instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_SRAIW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "sraiw");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sraiw");
     // When rd=0 the instruction is a HINT, and we consider it as a soft yield when rs1 == 31
     if constexpr (rd_kind == rd_kind::x0) {
         if constexpr (is_an_i_interactive_state_access_v<STATE_ACCESS>) {
-            if (unlikely(insn_get_rd(insn) == 0 && insn_get_rs1(insn) == 31 && a.get_soft_yield())) {
+            if ((insn_get_rs1(insn) == 31) && a.get_soft_yield()) {
                 // Force the main interpreter loop to break
                 return advance_to_next_insn(a, pc, execute_status::success_and_yield);
             }
@@ -3249,28 +3288,28 @@ static FORCE_INLINE execute_status execute_S(STATE_ACCESS a, uint64_t &pc, uint6
 /// \brief Implementation of the SB instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_SB(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "sb");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sb");
     return execute_S<uint8_t>(a, pc, mcycle, insn);
 }
 
 /// \brief Implementation of the SH instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_SH(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "sh");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sh");
     return execute_S<uint16_t>(a, pc, mcycle, insn);
 }
 
 /// \brief Implementation of the SW instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_SW(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "sw");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sw");
     return execute_S<uint32_t>(a, pc, mcycle, insn);
 }
 
 /// \brief Implementation of the SD instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_SD(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "sd");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sd");
     return execute_S<uint64_t>(a, pc, mcycle, insn);
 }
 
@@ -3299,49 +3338,49 @@ static FORCE_INLINE execute_status execute_L(STATE_ACCESS a, uint64_t &pc, uint6
 /// \brief Implementation of the LB instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_LB(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "lb");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "lb");
     return execute_L<int8_t, rd_kind>(a, pc, mcycle, insn);
 }
 
 /// \brief Implementation of the LH instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_LH(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "lh");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "lh");
     return execute_L<int16_t, rd_kind>(a, pc, mcycle, insn);
 }
 
 /// \brief Implementation of the LW instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_LW(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "lw");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "lw");
     return execute_L<int32_t, rd_kind>(a, pc, mcycle, insn);
 }
 
 /// \brief Implementation of the LD instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_LD(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "ld");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "ld");
     return execute_L<int64_t, rd_kind>(a, pc, mcycle, insn);
 }
 
 /// \brief Implementation of the LBU instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_LBU(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "lbu");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "lbu");
     return execute_L<uint8_t, rd_kind>(a, pc, mcycle, insn);
 }
 
 /// \brief Implementation of the LHU instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_LHU(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "lhu");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "lhu");
     return execute_L<uint16_t, rd_kind>(a, pc, mcycle, insn);
 }
 
 /// \brief Implementation of the LWU instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_LWU(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "lwu");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "lwu");
     return execute_L<uint32_t, rd_kind>(a, pc, mcycle, insn);
 }
 
@@ -3359,21 +3398,21 @@ static FORCE_INLINE execute_status execute_branch(STATE_ACCESS a, uint64_t &pc,
 /// \brief Implementation of the BEQ instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_BEQ(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "beq");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "beq");
     return execute_branch(a, pc, insn, [](uint64_t rs1, uint64_t rs2) -> bool { return rs1 == rs2; });
 }
 
 /// \brief Implementation of the BNE instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_BNE(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "bne");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "bne");
     return execute_branch(a, pc, insn, [](uint64_t rs1, uint64_t rs2) -> bool { return rs1 != rs2; });
 }
 
 /// \brief Implementation of the BLT instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_BLT(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "blt");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "blt");
     return execute_branch(a, pc, insn,
         [](uint64_t rs1, uint64_t rs2) -> bool { return static_cast<int64_t>(rs1) < static_cast<int64_t>(rs2); });
 }
@@ -3381,7 +3420,7 @@ static FORCE_INLINE execute_status execute_BLT(STATE_ACCESS a, uint64_t &pc, uin
 /// \brief Implementation of the BGE instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_BGE(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "bge");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "bge");
     return execute_branch(a, pc, insn,
         [](uint64_t rs1, uint64_t rs2) -> bool { return static_cast<int64_t>(rs1) >= static_cast<int64_t>(rs2); });
 }
@@ -3389,21 +3428,21 @@ static FORCE_INLINE execute_status execute_BGE(STATE_ACCESS a, uint64_t &pc, uin
 /// \brief Implementation of the BLTU instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_BLTU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "bltu");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "bltu");
     return execute_branch(a, pc, insn, [](uint64_t rs1, uint64_t rs2) -> bool { return rs1 < rs2; });
 }
 
 /// \brief Implementation of the BGEU instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_BGEU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "bgeu");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "bgeu");
     return execute_branch(a, pc, insn, [](uint64_t rs1, uint64_t rs2) -> bool { return rs1 >= rs2; });
 }
 
 /// \brief Implementation of the LUI instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_LUI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "lui");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "lui");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -3415,7 +3454,7 @@ static FORCE_INLINE execute_status execute_LUI(STATE_ACCESS a, uint64_t &pc, uin
 /// \brief Implementation of the AUIPC instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_AUIPC(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "auipc");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "auipc");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
@@ -3427,7 +3466,7 @@ static FORCE_INLINE execute_status execute_AUIPC(STATE_ACCESS a, uint64_t &pc, u
 /// \brief Implementation of the JAL instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_JAL(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "jal");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "jal");
     const uint64_t new_pc = pc + insn_J_get_imm(insn);
     if constexpr (rd_kind == rd_kind::x0) {
         return execute_jump(a, pc, new_pc);
@@ -3440,7 +3479,7 @@ static FORCE_INLINE execute_status execute_JAL(STATE_ACCESS a, uint64_t &pc, uin
 /// \brief Implementation of the JALR instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_JALR(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "jalr");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "jalr");
     const uint64_t val = pc + 4;
     const uint64_t new_pc =
         static_cast<int64_t>(a.read_x(insn_get_rs1(insn)) + insn_I_get_imm(insn)) & ~static_cast<uint64_t>(1);
@@ -3460,8 +3499,8 @@ static FORCE_INLINE execute_status execute_SFENCE_VMA(STATE_ACCESS a, uint64_t &
     if (unlikely((insn & 0b11111110000000000111111111111111) != 0b00010010000000000000000001110011)) {
         return raise_illegal_insn_exception(a, pc, insn);
     }
-    INC_COUNTER(a.get_statistics(), fence_vma);
-    dump_insn(a, pc, insn, "sfence.vma");
+    DUMP_STATS_INCR(a, "fence_vma");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sfence.vma");
     auto prv = a.read_iprv();
     const uint64_t mstatus = a.read_mstatus();
 
@@ -3474,33 +3513,33 @@ static FORCE_INLINE execute_status execute_SFENCE_VMA(STATE_ACCESS a, uint64_t &
     [[maybe_unused]] const uint32_t rs2 = insn_get_rs2(insn);
     if (rs1 == 0) {
         flush_all_tlb(a);
-#ifdef DUMP_COUNTERS
-        INC_COUNTER(a.get_statistics(), tlb_flush_all);
+#ifdef DUMP_STATS
+        DUMP_STATS_INCR(a, "tlb.flush_all");
         if (rs2 == 0) {
             // Invalidates all address-translation cache entries, for all address spaces
-            INC_COUNTER(a.get_statistics(), tlb_flush_fence_vma_all);
+            DUMP_STATS_INCR(a, "tlb.flush_fence_vma_all");
         } else {
             // Invalidates all address-translation cache entries matching the
             // address space identified by integer register rs2,
             // except for entries containing global mappings.
-            INC_COUNTER(a.get_statistics(), tlb_flush_fence_vma_asid);
+            DUMP_STATS_INCR(a, "tlb.flush_fence_vma_asid");
         }
 #endif
     } else {
         const uint64_t vaddr = a.read_x(rs1);
         flush_tlb_vaddr(a, vaddr);
-#ifdef DUMP_COUNTERS
-        INC_COUNTER(a.get_statistics(), tlb_flush_vaddr);
+#ifdef DUMP_STATS
+        DUMP_STATS_INCR(a, "tlb.flush_vaddr");
         if (rs2 == 0) {
             // Invalidates all address-translation cache entries that contain leaf page table entries
             // corresponding to the virtual address in rs1, for all address spaces.
-            INC_COUNTER(a.get_statistics(), tlb_flush_fence_vma_vaddr);
+            DUMP_STATS_INCR(a, "tlb.flush_fence_vma_vaddr");
         } else {
             // Invalidates all address-translation cache entries that contain leaf page table entries
             // corresponding to the virtual address in rs1
             // and that match the address space identified by integer register rs2,
             // except for entries containing global mappings.
-            INC_COUNTER(a.get_statistics(), tlb_flush_fence_vma_asid_vaddr);
+            DUMP_STATS_INCR(a, "tlb.flush_fence_vma_asid_vaddr");
         }
 #endif
     }
@@ -3879,7 +3918,7 @@ static FORCE_INLINE execute_status execute_FS(STATE_ACCESS a, uint64_t &pc, uint
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FSW(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "fsw");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fsw");
     // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((a.read_mstatus() & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
         return raise_illegal_insn_exception(a, pc, insn);
@@ -3889,7 +3928,7 @@ static FORCE_INLINE execute_status execute_FSW(STATE_ACCESS a, uint64_t &pc, uin
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FSD(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "fsd");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fsd");
     // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((a.read_mstatus() & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
         return raise_illegal_insn_exception(a, pc, insn);
@@ -3915,7 +3954,7 @@ static FORCE_INLINE execute_status execute_FL(STATE_ACCESS a, uint64_t &pc, uint
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FLW(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "flw");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "flw");
     // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((a.read_mstatus() & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
         return raise_illegal_insn_exception(a, pc, insn);
@@ -3925,7 +3964,7 @@ static FORCE_INLINE execute_status execute_FLW(STATE_ACCESS a, uint64_t &pc, uin
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FLD(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, insn, "fld");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fld");
     // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((a.read_mstatus() & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
         return raise_illegal_insn_exception(a, pc, insn);
@@ -3935,7 +3974,7 @@ static FORCE_INLINE execute_status execute_FLD(STATE_ACCESS a, uint64_t &pc, uin
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FMADD_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fmadd.s");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmadd.s");
     return execute_float_ternary_op_rm<uint32_t>(a, pc, insn,
         [](uint32_t s1, uint32_t s2, uint32_t s3, uint32_t rm, uint32_t *fflags) -> uint32_t {
             return i_sfloat32::fma(s1, s2, s3, static_cast<FRM_modes>(rm), fflags);
@@ -3944,7 +3983,7 @@ static FORCE_INLINE execute_status execute_FMADD_S(STATE_ACCESS a, uint64_t &pc,
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FMADD_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fmadd.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmadd.d");
     return execute_float_ternary_op_rm<uint64_t>(a, pc, insn,
         [](uint64_t s1, uint64_t s2, uint64_t s3, uint32_t rm, uint32_t *fflags) -> uint64_t {
             return i_sfloat64::fma(s1, s2, s3, static_cast<FRM_modes>(rm), fflags);
@@ -3969,7 +4008,7 @@ static FORCE_INLINE execute_status execute_FMADD(STATE_ACCESS a, uint64_t &pc, u
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FMSUB_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fmsub.s");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmsub.s");
     return execute_float_ternary_op_rm<uint32_t>(a, pc, insn,
         [](uint32_t s1, uint32_t s2, uint32_t s3, uint32_t rm, uint32_t *fflags) -> uint32_t {
             return i_sfloat32::fma(s1, s2, s3 ^ i_sfloat32::SIGN_MASK, static_cast<FRM_modes>(rm), fflags);
@@ -3978,7 +4017,7 @@ static FORCE_INLINE execute_status execute_FMSUB_S(STATE_ACCESS a, uint64_t &pc,
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FMSUB_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fmsub.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmsub.d");
     return execute_float_ternary_op_rm<uint64_t>(a, pc, insn,
         [](uint64_t s1, uint64_t s2, uint64_t s3, uint32_t rm, uint32_t *fflags) -> uint64_t {
             return i_sfloat64::fma(s1, s2, s3 ^ i_sfloat64::SIGN_MASK, static_cast<FRM_modes>(rm), fflags);
@@ -4003,7 +4042,7 @@ static FORCE_INLINE execute_status execute_FMSUB(STATE_ACCESS a, uint64_t &pc, u
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FNMADD_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fnmadd.s");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fnmadd.s");
     return execute_float_ternary_op_rm<uint32_t>(a, pc, insn,
         [](uint32_t s1, uint32_t s2, uint32_t s3, uint32_t rm, uint32_t *fflags) -> uint32_t {
             return i_sfloat32::fma(s1 ^ i_sfloat32::SIGN_MASK, s2, s3 ^ i_sfloat32::SIGN_MASK,
@@ -4013,7 +4052,7 @@ static FORCE_INLINE execute_status execute_FNMADD_S(STATE_ACCESS a, uint64_t &pc
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FNMADD_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fnmadd.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fnmadd.d");
     return execute_float_ternary_op_rm<uint64_t>(a, pc, insn,
         [](uint64_t s1, uint64_t s2, uint64_t s3, uint32_t rm, uint32_t *fflags) -> uint64_t {
             return i_sfloat64::fma(s1 ^ i_sfloat64::SIGN_MASK, s2, s3 ^ i_sfloat64::SIGN_MASK,
@@ -4039,7 +4078,7 @@ static FORCE_INLINE execute_status execute_FNMADD(STATE_ACCESS a, uint64_t &pc,
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FNMSUB_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fnmsub.s");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fnmsub.s");
     return execute_float_ternary_op_rm<uint32_t>(a, pc, insn,
         [](uint32_t s1, uint32_t s2, uint32_t s3, uint32_t rm, uint32_t *fflags) -> uint32_t {
             return i_sfloat32::fma(s1 ^ i_sfloat32::SIGN_MASK, s2, s3, static_cast<FRM_modes>(rm), fflags);
@@ -4048,7 +4087,7 @@ static FORCE_INLINE execute_status execute_FNMSUB_S(STATE_ACCESS a, uint64_t &pc
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FNMSUB_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fnmsub.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fnmsub.d");
     return execute_float_ternary_op_rm<uint64_t>(a, pc, insn,
         [](uint64_t s1, uint64_t s2, uint64_t s3, uint32_t rm, uint32_t *fflags) -> uint64_t {
             return i_sfloat64::fma(s1 ^ i_sfloat64::SIGN_MASK, s2, s3, static_cast<FRM_modes>(rm), fflags);
@@ -4073,7 +4112,7 @@ static FORCE_INLINE execute_status execute_FNMSUB(STATE_ACCESS a, uint64_t &pc,
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FADD_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fadd.s");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fadd.s");
     return execute_float_binary_op_rm<uint32_t>(a, pc, insn,
         [](uint32_t s1, uint32_t s2, uint32_t rm, uint32_t *fflags) -> uint32_t {
             return i_sfloat32::add(s1, s2, static_cast<FRM_modes>(rm), fflags);
@@ -4082,7 +4121,7 @@ static FORCE_INLINE execute_status execute_FADD_S(STATE_ACCESS a, uint64_t &pc,
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FADD_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fadd.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fadd.d");
     return execute_float_binary_op_rm<uint64_t>(a, pc, insn,
         [](uint64_t s1, uint64_t s2, uint32_t rm, uint32_t *fflags) -> uint64_t {
             return i_sfloat64::add(s1, s2, static_cast<FRM_modes>(rm), fflags);
@@ -4091,7 +4130,7 @@ static FORCE_INLINE execute_status execute_FADD_D(STATE_ACCESS a, uint64_t &pc,
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FSUB_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fsub.s");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fsub.s");
     return execute_float_binary_op_rm<uint32_t>(a, pc, insn,
         [](uint32_t s1, uint32_t s2, uint32_t rm, uint32_t *fflags) -> uint32_t {
             return i_sfloat32::add(s1, s2 ^ i_sfloat32::SIGN_MASK, static_cast<FRM_modes>(rm), fflags);
@@ -4100,7 +4139,7 @@ static FORCE_INLINE execute_status execute_FSUB_S(STATE_ACCESS a, uint64_t &pc,
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FSUB_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fsub.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fsub.d");
     return execute_float_binary_op_rm<uint64_t>(a, pc, insn,
         [](uint64_t s1, uint64_t s2, uint32_t rm, uint32_t *fflags) -> uint64_t {
             return i_sfloat64::add(s1, s2 ^ i_sfloat64::SIGN_MASK, static_cast<FRM_modes>(rm), fflags);
@@ -4109,7 +4148,7 @@ static FORCE_INLINE execute_status execute_FSUB_D(STATE_ACCESS a, uint64_t &pc,
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FMUL_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fmul.s");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmul.s");
     return execute_float_binary_op_rm<uint32_t>(a, pc, insn,
         [](uint32_t s1, uint32_t s2, uint32_t rm, uint32_t *fflags) -> uint32_t {
             return i_sfloat32::mul(s1, s2, static_cast<FRM_modes>(rm), fflags);
@@ -4118,7 +4157,7 @@ static FORCE_INLINE execute_status execute_FMUL_S(STATE_ACCESS a, uint64_t &pc,
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FMUL_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fmul.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmul.d");
     return execute_float_binary_op_rm<uint64_t>(a, pc, insn,
         [](uint64_t s1, uint64_t s2, uint32_t rm, uint32_t *fflags) -> uint64_t {
             return i_sfloat64::mul(s1, s2, static_cast<FRM_modes>(rm), fflags);
@@ -4127,7 +4166,7 @@ static FORCE_INLINE execute_status execute_FMUL_D(STATE_ACCESS a, uint64_t &pc,
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FDIV_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fdiv.s");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fdiv.s");
     return execute_float_binary_op_rm<uint32_t>(a, pc, insn,
         [](uint32_t s1, uint32_t s2, uint32_t rm, uint32_t *fflags) -> uint32_t {
             return i_sfloat32::div(s1, s2, static_cast<FRM_modes>(rm), fflags);
@@ -4136,7 +4175,7 @@ static FORCE_INLINE execute_status execute_FDIV_S(STATE_ACCESS a, uint64_t &pc,
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FDIV_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fdiv.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fdiv.d");
     return execute_float_binary_op_rm<uint64_t>(a, pc, insn,
         [](uint64_t s1, uint64_t s2, uint32_t rm, uint32_t *fflags) -> uint64_t {
             return i_sfloat64::div(s1, s2, static_cast<FRM_modes>(rm), fflags);
@@ -4189,7 +4228,7 @@ static FORCE_INLINE execute_status execute_float_cmp_op(STATE_ACCESS a, uint64_t
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FSGNJ_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fsgnj.s");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fsgnj.s");
     return execute_float_binary_op<uint32_t>(a, pc, insn,
         [](uint32_t s1, uint32_t s2, const uint32_t * /*fflags*/) -> uint32_t {
             return (s1 & ~i_sfloat32::SIGN_MASK) | (s2 & i_sfloat32::SIGN_MASK);
@@ -4198,7 +4237,7 @@ static FORCE_INLINE execute_status execute_FSGNJ_S(STATE_ACCESS a, uint64_t &pc,
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FSGNJN_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fsgnjn.s");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fsgnjn.s");
     return execute_float_binary_op<uint32_t>(a, pc, insn,
         [](uint32_t s1, uint32_t s2, const uint32_t * /*fflags*/) -> uint32_t {
             return (s1 & ~i_sfloat32::SIGN_MASK) | ((s2 & i_sfloat32::SIGN_MASK) ^ i_sfloat32::SIGN_MASK);
@@ -4207,7 +4246,7 @@ static FORCE_INLINE execute_status execute_FSGNJN_S(STATE_ACCESS a, uint64_t &pc
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FSGNJX_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fsgnjx.s");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fsgnjx.s");
     return execute_float_binary_op<uint32_t>(a, pc, insn,
         [](uint32_t s1, uint32_t s2, const uint32_t * /*fflags*/) -> uint32_t {
             return s1 ^ (s2 & i_sfloat32::SIGN_MASK);
@@ -4230,7 +4269,7 @@ static FORCE_INLINE execute_status execute_FSGN_S(STATE_ACCESS a, uint64_t &pc,
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FSGNJ_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fsgnj.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fsgnj.d");
     return execute_float_binary_op<uint64_t>(a, pc, insn,
         [](uint64_t s1, uint64_t s2, const uint32_t * /*fflags*/) -> uint64_t {
             return (s1 & ~i_sfloat64::SIGN_MASK) | (s2 & i_sfloat64::SIGN_MASK);
@@ -4239,7 +4278,7 @@ static FORCE_INLINE execute_status execute_FSGNJ_D(STATE_ACCESS a, uint64_t &pc,
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FSGNJN_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fsgnjn.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fsgnjn.d");
     return execute_float_binary_op<uint64_t>(a, pc, insn,
         [](uint64_t s1, uint64_t s2, const uint32_t * /*fflags*/) -> uint64_t {
             return (s1 & ~i_sfloat64::SIGN_MASK) | ((s2 & i_sfloat64::SIGN_MASK) ^ i_sfloat64::SIGN_MASK);
@@ -4248,7 +4287,7 @@ static FORCE_INLINE execute_status execute_FSGNJN_D(STATE_ACCESS a, uint64_t &pc
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FSGNJX_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fsgnjx.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fsgnjx.d");
     return execute_float_binary_op<uint64_t>(a, pc, insn,
         [](uint64_t s1, uint64_t s2, const uint32_t * /*fflags*/) -> uint64_t {
             return s1 ^ (s2 & i_sfloat64::SIGN_MASK);
@@ -4271,14 +4310,14 @@ static FORCE_INLINE execute_status execute_FSGN_D(STATE_ACCESS a, uint64_t &pc,
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FMIN_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fmin.s");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmin.s");
     return execute_float_binary_op<uint32_t>(a, pc, insn,
         [](uint32_t s1, uint32_t s2, uint32_t *fflags) -> uint32_t { return i_sfloat32::min(s1, s2, fflags); });
 }
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FMAX_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fmax.s");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmax.s");
     return execute_float_binary_op<uint32_t>(a, pc, insn,
         [](uint32_t s1, uint32_t s2, uint32_t *fflags) -> uint32_t { return i_sfloat32::max(s1, s2, fflags); });
 }
@@ -4297,14 +4336,14 @@ static FORCE_INLINE execute_status execute_FMINMAX_S(STATE_ACCESS a, uint64_t &p
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FMIN_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fmin.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmin.d");
     return execute_float_binary_op<uint64_t>(a, pc, insn,
         [](uint64_t s1, uint64_t s2, uint32_t *fflags) -> uint64_t { return i_sfloat64::min(s1, s2, fflags); });
 }
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FMAX_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fmax.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmax.d");
     return execute_float_binary_op<uint64_t>(a, pc, insn,
         [](uint64_t s1, uint64_t s2, uint32_t *fflags) -> uint64_t { return i_sfloat64::max(s1, s2, fflags); });
 }
@@ -4384,7 +4423,7 @@ static FORCE_INLINE execute_status execute_FCVT_F_X(STATE_ACCESS a, uint64_t &pc
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FCVT_S_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fcvt.s.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.s.d");
     return execute_FCVT_F_F<uint64_t, uint32_t>(a, pc, insn,
         [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint32_t {
             return sfloat_cvt_f64_f32(s1, static_cast<FRM_modes>(rm), fflags);
@@ -4393,7 +4432,7 @@ static FORCE_INLINE execute_status execute_FCVT_S_D(STATE_ACCESS a, uint64_t &pc
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FCVT_D_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fcvt.d.s");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.d.s");
     return execute_FCVT_F_F<uint32_t, uint64_t>(a, pc, insn,
         [](uint32_t s1, uint32_t /*rm*/, uint32_t *fflags) -> uint64_t {
             // FCVT.D.S will never round, since it's a widen operation.
@@ -4403,7 +4442,7 @@ static FORCE_INLINE execute_status execute_FCVT_D_S(STATE_ACCESS a, uint64_t &pc
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FSQRT_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fsqrt.s");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fsqrt.s");
     return execute_float_unary_op_rm<uint32_t>(a, pc, insn, [](uint32_t s1, uint32_t rm, uint32_t *fflags) -> uint32_t {
         return i_sfloat32::sqrt(s1, static_cast<FRM_modes>(rm), fflags);
     });
@@ -4411,7 +4450,7 @@ static FORCE_INLINE execute_status execute_FSQRT_S(STATE_ACCESS a, uint64_t &pc,
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FSQRT_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fsqrt.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fsqrt.d");
     return execute_float_unary_op_rm<uint64_t>(a, pc, insn, [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint64_t {
         return i_sfloat64::sqrt(s1, static_cast<FRM_modes>(rm), fflags);
     });
@@ -4419,7 +4458,7 @@ static FORCE_INLINE execute_status execute_FSQRT_D(STATE_ACCESS a, uint64_t &pc,
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FLE_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fle.s");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fle.s");
     return execute_float_cmp_op<uint32_t>(a, pc, insn, [](uint32_t s1, uint32_t s2, uint32_t *fflags) -> uint64_t {
         return static_cast<uint64_t>(i_sfloat32::le(s1, s2, fflags));
     });
@@ -4427,7 +4466,7 @@ static FORCE_INLINE execute_status execute_FLE_S(STATE_ACCESS a, uint64_t &pc, u
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FLT_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "flt.s");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "flt.s");
     return execute_float_cmp_op<uint32_t>(a, pc, insn, [](uint32_t s1, uint32_t s2, uint32_t *fflags) -> uint64_t {
         return static_cast<uint64_t>(i_sfloat32::lt(s1, s2, fflags));
     });
@@ -4435,7 +4474,7 @@ static FORCE_INLINE execute_status execute_FLT_S(STATE_ACCESS a, uint64_t &pc, u
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FEQ_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "feq.s");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "feq.s");
     return execute_float_cmp_op<uint32_t>(a, pc, insn, [](uint32_t s1, uint32_t s2, uint32_t *fflags) -> uint64_t {
         return static_cast<uint64_t>(i_sfloat32::eq(s1, s2, fflags));
     });
@@ -4457,7 +4496,7 @@ static FORCE_INLINE execute_status execute_FCMP_S(STATE_ACCESS a, uint64_t &pc,
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FLE_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fle.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fle.d");
     return execute_float_cmp_op<uint64_t>(a, pc, insn, [](uint64_t s1, uint64_t s2, uint32_t *fflags) -> uint64_t {
         return static_cast<uint64_t>(i_sfloat64::le(s1, s2, fflags));
     });
@@ -4465,7 +4504,7 @@ static FORCE_INLINE execute_status execute_FLE_D(STATE_ACCESS a, uint64_t &pc, u
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FLT_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "flt.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "flt.d");
     return execute_float_cmp_op<uint64_t>(a, pc, insn, [](uint64_t s1, uint64_t s2, uint32_t *fflags) -> uint64_t {
         return static_cast<uint64_t>(i_sfloat64::lt(s1, s2, fflags));
     });
@@ -4473,7 +4512,7 @@ static FORCE_INLINE execute_status execute_FLT_D(STATE_ACCESS a, uint64_t &pc, u
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FEQ_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "feq.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "feq.d");
     return execute_float_cmp_op<uint64_t>(a, pc, insn, [](uint64_t s1, uint64_t s2, uint32_t *fflags) -> uint64_t {
         return static_cast<uint64_t>(i_sfloat64::eq(s1, s2, fflags));
     });
@@ -4495,7 +4534,7 @@ static FORCE_INLINE execute_status execute_FCMP_D(STATE_ACCESS a, uint64_t &pc,
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FCVT_W_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fcvt.w.s");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.w.s");
     return execute_FCVT_X_F<uint32_t>(a, pc, insn, [](uint32_t s1, uint32_t rm, uint32_t *fflags) -> uint64_t {
         const auto val = i_sfloat32::cvt_f_i<int32_t>(s1, static_cast<FRM_modes>(rm), fflags);
         // For XLEN > 32, FCVT.W.S sign-extends the 32-bit result.
@@ -4505,7 +4544,7 @@ static FORCE_INLINE execute_status execute_FCVT_W_S(STATE_ACCESS a, uint64_t &pc
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FCVT_WU_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fcvt.wu.s");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.wu.s");
     return execute_FCVT_X_F<uint32_t>(a, pc, insn, [](uint32_t s1, uint32_t rm, uint32_t *fflags) -> uint64_t {
         const auto val = i_sfloat32::cvt_f_i<uint32_t>(s1, static_cast<FRM_modes>(rm), fflags);
         // For XLEN > 32, FCVT.WU.S sign-extends the 32-bit result.
@@ -4515,7 +4554,7 @@ static FORCE_INLINE execute_status execute_FCVT_WU_S(STATE_ACCESS a, uint64_t &p
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FCVT_L_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fcvt.l.s");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.l.s");
     return execute_FCVT_X_F<uint32_t>(a, pc, insn, [](uint32_t s1, uint32_t rm, uint32_t *fflags) -> uint64_t {
         const auto val = i_sfloat32::cvt_f_i<int64_t>(s1, static_cast<FRM_modes>(rm), fflags);
         return static_cast<uint64_t>(val);
@@ -4524,7 +4563,7 @@ static FORCE_INLINE execute_status execute_FCVT_L_S(STATE_ACCESS a, uint64_t &pc
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FCVT_LU_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fcvt.lu.s");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.lu.s");
     return execute_FCVT_X_F<uint32_t>(a, pc, insn, [](uint32_t s1, uint32_t rm, uint32_t *fflags) -> uint64_t {
         return i_sfloat32::cvt_f_i<uint64_t>(s1, static_cast<FRM_modes>(rm), fflags);
     });
@@ -4532,7 +4571,7 @@ static FORCE_INLINE execute_status execute_FCVT_LU_S(STATE_ACCESS a, uint64_t &p
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FCVT_W_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fcvt.w.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.w.d");
     return execute_FCVT_X_F<uint64_t>(a, pc, insn, [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint64_t {
         const auto val = i_sfloat64::cvt_f_i<int32_t>(s1, static_cast<FRM_modes>(rm), fflags);
         // For RV64, FCVT.W.D sign-extends the 32-bit result.
@@ -4542,7 +4581,7 @@ static FORCE_INLINE execute_status execute_FCVT_W_D(STATE_ACCESS a, uint64_t &pc
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FCVT_WU_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fcvt.wu.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.wu.d");
     return execute_FCVT_X_F<uint64_t>(a, pc, insn, [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint64_t {
         const auto val = i_sfloat64::cvt_f_i<uint32_t>(s1, static_cast<FRM_modes>(rm), fflags);
         // For RV64, FCVT.WU.D sign-extends the 32-bit result.
@@ -4552,7 +4591,7 @@ static FORCE_INLINE execute_status execute_FCVT_WU_D(STATE_ACCESS a, uint64_t &p
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FCVT_L_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fcvt.l.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.l.d");
     return execute_FCVT_X_F<uint64_t>(a, pc, insn, [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint64_t {
         const auto val = i_sfloat64::cvt_f_i<int64_t>(s1, static_cast<FRM_modes>(rm), fflags);
         return static_cast<uint64_t>(val);
@@ -4561,7 +4600,7 @@ static FORCE_INLINE execute_status execute_FCVT_L_D(STATE_ACCESS a, uint64_t &pc
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FCVT_LU_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fcvt.lu.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.lu.d");
     return execute_FCVT_X_F<uint64_t>(a, pc, insn, [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint64_t {
         return i_sfloat64::cvt_f_i<uint64_t>(s1, static_cast<FRM_modes>(rm), fflags);
     });
@@ -4569,7 +4608,7 @@ static FORCE_INLINE execute_status execute_FCVT_LU_D(STATE_ACCESS a, uint64_t &p
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FCVT_S_W(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fcvt.s.w");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.s.w");
     return execute_FCVT_F_X<uint32_t>(a, pc, insn, [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint32_t {
         return i_sfloat32::cvt_i_f(static_cast<int32_t>(s1), static_cast<FRM_modes>(rm), fflags);
     });
@@ -4577,7 +4616,7 @@ static FORCE_INLINE execute_status execute_FCVT_S_W(STATE_ACCESS a, uint64_t &pc
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FCVT_S_WU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fcvt.s.wu");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.s.wu");
     return execute_FCVT_F_X<uint32_t>(a, pc, insn, [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint32_t {
         return i_sfloat32::cvt_i_f(static_cast<uint32_t>(s1), static_cast<FRM_modes>(rm), fflags);
     });
@@ -4585,7 +4624,7 @@ static FORCE_INLINE execute_status execute_FCVT_S_WU(STATE_ACCESS a, uint64_t &p
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FCVT_S_L(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fcvt.s.l");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.s.l");
     return execute_FCVT_F_X<uint32_t>(a, pc, insn, [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint32_t {
         return i_sfloat32::cvt_i_f(static_cast<int64_t>(s1), static_cast<FRM_modes>(rm), fflags);
     });
@@ -4593,7 +4632,7 @@ static FORCE_INLINE execute_status execute_FCVT_S_L(STATE_ACCESS a, uint64_t &pc
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FCVT_S_LU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fcvt.s.lu");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.s.lu");
     return execute_FCVT_F_X<uint32_t>(a, pc, insn, [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint32_t {
         return i_sfloat32::cvt_i_f(s1, static_cast<FRM_modes>(rm), fflags);
     });
@@ -4601,7 +4640,7 @@ static FORCE_INLINE execute_status execute_FCVT_S_LU(STATE_ACCESS a, uint64_t &p
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FCVT_D_W(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fcvt.d.w");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.d.w");
     return execute_FCVT_F_X<uint64_t>(a, pc, insn, [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint64_t {
         return i_sfloat64::cvt_i_f(static_cast<int32_t>(s1), static_cast<FRM_modes>(rm), fflags);
     });
@@ -4609,7 +4648,7 @@ static FORCE_INLINE execute_status execute_FCVT_D_W(STATE_ACCESS a, uint64_t &pc
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FCVT_D_WU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fcvt.d.wu");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.d.wu");
     return execute_FCVT_F_X<uint64_t>(a, pc, insn, [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint64_t {
         return i_sfloat64::cvt_i_f(static_cast<uint32_t>(s1), static_cast<FRM_modes>(rm), fflags);
     });
@@ -4617,7 +4656,7 @@ static FORCE_INLINE execute_status execute_FCVT_D_WU(STATE_ACCESS a, uint64_t &p
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FCVT_D_L(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fcvt.d.l");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.d.l");
     return execute_FCVT_F_X<uint64_t>(a, pc, insn, [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint64_t {
         return i_sfloat64::cvt_i_f(static_cast<int64_t>(s1), static_cast<FRM_modes>(rm), fflags);
     });
@@ -4625,7 +4664,7 @@ static FORCE_INLINE execute_status execute_FCVT_D_L(STATE_ACCESS a, uint64_t &pc
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FCVT_D_LU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fcvt.d.lu");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.d.lu");
     return execute_FCVT_F_X<uint64_t>(a, pc, insn, [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint64_t {
         return i_sfloat64::cvt_i_f(s1, static_cast<FRM_modes>(rm), fflags);
     });
@@ -4646,25 +4685,25 @@ static FORCE_INLINE execute_status execute_FMV_F_X(STATE_ACCESS a, uint64_t &pc,
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FMV_W_X(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fmv.w.x");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmv.w.x");
     return execute_FMV_F_X<uint32_t>(a, pc, insn);
 }
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FMV_D_X(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fmv.d.x");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmv.d.x");
     return execute_FMV_F_X<uint64_t>(a, pc, insn);
 }
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FCLASS_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fclass.s");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fclass.s");
     return execute_FCLASS<uint32_t>(a, pc, insn, [](uint32_t s1) -> uint64_t { return i_sfloat32::fclass(s1); });
 }
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FMV_X_W(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fmv.x.w");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmv.x.w");
     const uint32_t rd = insn_get_rd(insn);
     if (unlikely(rd == 0)) {
         return advance_to_next_insn(a, pc);
@@ -4691,13 +4730,13 @@ static FORCE_INLINE execute_status execute_FMV_FCLASS_S(STATE_ACCESS a, uint64_t
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FCLASS_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fclass.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fclass.d");
     return execute_FCLASS<uint64_t>(a, pc, insn, [](uint64_t s1) -> uint64_t { return i_sfloat64::fclass(s1); });
 }
 
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_FMV_X_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, insn, "fmv.x.d");
+    [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmv.x.d");
     const uint32_t rd = insn_get_rd(insn);
     if (unlikely(rd == 0)) {
         return advance_to_next_insn(a, pc);
@@ -4882,7 +4921,7 @@ static FORCE_INLINE execute_status execute_C_FS(STATE_ACCESS a, uint64_t &pc, ui
 /// \brief Implementation of the C.ADDI4SPN instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_ADDI4SPN(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.addi4spn");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.addi4spn");
     // rd cannot be zero (guaranteed by RISC-V spec design)
     const uint32_t rd = insn_get_CIW_CL_rd_CS_CA_rs2(insn);
     // imm cannot be zero (guaranteed by the jump table)
@@ -4897,9 +4936,8 @@ static FORCE_INLINE execute_status execute_C_ADDI4SPN(STATE_ACCESS a, uint64_t &
 /// \brief Implementation of the C.FLD instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_FLD(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.fld");
-    // If FS is OFF, attempts to read or write the float state will cause an illegal instruction
-    // exception.
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.fld");
+    // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((a.read_mstatus() & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
         return raise_illegal_insn_exception(a, pc, insn);
     }
@@ -4912,7 +4950,7 @@ static FORCE_INLINE execute_status execute_C_FLD(STATE_ACCESS a, uint64_t &pc, u
 /// \brief Implementation of the C.LW instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_LW(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.lw");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.lw");
     const uint32_t rd = insn_get_CIW_CL_rd_CS_CA_rs2(insn);
     const uint32_t rs1 = insn_get_CL_CS_CA_CB_rs1(insn);
     const int32_t imm = insn_get_C_LW_C_SW_imm(insn);
@@ -4922,7 +4960,7 @@ static FORCE_INLINE execute_status execute_C_LW(STATE_ACCESS a, uint64_t &pc, ui
 /// \brief Implementation of the C.LD instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_LD(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.ld");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.ld");
     const uint32_t rd = insn_get_CIW_CL_rd_CS_CA_rs2(insn);
     const uint32_t rs1 = insn_get_CL_CS_CA_CB_rs1(insn);
     const int32_t imm = insn_get_CL_CS_imm(insn);
@@ -4932,9 +4970,8 @@ static FORCE_INLINE execute_status execute_C_LD(STATE_ACCESS a, uint64_t &pc, ui
 /// \brief Implementation of the C.FSD instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_FSD(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.fsd");
-    // If FS is OFF, attempts to read or write the float state will cause an illegal instruction
-    // exception.
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.fsd");
+    // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((a.read_mstatus() & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
         return raise_illegal_insn_exception(a, pc, insn);
     }
@@ -4947,7 +4984,7 @@ static FORCE_INLINE execute_status execute_C_FSD(STATE_ACCESS a, uint64_t &pc, u
 /// \brief Implementation of the C.SW instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_SW(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.sw");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.sw");
     const uint32_t rs1 = insn_get_CL_CS_CA_CB_rs1(insn);
     const uint32_t rs2 = insn_get_CIW_CL_rd_CS_CA_rs2(insn);
     const int32_t imm = insn_get_C_LW_C_SW_imm(insn);
@@ -4957,7 +4994,7 @@ static FORCE_INLINE execute_status execute_C_SW(STATE_ACCESS a, uint64_t &pc, ui
 /// \brief Implementation of the C.SD instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_SD(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.sd");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.sd");
     const uint32_t rs1 = insn_get_CL_CS_CA_CB_rs1(insn);
     const uint32_t rs2 = insn_get_CIW_CL_rd_CS_CA_rs2(insn);
     const int32_t imm = insn_get_CL_CS_imm(insn);
@@ -4967,7 +5004,7 @@ static FORCE_INLINE execute_status execute_C_SD(STATE_ACCESS a, uint64_t &pc, ui
 /// \brief Implementation of the C.NOP instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_NOP(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.nop");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.nop");
     // Really do nothing
     return advance_to_next_insn<2>(a, pc);
 }
@@ -4975,7 +5012,7 @@ static FORCE_INLINE execute_status execute_C_NOP(STATE_ACCESS a, uint64_t &pc, u
 /// \brief Implementation of the C.ADDI instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_ADDI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.addi");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.addi");
     // rd cannot be zero (guaranteed by jump table)
     const uint32_t rd = insn_get_rd(insn);
     const int32_t imm = insn_get_CI_CB_imm_se(insn);
@@ -4990,7 +5027,7 @@ static FORCE_INLINE execute_status execute_C_ADDI(STATE_ACCESS a, uint64_t &pc,
 /// \brief Implementation of the C.addiw instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_ADDIW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.addiw");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.addiw");
     // rd cannot be zero (guaranteed by jump table)
     const uint32_t rd = insn_get_rd(insn);
     const uint64_t rd_value = a.read_x(rd);
@@ -5004,7 +5041,7 @@ static FORCE_INLINE execute_status execute_C_ADDIW(STATE_ACCESS a, uint64_t &pc,
 /// \brief Implementation of the C.LI instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_LI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.li");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.li");
     // rd cannot be zero (guaranteed by jump table)
     const uint32_t rd = insn_get_rd(insn);
     const int32_t imm = insn_get_CI_CB_imm_se(insn);
@@ -5015,7 +5052,7 @@ static FORCE_INLINE execute_status execute_C_LI(STATE_ACCESS a, uint64_t &pc, ui
 /// \brief Implementation of the C.ADDI16SP instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_ADDI16SP(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.addi16sp");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.addi16sp");
     // imm cannot be zero (guaranteed by the jump table)
     const int32_t imm = insn_get_C_ADDI16SP_imm(insn);
     const uint64_t rs1_value = a.read_x(2);
@@ -5028,7 +5065,7 @@ static FORCE_INLINE execute_status execute_C_ADDI16SP(STATE_ACCESS a, uint64_t &
 /// \brief Implementation of the C.LUI instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_LUI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.lui");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.lui");
     // imm cannot be zero (guaranteed by the jump table)
     const int32_t imm = insn_get_C_LUI_imm(insn);
     // rd cannot be zero (guaranteed by the jump table)
@@ -5040,7 +5077,7 @@ static FORCE_INLINE execute_status execute_C_LUI(STATE_ACCESS a, uint64_t &pc, u
 /// \brief Implementation of the C.SRLI instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_SRLI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.srli");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.srli");
     const uint32_t rs1 = insn_get_CL_CS_CA_CB_rs1(insn);
     // imm cannot be zero (guaranteed by the jump table)
     const uint32_t imm = insn_get_CI_CB_imm(insn);
@@ -5052,7 +5089,7 @@ static FORCE_INLINE execute_status execute_C_SRLI(STATE_ACCESS a, uint64_t &pc,
 /// \brief Implementation of the C.SRAI instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_SRAI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.srai");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.srai");
     const uint32_t rs1 = insn_get_CL_CS_CA_CB_rs1(insn);
     // imm cannot be zero (guaranteed by the jump table)
     const uint32_t imm = insn_get_CI_CB_imm(insn);
@@ -5064,7 +5101,7 @@ static FORCE_INLINE execute_status execute_C_SRAI(STATE_ACCESS a, uint64_t &pc,
 /// \brief Implementation of the C.ANDI instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_ANDI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.andi");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.andi");
     const uint32_t rs1 = insn_get_CL_CS_CA_CB_rs1(insn);
     const int32_t imm = insn_get_CI_CB_imm_se(insn);
     const uint64_t rs1_value = a.read_x(rs1);
@@ -5087,7 +5124,7 @@ static FORCE_INLINE execute_status execute_C_arithmetic(STATE_ACCESS a, uint64_t
 /// \brief Implementation of the C.SUB instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_SUB(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.sub");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.sub");
     return execute_C_arithmetic(a, pc, insn, [](uint64_t rs1_value, uint64_t rs2_value) -> uint64_t {
         uint64_t val = 0;
         __builtin_sub_overflow(rs1_value, rs2_value, &val);
@@ -5098,7 +5135,7 @@ static FORCE_INLINE execute_status execute_C_SUB(STATE_ACCESS a, uint64_t &pc, u
 /// \brief Implementation of the C.XOR instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_XOR(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.xor");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.xor");
     return execute_C_arithmetic(a, pc, insn,
         [](uint64_t rs1_value, uint64_t rs2_value) -> uint64_t { return rs1_value ^ rs2_value; });
 }
@@ -5106,7 +5143,7 @@ static FORCE_INLINE execute_status execute_C_XOR(STATE_ACCESS a, uint64_t &pc, u
 /// \brief Implementation of the C.OR instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_OR(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.or");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.or");
     return execute_C_arithmetic(a, pc, insn,
         [](uint64_t rs1_value, uint64_t rs2_value) -> uint64_t { return rs1_value | rs2_value; });
 }
@@ -5114,7 +5151,7 @@ static FORCE_INLINE execute_status execute_C_OR(STATE_ACCESS a, uint64_t &pc, ui
 /// \brief Implementation of the C.AND instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_AND(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.and");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.and");
     return execute_C_arithmetic(a, pc, insn,
         [](uint64_t rs1_value, uint64_t rs2_value) -> uint64_t { return rs1_value & rs2_value; });
 }
@@ -5122,7 +5159,7 @@ static FORCE_INLINE execute_status execute_C_AND(STATE_ACCESS a, uint64_t &pc, u
 /// \brief Implementation of the C.SUBW instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_SUBW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.subw");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.subw");
     return execute_C_arithmetic(a, pc, insn, [](uint64_t rs1_value, uint64_t rs2_value) -> uint64_t {
         // Convert 64-bit to 32-bit
         auto rs1w = static_cast<int32_t>(rs1_value);
@@ -5136,7 +5173,7 @@ static FORCE_INLINE execute_status execute_C_SUBW(STATE_ACCESS a, uint64_t &pc,
 /// \brief Implementation of the C.ADDW instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_ADDW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.addw");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.addw");
     return execute_C_arithmetic(a, pc, insn, [](uint64_t rs1_value, uint64_t rs2_value) -> uint64_t {
         // Discard upper 32 bits
         auto rs1w = static_cast<int32_t>(rs1_value);
@@ -5150,7 +5187,7 @@ static FORCE_INLINE execute_status execute_C_ADDW(STATE_ACCESS a, uint64_t &pc,
 /// \brief Implementation of the C_J instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_J(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.j");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.j");
     const uint64_t new_pc = pc + static_cast<uint64_t>(insn_get_C_J_imm(insn));
     return execute_jump(a, pc, new_pc);
 }
@@ -5158,7 +5195,7 @@ static FORCE_INLINE execute_status execute_C_J(STATE_ACCESS a, uint64_t &pc, uin
 /// \brief Implementation of the C.BEQZ instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_BEQZ(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.beqz");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.beqz");
     const uint32_t rs1 = insn_get_CL_CS_CA_CB_rs1(insn);
     if (a.read_x(rs1) == 0) {
         const int32_t imm = insn_get_C_BEQZ_BNEZ_imm(insn);
@@ -5171,7 +5208,7 @@ static FORCE_INLINE execute_status execute_C_BEQZ(STATE_ACCESS a, uint64_t &pc,
 /// \brief Implementation of the C.BNEZ instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_BNEZ(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.bnez");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.bnez");
     const uint32_t rs1 = insn_get_CL_CS_CA_CB_rs1(insn);
     if (a.read_x(rs1) != 0) {
         const int32_t imm = insn_get_C_BEQZ_BNEZ_imm(insn);
@@ -5184,7 +5221,7 @@ static FORCE_INLINE execute_status execute_C_BNEZ(STATE_ACCESS a, uint64_t &pc,
 /// \brief Implementation of the C.SLLI instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_SLLI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.slli");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.slli");
     // rd cannot be zero (guaranteed by jump table)
     const uint32_t rd = insn_get_rd(insn);
     // imm cannot be zero (guaranteed by jump table)
@@ -5197,9 +5234,8 @@ static FORCE_INLINE execute_status execute_C_SLLI(STATE_ACCESS a, uint64_t &pc,
 /// \brief Implementation of the C.FLDSP instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_FLDSP(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.fldsp");
-    // If FS is OFF, attempts to read or write the float state will cause an illegal instruction
-    // exception.
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.fldsp");
+    // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((a.read_mstatus() & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
         return raise_illegal_insn_exception(a, pc, insn);
     }
@@ -5211,7 +5247,7 @@ static FORCE_INLINE execute_status execute_C_FLDSP(STATE_ACCESS a, uint64_t &pc,
 /// \brief Implementation of the C.LWSP instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_LWSP(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.lwsp");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.lwsp");
     // rd cannot be zero (guaranteed by jump table)
     const uint32_t rd = insn_get_rd(insn);
     const int32_t imm = insn_get_C_LWSP_imm(insn);
@@ -5221,7 +5257,7 @@ static FORCE_INLINE execute_status execute_C_LWSP(STATE_ACCESS a, uint64_t &pc,
 /// \brief Implementation of the C.LDSP instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_LDSP(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.ldsp");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.ldsp");
     // rd cannot be zero (guaranteed by jump table)
     const uint32_t rd = insn_get_rd(insn);
     const int32_t imm = insn_get_C_FLDSP_LDSP_imm(insn);
@@ -5231,7 +5267,7 @@ static FORCE_INLINE execute_status execute_C_LDSP(STATE_ACCESS a, uint64_t &pc,
 /// \brief Implementation of the C.JR instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_JR(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.jr");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.jr");
     // rs1 cannot be zero (guaranteed by the jump table)
     const uint32_t rs1 = insn_get_rd(insn);
     const uint64_t new_pc = a.read_x(rs1) & ~static_cast<uint64_t>(1);
@@ -5241,7 +5277,7 @@ static FORCE_INLINE execute_status execute_C_JR(STATE_ACCESS a, uint64_t &pc, ui
 /// \brief Implementation of the C.MV instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_MV(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.mv");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.mv");
     // rd cannot be zero (guaranteed by the jump table)
     const uint32_t rd = insn_get_rd(insn);
     const uint32_t rs2 = insn_get_CR_CSS_rs2(insn);
@@ -5253,7 +5289,7 @@ static FORCE_INLINE execute_status execute_C_MV(STATE_ACCESS a, uint64_t &pc, ui
 /// \brief Implementation of the C.EBREAK instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_EBREAK(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.ebreak");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.ebreak");
     pc = raise_exception(a, pc, MCAUSE_BREAKPOINT, pc);
     return advance_to_raised_exception(a, pc);
 }
@@ -5261,7 +5297,7 @@ static FORCE_INLINE execute_status execute_C_EBREAK(STATE_ACCESS a, uint64_t &pc
 /// \brief Implementation of the C.JALR instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_JALR(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.jalr");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.jalr");
     const uint32_t rs1 = insn_get_rd(insn);
     const uint64_t new_pc = a.read_x(rs1) & ~static_cast<uint64_t>(1);
     const uint64_t val = pc + 2;
@@ -5272,7 +5308,7 @@ static FORCE_INLINE execute_status execute_C_JALR(STATE_ACCESS a, uint64_t &pc,
 /// \brief Implementation of the C.ADD instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_ADD(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.add");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.add");
     // rd cannot be zero (guaranteed by the jump table)
     const uint32_t rd = insn_get_rd(insn);
     const uint32_t rs2 = insn_get_CR_CSS_rs2(insn);
@@ -5287,9 +5323,8 @@ static FORCE_INLINE execute_status execute_C_ADD(STATE_ACCESS a, uint64_t &pc, u
 /// \brief Implementation of the C.FSDSP instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_FSDSP(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.fsdsp");
-    // If FS is OFF, attempts to read or write the float state will cause an illegal instruction
-    // exception.
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.fsdsp");
+    // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((a.read_mstatus() & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
         return raise_illegal_insn_exception(a, pc, insn);
     }
@@ -5301,7 +5336,7 @@ static FORCE_INLINE execute_status execute_C_FSDSP(STATE_ACCESS a, uint64_t &pc,
 /// \brief Implementation of the C.SWSP instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_SWSP(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.swsp");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.swsp");
     const uint32_t rs2 = insn_get_CR_CSS_rs2(insn);
     const int32_t imm = insn_get_C_SWSP_imm(insn);
     return execute_C_S<uint32_t>(a, pc, mcycle, rs2, 0x2, imm);
@@ -5310,7 +5345,7 @@ static FORCE_INLINE execute_status execute_C_SWSP(STATE_ACCESS a, uint64_t &pc,
 /// \brief Implementation of the C.SDSP instruction.
 template <typename STATE_ACCESS>
 static FORCE_INLINE execute_status execute_C_SDSP(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
-    dump_insn(a, pc, static_cast<uint16_t>(insn), "c.sdsp");
+    [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.sdsp");
     const uint32_t rs2 = insn_get_CR_CSS_rs2(insn);
     const int32_t imm = insn_get_C_FSDSP_SDSP_imm(insn);
     return execute_C_S<uint64_t>(a, pc, mcycle, rs2, 0x2, imm);
@@ -5368,13 +5403,13 @@ static FORCE_INLINE fetch_status fetch_translate_pc(STATE_ACCESS a, uint64_t &pc
     const uint64_t slot_index = tlb_slot_index(vaddr);
     const uint64_t slot_vaddr_page = a.template read_tlb_vaddr_page<TLB_CODE>(slot_index);
     if (unlikely(!tlb_is_hit<uint16_t>(slot_vaddr_page, vaddr))) {
-        INC_COUNTER(a.get_statistics(), tlb_cmiss);
+        DUMP_STATS_INCR(a, "tlb.cmiss");
         // Outline the slow path into a function call to minimize host CPU code cache pressure
         return fetch_translate_pc_slow(a, pc, vaddr, vp_offset, pma_index);
     }
     vp_offset = a.template read_tlb_vp_offset<TLB_CODE>(slot_index);
     pma_index = a.template read_tlb_pma_index<TLB_CODE>(slot_index);
-    INC_COUNTER(a.get_statistics(), tlb_chit);
+    DUMP_STATS_INCR(a, "tlb.chit");
     return fetch_status::success;
 }
 
@@ -5478,7 +5513,7 @@ static NO_INLINE execute_status interpret_loop(STATE_ACCESS a, uint64_t mcycle_e
     // The outer loop continues until there is an interruption that should be handled
     // externally, or mcycle reaches mcycle_end
     while (mcycle < mcycle_end) {
-        INC_COUNTER(a.get_statistics(), outer_loop);
+        DUMP_STATS_INCR(a, "outer_loop");
 
         if (rtc_is_tick(mcycle)) {
             // Set interrupt flag for RTC
@@ -5507,7 +5542,7 @@ static NO_INLINE execute_status interpret_loop(STATE_ACCESS a, uint64_t mcycle_e
         // The inner loop continues until there is an interrupt condition
         // or mcycle reaches mcycle_tick_end
         while (mcycle < mcycle_tick_end) {
-            INC_COUNTER(a.get_statistics(), inner_loop);
+            DUMP_STATS_INCR(a, "inner_loop");
 
             uint32_t insn = 0;
 
@@ -6056,7 +6091,7 @@ interpreter_break_reason interpret(STATE_ACCESS a, uint64_t mcycle_end) {
     }
     if (status == execute_status::success_and_yield) {
         return interpreter_break_reason::yielded_softly;
-    }                                      // Reached mcycle_end
+    } // Reached mcycle_end
     assert(a.read_mcycle() == mcycle_end); // LCOV_EXCL_LINE
     return interpreter_break_reason::reached_target_mcycle;
 }
diff --git a/src/machine-state.h b/src/machine-state.h
index 0b85a386e..2d3ae4dbd 100644
--- a/src/machine-state.h
+++ b/src/machine-state.h
@@ -23,10 +23,6 @@
 #include <array>
 #include <cstdint>
 
-#ifdef DUMP_HIST
-#include <unordered_map>
-#endif
-
 #include <boost/container/static_vector.hpp>
 
 #include "pma-constants.h"
@@ -124,16 +120,6 @@ struct machine_state {
     boost::container::static_vector<pma_entry, PMA_MAX> pmas;
 
     pma_entry empty_pma; ///< fallback to PMA for empty range
-
-    // Entries below this mark are not needed in the blockchain
-
-#ifdef DUMP_COUNTERS
-    machine_statistics stats;
-#endif
-
-#ifdef DUMP_HIST
-    std::unordered_map<std::string, uint64_t> insn_hist;
-#endif
 };
 
 } // namespace cartesi
diff --git a/src/machine-statistics.h b/src/machine-statistics.h
deleted file mode 100644
index e0221d68d..000000000
--- a/src/machine-statistics.h
+++ /dev/null
@@ -1,78 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef MACHINE_STATISTICS_H
-#define MACHINE_STATISTICS_H
-
-#include <cstdint>
-
-namespace cartesi {
-
-/// \brief Machine statistics
-struct machine_statistics {
-    uint64_t inner_loop;   ///< Counts executions of inner loop
-    uint64_t outer_loop;   ///< Counts executions of outer loop
-    uint64_t sv_int;       ///< Counts supervisor interrupts
-    uint64_t sv_ex;        ///< Counts supervisor exceptions (except ECALL)
-    uint64_t m_int;        ///< Counts machine interrupts
-    uint64_t m_ex;         ///< Counts machine exceptions (except ECALL)
-    uint64_t atomic_mop;   ///< Counts atomic memory operations
-    uint64_t flush_all;    ///< Counts flush all calls
-    uint64_t flush_va;     ///< Counts flush virtual address calls
-    uint64_t fence;        ///< Counts fence calls
-    uint64_t fence_i;      ///< Counts fence.i calls
-    uint64_t fence_vma;    ///< Counts fence.vma calls
-    uint64_t max_asid;     ///< Counts the maximum number of used ASIDs (only relevant when ASIDLEN > 0)
-    uint64_t prv_level[4]; ///< Counts changes to prvilege levels
-
-    // TLB
-    uint64_t tlb_chit;                       ///< Counts TLB code access hits
-    uint64_t tlb_cmiss;                      ///< Counts TLB code access misses
-    uint64_t tlb_rhit;                       ///< Counts TLB read access hits
-    uint64_t tlb_rmiss;                      ///< Counts TLB read access misses
-    uint64_t tlb_whit;                       ///< Counts TLB write access hits
-    uint64_t tlb_wmiss;                      ///< Counts TLB write access misses
-    uint64_t tlb_flush_all;                  ///< Counts TLB flush all calls
-    uint64_t tlb_flush_vaddr;                ///< Counts TLB flush virtual address calls
-    uint64_t tlb_flush_read;                 ///< Counts read TLB flush calls
-    uint64_t tlb_flush_write;                ///< Counts write TLB flush calls
-    uint64_t tlb_flush_satp;                 ///< Counts TLB flush originated from satp changes
-    uint64_t tlb_flush_mstatus;              ///< Counts TLB flush originated from mstatus changes
-    uint64_t tlb_flush_set_prv;              ///< Counts TLB flush originated from set_prv changes
-    uint64_t tlb_flush_fence_vma_all;        ///< Counts TLB flush originated from SFENCE.VMA (all)
-    uint64_t tlb_flush_fence_vma_asid;       ///< Counts TLB flush originated from SFENCE.VMA (asid)
-    uint64_t tlb_flush_fence_vma_vaddr;      ///< Counts TLB flush originated from SFENCE.VMA (vaddr)
-    uint64_t tlb_flush_fence_vma_asid_vaddr; ///< Counts TLB flush originated originated from SFENCE.VMA (vaddr,asid)
-};
-
-#ifdef DUMP_COUNTERS
-// NOLINTBEGIN(cppcoreguidelines-macro-usage,cppcoreguidelines-avoid-do-while)
-#define INC_COUNTER(stats, counter)                                                                                    \
-    do {                                                                                                               \
-        stats.counter++;                                                                                               \
-    } while (0)
-// NOLINTEND(cppcoreguidelines-macro-usage,cppcoreguidelines-avoid-do-while)
-#else
-// NOLINTBEGIN(cppcoreguidelines-macro-usage,cppcoreguidelines-avoid-do-while)
-#define INC_COUNTER(state, counter)                                                                                    \
-    do {                                                                                                               \
-    } while (0)
-// NOLINTEND(cppcoreguidelines-macro-usage,cppcoreguidelines-avoid-do-while)
-#endif
-
-} // namespace cartesi
-
-#endif
diff --git a/src/machine.cpp b/src/machine.cpp
index 26052f4cd..d30ee1aa3 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -955,57 +955,70 @@ void machine::store(const std::string &dir) const {
     store_pmas(c, dir);
 }
 
+void machine::dump_insn_hist() {
+#ifdef DUMP_INSN_HIST
+    D_PRINTF("\nInstruction Histogram:\n", "");
+    for (const auto &[key, val] : m_counters) {
+        if (key.starts_with("insn.")) {
+            D_PRINTF("%s: %" PRIu64 "\n", key.c_str(), val);
+        }
+    }
+#endif
+}
+
+void machine::dump_stats() {
+#if DUMP_STATS
+    const auto hr = [](uint64_t a, uint64_t b) {
+        // NOLINTNEXTLINE(bugprone-narrowing-conversions,cppcoreguidelines-narrowing-conversions)
+        return static_cast<double>(b) / (a + b);
+    };
+
+    D_PRINTF("\nMachine Counters:\n", "");
+    D_PRINTF("inner loops: %" PRIu64 "\n", m_counters["stats.inner_loop"]);
+    D_PRINTF("outers loops: %" PRIu64 "\n", m_counters["stats.outer_loop"]);
+    D_PRINTF("supervisor ints: %" PRIu64 "\n", m_counters["stats.sv_int"]);
+    D_PRINTF("supervisor ex: %" PRIu64 "\n", m_counters["stats.sv_ex"]);
+    D_PRINTF("machine ints: %" PRIu64 "\n", m_counters["stats.m_int"]);
+    D_PRINTF("machine ex: %" PRIu64 "\n", m_counters["stats.m_ex"]);
+    D_PRINTF("atomic mem ops: %" PRIu64 "\n", m_counters["stats.atomic_mop"]);
+    D_PRINTF("fence: %" PRIu64 "\n", m_counters["stats.fence"]);
+    D_PRINTF("fence.i: %" PRIu64 "\n", m_counters["stats.fence_i"]);
+    D_PRINTF("fence.vma: %" PRIu64 "\n", m_counters["stats.fence_vma"]);
+    D_PRINTF("max asid: %" PRIu64 "\n", m_counters["stats.max_asid"]);
+    D_PRINTF("User mode: %" PRIu64 "\n", m_counters["stats.prv.U"]);
+    D_PRINTF("Supervisor mode: %" PRIu64 "\n", m_counters["stats.prv.S"]);
+    D_PRINTF("Machine mode: %" PRIu64 "\n", m_counters["stats.prv.M"]);
+    D_PRINTF("tlb code hit ratio: %.4f\n", hr(m_counters["stats.tlb.cmiss"], m_counters["stats.tlb.chit"]));
+    D_PRINTF("tlb read hit ratio: %.4f\n", hr(m_counters["stats.tlb.rmiss"], m_counters["stats.tlb.rhit"]));
+    D_PRINTF("tlb write hit ratio: %.4f\n", hr(m_counters["stats.tlb.wmiss"], m_counters["stats.tlb.whit"]));
+    D_PRINTF("tlb.chit: %" PRIu64 "\n", m_counters["stats.tlb.chit"]);
+    D_PRINTF("tlb.cmiss: %" PRIu64 "\n", m_counters["stats.tlb.cmiss"]);
+    D_PRINTF("tlb.rhit: %" PRIu64 "\n", m_counters["stats.tlb.rhit"]);
+    D_PRINTF("tlb.rmiss: %" PRIu64 "\n", m_counters["stats.tlb.rmiss"]);
+    D_PRINTF("tlb.whit: %" PRIu64 "\n", m_counters["stats.tlb.whit"]);
+    D_PRINTF("tlb.wmiss: %" PRIu64 "\n", m_counters["stats.tlb.wmiss"]);
+    D_PRINTF("tlb.flush_all: %" PRIu64 "\n", m_counters["stats.tlb.flush_all"]);
+    D_PRINTF("tlb.flush_read: %" PRIu64 "\n", m_counters["stats.tlb.flush_read"]);
+    D_PRINTF("tlb.flush_write: %" PRIu64 "\n", m_counters["stats.tlb.flush_write"]);
+    D_PRINTF("tlb.flush_vaddr: %" PRIu64 "\n", m_counters["stats.tlb.flush_vaddr"]);
+    D_PRINTF("tlb.flush_satp: %" PRIu64 "\n", m_counters["stats.tlb.flush_satp"]);
+    D_PRINTF("tlb.flush_mstatus: %" PRIu64 "\n", m_counters["stats.tlb.flush_mstatus"]);
+    D_PRINTF("tlb.flush_set_prv: %" PRIu64 "\n", m_counters["stats.tlb.flush_set_prv"]);
+    D_PRINTF("tlb.flush_fence_vma_all: %" PRIu64 "\n", m_counters["stats.tlb.flush_fence_vma_all"]);
+    D_PRINTF("tlb.flush_fence_vma_asid: %" PRIu64 "\n", m_counters["stats.tlb.flush_fence_vma_asid"]);
+    D_PRINTF("tlb.flush_fence_vma_vaddr: %" PRIu64 "\n", m_counters["stats.tlb.flush_fence_vma_vaddr"]);
+    D_PRINTF("tlb.flush_fence_vma_asid_vaddr: %" PRIu64 "\n", m_counters["stats.tlb.flush_fence_vma_asid_vaddr"]);
+#undef TLB_HIT_RATIO
+#endif
+}
+
 machine::~machine() {
     // Cleanup TTY if console input was enabled
     if (m_c.htif.console_getchar || has_virtio_console()) {
         os_close_tty();
     }
-#ifdef DUMP_HIST
-    std::ignore = fprintf(stderr, "\nInstruction Histogram:\n");
-    for (auto v : m_s.insn_hist) {
-        std::ignore = fprintf(stderr, "%12" PRIu64 "  %s\n", v.second, v.first.c_str());
-    }
-#endif
-#if DUMP_COUNTERS
-#define TLB_HIT_RATIO(s, a, b) (((double) (s).stats.b) / ((s).stats.a + (s).stats.b))
-    std::ignore = fprintf(stderr, "\nMachine Counters:\n");
-    std::ignore = fprintf(stderr, "inner loops: %" PRIu64 "\n", m_s.stats.inner_loop);
-    std::ignore = fprintf(stderr, "outers loops: %" PRIu64 "\n", m_s.stats.outer_loop);
-    std::ignore = fprintf(stderr, "supervisor ints: %" PRIu64 "\n", m_s.stats.sv_int);
-    std::ignore = fprintf(stderr, "supervisor ex: %" PRIu64 "\n", m_s.stats.sv_ex);
-    std::ignore = fprintf(stderr, "machine ints: %" PRIu64 "\n", m_s.stats.m_int);
-    std::ignore = fprintf(stderr, "machine ex: %" PRIu64 "\n", m_s.stats.m_ex);
-    std::ignore = fprintf(stderr, "atomic mem ops: %" PRIu64 "\n", m_s.stats.atomic_mop);
-    std::ignore = fprintf(stderr, "fence: %" PRIu64 "\n", m_s.stats.fence);
-    std::ignore = fprintf(stderr, "fence.i: %" PRIu64 "\n", m_s.stats.fence_i);
-    std::ignore = fprintf(stderr, "fence.vma: %" PRIu64 "\n", m_s.stats.fence_vma);
-    std::ignore = fprintf(stderr, "max asid: %" PRIu64 "\n", m_s.stats.max_asid);
-    std::ignore = fprintf(stderr, "User mode: %" PRIu64 "\n", m_s.stats.prv_level[PRV_U]);
-    std::ignore = fprintf(stderr, "Supervisor mode: %" PRIu64 "\n", m_s.stats.prv_level[PRV_S]);
-    std::ignore = fprintf(stderr, "Machine mode: %" PRIu64 "\n", m_s.stats.prv_level[PRV_M]);
-
-    std::ignore = fprintf(stderr, "tlb code hit ratio: %.4f\n", TLB_HIT_RATIO(m_s, tlb_cmiss, tlb_chit));
-    std::ignore = fprintf(stderr, "tlb read hit ratio: %.4f\n", TLB_HIT_RATIO(m_s, tlb_rmiss, tlb_rhit));
-    std::ignore = fprintf(stderr, "tlb write hit ratio: %.4f\n", TLB_HIT_RATIO(m_s, tlb_wmiss, tlb_whit));
-    std::ignore = fprintf(stderr, "tlb_chit: %" PRIu64 "\n", m_s.stats.tlb_chit);
-    std::ignore = fprintf(stderr, "tlb_cmiss: %" PRIu64 "\n", m_s.stats.tlb_cmiss);
-    std::ignore = fprintf(stderr, "tlb_rhit: %" PRIu64 "\n", m_s.stats.tlb_rhit);
-    std::ignore = fprintf(stderr, "tlb_rmiss: %" PRIu64 "\n", m_s.stats.tlb_rmiss);
-    std::ignore = fprintf(stderr, "tlb_whit: %" PRIu64 "\n", m_s.stats.tlb_whit);
-    std::ignore = fprintf(stderr, "tlb_wmiss: %" PRIu64 "\n", m_s.stats.tlb_wmiss);
-    std::ignore = fprintf(stderr, "tlb_flush_all: %" PRIu64 "\n", m_s.stats.tlb_flush_all);
-    std::ignore = fprintf(stderr, "tlb_flush_read: %" PRIu64 "\n", m_s.stats.tlb_flush_read);
-    std::ignore = fprintf(stderr, "tlb_flush_write: %" PRIu64 "\n", m_s.stats.tlb_flush_write);
-    std::ignore = fprintf(stderr, "tlb_flush_vaddr: %" PRIu64 "\n", m_s.stats.tlb_flush_vaddr);
-    std::ignore = fprintf(stderr, "tlb_flush_satp: %" PRIu64 "\n", m_s.stats.tlb_flush_satp);
-    std::ignore = fprintf(stderr, "tlb_flush_mstatus: %" PRIu64 "\n", m_s.stats.tlb_flush_mstatus);
-    std::ignore = fprintf(stderr, "tlb_flush_set_prv: %" PRIu64 "\n", m_s.stats.tlb_flush_set_prv);
-    std::ignore = fprintf(stderr, "tlb_flush_fence_vma_all: %" PRIu64 "\n", m_s.stats.tlb_flush_fence_vma_all);
-    std::ignore = fprintf(stderr, "tlb_flush_fence_vma_asid: %" PRIu64 "\n", m_s.stats.tlb_flush_fence_vma_asid);
-    std::ignore = fprintf(stderr, "tlb_flush_fence_vma_vaddr: %" PRIu64 "\n", m_s.stats.tlb_flush_fence_vma_vaddr);
-    std::ignore =
-        fprintf(stderr, "tlb_flush_fence_vma_asid_vaddr: %" PRIu64 "\n", m_s.stats.tlb_flush_fence_vma_asid_vaddr);
-#endif
+    dump_insn_hist();
+    dump_stats();
 }
 
 uint64_t machine::read_reg(reg r) const {
@@ -2536,4 +2549,27 @@ std::pair<uint64_t, execute_status> machine::poll_external_interrupts(uint64_t m
     return {mcycle, status};
 }
 
+std::string machine::get_counter_key(const char *name, const char *domain) {
+    if (name == nullptr) {
+        throw std::invalid_argument{"invalid name argument"};
+    }
+    std::string key{(domain != nullptr) ? domain : name};
+    if (domain != nullptr) {
+        key.append(name);
+    }
+    return key;
+}
+
+void machine::increment_counter(const char *name, const char *domain) {
+    ++m_counters[get_counter_key(name, domain)];
+}
+
+uint64_t machine::read_counter(const char *name, const char *domain) {
+    return m_counters[get_counter_key(name, domain)];
+}
+
+void machine::write_counter(uint64_t val, const char *name, const char *domain) {
+    m_counters[get_counter_key(name, domain)] = val;
+}
+
 } // namespace cartesi
diff --git a/src/machine.h b/src/machine.h
index 8bc7e98cc..6a83602c0 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -26,6 +26,7 @@
 #include <vector>
 
 #include <boost/container/static_vector.hpp>
+#include <unordered_map>
 
 #include "access-log.h"
 #include "host-addr.h"
@@ -75,6 +76,8 @@ class machine final {
     static const pma_entry::flags m_cmio_rx_buffer_flags; ///< PMA flags used for cmio rx buffer
     static const pma_entry::flags m_cmio_tx_buffer_flags; ///< PMA flags used for cmio tx buffer
 
+    std::unordered_map<std::string, uint64_t> m_counters;
+
     /// \brief Allocates a new PMA entry.
     /// \param pma PMA entry to add to machine.
     /// \returns Reference to corresponding entry in machine state.
@@ -135,6 +138,18 @@ class machine final {
     /// \param config Microarchitecture configuration
     void init_uarch(const uarch_config &config);
 
+    /// \brief Dumps statistics
+    void dump_stats();
+
+    /// \brief Dumps instruction histogram
+    void dump_insn_hist();
+
+    /// \brief Returns key to counter
+    /// \param name Counter name.
+    /// \param domain Counter domain. Can be nullptr. Otherwise, should end with a dot '.'
+    /// \details The counter is key is the concatenation of \p domain with \p name.
+    static std::string get_counter_key(const char *name, const char *domain = nullptr);
+
 public:
     /// \brief Type of hash
     using hash_type = machine_merkle_tree::hash_type;
@@ -546,6 +561,30 @@ class machine final {
     /// \param paddr Target physical address of interest
     /// \returns Description of what is at that address
     static const char *get_what_name(uint64_t paddr);
+
+    /// \brief Increments a counter
+    /// \param name Counter name.
+    /// \param domain Counter domain. Can be nullptr. Otherwise, should end with a dot '.'
+    /// \details The counter is identified by the concatenation of \p domain with \p name.
+    void increment_counter(const char *name, const char *domain = nullptr);
+
+    /// \brief Writes value to counter
+    /// \param val Value to write.
+    /// \param name Counter name.
+    /// \param domain Counter domain. Can be nullptr. Otherwise, should end with a dot '.'
+    /// \details The counter is identified by the concatenation of \p domain with \p name.
+    void write_counter(uint64_t val, const char *name, const char *domain = nullptr);
+
+    /// \brief Returns value in counter
+    /// \param name Counter name.
+    /// \param domain Counter domain. Can be nullptr. Otherwise, should end with a dot '.'
+    /// \details The counter is identified by the concatenation of \p domain with \p name.
+    uint64_t read_counter(const char *name, const char *domain = nullptr);
+
+    /// \brief Returns all counters
+    const auto &get_counters() {
+        return m_counters;
+    }
 };
 
 } // namespace cartesi
diff --git a/src/state-access.h b/src/state-access.h
index ffa98c7b2..c0ef6ea68 100644
--- a/src/state-access.h
+++ b/src/state-access.h
@@ -29,6 +29,7 @@
 #include "compiler-defines.h"
 #include "host-addr.h"
 #include "i-accept-scoped-note.h"
+#include "i-counters.h"
 #include "i-interactive-state-access.h"
 #include "i-state-access.h"
 #include "interpret.h"
@@ -62,7 +63,9 @@ struct i_state_access_fast_addr<state_access> {
 class state_access :
     public i_state_access<state_access>,
     public i_interactive_state_access<state_access>,
-    public i_accept_scoped_note<state_access> {
+    public i_accept_scoped_note<state_access>,
+    public i_counters<state_access> {
+
     // NOLINTNEXTLINE(cppcoreguidelines-avoid-const-or-ref-data-members)
     machine &m_m; ///< Associated machine
 
@@ -73,19 +76,7 @@ class state_access :
         ;
     }
 
-    const machine &get_naked_machine() const {
-        return m_m;
-    }
-
-    machine &get_naked_machine() {
-        return m_m;
-    }
-
 private:
-    machine_state &do_get_naked_state() {
-        return m_m.get_state();
-    }
-
     // -----
     // i_state_access interface implementation
     // -----
@@ -511,12 +502,6 @@ class state_access :
         return "state_access";
     }
 
-#ifdef DUMP_COUNTERS
-    machine_statistics &do_get_statistics() {
-        return m_m.get_state().stats;
-    }
-#endif
-
     // -----
     // i_intereactive_state_access interface implementation
     // -----
@@ -535,6 +520,23 @@ class state_access :
         os_poll_tty(0);
         return os_getchar();
     }
+
+    // -----
+    // i_counters interface implementation
+    // -----
+    friend i_counters<state_access>;
+
+    void do_increment_counter(const char *name, const char *domain) {
+        m_m.increment_counter(name, domain);
+    }
+
+    uint64_t do_read_counter(const char *name, const char *domain) {
+        return m_m.read_counter(name, domain);
+    }
+
+    void do_write_counter(uint64_t val, const char *name, const char *domain) {
+        m_m.write_counter(val, name, domain);
+    }
 };
 
 } // namespace cartesi
diff --git a/src/uarch-solidity-compat.h b/src/uarch-solidity-compat.h
index 6f66278d0..c47a8968a 100644
--- a/src/uarch-solidity-compat.h
+++ b/src/uarch-solidity-compat.h
@@ -21,7 +21,9 @@
 #include <cmath>
 #include <cstdint>
 #include <stdexcept>
-#ifdef DUMP_INSN
+
+#ifdef DUMP_UARCH_INSN
+#include "dump.h"
 #include <cinttypes>
 #endif
 
@@ -226,13 +228,14 @@ void require([[maybe_unused]] T1 condition, [[maybe_unused]] T2 message) {
 }
 
 template <typename UarchState>
-static void dumpInsn([[maybe_unused]] UarchState &a, [[maybe_unused]] uint64 pc, [[maybe_unused]] uint32 insn,
+static auto dumpInsn([[maybe_unused]] UarchState &a, [[maybe_unused]] uint64 pc, [[maybe_unused]] uint32 insn,
     [[maybe_unused]] const char *name) {
-#ifdef DUMP_INSN
-    fprintf(stderr, "%08" PRIx64, pc);
-    fprintf(stderr, ":   %08" PRIx32 "   ", insn);
-    fprintf(stderr, "%s\n", name);
+#ifdef DUMP_UARCH_INSN
+    D_PRINTF("ua %08" PRIx64, pc);
+    D_PRINTF(":   %08" PRIx32 "   ", insn);
+    D_PRINTF("%s\n", name);
 #endif
+    return a.make_scoped_note(name);
 }
 
 } // namespace cartesi
diff --git a/src/uarch-step.cpp b/src/uarch-step.cpp
index 6e2466aff..7c6e97fcb 100644
--- a/src/uarch-step.cpp
+++ b/src/uarch-step.cpp
@@ -179,7 +179,7 @@ static inline void branch(UarchState &a, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeLUI(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("lui");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "lui");
     uint8 rd = operandRd(insn);
     int32 imm = operandImm20(insn);
     if (rd != 0) {
@@ -190,7 +190,7 @@ static inline void executeLUI(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeAUIPC(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("auipc");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "auipc");
     int32 imm = operandImm20(insn);
     uint8 rd = operandRd(insn);
     if (rd != 0) {
@@ -201,7 +201,7 @@ static inline void executeAUIPC(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeJAL(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("jal");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "jal");
     int32 imm = operandJimm20(insn);
     uint8 rd = operandRd(insn);
     if (rd != 0) {
@@ -212,7 +212,7 @@ static inline void executeJAL(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeJALR(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("jalr");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "jalr");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -225,7 +225,7 @@ static inline void executeJALR(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeBEQ(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("beq");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "beq");
     int32 imm = operandSbimm12(insn);
     uint8 rs1 = operandRs1(insn);
     uint8 rs2 = operandRs2(insn);
@@ -239,7 +239,7 @@ static inline void executeBEQ(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeBNE(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("bne");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "bne");
     int32 imm = operandSbimm12(insn);
     uint8 rs1 = operandRs1(insn);
     uint8 rs2 = operandRs2(insn);
@@ -253,7 +253,7 @@ static inline void executeBNE(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeBLT(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("blt");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "blt");
     int32 imm = operandSbimm12(insn);
     uint8 rs1 = operandRs1(insn);
     uint8 rs2 = operandRs2(insn);
@@ -267,7 +267,7 @@ static inline void executeBLT(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeBGE(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("bge");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "bge");
     int32 imm = operandSbimm12(insn);
     uint8 rs1 = operandRs1(insn);
     uint8 rs2 = operandRs2(insn);
@@ -281,7 +281,7 @@ static inline void executeBGE(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeBLTU(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("bltu");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "bltu");
     int32 imm = operandSbimm12(insn);
     uint8 rs1 = operandRs1(insn);
     uint8 rs2 = operandRs2(insn);
@@ -295,7 +295,7 @@ static inline void executeBLTU(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeBGEU(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("bgeu");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "bgeu");
     int32 imm = operandSbimm12(insn);
     uint8 rs1 = operandRs1(insn);
     uint8 rs2 = operandRs2(insn);
@@ -309,7 +309,7 @@ static inline void executeBGEU(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeLB(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("lb");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "lb");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -323,7 +323,7 @@ static inline void executeLB(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeLHU(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("lhu");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "lhu");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -337,7 +337,7 @@ static inline void executeLHU(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeLH(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("lh");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "lh");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -351,7 +351,7 @@ static inline void executeLH(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeLW(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("lw");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "lw");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -365,7 +365,7 @@ static inline void executeLW(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeLBU(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("lbu");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "lbu");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -379,7 +379,7 @@ static inline void executeLBU(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeSB(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("sb");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "sb");
     int32 imm = operandSimm12(insn);
     uint8 rs1 = operandRs1(insn);
     uint8 rs2 = operandRs2(insn);
@@ -391,7 +391,7 @@ static inline void executeSB(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeSH(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("sh");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "sh");
     int32 imm = operandSimm12(insn);
     uint8 rs1 = operandRs1(insn);
     uint8 rs2 = operandRs2(insn);
@@ -403,7 +403,7 @@ static inline void executeSH(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeSW(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("sw");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "sw");
     int32 imm = operandSimm12(insn);
     uint8 rs1 = operandRs1(insn);
     uint8 rs2 = operandRs2(insn);
@@ -415,7 +415,7 @@ static inline void executeSW(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeADDI(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("addi");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "addi");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -429,7 +429,7 @@ static inline void executeADDI(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeADDIW(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("addiw");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "addiw");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -443,7 +443,7 @@ static inline void executeADDIW(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeSLTI(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("slti");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "slti");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -460,7 +460,7 @@ static inline void executeSLTI(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeSLTIU(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("sltiu");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "sltiu");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -477,7 +477,7 @@ static inline void executeSLTIU(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeXORI(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("xori");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "xori");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -490,7 +490,7 @@ static inline void executeXORI(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeORI(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("ori");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "ori");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -503,7 +503,7 @@ static inline void executeORI(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeANDI(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("andi");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "andi");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -516,7 +516,7 @@ static inline void executeANDI(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeSLLI(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("slli");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "slli");
     int32 imm = operandShamt6(insn);
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -529,7 +529,7 @@ static inline void executeSLLI(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeSLLIW(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("slliw");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "slliw");
     int32 imm = operandShamt5(insn);
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -542,7 +542,7 @@ static inline void executeSLLIW(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeSRLI(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("srli");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "srli");
     int32 imm = operandShamt6(insn);
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -555,7 +555,7 @@ static inline void executeSRLI(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeSRLW(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("srlw");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "srlw");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
     uint8 rs2 = operandRs2(insn);
@@ -570,7 +570,7 @@ static inline void executeSRLW(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeSRLIW(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("srliw");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "srliw");
     int32 imm = operandShamt5(insn);
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -584,7 +584,7 @@ static inline void executeSRLIW(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeSRAI(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("srai");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "srai");
     int32 imm = operandShamt6(insn);
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -597,7 +597,7 @@ static inline void executeSRAI(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeSRAIW(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("sraiw");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "sraiw");
     int32 imm = operandShamt5(insn);
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -610,7 +610,7 @@ static inline void executeSRAIW(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeADD(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("add");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "add");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
     uint8 rs2 = operandRs2(insn);
@@ -624,7 +624,7 @@ static inline void executeADD(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeADDW(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("addw");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "addw");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
     uint8 rs2 = operandRs2(insn);
@@ -639,7 +639,7 @@ static inline void executeADDW(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeSUB(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("sub");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "sub");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
     uint8 rs2 = operandRs2(insn);
@@ -653,7 +653,7 @@ static inline void executeSUB(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeSUBW(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("subw");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "subw");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
     uint8 rs2 = operandRs2(insn);
@@ -668,7 +668,7 @@ static inline void executeSUBW(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeSLL(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("sll");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "sll");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
     uint8 rs2 = operandRs2(insn);
@@ -682,7 +682,7 @@ static inline void executeSLL(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeSLLW(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("sllw");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "sllw");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
     uint8 rs2 = operandRs2(insn);
@@ -697,7 +697,7 @@ static inline void executeSLLW(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeSLT(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("slt");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "slt");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
     uint8 rs2 = operandRs2(insn);
@@ -715,7 +715,7 @@ static inline void executeSLT(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeSLTU(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("sltu");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "sltu");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
     uint8 rs2 = operandRs2(insn);
@@ -733,7 +733,7 @@ static inline void executeSLTU(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeXOR(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("xor");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "xor");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
     uint8 rs2 = operandRs2(insn);
@@ -747,7 +747,7 @@ static inline void executeXOR(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeSRL(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("srl");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "srl");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
     uint8 rs2 = operandRs2(insn);
@@ -761,7 +761,7 @@ static inline void executeSRL(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeSRA(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("sra");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "sra");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
     uint8 rs2 = operandRs2(insn);
@@ -775,7 +775,7 @@ static inline void executeSRA(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeSRAW(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("sraw");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "sraw");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
     uint8 rs2 = operandRs2(insn);
@@ -790,7 +790,7 @@ static inline void executeSRAW(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeOR(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("or");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "or");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
     uint8 rs2 = operandRs2(insn);
@@ -804,7 +804,7 @@ static inline void executeOR(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeAND(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("and");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "and");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
     uint8 rs2 = operandRs2(insn);
@@ -817,14 +817,14 @@ static inline void executeAND(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeFENCE(UarchState &a, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("fence");
+static inline void executeFENCE(UarchState &a, uint32 insn, uint64 pc) {
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "fence");
     return advancePc(a, pc);
 }
 
 template <typename UarchState>
 static inline void executeLWU(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("lwu");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "lwu");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -838,7 +838,7 @@ static inline void executeLWU(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeLD(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("ld");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "ld");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -852,7 +852,7 @@ static inline void executeLD(UarchState &a, uint32 insn, uint64 pc) {
 
 template <typename UarchState>
 static inline void executeSD(UarchState &a, uint32 insn, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("sd");
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "sd");
     int32 imm = operandSimm12(insn);
     uint8 rs1 = operandRs1(insn);
     uint8 rs2 = operandRs2(insn);
@@ -863,8 +863,8 @@ static inline void executeSD(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeECALL(UarchState &a, uint64 pc) {
-    [[maybe_unused]] auto note = a.make_scoped_note("ecall");
+static inline void executeECALL(UarchState &a, uint32 insn, uint64 pc) {
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "ecall");
     // ECALL conventions
     // a0--a7 are the same as x10--x17
     // syscall is passed in a7
@@ -899,8 +899,8 @@ static inline void executeECALL(UarchState &a, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeEBREAK(UarchState &a) {
-    [[maybe_unused]] auto note = a.make_scoped_note("ebreak");
+static inline void executeEBREAK(UarchState &a, uint32 insn, uint64 pc) {
+    [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "ebreak");
     throwRuntimeError(a, "uarch aborted");
 }
 
@@ -1079,13 +1079,13 @@ static inline void executeInsn(UarchState &a, uint32 insn, uint64 pc) {
         return executeSLTI(a, insn, pc);
     }
     if (insnMatchOpcodeFunct3(insn, 0xf, 0x0)) {
-        return executeFENCE(a, pc);
+        return executeFENCE(a, insn, pc);
     }
     if (insn == uint32(0x73)) {
-        return executeECALL(a, pc);
+        return executeECALL(a, insn, pc);
     }
     if (insn == uint32(0x100073)) {
-        return executeEBREAK(a);
+        return executeEBREAK(a, insn, pc);
     }
     throwRuntimeError(a, "illegal instruction");
 }

From 2bc0eb45be3c389d114dd05d6acbe1137df6b335 Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Fri, 7 Feb 2025 10:59:06 +0000
Subject: [PATCH 12/82] refactor: move uarch-printf to uarch/third-party

---
 uarch/Makefile                                |    8 +-
 uarch/third-party/printf/LICENSE              |   22 +
 .../printf/printf.c}                          | 1835 +++++++++--------
 .../printf/printf.h}                          |  217 +-
 uarch/uarch-runtime.h                         |    5 +-
 5 files changed, 1060 insertions(+), 1027 deletions(-)
 create mode 100644 uarch/third-party/printf/LICENSE
 rename uarch/{uarch-printf.c => third-party/printf/printf.c} (96%)
 rename uarch/{uarch-printf.h => third-party/printf/printf.h} (79%)

diff --git a/uarch/Makefile b/uarch/Makefile
index ba20dd7cb..6b93c1d7a 100644
--- a/uarch/Makefile
+++ b/uarch/Makefile
@@ -61,7 +61,7 @@ CFLAGS := -march=rv64i -mabi=lp64 -Wl,--gc-sections $(OPTFLAGS) $(UBFLAGS) $(WAR
 CXXFLAGS := -std=c++20 -fno-rtti
 
 UARCH_SOURCES=\
-	uarch-printf.c \
+	third-party/printf/printf.c \
 	uarch-run.cpp \
 	uarch-ecall.c \
 	uarch-runtime.cpp
@@ -90,10 +90,8 @@ UARCH_OBJS = $(patsubst %.c,%.uarch_c.o,$(patsubst %.cpp,%.uarch_cpp.o,$(UARCH_S
 EMULATOR_OBJS = $(patsubst %.c,%.emulator_c.o,$(patsubst %.cpp,%.emulator_cpp.o,$(EMULATOR_SOURCES)))
 COMPUTE_OBJS = $(patsubst %.c,%.compute_c.o,$(patsubst %.cpp,%.compute_cpp.o,$(COMPUTE_SOURCES)))
 
-LINTER_IGNORE_SOURCES=uarch-printf.c uarch-pristine-hash.c uarch-pristine-ram.c
-LINTER_IGNORE_HEADERS=uarch-printf.h
-LINTER_SOURCES=$(filter-out $(LINTER_IGNORE_SOURCES),$(strip $(wildcard uarch-*.cpp) $(wildcard uarch-*.c)))
-LINTER_HEADERS=$(filter-out $(LINTER_IGNORE_HEADERS),$(strip $(wildcard uarch-*.h)))
+LINTER_SOURCES=$($(strip $(wildcard uarch-*.cpp) $(wildcard uarch-*.c)))
+LINTER_HEADERS=$($(strip $(wildcard uarch-*.h)))
 EMPTY:=
 SPACE:=$(EMPTY) $(EMPTY)
 CLANG_TIDY_HEADER_FILTER=$(CURDIR)/($(subst $(SPACE),|,$(LINTER_HEADERS)))
diff --git a/uarch/third-party/printf/LICENSE b/uarch/third-party/printf/LICENSE
new file mode 100644
index 000000000..8f7ebd0b9
--- /dev/null
+++ b/uarch/third-party/printf/LICENSE
@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Marco Paland
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
diff --git a/uarch/uarch-printf.c b/uarch/third-party/printf/printf.c
similarity index 96%
rename from uarch/uarch-printf.c
rename to uarch/third-party/printf/printf.c
index 70254e586..268ed54a6 100644
--- a/uarch/uarch-printf.c
+++ b/uarch/third-party/printf/printf.c
@@ -1,917 +1,918 @@
-///////////////////////////////////////////////////////////////////////////////
-// \author (c) Marco Paland (info@paland.com)
-//             2014-2019, PALANDesign Hannover, Germany
-//
-// \license The MIT License (MIT)
-//
-// Permission is hereby granted, free of charge, to any person obtaining a copy
-// of this software and associated documentation files (the "Software"), to deal
-// in the Software without restriction, including without limitation the rights
-// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-// copies of the Software, and to permit persons to whom the Software is
-// furnished to do so, subject to the following conditions:
-//
-// The above copyright notice and this permission notice shall be included in
-// all copies or substantial portions of the Software.
-//
-// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-// THE SOFTWARE.
-//
-// \brief Tiny printf, sprintf and (v)snprintf implementation, optimized for speed on
-//        embedded systems with a very limited resources. These routines are thread
-//        safe and reentrant!
-//        Use this instead of the bloated standard/newlib printf cause these use
-//        malloc for printf (and may not be thread safe).
-//
-///////////////////////////////////////////////////////////////////////////////
-
-#define PRINTF_DISABLE_SUPPORT_FLOAT
-#define PRINTF_DISABLE_SUPPORT_EXPONENTIAL
-
-#include <stdbool.h>
-#include <stdint.h>
-
-#include "uarch-printf.h"
-#include "uarch-ecall.h"
-
-// define this globally (e.g. gcc -DPRINTF_INCLUDE_CONFIG_H ...) to include the
-// printf_config.h header file
-// default: undefined
-#ifdef PRINTF_INCLUDE_CONFIG_H
-#include "printf_config.h"
-#endif
-
-
-// 'ntoa' conversion buffer size, this must be big enough to hold one converted
-// numeric number including padded zeros (dynamically created on stack)
-// default: 32 byte
-#ifndef PRINTF_NTOA_BUFFER_SIZE
-#define PRINTF_NTOA_BUFFER_SIZE    32U
-#endif
-
-// 'ftoa' conversion buffer size, this must be big enough to hold one converted
-// float number including padded zeros (dynamically created on stack)
-// default: 32 byte
-#ifndef PRINTF_FTOA_BUFFER_SIZE
-#define PRINTF_FTOA_BUFFER_SIZE    32U
-#endif
-
-// support for the floating point type (%f)
-// default: activated
-#ifndef PRINTF_DISABLE_SUPPORT_FLOAT
-#define PRINTF_SUPPORT_FLOAT
-#endif
-
-// support for exponential floating point notation (%e/%g)
-// default: activated
-#ifndef PRINTF_DISABLE_SUPPORT_EXPONENTIAL
-#define PRINTF_SUPPORT_EXPONENTIAL
-#endif
-
-// define the default floating point precision
-// default: 6 digits
-#ifndef PRINTF_DEFAULT_FLOAT_PRECISION
-#define PRINTF_DEFAULT_FLOAT_PRECISION  6U
-#endif
-
-// define the largest float suitable to print with %f
-// default: 1e9
-#ifndef PRINTF_MAX_FLOAT
-#define PRINTF_MAX_FLOAT  1e9
-#endif
-
-// support for the long long types (%llu or %p)
-// default: activated
-#ifndef PRINTF_DISABLE_SUPPORT_LONG_LONG
-#define PRINTF_SUPPORT_LONG_LONG
-#endif
-
-// support for the ptrdiff_t type (%t)
-// ptrdiff_t is normally defined in <stddef.h> as long or long long type
-// default: activated
-#ifndef PRINTF_DISABLE_SUPPORT_PTRDIFF_T
-#define PRINTF_SUPPORT_PTRDIFF_T
-#endif
-
-///////////////////////////////////////////////////////////////////////////////
-
-// internal flag definitions
-#define FLAGS_ZEROPAD   (1U <<  0U)
-#define FLAGS_LEFT      (1U <<  1U)
-#define FLAGS_PLUS      (1U <<  2U)
-#define FLAGS_SPACE     (1U <<  3U)
-#define FLAGS_HASH      (1U <<  4U)
-#define FLAGS_UPPERCASE (1U <<  5U)
-#define FLAGS_CHAR      (1U <<  6U)
-#define FLAGS_SHORT     (1U <<  7U)
-#define FLAGS_LONG      (1U <<  8U)
-#define FLAGS_LONG_LONG (1U <<  9U)
-#define FLAGS_PRECISION (1U << 10U)
-#define FLAGS_ADAPT_EXP (1U << 11U)
-
-
-// import float.h for DBL_MAX
-#if defined(PRINTF_SUPPORT_FLOAT)
-#include <float.h>
-#endif
-
-
-// output function type
-typedef void (*out_fct_type)(char character, void* buffer, size_t idx, size_t maxlen);
-
-
-// wrapper (used as buffer) for output function type
-typedef struct {
-  void  (*fct)(char character, void* arg);
-  void* arg;
-} out_fct_wrap_type;
-
-
-// internal buffer output
-static inline void _out_buffer(char character, void* buffer, size_t idx, size_t maxlen)
-{
-  if (idx < maxlen) {
-    ((char*)buffer)[idx] = character;
-  }
-}
-
-
-// internal null output
-static inline void _out_null(char character, void* buffer, size_t idx, size_t maxlen)
-{
-  (void)character; (void)buffer; (void)idx; (void)maxlen;
-}
-
-
-// internal _putchar wrapper
-static inline void _out_char(char character, void* buffer, size_t idx, size_t maxlen)
-{
-  (void)buffer; (void)idx; (void)maxlen;
-  if (character) {
-    ua_putchar_ECALL(character);
-  }
-}
-
-
-// internal output function wrapper
-static inline void _out_fct(char character, void* buffer, size_t idx, size_t maxlen)
-{
-  (void)idx; (void)maxlen;
-  if (character) {
-    // buffer is the output fct pointer
-    ((out_fct_wrap_type*)buffer)->fct(character, ((out_fct_wrap_type*)buffer)->arg);
-  }
-}
-
-
-// internal secure strlen
-// \return The length of the string (excluding the terminating 0) limited by 'maxsize'
-static inline unsigned int _strnlen_s(const char* str, size_t maxsize)
-{
-  const char* s;
-  for (s = str; *s && maxsize--; ++s);
-  return (unsigned int)(s - str);
-}
-
-
-// internal test if char is a digit (0-9)
-// \return true if char is a digit
-static inline bool _is_digit(char ch)
-{
-  return (ch >= '0') && (ch <= '9');
-}
-
-
-// internal ASCII string to unsigned int conversion
-static unsigned int _atoi(const char** str)
-{
-  unsigned int i = 0U;
-  while (_is_digit(**str)) {
-    i = i * 10U + (unsigned int)(*((*str)++) - '0');
-  }
-  return i;
-}
-
-
-// output the specified string in reverse, taking care of any zero-padding
-static size_t _out_rev(out_fct_type out, char* buffer, size_t idx, size_t maxlen, const char* buf, size_t len, unsigned int width, unsigned int flags)
-{
-  const size_t start_idx = idx;
-
-  // pad spaces up to given width
-  if (!(flags & FLAGS_LEFT) && !(flags & FLAGS_ZEROPAD)) {
-    for (size_t i = len; i < width; i++) {
-      out(' ', buffer, idx++, maxlen);
-    }
-  }
-
-  // reverse string
-  while (len) {
-    out(buf[--len], buffer, idx++, maxlen);
-  }
-
-  // append pad spaces up to given width
-  if (flags & FLAGS_LEFT) {
-    while (idx - start_idx < width) {
-      out(' ', buffer, idx++, maxlen);
-    }
-  }
-
-  return idx;
-}
-
-
-// internal itoa format
-static size_t _ntoa_format(out_fct_type out, char* buffer, size_t idx, size_t maxlen, char* buf, size_t len, bool negative, unsigned int base, unsigned int prec, unsigned int width, unsigned int flags)
-{
-  // pad leading zeros
-  if (!(flags & FLAGS_LEFT)) {
-    if (width && (flags & FLAGS_ZEROPAD) && (negative || (flags & (FLAGS_PLUS | FLAGS_SPACE)))) {
-      width--;
-    }
-    while ((len < prec) && (len < PRINTF_NTOA_BUFFER_SIZE)) {
-      buf[len++] = '0';
-    }
-    while ((flags & FLAGS_ZEROPAD) && (len < width) && (len < PRINTF_NTOA_BUFFER_SIZE)) {
-      buf[len++] = '0';
-    }
-  }
-
-  // handle hash
-  if (flags & FLAGS_HASH) {
-    if (!(flags & FLAGS_PRECISION) && len && ((len == prec) || (len == width))) {
-      len--;
-      if (len && (base == 16U)) {
-        len--;
-      }
-    }
-    if ((base == 16U) && !(flags & FLAGS_UPPERCASE) && (len < PRINTF_NTOA_BUFFER_SIZE)) {
-      buf[len++] = 'x';
-    }
-    else if ((base == 16U) && (flags & FLAGS_UPPERCASE) && (len < PRINTF_NTOA_BUFFER_SIZE)) {
-      buf[len++] = 'X';
-    }
-    else if ((base == 2U) && (len < PRINTF_NTOA_BUFFER_SIZE)) {
-      buf[len++] = 'b';
-    }
-    if (len < PRINTF_NTOA_BUFFER_SIZE) {
-      buf[len++] = '0';
-    }
-  }
-
-  if (len < PRINTF_NTOA_BUFFER_SIZE) {
-    if (negative) {
-      buf[len++] = '-';
-    }
-    else if (flags & FLAGS_PLUS) {
-      buf[len++] = '+';  // ignore the space if the '+' exists
-    }
-    else if (flags & FLAGS_SPACE) {
-      buf[len++] = ' ';
-    }
-  }
-
-  return _out_rev(out, buffer, idx, maxlen, buf, len, width, flags);
-}
-
-
-// internal itoa for 'long' type
-static size_t _ntoa_long(out_fct_type out, char* buffer, size_t idx, size_t maxlen, unsigned long value, bool negative, unsigned long base, unsigned int prec, unsigned int width, unsigned int flags)
-{
-  char buf[PRINTF_NTOA_BUFFER_SIZE];
-  size_t len = 0U;
-
-  // no hash for 0 values
-  if (!value) {
-    flags &= ~FLAGS_HASH;
-  }
-
-  // write if precision != 0 and value is != 0
-  if (!(flags & FLAGS_PRECISION) || value) {
-    do {
-      const char digit = (char)(value % base);
-      buf[len++] = digit < 10 ? '0' + digit : (flags & FLAGS_UPPERCASE ? 'A' : 'a') + digit - 10;
-      value /= base;
-    } while (value && (len < PRINTF_NTOA_BUFFER_SIZE));
-  }
-
-  return _ntoa_format(out, buffer, idx, maxlen, buf, len, negative, (unsigned int)base, prec, width, flags);
-}
-
-
-// internal itoa for 'long long' type
-#if defined(PRINTF_SUPPORT_LONG_LONG)
-static size_t _ntoa_long_long(out_fct_type out, char* buffer, size_t idx, size_t maxlen, unsigned long long value, bool negative, unsigned long long base, unsigned int prec, unsigned int width, unsigned int flags)
-{
-  char buf[PRINTF_NTOA_BUFFER_SIZE];
-  size_t len = 0U;
-
-  // no hash for 0 values
-  if (!value) {
-    flags &= ~FLAGS_HASH;
-  }
-
-  // write if precision != 0 and value is != 0
-  if (!(flags & FLAGS_PRECISION) || value) {
-    do {
-      const char digit = (char)(value % base);
-      buf[len++] = digit < 10 ? '0' + digit : (flags & FLAGS_UPPERCASE ? 'A' : 'a') + digit - 10;
-      value /= base;
-    } while (value && (len < PRINTF_NTOA_BUFFER_SIZE));
-  }
-
-  return _ntoa_format(out, buffer, idx, maxlen, buf, len, negative, (unsigned int)base, prec, width, flags);
-}
-#endif  // PRINTF_SUPPORT_LONG_LONG
-
-
-#if defined(PRINTF_SUPPORT_FLOAT)
-
-#if defined(PRINTF_SUPPORT_EXPONENTIAL)
-// forward declaration so that _ftoa can switch to exp notation for values > PRINTF_MAX_FLOAT
-static size_t _etoa(out_fct_type out, char* buffer, size_t idx, size_t maxlen, double value, unsigned int prec, unsigned int width, unsigned int flags);
-#endif
-
-
-// internal ftoa for fixed decimal floating point
-static size_t _ftoa(out_fct_type out, char* buffer, size_t idx, size_t maxlen, double value, unsigned int prec, unsigned int width, unsigned int flags)
-{
-  char buf[PRINTF_FTOA_BUFFER_SIZE];
-  size_t len  = 0U;
-  double diff = 0.0;
-
-  // powers of 10
-  static const double pow10[] = { 1, 10, 100, 1000, 10000, 100000, 1000000, 10000000, 100000000, 1000000000 };
-
-  // test for special values
-  if (value != value)
-    return _out_rev(out, buffer, idx, maxlen, "nan", 3, width, flags);
-  if (value < -DBL_MAX)
-    return _out_rev(out, buffer, idx, maxlen, "fni-", 4, width, flags);
-  if (value > DBL_MAX)
-    return _out_rev(out, buffer, idx, maxlen, (flags & FLAGS_PLUS) ? "fni+" : "fni", (flags & FLAGS_PLUS) ? 4U : 3U, width, flags);
-
-  // test for very large values
-  // standard printf behavior is to print EVERY whole number digit -- which could be 100s of characters overflowing your buffers == bad
-  if ((value > PRINTF_MAX_FLOAT) || (value < -PRINTF_MAX_FLOAT)) {
-#if defined(PRINTF_SUPPORT_EXPONENTIAL)
-    return _etoa(out, buffer, idx, maxlen, value, prec, width, flags);
-#else
-    return 0U;
-#endif
-  }
-
-  // test for negative
-  bool negative = false;
-  if (value < 0) {
-    negative = true;
-    value = 0 - value;
-  }
-
-  // set default precision, if not set explicitly
-  if (!(flags & FLAGS_PRECISION)) {
-    prec = PRINTF_DEFAULT_FLOAT_PRECISION;
-  }
-  // limit precision to 9, cause a prec >= 10 can lead to overflow errors
-  while ((len < PRINTF_FTOA_BUFFER_SIZE) && (prec > 9U)) {
-    buf[len++] = '0';
-    prec--;
-  }
-
-  int whole = (int)value;
-  double tmp = (value - whole) * pow10[prec];
-  unsigned long frac = (unsigned long)tmp;
-  diff = tmp - frac;
-
-  if (diff > 0.5) {
-    ++frac;
-    // handle rollover, e.g. case 0.99 with prec 1 is 1.0
-    if (frac >= pow10[prec]) {
-      frac = 0;
-      ++whole;
-    }
-  }
-  else if (diff < 0.5) {
-  }
-  else if ((frac == 0U) || (frac & 1U)) {
-    // if halfway, round up if odd OR if last digit is 0
-    ++frac;
-  }
-
-  if (prec == 0U) {
-    diff = value - (double)whole;
-    if ((!(diff < 0.5) || (diff > 0.5)) && (whole & 1)) {
-      // exactly 0.5 and ODD, then round up
-      // 1.5 -> 2, but 2.5 -> 2
-      ++whole;
-    }
-  }
-  else {
-    unsigned int count = prec;
-    // now do fractional part, as an unsigned number
-    while (len < PRINTF_FTOA_BUFFER_SIZE) {
-      --count;
-      buf[len++] = (char)(48U + (frac % 10U));
-      if (!(frac /= 10U)) {
-        break;
-      }
-    }
-    // add extra 0s
-    while ((len < PRINTF_FTOA_BUFFER_SIZE) && (count-- > 0U)) {
-      buf[len++] = '0';
-    }
-    if (len < PRINTF_FTOA_BUFFER_SIZE) {
-      // add decimal
-      buf[len++] = '.';
-    }
-  }
-
-  // do whole part, number is reversed
-  while (len < PRINTF_FTOA_BUFFER_SIZE) {
-    buf[len++] = (char)(48 + (whole % 10));
-    if (!(whole /= 10)) {
-      break;
-    }
-  }
-
-  // pad leading zeros
-  if (!(flags & FLAGS_LEFT) && (flags & FLAGS_ZEROPAD)) {
-    if (width && (negative || (flags & (FLAGS_PLUS | FLAGS_SPACE)))) {
-      width--;
-    }
-    while ((len < width) && (len < PRINTF_FTOA_BUFFER_SIZE)) {
-      buf[len++] = '0';
-    }
-  }
-
-  if (len < PRINTF_FTOA_BUFFER_SIZE) {
-    if (negative) {
-      buf[len++] = '-';
-    }
-    else if (flags & FLAGS_PLUS) {
-      buf[len++] = '+';  // ignore the space if the '+' exists
-    }
-    else if (flags & FLAGS_SPACE) {
-      buf[len++] = ' ';
-    }
-  }
-
-  return _out_rev(out, buffer, idx, maxlen, buf, len, width, flags);
-}
-
-
-#if defined(PRINTF_SUPPORT_EXPONENTIAL)
-// internal ftoa variant for exponential floating-point type, contributed by Martijn Jasperse <m.jasperse@gmail.com>
-static size_t _etoa(out_fct_type out, char* buffer, size_t idx, size_t maxlen, double value, unsigned int prec, unsigned int width, unsigned int flags)
-{
-  // check for NaN and special values
-  if ((value != value) || (value > DBL_MAX) || (value < -DBL_MAX)) {
-    return _ftoa(out, buffer, idx, maxlen, value, prec, width, flags);
-  }
-
-  // determine the sign
-  const bool negative = value < 0;
-  if (negative) {
-    value = -value;
-  }
-
-  // default precision
-  if (!(flags & FLAGS_PRECISION)) {
-    prec = PRINTF_DEFAULT_FLOAT_PRECISION;
-  }
-
-  // determine the decimal exponent
-  // based on the algorithm by David Gay (https://www.ampl.com/netlib/fp/dtoa.c)
-  union {
-    uint64_t U;
-    double   F;
-  } conv;
-
-  conv.F = value;
-  int exp2 = (int)((conv.U >> 52U) & 0x07FFU) - 1023;           // effectively log2
-  conv.U = (conv.U & ((1ULL << 52U) - 1U)) | (1023ULL << 52U);  // drop the exponent so conv.F is now in [1,2)
-  // now approximate log10 from the log2 integer part and an expansion of ln around 1.5
-  int expval = (int)(0.1760912590558 + exp2 * 0.301029995663981 + (conv.F - 1.5) * 0.289529654602168);
-  // now we want to compute 10^expval but we want to be sure it won't overflow
-  exp2 = (int)(expval * 3.321928094887362 + 0.5);
-  const double z  = expval * 2.302585092994046 - exp2 * 0.6931471805599453;
-  const double z2 = z * z;
-  conv.U = (uint64_t)(exp2 + 1023) << 52U;
-  // compute exp(z) using continued fractions, see https://en.wikipedia.org/wiki/Exponential_function#Continued_fractions_for_ex
-  conv.F *= 1 + 2 * z / (2 - z + (z2 / (6 + (z2 / (10 + z2 / 14)))));
-  // correct for rounding errors
-  if (value < conv.F) {
-    expval--;
-    conv.F /= 10;
-  }
-
-  // the exponent format is "%+03d" and largest value is "307", so set aside 4-5 characters
-  unsigned int minwidth = ((expval < 100) && (expval > -100)) ? 4U : 5U;
-
-  // in "%g" mode, "prec" is the number of *significant figures* not decimals
-  if (flags & FLAGS_ADAPT_EXP) {
-    // do we want to fall-back to "%f" mode?
-    if ((value >= 1e-4) && (value < 1e6)) {
-      if ((int)prec > expval) {
-        prec = (unsigned)((int)prec - expval - 1);
-      }
-      else {
-        prec = 0;
-      }
-      flags |= FLAGS_PRECISION;   // make sure _ftoa respects precision
-      // no characters in exponent
-      minwidth = 0U;
-      expval   = 0;
-    }
-    else {
-      // we use one sigfig for the whole part
-      if ((prec > 0) && (flags & FLAGS_PRECISION)) {
-        --prec;
-      }
-    }
-  }
-
-  // will everything fit?
-  unsigned int fwidth = width;
-  if (width > minwidth) {
-    // we didn't fall-back so subtract the characters required for the exponent
-    fwidth -= minwidth;
-  } else {
-    // not enough characters, so go back to default sizing
-    fwidth = 0U;
-  }
-  if ((flags & FLAGS_LEFT) && minwidth) {
-    // if we're padding on the right, DON'T pad the floating part
-    fwidth = 0U;
-  }
-
-  // rescale the float value
-  if (expval) {
-    value /= conv.F;
-  }
-
-  // output the floating part
-  const size_t start_idx = idx;
-  idx = _ftoa(out, buffer, idx, maxlen, negative ? -value : value, prec, fwidth, flags & ~FLAGS_ADAPT_EXP);
-
-  // output the exponent part
-  if (minwidth) {
-    // output the exponential symbol
-    out((flags & FLAGS_UPPERCASE) ? 'E' : 'e', buffer, idx++, maxlen);
-    // output the exponent value
-    idx = _ntoa_long(out, buffer, idx, maxlen, (expval < 0) ? -expval : expval, expval < 0, 10, 0, minwidth-1, FLAGS_ZEROPAD | FLAGS_PLUS);
-    // might need to right-pad spaces
-    if (flags & FLAGS_LEFT) {
-      while (idx - start_idx < width) out(' ', buffer, idx++, maxlen);
-    }
-  }
-  return idx;
-}
-#endif  // PRINTF_SUPPORT_EXPONENTIAL
-#endif  // PRINTF_SUPPORT_FLOAT
-
-
-// internal vsnprintf
-static int _vsnprintf(out_fct_type out, char* buffer, const size_t maxlen, const char* format, va_list va)
-{
-  unsigned int flags, width, precision, n;
-  size_t idx = 0U;
-
-  if (!buffer) {
-    // use null output function
-    out = _out_null;
-  }
-
-  while (*format)
-  {
-    // format specifier?  %[flags][width][.precision][length]
-    if (*format != '%') {
-      // no
-      out(*format, buffer, idx++, maxlen);
-      format++;
-      continue;
-    }
-    else {
-      // yes, evaluate it
-      format++;
-    }
-
-    // evaluate flags
-    flags = 0U;
-    do {
-      switch (*format) {
-        case '0': flags |= FLAGS_ZEROPAD; format++; n = 1U; break;
-        case '-': flags |= FLAGS_LEFT;    format++; n = 1U; break;
-        case '+': flags |= FLAGS_PLUS;    format++; n = 1U; break;
-        case ' ': flags |= FLAGS_SPACE;   format++; n = 1U; break;
-        case '#': flags |= FLAGS_HASH;    format++; n = 1U; break;
-        default :                                   n = 0U; break;
-      }
-    } while (n);
-
-    // evaluate width field
-    width = 0U;
-    if (_is_digit(*format)) {
-      width = _atoi(&format);
-    }
-    else if (*format == '*') {
-      const int w = va_arg(va, int);
-      if (w < 0) {
-        flags |= FLAGS_LEFT;    // reverse padding
-        width = (unsigned int)-w;
-      }
-      else {
-        width = (unsigned int)w;
-      }
-      format++;
-    }
-
-    // evaluate precision field
-    precision = 0U;
-    if (*format == '.') {
-      flags |= FLAGS_PRECISION;
-      format++;
-      if (_is_digit(*format)) {
-        precision = _atoi(&format);
-      }
-      else if (*format == '*') {
-        const int prec = (int)va_arg(va, int);
-        precision = prec > 0 ? (unsigned int)prec : 0U;
-        format++;
-      }
-    }
-
-    // evaluate length field
-    switch (*format) {
-      case 'l' :
-        flags |= FLAGS_LONG;
-        format++;
-        if (*format == 'l') {
-          flags |= FLAGS_LONG_LONG;
-          format++;
-        }
-        break;
-      case 'h' :
-        flags |= FLAGS_SHORT;
-        format++;
-        if (*format == 'h') {
-          flags |= FLAGS_CHAR;
-          format++;
-        }
-        break;
-#if defined(PRINTF_SUPPORT_PTRDIFF_T)
-      case 't' :
-        flags |= (sizeof(ptrdiff_t) == sizeof(long) ? FLAGS_LONG : FLAGS_LONG_LONG);
-        format++;
-        break;
-#endif
-      case 'j' :
-        flags |= (sizeof(intmax_t) == sizeof(long) ? FLAGS_LONG : FLAGS_LONG_LONG);
-        format++;
-        break;
-      case 'z' :
-        flags |= (sizeof(size_t) == sizeof(long) ? FLAGS_LONG : FLAGS_LONG_LONG);
-        format++;
-        break;
-      default :
-        break;
-    }
-
-    // evaluate specifier
-    switch (*format) {
-      case 'd' :
-      case 'i' :
-      case 'u' :
-      case 'x' :
-      case 'X' :
-      case 'o' :
-      case 'b' : {
-        // set the base
-        unsigned int base;
-        if (*format == 'x' || *format == 'X') {
-          base = 16U;
-        }
-        else if (*format == 'o') {
-          base =  8U;
-        }
-        else if (*format == 'b') {
-          base =  2U;
-        }
-        else {
-          base = 10U;
-          flags &= ~FLAGS_HASH;   // no hash for dec format
-        }
-        // uppercase
-        if (*format == 'X') {
-          flags |= FLAGS_UPPERCASE;
-        }
-
-        // no plus or space flag for u, x, X, o, b
-        if ((*format != 'i') && (*format != 'd')) {
-          flags &= ~(FLAGS_PLUS | FLAGS_SPACE);
-        }
-
-        // ignore '0' flag when precision is given
-        if (flags & FLAGS_PRECISION) {
-          flags &= ~FLAGS_ZEROPAD;
-        }
-
-        // convert the integer
-        if ((*format == 'i') || (*format == 'd')) {
-          // signed
-          if (flags & FLAGS_LONG_LONG) {
-#if defined(PRINTF_SUPPORT_LONG_LONG)
-            const long long value = va_arg(va, long long);
-            idx = _ntoa_long_long(out, buffer, idx, maxlen, (unsigned long long)(value > 0 ? value : 0 - value), value < 0, base, precision, width, flags);
-#endif
-          }
-          else if (flags & FLAGS_LONG) {
-            const long value = va_arg(va, long);
-            idx = _ntoa_long(out, buffer, idx, maxlen, (unsigned long)(value > 0 ? value : 0 - value), value < 0, base, precision, width, flags);
-          }
-          else {
-            const int value = (flags & FLAGS_CHAR) ? (char)va_arg(va, int) : (flags & FLAGS_SHORT) ? (short int)va_arg(va, int) : va_arg(va, int);
-            idx = _ntoa_long(out, buffer, idx, maxlen, (unsigned int)(value > 0 ? value : 0 - value), value < 0, base, precision, width, flags);
-          }
-        }
-        else {
-          // unsigned
-          if (flags & FLAGS_LONG_LONG) {
-#if defined(PRINTF_SUPPORT_LONG_LONG)
-            idx = _ntoa_long_long(out, buffer, idx, maxlen, va_arg(va, unsigned long long), false, base, precision, width, flags);
-#endif
-          }
-          else if (flags & FLAGS_LONG) {
-            idx = _ntoa_long(out, buffer, idx, maxlen, va_arg(va, unsigned long), false, base, precision, width, flags);
-          }
-          else {
-            const unsigned int value = (flags & FLAGS_CHAR) ? (unsigned char)va_arg(va, unsigned int) : (flags & FLAGS_SHORT) ? (unsigned short int)va_arg(va, unsigned int) : va_arg(va, unsigned int);
-            idx = _ntoa_long(out, buffer, idx, maxlen, value, false, base, precision, width, flags);
-          }
-        }
-        format++;
-        break;
-      }
-#if defined(PRINTF_SUPPORT_FLOAT)
-      case 'f' :
-      case 'F' :
-        if (*format == 'F') flags |= FLAGS_UPPERCASE;
-        idx = _ftoa(out, buffer, idx, maxlen, va_arg(va, double), precision, width, flags);
-        format++;
-        break;
-#if defined(PRINTF_SUPPORT_EXPONENTIAL)
-      case 'e':
-      case 'E':
-      case 'g':
-      case 'G':
-        if ((*format == 'g')||(*format == 'G')) flags |= FLAGS_ADAPT_EXP;
-        if ((*format == 'E')||(*format == 'G')) flags |= FLAGS_UPPERCASE;
-        idx = _etoa(out, buffer, idx, maxlen, va_arg(va, double), precision, width, flags);
-        format++;
-        break;
-#endif  // PRINTF_SUPPORT_EXPONENTIAL
-#endif  // PRINTF_SUPPORT_FLOAT
-      case 'c' : {
-        unsigned int l = 1U;
-        // pre padding
-        if (!(flags & FLAGS_LEFT)) {
-          while (l++ < width) {
-            out(' ', buffer, idx++, maxlen);
-          }
-        }
-        // char output
-        out((char)va_arg(va, int), buffer, idx++, maxlen);
-        // post padding
-        if (flags & FLAGS_LEFT) {
-          while (l++ < width) {
-            out(' ', buffer, idx++, maxlen);
-          }
-        }
-        format++;
-        break;
-      }
-
-      case 's' : {
-        const char* p = va_arg(va, char*);
-        unsigned int l = _strnlen_s(p, precision ? precision : (size_t)-1);
-        // pre padding
-        if (flags & FLAGS_PRECISION) {
-          l = (l < precision ? l : precision);
-        }
-        if (!(flags & FLAGS_LEFT)) {
-          while (l++ < width) {
-            out(' ', buffer, idx++, maxlen);
-          }
-        }
-        // string output
-        while ((*p != 0) && (!(flags & FLAGS_PRECISION) || precision--)) {
-          out(*(p++), buffer, idx++, maxlen);
-        }
-        // post padding
-        if (flags & FLAGS_LEFT) {
-          while (l++ < width) {
-            out(' ', buffer, idx++, maxlen);
-          }
-        }
-        format++;
-        break;
-      }
-
-      case 'p' : {
-        width = sizeof(void*) * 2U;
-        flags |= FLAGS_ZEROPAD | FLAGS_UPPERCASE;
-#if defined(PRINTF_SUPPORT_LONG_LONG)
-        const bool is_ll = sizeof(uintptr_t) == sizeof(long long);
-        if (is_ll) {
-          idx = _ntoa_long_long(out, buffer, idx, maxlen, (uintptr_t)va_arg(va, void*), false, 16U, precision, width, flags);
-        }
-        else {
-#endif
-          idx = _ntoa_long(out, buffer, idx, maxlen, (unsigned long)((uintptr_t)va_arg(va, void*)), false, 16U, precision, width, flags);
-#if defined(PRINTF_SUPPORT_LONG_LONG)
-        }
-#endif
-        format++;
-        break;
-      }
-
-      case '%' :
-        out('%', buffer, idx++, maxlen);
-        format++;
-        break;
-
-      default :
-        out(*format, buffer, idx++, maxlen);
-        format++;
-        break;
-    }
-  }
-
-  // termination
-  out((char)0, buffer, idx < maxlen ? idx : maxlen - 1U, maxlen);
-
-  // return written chars without terminating \0
-  return (int)idx;
-}
-
-
-///////////////////////////////////////////////////////////////////////////////
-
-int printf_(const char* format, ...)
-{
-  va_list va;
-  va_start(va, format);
-  char buffer[1];
-  const int ret = _vsnprintf(_out_char, buffer, (size_t)-1, format, va);
-  va_end(va);
-  return ret;
-}
-
-
-int sprintf_(char* buffer, const char* format, ...)
-{
-  va_list va;
-  va_start(va, format);
-  const int ret = _vsnprintf(_out_buffer, buffer, (size_t)-1, format, va);
-  va_end(va);
-  return ret;
-}
-
-
-int snprintf_(char* buffer, size_t count, const char* format, ...)
-{
-  va_list va;
-  va_start(va, format);
-  const int ret = _vsnprintf(_out_buffer, buffer, count, format, va);
-  va_end(va);
-  return ret;
-}
-
-
-int vprintf_(const char* format, va_list va)
-{
-  char buffer[1];
-  return _vsnprintf(_out_char, buffer, (size_t)-1, format, va);
-}
-
-
-int vsnprintf_(char* buffer, size_t count, const char* format, va_list va)
-{
-  return _vsnprintf(_out_buffer, buffer, count, format, va);
-}
-
-
-int fctprintf(void (*out)(char character, void* arg), void* arg, const char* format, ...)
-{
-  va_list va;
-  va_start(va, format);
-  const out_fct_wrap_type out_fct_wrap = { out, arg };
-  const int ret = _vsnprintf(_out_fct, (char*)(uintptr_t)&out_fct_wrap, (size_t)-1, format, va);
-  va_end(va);
-  return ret;
-}
+///////////////////////////////////////////////////////////////////////////////
+// \author (c) Marco Paland (info@paland.com)
+//             2014-2019, PALANDesign Hannover, Germany
+//
+// \license The MIT License (MIT)
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+//
+// \brief Tiny printf, sprintf and (v)snprintf implementation, optimized for speed on
+//        embedded systems with a very limited resources. These routines are thread
+//        safe and reentrant!
+//        Use this instead of the bloated standard/newlib printf cause these use
+//        malloc for printf (and may not be thread safe).
+//
+///////////////////////////////////////////////////////////////////////////////
+
+#define PRINTF_DISABLE_SUPPORT_FLOAT
+#define PRINTF_DISABLE_SUPPORT_EXPONENTIAL
+
+#include <stdbool.h>
+#include <stdint.h>
+
+#include "printf.h"
+#include "uarch-ecall.h"
+
+
+// define this globally (e.g. gcc -DPRINTF_INCLUDE_CONFIG_H ...) to include the
+// printf_config.h header file
+// default: undefined
+#ifdef PRINTF_INCLUDE_CONFIG_H
+#include "printf_config.h"
+#endif
+
+
+// 'ntoa' conversion buffer size, this must be big enough to hold one converted
+// numeric number including padded zeros (dynamically created on stack)
+// default: 32 byte
+#ifndef PRINTF_NTOA_BUFFER_SIZE
+#define PRINTF_NTOA_BUFFER_SIZE    32U
+#endif
+
+// 'ftoa' conversion buffer size, this must be big enough to hold one converted
+// float number including padded zeros (dynamically created on stack)
+// default: 32 byte
+#ifndef PRINTF_FTOA_BUFFER_SIZE
+#define PRINTF_FTOA_BUFFER_SIZE    32U
+#endif
+
+// support for the floating point type (%f)
+// default: activated
+#ifndef PRINTF_DISABLE_SUPPORT_FLOAT
+#define PRINTF_SUPPORT_FLOAT
+#endif
+
+// support for exponential floating point notation (%e/%g)
+// default: activated
+#ifndef PRINTF_DISABLE_SUPPORT_EXPONENTIAL
+#define PRINTF_SUPPORT_EXPONENTIAL
+#endif
+
+// define the default floating point precision
+// default: 6 digits
+#ifndef PRINTF_DEFAULT_FLOAT_PRECISION
+#define PRINTF_DEFAULT_FLOAT_PRECISION  6U
+#endif
+
+// define the largest float suitable to print with %f
+// default: 1e9
+#ifndef PRINTF_MAX_FLOAT
+#define PRINTF_MAX_FLOAT  1e9
+#endif
+
+// support for the long long types (%llu or %p)
+// default: activated
+#ifndef PRINTF_DISABLE_SUPPORT_LONG_LONG
+#define PRINTF_SUPPORT_LONG_LONG
+#endif
+
+// support for the ptrdiff_t type (%t)
+// ptrdiff_t is normally defined in <stddef.h> as long or long long type
+// default: activated
+#ifndef PRINTF_DISABLE_SUPPORT_PTRDIFF_T
+#define PRINTF_SUPPORT_PTRDIFF_T
+#endif
+
+///////////////////////////////////////////////////////////////////////////////
+
+// internal flag definitions
+#define FLAGS_ZEROPAD   (1U <<  0U)
+#define FLAGS_LEFT      (1U <<  1U)
+#define FLAGS_PLUS      (1U <<  2U)
+#define FLAGS_SPACE     (1U <<  3U)
+#define FLAGS_HASH      (1U <<  4U)
+#define FLAGS_UPPERCASE (1U <<  5U)
+#define FLAGS_CHAR      (1U <<  6U)
+#define FLAGS_SHORT     (1U <<  7U)
+#define FLAGS_LONG      (1U <<  8U)
+#define FLAGS_LONG_LONG (1U <<  9U)
+#define FLAGS_PRECISION (1U << 10U)
+#define FLAGS_ADAPT_EXP (1U << 11U)
+
+
+// import float.h for DBL_MAX
+#if defined(PRINTF_SUPPORT_FLOAT)
+#include <float.h>
+#endif
+
+
+// output function type
+typedef void (*out_fct_type)(char character, void* buffer, size_t idx, size_t maxlen);
+
+
+// wrapper (used as buffer) for output function type
+typedef struct {
+  void  (*fct)(char character, void* arg);
+  void* arg;
+} out_fct_wrap_type;
+
+
+// internal buffer output
+static inline void _out_buffer(char character, void* buffer, size_t idx, size_t maxlen)
+{
+  if (idx < maxlen) {
+    ((char*)buffer)[idx] = character;
+  }
+}
+
+
+// internal null output
+static inline void _out_null(char character, void* buffer, size_t idx, size_t maxlen)
+{
+  (void)character; (void)buffer; (void)idx; (void)maxlen;
+}
+
+
+// internal _putchar wrapper
+static inline void _out_char(char character, void* buffer, size_t idx, size_t maxlen)
+{
+  (void)buffer; (void)idx; (void)maxlen;
+  if (character) {
+    ua_putchar_ECALL(character);
+  }
+}
+
+
+// internal output function wrapper
+static inline void _out_fct(char character, void* buffer, size_t idx, size_t maxlen)
+{
+  (void)idx; (void)maxlen;
+  if (character) {
+    // buffer is the output fct pointer
+    ((out_fct_wrap_type*)buffer)->fct(character, ((out_fct_wrap_type*)buffer)->arg);
+  }
+}
+
+
+// internal secure strlen
+// \return The length of the string (excluding the terminating 0) limited by 'maxsize'
+static inline unsigned int _strnlen_s(const char* str, size_t maxsize)
+{
+  const char* s;
+  for (s = str; *s && maxsize--; ++s);
+  return (unsigned int)(s - str);
+}
+
+
+// internal test if char is a digit (0-9)
+// \return true if char is a digit
+static inline bool _is_digit(char ch)
+{
+  return (ch >= '0') && (ch <= '9');
+}
+
+
+// internal ASCII string to unsigned int conversion
+static unsigned int _atoi(const char** str)
+{
+  unsigned int i = 0U;
+  while (_is_digit(**str)) {
+    i = i * 10U + (unsigned int)(*((*str)++) - '0');
+  }
+  return i;
+}
+
+
+// output the specified string in reverse, taking care of any zero-padding
+static size_t _out_rev(out_fct_type out, char* buffer, size_t idx, size_t maxlen, const char* buf, size_t len, unsigned int width, unsigned int flags)
+{
+  const size_t start_idx = idx;
+
+  // pad spaces up to given width
+  if (!(flags & FLAGS_LEFT) && !(flags & FLAGS_ZEROPAD)) {
+    for (size_t i = len; i < width; i++) {
+      out(' ', buffer, idx++, maxlen);
+    }
+  }
+
+  // reverse string
+  while (len) {
+    out(buf[--len], buffer, idx++, maxlen);
+  }
+
+  // append pad spaces up to given width
+  if (flags & FLAGS_LEFT) {
+    while (idx - start_idx < width) {
+      out(' ', buffer, idx++, maxlen);
+    }
+  }
+
+  return idx;
+}
+
+
+// internal itoa format
+static size_t _ntoa_format(out_fct_type out, char* buffer, size_t idx, size_t maxlen, char* buf, size_t len, bool negative, unsigned int base, unsigned int prec, unsigned int width, unsigned int flags)
+{
+  // pad leading zeros
+  if (!(flags & FLAGS_LEFT)) {
+    if (width && (flags & FLAGS_ZEROPAD) && (negative || (flags & (FLAGS_PLUS | FLAGS_SPACE)))) {
+      width--;
+    }
+    while ((len < prec) && (len < PRINTF_NTOA_BUFFER_SIZE)) {
+      buf[len++] = '0';
+    }
+    while ((flags & FLAGS_ZEROPAD) && (len < width) && (len < PRINTF_NTOA_BUFFER_SIZE)) {
+      buf[len++] = '0';
+    }
+  }
+
+  // handle hash
+  if (flags & FLAGS_HASH) {
+    if (!(flags & FLAGS_PRECISION) && len && ((len == prec) || (len == width))) {
+      len--;
+      if (len && (base == 16U)) {
+        len--;
+      }
+    }
+    if ((base == 16U) && !(flags & FLAGS_UPPERCASE) && (len < PRINTF_NTOA_BUFFER_SIZE)) {
+      buf[len++] = 'x';
+    }
+    else if ((base == 16U) && (flags & FLAGS_UPPERCASE) && (len < PRINTF_NTOA_BUFFER_SIZE)) {
+      buf[len++] = 'X';
+    }
+    else if ((base == 2U) && (len < PRINTF_NTOA_BUFFER_SIZE)) {
+      buf[len++] = 'b';
+    }
+    if (len < PRINTF_NTOA_BUFFER_SIZE) {
+      buf[len++] = '0';
+    }
+  }
+
+  if (len < PRINTF_NTOA_BUFFER_SIZE) {
+    if (negative) {
+      buf[len++] = '-';
+    }
+    else if (flags & FLAGS_PLUS) {
+      buf[len++] = '+';  // ignore the space if the '+' exists
+    }
+    else if (flags & FLAGS_SPACE) {
+      buf[len++] = ' ';
+    }
+  }
+
+  return _out_rev(out, buffer, idx, maxlen, buf, len, width, flags);
+}
+
+
+// internal itoa for 'long' type
+static size_t _ntoa_long(out_fct_type out, char* buffer, size_t idx, size_t maxlen, unsigned long value, bool negative, unsigned long base, unsigned int prec, unsigned int width, unsigned int flags)
+{
+  char buf[PRINTF_NTOA_BUFFER_SIZE];
+  size_t len = 0U;
+
+  // no hash for 0 values
+  if (!value) {
+    flags &= ~FLAGS_HASH;
+  }
+
+  // write if precision != 0 and value is != 0
+  if (!(flags & FLAGS_PRECISION) || value) {
+    do {
+      const char digit = (char)(value % base);
+      buf[len++] = digit < 10 ? '0' + digit : (flags & FLAGS_UPPERCASE ? 'A' : 'a') + digit - 10;
+      value /= base;
+    } while (value && (len < PRINTF_NTOA_BUFFER_SIZE));
+  }
+
+  return _ntoa_format(out, buffer, idx, maxlen, buf, len, negative, (unsigned int)base, prec, width, flags);
+}
+
+
+// internal itoa for 'long long' type
+#if defined(PRINTF_SUPPORT_LONG_LONG)
+static size_t _ntoa_long_long(out_fct_type out, char* buffer, size_t idx, size_t maxlen, unsigned long long value, bool negative, unsigned long long base, unsigned int prec, unsigned int width, unsigned int flags)
+{
+  char buf[PRINTF_NTOA_BUFFER_SIZE];
+  size_t len = 0U;
+
+  // no hash for 0 values
+  if (!value) {
+    flags &= ~FLAGS_HASH;
+  }
+
+  // write if precision != 0 and value is != 0
+  if (!(flags & FLAGS_PRECISION) || value) {
+    do {
+      const char digit = (char)(value % base);
+      buf[len++] = digit < 10 ? '0' + digit : (flags & FLAGS_UPPERCASE ? 'A' : 'a') + digit - 10;
+      value /= base;
+    } while (value && (len < PRINTF_NTOA_BUFFER_SIZE));
+  }
+
+  return _ntoa_format(out, buffer, idx, maxlen, buf, len, negative, (unsigned int)base, prec, width, flags);
+}
+#endif  // PRINTF_SUPPORT_LONG_LONG
+
+
+#if defined(PRINTF_SUPPORT_FLOAT)
+
+#if defined(PRINTF_SUPPORT_EXPONENTIAL)
+// forward declaration so that _ftoa can switch to exp notation for values > PRINTF_MAX_FLOAT
+static size_t _etoa(out_fct_type out, char* buffer, size_t idx, size_t maxlen, double value, unsigned int prec, unsigned int width, unsigned int flags);
+#endif
+
+
+// internal ftoa for fixed decimal floating point
+static size_t _ftoa(out_fct_type out, char* buffer, size_t idx, size_t maxlen, double value, unsigned int prec, unsigned int width, unsigned int flags)
+{
+  char buf[PRINTF_FTOA_BUFFER_SIZE];
+  size_t len  = 0U;
+  double diff = 0.0;
+
+  // powers of 10
+  static const double pow10[] = { 1, 10, 100, 1000, 10000, 100000, 1000000, 10000000, 100000000, 1000000000 };
+
+  // test for special values
+  if (value != value)
+    return _out_rev(out, buffer, idx, maxlen, "nan", 3, width, flags);
+  if (value < -DBL_MAX)
+    return _out_rev(out, buffer, idx, maxlen, "fni-", 4, width, flags);
+  if (value > DBL_MAX)
+    return _out_rev(out, buffer, idx, maxlen, (flags & FLAGS_PLUS) ? "fni+" : "fni", (flags & FLAGS_PLUS) ? 4U : 3U, width, flags);
+
+  // test for very large values
+  // standard printf behavior is to print EVERY whole number digit -- which could be 100s of characters overflowing your buffers == bad
+  if ((value > PRINTF_MAX_FLOAT) || (value < -PRINTF_MAX_FLOAT)) {
+#if defined(PRINTF_SUPPORT_EXPONENTIAL)
+    return _etoa(out, buffer, idx, maxlen, value, prec, width, flags);
+#else
+    return 0U;
+#endif
+  }
+
+  // test for negative
+  bool negative = false;
+  if (value < 0) {
+    negative = true;
+    value = 0 - value;
+  }
+
+  // set default precision, if not set explicitly
+  if (!(flags & FLAGS_PRECISION)) {
+    prec = PRINTF_DEFAULT_FLOAT_PRECISION;
+  }
+  // limit precision to 9, cause a prec >= 10 can lead to overflow errors
+  while ((len < PRINTF_FTOA_BUFFER_SIZE) && (prec > 9U)) {
+    buf[len++] = '0';
+    prec--;
+  }
+
+  int whole = (int)value;
+  double tmp = (value - whole) * pow10[prec];
+  unsigned long frac = (unsigned long)tmp;
+  diff = tmp - frac;
+
+  if (diff > 0.5) {
+    ++frac;
+    // handle rollover, e.g. case 0.99 with prec 1 is 1.0
+    if (frac >= pow10[prec]) {
+      frac = 0;
+      ++whole;
+    }
+  }
+  else if (diff < 0.5) {
+  }
+  else if ((frac == 0U) || (frac & 1U)) {
+    // if halfway, round up if odd OR if last digit is 0
+    ++frac;
+  }
+
+  if (prec == 0U) {
+    diff = value - (double)whole;
+    if ((!(diff < 0.5) || (diff > 0.5)) && (whole & 1)) {
+      // exactly 0.5 and ODD, then round up
+      // 1.5 -> 2, but 2.5 -> 2
+      ++whole;
+    }
+  }
+  else {
+    unsigned int count = prec;
+    // now do fractional part, as an unsigned number
+    while (len < PRINTF_FTOA_BUFFER_SIZE) {
+      --count;
+      buf[len++] = (char)(48U + (frac % 10U));
+      if (!(frac /= 10U)) {
+        break;
+      }
+    }
+    // add extra 0s
+    while ((len < PRINTF_FTOA_BUFFER_SIZE) && (count-- > 0U)) {
+      buf[len++] = '0';
+    }
+    if (len < PRINTF_FTOA_BUFFER_SIZE) {
+      // add decimal
+      buf[len++] = '.';
+    }
+  }
+
+  // do whole part, number is reversed
+  while (len < PRINTF_FTOA_BUFFER_SIZE) {
+    buf[len++] = (char)(48 + (whole % 10));
+    if (!(whole /= 10)) {
+      break;
+    }
+  }
+
+  // pad leading zeros
+  if (!(flags & FLAGS_LEFT) && (flags & FLAGS_ZEROPAD)) {
+    if (width && (negative || (flags & (FLAGS_PLUS | FLAGS_SPACE)))) {
+      width--;
+    }
+    while ((len < width) && (len < PRINTF_FTOA_BUFFER_SIZE)) {
+      buf[len++] = '0';
+    }
+  }
+
+  if (len < PRINTF_FTOA_BUFFER_SIZE) {
+    if (negative) {
+      buf[len++] = '-';
+    }
+    else if (flags & FLAGS_PLUS) {
+      buf[len++] = '+';  // ignore the space if the '+' exists
+    }
+    else if (flags & FLAGS_SPACE) {
+      buf[len++] = ' ';
+    }
+  }
+
+  return _out_rev(out, buffer, idx, maxlen, buf, len, width, flags);
+}
+
+
+#if defined(PRINTF_SUPPORT_EXPONENTIAL)
+// internal ftoa variant for exponential floating-point type, contributed by Martijn Jasperse <m.jasperse@gmail.com>
+static size_t _etoa(out_fct_type out, char* buffer, size_t idx, size_t maxlen, double value, unsigned int prec, unsigned int width, unsigned int flags)
+{
+  // check for NaN and special values
+  if ((value != value) || (value > DBL_MAX) || (value < -DBL_MAX)) {
+    return _ftoa(out, buffer, idx, maxlen, value, prec, width, flags);
+  }
+
+  // determine the sign
+  const bool negative = value < 0;
+  if (negative) {
+    value = -value;
+  }
+
+  // default precision
+  if (!(flags & FLAGS_PRECISION)) {
+    prec = PRINTF_DEFAULT_FLOAT_PRECISION;
+  }
+
+  // determine the decimal exponent
+  // based on the algorithm by David Gay (https://www.ampl.com/netlib/fp/dtoa.c)
+  union {
+    uint64_t U;
+    double   F;
+  } conv;
+
+  conv.F = value;
+  int exp2 = (int)((conv.U >> 52U) & 0x07FFU) - 1023;           // effectively log2
+  conv.U = (conv.U & ((1ULL << 52U) - 1U)) | (1023ULL << 52U);  // drop the exponent so conv.F is now in [1,2)
+  // now approximate log10 from the log2 integer part and an expansion of ln around 1.5
+  int expval = (int)(0.1760912590558 + exp2 * 0.301029995663981 + (conv.F - 1.5) * 0.289529654602168);
+  // now we want to compute 10^expval but we want to be sure it won't overflow
+  exp2 = (int)(expval * 3.321928094887362 + 0.5);
+  const double z  = expval * 2.302585092994046 - exp2 * 0.6931471805599453;
+  const double z2 = z * z;
+  conv.U = (uint64_t)(exp2 + 1023) << 52U;
+  // compute exp(z) using continued fractions, see https://en.wikipedia.org/wiki/Exponential_function#Continued_fractions_for_ex
+  conv.F *= 1 + 2 * z / (2 - z + (z2 / (6 + (z2 / (10 + z2 / 14)))));
+  // correct for rounding errors
+  if (value < conv.F) {
+    expval--;
+    conv.F /= 10;
+  }
+
+  // the exponent format is "%+03d" and largest value is "307", so set aside 4-5 characters
+  unsigned int minwidth = ((expval < 100) && (expval > -100)) ? 4U : 5U;
+
+  // in "%g" mode, "prec" is the number of *significant figures* not decimals
+  if (flags & FLAGS_ADAPT_EXP) {
+    // do we want to fall-back to "%f" mode?
+    if ((value >= 1e-4) && (value < 1e6)) {
+      if ((int)prec > expval) {
+        prec = (unsigned)((int)prec - expval - 1);
+      }
+      else {
+        prec = 0;
+      }
+      flags |= FLAGS_PRECISION;   // make sure _ftoa respects precision
+      // no characters in exponent
+      minwidth = 0U;
+      expval   = 0;
+    }
+    else {
+      // we use one sigfig for the whole part
+      if ((prec > 0) && (flags & FLAGS_PRECISION)) {
+        --prec;
+      }
+    }
+  }
+
+  // will everything fit?
+  unsigned int fwidth = width;
+  if (width > minwidth) {
+    // we didn't fall-back so subtract the characters required for the exponent
+    fwidth -= minwidth;
+  } else {
+    // not enough characters, so go back to default sizing
+    fwidth = 0U;
+  }
+  if ((flags & FLAGS_LEFT) && minwidth) {
+    // if we're padding on the right, DON'T pad the floating part
+    fwidth = 0U;
+  }
+
+  // rescale the float value
+  if (expval) {
+    value /= conv.F;
+  }
+
+  // output the floating part
+  const size_t start_idx = idx;
+  idx = _ftoa(out, buffer, idx, maxlen, negative ? -value : value, prec, fwidth, flags & ~FLAGS_ADAPT_EXP);
+
+  // output the exponent part
+  if (minwidth) {
+    // output the exponential symbol
+    out((flags & FLAGS_UPPERCASE) ? 'E' : 'e', buffer, idx++, maxlen);
+    // output the exponent value
+    idx = _ntoa_long(out, buffer, idx, maxlen, (expval < 0) ? -expval : expval, expval < 0, 10, 0, minwidth-1, FLAGS_ZEROPAD | FLAGS_PLUS);
+    // might need to right-pad spaces
+    if (flags & FLAGS_LEFT) {
+      while (idx - start_idx < width) out(' ', buffer, idx++, maxlen);
+    }
+  }
+  return idx;
+}
+#endif  // PRINTF_SUPPORT_EXPONENTIAL
+#endif  // PRINTF_SUPPORT_FLOAT
+
+
+// internal vsnprintf
+static int _vsnprintf(out_fct_type out, char* buffer, const size_t maxlen, const char* format, va_list va)
+{
+  unsigned int flags, width, precision, n;
+  size_t idx = 0U;
+
+  if (!buffer) {
+    // use null output function
+    out = _out_null;
+  }
+
+  while (*format)
+  {
+    // format specifier?  %[flags][width][.precision][length]
+    if (*format != '%') {
+      // no
+      out(*format, buffer, idx++, maxlen);
+      format++;
+      continue;
+    }
+    else {
+      // yes, evaluate it
+      format++;
+    }
+
+    // evaluate flags
+    flags = 0U;
+    do {
+      switch (*format) {
+        case '0': flags |= FLAGS_ZEROPAD; format++; n = 1U; break;
+        case '-': flags |= FLAGS_LEFT;    format++; n = 1U; break;
+        case '+': flags |= FLAGS_PLUS;    format++; n = 1U; break;
+        case ' ': flags |= FLAGS_SPACE;   format++; n = 1U; break;
+        case '#': flags |= FLAGS_HASH;    format++; n = 1U; break;
+        default :                                   n = 0U; break;
+      }
+    } while (n);
+
+    // evaluate width field
+    width = 0U;
+    if (_is_digit(*format)) {
+      width = _atoi(&format);
+    }
+    else if (*format == '*') {
+      const int w = va_arg(va, int);
+      if (w < 0) {
+        flags |= FLAGS_LEFT;    // reverse padding
+        width = (unsigned int)-w;
+      }
+      else {
+        width = (unsigned int)w;
+      }
+      format++;
+    }
+
+    // evaluate precision field
+    precision = 0U;
+    if (*format == '.') {
+      flags |= FLAGS_PRECISION;
+      format++;
+      if (_is_digit(*format)) {
+        precision = _atoi(&format);
+      }
+      else if (*format == '*') {
+        const int prec = (int)va_arg(va, int);
+        precision = prec > 0 ? (unsigned int)prec : 0U;
+        format++;
+      }
+    }
+
+    // evaluate length field
+    switch (*format) {
+      case 'l' :
+        flags |= FLAGS_LONG;
+        format++;
+        if (*format == 'l') {
+          flags |= FLAGS_LONG_LONG;
+          format++;
+        }
+        break;
+      case 'h' :
+        flags |= FLAGS_SHORT;
+        format++;
+        if (*format == 'h') {
+          flags |= FLAGS_CHAR;
+          format++;
+        }
+        break;
+#if defined(PRINTF_SUPPORT_PTRDIFF_T)
+      case 't' :
+        flags |= (sizeof(ptrdiff_t) == sizeof(long) ? FLAGS_LONG : FLAGS_LONG_LONG);
+        format++;
+        break;
+#endif
+      case 'j' :
+        flags |= (sizeof(intmax_t) == sizeof(long) ? FLAGS_LONG : FLAGS_LONG_LONG);
+        format++;
+        break;
+      case 'z' :
+        flags |= (sizeof(size_t) == sizeof(long) ? FLAGS_LONG : FLAGS_LONG_LONG);
+        format++;
+        break;
+      default :
+        break;
+    }
+
+    // evaluate specifier
+    switch (*format) {
+      case 'd' :
+      case 'i' :
+      case 'u' :
+      case 'x' :
+      case 'X' :
+      case 'o' :
+      case 'b' : {
+        // set the base
+        unsigned int base;
+        if (*format == 'x' || *format == 'X') {
+          base = 16U;
+        }
+        else if (*format == 'o') {
+          base =  8U;
+        }
+        else if (*format == 'b') {
+          base =  2U;
+        }
+        else {
+          base = 10U;
+          flags &= ~FLAGS_HASH;   // no hash for dec format
+        }
+        // uppercase
+        if (*format == 'X') {
+          flags |= FLAGS_UPPERCASE;
+        }
+
+        // no plus or space flag for u, x, X, o, b
+        if ((*format != 'i') && (*format != 'd')) {
+          flags &= ~(FLAGS_PLUS | FLAGS_SPACE);
+        }
+
+        // ignore '0' flag when precision is given
+        if (flags & FLAGS_PRECISION) {
+          flags &= ~FLAGS_ZEROPAD;
+        }
+
+        // convert the integer
+        if ((*format == 'i') || (*format == 'd')) {
+          // signed
+          if (flags & FLAGS_LONG_LONG) {
+#if defined(PRINTF_SUPPORT_LONG_LONG)
+            const long long value = va_arg(va, long long);
+            idx = _ntoa_long_long(out, buffer, idx, maxlen, (unsigned long long)(value > 0 ? value : 0 - value), value < 0, base, precision, width, flags);
+#endif
+          }
+          else if (flags & FLAGS_LONG) {
+            const long value = va_arg(va, long);
+            idx = _ntoa_long(out, buffer, idx, maxlen, (unsigned long)(value > 0 ? value : 0 - value), value < 0, base, precision, width, flags);
+          }
+          else {
+            const int value = (flags & FLAGS_CHAR) ? (char)va_arg(va, int) : (flags & FLAGS_SHORT) ? (short int)va_arg(va, int) : va_arg(va, int);
+            idx = _ntoa_long(out, buffer, idx, maxlen, (unsigned int)(value > 0 ? value : 0 - value), value < 0, base, precision, width, flags);
+          }
+        }
+        else {
+          // unsigned
+          if (flags & FLAGS_LONG_LONG) {
+#if defined(PRINTF_SUPPORT_LONG_LONG)
+            idx = _ntoa_long_long(out, buffer, idx, maxlen, va_arg(va, unsigned long long), false, base, precision, width, flags);
+#endif
+          }
+          else if (flags & FLAGS_LONG) {
+            idx = _ntoa_long(out, buffer, idx, maxlen, va_arg(va, unsigned long), false, base, precision, width, flags);
+          }
+          else {
+            const unsigned int value = (flags & FLAGS_CHAR) ? (unsigned char)va_arg(va, unsigned int) : (flags & FLAGS_SHORT) ? (unsigned short int)va_arg(va, unsigned int) : va_arg(va, unsigned int);
+            idx = _ntoa_long(out, buffer, idx, maxlen, value, false, base, precision, width, flags);
+          }
+        }
+        format++;
+        break;
+      }
+#if defined(PRINTF_SUPPORT_FLOAT)
+      case 'f' :
+      case 'F' :
+        if (*format == 'F') flags |= FLAGS_UPPERCASE;
+        idx = _ftoa(out, buffer, idx, maxlen, va_arg(va, double), precision, width, flags);
+        format++;
+        break;
+#if defined(PRINTF_SUPPORT_EXPONENTIAL)
+      case 'e':
+      case 'E':
+      case 'g':
+      case 'G':
+        if ((*format == 'g')||(*format == 'G')) flags |= FLAGS_ADAPT_EXP;
+        if ((*format == 'E')||(*format == 'G')) flags |= FLAGS_UPPERCASE;
+        idx = _etoa(out, buffer, idx, maxlen, va_arg(va, double), precision, width, flags);
+        format++;
+        break;
+#endif  // PRINTF_SUPPORT_EXPONENTIAL
+#endif  // PRINTF_SUPPORT_FLOAT
+      case 'c' : {
+        unsigned int l = 1U;
+        // pre padding
+        if (!(flags & FLAGS_LEFT)) {
+          while (l++ < width) {
+            out(' ', buffer, idx++, maxlen);
+          }
+        }
+        // char output
+        out((char)va_arg(va, int), buffer, idx++, maxlen);
+        // post padding
+        if (flags & FLAGS_LEFT) {
+          while (l++ < width) {
+            out(' ', buffer, idx++, maxlen);
+          }
+        }
+        format++;
+        break;
+      }
+
+      case 's' : {
+        const char* p = va_arg(va, char*);
+        unsigned int l = _strnlen_s(p, precision ? precision : (size_t)-1);
+        // pre padding
+        if (flags & FLAGS_PRECISION) {
+          l = (l < precision ? l : precision);
+        }
+        if (!(flags & FLAGS_LEFT)) {
+          while (l++ < width) {
+            out(' ', buffer, idx++, maxlen);
+          }
+        }
+        // string output
+        while ((*p != 0) && (!(flags & FLAGS_PRECISION) || precision--)) {
+          out(*(p++), buffer, idx++, maxlen);
+        }
+        // post padding
+        if (flags & FLAGS_LEFT) {
+          while (l++ < width) {
+            out(' ', buffer, idx++, maxlen);
+          }
+        }
+        format++;
+        break;
+      }
+
+      case 'p' : {
+        width = sizeof(void*) * 2U;
+        flags |= FLAGS_ZEROPAD | FLAGS_UPPERCASE;
+#if defined(PRINTF_SUPPORT_LONG_LONG)
+        const bool is_ll = sizeof(uintptr_t) == sizeof(long long);
+        if (is_ll) {
+          idx = _ntoa_long_long(out, buffer, idx, maxlen, (uintptr_t)va_arg(va, void*), false, 16U, precision, width, flags);
+        }
+        else {
+#endif
+          idx = _ntoa_long(out, buffer, idx, maxlen, (unsigned long)((uintptr_t)va_arg(va, void*)), false, 16U, precision, width, flags);
+#if defined(PRINTF_SUPPORT_LONG_LONG)
+        }
+#endif
+        format++;
+        break;
+      }
+
+      case '%' :
+        out('%', buffer, idx++, maxlen);
+        format++;
+        break;
+
+      default :
+        out(*format, buffer, idx++, maxlen);
+        format++;
+        break;
+    }
+  }
+
+  // termination
+  out((char)0, buffer, idx < maxlen ? idx : maxlen - 1U, maxlen);
+
+  // return written chars without terminating \0
+  return (int)idx;
+}
+
+
+///////////////////////////////////////////////////////////////////////////////
+
+int printf_(const char* format, ...)
+{
+  va_list va;
+  va_start(va, format);
+  char buffer[1];
+  const int ret = _vsnprintf(_out_char, buffer, (size_t)-1, format, va);
+  va_end(va);
+  return ret;
+}
+
+
+int sprintf_(char* buffer, const char* format, ...)
+{
+  va_list va;
+  va_start(va, format);
+  const int ret = _vsnprintf(_out_buffer, buffer, (size_t)-1, format, va);
+  va_end(va);
+  return ret;
+}
+
+
+int snprintf_(char* buffer, size_t count, const char* format, ...)
+{
+  va_list va;
+  va_start(va, format);
+  const int ret = _vsnprintf(_out_buffer, buffer, count, format, va);
+  va_end(va);
+  return ret;
+}
+
+
+int vprintf_(const char* format, va_list va)
+{
+  char buffer[1];
+  return _vsnprintf(_out_char, buffer, (size_t)-1, format, va);
+}
+
+
+int vsnprintf_(char* buffer, size_t count, const char* format, va_list va)
+{
+  return _vsnprintf(_out_buffer, buffer, count, format, va);
+}
+
+
+int fctprintf(void (*out)(char character, void* arg), void* arg, const char* format, ...)
+{
+  va_list va;
+  va_start(va, format);
+  const out_fct_wrap_type out_fct_wrap = { out, arg };
+  const int ret = _vsnprintf(_out_fct, (char*)(uintptr_t)&out_fct_wrap, (size_t)-1, format, va);
+  va_end(va);
+  return ret;
+}
diff --git a/uarch/uarch-printf.h b/uarch/third-party/printf/printf.h
similarity index 79%
rename from uarch/uarch-printf.h
rename to uarch/third-party/printf/printf.h
index a68a6141b..6075bc2cf 100644
--- a/uarch/uarch-printf.h
+++ b/uarch/third-party/printf/printf.h
@@ -1,101 +1,116 @@
-///////////////////////////////////////////////////////////////////////////////
-// \author (c) Marco Paland (info@paland.com)
-//             2014-2019, PALANDesign Hannover, Germany
-//
-// \license The MIT License (MIT)
-//
-// Permission is hereby granted, free of charge, to any person obtaining a copy
-// of this software and associated documentation files (the "Software"), to deal
-// in the Software without restriction, including without limitation the rights
-// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-// copies of the Software, and to permit persons to whom the Software is
-// furnished to do so, subject to the following conditions:
-//
-// The above copyright notice and this permission notice shall be included in
-// all copies or substantial portions of the Software.
-//
-// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-// THE SOFTWARE.
-//
-// \brief Tiny printf, sprintf and snprintf implementation, optimized for speed on
-//        embedded systems with a very limited resources.
-//        Use this instead of bloated standard/newlib printf.
-//        These routines are thread safe and reentrant.
-//
-///////////////////////////////////////////////////////////////////////////////
-
-#ifndef _PRINTF_H_
-#define _PRINTF_H_
-
-#include <stdarg.h>
-#include <stddef.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-/**
- * Tiny printf implementation
- * You have to implement _putchar if you use printf()
- * To avoid conflicts with the regular printf() API it is overridden by macro defines
- * and internal underscore-appended functions like printf_() are used
- * \param format A string that specifies the format of the output
- * \return The number of characters that are written into the array, not counting the terminating null character
- */
-#define printf printf_
-int printf_(const char *format, ...);
-
-/**
- * Tiny sprintf implementation
- * Due to security reasons (buffer overflow) YOU SHOULD CONSIDER USING (V)SNPRINTF INSTEAD!
- * \param buffer A pointer to the buffer where to store the formatted string. MUST be big enough to store the output!
- * \param format A string that specifies the format of the output
- * \return The number of characters that are WRITTEN into the buffer, not counting the terminating null character
- */
-#define sprintf sprintf_
-int sprintf_(char *buffer, const char *format, ...);
-
-/**
- * Tiny snprintf/vsnprintf implementation
- * \param buffer A pointer to the buffer where to store the formatted string
- * \param count The maximum number of characters to store in the buffer, including a terminating null character
- * \param format A string that specifies the format of the output
- * \param va A value identifying a variable arguments list
- * \return The number of characters that COULD have been written into the buffer, not counting the terminating
- *         null character. A value equal or larger than count indicates truncation. Only when the returned value
- *         is non-negative and less than count, the string has been completely written.
- */
-#define snprintf snprintf_
-#define vsnprintf vsnprintf_
-int snprintf_(char *buffer, size_t count, const char *format, ...);
-int vsnprintf_(char *buffer, size_t count, const char *format, va_list va);
-
-/**
- * Tiny vprintf implementation
- * \param format A string that specifies the format of the output
- * \param va A value identifying a variable arguments list
- * \return The number of characters that are WRITTEN into the buffer, not counting the terminating null character
- */
-#define vprintf vprintf_
-int vprintf_(const char *format, va_list va);
-
-/**
- * printf with output function
- * You may use this as dynamic alternative to printf() with its fixed _putchar() output
- * \param out An output function which takes one character and an argument pointer
- * \param arg An argument pointer for user data passed to output function
- * \param format A string that specifies the format of the output
- * \return The number of characters that are sent to the output function, not counting the terminating null character
- */
-int fctprintf(void (*out)(char character, void *arg), void *arg, const char *format, ...);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif // _PRINTF_H_
+///////////////////////////////////////////////////////////////////////////////
+// \author (c) Marco Paland (info@paland.com)
+//             2014-2019, PALANDesign Hannover, Germany
+//
+// \license The MIT License (MIT)
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+// 
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+// 
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+//
+// \brief Tiny printf, sprintf and snprintf implementation, optimized for speed on
+//        embedded systems with a very limited resources.
+//        Use this instead of bloated standard/newlib printf.
+//        These routines are thread safe and reentrant.
+//
+///////////////////////////////////////////////////////////////////////////////
+
+#ifndef _PRINTF_H_
+#define _PRINTF_H_
+
+#include <stdarg.h>
+#include <stddef.h>
+
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+/**
+ * Output a character to a custom device like UART, used by the printf() function
+ * This function is declared here only. You have to write your custom implementation somewhere
+ * \param character Character to output
+ */
+void _putchar(char character);
+
+
+/**
+ * Tiny printf implementation
+ * You have to implement _putchar if you use printf()
+ * To avoid conflicts with the regular printf() API it is overridden by macro defines
+ * and internal underscore-appended functions like printf_() are used
+ * \param format A string that specifies the format of the output
+ * \return The number of characters that are written into the array, not counting the terminating null character
+ */
+#define printf printf_
+int printf_(const char* format, ...);
+
+
+/**
+ * Tiny sprintf implementation
+ * Due to security reasons (buffer overflow) YOU SHOULD CONSIDER USING (V)SNPRINTF INSTEAD!
+ * \param buffer A pointer to the buffer where to store the formatted string. MUST be big enough to store the output!
+ * \param format A string that specifies the format of the output
+ * \return The number of characters that are WRITTEN into the buffer, not counting the terminating null character
+ */
+#define sprintf sprintf_
+int sprintf_(char* buffer, const char* format, ...);
+
+
+/**
+ * Tiny snprintf/vsnprintf implementation
+ * \param buffer A pointer to the buffer where to store the formatted string
+ * \param count The maximum number of characters to store in the buffer, including a terminating null character
+ * \param format A string that specifies the format of the output
+ * \param va A value identifying a variable arguments list
+ * \return The number of characters that are WRITTEN into the buffer, not counting the terminating null character
+ *         If the formatted string is truncated the buffer size (count) is returned
+ */
+#define snprintf  snprintf_
+#define vsnprintf vsnprintf_
+int  snprintf_(char* buffer, size_t count, const char* format, ...);
+int vsnprintf_(char* buffer, size_t count, const char* format, va_list va);
+
+
+/**
+ * Tiny vprintf implementation
+ * \param format A string that specifies the format of the output
+ * \param va A value identifying a variable arguments list
+ * \return The number of characters that are WRITTEN into the buffer, not counting the terminating null character
+ */
+#define vprintf vprintf_
+int vprintf_(const char* format, va_list va);
+
+
+/**
+ * printf with output function
+ * You may use this as dynamic alternative to printf() with its fixed _putchar() output
+ * \param out An output function which takes one character and an argument pointer
+ * \param arg An argument pointer for user data passed to output function
+ * \param format A string that specifies the format of the output
+ * \return The number of characters that are sent to the output function, not counting the terminating null character
+ */
+int fctprintf(void (*out)(char character, void* arg), void* arg, const char* format, ...);
+
+
+#ifdef __cplusplus
+}
+#endif
+
+
+#endif  // _PRINTF_H_
diff --git a/uarch/uarch-runtime.h b/uarch/uarch-runtime.h
index 96e804e13..dc28fdbfb 100644
--- a/uarch/uarch-runtime.h
+++ b/uarch/uarch-runtime.h
@@ -18,14 +18,11 @@
 #define UARCH_RUNTIME_H
 
 #include "compiler-defines.h"
-#include "uarch-printf.h"
+#include "third-party/printf/printf.h"
 
 #include <inttypes.h>
 #include <stddef.h>
 
-// NOLINTNEXTLINE(cppcoreguidelines-macro-usage)
-#define fprintf(a, ...) printf(__VA_ARGS__)
-
 // NOLINTNEXTLINE(cppcoreguidelines-macro-usage)
 #define assert(a)                                                                                                      \
     if (!(a)) {                                                                                                        \

From 7f521352e7744f29edda8ff9d7e5508779c0c08d Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Fri, 7 Feb 2025 15:45:18 +0000
Subject: [PATCH 13/82] refactor: make all DUMP_*.* work and pass linter

---
 src/Makefile                              |  14 +-
 src/interpret.cpp                         | 200 +++++++++++-----------
 src/json-util.cpp                         |   2 +-
 src/jsonrpc-remote-machine.cpp            |   6 +-
 src/machine.cpp                           |  10 +-
 src/os.cpp                                |  12 +-
 src/record-step-state-access.h            |   1 -
 src/replay-send-cmio-state-access.h       |   1 -
 src/virtio-net-carrier-slirp.cpp          |   4 +-
 tests/misc/test-utils.h                   |   2 +-
 uarch/machine-uarch-bridge-state-access.h |   4 +-
 uarch/uarch-run.cpp                       |   4 +-
 uarch/uarch-runtime.cpp                   |   6 +-
 13 files changed, 133 insertions(+), 133 deletions(-)

diff --git a/src/Makefile b/src/Makefile
index 409571a41..42701d764 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -175,13 +175,13 @@ DEFS+=-D_FILE_OFFSET_BITS=64
 DEFS+=-DJSON_HAS_FILESYSTEM=0
 
 ifeq ($(dump),yes)
-#DUMP_DEFS+=-DDUMP_ILLEGAL_INSN_EXCEPTIONS
-#DUMP_DEFS+=-DDUMP_EXCEPTIONS
-#DUMP_DEFS+=-DDUMP_INTERRUPTS
-#DUMP_DEFS+=-DDUMP_MMU_EXCEPTIONS
-#DUMP_DEFS+=-DDUMP_INVALID_MEM_ACCESS
-#DUMP_DEFS+=-DDUMP_INVALID_CSR
-#DUMP_DEFS+=-DDUMP_REGS
+DUMP_DEFS+=-DDUMP_ILLEGAL_INSN_EXCEPTIONS
+DUMP_DEFS+=-DDUMP_EXCEPTIONS
+DUMP_DEFS+=-DDUMP_INTERRUPTS
+DUMP_DEFS+=-DDUMP_MMU_EXCEPTIONS
+DUMP_DEFS+=-DDUMP_INVALID_MEM_ACCESS
+DUMP_DEFS+=-DDUMP_INVALID_CSR
+DUMP_DEFS+=-DDUMP_REGS
 DUMP_DEFS+=-DDUMP_INSN_HIST
 DUMP_DEFS+=-DDUMP_STATS
 DUMP_DEFS+=-DDUMP_INSN
diff --git a/src/interpret.cpp b/src/interpret.cpp
index 6fb4809ff..d75b5ea5c 100644
--- a/src/interpret.cpp
+++ b/src/interpret.cpp
@@ -150,9 +150,6 @@ static const std::array<const char *, F_REG_COUNT> f_reg_name{"ft0", "ft1", "ft2
     "fs0", "fs1", "fa0", "fa1", "fa2", "fa3", "fa4", "fa5", "fa6", "fa7", "fs2", "fs3", "fs4", "fs5", "fs6", "fs7",
     "fs8", "fs9", "fs10", "fs11", "ft8", "ft9", "ft10", "ft11"};
 
-static void print_uint64_t(uint64_t a) {
-    D_PRINTF("%016" PRIx64, a);
-}
 #endif
 
 #if defined(DUMP_EXCEPTIONS) || defined(DUMP_MMU_EXCEPTIONS) || defined(DUMP_INTERRUPTS) ||                            \
@@ -182,76 +179,74 @@ static const char *sbi_ecall_name(uint64_t a7) {
     }
 }
 
-template <typename STATE>
-static void dump_exception_or_interrupt(uint64_t cause, STATE &s) {
-    uint64_t a7 = s.x[17];
+static void dump_exception_or_interrupt(uint64_t cause, uint64_t a7) {
     if ((cause & MCAUSE_INTERRUPT_FLAG) != 0) {
         switch (cause & ~MCAUSE_INTERRUPT_FLAG) {
             case 0:
-                D_PRINTF("reserved software interrupt");
+                D_PRINTF("reserved software interrupt", "");
                 break;
             case 1:
-                D_PRINTF("supervisor software interrupt");
+                D_PRINTF("supervisor software interrupt", "");
                 break;
             case 2:
-                D_PRINTF("reserved software interrupt");
+                D_PRINTF("reserved software interrupt", "");
                 break;
             case 3:
-                D_PRINTF("machine software interrupt");
+                D_PRINTF("machine software interrupt", "");
                 break;
             case 4:
-                D_PRINTF("reserved timer interrupt");
+                D_PRINTF("reserved timer interrupt", "");
                 break;
             case 5:
-                D_PRINTF("supervisor timer interrupt");
+                D_PRINTF("supervisor timer interrupt", "");
                 break;
             case 6:
-                D_PRINTF("reserved timer interrupt");
+                D_PRINTF("reserved timer interrupt", "");
                 break;
             case 7:
-                D_PRINTF("machine timer interrupt");
+                D_PRINTF("machine timer interrupt", "");
                 break;
             case 8:
-                D_PRINTF("reserved external interrupt");
+                D_PRINTF("reserved external interrupt", "");
                 break;
             case 9:
-                D_PRINTF("supervisor external interrupt");
+                D_PRINTF("supervisor external interrupt", "");
                 break;
             case 10:
-                D_PRINTF("reserved external interrupt");
+                D_PRINTF("reserved external interrupt", "");
                 break;
             case 11:
-                D_PRINTF("machine external interrupt");
+                D_PRINTF("machine external interrupt", "");
                 break;
             default:
-                D_PRINTF("unknown interrupt");
+                D_PRINTF("unknown interrupt", "");
                 break;
         }
     } else {
         switch (cause) {
             case 0:
-                D_PRINTF("instruction address misaligned");
+                D_PRINTF("instruction address misaligned", "");
                 break;
             case 1:
-                D_PRINTF("instruction access fault");
+                D_PRINTF("instruction access fault", "");
                 break;
             case 2:
-                D_PRINTF("illegal instruction");
+                D_PRINTF("illegal instruction", "");
                 break;
             case 3:
-                D_PRINTF("breakpoint");
+                D_PRINTF("breakpoint", "");
                 break;
             case 4:
-                D_PRINTF("load address misaligned");
+                D_PRINTF("load address misaligned", "");
                 break;
             case 5:
-                D_PRINTF("load access fault");
+                D_PRINTF("load access fault", "");
                 break;
             case 6:
-                D_PRINTF("store/amo address misaligned");
+                D_PRINTF("store/amo address misaligned", "");
                 break;
             case 7:
-                D_PRINTF("store/amo access fault");
+                D_PRINTF("store/amo access fault", "");
                 break;
             case 8:
                 D_PRINTF("ecall %d from u-mode", static_cast<int>(a7));
@@ -266,61 +261,86 @@ static void dump_exception_or_interrupt(uint64_t cause, STATE &s) {
                 D_PRINTF("ecall %s(%d) from m-mode", sbi_ecall_name(a7), static_cast<int>(a7));
                 break;
             case 12:
-                D_PRINTF("instruction page fault");
+                D_PRINTF("instruction page fault", "");
                 break;
             case 13:
-                D_PRINTF("load page fault");
+                D_PRINTF("load page fault", "");
                 break;
             case 15:
-                D_PRINTF("store/amo page fault");
+                D_PRINTF("store/amo page fault", "");
                 break;
             default:
-                D_PRINTF("reserved");
+                D_PRINTF("reserved", "");
                 break;
         }
     }
 }
 #endif
 
+/// \brief Returns the name for a given privilege level
+/// \param prv Privilege level
+constexpr const char *prv_get_name(uint64_t prv) {
+    switch (prv) {
+        case PRV_U:
+            return "prv.U";
+        case PRV_S:
+            return "prv.S";
+        case PRV_HS:
+            return "prv.HS";
+        case PRV_M:
+            return "prv.M";
+        default:
+            return "prv.unknown";
+    }
+}
+
 #ifdef DUMP_REGS
-template <typename STATE>
-static void dump_regs(const STATE &s) {
-    const std::array<char, 5> prv_str{"USHM"};
-    int cols = 256 / XLEN;
-    D_PRINTF("pc = ");
-    print_uint64_t(s.pc);
-    D_PRINTF(" ");
+template <typename STATE_ACCESS>
+static void dump_regs(STATE_ACCESS &a) {
+    [[maybe_unused]] auto note = a.make_scoped_note("dump_regs");
+#define PRIxREG "0x%016" PRIx64
+#define PRIuREG "%" PRIu64
+    const int cols = 256 / XLEN;
+    // First, read all needed registers from state access
+    // otherwise, DUMP_STATE_ACCESS output would get mixed in with DUMP_REGS
+    const auto pc = a.read_pc();
+    const auto iprv = a.read_iprv();
+    const auto mstatus = a.read_mstatus();
+    //??D We would need to receive mcycle as an argument in order to have the
+    //??D up-to-date value for it. As it turns out, this would require many, many
+    //??D changes...
+    // const auto mcycle = a.read_mcycle();
+    // const auto icycleinstret = a.read_icycleinstret();
+    const auto mideleg = a.read_mideleg();
+    const auto mie = a.read_mie();
+    const auto mip = a.read_mip();
+    std::array<uint64_t, X_REG_COUNT> x{};
     for (int i = 1; i < X_REG_COUNT; i++) {
-        D_PRINTF("%-3s= ", reg_name[i]);
-        print_uint64_t(s.x[i]);
-        if ((i & (cols - 1)) == (cols - 1)) {
-            D_PRINTF("\n");
-        } else {
-            D_PRINTF(" ");
-        }
+        x[i] = a.read_x(i);
     }
+    std::array<uint64_t, X_REG_COUNT> f{};
     for (int i = 0; i < F_REG_COUNT; i++) {
-        D_PRINTF("%-3s= ", f_reg_name[i]);
-        print_uint64_t(s.f[i]);
-        if ((i & (cols - 1)) == (cols - 1)) {
-            D_PRINTF("\n");
-        } else {
-            D_PRINTF(" ");
-        }
+        f[i] = a.read_f(i);
     }
-    D_PRINTF("prv=%c", prv_str[s.iprv]);
-    D_PRINTF(" mstatus=");
-    print_uint64_t(s.mstatus);
-    D_PRINTF(" cycles=%" PRId64, s.mcycle);
-    D_PRINTF(" insns=%" PRId64, s.mcycle - s.icycleinstret);
-    D_PRINTF("\n");
-    D_PRINTF("mideleg=");
-    print_uint64_t(s.mideleg);
-    D_PRINTF(" mie=");
-    print_uint64_t(s.mie);
-    D_PRINTF(" mip=");
-    print_uint64_t(s.mip);
-    D_PRINTF("\n");
+    // Now print them
+    D_PRINTF("pc  = " PRIxREG " ", pc);
+    for (int i = 1; i < X_REG_COUNT; i++) {
+        const char sep = ((i & (cols - 1)) == (cols - 1)) ? '\n' : ' ';
+        D_PRINTF("%-4s= " PRIxREG "%c", reg_name[i], x[i], sep);
+    }
+    for (int i = 0; i < F_REG_COUNT; i++) {
+        const char sep = ((i & (cols - 1)) == (cols - 1)) ? '\n' : ' ';
+        D_PRINTF("%-4s= " PRIxREG "%c", f_reg_name[i], f[i], sep);
+    }
+    D_PRINTF("prv=%s", prv_get_name(iprv));
+    D_PRINTF(" mstatus=" PRIxREG "\n", mstatus);
+    // D_PRINTF(" cycles=" PRIuREG, mcycle);
+    // D_PRINTF(" insns=" PRIuREG "\n", mcycle - icycleinstret);
+    D_PRINTF("mideleg=" PRIxREG, mideleg);
+    D_PRINTF(" mie=" PRIxREG, mie);
+    D_PRINTF(" mip=" PRIxREG "\n", mip);
+#undef PRIxREG
+#undef PRIuREG
 }
 #endif
 
@@ -346,31 +366,14 @@ static inline uint32_t csr_prv(CSR_address csr) {
     return (to_underlying(csr) >> 8) & 3;
 }
 
-/// \brief Returns the statistic name for a change to a given privilege level
-/// \param prv Privilege level
-constexpr const char *prv_stat(uint64_t prv) {
-    switch (prv) {
-        case PRV_U:
-            return "prv.U";
-        case PRV_S:
-            return "prv.S";
-        case PRV_HS:
-            return "prv.HS";
-        case PRV_M:
-            return "prv.M";
-        default:
-            return "prv.unknown";
-    }
-}
-
 /// \brief Changes privilege level.
 /// \param a Machine state accessor object.
 /// \param previous_prv Previous privilege level.
 /// \param new_prv New privilege level.
 /// \details This function is outlined to minimize host CPU code cache pressure.
 template <typename STATE_ACCESS>
-static FORCE_INLINE void set_prv(STATE_ACCESS a, uint64_t new_prv) {
-    DUMP_STATS_INCR(a, prv_stat(new_prv));
+static FORCE_INLINE void set_prv(STATE_ACCESS &a, uint64_t new_prv) {
+    DUMP_STATS_INCR(a, prv_get_name(new_prv));
     a.write_iprv(new_prv);
     // Invalidate all TLB entries
     flush_all_tlb(a);
@@ -399,13 +402,13 @@ static NO_INLINE uint64_t raise_exception(STATE_ACCESS a, uint64_t pc, uint64_t
 #if defined(DUMP_EXCEPTIONS) || defined(DUMP_MMU_EXCEPTIONS) || defined(DUMP_INTERRUPTS) ||                            \
     defined(DUMP_ILLEGAL_INSN_EXCEPTIONS)
     {
-        int flag;
-        flag = 0;
+        int flag = 0;
 #ifdef DUMP_MMU_EXCEPTIONS
         if (cause == MCAUSE_INSN_ACCESS_FAULT || cause == MCAUSE_LOAD_ACCESS_FAULT ||
             cause == MCAUSE_STORE_AMO_ACCESS_FAULT || cause == MCAUSE_FETCH_PAGE_FAULT ||
-            cause == MCAUSE_LOAD_PAGE_FAULT || cause == MCAUSE_STORE_AMO_PAGE_FAULT)
+            cause == MCAUSE_LOAD_PAGE_FAULT || cause == MCAUSE_STORE_AMO_PAGE_FAULT) {
             flag = 1;
+        }
 #endif
 #ifdef DUMP_INTERRUPTS
         flag |= (cause & MCAUSE_INTERRUPT_FLAG) != 0;
@@ -414,19 +417,19 @@ static NO_INLINE uint64_t raise_exception(STATE_ACCESS a, uint64_t pc, uint64_t
         flag |= (cause & MCAUSE_INTERRUPT_FLAG) == 0;
 #endif
 #ifdef DUMP_ILLEGAL_INSN_EXCEPTIONS
-        if (cause == MCAUSE_ILLEGAL_INSN)
+        if (cause == MCAUSE_ILLEGAL_INSN) {
             flag = 1;
+        }
 #endif
         if (flag) {
-            D_PRINTF("raise_exception: cause=0x");
-            print_uint64_t(cause);
-            D_PRINTF(" tval=0x");
-            print_uint64_t(tval);
-            D_PRINTF(" (");
-            dump_exception_or_interrupt(cause, a.get_naked_state());
-            D_PRINTF(")\n");
+            [[maybe_unused]] auto dnote = a.make_scoped_note("dump_exception");
+            const auto a7 = a.read_x(17);
+            D_PRINTF("raise_exception: cause=0x%016" PRIx64, cause);
+            D_PRINTF(" tval=0x%016" PRIx64 " (", tval);
+            dump_exception_or_interrupt(cause, a7);
+            D_PRINTF(")\n", "");
 #ifdef DUMP_REGS
-            dump_regs(a.get_naked_state());
+            dump_regs(a);
 #endif
         }
     }
@@ -1144,7 +1147,7 @@ static auto dump_insn([[maybe_unused]] STATE_ACCESS a, [[maybe_unused]] uint64_t
     [[maybe_unused]] const char *name) {
     DUMP_INSN_HIST_INCR(a, name);
 #ifdef DUMP_REGS
-    dump_regs(a.get_naked_state());
+    dump_regs(a);
 #endif
 #ifdef DUMP_INSN
     [[maybe_unused]] auto note = a.make_scoped_note("dump_insn");
@@ -1154,8 +1157,7 @@ static auto dump_insn([[maybe_unused]] STATE_ACCESS a, [[maybe_unused]] uint64_t
     } else {
         D_PRINTF("p    %08" PRIx64, ppc);
     }
-    D_PRINTF(":   %08" PRIx32 "   ", insn);
-    D_PRINTF("%s\n", name);
+    D_PRINTF(":   %08" PRIx32 "   %s\n", insn, name);
 #endif
     return a.make_scoped_note(name);
 }
diff --git a/src/json-util.cpp b/src/json-util.cpp
index a80e85e07..4fc036b2c 100644
--- a/src/json-util.cpp
+++ b/src/json-util.cpp
@@ -894,7 +894,7 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key,
     }
     const auto sibling_hashes_base = path + "sibling_hashes/";
     for (int log2_size = proof.get_log2_target_size(), i = 0; log2_size < proof.get_log2_root_size();
-        ++log2_size, ++i) {
+         ++log2_size, ++i) {
         machine_merkle_tree::proof_type::hash_type sibling_hash;
         ju_get_field(sh, i, sibling_hash, sibling_hashes_base);
         proof.set_sibling_hash(sibling_hash, log2_size);
diff --git a/src/jsonrpc-remote-machine.cpp b/src/jsonrpc-remote-machine.cpp
index b1d7c30ec..021c106c3 100644
--- a/src/jsonrpc-remote-machine.cpp
+++ b/src/jsonrpc-remote-machine.cpp
@@ -98,7 +98,7 @@ static std::ostream &operator<<(std::ostream &out, log_prefix prefix) {
     using namespace slog;
     char stime[std::size("yyyy-mm-dd hh-mm-ss")];
     const time_t t = time(nullptr);
-    struct tm ttime{};
+    struct tm ttime {};
     if (strftime(std::data(stime), std::size(stime), "%Y-%m-%d %H-%M-%S", localtime_r(&t, &ttime)) != 0) {
         out << stime << " ";
     }
@@ -116,7 +116,7 @@ using json = nlohmann::json;
 /// \brief Installs a signal handler
 template <typename HANDLER>
 static void install_signal_handler(int signum, HANDLER handler) {
-    struct sigaction act{};
+    struct sigaction act {};
     if (sigemptyset(&act.sa_mask) < 0) {
         throw std::system_error{errno, std::generic_category(), "sigemptyset failed"};
     }
@@ -1749,7 +1749,7 @@ int main(int argc, char *argv[]) try {
         }
         SLOG(info) << "attempting to inherit fd " << server_fd << " from parent";
         // check socket is listening and is of right domain and type
-        struct sockaddr_in fd_addr{};
+        struct sockaddr_in fd_addr {};
         socklen_t len = sizeof(fd_addr);
         memset(&fd_addr, 0, len);
         // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
diff --git a/src/machine.cpp b/src/machine.cpp
index d30ee1aa3..5d08b599b 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -359,14 +359,14 @@ machine::machine(machine_config c, machine_runtime_config r) : m_c{std::move(c)}
         register_pma_entry(make_callocd_memory_pma_entry("RAM"s, PMA_RAM_START, m_c.ram.length).set_flags(m_ram_flags));
     } else {
         register_pma_entry(make_callocd_memory_pma_entry("RAM"s, PMA_RAM_START, m_c.ram.length, m_c.ram.image_filename)
-                .set_flags(m_ram_flags));
+                               .set_flags(m_ram_flags));
     }
 
     // Register DTB
     pma_entry &dtb = register_pma_entry((m_c.dtb.image_filename.empty() ?
             make_callocd_memory_pma_entry("DTB"s, PMA_DTB_START, PMA_DTB_LENGTH) :
             make_callocd_memory_pma_entry("DTB"s, PMA_DTB_START, PMA_DTB_LENGTH, m_c.dtb.image_filename))
-            .set_flags(m_dtb_flags));
+                                            .set_flags(m_dtb_flags));
 
     // Register all flash drives
     int i = 0; // NOLINT(misc-const-correctness)
@@ -735,7 +735,7 @@ static void store_device_pma(const machine &m, const pma_entry &pma, const std::
     auto name = machine_config::get_image_filename(dir, pma.get_start(), pma.get_length());
     auto fp = unique_fopen(name.c_str(), "wb");
     for (uint64_t page_start_in_range = 0; page_start_in_range < pma.get_length();
-        page_start_in_range += PMA_PAGE_SIZE) {
+         page_start_in_range += PMA_PAGE_SIZE) {
         const unsigned char *page_data = nullptr;
         auto peek = pma.get_peek();
         if (!peek(pma, m, page_start_in_range, PMA_PAGE_SIZE, &page_data, scratch.get())) {
@@ -1825,7 +1825,7 @@ bool machine::verify_dirty_page_maps() const {
     for (const auto &pma : m_s.pmas) {
         auto peek = pma.get_peek();
         for (uint64_t page_start_in_range = 0; page_start_in_range < pma.get_length();
-            page_start_in_range += PMA_PAGE_SIZE) {
+             page_start_in_range += PMA_PAGE_SIZE) {
             const uint64_t page_address = pma.get_start() + page_start_in_range;
             if (pma.get_istart_M()) {
                 const unsigned char *page_data = nullptr;
@@ -2520,7 +2520,7 @@ std::pair<uint64_t, execute_status> machine::poll_external_interrupts(uint64_t m
         if (timeout_us > 0) {
             start_us = os_now_us();
         }
-        state_access a(*this);
+        const state_access a(*this);
         device_state_access da(a, mcycle);
         // Poll virtio for events (e.g console stdin, network sockets)
         // Timeout may be decremented in case a device has deadline timers (e.g network device)
diff --git a/src/os.cpp b/src/os.cpp
index 5e9fe08a3..000112553 100644
--- a/src/os.cpp
+++ b/src/os.cpp
@@ -255,7 +255,7 @@ void os_open_tty() {
 #endif
         return;
     }
-    struct termios tty{};
+    struct termios tty {};
     if (tcgetattr(ttyfd, &tty) < 0) { // Failed to retrieve old mode
 #ifdef DEBUG_OS
         std::ignore = fprintf(stderr, "os_open_tty(): failed retrieve old mode\n");
@@ -322,7 +322,7 @@ void os_open_tty() {
 
 #ifdef HAVE_SIGACTION
     // Install console resize signal handler
-    struct sigaction sigact{};
+    struct sigaction sigact {};
     sigact.sa_flags = SA_RESTART;
     sigact.sa_handler = os_SIGWINCH_handler;
     if (sigemptyset(&sigact.sa_mask) != 0 || sigaction(SIGWINCH, &sigact, nullptr) != 0) {
@@ -567,7 +567,7 @@ unsigned char *os_map_file(const char *path, uint64_t length, bool shared) {
     }
 
     // Try to get file size
-    struct stat statbuf{};
+    struct stat statbuf {};
     if (fstat(backing_file, &statbuf) < 0) {
         close(backing_file);
         throw std::system_error{errno, std::generic_category(),
@@ -605,7 +605,7 @@ unsigned char *os_map_file(const char *path, uint64_t length, bool shared) {
     }
 
     // Try to get file size
-    struct __stat64 statbuf{};
+    struct __stat64 statbuf {};
     if (_fstat64(backing_file, &statbuf) < 0) {
         _close(backing_file);
         throw std::system_error{errno, std::generic_category(),
@@ -773,7 +773,7 @@ bool os_select_fds(const os_select_before_callback &before_cb, const os_select_a
 
 void os_disable_sigpipe() {
 #ifdef HAVE_SIGACTION
-    struct sigaction sigact{};
+    struct sigaction sigact {};
     sigact.sa_handler = SIG_IGN;
     sigact.sa_flags = SA_RESTART;
     if (sigemptyset(&sigact.sa_mask) != 0 || sigaction(SIGPIPE, &sigact, nullptr) != 0) {
@@ -814,7 +814,7 @@ int64_t os_get_file_length(const char *filename, const char *text) {
 }
 
 bool os_file_exists(const char *filename) {
-    struct stat buffer{};
+    struct stat buffer {};
     return (stat(filename, &buffer) == 0);
 }
 
diff --git a/src/record-step-state-access.h b/src/record-step-state-access.h
index b238a864a..0b7b33a3a 100644
--- a/src/record-step-state-access.h
+++ b/src/record-step-state-access.h
@@ -63,7 +63,6 @@ class record_step_state_access :
     using page_indices_type = std::vector<address_type>;
 
 public:
-
     struct context {
         /// \brief Constructor of record step state access context
         /// \param filename where to save the log
diff --git a/src/replay-send-cmio-state-access.h b/src/replay-send-cmio-state-access.h
index 36a028b9b..51b411d80 100644
--- a/src/replay-send-cmio-state-access.h
+++ b/src/replay-send-cmio-state-access.h
@@ -62,7 +62,6 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
     using proof_type = tree_type::proof_type;
 
 public:
-
     struct context {
         /// \brief Constructor replay_send_cmio_state_access context
         /// \param log Access log to be replayed
diff --git a/src/virtio-net-carrier-slirp.cpp b/src/virtio-net-carrier-slirp.cpp
index 39a72986f..edc0fe92b 100644
--- a/src/virtio-net-carrier-slirp.cpp
+++ b/src/virtio-net-carrier-slirp.cpp
@@ -209,8 +209,8 @@ virtio_net_carrier_slirp::virtio_net_carrier_slirp(const cartesi::virtio_net_use
 
     // Setup host forward ports
     for (const auto &hostfwd : config.hostfwd) {
-        struct in_addr host_addr{};
-        struct in_addr guest_addr{};
+        struct in_addr host_addr {};
+        struct in_addr guest_addr {};
         host_addr.s_addr = htonl(hostfwd.host_ip);
         guest_addr.s_addr = htonl(hostfwd.guest_ip);
         if (slirp_add_hostfwd(slirp, static_cast<int>(hostfwd.is_udp), host_addr, hostfwd.host_port, guest_addr,
diff --git a/tests/misc/test-utils.h b/tests/misc/test-utils.h
index 660ada53e..9fc017d64 100644
--- a/tests/misc/test-utils.h
+++ b/tests/misc/test-utils.h
@@ -68,7 +68,7 @@ static hash_type calculate_proof_root_hash(const cartesi::machine_merkle_tree::p
     hash_type hash;
     memcpy(hash.data(), proof.get_target_hash().data(), sizeof(cm_hash));
     for (int log2_size = static_cast<int>(proof.get_log2_target_size());
-        log2_size < static_cast<int>(proof.get_log2_root_size()); ++log2_size) {
+         log2_size < static_cast<int>(proof.get_log2_root_size()); ++log2_size) {
         cartesi::keccak_256_hasher h;
         auto bit = (proof.get_target_address() & (UINT64_C(1) << log2_size));
         hash_type first;
diff --git a/uarch/machine-uarch-bridge-state-access.h b/uarch/machine-uarch-bridge-state-access.h
index f5dfc0b84..e8eea56c5 100644
--- a/uarch/machine-uarch-bridge-state-access.h
+++ b/uarch/machine-uarch-bridge-state-access.h
@@ -56,11 +56,11 @@ class machine_uarch_bridge_state_access :
     public i_accept_scoped_note<machine_uarch_bridge_state_access>,
     public i_prefer_shadow_state<machine_uarch_bridge_state_access> {
 
-    //NOLINTNEXTLINE(cppcoreguidelines-avoid-const-or-ref-data-members)
+    // NOLINTNEXTLINE(cppcoreguidelines-avoid-const-or-ref-data-members)
     std::array<std::optional<mock_pma_entry>, PMA_MAX> &m_pmas;
 
 public:
-    machine_uarch_bridge_state_access(std::array<std::optional<mock_pma_entry>, PMA_MAX> &pmas): m_pmas(pmas) {}
+    machine_uarch_bridge_state_access(std::array<std::optional<mock_pma_entry>, PMA_MAX> &pmas) : m_pmas(pmas) {}
     machine_uarch_bridge_state_access(const machine_uarch_bridge_state_access &other) = default;
     machine_uarch_bridge_state_access(machine_uarch_bridge_state_access &&other) = default;
     machine_uarch_bridge_state_access &operator=(const machine_uarch_bridge_state_access &other) = delete;
diff --git a/uarch/uarch-run.cpp b/uarch/uarch-run.cpp
index 1248daa0f..d1b54dfa0 100644
--- a/uarch/uarch-run.cpp
+++ b/uarch/uarch-run.cpp
@@ -18,14 +18,14 @@
 
 #include "compiler-defines.h"
 #include "interpret.h"
-#include "mock-pma-entry.h"
 #include "machine-uarch-bridge-state-access.h"
+#include "mock-pma-entry.h"
 #include "uarch-constants.h"
 #include "uarch-ecall.h"
 
 #include <array>
-#include <optional>
 #include <cstdint>
+#include <optional>
 
 using namespace cartesi;
 
diff --git a/uarch/uarch-runtime.cpp b/uarch/uarch-runtime.cpp
index 932544cef..4824e90d2 100644
--- a/uarch/uarch-runtime.cpp
+++ b/uarch/uarch-runtime.cpp
@@ -82,9 +82,9 @@ extern "C" void *memset(void *ptr, int value, size_t num) {
 extern "C" NO_RETURN void abort() {
     // NOLINTNEXTLINE(hicpp-no-assembler)
     asm volatile("ebreak"
-        : // no output
-        : // no input
-        : // no affected registers
+                 : // no output
+                 : // no input
+                 : // no affected registers
     );
     // execution will never reach this point
     __builtin_trap();

From c1506b0014f7a8e545b70cd7b6fae7688b859949 Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Sat, 8 Feb 2025 12:13:54 +0000
Subject: [PATCH 14/82] refactor: move log out of record state access

---
 src/machine.cpp                 | 14 +++++++-----
 src/scoped-note.h               |  4 ++--
 src/uarch-record-state-access.h | 40 ++++++++-------------------------
 3 files changed, 19 insertions(+), 39 deletions(-)

diff --git a/src/machine.cpp b/src/machine.cpp
index 5d08b599b..60f4bfb74 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -2376,7 +2376,8 @@ access_log machine::log_reset_uarch(const access_log::type &log_type) {
     hash_type root_hash_before;
     get_root_hash(root_hash_before);
     // Call uarch_reset_state with a uarch_record_state_access object
-    uarch_record_state_access a(*this, log_type);
+    access_log log(log_type);
+    uarch_record_state_access a(*this, log);
     {
         [[maybe_unused]] auto note = a.make_scoped_note("reset_uarch_state");
         uarch_reset_state(a);
@@ -2385,8 +2386,8 @@ access_log machine::log_reset_uarch(const access_log::type &log_type) {
     hash_type root_hash_after;
     update_merkle_tree();
     get_root_hash(root_hash_after);
-    verify_reset_uarch(root_hash_before, *a.get_log(), root_hash_after);
-    return std::move(*a.get_log());
+    verify_reset_uarch(root_hash_before, log, root_hash_after);
+    return log;
 }
 
 void machine::verify_reset_uarch(const hash_type &root_hash_before, const access_log &log,
@@ -2412,8 +2413,9 @@ access_log machine::log_step_uarch(const access_log::type &log_type) {
     }
     hash_type root_hash_before;
     get_root_hash(root_hash_before);
+    access_log log(log_type);
     // Call interpret with a logged state access object
-    uarch_record_state_access a(*this, log_type);
+    uarch_record_state_access a(*this, log);
     {
         [[maybe_unused]] auto note = a.make_scoped_note("step");
         uarch_step(a);
@@ -2421,8 +2423,8 @@ access_log machine::log_step_uarch(const access_log::type &log_type) {
     // Verify access log before returning
     hash_type root_hash_after;
     get_root_hash(root_hash_after);
-    verify_step_uarch(root_hash_before, *a.get_log(), root_hash_after);
-    return std::move(*a.get_log());
+    verify_step_uarch(root_hash_before, log, root_hash_after);
+    return log;
 }
 
 // Declaration of explicit instantiation in module uarch-step.cpp
diff --git a/src/scoped-note.h b/src/scoped-note.h
index b5286b092..d3cca5014 100644
--- a/src/scoped-note.h
+++ b/src/scoped-note.h
@@ -23,7 +23,7 @@ namespace cartesi {
 template <typename STATE_ACCESS>
 class scoped_note {
 
-    STATE_ACCESS &m_a;
+    STATE_ACCESS m_a;
     const char *const m_text; ///< String with the text for the annotation
 
 public:
@@ -31,7 +31,7 @@ class scoped_note {
     /// \param a State access receiving annotations
     /// \param text Pointer to annotation text (must be valid until destruction)
     /// \details A note is added at the moment of construction and destruction
-    scoped_note(STATE_ACCESS &a, const char *text) : m_a{a}, m_text(text) {
+    scoped_note(STATE_ACCESS a, const char *text) : m_a{a}, m_text(text) {
         m_a.push_begin_bracket(m_text);
     }
 
diff --git a/src/uarch-record-state-access.h b/src/uarch-record-state-access.h
index d7bad6ad1..8c2c2d4cc 100644
--- a/src/uarch-record-state-access.h
+++ b/src/uarch-record-state-access.h
@@ -22,7 +22,6 @@
 #include <cassert>
 #include <cstdint>
 #include <cstring>
-#include <memory>
 #include <stdexcept>
 #include <string>
 #include <utility>
@@ -61,8 +60,8 @@ class uarch_record_state_access :
 
     // NOLINTBEGIN(cppcoreguidelines-avoid-const-or-ref-data-members)
     machine &m_m; ///< Macro machine
+    access_log &m_log; ///< Access log
     // NOLINTEND(cppcoreguidelines-avoid-const-or-ref-data-members)
-    std::shared_ptr<access_log> m_log; ///< Pointer to access log
 
     static auto get_hash(hasher_type &hasher, const access_data &data) {
         hash_type hash{};
@@ -72,35 +71,14 @@ class uarch_record_state_access :
 
 public:
     /// \brief Constructor from machine and uarch states.
-    /// \param um Reference to uarch state.
     /// \param m Reference to machine state.
-    explicit uarch_record_state_access(machine &m, access_log::type log_type) :
+    /// \param log Reference to log.
+    explicit uarch_record_state_access(machine &m, access_log &log) :
         m_m(m),
-        m_log(std::make_shared<access_log>(log_type)) {
+        m_log(log) {
         ;
     }
 
-    /// \brief No copy constructor
-    uarch_record_state_access(const uarch_record_state_access &) = delete;
-    /// \brief No copy assignment
-    uarch_record_state_access &operator=(const uarch_record_state_access &) = delete;
-    /// \brief No move constructor
-    uarch_record_state_access(uarch_record_state_access &&) = delete;
-    /// \brief No move assignment
-    uarch_record_state_access &operator=(uarch_record_state_access &&) = delete;
-    /// \brief Default destructor
-    ~uarch_record_state_access() = default;
-
-    /// \brief Returns const pointer to access log.
-    std::shared_ptr<const access_log> get_log() const {
-        return m_log;
-    }
-
-    /// \brief Returns pointer to access log.
-    std::shared_ptr<access_log> get_log() {
-        return m_log;
-    }
-
 private:
     static std::pair<uint64_t, int> adjust_access(uint64_t paddr, int log2_size) {
         static_assert(cartesi::log2_size_v<uint64_t> <= machine_merkle_tree::get_log2_word_size(),
@@ -115,7 +93,7 @@ class uarch_record_state_access :
     }
 
     void log_access(access &&a, const char *text) const {
-        m_log->push_access(std::move(a), text);
+        m_log.push_access(std::move(a), text);
     }
 
     static void log_access_type(access &a, access_type type) {
@@ -150,7 +128,7 @@ class uarch_record_state_access :
     }
 
     void log_read_data_if_requested(access &a, uint64_t paddr, int log2_size) const {
-        if (m_log->get_log_type().has_large_data()) {
+        if (m_log.get_log_type().has_large_data()) {
             std::ignore = log_read_data(a, paddr, log2_size);
         }
     }
@@ -165,7 +143,7 @@ class uarch_record_state_access :
     }
 
     void log_written_data_if_requested(access &a, uint64_t paddr, int log2_size) const {
-        if (m_log->get_log_type().has_large_data()) {
+        if (m_log.get_log_type().has_large_data()) {
             log_written_data(a, paddr, log2_size);
         }
     }
@@ -320,11 +298,11 @@ class uarch_record_state_access :
     friend i_accept_scoped_note<uarch_record_state_access>;
 
     void do_push_begin_bracket(const char *text) {
-        m_log->push_begin_bracket(text);
+        m_log.push_begin_bracket(text);
     }
 
     void do_push_end_bracket(const char *text) {
-        m_log->push_end_bracket(text);
+        m_log.push_end_bracket(text);
     }
 
     auto do_make_scoped_note(const char *text) {

From 2cf9c3ca390446f89de009aecbe0014234f6f90b Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Sat, 8 Feb 2025 14:11:39 +0000
Subject: [PATCH 15/82] fix: lint and format with new specs

---
 .clang-tidy                      |  1 +
 src/access-log.h                 |  4 ++--
 src/i-hasher.h                   |  3 ---
 src/interpret.cpp                |  8 ++++----
 src/json-util.cpp                |  2 +-
 src/jsonrpc-remote-machine.cpp   |  6 +++---
 src/keccak-256-hasher.h          |  3 ++-
 src/machine-reg.h                |  4 ++--
 src/machine.cpp                  |  8 ++++----
 src/os.cpp                       | 12 ++++++------
 src/shadow-pmas.h                |  2 +-
 src/shadow-state.h               |  2 +-
 src/shadow-tlb.h                 |  2 +-
 src/shadow-uarch-state.h         |  2 +-
 src/uarch-record-state-access.h  | 11 +++++++----
 src/uarch-replay-state-access.h  | 10 ++++++++++
 src/uarch-state-access.h         |  5 +++++
 src/virtio-net-carrier-slirp.cpp |  4 ++--
 tests/misc/test-utils.h          |  2 +-
 uarch/uarch-runtime.cpp          |  6 +++---
 20 files changed, 57 insertions(+), 40 deletions(-)

diff --git a/.clang-tidy b/.clang-tidy
index bdd70a8f7..c4a280dff 100644
--- a/.clang-tidy
+++ b/.clang-tidy
@@ -3,6 +3,7 @@ Checks: >-
   -boost-use-ranges,
   bugprone*,
   -bugprone-easily-swappable-parameters,
+  -bugprone-crtp-constructor-accessibility,
   cert*,
   -cert-int09-c,
   clang-analyzer*,
diff --git a/src/access-log.h b/src/access-log.h
index 62e526f6c..7e5e45c9c 100644
--- a/src/access-log.h
+++ b/src/access-log.h
@@ -304,7 +304,7 @@ class access_log {
             // Make sure we have room for the matching end bracket as well.
             // That way, unless the user is messing with unbalanced brackets, there is no way we
             // would throw an exception for lack of memory on the matching end bracket
-            m_brackets.push_back(bracket_note{bracket_type::begin, m_accesses.size(), text});
+            m_brackets.push_back(bracket_note{.type = bracket_type::begin, .where = m_accesses.size(), .text = text});
             m_brackets.reserve(m_brackets.size() + m_outstanding_ends);
         }
     }
@@ -314,7 +314,7 @@ class access_log {
             // If we failed to push, it was because the system is completely screwed anyway *and* the
             // user is using unbalanced brackets. Therefore, it's OK to quietly ignore the error.
             try {
-                m_brackets.push_back(bracket_note{bracket_type::end, m_accesses.size(), text});
+                m_brackets.push_back(bracket_note{.type = bracket_type::end, .where = m_accesses.size(), .text = text});
             } catch (...) { // NOLINT(bugprone-empty-catch)
             }
             // Decrement number of outstanding end brackets we are expecting
diff --git a/src/i-hasher.h b/src/i-hasher.h
index 790d98b2f..b00645493 100644
--- a/src/i-hasher.h
+++ b/src/i-hasher.h
@@ -35,9 +35,6 @@ namespace cartesi {
 /// \tparam HASH_SIZE Size of hash.
 template <typename DERIVED, typename HASH_SIZE>
 class i_hasher { // CRTP
-    i_hasher() = default;
-    friend DERIVED;
-
     /// \brief Returns object cast as the derived class
     DERIVED &derived() {
         return *static_cast<DERIVED *>(this);
diff --git a/src/interpret.cpp b/src/interpret.cpp
index d75b5ea5c..f8c0b44d9 100644
--- a/src/interpret.cpp
+++ b/src/interpret.cpp
@@ -279,7 +279,7 @@ static void dump_exception_or_interrupt(uint64_t cause, uint64_t a7) {
 
 /// \brief Returns the name for a given privilege level
 /// \param prv Privilege level
-constexpr const char *prv_get_name(uint64_t prv) {
+static constexpr const char *prv_get_name(uint64_t prv) {
     switch (prv) {
         case PRV_U:
             return "prv.U";
@@ -1004,7 +1004,7 @@ static NO_INLINE std::pair<bool, uint64_t> read_virtual_memory_slow(STATE_ACCESS
         if (likely(pma.get_istart_M())) {
             [[maybe_unused]] auto note = a.make_scoped_note("read memory");
             const auto faddr = replace_tlb_entry<TLB_READ>(a, vaddr, paddr, pma_index);
-            a.template read_memory_word(faddr, pma_index, pval);
+            a.template read_memory_word<T>(faddr, pma_index, pval);
             return {true, pc};
         }
         if (likely(pma.get_istart_IO())) {
@@ -5453,7 +5453,7 @@ static FORCE_INLINE fetch_status fetch_insn(STATE_ACCESS a, uint64_t &pc, uint32
     if (unlikely(((~pc & PAGE_OFFSET_MASK) >> 1) == 0)) {
         // Here we are crossing page boundary, this is unlikely (1 in 2048 possible cases)
         uint16_t insn16 = 0;
-        a.template read_memory_word(faddr, last_pma_index, &insn16);
+        a.template read_memory_word<uint16_t>(faddr, last_pma_index, &insn16);
         insn = insn16;
         // If not a compressed instruction, we must read 2 additional bytes from the next page.
         if (unlikely(insn_is_uncompressed(insn))) {
@@ -5468,7 +5468,7 @@ static FORCE_INLINE fetch_status fetch_insn(STATE_ACCESS a, uint64_t &pc, uint32
             last_vp_offset = pc2_vp_offset;
             last_pma_index = pc2_pma_index;
             faddr = pc2 + last_vp_offset;
-            a.template read_memory_word(faddr, last_pma_index, &insn16);
+            a.template read_memory_word<uint16_t>(faddr, last_pma_index, &insn16);
             insn |= insn16 << 16;
         }
         return fetch_status::success;
diff --git a/src/json-util.cpp b/src/json-util.cpp
index 4fc036b2c..a80e85e07 100644
--- a/src/json-util.cpp
+++ b/src/json-util.cpp
@@ -894,7 +894,7 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key,
     }
     const auto sibling_hashes_base = path + "sibling_hashes/";
     for (int log2_size = proof.get_log2_target_size(), i = 0; log2_size < proof.get_log2_root_size();
-         ++log2_size, ++i) {
+        ++log2_size, ++i) {
         machine_merkle_tree::proof_type::hash_type sibling_hash;
         ju_get_field(sh, i, sibling_hash, sibling_hashes_base);
         proof.set_sibling_hash(sibling_hash, log2_size);
diff --git a/src/jsonrpc-remote-machine.cpp b/src/jsonrpc-remote-machine.cpp
index 021c106c3..b1d7c30ec 100644
--- a/src/jsonrpc-remote-machine.cpp
+++ b/src/jsonrpc-remote-machine.cpp
@@ -98,7 +98,7 @@ static std::ostream &operator<<(std::ostream &out, log_prefix prefix) {
     using namespace slog;
     char stime[std::size("yyyy-mm-dd hh-mm-ss")];
     const time_t t = time(nullptr);
-    struct tm ttime {};
+    struct tm ttime{};
     if (strftime(std::data(stime), std::size(stime), "%Y-%m-%d %H-%M-%S", localtime_r(&t, &ttime)) != 0) {
         out << stime << " ";
     }
@@ -116,7 +116,7 @@ using json = nlohmann::json;
 /// \brief Installs a signal handler
 template <typename HANDLER>
 static void install_signal_handler(int signum, HANDLER handler) {
-    struct sigaction act {};
+    struct sigaction act{};
     if (sigemptyset(&act.sa_mask) < 0) {
         throw std::system_error{errno, std::generic_category(), "sigemptyset failed"};
     }
@@ -1749,7 +1749,7 @@ int main(int argc, char *argv[]) try {
         }
         SLOG(info) << "attempting to inherit fd " << server_fd << " from parent";
         // check socket is listening and is of right domain and type
-        struct sockaddr_in fd_addr {};
+        struct sockaddr_in fd_addr{};
         socklen_t len = sizeof(fd_addr);
         memset(&fd_addr, 0, len);
         // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
diff --git a/src/keccak-256-hasher.h b/src/keccak-256-hasher.h
index a649d8d29..bac5d8963 100644
--- a/src/keccak-256-hasher.h
+++ b/src/keccak-256-hasher.h
@@ -39,8 +39,9 @@ struct keccak_instance final {
 
 class keccak_256_hasher final : public i_hasher<keccak_256_hasher, std::integral_constant<int, 32>> {
     sha3_ctx_t m_ctx{};
+    using base = i_hasher<keccak_256_hasher, std::integral_constant<int, 32>>;
 
-    friend i_hasher<keccak_256_hasher, std::integral_constant<int, 32>>;
+    friend base;
 
     void do_begin() {
         sha3_init(&m_ctx, 32, 0x01);
diff --git a/src/machine-reg.h b/src/machine-reg.h
index 57765353e..48f868b5c 100644
--- a/src/machine-reg.h
+++ b/src/machine-reg.h
@@ -193,11 +193,11 @@ enum class machine_reg : uint64_t {
 };
 
 static constexpr uint64_t machine_reg_address(machine_reg reg, int i = 0) {
-    return static_cast<uint64_t>(reg) + i * sizeof(uint64_t);
+    return static_cast<uint64_t>(reg) + (i * sizeof(uint64_t));
 }
 
 static constexpr machine_reg machine_reg_enum(machine_reg reg, int i) {
-    return static_cast<machine_reg>(static_cast<uint64_t>(reg) + i * sizeof(uint64_t));
+    return static_cast<machine_reg>(static_cast<uint64_t>(reg) + (i * sizeof(uint64_t)));
 }
 
 static constexpr machine_reg machine_reg_enum(shadow_state_what reg) {
diff --git a/src/machine.cpp b/src/machine.cpp
index 60f4bfb74..9f59ba01a 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -359,14 +359,14 @@ machine::machine(machine_config c, machine_runtime_config r) : m_c{std::move(c)}
         register_pma_entry(make_callocd_memory_pma_entry("RAM"s, PMA_RAM_START, m_c.ram.length).set_flags(m_ram_flags));
     } else {
         register_pma_entry(make_callocd_memory_pma_entry("RAM"s, PMA_RAM_START, m_c.ram.length, m_c.ram.image_filename)
-                               .set_flags(m_ram_flags));
+                .set_flags(m_ram_flags));
     }
 
     // Register DTB
     pma_entry &dtb = register_pma_entry((m_c.dtb.image_filename.empty() ?
             make_callocd_memory_pma_entry("DTB"s, PMA_DTB_START, PMA_DTB_LENGTH) :
             make_callocd_memory_pma_entry("DTB"s, PMA_DTB_START, PMA_DTB_LENGTH, m_c.dtb.image_filename))
-                                            .set_flags(m_dtb_flags));
+            .set_flags(m_dtb_flags));
 
     // Register all flash drives
     int i = 0; // NOLINT(misc-const-correctness)
@@ -735,7 +735,7 @@ static void store_device_pma(const machine &m, const pma_entry &pma, const std::
     auto name = machine_config::get_image_filename(dir, pma.get_start(), pma.get_length());
     auto fp = unique_fopen(name.c_str(), "wb");
     for (uint64_t page_start_in_range = 0; page_start_in_range < pma.get_length();
-         page_start_in_range += PMA_PAGE_SIZE) {
+        page_start_in_range += PMA_PAGE_SIZE) {
         const unsigned char *page_data = nullptr;
         auto peek = pma.get_peek();
         if (!peek(pma, m, page_start_in_range, PMA_PAGE_SIZE, &page_data, scratch.get())) {
@@ -1825,7 +1825,7 @@ bool machine::verify_dirty_page_maps() const {
     for (const auto &pma : m_s.pmas) {
         auto peek = pma.get_peek();
         for (uint64_t page_start_in_range = 0; page_start_in_range < pma.get_length();
-             page_start_in_range += PMA_PAGE_SIZE) {
+            page_start_in_range += PMA_PAGE_SIZE) {
             const uint64_t page_address = pma.get_start() + page_start_in_range;
             if (pma.get_istart_M()) {
                 const unsigned char *page_data = nullptr;
diff --git a/src/os.cpp b/src/os.cpp
index 000112553..5e9fe08a3 100644
--- a/src/os.cpp
+++ b/src/os.cpp
@@ -255,7 +255,7 @@ void os_open_tty() {
 #endif
         return;
     }
-    struct termios tty {};
+    struct termios tty{};
     if (tcgetattr(ttyfd, &tty) < 0) { // Failed to retrieve old mode
 #ifdef DEBUG_OS
         std::ignore = fprintf(stderr, "os_open_tty(): failed retrieve old mode\n");
@@ -322,7 +322,7 @@ void os_open_tty() {
 
 #ifdef HAVE_SIGACTION
     // Install console resize signal handler
-    struct sigaction sigact {};
+    struct sigaction sigact{};
     sigact.sa_flags = SA_RESTART;
     sigact.sa_handler = os_SIGWINCH_handler;
     if (sigemptyset(&sigact.sa_mask) != 0 || sigaction(SIGWINCH, &sigact, nullptr) != 0) {
@@ -567,7 +567,7 @@ unsigned char *os_map_file(const char *path, uint64_t length, bool shared) {
     }
 
     // Try to get file size
-    struct stat statbuf {};
+    struct stat statbuf{};
     if (fstat(backing_file, &statbuf) < 0) {
         close(backing_file);
         throw std::system_error{errno, std::generic_category(),
@@ -605,7 +605,7 @@ unsigned char *os_map_file(const char *path, uint64_t length, bool shared) {
     }
 
     // Try to get file size
-    struct __stat64 statbuf {};
+    struct __stat64 statbuf{};
     if (_fstat64(backing_file, &statbuf) < 0) {
         _close(backing_file);
         throw std::system_error{errno, std::generic_category(),
@@ -773,7 +773,7 @@ bool os_select_fds(const os_select_before_callback &before_cb, const os_select_a
 
 void os_disable_sigpipe() {
 #ifdef HAVE_SIGACTION
-    struct sigaction sigact {};
+    struct sigaction sigact{};
     sigact.sa_handler = SIG_IGN;
     sigact.sa_flags = SA_RESTART;
     if (sigemptyset(&sigact.sa_mask) != 0 || sigaction(SIGPIPE, &sigact, nullptr) != 0) {
@@ -814,7 +814,7 @@ int64_t os_get_file_length(const char *filename, const char *text) {
 }
 
 bool os_file_exists(const char *filename) {
-    struct stat buffer {};
+    struct stat buffer{};
     return (stat(filename, &buffer) == 0);
 }
 
diff --git a/src/shadow-pmas.h b/src/shadow-pmas.h
index 523db548e..95f5837e7 100644
--- a/src/shadow-pmas.h
+++ b/src/shadow-pmas.h
@@ -50,7 +50,7 @@ enum class shadow_pmas_what : uint64_t {
 /// \param p Index of desired shadow PMA entry
 /// \returns The address.
 static constexpr uint64_t shadow_pmas_get_pma_abs_addr(uint64_t p) {
-    return PMA_SHADOW_PMAS_START + p * sizeof(shadow_pmas_entry);
+    return PMA_SHADOW_PMAS_START + (p * sizeof(shadow_pmas_entry));
 }
 
 /// \brief Obtains the absolute address of a PMA entry in shadow memory.
diff --git a/src/shadow-state.h b/src/shadow-state.h
index 8a02d2fa4..4efbc3b00 100644
--- a/src/shadow-state.h
+++ b/src/shadow-state.h
@@ -198,7 +198,7 @@ static constexpr shadow_state_what shadow_state_get_what(uint64_t paddr) {
 }
 
 static constexpr shadow_state_what shadow_state_get_what(shadow_state_what what, int i) {
-    return static_cast<shadow_state_what>(static_cast<uint64_t>(what) + i * sizeof(uint64_t));
+    return static_cast<shadow_state_what>(static_cast<uint64_t>(what) + (i * sizeof(uint64_t)));
 }
 
 static constexpr const char *shadow_state_get_what_name(shadow_state_what what) {
diff --git a/src/shadow-tlb.h b/src/shadow-tlb.h
index 52a5d66e0..4666ecfd7 100644
--- a/src/shadow-tlb.h
+++ b/src/shadow-tlb.h
@@ -67,7 +67,7 @@ enum class shadow_tlb_what : uint64_t {
 };
 
 static constexpr uint64_t shadow_tlb_get_abs_addr(TLB_set_index set_index, uint64_t slot_index) {
-    return PMA_SHADOW_TLB_START + set_index * sizeof(shadow_tlb_set) + slot_index * sizeof(shadow_tlb_slot);
+    return PMA_SHADOW_TLB_START + (set_index * sizeof(shadow_tlb_set)) + (slot_index * sizeof(shadow_tlb_slot));
 }
 
 static constexpr uint64_t shadow_tlb_get_abs_addr(TLB_set_index set_index, uint64_t slot_index, shadow_tlb_what what) {
diff --git a/src/shadow-uarch-state.h b/src/shadow-uarch-state.h
index b30762861..d161dcd27 100644
--- a/src/shadow-uarch-state.h
+++ b/src/shadow-uarch-state.h
@@ -86,7 +86,7 @@ static constexpr shadow_uarch_state_what shadow_uarch_state_get_what(uint64_t pa
 }
 
 static constexpr shadow_uarch_state_what shadow_uarch_state_get_what(shadow_uarch_state_what what, int i) {
-    return static_cast<shadow_uarch_state_what>(static_cast<uint64_t>(what) + i * sizeof(uint64_t));
+    return static_cast<shadow_uarch_state_what>(static_cast<uint64_t>(what) + (i * sizeof(uint64_t)));
 }
 
 static constexpr const char *shadow_uarch_state_get_what_name(shadow_uarch_state_what what) {
diff --git a/src/uarch-record-state-access.h b/src/uarch-record-state-access.h
index 8c2c2d4cc..19a763941 100644
--- a/src/uarch-record-state-access.h
+++ b/src/uarch-record-state-access.h
@@ -59,7 +59,7 @@ class uarch_record_state_access :
     using hash_type = machine_merkle_tree::hash_type;
 
     // NOLINTBEGIN(cppcoreguidelines-avoid-const-or-ref-data-members)
-    machine &m_m; ///< Macro machine
+    machine &m_m;      ///< Macro machine
     access_log &m_log; ///< Access log
     // NOLINTEND(cppcoreguidelines-avoid-const-or-ref-data-members)
 
@@ -73,9 +73,7 @@ class uarch_record_state_access :
     /// \brief Constructor from machine and uarch states.
     /// \param m Reference to machine state.
     /// \param log Reference to log.
-    explicit uarch_record_state_access(machine &m, access_log &log) :
-        m_m(m),
-        m_log(log) {
+    explicit uarch_record_state_access(machine &m, access_log &log) : m_m(m), m_log(log) {
         ;
     }
 
@@ -308,6 +306,11 @@ class uarch_record_state_access :
     auto do_make_scoped_note(const char *text) {
         return scoped_note{*this, text};
     }
+
+    // -----
+    // i_prefer_shadow_uarch_state interface implementation
+    // -----
+    friend i_prefer_shadow_uarch_state<uarch_record_state_access>;
 };
 
 } // namespace cartesi
diff --git a/src/uarch-replay-state-access.h b/src/uarch-replay-state-access.h
index 01a2e4fc8..6881000be 100644
--- a/src/uarch-replay-state-access.h
+++ b/src/uarch-replay-state-access.h
@@ -361,6 +361,16 @@ class uarch_replay_state_access :
         return "uarch_replay_state_access";
 >>>>>>> 1e5dc22 (refactor: clean up uarch state access mechanism)
     }
+
+    // -----
+    // i_prefer_shadow_uarch_state interface implementation
+    // -----
+    friend i_prefer_shadow_uarch_state<uarch_replay_state_access>;
+
+    // -----
+    // i_accept_scoped_note interface implementation
+    // -----
+    friend i_accept_scoped_note<uarch_replay_state_access>;
 };
 
 } // namespace cartesi
diff --git a/src/uarch-state-access.h b/src/uarch-state-access.h
index 8c1821951..cf342d587 100644
--- a/src/uarch-state-access.h
+++ b/src/uarch-state-access.h
@@ -157,6 +157,11 @@ class uarch_state_access :
     constexpr const char *do_get_name() const {
         return "uarch_state_access";
     }
+
+    // -----
+    // i_accept_scoped_note interface implementation
+    // -----
+    friend i_accept_scoped_note<uarch_state_access>;
 };
 
 } // namespace cartesi
diff --git a/src/virtio-net-carrier-slirp.cpp b/src/virtio-net-carrier-slirp.cpp
index edc0fe92b..39a72986f 100644
--- a/src/virtio-net-carrier-slirp.cpp
+++ b/src/virtio-net-carrier-slirp.cpp
@@ -209,8 +209,8 @@ virtio_net_carrier_slirp::virtio_net_carrier_slirp(const cartesi::virtio_net_use
 
     // Setup host forward ports
     for (const auto &hostfwd : config.hostfwd) {
-        struct in_addr host_addr {};
-        struct in_addr guest_addr {};
+        struct in_addr host_addr{};
+        struct in_addr guest_addr{};
         host_addr.s_addr = htonl(hostfwd.host_ip);
         guest_addr.s_addr = htonl(hostfwd.guest_ip);
         if (slirp_add_hostfwd(slirp, static_cast<int>(hostfwd.is_udp), host_addr, hostfwd.host_port, guest_addr,
diff --git a/tests/misc/test-utils.h b/tests/misc/test-utils.h
index 9fc017d64..660ada53e 100644
--- a/tests/misc/test-utils.h
+++ b/tests/misc/test-utils.h
@@ -68,7 +68,7 @@ static hash_type calculate_proof_root_hash(const cartesi::machine_merkle_tree::p
     hash_type hash;
     memcpy(hash.data(), proof.get_target_hash().data(), sizeof(cm_hash));
     for (int log2_size = static_cast<int>(proof.get_log2_target_size());
-         log2_size < static_cast<int>(proof.get_log2_root_size()); ++log2_size) {
+        log2_size < static_cast<int>(proof.get_log2_root_size()); ++log2_size) {
         cartesi::keccak_256_hasher h;
         auto bit = (proof.get_target_address() & (UINT64_C(1) << log2_size));
         hash_type first;
diff --git a/uarch/uarch-runtime.cpp b/uarch/uarch-runtime.cpp
index 4824e90d2..932544cef 100644
--- a/uarch/uarch-runtime.cpp
+++ b/uarch/uarch-runtime.cpp
@@ -82,9 +82,9 @@ extern "C" void *memset(void *ptr, int value, size_t num) {
 extern "C" NO_RETURN void abort() {
     // NOLINTNEXTLINE(hicpp-no-assembler)
     asm volatile("ebreak"
-                 : // no output
-                 : // no input
-                 : // no affected registers
+        : // no output
+        : // no input
+        : // no affected registers
     );
     // execution will never reach this point
     __builtin_trap();

From 8ba4e7969262c3af538aaac32e4c3d7999c908a8 Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Sun, 9 Feb 2025 22:14:56 +0000
Subject: [PATCH 16/82] refactor: improve includes

---
 src/Makefile                                  |  1 -
 src/back-merkle-tree.cpp                      |  3 +-
 src/base64.cpp                                |  4 +-
 src/clint-factory.cpp                         |  3 +-
 src/clint.cpp                                 |  3 +-
 src/clua-cartesi-jsonrpc.cpp                  |  7 +++
 src/clua-cartesi.cpp                          |  5 ++
 src/clua-i-virtual-machine.cpp                | 10 +++-
 src/clua.cpp                                  |  6 +-
 src/complete-merkle-tree.cpp                  |  3 +-
 src/dtb.cpp                                   |  3 +-
 src/dump.h                                    |  7 +--
 src/full-merkle-tree.cpp                      |  3 +-
 src/host-addr.h                               |  4 +-
 src/htif-factory.cpp                          |  3 +-
 src/htif.cpp                                  |  3 +-
 src/{i-counters.h => i-accept-counters.h}     | 20 +++----
 ...-scoped-note.h => i-accept-scoped-notes.h} | 20 +++----
 src/i-device-state-access.h                   | 15 ++---
 src/i-interactive-state-access.h              |  4 +-
 src/i-prefer-shadow-state.h                   |  6 +-
 src/i-prefer-shadow-uarch-state.h             |  4 +-
 src/i-state-access.h                          | 15 +++--
 src/interpret.cpp                             | 57 +++++++++----------
 src/json-util.cpp                             |  7 ++-
 src/jsonrpc-machine-c-api.cpp                 | 13 +----
 src/jsonrpc-remote-machine.cpp                |  4 +-
 src/jsonrpc-virtual-machine.cpp               | 12 ++--
 src/machine-c-api.cpp                         |  2 +
 src/machine-config.cpp                        |  3 +-
 src/machine-merkle-tree.cpp                   |  5 +-
 src/machine.cpp                               | 18 +++---
 src/os.cpp                                    | 11 ++--
 src/plic-factory.cpp                          |  3 +-
 src/pma-constants.h                           |  5 --
 src/pma-defines.h                             |  1 -
 src/pma.cpp                                   |  1 +
 src/record-send-cmio-state-access.h           |  8 +--
 src/record-step-state-access.h                |  4 +-
 src/replay-step-state-access-interop.cpp      |  5 ++
 src/replay-step-state-access.h                |  4 +-
 src/send-cmio-response.cpp                    |  7 +--
 src/shadow-pmas-factory.cpp                   |  3 -
 src/shadow-state-factory.cpp                  |  4 +-
 src/shadow-state.cpp                          |  1 +
 src/shadow-tlb-factory.cpp                    |  4 +-
 src/shadow-tlb.h                              | 16 ++++--
 src/shadow-uarch-state-factory.cpp            |  4 +-
 src/shadow-uarch-state.cpp                    |  1 +
 src/state-access.h                            | 12 ++--
 src/tlb.h                                     | 10 +++-
 src/uarch-record-state-access.h               |  8 +--
 src/uarch-replay-state-access.h               |  8 +--
 src/uarch-reset-state.cpp                     |  1 +
 src/uarch-state-access.h                      |  8 +--
 src/virtio-device.cpp                         |  9 +--
 src/virtio-net-carrier-slirp.cpp              |  4 ++
 src/virtio-net-carrier-tuntap.cpp             |  1 +
 src/virtual-machine.cpp                       |  1 +
 tests/misc/test-merkle-tree-hash.cpp          |  2 +-
 uarch/machine-uarch-bridge-state-access.h     |  4 +-
 61 files changed, 238 insertions(+), 185 deletions(-)
 rename src/{i-counters.h => i-accept-counters.h} (75%)
 rename src/{i-accept-scoped-note.h => i-accept-scoped-notes.h} (88%)

diff --git a/src/Makefile b/src/Makefile
index 42701d764..ca2249122 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -179,7 +179,6 @@ DUMP_DEFS+=-DDUMP_ILLEGAL_INSN_EXCEPTIONS
 DUMP_DEFS+=-DDUMP_EXCEPTIONS
 DUMP_DEFS+=-DDUMP_INTERRUPTS
 DUMP_DEFS+=-DDUMP_MMU_EXCEPTIONS
-DUMP_DEFS+=-DDUMP_INVALID_MEM_ACCESS
 DUMP_DEFS+=-DDUMP_INVALID_CSR
 DUMP_DEFS+=-DDUMP_REGS
 DUMP_DEFS+=-DDUMP_INSN_HIST
diff --git a/src/back-merkle-tree.cpp b/src/back-merkle-tree.cpp
index 027edccb7..93eaced27 100644
--- a/src/back-merkle-tree.cpp
+++ b/src/back-merkle-tree.cpp
@@ -17,13 +17,14 @@
 /// \file
 /// \brief Back Merkle tree implementation.
 
+#include "back-merkle-tree.h"
+
 #include <algorithm>
 #include <cassert>
 #include <cstdint>
 #include <limits>
 #include <stdexcept>
 
-#include "back-merkle-tree.h"
 #include "i-hasher.h"
 
 namespace cartesi {
diff --git a/src/base64.cpp b/src/base64.cpp
index 1fb10354d..d77f55ea2 100644
--- a/src/base64.cpp
+++ b/src/base64.cpp
@@ -14,6 +14,8 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
+#include "base64.h"
+
 #include <cstddef>
 #include <cstdint>
 #include <sstream>
@@ -21,8 +23,6 @@
 #include <string>
 #include <string_view>
 
-#include "base64.h"
-
 namespace cartesi {
 
 // Base64 globals
diff --git a/src/clint-factory.cpp b/src/clint-factory.cpp
index 24e323932..0dd9ba3e7 100644
--- a/src/clint-factory.cpp
+++ b/src/clint-factory.cpp
@@ -14,9 +14,10 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
+#include "clint-factory.h"
+
 #include <cstdint>
 
-#include "clint-factory.h"
 #include "clint.h"
 #include "pma-constants.h"
 #include "pma.h"
diff --git a/src/clint.cpp b/src/clint.cpp
index 1e04a8b8f..55dbfa200 100644
--- a/src/clint.cpp
+++ b/src/clint.cpp
@@ -14,9 +14,10 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
+#include "clint.h"
+
 #include <cstdint>
 
-#include "clint.h"
 #include "i-device-state-access.h"
 #include "interpret.h"
 #include "pma-constants.h"
diff --git a/src/clua-cartesi-jsonrpc.cpp b/src/clua-cartesi-jsonrpc.cpp
index 082302db4..2f57229bb 100644
--- a/src/clua-cartesi-jsonrpc.cpp
+++ b/src/clua-cartesi-jsonrpc.cpp
@@ -14,6 +14,13 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
+#include <cstdint>
+
+extern "C" {
+#include <lauxlib.h>
+#include <lua.h>
+}
+
 #include "clua-i-virtual-machine.h"
 #include "clua.h"
 #include "jsonrpc-machine-c-api.h"
diff --git a/src/clua-cartesi.cpp b/src/clua-cartesi.cpp
index 9d513edaf..232638c87 100644
--- a/src/clua-cartesi.cpp
+++ b/src/clua-cartesi.cpp
@@ -22,6 +22,11 @@
 
 #include <boost/config.hpp>
 
+extern "C" {
+#include <lauxlib.h>
+#include <lua.h>
+}
+
 #include "base64.h"
 #include "clua-i-virtual-machine.h"
 #include "clua.h"
diff --git a/src/clua-i-virtual-machine.cpp b/src/clua-i-virtual-machine.cpp
index 593a9b893..e9a89018d 100644
--- a/src/clua-i-virtual-machine.cpp
+++ b/src/clua-i-virtual-machine.cpp
@@ -14,6 +14,8 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
+#include "clua-i-virtual-machine.h"
+
 #include <algorithm>
 #include <cassert>
 #include <cstddef>
@@ -25,8 +27,14 @@
 #include <string_view>
 #include <unordered_map>
 
+#include <json.hpp>
+
+extern "C" {
+#include <lauxlib.h>
+#include <lua.h>
+}
+
 #include "base64.h"
-#include "clua-i-virtual-machine.h"
 #include "clua.h"
 #include "machine-c-api.h"
 
diff --git a/src/clua.cpp b/src/clua.cpp
index dce1dcbda..db248ac0a 100644
--- a/src/clua.cpp
+++ b/src/clua.cpp
@@ -14,10 +14,14 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
+#include "clua.h"
+
 #include <cstddef>
 #include <cstdint>
 
-#include "clua.h"
+extern "C" {
+#include <lua.h>
+}
 
 namespace cartesi {
 
diff --git a/src/complete-merkle-tree.cpp b/src/complete-merkle-tree.cpp
index af28e3bbb..658dbe324 100644
--- a/src/complete-merkle-tree.cpp
+++ b/src/complete-merkle-tree.cpp
@@ -15,7 +15,6 @@
 //
 
 #include "complete-merkle-tree.h"
-#include "i-hasher.h"
 
 #include <algorithm>
 #include <cassert>
@@ -23,6 +22,8 @@
 #include <stdexcept>
 #include <utility>
 
+#include "i-hasher.h"
+
 /// \file
 /// \brief Complete Merkle tree implementation.
 
diff --git a/src/dtb.cpp b/src/dtb.cpp
index 9a8cc0d30..5d0914896 100644
--- a/src/dtb.cpp
+++ b/src/dtb.cpp
@@ -17,12 +17,13 @@
 /// \file
 /// \brief Device Tree Blob
 
+#include "dtb.h"
+
 #include <cstdint>
 #include <sstream>
 #include <stdexcept>
 #include <string>
 
-#include "dtb.h"
 #include "fdt-builder.h"
 #include "machine-c-version.h"
 #include "machine-config.h"
diff --git a/src/dump.h b/src/dump.h
index 507d18538..f7c00c538 100644
--- a/src/dump.h
+++ b/src/dump.h
@@ -13,12 +13,11 @@
 // You should have received a copy of the GNU Lesser General Public License along
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
-
-#include <tuple>
-
 #ifndef DUMP_H
 #define DUMP_H
 
+#include <tuple>
+
 #ifdef MICROARCHITECTURE
 template <size_t N, typename... ARGS>
 static inline void D_PRINTF(const char (&fmt)[N], ARGS... args) {
@@ -32,4 +31,4 @@ static inline auto D_PRINTF(const char (&fmt)[N], ARGS... args) {
 }
 #endif
 
-#endif
+#endif // DUMP_H
diff --git a/src/full-merkle-tree.cpp b/src/full-merkle-tree.cpp
index 5b107d8fc..e59cad55d 100644
--- a/src/full-merkle-tree.cpp
+++ b/src/full-merkle-tree.cpp
@@ -14,12 +14,13 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
+#include "full-merkle-tree.h"
+
 #include <algorithm>
 #include <limits>
 #include <stdexcept>
 #include <vector>
 
-#include "full-merkle-tree.h"
 #include "i-hasher.h"
 #include "pristine-merkle-tree.h"
 
diff --git a/src/host-addr.h b/src/host-addr.h
index af5f70dbd..a8941e2ca 100644
--- a/src/host-addr.h
+++ b/src/host-addr.h
@@ -21,8 +21,8 @@
 
 namespace cartesi {
 
-// This is simply an uint64_t as a separate type, not automatically convertible to uint64_t
-// It prevents any attempt of passing a host_addr where one is not expected
+// This is simply an uint64_t as a separate type, not automatically convertible to uint64_t.
+// It prevents any attempt of passing a host_addr where one is not expected.
 enum class host_addr : uint64_t {};
 
 // Comparison operaator
diff --git a/src/htif-factory.cpp b/src/htif-factory.cpp
index 4754b8ccc..f09b2fb39 100644
--- a/src/htif-factory.cpp
+++ b/src/htif-factory.cpp
@@ -14,9 +14,10 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
+#include "htif-factory.h"
+
 #include <cstdint>
 
-#include "htif-factory.h"
 #include "htif.h"
 #include "pma-constants.h"
 #include "pma.h"
diff --git a/src/htif.cpp b/src/htif.cpp
index 9ffcec2ef..1a17d1e02 100644
--- a/src/htif.cpp
+++ b/src/htif.cpp
@@ -14,9 +14,10 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
+#include "htif.h"
+
 #include <cstdint>
 
-#include "htif.h"
 #include "i-device-state-access.h"
 #include "interpret.h"
 #include "pma-driver.h"
diff --git a/src/i-counters.h b/src/i-accept-counters.h
similarity index 75%
rename from src/i-counters.h
rename to src/i-accept-counters.h
index 32078c6ea..70e6e81c2 100644
--- a/src/i-counters.h
+++ b/src/i-accept-counters.h
@@ -14,11 +14,11 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#ifndef I_COUNTERS_H
-#define I_COUNTERS_H
+#ifndef I_ACCEPT_COUNTERS_H
+#define I_ACCEPT_COUNTERS_H
 
 /// \file
-/// \brief Interface for state access that prefers to go thrhough shadow state
+/// \brief Accept counters interface
 
 #include <cstdint>
 #include <type_traits>
@@ -27,12 +27,11 @@
 
 namespace cartesi {
 
-/// \class i_counters
-/// \brief Interface for multiplexed access to shadow state.
+/// \class i_accept_counters
+/// \brief Interface for state access classes (and others) that accept counters.
 /// \tparam DERIVED Derived class implementing the interface. (An example of CRTP.)
-/// \detail This is for state access methods that do not need individualized access to machine registers
 template <typename DERIVED>
-class i_counters { // CRTP
+class i_accept_counters { // CRTP
 
     /// \brief Returns object cast as the derived class
     DERIVED &derived() {
@@ -58,12 +57,13 @@ class i_counters { // CRTP
     }
 };
 
-/// \brief SFINAE test implementation of the i_state_access interface
+/// \brief SFINAE test implementation of the i_accept_counters interface
 template <typename DERIVED>
-using is_an_i_counters = std::integral_constant<bool, is_template_base_of_v<i_counters, std::remove_cvref_t<DERIVED>>>;
+using is_an_i_accept_counters =
+    std::integral_constant<bool, is_template_base_of_v<i_accept_counters, std::remove_cvref_t<DERIVED>>>;
 
 template <typename DERIVED>
-constexpr bool is_an_i_counters_v = is_an_i_counters<DERIVED>::value;
+constexpr bool is_an_i_accept_counters_v = is_an_i_accept_counters<DERIVED>::value;
 
 } // namespace cartesi
 
diff --git a/src/i-accept-scoped-note.h b/src/i-accept-scoped-notes.h
similarity index 88%
rename from src/i-accept-scoped-note.h
rename to src/i-accept-scoped-notes.h
index e05124135..9a1e78d9f 100644
--- a/src/i-accept-scoped-note.h
+++ b/src/i-accept-scoped-notes.h
@@ -14,11 +14,11 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#ifndef I_ACCEPT_SCOPED_NOTE_H
-#define I_ACCEPT_SCOPED_NOTE_H
+#ifndef I_ACCEPT_SCOPED_NOTES_H
+#define I_ACCEPT_SCOPED_NOTES_H
 
 /// \file
-/// \brief State access interface
+/// \brief Accept scoped notes interface
 
 #include <cstdint>
 #include <type_traits>
@@ -31,11 +31,11 @@
 
 namespace cartesi {
 
-/// \class i_accept_scoped_note
-/// \brief Interface that lets a state access accept scoped notes.
+/// \class i_accept_scoped_notes
+/// \brief Interface that lets a state access class accept scoped notes.
 /// \tparam DERIVED Derived class implementing the interface. (An example of CRTP.)
 template <typename DERIVED>
-class i_accept_scoped_note { // CRTP
+class i_accept_scoped_notes { // CRTP
 
     /// \brief Returns object cast as the derived class
     DERIVED &derived() {
@@ -103,13 +103,13 @@ class i_accept_scoped_note { // CRTP
     }
 };
 
-/// \brief SFINAE test implementation of the i_state_access interface
+/// \brief SFINAE test implementation of the i_accept_scoped_notes interface
 template <typename DERIVED>
-using is_an_i_accept_scoped_note =
-    std::integral_constant<bool, is_template_base_of_v<i_accept_scoped_note, std::remove_cvref_t<DERIVED>>>;
+using is_an_i_accept_scoped_notes =
+    std::integral_constant<bool, is_template_base_of_v<i_accept_scoped_notes, std::remove_cvref_t<DERIVED>>>;
 
 template <typename DERIVED>
-constexpr bool is_an_i_accept_scoped_note_v = is_an_i_accept_scoped_note<DERIVED>::value;
+constexpr bool is_an_i_accept_scoped_note_v = is_an_i_accept_scoped_notes<DERIVED>::value;
 
 } // namespace cartesi
 
diff --git a/src/i-device-state-access.h b/src/i-device-state-access.h
index 784e2c684..88d4a8498 100644
--- a/src/i-device-state-access.h
+++ b/src/i-device-state-access.h
@@ -22,19 +22,16 @@
 namespace cartesi {
 
 /// \file
-/// \brief Virtual interface for state access
+/// \brief Virtual interface for device state access
 
-/// \brief Virtual interface for state access
+/// \brief Virtual interface for device state access
 /// \details \{
 /// Memory mapped devices must be able to modify the state.
-/// However, the prototype for the read/write callbacks
-/// cannot change depending on the different classes implementing the
-/// i_state_access interface (which is not virtual).
+/// However, the prototype for the read/write callbacks cannot change depending on the different classes
+/// implementing the i_state_access interface (which is not virtual).
 ///
-/// Since device access to state is not time critical, the
-/// i_device_state_access interface uses virtual methods.  A
-/// template class device_state_access implements this
-/// virtual interface on top of any class that implements the
+/// Since device access to state is not time critical, the i_device_state_access interface uses virtual methods.
+/// A template class device_state_access implements this virtual interface on top of any class that implements
 /// i_state_access.
 /// \}
 class i_device_state_access {
diff --git a/src/i-interactive-state-access.h b/src/i-interactive-state-access.h
index 3b1024be3..91ec34870 100644
--- a/src/i-interactive-state-access.h
+++ b/src/i-interactive-state-access.h
@@ -18,7 +18,7 @@
 #define I_INTERACTIVE_STATE_ACCESS_H
 
 /// \file
-/// \brief State access interface
+/// \brief Interactive state access interface
 
 #include <cstdint>
 #include <type_traits>
@@ -63,7 +63,7 @@ class i_interactive_state_access { // CRTP
     }
 };
 
-/// \brief SFINAE test implementation of the i_state_access interface
+/// \brief SFINAE test implementation of the i_interactive_state_access interface
 template <typename DERIVED>
 using is_an_i_interactive_state_access =
     std::integral_constant<bool, is_template_base_of_v<i_interactive_state_access, std::remove_cvref_t<DERIVED>>>;
diff --git a/src/i-prefer-shadow-state.h b/src/i-prefer-shadow-state.h
index a1d6b78d8..cadbf8df5 100644
--- a/src/i-prefer-shadow-state.h
+++ b/src/i-prefer-shadow-state.h
@@ -31,9 +31,9 @@
 namespace cartesi {
 
 /// \class i_prefer_shadow_state
-/// \brief Interface for multiplexed access to shadow state.
+/// \brief Interface for multiplexed access to shadow state registers.
 /// \tparam DERIVED Derived class implementing the interface. (An example of CRTP.)
-/// \detail This is for state access methods that do not need individualized access to machine registers
+/// \detail This is for state access methods that do not need individualized access to machine registers.
 template <typename DERIVED>
 class i_prefer_shadow_state { // CRTP
 
@@ -57,7 +57,7 @@ class i_prefer_shadow_state { // CRTP
     }
 };
 
-/// \brief SFINAE test implementation of the i_state_access interface
+/// \brief SFINAE test implementation of the i_prefer_state_access interface
 template <typename DERIVED>
 using is_an_i_prefer_shadow_state =
     std::integral_constant<bool, is_template_base_of_v<i_prefer_shadow_state, std::remove_cvref_t<DERIVED>>>;
diff --git a/src/i-prefer-shadow-uarch-state.h b/src/i-prefer-shadow-uarch-state.h
index 69faa875c..791996916 100644
--- a/src/i-prefer-shadow-uarch-state.h
+++ b/src/i-prefer-shadow-uarch-state.h
@@ -33,7 +33,7 @@ namespace cartesi {
 /// \class i_prefer_shadow_uarch_state
 /// \brief Interface for multiplexed access to shadow uarch state.
 /// \tparam DERIVED Derived class implementing the interface. (An example of CRTP.)
-/// \detail This is for state access methods that do not need individualized access to uarch registers
+/// \detail This is for state access methods that do not need individualized access to uarch registers.
 template <typename DERIVED>
 class i_prefer_shadow_uarch_state { // CRTP
 
@@ -57,7 +57,7 @@ class i_prefer_shadow_uarch_state { // CRTP
     }
 };
 
-/// \brief SFINAE test implementation of the i_state_access interface
+/// \brief SFINAE test implementation of the i_prefer_shadow_uarch_state interface
 template <typename DERIVED>
 using is_an_i_prefer_shadow_uarch_state =
     std::integral_constant<bool, is_template_base_of_v<i_prefer_shadow_uarch_state, std::remove_cvref_t<DERIVED>>>;
diff --git a/src/i-state-access.h b/src/i-state-access.h
index d8d90f17f..579dccc4e 100644
--- a/src/i-state-access.h
+++ b/src/i-state-access.h
@@ -327,11 +327,12 @@ class i_state_access { // CRTP
 
     /// \brief Reads a word from memory.
     /// \tparam T Type of word to read, potentially unaligned.
-    /// \tparam A Type to which \p paddr and \p haddr are known to be aligned.
+    /// \tparam A Type to which \p paddr and \p faddr are known to be aligned.
     /// \param faddr Implementation-defined fast address.
+    /// \param pma_index Index of PMA where word falls.
     /// \param pval Pointer to word receiving value.
-    /// \warning T must not cross page boundary starting from \p faddr
-    /// \warning T may or may not cross a Merkle tree word boundary starting from \p faddr!
+    /// \warning T must not cross page boundary starting from \p faddr.
+    /// \warning T (when A is smaller) may or may not cross a Merkle tree word boundary starting from \p faddr!
     template <typename T, typename A = T>
     void read_memory_word(fast_addr faddr, uint64_t pma_index, T *pval) {
         static_assert(std::is_integral_v<T> && sizeof(T) <= sizeof(uint64_t), "unsupported type");
@@ -344,13 +345,11 @@ class i_state_access { // CRTP
 
     /// \brief Writes a word to memory.
     /// \tparam T Type of word to write.
-    /// \tparam A Type to which \p paddr and \p haddr are known to be aligned.
+    /// \tparam A Type to which \p paddr and \p faddr are known to be aligned.
     /// \param faddr Implementation-defined fast address.
     /// \param val Value to be written.
-    /// \details \p haddr is ONLY valid when there is a host machine.
-    /// It should never be referenced outside of this context.
-    /// \warning T must not cross page boundary starting from \p faddr
-    /// \warning T may or may not cross a Merkle tree word boundary starting from \p faddr!
+    /// \warning T must not cross page boundary starting from \p faddr.
+    /// \warning T (when A is smaller) may or may not cross a Merkle tree word boundary starting from \p faddr!
     template <typename T, typename A = T>
     void write_memory_word(fast_addr faddr, uint64_t pma_index, T val) {
         static_assert(std::is_integral_v<T> && sizeof(T) <= sizeof(uint64_t), "unsupported type");
diff --git a/src/interpret.cpp b/src/interpret.cpp
index f8c0b44d9..4079967a3 100644
--- a/src/interpret.cpp
+++ b/src/interpret.cpp
@@ -14,31 +14,6 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#include <algorithm>
-#include <array>
-#include <cstdint>
-#include <tuple>
-#include <type_traits>
-#include <utility>
-
-#ifdef MICROARCHITECTURE
-#include "machine-uarch-bridge-state-access.h"
-#include "uarch-runtime.h"
-#else
-#include "record-step-state-access.h"
-#include "replay-step-state-access.h"
-#include "state-access.h"
-#include <cassert>
-#endif // MICROARCHITECTURE
-
-#include "compiler-defines.h"
-#include "device-state-access.h"
-#include "dump.h"
-#include "i-counters.h"
-#include "i-interactive-state-access.h"
-#include "i-state-access.h"
-#include "tlb.h"
-
 /// \file
 /// \brief Interpreter implementation.
 /// \details \{
@@ -106,13 +81,37 @@
 ///   https://gcc.gnu.org/onlinedocs/gcc-7.3.0/gcc/Arrays-and-pointers-implementation.html#Arrays-and-pointers-implementation
 /// \}
 
-#include "find-pma-entry.h"
 #include "interpret.h"
+
+#include <algorithm>
+#include <array>
+#include <cstdint>
+#include <tuple>
+#include <type_traits>
+#include <utility>
+
+#ifdef MICROARCHITECTURE
+#include "machine-uarch-bridge-state-access.h"
+#include "uarch-runtime.h"
+#else
+#include "record-step-state-access.h"
+#include "replay-step-state-access.h"
+#include "state-access.h"
+#include <cassert>
+#endif // MICROARCHITECTURE
+
+#include "compiler-defines.h"
+#include "device-state-access.h"
+#include "dump.h"
+#include "find-pma-entry.h"
+#include "i-accept-counters.h"
+#include "i-interactive-state-access.h"
+#include "i-state-access.h"
 #include "meta.h"
 #include "riscv-constants.h"
 #include "rtc.h"
 #include "soft-float.h"
-#include "strict-aliasing.h"
+#include "tlb.h"
 #include "translate-virtual-address.h"
 #include "uint128.h"
 
@@ -900,7 +899,7 @@ static void flush_tlb_slot(STATE_ACCESS a, uint64_t slot_index) {
 /// \param a Machine state accessor object.
 template <TLB_set_index SET, typename STATE_ACCESS>
 static void flush_tlb_set(STATE_ACCESS a) {
-    for (uint64_t slot_index = 0; slot_index < PMA_TLB_SIZE; ++slot_index) {
+    for (uint64_t slot_index = 0; slot_index < TLB_SET_SIZE; ++slot_index) {
         flush_tlb_slot<SET>(a, slot_index);
     }
 }
@@ -6055,7 +6054,7 @@ template <typename STATE_ACCESS>
 interpreter_break_reason interpret(STATE_ACCESS a, uint64_t mcycle_end) {
     static_assert(__BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__, "code assumes little-endian byte ordering");
     static_assert(is_an_i_state_access_v<STATE_ACCESS>, "not an i_state_access");
-    static_assert(is_an_i_accept_scoped_note_v<STATE_ACCESS>, "not an i_accept_scoped_note");
+    static_assert(is_an_i_accept_scoped_note_v<STATE_ACCESS>, "not an i_accept_scoped_notes");
 
     const uint64_t mcycle = a.read_mcycle();
 
diff --git a/src/json-util.cpp b/src/json-util.cpp
index a80e85e07..3df07f1ff 100644
--- a/src/json-util.cpp
+++ b/src/json-util.cpp
@@ -14,6 +14,8 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
+#include "json-util.h"
+
 #include <algorithm>
 #include <climits>
 #include <cstddef>
@@ -28,12 +30,13 @@
 #include <variant>
 #include <vector>
 
+#include <json.hpp>
+
 #include "access-log.h"
 #include "base64.h"
 #include "bracket-note.h"
 #include "interpret.h"
-#include "json-util.h"
-#include "json.hpp"
+#include "jsonrpc-fork-result.h"
 #include "machine-config.h"
 #include "machine-memory-range-descr.h"
 #include "machine-merkle-tree.h"
diff --git a/src/jsonrpc-machine-c-api.cpp b/src/jsonrpc-machine-c-api.cpp
index a50429ba1..db79afdec 100644
--- a/src/jsonrpc-machine-c-api.cpp
+++ b/src/jsonrpc-machine-c-api.cpp
@@ -14,30 +14,23 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
+#include "jsonrpc-machine-c-api.h"
+
 #include <cassert>
 #include <csignal>
 #include <cstdint>
 #include <cstdio>
 #include <cstdlib>
 #include <cstring>
-#include <exception>
-#include <memory>
 #include <stdexcept>
 #include <string>
 
-#include "access-log.h"
 #include "i-virtual-machine.h"
 #include "json-util.h"
-#include "jsonrpc-machine-c-api.h"
+#include "jsonrpc-fork-result.h"
 #include "jsonrpc-virtual-machine.h"
 #include "machine-c-api-internal.h"
 #include "machine-c-api.h"
-#include "machine-config.h"
-#include "machine-runtime-config.h"
-#include "machine.h"
-#include "os-features.h"
-#include "os.h"
-#include "semantic-version.h"
 
 using namespace std::string_literals;
 
diff --git a/src/jsonrpc-remote-machine.cpp b/src/jsonrpc-remote-machine.cpp
index b1d7c30ec..f5f964678 100644
--- a/src/jsonrpc-remote-machine.cpp
+++ b/src/jsonrpc-remote-machine.cpp
@@ -46,10 +46,9 @@
 #include <utility>
 #include <vector>
 
-#include <fcntl.h>
+#include <netinet/in.h>
 #include <sys/socket.h>
 #include <sys/types.h>
-#include <sys/wait.h>
 #include <unistd.h>
 
 #pragma GCC diagnostic push
@@ -68,6 +67,7 @@
 #include "interpret.h"
 #include "json-util.h"
 #include "jsonrpc-discover.h"
+#include "jsonrpc-fork-result.h"
 #include "jsonrpc-version.h"
 #include "machine-config.h"
 #include "machine-merkle-tree.h"
diff --git a/src/jsonrpc-virtual-machine.cpp b/src/jsonrpc-virtual-machine.cpp
index dbb253e65..7bc907ef6 100644
--- a/src/jsonrpc-virtual-machine.cpp
+++ b/src/jsonrpc-virtual-machine.cpp
@@ -16,14 +16,16 @@
 
 #include "jsonrpc-virtual-machine.h"
 
+#include <cassert>
 #include <cerrno>
 #include <chrono>
 #include <csignal>
 #include <cstddef>
 #include <cstdint>
+#include <cstdlib>
 #include <cstring>
 #include <exception>
-#include <iostream>
+#include <memory>
 #include <sstream>
 #include <stdexcept>
 #include <string>
@@ -31,8 +33,6 @@
 #include <tuple>
 #include <utility>
 
-#include "os-features.h"
-
 #ifdef HAVE_FORK
 #include <spawn.h>
 #include <sys/wait.h>
@@ -57,16 +57,20 @@
 #include <boost/beast/version.hpp>
 #pragma GCC diagnostic pop
 
+#include <json.hpp>
+
 #include "access-log.h"
 #include "base64.h"
+#include "i-virtual-machine.h"
 #include "interpret.h"
 #include "json-util.h"
-#include "json.hpp"
+#include "jsonrpc-fork-result.h"
 #include "jsonrpc-version.h"
 #include "machine-config.h"
 #include "machine-memory-range-descr.h"
 #include "machine-merkle-tree.h"
 #include "machine-runtime-config.h"
+#include "os-features.h"
 #include "os.h"
 #include "scope-exit.h"
 #include "semantic-version.h"
diff --git a/src/machine-c-api.cpp b/src/machine-c-api.cpp
index 920133f2a..b1cc751c2 100644
--- a/src/machine-c-api.cpp
+++ b/src/machine-c-api.cpp
@@ -34,11 +34,13 @@
 #include "access-log.h"
 #include "htif.h"
 #include "i-virtual-machine.h"
+#include "interpret.h"
 #include "json-util.h"
 #include "machine-c-api-internal.h"
 #include "machine-config.h"
 #include "machine-memory-range-descr.h"
 #include "machine-merkle-tree.h"
+#include "machine-reg.h"
 #include "machine-runtime-config.h"
 #include "machine.h"
 #include "os-features.h"
diff --git a/src/machine-config.cpp b/src/machine-config.cpp
index 9f8961727..df6d4e931 100644
--- a/src/machine-config.cpp
+++ b/src/machine-config.cpp
@@ -27,8 +27,9 @@
 #include <string>
 #include <system_error>
 
+#include <json.hpp>
+
 #include "json-util.h"
-#include "json.hpp"
 #include "pma-constants.h"
 
 static constexpr uint32_t archive_version = 5;
diff --git a/src/machine-merkle-tree.cpp b/src/machine-merkle-tree.cpp
index a0c23bc57..28e0740d6 100644
--- a/src/machine-merkle-tree.cpp
+++ b/src/machine-merkle-tree.cpp
@@ -15,8 +15,6 @@
 //
 
 #include "machine-merkle-tree.h"
-#include "i-hasher.h"
-#include "pristine-merkle-tree.h"
 
 #include <algorithm>
 #include <cassert>
@@ -26,6 +24,9 @@
 #include <iostream>
 #include <tuple>
 
+#include "i-hasher.h"
+#include "pristine-merkle-tree.h"
+
 /// \file
 /// \brief Merkle tree implementation.
 
diff --git a/src/machine.cpp b/src/machine.cpp
index 9f59ba01a..a57c0e0d2 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -17,14 +17,15 @@
 #include "machine.h"
 
 #include <algorithm>
+#include <array>
 #include <cerrno>
-#include <cinttypes>
 #include <cstdint>
 #include <cstdio>
 #include <cstring>
 #include <iomanip>
 #include <iostream>
 #include <memory>
+#include <sstream>
 #include <stdexcept>
 #include <string>
 #include <system_error>
@@ -35,16 +36,20 @@
 #include <boost/container/static_vector.hpp>
 
 #include "access-log.h"
-#include "bracket-note.h"
 #include "clint-factory.h"
+#include "compiler-defines.h"
 #include "device-state-access.h"
 #include "dtb.h"
+#include "host-addr.h"
 #include "htif-factory.h"
 #include "htif.h"
+#include "i-device-state-access.h"
+#include "i-hasher.h"
 #include "interpret.h"
 #include "is-pristine.h"
 #include "machine-config.h"
 #include "machine-memory-range-descr.h"
+#include "machine-reg.h"
 #include "machine-runtime-config.h"
 #include "os.h"
 #include "plic-factory.h"
@@ -59,6 +64,7 @@
 #include "rtc.h"
 #include "send-cmio-response.h"
 #include "shadow-pmas-factory.h"
+#include "shadow-pmas.h"
 #include "shadow-state-factory.h"
 #include "shadow-state.h"
 #include "shadow-tlb-factory.h"
@@ -1792,7 +1798,7 @@ uint64_t machine::get_reg_address(reg r) {
 void machine::mark_write_tlb_dirty_pages() const {
     auto &hot_set = m_s.tlb.hot[TLB_WRITE];
     auto &cold_set = m_s.tlb.cold[TLB_WRITE];
-    for (uint64_t slot_index = 0; slot_index < PMA_TLB_SIZE; ++slot_index) {
+    for (uint64_t slot_index = 0; slot_index < TLB_SET_SIZE; ++slot_index) {
         const auto &hot_slot = hot_set[slot_index];
         if (hot_slot.vaddr_page != TLB_INVALID_PAGE) {
             auto haddr_page = hot_slot.vaddr_page + hot_slot.vh_offset;
@@ -2279,9 +2285,6 @@ void machine::write_word(uint64_t paddr, uint64_t val) {
         if (reg == shadow_state_what::unknown_) {
             throw std::runtime_error("unhandled write to shadow state");
         }
-        if (reg == shadow_state_what::x0) {
-            throw std::runtime_error("invalid shadow state write to x0");
-        }
         write_reg(machine_reg_enum(reg), val);
         return;
     }
@@ -2291,9 +2294,6 @@ void machine::write_word(uint64_t paddr, uint64_t val) {
         if (reg == shadow_uarch_state_what::unknown_) {
             throw std::runtime_error("unhandled write to shadow uarch state");
         }
-        if (reg == shadow_uarch_state_what::uarch_x0) {
-            throw std::runtime_error("invalid shadow state write to uarch.x0");
-        }
         write_reg(machine_reg_enum(reg), val);
         return;
     }
diff --git a/src/os.cpp b/src/os.cpp
index 5e9fe08a3..736ba928c 100644
--- a/src/os.cpp
+++ b/src/os.cpp
@@ -14,6 +14,9 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
+#include "os.h"
+#include "os-features.h"
+
 #include <array>
 #include <cerrno>
 #include <chrono>
@@ -28,11 +31,6 @@
 #include <tuple>
 #include <vector>
 
-#include "compiler-defines.h"
-#include "os-features.h"
-#include "os.h"
-#include "unique-c-ptr.h"
-
 #include <sys/time.h>
 
 #ifdef HAVE_SIGACTION
@@ -104,6 +102,9 @@
 
 #endif // _WIN32
 
+#include "compiler-defines.h"
+#include "unique-c-ptr.h"
+
 // Enable these defines to debug
 // #define DEBUG_OS
 
diff --git a/src/plic-factory.cpp b/src/plic-factory.cpp
index c68f7b6b1..01bb24686 100644
--- a/src/plic-factory.cpp
+++ b/src/plic-factory.cpp
@@ -14,9 +14,10 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
+#include "plic-factory.h"
+
 #include <cstdint>
 
-#include "plic-factory.h"
 #include "plic.h"
 #include "pma-constants.h"
 #include "pma.h"
diff --git a/src/pma-constants.h b/src/pma-constants.h
index 6e105ccdd..4dd234df5 100644
--- a/src/pma-constants.h
+++ b/src/pma-constants.h
@@ -73,11 +73,6 @@ enum PMA_constants : uint64_t {
     PMA_MAX = EXPAND_UINT64_C(PMA_MAX_DEF)                        ///< Maximum number of PMAs
 };
 
-/// \brief PMA TLB constants.
-enum PMA_tlb_constants : uint64_t {
-    PMA_TLB_SIZE = EXPAND_UINT64_C(PMA_TLB_SIZE_DEF), ///< Number for entries per TLB type
-};
-
 /// \brief PMA PLIC constants.
 enum PMA_plic_constants : uint64_t {
     PMA_PLIC_MAX_IRQ = EXPAND_UINT64_C(PMA_PLIC_MAX_IRQ_DEF), ///< Maximum PLIC interrupt
diff --git a/src/pma-defines.h b/src/pma-defines.h
index c54ca6ebc..8a69bdbdb 100644
--- a/src/pma-defines.h
+++ b/src/pma-defines.h
@@ -50,7 +50,6 @@
 #define PMA_PAGE_SIZE_LOG2_DEF 12 ///< log<sub>2</sub> of physical memory page size.
 #define PMA_WORD_SIZE_DEF 8       ///< Physical memory word size.
 #define PMA_MAX_DEF 32            ///< Maximum number of PMAs
-#define PMA_TLB_SIZE_DEF 256      ///< Number for entries per TLB type
 #define PMA_PLIC_MAX_IRQ_DEF 31   ///< Maximum PLIC interrupt
 
 #define PMA_MEMORY_DID_DEF 0              ///< Device ID for memory
diff --git a/src/pma.cpp b/src/pma.cpp
index 5edb43f46..5e39cdcb2 100644
--- a/src/pma.cpp
+++ b/src/pma.cpp
@@ -16,6 +16,7 @@
 
 #include "pma.h"
 
+#include <algorithm>
 #include <cerrno>
 #include <cstdint>
 #include <cstdio>
diff --git a/src/record-send-cmio-state-access.h b/src/record-send-cmio-state-access.h
index 093bc0abb..cb3d933fb 100644
--- a/src/record-send-cmio-state-access.h
+++ b/src/record-send-cmio-state-access.h
@@ -28,7 +28,7 @@
 
 #include "access-log.h"
 #include "host-addr.h"
-#include "i-accept-scoped-note.h"
+#include "i-accept-scoped-notes.h"
 #include "i-hasher.h"
 #include "i-state-access.h"
 #include "machine-merkle-tree.h"
@@ -58,7 +58,7 @@ struct i_state_access_fast_addr<record_send_cmio_state_access> {
 /// a machine::send_cmio_response() function call
 class record_send_cmio_state_access :
     public i_state_access<record_send_cmio_state_access>,
-    public i_accept_scoped_note<record_send_cmio_state_access> {
+    public i_accept_scoped_notes<record_send_cmio_state_access> {
     using hasher_type = machine_merkle_tree::hasher_type;
     using hash_type = machine_merkle_tree::hash_type;
     // NOLINTBEGIN(cppcoreguidelines-avoid-const-or-ref-data-members)
@@ -271,9 +271,9 @@ class record_send_cmio_state_access :
     }
 
     // -----
-    // i_accept_scoped_note interface implementation
+    // i_accept_scoped_notes interface implementation
     // -----
-    friend i_accept_scoped_note<record_send_cmio_state_access>;
+    friend i_accept_scoped_notes<record_send_cmio_state_access>;
 
     void do_push_begin_bracket(const char *text) {
         m_log.push_begin_bracket(text);
diff --git a/src/record-step-state-access.h b/src/record-step-state-access.h
index 0b7b33a3a..91c400a88 100644
--- a/src/record-step-state-access.h
+++ b/src/record-step-state-access.h
@@ -22,7 +22,7 @@
 #include <vector>
 
 #include "compiler-defines.h"
-#include "i-accept-scoped-note.h"
+#include "i-accept-scoped-notes.h"
 #include "i-prefer-shadow-state.h"
 #include "i-state-access.h"
 #include "machine.h"
@@ -49,7 +49,7 @@ struct i_state_access_fast_addr<record_step_state_access> {
 /// \brief Records machine state access into a step log file
 class record_step_state_access :
     public i_state_access<record_step_state_access>,
-    public i_accept_scoped_note<record_step_state_access>,
+    public i_accept_scoped_notes<record_step_state_access>,
     public i_prefer_shadow_state<record_step_state_access> {
     constexpr static int TREE_LOG2_ROOT_SIZE = machine_merkle_tree::get_log2_root_size();
     constexpr static int TREE_LOG2_PAGE_SIZE = machine_merkle_tree::get_log2_page_size();
diff --git a/src/replay-step-state-access-interop.cpp b/src/replay-step-state-access-interop.cpp
index bcd300b3d..5485c841e 100644
--- a/src/replay-step-state-access-interop.cpp
+++ b/src/replay-step-state-access-interop.cpp
@@ -15,6 +15,11 @@
 //
 
 #include "replay-step-state-access-interop.h"
+
+#include <cstddef>
+#include <type_traits>
+
+#include "i-hasher.h"
 #include "machine-merkle-tree.h"
 
 using namespace cartesi;
diff --git a/src/replay-step-state-access.h b/src/replay-step-state-access.h
index d86714766..38d0f1469 100644
--- a/src/replay-step-state-access.h
+++ b/src/replay-step-state-access.h
@@ -22,7 +22,7 @@
 
 #include "compiler-defines.h"
 #include "host-addr.h"
-#include "i-accept-scoped-note.h"
+#include "i-accept-scoped-notes.h"
 #include "i-prefer-shadow-state.h"
 #include "i-state-access.h"
 #include "mock-pma-entry.h"
@@ -77,7 +77,7 @@ static inline bool validate_and_advance_offset(uint64_t max, uint64_t current, u
 // \brief Provides machine state from a step log file
 class replay_step_state_access :
     public i_state_access<replay_step_state_access>,
-    public i_accept_scoped_note<replay_step_state_access>,
+    public i_accept_scoped_notes<replay_step_state_access>,
     public i_prefer_shadow_state<replay_step_state_access> {
 public:
     using address_type = uint64_t;
diff --git a/src/send-cmio-response.cpp b/src/send-cmio-response.cpp
index fb4003682..4e41cd401 100644
--- a/src/send-cmio-response.cpp
+++ b/src/send-cmio-response.cpp
@@ -19,14 +19,13 @@
 
 // NOLINTBEGIN(google-readability-casting,misc-const-correctness,modernize-use-auto,hicpp-use-auto,readability-use-std-min-max)
 
-#include "record-send-cmio-state-access.h"
-#include "replay-send-cmio-state-access.h"
-#include "state-access.h"
-
 #include "send-cmio-response.h"
 
 #include "machine-merkle-tree.h"
 #include "pma-constants.h"
+#include "record-send-cmio-state-access.h"
+#include "replay-send-cmio-state-access.h"
+#include "state-access.h"
 #include "uarch-solidity-compat.h"
 
 namespace cartesi {
diff --git a/src/shadow-pmas-factory.cpp b/src/shadow-pmas-factory.cpp
index a3e9415e9..251660213 100644
--- a/src/shadow-pmas-factory.cpp
+++ b/src/shadow-pmas-factory.cpp
@@ -17,12 +17,9 @@
 #include "shadow-pmas-factory.h"
 
 #include <cstdint>
-#include <cstring>
 
-#include "machine.h"
 #include "pma-constants.h"
 #include "pma.h"
-#include "shadow-pmas.h"
 
 namespace cartesi {
 
diff --git a/src/shadow-state-factory.cpp b/src/shadow-state-factory.cpp
index e87c975f1..959e745e3 100644
--- a/src/shadow-state-factory.cpp
+++ b/src/shadow-state-factory.cpp
@@ -14,13 +14,15 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
+#include "shadow-state-factory.h"
+
 #include <cstdint>
 
+#include "machine-reg.h"
 #include "machine.h"
 #include "pma-constants.h"
 #include "pma.h"
 #include "shadow-peek.h"
-#include "shadow-state-factory.h"
 #include "shadow-state.h"
 
 namespace cartesi {
diff --git a/src/shadow-state.cpp b/src/shadow-state.cpp
index 74652288d..6cc463e29 100644
--- a/src/shadow-state.cpp
+++ b/src/shadow-state.cpp
@@ -15,6 +15,7 @@
 //
 
 #include "shadow-state.h"
+
 #include "pma-driver.h"
 
 namespace cartesi {
diff --git a/src/shadow-tlb-factory.cpp b/src/shadow-tlb-factory.cpp
index 915cfb99d..e3cefa319 100644
--- a/src/shadow-tlb-factory.cpp
+++ b/src/shadow-tlb-factory.cpp
@@ -14,14 +14,16 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
+#include "shadow-tlb-factory.h"
+
 #include <cstdint>
 
 #include "machine.h"
 #include "pma-constants.h"
 #include "pma.h"
 #include "shadow-peek.h"
-#include "shadow-tlb-factory.h"
 #include "shadow-tlb.h"
+#include "tlb.h"
 
 namespace cartesi {
 
diff --git a/src/shadow-tlb.h b/src/shadow-tlb.h
index 4666ecfd7..508682e63 100644
--- a/src/shadow-tlb.h
+++ b/src/shadow-tlb.h
@@ -32,13 +32,19 @@
 namespace cartesi {
 
 /// \brief Shadow TLB slot
-// Writes to TLB slots have to be atomic.
-// We can only do /aligned/ atomic writes.
-// Therefore, TLB slot cannot be misaligned.
+/// \details
+/// Given a target virtual address vaddr within a page matching vaddr_page in TLB slot, the corresponding
+/// target physical address paddr = vaddr + vp_offset.
+/// The pma_index helps translate between target physical addresses and host addresses when needed.
+/// Writes to TLB slots have to be atomic.
+/// We can only do /aligned/ atomic writes.
+/// Therefore, TLB slot cannot be misaligned.
+/// To complete the power-of-two size, we include a zero_padding_ entry.
 struct PACKED shadow_tlb_slot {
-    uint64_t vaddr_page;    ///< Tag is target virtual address of start of page
-    uint64_t vp_offset;     ///< Value is offset from target virtual address to target physical address within page
+    uint64_t vaddr_page;    ///< Target virtual address of start of page
+    uint64_t vp_offset;     ///< Offset from target virtual address to target physical address within page
     uint64_t pma_index;     ///< Index of PMA where physical page falls
+                            /// and host addresses
     uint64_t zero_padding_; ///< Padding to make sure the sizeof(shadow_tlb_slot) is a power of 2
 };
 
diff --git a/src/shadow-uarch-state-factory.cpp b/src/shadow-uarch-state-factory.cpp
index de98f4a6f..bc5284c13 100644
--- a/src/shadow-uarch-state-factory.cpp
+++ b/src/shadow-uarch-state-factory.cpp
@@ -14,13 +14,15 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
+#include "shadow-uarch-state-factory.h"
+
 #include <cstdint>
 
+#include "machine-reg.h"
 #include "machine.h"
 #include "pma-constants.h"
 #include "pma.h"
 #include "shadow-peek.h"
-#include "shadow-uarch-state-factory.h"
 #include "shadow-uarch-state.h"
 
 namespace cartesi {
diff --git a/src/shadow-uarch-state.cpp b/src/shadow-uarch-state.cpp
index 9c91843d7..1cb3d25e3 100644
--- a/src/shadow-uarch-state.cpp
+++ b/src/shadow-uarch-state.cpp
@@ -15,6 +15,7 @@
 //
 
 #include "shadow-uarch-state.h"
+
 #include "pma-driver.h"
 
 namespace cartesi {
diff --git a/src/state-access.h b/src/state-access.h
index c0ef6ea68..8c8317640 100644
--- a/src/state-access.h
+++ b/src/state-access.h
@@ -28,8 +28,8 @@
 
 #include "compiler-defines.h"
 #include "host-addr.h"
-#include "i-accept-scoped-note.h"
-#include "i-counters.h"
+#include "i-accept-counters.h"
+#include "i-accept-scoped-notes.h"
 #include "i-interactive-state-access.h"
 #include "i-state-access.h"
 #include "interpret.h"
@@ -63,8 +63,8 @@ struct i_state_access_fast_addr<state_access> {
 class state_access :
     public i_state_access<state_access>,
     public i_interactive_state_access<state_access>,
-    public i_accept_scoped_note<state_access>,
-    public i_counters<state_access> {
+    public i_accept_scoped_notes<state_access>,
+    public i_accept_counters<state_access> {
 
     // NOLINTNEXTLINE(cppcoreguidelines-avoid-const-or-ref-data-members)
     machine &m_m; ///< Associated machine
@@ -522,9 +522,9 @@ class state_access :
     }
 
     // -----
-    // i_counters interface implementation
+    // i_accept_counters interface implementation
     // -----
-    friend i_counters<state_access>;
+    friend i_accept_counters<state_access>;
 
     void do_increment_counter(const char *name, const char *domain) {
         m_m.increment_counter(name, domain);
diff --git a/src/tlb.h b/src/tlb.h
index ab7336bcf..2baa96918 100644
--- a/src/tlb.h
+++ b/src/tlb.h
@@ -43,15 +43,19 @@ enum TLB_constants : uint64_t {
 };
 
 /// \brief TLB hot slot.
+/// \details
+/// Given a target virtual address vaddr within a page matching vaddr_page in TLB slot, the corresponding host address
+/// haddr = vaddr + vh_offset.
 struct tlb_hot_slot final {
-    uint64_t vaddr_page; ///< Tag is the target virtual address of page start
-    host_addr vh_offset; ///< Value is the offset from target virtual address in the same page to
-                         ///< translated host address (vh_offset = haddr - vaddr)
+    uint64_t vaddr_page; ///< Target virtual address of start of page
+    host_addr vh_offset; ///< Offset from target virtual address in the same page to host address
 };
 
 using tlb_hot_set = std::array<tlb_hot_slot, TLB_SET_SIZE>;
 
 /// \brief TLB cold slot.
+/// \details
+/// The pma_index helps translate between target physical addresses and host addresses when needed.
 struct tlb_cold_slot final {
     uint64_t pma_index; ///< Index of PMA where physical address falls
 };
diff --git a/src/uarch-record-state-access.h b/src/uarch-record-state-access.h
index 19a763941..05aacf599 100644
--- a/src/uarch-record-state-access.h
+++ b/src/uarch-record-state-access.h
@@ -28,7 +28,7 @@
 
 #include "access-log.h"
 #include "host-addr.h"
-#include "i-accept-scoped-note.h"
+#include "i-accept-scoped-notes.h"
 #include "i-hasher.h"
 #include "i-prefer-shadow-uarch-state.h"
 #include "i-uarch-state-access.h"
@@ -52,7 +52,7 @@ using namespace std::string_literals;
 /// \details The uarch_record_state_access logs all access to the machine state.
 class uarch_record_state_access :
     public i_uarch_state_access<uarch_record_state_access>,
-    public i_accept_scoped_note<uarch_record_state_access>,
+    public i_accept_scoped_notes<uarch_record_state_access>,
     public i_prefer_shadow_uarch_state<uarch_record_state_access> {
 
     using hasher_type = machine_merkle_tree::hasher_type;
@@ -291,9 +291,9 @@ class uarch_record_state_access :
     }
 
     // -----
-    // i_accept_scoped_note interface implementation
+    // i_accept_scoped_notes interface implementation
     // -----
-    friend i_accept_scoped_note<uarch_record_state_access>;
+    friend i_accept_scoped_notes<uarch_record_state_access>;
 
     void do_push_begin_bracket(const char *text) {
         m_log.push_begin_bracket(text);
diff --git a/src/uarch-replay-state-access.h b/src/uarch-replay-state-access.h
index 6881000be..8c266830e 100644
--- a/src/uarch-replay-state-access.h
+++ b/src/uarch-replay-state-access.h
@@ -29,7 +29,7 @@
 #include <vector>
 
 #include "access-log.h"
-#include "i-accept-scoped-note.h"
+#include "i-accept-scoped-notes.h"
 #include "i-hasher.h"
 #include "i-prefer-shadow-uarch-state.h"
 #include "i-uarch-state-access.h"
@@ -44,7 +44,7 @@ namespace cartesi {
 
 class uarch_replay_state_access :
     public i_uarch_state_access<uarch_replay_state_access>,
-    public i_accept_scoped_note<uarch_replay_state_access>,
+    public i_accept_scoped_notes<uarch_replay_state_access>,
     public i_prefer_shadow_uarch_state<uarch_replay_state_access> {
     using tree_type = machine_merkle_tree;
     using hash_type = tree_type::hash_type;
@@ -368,9 +368,9 @@ class uarch_replay_state_access :
     friend i_prefer_shadow_uarch_state<uarch_replay_state_access>;
 
     // -----
-    // i_accept_scoped_note interface implementation
+    // i_accept_scoped_notes interface implementation
     // -----
-    friend i_accept_scoped_note<uarch_replay_state_access>;
+    friend i_accept_scoped_notes<uarch_replay_state_access>;
 };
 
 } // namespace cartesi
diff --git a/src/uarch-reset-state.cpp b/src/uarch-reset-state.cpp
index 7302c6c29..8c08dac16 100644
--- a/src/uarch-reset-state.cpp
+++ b/src/uarch-reset-state.cpp
@@ -20,6 +20,7 @@
 // NOLINTBEGIN(google-readability-casting,misc-const-correctness,modernize-use-auto,hicpp-use-auto)
 
 #include "uarch-reset-state.h"
+
 #include "uarch-record-state-access.h"
 #include "uarch-replay-state-access.h"
 #include "uarch-solidity-compat.h"
diff --git a/src/uarch-state-access.h b/src/uarch-state-access.h
index cf342d587..806151272 100644
--- a/src/uarch-state-access.h
+++ b/src/uarch-state-access.h
@@ -22,7 +22,7 @@
 #include <stdexcept>
 
 #include "host-addr.h"
-#include "i-accept-scoped-note.h"
+#include "i-accept-scoped-notes.h"
 #include "i-uarch-state-access.h"
 #include "machine.h"
 #include "os.h"
@@ -34,7 +34,7 @@ namespace cartesi {
 
 class uarch_state_access :
     public i_uarch_state_access<uarch_state_access>,
-    public i_accept_scoped_note<uarch_state_access> {
+    public i_accept_scoped_notes<uarch_state_access> {
     // NOLINTBEGIN(cppcoreguidelines-avoid-const-or-ref-data-members)
     machine &m_m;
     // NOLINTEND(cppcoreguidelines-avoid-const-or-ref-data-members)
@@ -159,9 +159,9 @@ class uarch_state_access :
     }
 
     // -----
-    // i_accept_scoped_note interface implementation
+    // i_accept_scoped_notes interface implementation
     // -----
-    friend i_accept_scoped_note<uarch_state_access>;
+    friend i_accept_scoped_notes<uarch_state_access>;
 };
 
 } // namespace cartesi
diff --git a/src/virtio-device.cpp b/src/virtio-device.cpp
index 6d226cb0f..d3a5d90ca 100644
--- a/src/virtio-device.cpp
+++ b/src/virtio-device.cpp
@@ -20,6 +20,11 @@
 // #define DEBUG_VIRTIO_ERRORS
 
 #include "virtio-device.h"
+
+#include <algorithm>
+#include <cassert>
+#include <cstdint>
+
 #include "i-device-state-access.h"
 #include "interpret.h"
 #include "os.h"
@@ -27,10 +32,6 @@
 #include "pma-driver.h"
 #include "strict-aliasing.h"
 
-#include <algorithm>
-#include <cassert>
-#include <cstdint>
-
 namespace cartesi {
 
 static inline bool is_power_of_2(uint32_t val) {
diff --git a/src/virtio-net-carrier-slirp.cpp b/src/virtio-net-carrier-slirp.cpp
index 39a72986f..4c51b1849 100644
--- a/src/virtio-net-carrier-slirp.cpp
+++ b/src/virtio-net-carrier-slirp.cpp
@@ -60,13 +60,16 @@
 #include <algorithm>
 #include <cerrno>
 #include <chrono>
+#include <cstddef>
 #include <cstdint>
 #include <cstring>
 #include <stdexcept>
 #include <string>
 #include <system_error>
 
+#include <arpa/inet.h>
 #include <slirp/libslirp.h>
+#include <sys/select.h>
 
 #include "i-device-state-access.h"
 #include "machine-config.h"
@@ -78,6 +81,7 @@ using namespace std::string_literals;
 
 namespace cartesi {
 
+//??D why ssize_t?
 static ssize_t slirp_send_packet(const void *buf, size_t len, void *opaque) {
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
     auto *carrier = reinterpret_cast<virtio_net_carrier_slirp *>(opaque);
diff --git a/src/virtio-net-carrier-tuntap.cpp b/src/virtio-net-carrier-tuntap.cpp
index ad057f943..4da7a3188 100644
--- a/src/virtio-net-carrier-tuntap.cpp
+++ b/src/virtio-net-carrier-tuntap.cpp
@@ -56,6 +56,7 @@
 
 #ifdef HAVE_TUNTAP
 
+#include <algorithm>
 #include <array>
 #include <cerrno>
 #include <cstdint>
diff --git a/src/virtual-machine.cpp b/src/virtual-machine.cpp
index 3fad1ec4f..0c4d4f3c3 100644
--- a/src/virtual-machine.cpp
+++ b/src/virtual-machine.cpp
@@ -20,6 +20,7 @@
 #include <string>
 
 #include "access-log.h"
+#include "i-virtual-machine.h"
 #include "interpret.h"
 #include "machine-config.h"
 #include "machine-memory-range-descr.h"
diff --git a/tests/misc/test-merkle-tree-hash.cpp b/tests/misc/test-merkle-tree-hash.cpp
index dab8986e4..0d3c93650 100644
--- a/tests/misc/test-merkle-tree-hash.cpp
+++ b/tests/misc/test-merkle-tree-hash.cpp
@@ -14,7 +14,6 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#include <array>
 #include <cassert>
 #include <cstdarg>
 #include <cstdint>
@@ -24,6 +23,7 @@
 #include <exception>
 #include <iostream>
 #include <new>
+#include <tuple>
 #include <vector>
 
 #include <back-merkle-tree.h>
diff --git a/uarch/machine-uarch-bridge-state-access.h b/uarch/machine-uarch-bridge-state-access.h
index e8eea56c5..dbda86744 100644
--- a/uarch/machine-uarch-bridge-state-access.h
+++ b/uarch/machine-uarch-bridge-state-access.h
@@ -22,7 +22,7 @@
 #include <optional>
 
 #include "compiler-defines.h"
-#include "i-accept-scoped-note.h"
+#include "i-accept-scoped-notes.h"
 #include "i-prefer-shadow-state.h"
 #include "i-state-access.h"
 #include "machine-reg.h"
@@ -53,7 +53,7 @@ struct i_state_access_fast_addr<machine_uarch_bridge_state_access> {
 // Provides access to the state of the big emulator from microcode
 class machine_uarch_bridge_state_access :
     public i_state_access<machine_uarch_bridge_state_access>,
-    public i_accept_scoped_note<machine_uarch_bridge_state_access>,
+    public i_accept_scoped_notes<machine_uarch_bridge_state_access>,
     public i_prefer_shadow_state<machine_uarch_bridge_state_access> {
 
     // NOLINTNEXTLINE(cppcoreguidelines-avoid-const-or-ref-data-members)

From 32c7f0dda68f7c538a6089a67746fd248f8f23ed Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Wed, 12 Feb 2025 16:01:42 +0000
Subject: [PATCH 17/82] refactor: make all state access objects const

---
 src/i-accept-counters.h                   |   6 +-
 src/i-accept-scoped-notes.h               |  12 +-
 src/i-interactive-state-access.h          |   6 +-
 src/i-prefer-shadow-state.h               |   4 +-
 src/i-prefer-shadow-uarch-state.h         |   4 +-
 src/i-state-access.h                      |  40 +-
 src/i-uarch-state-access.h                |  24 +-
 src/interpret.cpp                         | 724 +++++++++++-----------
 src/is-pristine.h                         |   4 +-
 src/machine.cpp                           |  12 +-
 src/record-send-cmio-state-access.h       |  20 +-
 src/record-step-state-access.h            |  28 +-
 src/replay-send-cmio-state-access.h       |  14 +-
 src/replay-step-state-access.h            |  38 +-
 src/state-access.h                        | 110 ++--
 src/uarch-interpret.cpp                   |   4 +-
 src/uarch-interpret.h                     |   2 +-
 src/uarch-record-state-access.h           |  24 +-
 src/uarch-replay-state-access.h           | 125 ++--
 src/uarch-solidity-compat.h               |  30 +-
 src/uarch-state-access.h                  |  31 +-
 src/uarch-step.cpp                        | 134 ++--
 src/uarch-step.h                          |   2 +-
 uarch/machine-uarch-bridge-state-access.h |  36 +-
 24 files changed, 722 insertions(+), 712 deletions(-)

diff --git a/src/i-accept-counters.h b/src/i-accept-counters.h
index 70e6e81c2..1b944d352 100644
--- a/src/i-accept-counters.h
+++ b/src/i-accept-counters.h
@@ -44,15 +44,15 @@ class i_accept_counters { // CRTP
     }
 
 public:
-    void increment_counter(const char *name, const char *domain = nullptr) {
+    void increment_counter(const char *name, const char *domain = nullptr) const {
         derived().do_increment_counter(name, domain);
     }
 
-    uint64_t read_counter(const char *name, const char *domain = nullptr) {
+    uint64_t read_counter(const char *name, const char *domain = nullptr) const {
         return derived().do_read_counter(name, domain);
     }
 
-    void write_counter(uint64_t val, const char *name, const char *domain = nullptr) {
+    void write_counter(uint64_t val, const char *name, const char *domain = nullptr) const {
         derived().do_write_counter(val, name, domain);
     }
 };
diff --git a/src/i-accept-scoped-notes.h b/src/i-accept-scoped-notes.h
index 9a1e78d9f..affc19c3e 100644
--- a/src/i-accept-scoped-notes.h
+++ b/src/i-accept-scoped-notes.h
@@ -64,14 +64,14 @@ class i_accept_scoped_notes { // CRTP
 
     /// \brief Adds a begin bracket annotation to the log
     /// \param text String with the text for the annotation
-    void push_begin_bracket(const char *text) {
+    void push_begin_bracket(const char *text) const {
         derived().do_push_begin_bracket(text);
         DSN_PRINTF("----> begin %s (%s)\n", text, derived().get_name());
     }
 
     /// \brief Adds an end bracket annotation to the log
     /// \param text String with the text for the annotation
-    void push_end_bracket(const char *text) {
+    void push_end_bracket(const char *text) const {
         derived().do_push_end_bracket(text);
         DSN_PRINTF("<---- end %s (%s)\n", text, derived().get_name());
     }
@@ -79,14 +79,14 @@ class i_accept_scoped_notes { // CRTP
     /// \brief Adds annotations to the state, bracketing a scope
     /// \param text String with the text for the annotation
     /// \returns An object that, when constructed and destroyed issues an annonation.
-    auto make_scoped_note(const char *text) {
+    auto make_scoped_note(const char *text) const {
         return derived().do_make_scoped_note(text);
     }
 
 protected:
     // Default implementation for classes that do not use scoped notes
     // (It still will dump the scoped notes when requested)
-    auto do_make_scoped_note([[maybe_unused]] const char *text) {
+    auto do_make_scoped_note([[maybe_unused]] const char *text) const {
 #ifdef DUMP_SCOPED_NOTE
         return scoped_note{*this, text};
 #else
@@ -94,11 +94,11 @@ class i_accept_scoped_notes { // CRTP
 #endif
     }
 
-    void do_push_begin_bracket(const char * /*text*/) {
+    void do_push_begin_bracket(const char * /*text*/) const {
         ;
     }
 
-    void do_push_end_bracket(const char * /*text*/) {
+    void do_push_end_bracket(const char * /*text*/) const {
         ;
     }
 };
diff --git a/src/i-interactive-state-access.h b/src/i-interactive-state-access.h
index 91ec34870..33229bfe9 100644
--- a/src/i-interactive-state-access.h
+++ b/src/i-interactive-state-access.h
@@ -47,18 +47,18 @@ class i_interactive_state_access { // CRTP
     /// \brief Wait for external interrupts requests.
     /// \param mcycle Current value of mcycle.
     /// \param mcycle_max Maximum mcycle after wait.
-    auto poll_external_interrupts(uint64_t mcycle, uint64_t mcycle_max) {
+    auto poll_external_interrupts(uint64_t mcycle, uint64_t mcycle_max) const {
         return derived().do_poll_external_interrupts(mcycle, mcycle_max);
     }
 
     /// \brief Returns true if soft yield HINT instruction is enabled at runtime
-    bool get_soft_yield() {
+    bool get_soft_yield() const {
         return derived().do_get_soft_yield();
     }
 
     /// \brief Reads a character from the console
     /// \returns Character read if any, -1 otherwise
-    int getchar() {
+    int getchar() const {
         return derived().do_getchar();
     }
 };
diff --git a/src/i-prefer-shadow-state.h b/src/i-prefer-shadow-state.h
index cadbf8df5..4d4f83213 100644
--- a/src/i-prefer-shadow-state.h
+++ b/src/i-prefer-shadow-state.h
@@ -48,11 +48,11 @@ class i_prefer_shadow_state { // CRTP
     }
 
 public:
-    uint64_t read_shadow_state(shadow_state_what what) {
+    uint64_t read_shadow_state(shadow_state_what what) const {
         return derived().do_read_shadow_state(what);
     }
 
-    void write_shadow_state(shadow_state_what what, uint64_t val) {
+    void write_shadow_state(shadow_state_what what, uint64_t val) const {
         derived().do_write_shadow_state(what, val);
     }
 };
diff --git a/src/i-prefer-shadow-uarch-state.h b/src/i-prefer-shadow-uarch-state.h
index 791996916..f540cff75 100644
--- a/src/i-prefer-shadow-uarch-state.h
+++ b/src/i-prefer-shadow-uarch-state.h
@@ -48,11 +48,11 @@ class i_prefer_shadow_uarch_state { // CRTP
     }
 
 public:
-    uint64_t read_shadow_uarch_state(shadow_uarch_state_what what) {
+    uint64_t read_shadow_uarch_state(shadow_uarch_state_what what) const {
         return derived().do_read_shadow_uarch_state(what);
     }
 
-    void write_shadow_uarch_state(shadow_uarch_state_what what, uint64_t val) {
+    void write_shadow_uarch_state(shadow_uarch_state_what what, uint64_t val) const {
         derived().do_write_shadow_uarch_state(what, val);
     }
 };
diff --git a/src/i-state-access.h b/src/i-state-access.h
index 579dccc4e..6e7be2874 100644
--- a/src/i-state-access.h
+++ b/src/i-state-access.h
@@ -50,7 +50,7 @@ using i_state_access_fast_addr_t = typename i_state_access_fast_addr<STATE_ACCES
 
 // NOLINTBEGIN(cppcoreguidelines-macro-usage)
 #define DEFINE_SA_READ(REG)                                                                                            \
-    uint64_t read_##REG() {                                                                                            \
+    uint64_t read_##REG() const {                                                                                      \
         if constexpr (!is_an_i_prefer_shadow_state_v<DERIVED>) {                                                       \
             const auto val = derived().do_read_##REG();                                                                \
             DSA_PRINTF("%s::read_" #REG "() = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), val, val);                    \
@@ -61,7 +61,7 @@ using i_state_access_fast_addr_t = typename i_state_access_fast_addr<STATE_ACCES
     }
 
 #define DEFINE_SA_WRITE(REG)                                                                                           \
-    void write_##REG(uint64_t val) {                                                                                   \
+    void write_##REG(uint64_t val) const {                                                                             \
         if constexpr (!is_an_i_prefer_shadow_state_v<DERIVED>) {                                                       \
             derived().do_write_##REG(val);                                                                             \
             DSA_PRINTF("%s::write_" #REG "(%" PRIu64 "(0x%" PRIx64 "))\n", get_name(), val, val);                      \
@@ -107,14 +107,14 @@ class i_state_access { // CRTP
         return *static_cast<const DERIVED *>(this);
     }
 
-    uint64_t prefer_read_shadow_state(shadow_state_what what) {
+    uint64_t prefer_read_shadow_state(shadow_state_what what) const {
         const auto val = derived().read_shadow_state(what);
         [[maybe_unused]] const auto *const what_name = shadow_state_get_what_name(what);
         DSA_PRINTF("%s::read_shadow_state(%s) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), what_name, val, val);
         return val;
     }
 
-    void prefer_write_shadow_state(shadow_state_what what, uint64_t val) {
+    void prefer_write_shadow_state(shadow_state_what what, uint64_t val) const {
         derived().write_shadow_state(what, val);
         [[maybe_unused]] const auto *const what_name = shadow_state_get_what_name(what);
         DSA_PRINTF("%s::write_shadow_state(%s, %" PRIu64 "(0x%" PRIx64 "))\n", get_name(), what_name, val, val);
@@ -135,7 +135,7 @@ class i_state_access { // CRTP
     /// \brief Reads from general-purpose register.
     /// \param i Register index.
     /// \returns Register value.
-    uint64_t read_x(int i) {
+    uint64_t read_x(int i) const {
         if constexpr (!is_an_i_prefer_shadow_state_v<DERIVED>) {
             const auto val = derived().do_read_x(i);
             DSA_PRINTF("%s::read_x(%d) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), i, val, val);
@@ -150,7 +150,7 @@ class i_state_access { // CRTP
     /// \param val New register value.
     /// \details Writes to register zero *break* the machine.
     /// There is an assertion to catch this, but NDEBUG will let the value pass through.
-    void write_x(int i, uint64_t val) {
+    void write_x(int i, uint64_t val) const {
         if constexpr (!is_an_i_prefer_shadow_state_v<DERIVED>) {
             derived().do_write_x(i, val);
             DSA_PRINTF("%s::write_x(%d, %" PRIu64 "(0x%" PRIx64 "))\n", get_name(), i, val, val);
@@ -162,7 +162,7 @@ class i_state_access { // CRTP
     /// \brief Reads from floating-point register.
     /// \param i Register index.
     /// \returns Register value.
-    uint64_t read_f(int i) {
+    uint64_t read_f(int i) const {
         if constexpr (!is_an_i_prefer_shadow_state_v<DERIVED>) {
             const auto val = derived().do_read_f(i);
             DSA_PRINTF("%s::read_f(%d) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), i, val, val);
@@ -175,7 +175,7 @@ class i_state_access { // CRTP
     /// \brief Writes register to floating-point register.
     /// \param i Register index.
     /// \param val New register value.
-    void write_f(int i, uint64_t val) {
+    void write_f(int i, uint64_t val) const {
         if constexpr (!is_an_i_prefer_shadow_state_v<DERIVED>) {
             derived().do_write_f(i, val);
             DSA_PRINTF("%s::write_f(%d, %" PRIu64 "(%" PRIx64 "))\n", get_name(), i, val, val);
@@ -274,7 +274,7 @@ class i_state_access { // CRTP
 
     /// \brief Reads PMA entry at a given index.
     /// \param index Index of PMA
-    pma_entry &read_pma_entry(uint64_t index) {
+    pma_entry &read_pma_entry(uint64_t index) const {
         auto &pma = derived().do_read_pma_entry(index);
         DSA_PRINTF("%s::read_pma_entry(%" PRIu64 ") = {%s, 0x%" PRIx64 ", 0x%" PRIx64 "}\n", get_name(), index,
             pma_get_DID_name(pma.get_istart_DID()), pma.get_start(), pma.get_length());
@@ -300,7 +300,7 @@ class i_state_access { // CRTP
     /// \returns True if PMA was found and memory fully read, false otherwise.
     /// \details The entire chunk of data must fit inside the same memory
     /// PMA range, otherwise it fails. The search for the PMA range is implicit, and not logged.
-    bool read_memory(uint64_t paddr, unsigned char *data, uint64_t length) {
+    bool read_memory(uint64_t paddr, unsigned char *data, uint64_t length) const {
         return derived().do_read_memory(paddr, data, length);
     }
 
@@ -311,7 +311,7 @@ class i_state_access { // CRTP
     /// \returns True if PMA was found and memory fully written, false otherwise.
     /// \details The entire chunk of data must fit inside the same memory
     /// PMA range, otherwise it fails. The search for the PMA range is implicit, and not logged.
-    bool write_memory(uint64_t paddr, const unsigned char *data, uint64_t length) {
+    bool write_memory(uint64_t paddr, const unsigned char *data, uint64_t length) const {
         return derived().do_write_memory(paddr, data, length);
     }
 
@@ -321,7 +321,7 @@ class i_state_access { // CRTP
     /// \param data_length Length of data buffer.
     /// \param write_length_log2_size Log2 size of the total write length.
     void write_memory_with_padding(uint64_t paddr, const unsigned char *data, uint64_t data_length,
-        int write_length_log2_size) {
+        int write_length_log2_size) const {
         derived().do_write_memory_with_padding(paddr, data, data_length, write_length_log2_size);
     }
 
@@ -334,7 +334,7 @@ class i_state_access { // CRTP
     /// \warning T must not cross page boundary starting from \p faddr.
     /// \warning T (when A is smaller) may or may not cross a Merkle tree word boundary starting from \p faddr!
     template <typename T, typename A = T>
-    void read_memory_word(fast_addr faddr, uint64_t pma_index, T *pval) {
+    void read_memory_word(fast_addr faddr, uint64_t pma_index, T *pval) const {
         static_assert(std::is_integral_v<T> && sizeof(T) <= sizeof(uint64_t), "unsupported type");
         derived().template do_read_memory_word<T, A>(faddr, pma_index, pval);
         [[maybe_unused]] const auto fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
@@ -351,7 +351,7 @@ class i_state_access { // CRTP
     /// \warning T must not cross page boundary starting from \p faddr.
     /// \warning T (when A is smaller) may or may not cross a Merkle tree word boundary starting from \p faddr!
     template <typename T, typename A = T>
-    void write_memory_word(fast_addr faddr, uint64_t pma_index, T val) {
+    void write_memory_word(fast_addr faddr, uint64_t pma_index, T val) const {
         static_assert(std::is_integral_v<T> && sizeof(T) <= sizeof(uint64_t), "unsupported type");
         derived().template do_write_memory_word<T, A>(faddr, pma_index, val);
         [[maybe_unused]] const auto fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
@@ -365,7 +365,7 @@ class i_state_access { // CRTP
     /// \param slot_index Slot index
     /// \returns Value in slot.
     template <TLB_set_index SET>
-    uint64_t read_tlb_vaddr_page(uint64_t slot_index) {
+    uint64_t read_tlb_vaddr_page(uint64_t slot_index) const {
         const auto val = derived().template do_read_tlb_vaddr_page<SET>(slot_index);
         DSA_PRINTF("%s::read_tlb_vaddr_page<%" PRIu64 ">(%" PRIu64 ") = 0x%" PRIx64 "\n", get_name(), SET, slot_index,
             val);
@@ -377,7 +377,7 @@ class i_state_access { // CRTP
     /// \param slot_index Slot index
     /// \returns Value in slot.
     template <TLB_set_index SET>
-    fast_addr read_tlb_vp_offset(uint64_t slot_index) {
+    fast_addr read_tlb_vp_offset(uint64_t slot_index) const {
         [[maybe_unused]] const auto fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
         const auto val = derived().template do_read_tlb_vp_offset<SET>(slot_index);
         DSA_PRINTF("%s::read_tlb_vp_offset<%" PRIu64 ">(%" PRIu64 ") = %s{0x%" PRIx64 "}\n", get_name(), SET,
@@ -390,7 +390,7 @@ class i_state_access { // CRTP
     /// \param slot_index Slot index
     /// \returns Value in slot.
     template <TLB_set_index SET>
-    uint64_t read_tlb_pma_index(uint64_t slot_index) {
+    uint64_t read_tlb_pma_index(uint64_t slot_index) const {
         const auto val = derived().template do_read_tlb_pma_index<SET>(slot_index);
         DSA_PRINTF("%s::read_tlb_pma_index<%" PRIu64 ">(%" PRIu64 ") = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), SET,
             slot_index, val, val);
@@ -406,7 +406,7 @@ class i_state_access { // CRTP
     /// \detail Writes to the TLB must be modify all fields atomically to prevent an inconsistent state.
     /// This simplifies all state access implementations.
     template <TLB_set_index SET>
-    void write_tlb(uint64_t slot_index, uint64_t vaddr_page, fast_addr vp_offset, uint64_t pma_index) {
+    void write_tlb(uint64_t slot_index, uint64_t vaddr_page, fast_addr vp_offset, uint64_t pma_index) const {
         derived().template do_write_tlb<SET>(slot_index, vaddr_page, vp_offset, pma_index);
         [[maybe_unused]] const auto fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
         DSA_PRINTF("%s::write_tlb<%" PRIu64 ">(%" PRIu64 ", 0x%" PRIx64 ", %s{0x%" PRIx64 "}, %" PRIu64 ")\n",
@@ -421,13 +421,13 @@ class i_state_access { // CRTP
     /// the Merkle tree only considers the pages that are currently in the write TLB and those that
     /// have been marked dirty. When a page leaves the write TLB, it is marked dirty.
     /// If the state belongs to a host machine, then this call MUST be forwarded to machine::mark_dirty_page();
-    void mark_dirty_page(fast_addr faddr, uint64_t pma_index) {
+    void mark_dirty_page(fast_addr faddr, uint64_t pma_index) const {
         derived().do_mark_dirty_page(faddr, pma_index);
     }
 
     /// \brief Writes a character to the console
     /// \param c Character to output
-    void putchar(uint8_t c) {
+    void putchar(uint8_t c) const {
         derived().do_putchar(c);
     }
 
diff --git a/src/i-uarch-state-access.h b/src/i-uarch-state-access.h
index 183874100..fd58933b7 100644
--- a/src/i-uarch-state-access.h
+++ b/src/i-uarch-state-access.h
@@ -27,7 +27,7 @@
 
 // NOLINTBEGIN(cppcoreguidelines-macro-usage)
 #define DEFINE_USA_READ(REG)                                                                                           \
-    uint64_t read_##REG() {                                                                                            \
+    uint64_t read_##REG() const {                                                                                      \
         if constexpr (!is_an_i_prefer_shadow_uarch_state_v<DERIVED>) {                                                 \
             const auto val = derived().do_read_##REG();                                                                \
             DUSA_PRINTF("%s::read_" #REG "() = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), val, val);                   \
@@ -38,7 +38,7 @@
     }
 
 #define DEFINE_USA_WRITE(REG)                                                                                          \
-    void write_##REG(uint64_t val) {                                                                                   \
+    void write_##REG(uint64_t val) const {                                                                             \
         if constexpr (!is_an_i_prefer_shadow_uarch_state_v<DERIVED>) {                                                 \
             derived().do_write_##REG(val);                                                                             \
             DUSA_PRINTF("%s::write_" #REG "(%" PRIu64 "(0x%" PRIx64 "))\n", get_name(), val, val);                     \
@@ -64,14 +64,14 @@ class i_uarch_state_access { // CRTP
         return *static_cast<const DERIVED *>(this);
     }
 
-    uint64_t prefer_read_shadow_uarch_state(shadow_uarch_state_what what) {
+    uint64_t prefer_read_shadow_uarch_state(shadow_uarch_state_what what) const {
         const auto val = derived().read_shadow_uarch_state(what);
         [[maybe_unused]] const auto *const what_name = shadow_uarch_state_get_what_name(what);
         DUSA_PRINTF("%s::read_shadow_uarch_state(%s) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), what_name, val, val);
         return val;
     }
 
-    void prefer_write_shadow_uarch_state(shadow_uarch_state_what what, uint64_t val) {
+    void prefer_write_shadow_uarch_state(shadow_uarch_state_what what, uint64_t val) const {
         derived().write_shadow_uarch_state(what, val);
         [[maybe_unused]] const auto *const what_name = shadow_uarch_state_get_what_name(what);
         DUSA_PRINTF("%s::write_shadow_uarch_state(%s, %" PRIu64 "(0x%" PRIx64 "))\n", get_name(), what_name, val, val);
@@ -86,7 +86,7 @@ class i_uarch_state_access { // CRTP
 #endif
     }
 
-    uint64_t read_uarch_x(int i) {
+    uint64_t read_uarch_x(int i) const {
         if constexpr (!is_an_i_prefer_shadow_uarch_state_v<DERIVED>) {
             const auto val = derived().do_read_uarch_x(i);
             DUSA_PRINTF("%s::read_uarch_x(%d) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), i, val, val);
@@ -96,7 +96,7 @@ class i_uarch_state_access { // CRTP
         }
     }
 
-    void write_uarch_x(int i, uint64_t val) {
+    void write_uarch_x(int i, uint64_t val) const {
         if constexpr (!is_an_i_prefer_shadow_uarch_state_v<DERIVED>) {
             derived().do_write_uarch_x(i, val);
             DUSA_PRINTF("%s::write_uarch_x(%d, %" PRIu64 ")\n", get_name(), i, val);
@@ -115,34 +115,34 @@ class i_uarch_state_access { // CRTP
     DEFINE_USA_WRITE(uarch_pc)
     // NOLINTEND(cppcoreguidelines-macro-usage)
 
-    uint64_t read_word(uint64_t paddr) {
+    uint64_t read_word(uint64_t paddr) const {
         const auto val = derived().do_read_word(paddr);
         DUSA_PRINTF("%s::read_word(phys_addr{0x%" PRIx64 "}) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), paddr, val,
             val);
         return val;
     }
 
-    void write_word(uint64_t paddr, uint64_t val) {
+    void write_word(uint64_t paddr, uint64_t val) const {
         derived().do_write_word(paddr, val);
         DUSA_PRINTF("%s::write_word(phys_addr{0x%" PRIx64 "}, %" PRIu64 "(0x%" PRIx64 "))\n", get_name(), paddr, val,
             val);
     }
 
     /// \brief Resets uarch to pristine state
-    void reset_uarch() {
+    void reset_uarch() const {
         return derived().do_reset_uarch();
     }
 
-    void putchar(uint8_t c) {
+    void putchar(uint8_t c) const {
         derived().do_putchar(c);
     }
 
-    void mark_dirty_page(uint64_t paddr, uint64_t pma_index) {
+    void mark_dirty_page(uint64_t paddr, uint64_t pma_index) const {
         return derived().do_mark_dirty_page(paddr, pma_index);
     }
 
     void write_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset,
-        uint64_t pma_index) {
+        uint64_t pma_index) const {
         derived().do_write_tlb(set_index, slot_index, vaddr_page, vp_offset, pma_index);
     }
 
diff --git a/src/interpret.cpp b/src/interpret.cpp
index 4079967a3..2b0879e6f 100644
--- a/src/interpret.cpp
+++ b/src/interpret.cpp
@@ -123,18 +123,18 @@ enum class rd_kind {
 };
 
 template <typename STATE_ACCESS>
-static inline void DUMP_STATS_INCR([[maybe_unused]] STATE_ACCESS a, [[maybe_unused]] const char *name) {
+static inline void DUMP_STATS_INCR([[maybe_unused]] const STATE_ACCESS a, [[maybe_unused]] const char *name) {
 #ifdef DUMP_STATS
-    if constexpr (is_an_i_counters_v<STATE_ACCESS>) {
+    if constexpr (is_an_i_accept_counters_v<STATE_ACCESS>) {
         a.increment_counter(name, "stats.");
     }
 #endif
 }
 
 template <typename STATE_ACCESS>
-static inline void DUMP_INSN_HIST_INCR([[maybe_unused]] STATE_ACCESS a, [[maybe_unused]] const char *name) {
+static inline void DUMP_INSN_HIST_INCR([[maybe_unused]] const STATE_ACCESS a, [[maybe_unused]] const char *name) {
 #ifdef DUMP_INSN_HIST
-    if constexpr (is_an_i_counters_v<STATE_ACCESS>) {
+    if constexpr (is_an_i_accept_counters_v<STATE_ACCESS>) {
         a.increment_counter(name, "insn.");
     }
 #endif
@@ -392,7 +392,7 @@ static FORCE_INLINE void set_prv(STATE_ACCESS &a, uint64_t new_prv) {
 /// \returns The new program counter, pointing to the raised exception trap handler.
 /// \details This function is outlined to minimize host CPU code cache pressure.
 template <typename STATE_ACCESS>
-static NO_INLINE uint64_t raise_exception(STATE_ACCESS a, uint64_t pc, uint64_t cause, uint64_t tval) {
+static NO_INLINE uint64_t raise_exception(const STATE_ACCESS a, uint64_t pc, uint64_t cause, uint64_t tval) {
     if (cause == MCAUSE_ILLEGAL_INSN && !insn_is_uncompressed(static_cast<uint32_t>(tval))) {
         // Discard high bits of compressed instructions,
         // this is not performed in the instruction hot loop as an optimization.
@@ -502,7 +502,7 @@ static NO_INLINE uint64_t raise_exception(STATE_ACCESS a, uint64_t pc, uint64_t
 /// \param a Machine state accessor object.
 /// \returns The mask.
 template <typename STATE_ACCESS>
-static inline uint32_t get_pending_irq_mask(STATE_ACCESS a) {
+static inline uint32_t get_pending_irq_mask(const STATE_ACCESS a) {
     const uint64_t mip = a.read_mip();
     const uint64_t mie = a.read_mie();
 
@@ -582,7 +582,7 @@ static inline uint32_t get_highest_priority_irq_num(uint32_t v) {
 /// \param a Machine state accessor object.
 /// \param pc Machine current program counter.
 template <typename STATE_ACCESS>
-static inline uint64_t raise_interrupt_if_any(STATE_ACCESS a, uint64_t pc) {
+static inline uint64_t raise_interrupt_if_any(const STATE_ACCESS a, uint64_t pc) {
     const uint32_t mask = get_pending_irq_mask(a);
     if (unlikely(mask != 0)) {
         const uint64_t irq_num = get_highest_priority_irq_num(mask);
@@ -595,7 +595,7 @@ static inline uint64_t raise_interrupt_if_any(STATE_ACCESS a, uint64_t pc) {
 /// \param a Machine state accessor object.
 /// \param mcycle Machine current cycle.
 template <typename STATE_ACCESS>
-static inline void set_rtc_interrupt(STATE_ACCESS a, uint64_t mcycle) {
+static inline void set_rtc_interrupt(const STATE_ACCESS a, uint64_t mcycle) {
     const uint64_t timecmp_cycle = rtc_time_to_cycle(a.read_clint_mtimecmp());
     if (timecmp_cycle <= mcycle && timecmp_cycle != 0) {
         const uint64_t mip = a.read_mip();
@@ -871,7 +871,7 @@ static FORCE_INLINE int32_t insn_get_C_SWSP_imm(uint32_t insn) {
 /// \param a Machine state accessor object.
 /// \param slot_index Slot index
 template <TLB_set_index SET, typename STATE_ACCESS>
-static void flush_tlb_slot(STATE_ACCESS a, uint64_t slot_index) {
+static void flush_tlb_slot(const STATE_ACCESS a, uint64_t slot_index) {
     // Make sure a valid page leaving the write TLB is marked as dirty
     // We must do this BEFORE we modify the TLB entries themselves
     // (Otherwise, we could stop uarch before it marks the page dirty but after
@@ -898,7 +898,7 @@ static void flush_tlb_slot(STATE_ACCESS a, uint64_t slot_index) {
 /// \tparam STATE_ACCESS Class of machine state accessor object.
 /// \param a Machine state accessor object.
 template <TLB_set_index SET, typename STATE_ACCESS>
-static void flush_tlb_set(STATE_ACCESS a) {
+static void flush_tlb_set(const STATE_ACCESS a) {
     for (uint64_t slot_index = 0; slot_index < TLB_SET_SIZE; ++slot_index) {
         flush_tlb_slot<SET>(a, slot_index);
     }
@@ -908,7 +908,7 @@ static void flush_tlb_set(STATE_ACCESS a) {
 /// \tparam STATE_ACCESS Class of machine state accessor object.
 /// \param a Machine state accessor object.
 template <typename STATE_ACCESS>
-static void flush_all_tlb(STATE_ACCESS a) {
+static void flush_all_tlb(const STATE_ACCESS a) {
     flush_tlb_set<TLB_CODE>(a);
     flush_tlb_set<TLB_READ>(a);
     flush_tlb_set<TLB_WRITE>(a);
@@ -919,7 +919,7 @@ static void flush_all_tlb(STATE_ACCESS a) {
 /// \param a Machine state accessor object.
 /// \param vaddr Virtual address to remove form mapping
 template <typename STATE_ACCESS>
-static void flush_tlb_vaddr(STATE_ACCESS a, uint64_t /* vaddr */) {
+static void flush_tlb_vaddr(const STATE_ACCESS a, uint64_t /* vaddr */) {
     // We can't flush just one TLB entry for that specific virtual address,
     // because megapages/gigapages may be in use while this TLB implementation ignores it,
     // so we have to flush all addresses.
@@ -938,7 +938,7 @@ static void flush_tlb_vaddr(STATE_ACCESS a, uint64_t /* vaddr */) {
 /// \param vp_offset Receives the new vp_offset that will be stored in the slot
 /// \returns The implementation-defined fast address corresponding to paddr
 template <TLB_set_index SET, typename STATE_ACCESS>
-static i_state_access_fast_addr_t<STATE_ACCESS> replace_tlb_entry(STATE_ACCESS a, uint64_t vaddr, uint64_t paddr,
+static i_state_access_fast_addr_t<STATE_ACCESS> replace_tlb_entry(const STATE_ACCESS a, uint64_t vaddr, uint64_t paddr,
     uint64_t pma_index, i_state_access_fast_addr_t<STATE_ACCESS> &vp_offset) {
     [[maybe_unused]] auto note = a.make_scoped_note("replace_tlb_entry");
     const auto slot_index = tlb_slot_index(vaddr);
@@ -959,7 +959,7 @@ static i_state_access_fast_addr_t<STATE_ACCESS> replace_tlb_entry(STATE_ACCESS a
 /// \param paddr Index of PMA where paddr falls
 /// \returns The implementation-defined fast address corresponding to paddr
 template <TLB_set_index SET, typename STATE_ACCESS>
-static FORCE_INLINE auto replace_tlb_entry(STATE_ACCESS a, uint64_t vaddr, uint64_t paddr, uint64_t pma_index) {
+static FORCE_INLINE auto replace_tlb_entry(const STATE_ACCESS a, uint64_t vaddr, uint64_t paddr, uint64_t pma_index) {
     i_state_access_fast_addr_t<STATE_ACCESS> vp_offset{0};
     return replace_tlb_entry<SET>(a, vaddr, paddr, pma_index, vp_offset);
 }
@@ -980,7 +980,7 @@ static FORCE_INLINE auto replace_tlb_entry(STATE_ACCESS a, uint64_t vaddr, uint6
 /// is outlined, and taking PC by reference would cause the compiler to store it in a stack variable
 /// instead of always storing it in register (this is an optimization).
 template <typename T, typename STATE_ACCESS, bool RAISE_STORE_EXCEPTIONS = false>
-static NO_INLINE std::pair<bool, uint64_t> read_virtual_memory_slow(STATE_ACCESS a, uint64_t pc, uint64_t mcycle,
+static NO_INLINE std::pair<bool, uint64_t> read_virtual_memory_slow(const STATE_ACCESS a, uint64_t pc, uint64_t mcycle,
     uint64_t vaddr, T *pval) {
     [[maybe_unused]] auto note = a.make_scoped_note("read_virtual_memory_slow");
     using U = std::make_unsigned_t<T>;
@@ -1035,7 +1035,8 @@ static NO_INLINE std::pair<bool, uint64_t> read_virtual_memory_slow(STATE_ACCESS
 /// \param pval Pointer to word receiving value.
 /// \returns True if succeeded, false otherwise.
 template <typename T, typename STATE_ACCESS, bool RAISE_STORE_EXCEPTIONS = false>
-static FORCE_INLINE bool read_virtual_memory(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint64_t vaddr, T *pval) {
+static FORCE_INLINE bool read_virtual_memory(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint64_t vaddr,
+    T *pval) {
     [[maybe_unused]] auto note = a.make_scoped_note("read_virtual_memory");
     // Try hitting the TLB
     const auto slot_index = tlb_slot_index(vaddr);
@@ -1073,7 +1074,7 @@ static FORCE_INLINE bool read_virtual_memory(STATE_ACCESS a, uint64_t &pc, uint6
 /// is outlined, and taking PC by reference would cause the compiler to store it in a stack variable
 /// instead of always storing it in register (this is an optimization).
 template <typename T, typename STATE_ACCESS>
-static NO_INLINE std::pair<execute_status, uint64_t> write_virtual_memory_slow(STATE_ACCESS a, uint64_t pc,
+static NO_INLINE std::pair<execute_status, uint64_t> write_virtual_memory_slow(const STATE_ACCESS a, uint64_t pc,
     uint64_t mcycle, uint64_t vaddr, uint64_t val64) {
     [[maybe_unused]] auto note = a.make_scoped_note("write_virtual_memory_slow");
     using U = std::make_unsigned_t<T>;
@@ -1120,8 +1121,8 @@ static NO_INLINE std::pair<execute_status, uint64_t> write_virtual_memory_slow(S
 /// \param val64 Value to write.
 /// \returns True if succeeded, false if exception raised.
 template <typename T, typename STATE_ACCESS>
-static FORCE_INLINE execute_status write_virtual_memory(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint64_t vaddr,
-    uint64_t val64) {
+static FORCE_INLINE execute_status write_virtual_memory(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle,
+    uint64_t vaddr, uint64_t val64) {
     [[maybe_unused]] auto note = a.make_scoped_note("write_virtual_memory");
     // Try hitting the TLB
     const uint64_t slot_index = tlb_slot_index(vaddr);
@@ -1142,8 +1143,8 @@ static FORCE_INLINE execute_status write_virtual_memory(STATE_ACCESS a, uint64_t
 }
 
 template <typename STATE_ACCESS>
-static auto dump_insn([[maybe_unused]] STATE_ACCESS a, [[maybe_unused]] uint64_t pc, [[maybe_unused]] uint32_t insn,
-    [[maybe_unused]] const char *name) {
+static auto dump_insn([[maybe_unused]] const STATE_ACCESS a, [[maybe_unused]] uint64_t pc,
+    [[maybe_unused]] uint32_t insn, [[maybe_unused]] const char *name) {
     DUMP_INSN_HIST_INCR(a, name);
 #ifdef DUMP_REGS
     dump_regs(a);
@@ -1170,7 +1171,7 @@ static auto dump_insn([[maybe_unused]] STATE_ACCESS a, [[maybe_unused]] uint64_t
 /// \details This function is tail-called whenever the caller decoded enough of the instruction to identify it as
 /// illegal.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status raise_illegal_insn_exception(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status raise_illegal_insn_exception(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     pc = raise_exception(a, pc, MCAUSE_ILLEGAL_INSN, insn);
     return execute_status::failure;
 }
@@ -1182,7 +1183,8 @@ static FORCE_INLINE execute_status raise_illegal_insn_exception(STATE_ACCESS a,
 /// \return execute_status::failure
 /// \details This function is tail-called whenever the caller identified that the next value of pc is misaligned.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status raise_misaligned_fetch_exception(STATE_ACCESS a, uint64_t &pc, uint64_t new_pc) {
+static FORCE_INLINE execute_status raise_misaligned_fetch_exception(const STATE_ACCESS a, uint64_t &pc,
+    uint64_t new_pc) {
     pc = raise_exception(a, pc, MCAUSE_INSN_ADDRESS_MISALIGNED, new_pc);
     return execute_status::failure;
 }
@@ -1231,7 +1233,7 @@ static FORCE_INLINE execute_status execute_jump(STATE_ACCESS /*a*/, uint64_t &pc
 /// \param pc Interpreter loop program counter (will be overwritten).
 /// \param insn Instruction.
 template <typename T, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_LR(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_LR(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     const uint64_t vaddr = a.read_x(insn_get_rs1(insn));
     T val = 0;
     if (unlikely(!read_virtual_memory<T>(a, pc, mcycle, vaddr, &val))) {
@@ -1252,7 +1254,7 @@ static FORCE_INLINE execute_status execute_LR(STATE_ACCESS a, uint64_t &pc, uint
 /// \param pc Interpreter loop program counter (will be overwritten).
 /// \param insn Instruction.
 template <typename T, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SC(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SC(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     uint64_t val = 0;
     const uint64_t vaddr = a.read_x(insn_get_rs1(insn));
     execute_status status = execute_status::success;
@@ -1275,7 +1277,7 @@ static FORCE_INLINE execute_status execute_SC(STATE_ACCESS a, uint64_t &pc, uint
 
 /// \brief Implementation of the LR.W instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_LR_W(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_LR_W(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     if (unlikely((insn & 0b00000001111100000000000000000000) != 0)) {
         return raise_illegal_insn_exception(a, pc, insn);
     }
@@ -1285,13 +1287,13 @@ static FORCE_INLINE execute_status execute_LR_W(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the SC.W instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SC_W(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SC_W(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sc.w");
     return execute_SC<int32_t>(a, pc, mcycle, insn);
 }
 
 template <typename T, typename STATE_ACCESS, typename F>
-static FORCE_INLINE execute_status execute_AMO(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn,
+static FORCE_INLINE execute_status execute_AMO(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn,
     const F &f) {
     const uint64_t vaddr = a.read_x(insn_get_rs1(insn));
     T valm = 0;
@@ -1316,14 +1318,16 @@ static FORCE_INLINE execute_status execute_AMO(STATE_ACCESS a, uint64_t &pc, uin
 
 /// \brief Implementation of the AMOSWAP.W instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_AMOSWAP_W(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_AMOSWAP_W(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle,
+    uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amoswap.w");
     return execute_AMO<int32_t>(a, pc, mcycle, insn, [](int32_t /*valm*/, int32_t valr) -> int32_t { return valr; });
 }
 
 /// \brief Implementation of the AMOADD.W instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_AMOADD_W(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_AMOADD_W(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle,
+    uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amoadd.w");
     return execute_AMO<int32_t>(a, pc, mcycle, insn, [](int32_t valm, int32_t valr) -> int32_t {
         int32_t val = 0;
@@ -1333,28 +1337,31 @@ static FORCE_INLINE execute_status execute_AMOADD_W(STATE_ACCESS a, uint64_t &pc
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_AMOXOR_W(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_AMOXOR_W(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle,
+    uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amoxor.w");
     return execute_AMO<int32_t>(a, pc, mcycle, insn, [](int32_t valm, int32_t valr) -> int32_t { return valm ^ valr; });
 }
 
 /// \brief Implementation of the AMOAND.W instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_AMOAND_W(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_AMOAND_W(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle,
+    uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amoand.w");
     return execute_AMO<int32_t>(a, pc, mcycle, insn, [](int32_t valm, int32_t valr) -> int32_t { return valm & valr; });
 }
 
 /// \brief Implementation of the AMOOR.W instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_AMOOR_W(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_AMOOR_W(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amoor.w");
     return execute_AMO<int32_t>(a, pc, mcycle, insn, [](int32_t valm, int32_t valr) -> int32_t { return valm | valr; });
 }
 
 /// \brief Implementation of the AMOMIN.W instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_AMOMIN_W(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_AMOMIN_W(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle,
+    uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amomin.w");
     return execute_AMO<int32_t>(a, pc, mcycle, insn, [](int32_t valm, int32_t valr) -> int32_t {
         if (valm < valr) {
@@ -1366,7 +1373,8 @@ static FORCE_INLINE execute_status execute_AMOMIN_W(STATE_ACCESS a, uint64_t &pc
 
 /// \brief Implementation of the AMOMAX.W instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_AMOMAX_W(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_AMOMAX_W(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle,
+    uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amomax.w");
     return execute_AMO<int32_t>(a, pc, mcycle, insn, [](int32_t valm, int32_t valr) -> int32_t {
         if (valm > valr) {
@@ -1378,7 +1386,8 @@ static FORCE_INLINE execute_status execute_AMOMAX_W(STATE_ACCESS a, uint64_t &pc
 
 /// \brief Implementation of the AMOMINU.W instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_AMOMINU_W(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_AMOMINU_W(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle,
+    uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amominu.w");
     return execute_AMO<int32_t>(a, pc, mcycle, insn, [](int32_t valm, int32_t valr) -> int32_t {
         if (static_cast<uint32_t>(valm) < static_cast<uint32_t>(valr)) {
@@ -1390,7 +1399,8 @@ static FORCE_INLINE execute_status execute_AMOMINU_W(STATE_ACCESS a, uint64_t &p
 
 /// \brief Implementation of the AMOMAXU.W instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_AMOMAXU_W(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_AMOMAXU_W(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle,
+    uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amomaxu.w");
     return execute_AMO<int32_t>(a, pc, mcycle, insn, [](int32_t valm, int32_t valr) -> int32_t {
         if (static_cast<uint32_t>(valm) > static_cast<uint32_t>(valr)) {
@@ -1402,7 +1412,7 @@ static FORCE_INLINE execute_status execute_AMOMAXU_W(STATE_ACCESS a, uint64_t &p
 
 /// \brief Implementation of the LR.D instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_LR_D(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_LR_D(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     if (unlikely((insn & 0b00000001111100000000000000000000) != 0)) {
         return raise_illegal_insn_exception(a, pc, insn);
     }
@@ -1412,21 +1422,23 @@ static FORCE_INLINE execute_status execute_LR_D(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the SC.D instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SC_D(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SC_D(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sc.d");
     return execute_SC<uint64_t>(a, pc, mcycle, insn);
 }
 
 /// \brief Implementation of the AMOSWAP.D instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_AMOSWAP_D(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_AMOSWAP_D(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle,
+    uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amoswap.d");
     return execute_AMO<int64_t>(a, pc, mcycle, insn, [](int64_t /*valm*/, int64_t valr) -> int64_t { return valr; });
 }
 
 /// \brief Implementation of the AMOADD.D instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_AMOADD_D(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_AMOADD_D(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle,
+    uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amoadd.d");
     return execute_AMO<int64_t>(a, pc, mcycle, insn, [](int64_t valm, int64_t valr) -> int64_t {
         int64_t val = 0;
@@ -1436,28 +1448,31 @@ static FORCE_INLINE execute_status execute_AMOADD_D(STATE_ACCESS a, uint64_t &pc
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_AMOXOR_D(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_AMOXOR_D(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle,
+    uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amoxor.d");
     return execute_AMO<int64_t>(a, pc, mcycle, insn, [](int64_t valm, int64_t valr) -> int64_t { return valm ^ valr; });
 }
 
 /// \brief Implementation of the AMOAND.D instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_AMOAND_D(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_AMOAND_D(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle,
+    uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amoand.d");
     return execute_AMO<int64_t>(a, pc, mcycle, insn, [](int64_t valm, int64_t valr) -> int64_t { return valm & valr; });
 }
 
 /// \brief Implementation of the AMOOR.D instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_AMOOR_D(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_AMOOR_D(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amoor.d");
     return execute_AMO<int64_t>(a, pc, mcycle, insn, [](int64_t valm, int64_t valr) -> int64_t { return valm | valr; });
 }
 
 /// \brief Implementation of the AMOMIN.D instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_AMOMIN_D(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_AMOMIN_D(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle,
+    uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amomin.d");
     return execute_AMO<int64_t>(a, pc, mcycle, insn, [](int64_t valm, int64_t valr) -> int64_t {
         if (valm < valr) {
@@ -1469,7 +1484,8 @@ static FORCE_INLINE execute_status execute_AMOMIN_D(STATE_ACCESS a, uint64_t &pc
 
 /// \brief Implementation of the AMOMAX.D instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_AMOMAX_D(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_AMOMAX_D(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle,
+    uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amomax.d");
     return execute_AMO<int64_t>(a, pc, mcycle, insn, [](int64_t valm, int64_t valr) -> int64_t {
         if (valm > valr) {
@@ -1481,7 +1497,8 @@ static FORCE_INLINE execute_status execute_AMOMAX_D(STATE_ACCESS a, uint64_t &pc
 
 /// \brief Implementation of the AMOMINU.D instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_AMOMINU_D(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_AMOMINU_D(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle,
+    uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amominu.d");
     return execute_AMO<uint64_t>(a, pc, mcycle, insn, [](uint64_t valm, uint64_t valr) -> uint64_t {
         if (valm < valr) {
@@ -1493,7 +1510,8 @@ static FORCE_INLINE execute_status execute_AMOMINU_D(STATE_ACCESS a, uint64_t &p
 
 /// \brief Implementation of the AMOMAXU.D instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_AMOMAXU_D(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_AMOMAXU_D(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle,
+    uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "amomaxu.d");
     return execute_AMO<uint64_t>(a, pc, mcycle, insn, [](uint64_t valm, uint64_t valr) -> uint64_t {
         if (valm > valr) {
@@ -1505,7 +1523,7 @@ static FORCE_INLINE execute_status execute_AMOMAXU_D(STATE_ACCESS a, uint64_t &p
 
 /// \brief Implementation of the ADDW instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_ADDW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_ADDW(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "addw");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -1522,7 +1540,7 @@ static FORCE_INLINE execute_status execute_ADDW(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the SUBW instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SUBW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SUBW(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "subw");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -1539,7 +1557,7 @@ static FORCE_INLINE execute_status execute_SUBW(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the SLLW instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SLLW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SLLW(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     if (unlikely((insn & 0b11111110000000000111000001111111) != 0b00000000000000000001000000111011)) {
         return raise_illegal_insn_exception(a, pc, insn);
     }
@@ -1555,7 +1573,7 @@ static FORCE_INLINE execute_status execute_SLLW(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the SRLW instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SRLW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SRLW(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "srlw");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -1568,7 +1586,7 @@ static FORCE_INLINE execute_status execute_SRLW(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the SRAW instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SRAW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SRAW(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sraw");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -1581,7 +1599,7 @@ static FORCE_INLINE execute_status execute_SRAW(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the MULW instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_MULW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_MULW(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "mulw");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -1597,7 +1615,7 @@ static FORCE_INLINE execute_status execute_MULW(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the DIVW instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_DIVW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_DIVW(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     if (unlikely((insn & 0b11111110000000000111000001111111) != 0b00000010000000000100000000111011)) {
         return raise_illegal_insn_exception(a, pc, insn);
     }
@@ -1620,7 +1638,7 @@ static FORCE_INLINE execute_status execute_DIVW(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the DIVUW instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_DIVUW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_DIVUW(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "divuw");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -1637,7 +1655,7 @@ static FORCE_INLINE execute_status execute_DIVUW(STATE_ACCESS a, uint64_t &pc, u
 
 /// \brief Implementation of the REMW instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_REMW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_REMW(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     if (unlikely((insn & 0b11111110000000000111000001111111) != 0b00000010000000000110000000111011)) {
         return raise_illegal_insn_exception(a, pc, insn);
     }
@@ -1660,7 +1678,7 @@ static FORCE_INLINE execute_status execute_REMW(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the REMUW instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_REMUW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_REMUW(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     if (unlikely((insn & 0b11111110000000000111000001111111) != 0b00000010000000000111000000111011)) {
         return raise_illegal_insn_exception(a, pc, insn);
     }
@@ -1689,7 +1707,7 @@ static inline uint64_t read_csr_success(uint64_t val, bool *status) {
 }
 
 template <typename STATE_ACCESS>
-static inline bool rdcounteren(STATE_ACCESS a, uint64_t mask) {
+static inline bool rdcounteren(const STATE_ACCESS a, uint64_t mask) {
     uint64_t counteren = MCOUNTEREN_R_MASK;
     auto prv = a.read_iprv();
     if (prv <= PRV_S) {
@@ -1702,7 +1720,7 @@ static inline bool rdcounteren(STATE_ACCESS a, uint64_t mask) {
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_cycle(STATE_ACCESS a, uint64_t mcycle, bool *status) {
+static inline uint64_t read_csr_cycle(const STATE_ACCESS a, uint64_t mcycle, bool *status) {
     if (rdcounteren(a, MCOUNTEREN_CY_MASK)) {
         return read_csr_success(mcycle, status);
     }
@@ -1710,7 +1728,7 @@ static inline uint64_t read_csr_cycle(STATE_ACCESS a, uint64_t mcycle, bool *sta
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_instret(STATE_ACCESS a, uint64_t mcycle, bool *status) {
+static inline uint64_t read_csr_instret(const STATE_ACCESS a, uint64_t mcycle, bool *status) {
     if (unlikely(!rdcounteren(a, MCOUNTEREN_IR_MASK))) {
         return read_csr_fail(status);
     }
@@ -1720,7 +1738,7 @@ static inline uint64_t read_csr_instret(STATE_ACCESS a, uint64_t mcycle, bool *s
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_time(STATE_ACCESS a, uint64_t mcycle, bool *status) {
+static inline uint64_t read_csr_time(const STATE_ACCESS a, uint64_t mcycle, bool *status) {
     if (unlikely(!rdcounteren(a, MCOUNTEREN_TM_MASK))) {
         return read_csr_fail(status);
     }
@@ -1729,54 +1747,54 @@ static inline uint64_t read_csr_time(STATE_ACCESS a, uint64_t mcycle, bool *stat
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_sstatus(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_sstatus(const STATE_ACCESS a, bool *status) {
     return read_csr_success(a.read_mstatus() & SSTATUS_R_MASK, status);
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_senvcfg(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_senvcfg(const STATE_ACCESS a, bool *status) {
     return read_csr_success(a.read_senvcfg() & SENVCFG_R_MASK, status);
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_sie(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_sie(const STATE_ACCESS a, bool *status) {
     const uint64_t mie = a.read_mie();
     const uint64_t mideleg = a.read_mideleg();
     return read_csr_success(mie & mideleg, status);
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_stvec(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_stvec(const STATE_ACCESS a, bool *status) {
     return read_csr_success(a.read_stvec(), status);
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_scounteren(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_scounteren(const STATE_ACCESS a, bool *status) {
     return read_csr_success(a.read_scounteren(), status);
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_sscratch(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_sscratch(const STATE_ACCESS a, bool *status) {
     return read_csr_success(a.read_sscratch(), status);
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_sepc(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_sepc(const STATE_ACCESS a, bool *status) {
     return read_csr_success(a.read_sepc(), status);
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_scause(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_scause(const STATE_ACCESS a, bool *status) {
     return read_csr_success(a.read_scause(), status);
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_stval(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_stval(const STATE_ACCESS a, bool *status) {
     return read_csr_success(a.read_stval(), status);
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_sip(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_sip(const STATE_ACCESS a, bool *status) {
     // Ensure values are are loaded in order: do not nest with operator
     const uint64_t mip = a.read_mip();
     const uint64_t mideleg = a.read_mideleg();
@@ -1784,7 +1802,7 @@ static inline uint64_t read_csr_sip(STATE_ACCESS a, bool *status) {
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_satp(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_satp(const STATE_ACCESS a, bool *status) {
     const uint64_t mstatus = a.read_mstatus();
     auto prv = a.read_iprv();
     // When TVM=1, attempts to read or write the satp CSR
@@ -1796,67 +1814,67 @@ static inline uint64_t read_csr_satp(STATE_ACCESS a, bool *status) {
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_mstatus(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_mstatus(const STATE_ACCESS a, bool *status) {
     return read_csr_success(a.read_mstatus() & MSTATUS_R_MASK, status);
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_menvcfg(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_menvcfg(const STATE_ACCESS a, bool *status) {
     return read_csr_success(a.read_menvcfg() & MENVCFG_R_MASK, status);
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_misa(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_misa(const STATE_ACCESS a, bool *status) {
     return read_csr_success(a.read_misa(), status);
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_medeleg(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_medeleg(const STATE_ACCESS a, bool *status) {
     return read_csr_success(a.read_medeleg(), status);
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_mideleg(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_mideleg(const STATE_ACCESS a, bool *status) {
     return read_csr_success(a.read_mideleg(), status);
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_mie(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_mie(const STATE_ACCESS a, bool *status) {
     return read_csr_success(a.read_mie(), status);
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_mtvec(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_mtvec(const STATE_ACCESS a, bool *status) {
     return read_csr_success(a.read_mtvec(), status);
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_mcounteren(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_mcounteren(const STATE_ACCESS a, bool *status) {
     return read_csr_success(a.read_mcounteren(), status);
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_mscratch(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_mscratch(const STATE_ACCESS a, bool *status) {
     return read_csr_success(a.read_mscratch(), status);
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_mepc(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_mepc(const STATE_ACCESS a, bool *status) {
     return read_csr_success(a.read_mepc(), status);
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_mcause(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_mcause(const STATE_ACCESS a, bool *status) {
     return read_csr_success(a.read_mcause(), status);
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_mtval(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_mtval(const STATE_ACCESS a, bool *status) {
     return read_csr_success(a.read_mtval(), status);
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_mip(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_mip(const STATE_ACCESS a, bool *status) {
     return read_csr_success(a.read_mip(), status);
 }
 
@@ -1865,29 +1883,29 @@ static inline uint64_t read_csr_mcycle(uint64_t mcycle, bool *status) {
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_minstret(STATE_ACCESS a, uint64_t mcycle, bool *status) {
+static inline uint64_t read_csr_minstret(const STATE_ACCESS a, uint64_t mcycle, bool *status) {
     const uint64_t icycleinstret = a.read_icycleinstret();
     const uint64_t minstret = mcycle - icycleinstret;
     return read_csr_success(minstret, status);
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_mvendorid(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_mvendorid(const STATE_ACCESS a, bool *status) {
     return read_csr_success(a.read_mvendorid(), status);
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_marchid(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_marchid(const STATE_ACCESS a, bool *status) {
     return read_csr_success(a.read_marchid(), status);
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_mimpid(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_mimpid(const STATE_ACCESS a, bool *status) {
     return read_csr_success(a.read_mimpid(), status);
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_fflags(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_fflags(const STATE_ACCESS a, bool *status) {
     // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((a.read_mstatus() & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
         return read_csr_fail(status);
@@ -1897,7 +1915,7 @@ static inline uint64_t read_csr_fflags(STATE_ACCESS a, bool *status) {
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_frm(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_frm(const STATE_ACCESS a, bool *status) {
     // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((a.read_mstatus() & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
         return read_csr_fail(status);
@@ -1907,7 +1925,7 @@ static inline uint64_t read_csr_frm(STATE_ACCESS a, bool *status) {
 }
 
 template <typename STATE_ACCESS>
-static inline uint64_t read_csr_fcsr(STATE_ACCESS a, bool *status) {
+static inline uint64_t read_csr_fcsr(const STATE_ACCESS a, bool *status) {
     // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((a.read_mstatus() & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
         return read_csr_fail(status);
@@ -1922,7 +1940,7 @@ static inline uint64_t read_csr_fcsr(STATE_ACCESS a, bool *status) {
 /// \returns Register value.
 /// \details This function is outlined to minimize host CPU code cache pressure.
 template <typename STATE_ACCESS>
-static NO_INLINE uint64_t read_csr(STATE_ACCESS a, uint64_t mcycle, CSR_address csraddr, bool *status) {
+static NO_INLINE uint64_t read_csr(const STATE_ACCESS a, uint64_t mcycle, CSR_address csraddr, bool *status) {
     if (unlikely(csr_prv(csraddr) > a.read_iprv())) {
         return read_csr_fail(status);
     }
@@ -2083,20 +2101,20 @@ static NO_INLINE uint64_t read_csr(STATE_ACCESS a, uint64_t mcycle, CSR_address
 }
 
 template <typename STATE_ACCESS>
-static execute_status write_csr_sstatus(STATE_ACCESS a, uint64_t val) {
+static execute_status write_csr_sstatus(const STATE_ACCESS a, uint64_t val) {
     const uint64_t mstatus = a.read_mstatus();
     return write_csr_mstatus(a, (mstatus & ~SSTATUS_W_MASK) | (val & SSTATUS_W_MASK));
 }
 
 template <typename STATE_ACCESS>
-static execute_status write_csr_senvcfg(STATE_ACCESS a, uint64_t val) {
+static execute_status write_csr_senvcfg(const STATE_ACCESS a, uint64_t val) {
     const uint64_t senvcfg = a.read_senvcfg();
     a.write_senvcfg((senvcfg & ~SENVCFG_W_MASK) | (val & SENVCFG_W_MASK));
     return execute_status::success;
 }
 
 template <typename STATE_ACCESS>
-static execute_status write_csr_sie(STATE_ACCESS a, uint64_t val) {
+static execute_status write_csr_sie(const STATE_ACCESS a, uint64_t val) {
     uint64_t mie = a.read_mie();
     const uint64_t mask = a.read_mideleg();
     mie = (mie & ~mask) | (val & mask);
@@ -2105,43 +2123,43 @@ static execute_status write_csr_sie(STATE_ACCESS a, uint64_t val) {
 }
 
 template <typename STATE_ACCESS>
-static execute_status write_csr_stvec(STATE_ACCESS a, uint64_t val) {
+static execute_status write_csr_stvec(const STATE_ACCESS a, uint64_t val) {
     a.write_stvec(val & ~1);
     return execute_status::success;
 }
 
 template <typename STATE_ACCESS>
-static execute_status write_csr_scounteren(STATE_ACCESS a, uint64_t val) {
+static execute_status write_csr_scounteren(const STATE_ACCESS a, uint64_t val) {
     a.write_scounteren(val & SCOUNTEREN_RW_MASK);
     return execute_status::success;
 }
 
 template <typename STATE_ACCESS>
-static execute_status write_csr_sscratch(STATE_ACCESS a, uint64_t val) {
+static execute_status write_csr_sscratch(const STATE_ACCESS a, uint64_t val) {
     a.write_sscratch(val);
     return execute_status::success;
 }
 
 template <typename STATE_ACCESS>
-static execute_status write_csr_sepc(STATE_ACCESS a, uint64_t val) {
+static execute_status write_csr_sepc(const STATE_ACCESS a, uint64_t val) {
     a.write_sepc(val & ~1);
     return execute_status::success;
 }
 
 template <typename STATE_ACCESS>
-static execute_status write_csr_scause(STATE_ACCESS a, uint64_t val) {
+static execute_status write_csr_scause(const STATE_ACCESS a, uint64_t val) {
     a.write_scause(val);
     return execute_status::success;
 }
 
 template <typename STATE_ACCESS>
-static execute_status write_csr_stval(STATE_ACCESS a, uint64_t val) {
+static execute_status write_csr_stval(const STATE_ACCESS a, uint64_t val) {
     a.write_stval(val);
     return execute_status::success;
 }
 
 template <typename STATE_ACCESS>
-static execute_status write_csr_sip(STATE_ACCESS a, uint64_t val) {
+static execute_status write_csr_sip(const STATE_ACCESS a, uint64_t val) {
     const uint64_t mask = a.read_mideleg();
     uint64_t mip = a.read_mip();
     mip = (mip & ~mask) | (val & mask);
@@ -2150,7 +2168,7 @@ static execute_status write_csr_sip(STATE_ACCESS a, uint64_t val) {
 }
 
 template <typename STATE_ACCESS>
-static NO_INLINE execute_status write_csr_satp(STATE_ACCESS a, uint64_t val) {
+static NO_INLINE execute_status write_csr_satp(const STATE_ACCESS a, uint64_t val) {
     const uint64_t mstatus = a.read_mstatus();
     auto prv = a.read_iprv();
 
@@ -2183,7 +2201,7 @@ static NO_INLINE execute_status write_csr_satp(STATE_ACCESS a, uint64_t val) {
     a.write_satp(stap);
 
 #ifdef DUMP_STATS
-    if constexpr (is_an_i_counters_v<STATE_ACCESS>) {
+    if constexpr (is_an_i_accept_counters_v<STATE_ACCESS>) {
         const uint64_t asid = (stap & SATP_ASID_MASK) >> SATP_ASID_SHIFT;
         if (asid != ASID_MAX_MASK) { // Software is not testing ASID bits
             a.write_counter(std::max(a.read_counter("stats.max_asid"), asid), "stats.max_asid");
@@ -2205,7 +2223,7 @@ static NO_INLINE execute_status write_csr_satp(STATE_ACCESS a, uint64_t val) {
 }
 
 template <typename STATE_ACCESS>
-static NO_INLINE execute_status write_csr_mstatus(STATE_ACCESS a, uint64_t val) {
+static NO_INLINE execute_status write_csr_mstatus(const STATE_ACCESS a, uint64_t val) {
     const uint64_t old_mstatus = a.read_mstatus() & MSTATUS_R_MASK;
 
     // M-mode software can determine whether a privilege mode is implemented
@@ -2278,7 +2296,7 @@ static NO_INLINE execute_status write_csr_mstatus(STATE_ACCESS a, uint64_t val)
 }
 
 template <typename STATE_ACCESS>
-static execute_status write_csr_menvcfg(STATE_ACCESS a, uint64_t val) {
+static execute_status write_csr_menvcfg(const STATE_ACCESS a, uint64_t val) {
     uint64_t menvcfg = a.read_menvcfg() & MENVCFG_R_MASK;
 
     // Modify only bits that can be written to
@@ -2289,7 +2307,7 @@ static execute_status write_csr_menvcfg(STATE_ACCESS a, uint64_t val) {
 }
 
 template <typename STATE_ACCESS>
-static execute_status write_csr_medeleg(STATE_ACCESS a, uint64_t val) {
+static execute_status write_csr_medeleg(const STATE_ACCESS a, uint64_t val) {
     // For exceptions that cannot occur in less privileged modes,
     // the corresponding medeleg bits should be read-only zero
     a.write_medeleg((a.read_medeleg() & ~MEDELEG_W_MASK) | (val & MEDELEG_W_MASK));
@@ -2297,7 +2315,7 @@ static execute_status write_csr_medeleg(STATE_ACCESS a, uint64_t val) {
 }
 
 template <typename STATE_ACCESS>
-static execute_status write_csr_mideleg(STATE_ACCESS a, uint64_t val) {
+static execute_status write_csr_mideleg(const STATE_ACCESS a, uint64_t val) {
     const uint64_t mask = MIP_SSIP_MASK | MIP_STIP_MASK | MIP_SEIP_MASK;
     uint64_t mideleg = a.read_mideleg();
     mideleg = (mideleg & ~mask) | (val & mask);
@@ -2306,7 +2324,7 @@ static execute_status write_csr_mideleg(STATE_ACCESS a, uint64_t val) {
 }
 
 template <typename STATE_ACCESS>
-static execute_status write_csr_mie(STATE_ACCESS a, uint64_t val) {
+static execute_status write_csr_mie(const STATE_ACCESS a, uint64_t val) {
     const uint64_t mask = MIP_MSIP_MASK | MIP_MTIP_MASK | MIP_MEIP_MASK | MIP_SSIP_MASK | MIP_STIP_MASK | MIP_SEIP_MASK;
     uint64_t mie = a.read_mie();
     mie = (mie & ~mask) | (val & mask);
@@ -2315,19 +2333,19 @@ static execute_status write_csr_mie(STATE_ACCESS a, uint64_t val) {
 }
 
 template <typename STATE_ACCESS>
-static execute_status write_csr_mtvec(STATE_ACCESS a, uint64_t val) {
+static execute_status write_csr_mtvec(const STATE_ACCESS a, uint64_t val) {
     a.write_mtvec(val & ~1);
     return execute_status::success;
 }
 
 template <typename STATE_ACCESS>
-static execute_status write_csr_mcounteren(STATE_ACCESS a, uint64_t val) {
+static execute_status write_csr_mcounteren(const STATE_ACCESS a, uint64_t val) {
     a.write_mcounteren(val & MCOUNTEREN_RW_MASK);
     return execute_status::success;
 }
 
 template <typename STATE_ACCESS>
-static execute_status write_csr_minstret(STATE_ACCESS a, uint64_t mcycle, uint64_t val) {
+static execute_status write_csr_minstret(const STATE_ACCESS a, uint64_t mcycle, uint64_t val) {
     // Note that mcycle will only be incremented after the instruction is executed,
     // but we have to compute this in advance
     const uint64_t icycleinstret = (mcycle + 1) - val;
@@ -2347,31 +2365,31 @@ static execute_status write_csr_mcycle(STATE_ACCESS /*a*/, uint64_t /*val*/) {
 }
 
 template <typename STATE_ACCESS>
-static execute_status write_csr_mscratch(STATE_ACCESS a, uint64_t val) {
+static execute_status write_csr_mscratch(const STATE_ACCESS a, uint64_t val) {
     a.write_mscratch(val);
     return execute_status::success;
 }
 
 template <typename STATE_ACCESS>
-static execute_status write_csr_mepc(STATE_ACCESS a, uint64_t val) {
+static execute_status write_csr_mepc(const STATE_ACCESS a, uint64_t val) {
     a.write_mepc(val & ~1);
     return execute_status::success;
 }
 
 template <typename STATE_ACCESS>
-static execute_status write_csr_mcause(STATE_ACCESS a, uint64_t val) {
+static execute_status write_csr_mcause(const STATE_ACCESS a, uint64_t val) {
     a.write_mcause(val);
     return execute_status::success;
 }
 
 template <typename STATE_ACCESS>
-static execute_status write_csr_mtval(STATE_ACCESS a, uint64_t val) {
+static execute_status write_csr_mtval(const STATE_ACCESS a, uint64_t val) {
     a.write_mtval(val);
     return execute_status::success;
 }
 
 template <typename STATE_ACCESS>
-static execute_status write_csr_mip(STATE_ACCESS a, uint64_t val) {
+static execute_status write_csr_mip(const STATE_ACCESS a, uint64_t val) {
     const uint64_t mask = MIP_SSIP_MASK | MIP_STIP_MASK | MIP_SEIP_MASK;
     auto mip = a.read_mip();
     mip = (mip & ~mask) | (val & mask);
@@ -2380,7 +2398,7 @@ static execute_status write_csr_mip(STATE_ACCESS a, uint64_t val) {
 }
 
 template <typename STATE_ACCESS>
-static inline execute_status write_csr_fflags(STATE_ACCESS a, uint64_t val) {
+static inline execute_status write_csr_fflags(const STATE_ACCESS a, uint64_t val) {
     const uint64_t mstatus = a.read_mstatus();
     // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((mstatus & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
@@ -2392,7 +2410,7 @@ static inline execute_status write_csr_fflags(STATE_ACCESS a, uint64_t val) {
 }
 
 template <typename STATE_ACCESS>
-static inline execute_status write_csr_frm(STATE_ACCESS a, uint64_t val) {
+static inline execute_status write_csr_frm(const STATE_ACCESS a, uint64_t val) {
     const uint64_t mstatus = a.read_mstatus();
     // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((mstatus & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
@@ -2404,7 +2422,7 @@ static inline execute_status write_csr_frm(STATE_ACCESS a, uint64_t val) {
 }
 
 template <typename STATE_ACCESS>
-static inline execute_status write_csr_fcsr(STATE_ACCESS a, uint64_t val) {
+static inline execute_status write_csr_fcsr(const STATE_ACCESS a, uint64_t val) {
     const uint64_t mstatus = a.read_mstatus();
     // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((mstatus & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
@@ -2422,7 +2440,7 @@ static inline execute_status write_csr_fcsr(STATE_ACCESS a, uint64_t val) {
 /// \returns The status of the operation (true for success, false otherwise).
 /// \details This function is outlined to minimize host CPU code cache pressure.
 template <typename STATE_ACCESS>
-static NO_INLINE execute_status write_csr(STATE_ACCESS a, uint64_t mcycle, CSR_address csraddr, uint64_t val) {
+static NO_INLINE execute_status write_csr(const STATE_ACCESS a, uint64_t mcycle, CSR_address csraddr, uint64_t val) {
 #if defined(DUMP_CSR)
     D_PRINTF("csr_write: csr=0x%03x val=0x", static_cast<int>(csraddr));
     print_uint64_t(val);
@@ -2576,7 +2594,7 @@ static NO_INLINE execute_status write_csr(STATE_ACCESS a, uint64_t mcycle, CSR_a
 }
 
 template <typename STATE_ACCESS, typename RS1VAL>
-static FORCE_INLINE execute_status execute_csr_RW(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn,
+static FORCE_INLINE execute_status execute_csr_RW(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn,
     const RS1VAL &rs1val) {
     auto csraddr = static_cast<CSR_address>(insn_I_get_uimm(insn));
     // Try to read old CSR value
@@ -2609,22 +2627,22 @@ static FORCE_INLINE execute_status execute_csr_RW(STATE_ACCESS a, uint64_t &pc,
 
 /// \brief Implementation of the CSRRW instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_CSRRW(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_CSRRW(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "csrrw");
     return execute_csr_RW(a, pc, mcycle, insn,
-        [](STATE_ACCESS a, uint32_t insn) -> uint64_t { return a.read_x(insn_get_rs1(insn)); });
+        [](const STATE_ACCESS a, uint32_t insn) -> uint64_t { return a.read_x(insn_get_rs1(insn)); });
 }
 
 /// \brief Implementation of the CSRRWI instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_CSRRWI(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_CSRRWI(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "csrrwi");
     return execute_csr_RW(a, pc, mcycle, insn,
         [](STATE_ACCESS, uint32_t insn) -> uint64_t { return static_cast<uint64_t>(insn_get_rs1(insn)); });
 }
 
 template <typename STATE_ACCESS, typename F>
-static FORCE_INLINE execute_status execute_csr_SC(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn,
+static FORCE_INLINE execute_status execute_csr_SC(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn,
     const F &f) {
     auto csraddr = static_cast<CSR_address>(insn_I_get_uimm(insn));
     // Try to read old CSR value
@@ -2659,20 +2677,20 @@ static FORCE_INLINE execute_status execute_csr_SC(STATE_ACCESS a, uint64_t &pc,
 
 /// \brief Implementation of the CSRRS instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_CSRRS(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_CSRRS(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "csrrs");
     return execute_csr_SC(a, pc, mcycle, insn, [](uint64_t csr, uint64_t rs1) -> uint64_t { return csr | rs1; });
 }
 
 /// \brief Implementation of the CSRRC instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_CSRRC(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_CSRRC(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "csrrc");
     return execute_csr_SC(a, pc, mcycle, insn, [](uint64_t csr, uint64_t rs1) -> uint64_t { return csr & ~rs1; });
 }
 
 template <typename STATE_ACCESS, typename F>
-static FORCE_INLINE execute_status execute_csr_SCI(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn,
+static FORCE_INLINE execute_status execute_csr_SCI(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn,
     const F &f) {
     auto csraddr = static_cast<CSR_address>(insn_I_get_uimm(insn));
     // Try to read old CSR value
@@ -2704,21 +2722,21 @@ static FORCE_INLINE execute_status execute_csr_SCI(STATE_ACCESS a, uint64_t &pc,
 
 /// \brief Implementation of the CSRRSI instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_CSRRSI(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_CSRRSI(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "csrrsi");
     return execute_csr_SCI(a, pc, mcycle, insn, [](uint64_t csr, uint32_t rs1) -> uint64_t { return csr | rs1; });
 }
 
 /// \brief Implementation of the CSRRCI instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_CSRRCI(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_CSRRCI(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "csrrci");
     return execute_csr_SCI(a, pc, mcycle, insn, [](uint64_t csr, uint32_t rs1) -> uint64_t { return csr & ~rs1; });
 }
 
 /// \brief Implementation of the ECALL instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_ECALL(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_ECALL(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "ecall");
     auto prv = a.read_iprv();
     pc = raise_exception(a, pc, MCAUSE_ECALL_BASE + prv, 0);
@@ -2727,7 +2745,7 @@ static FORCE_INLINE execute_status execute_ECALL(STATE_ACCESS a, uint64_t &pc, u
 
 /// \brief Implementation of the EBREAK instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_EBREAK(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_EBREAK(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "ebreak");
     pc = raise_exception(a, pc, MCAUSE_BREAKPOINT, pc);
     return execute_status::failure;
@@ -2735,7 +2753,7 @@ static FORCE_INLINE execute_status execute_EBREAK(STATE_ACCESS a, uint64_t &pc,
 
 /// \brief Implementation of the SRET instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SRET(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SRET(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sret");
     auto prv = a.read_iprv();
     uint64_t mstatus = a.read_mstatus();
@@ -2765,7 +2783,7 @@ static FORCE_INLINE execute_status execute_SRET(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the MRET instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_MRET(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_MRET(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "mret");
     auto prv = a.read_iprv();
     if (unlikely(prv < PRV_M)) {
@@ -2797,7 +2815,7 @@ static FORCE_INLINE execute_status execute_MRET(STATE_ACCESS a, uint64_t &pc, ui
 /// \brief Implementation of the WFI instruction.
 /// \details This function is outlined to minimize host CPU code cache pressure.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_WFI(STATE_ACCESS a, uint64_t &pc, uint64_t &mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_WFI(const STATE_ACCESS a, uint64_t &pc, uint64_t &mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "wfi");
     auto status = execute_status::success;
     // Check privileges and do nothing else
@@ -2821,7 +2839,7 @@ static FORCE_INLINE execute_status execute_WFI(STATE_ACCESS a, uint64_t &pc, uin
 
 /// \brief Implementation of the FENCE instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FENCE(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FENCE(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     DUMP_STATS_INCR(a, "fence");
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fence");
     // Really do nothing
@@ -2830,7 +2848,7 @@ static FORCE_INLINE execute_status execute_FENCE(STATE_ACCESS a, uint64_t &pc, u
 
 /// \brief Implementation of the FENCE.I instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FENCE_I(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FENCE_I(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     DUMP_STATS_INCR(a, "fence.i");
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fence.i");
     // Really do nothing
@@ -2838,7 +2856,7 @@ static FORCE_INLINE execute_status execute_FENCE_I(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename STATE_ACCESS, typename F>
-static FORCE_INLINE execute_status execute_arithmetic(STATE_ACCESS a, uint64_t &pc, uint32_t insn, const F &f) {
+static FORCE_INLINE execute_status execute_arithmetic(const STATE_ACCESS a, uint64_t &pc, uint32_t insn, const F &f) {
     const uint32_t rd = insn_get_rd(insn);
     // Ensure rs1 and rs2 are loaded in order: do not nest with call to f() as
     // the order of evaluation of arguments in a function call is undefined.
@@ -2851,7 +2869,7 @@ static FORCE_INLINE execute_status execute_arithmetic(STATE_ACCESS a, uint64_t &
 
 /// \brief Implementation of the ADD instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_ADD(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_ADD(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "add");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -2865,7 +2883,7 @@ static FORCE_INLINE execute_status execute_ADD(STATE_ACCESS a, uint64_t &pc, uin
 
 /// \brief Implementation of the SUB instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SUB(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SUB(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sub");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -2879,7 +2897,7 @@ static FORCE_INLINE execute_status execute_SUB(STATE_ACCESS a, uint64_t &pc, uin
 
 /// \brief Implementation of the SLL instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SLL(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SLL(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sll");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -2890,7 +2908,7 @@ static FORCE_INLINE execute_status execute_SLL(STATE_ACCESS a, uint64_t &pc, uin
 
 /// \brief Implementation of the SLT instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SLT(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SLT(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "slt");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -2901,7 +2919,7 @@ static FORCE_INLINE execute_status execute_SLT(STATE_ACCESS a, uint64_t &pc, uin
 
 /// \brief Implementation of the SLTU instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SLTU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SLTU(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sltu");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -2911,7 +2929,7 @@ static FORCE_INLINE execute_status execute_SLTU(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the XOR instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_XOR(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_XOR(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "xor");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -2921,7 +2939,7 @@ static FORCE_INLINE execute_status execute_XOR(STATE_ACCESS a, uint64_t &pc, uin
 
 /// \brief Implementation of the SRL instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SRL(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SRL(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "srl");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -2932,7 +2950,7 @@ static FORCE_INLINE execute_status execute_SRL(STATE_ACCESS a, uint64_t &pc, uin
 
 /// \brief Implementation of the SRA instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SRA(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SRA(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sra");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -2944,7 +2962,7 @@ static FORCE_INLINE execute_status execute_SRA(STATE_ACCESS a, uint64_t &pc, uin
 
 /// \brief Implementation of the OR instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_OR(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_OR(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "or");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -2954,7 +2972,7 @@ static FORCE_INLINE execute_status execute_OR(STATE_ACCESS a, uint64_t &pc, uint
 
 /// \brief Implementation of the AND instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_AND(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_AND(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "and");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -2964,7 +2982,7 @@ static FORCE_INLINE execute_status execute_AND(STATE_ACCESS a, uint64_t &pc, uin
 
 /// \brief Implementation of the MUL instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_MUL(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_MUL(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "mul");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -2980,7 +2998,7 @@ static FORCE_INLINE execute_status execute_MUL(STATE_ACCESS a, uint64_t &pc, uin
 
 /// \brief Implementation of the MULH instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_MULH(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_MULH(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "mulh");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -2994,7 +3012,7 @@ static FORCE_INLINE execute_status execute_MULH(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the MULHSU instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_MULHSU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_MULHSU(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "mulhsu");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -3008,7 +3026,7 @@ static FORCE_INLINE execute_status execute_MULHSU(STATE_ACCESS a, uint64_t &pc,
 
 /// \brief Implementation of the MULHU instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_MULHU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_MULHU(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "mulhu");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -3020,7 +3038,7 @@ static FORCE_INLINE execute_status execute_MULHU(STATE_ACCESS a, uint64_t &pc, u
 
 /// \brief Implementation of the DIV instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_DIV(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_DIV(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "div");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -3040,7 +3058,7 @@ static FORCE_INLINE execute_status execute_DIV(STATE_ACCESS a, uint64_t &pc, uin
 
 /// \brief Implementation of the DIVU instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_DIVU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_DIVU(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "divu");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -3055,7 +3073,7 @@ static FORCE_INLINE execute_status execute_DIVU(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the REM instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_REM(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_REM(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "rem");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -3075,7 +3093,7 @@ static FORCE_INLINE execute_status execute_REM(STATE_ACCESS a, uint64_t &pc, uin
 
 /// \brief Implementation of the REMU instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_REMU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_REMU(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "remu");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -3089,7 +3107,7 @@ static FORCE_INLINE execute_status execute_REMU(STATE_ACCESS a, uint64_t &pc, ui
 }
 
 template <typename STATE_ACCESS, typename F>
-static FORCE_INLINE execute_status execute_arithmetic_immediate(STATE_ACCESS a, uint64_t &pc, uint32_t insn,
+static FORCE_INLINE execute_status execute_arithmetic_immediate(const STATE_ACCESS a, uint64_t &pc, uint32_t insn,
     const F &f) {
     const uint32_t rd = insn_get_rd(insn);
     const uint64_t rs1 = a.read_x(insn_get_rs1(insn));
@@ -3100,7 +3118,7 @@ static FORCE_INLINE execute_status execute_arithmetic_immediate(STATE_ACCESS a,
 
 /// \brief Implementation of the SRLI instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SRLI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SRLI(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "srli");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -3111,7 +3129,7 @@ static FORCE_INLINE execute_status execute_SRLI(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the SRAI instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SRAI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SRAI(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "srai");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -3123,7 +3141,7 @@ static FORCE_INLINE execute_status execute_SRAI(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the ADDI instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_ADDI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_ADDI(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "addi");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -3137,7 +3155,7 @@ static FORCE_INLINE execute_status execute_ADDI(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the SLTI instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SLTI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SLTI(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "slti");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -3148,7 +3166,7 @@ static FORCE_INLINE execute_status execute_SLTI(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the SLTIU instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SLTIU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SLTIU(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sltiu");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -3159,7 +3177,7 @@ static FORCE_INLINE execute_status execute_SLTIU(STATE_ACCESS a, uint64_t &pc, u
 
 /// \brief Implementation of the XORI instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_XORI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_XORI(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "xori");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -3169,7 +3187,7 @@ static FORCE_INLINE execute_status execute_XORI(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the ORI instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_ORI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_ORI(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "ori");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -3179,7 +3197,7 @@ static FORCE_INLINE execute_status execute_ORI(STATE_ACCESS a, uint64_t &pc, uin
 
 /// \brief Implementation of the ANDI instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_ANDI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_ANDI(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "andi");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -3189,7 +3207,7 @@ static FORCE_INLINE execute_status execute_ANDI(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the SLLI instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SLLI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SLLI(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     if (unlikely((insn & (0b111111 << 26)) != 0)) {
         return raise_illegal_insn_exception(a, pc, insn);
     }
@@ -3206,7 +3224,7 @@ static FORCE_INLINE execute_status execute_SLLI(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the ADDIW instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_ADDIW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_ADDIW(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "addiw");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -3220,7 +3238,7 @@ static FORCE_INLINE execute_status execute_ADDIW(STATE_ACCESS a, uint64_t &pc, u
 
 /// \brief Implementation of the SLLIW instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SLLIW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SLLIW(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     if (unlikely(insn_get_funct7(insn) != 0)) {
         return raise_illegal_insn_exception(a, pc, insn);
     }
@@ -3238,7 +3256,7 @@ static FORCE_INLINE execute_status execute_SLLIW(STATE_ACCESS a, uint64_t &pc, u
 
 /// \brief Implementation of the SRLIW instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SRLIW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SRLIW(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "srliw");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -3253,7 +3271,7 @@ static FORCE_INLINE execute_status execute_SRLIW(STATE_ACCESS a, uint64_t &pc, u
 
 /// \brief Implementation of the SRAIW instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SRAIW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SRAIW(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sraiw");
     // When rd=0 the instruction is a HINT, and we consider it as a soft yield when rs1 == 31
     if constexpr (rd_kind == rd_kind::x0) {
@@ -3272,7 +3290,7 @@ static FORCE_INLINE execute_status execute_SRAIW(STATE_ACCESS a, uint64_t &pc, u
 }
 
 template <typename T, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_S(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_S(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     const uint64_t vaddr = a.read_x(insn_get_rs1(insn));
     const int32_t imm = insn_S_get_imm(insn);
     const uint64_t val = a.read_x(insn_get_rs2(insn));
@@ -3288,34 +3306,34 @@ static FORCE_INLINE execute_status execute_S(STATE_ACCESS a, uint64_t &pc, uint6
 
 /// \brief Implementation of the SB instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SB(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SB(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sb");
     return execute_S<uint8_t>(a, pc, mcycle, insn);
 }
 
 /// \brief Implementation of the SH instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SH(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SH(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sh");
     return execute_S<uint16_t>(a, pc, mcycle, insn);
 }
 
 /// \brief Implementation of the SW instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SW(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SW(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sw");
     return execute_S<uint32_t>(a, pc, mcycle, insn);
 }
 
 /// \brief Implementation of the SD instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SD(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SD(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "sd");
     return execute_S<uint64_t>(a, pc, mcycle, insn);
 }
 
 template <typename T, rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_L(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_L(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     const uint64_t vaddr = a.read_x(insn_get_rs1(insn));
     const int32_t imm = insn_I_get_imm(insn);
     T val = 0;
@@ -3338,55 +3356,55 @@ static FORCE_INLINE execute_status execute_L(STATE_ACCESS a, uint64_t &pc, uint6
 
 /// \brief Implementation of the LB instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_LB(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_LB(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "lb");
     return execute_L<int8_t, rd_kind>(a, pc, mcycle, insn);
 }
 
 /// \brief Implementation of the LH instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_LH(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_LH(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "lh");
     return execute_L<int16_t, rd_kind>(a, pc, mcycle, insn);
 }
 
 /// \brief Implementation of the LW instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_LW(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_LW(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "lw");
     return execute_L<int32_t, rd_kind>(a, pc, mcycle, insn);
 }
 
 /// \brief Implementation of the LD instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_LD(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_LD(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "ld");
     return execute_L<int64_t, rd_kind>(a, pc, mcycle, insn);
 }
 
 /// \brief Implementation of the LBU instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_LBU(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_LBU(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "lbu");
     return execute_L<uint8_t, rd_kind>(a, pc, mcycle, insn);
 }
 
 /// \brief Implementation of the LHU instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_LHU(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_LHU(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "lhu");
     return execute_L<uint16_t, rd_kind>(a, pc, mcycle, insn);
 }
 
 /// \brief Implementation of the LWU instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_LWU(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_LWU(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "lwu");
     return execute_L<uint32_t, rd_kind>(a, pc, mcycle, insn);
 }
 
 template <typename STATE_ACCESS, typename F>
-static FORCE_INLINE execute_status execute_branch(STATE_ACCESS a, uint64_t &pc, uint32_t insn, const F &f) {
+static FORCE_INLINE execute_status execute_branch(const STATE_ACCESS a, uint64_t &pc, uint32_t insn, const F &f) {
     const uint64_t rs1 = a.read_x(insn_get_rs1(insn));
     const uint64_t rs2 = a.read_x(insn_get_rs2(insn));
     if (f(rs1, rs2)) {
@@ -3398,21 +3416,21 @@ static FORCE_INLINE execute_status execute_branch(STATE_ACCESS a, uint64_t &pc,
 
 /// \brief Implementation of the BEQ instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_BEQ(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_BEQ(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "beq");
     return execute_branch(a, pc, insn, [](uint64_t rs1, uint64_t rs2) -> bool { return rs1 == rs2; });
 }
 
 /// \brief Implementation of the BNE instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_BNE(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_BNE(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "bne");
     return execute_branch(a, pc, insn, [](uint64_t rs1, uint64_t rs2) -> bool { return rs1 != rs2; });
 }
 
 /// \brief Implementation of the BLT instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_BLT(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_BLT(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "blt");
     return execute_branch(a, pc, insn,
         [](uint64_t rs1, uint64_t rs2) -> bool { return static_cast<int64_t>(rs1) < static_cast<int64_t>(rs2); });
@@ -3420,7 +3438,7 @@ static FORCE_INLINE execute_status execute_BLT(STATE_ACCESS a, uint64_t &pc, uin
 
 /// \brief Implementation of the BGE instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_BGE(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_BGE(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "bge");
     return execute_branch(a, pc, insn,
         [](uint64_t rs1, uint64_t rs2) -> bool { return static_cast<int64_t>(rs1) >= static_cast<int64_t>(rs2); });
@@ -3428,21 +3446,21 @@ static FORCE_INLINE execute_status execute_BGE(STATE_ACCESS a, uint64_t &pc, uin
 
 /// \brief Implementation of the BLTU instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_BLTU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_BLTU(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "bltu");
     return execute_branch(a, pc, insn, [](uint64_t rs1, uint64_t rs2) -> bool { return rs1 < rs2; });
 }
 
 /// \brief Implementation of the BGEU instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_BGEU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_BGEU(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "bgeu");
     return execute_branch(a, pc, insn, [](uint64_t rs1, uint64_t rs2) -> bool { return rs1 >= rs2; });
 }
 
 /// \brief Implementation of the LUI instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_LUI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_LUI(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "lui");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -3454,7 +3472,7 @@ static FORCE_INLINE execute_status execute_LUI(STATE_ACCESS a, uint64_t &pc, uin
 
 /// \brief Implementation of the AUIPC instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_AUIPC(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_AUIPC(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "auipc");
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
@@ -3466,7 +3484,7 @@ static FORCE_INLINE execute_status execute_AUIPC(STATE_ACCESS a, uint64_t &pc, u
 
 /// \brief Implementation of the JAL instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_JAL(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_JAL(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "jal");
     const uint64_t new_pc = pc + insn_J_get_imm(insn);
     if constexpr (rd_kind == rd_kind::x0) {
@@ -3479,7 +3497,7 @@ static FORCE_INLINE execute_status execute_JAL(STATE_ACCESS a, uint64_t &pc, uin
 
 /// \brief Implementation of the JALR instruction.
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_JALR(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_JALR(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "jalr");
     const uint64_t val = pc + 4;
     const uint64_t new_pc =
@@ -3495,7 +3513,7 @@ static FORCE_INLINE execute_status execute_JALR(STATE_ACCESS a, uint64_t &pc, ui
 /// \brief Implementation of the SFENCE.VMA instruction.
 /// \details This function is outlined to minimize host CPU code cache pressure.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SFENCE_VMA(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SFENCE_VMA(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     // rs1 and rs2 are arbitrary, rest is set
     if (unlikely((insn & 0b11111110000000000111111111111111) != 0b00010010000000000000000001110011)) {
         return raise_illegal_insn_exception(a, pc, insn);
@@ -3548,7 +3566,7 @@ static FORCE_INLINE execute_status execute_SFENCE_VMA(STATE_ACCESS a, uint64_t &
 }
 
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SRLI_SRAI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SRLI_SRAI(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     // Use ifs instead of a switch to produce fewer branches for the most frequent instructions
     const auto funct7_sr1 = static_cast<insn_SRLI_SRAI_funct7_sr1>(insn_get_funct7_sr1(insn));
     if (funct7_sr1 == insn_SRLI_SRAI_funct7_sr1::SRLI) {
@@ -3561,7 +3579,7 @@ static FORCE_INLINE execute_status execute_SRLI_SRAI(STATE_ACCESS a, uint64_t &p
 }
 
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SRLIW_SRAIW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SRLIW_SRAIW(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     // Use ifs instead of a switch to produce fewer branches for the most frequent instructions
     const auto funct7 = static_cast<insn_SRLIW_SRAIW_funct7>(insn_get_funct7(insn));
     if (funct7 == insn_SRLIW_SRAIW_funct7::SRLIW) {
@@ -3574,7 +3592,7 @@ static FORCE_INLINE execute_status execute_SRLIW_SRAIW(STATE_ACCESS a, uint64_t
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_AMO_W(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_AMO_W(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     switch (static_cast<insn_AMO_funct7_sr2>(insn_get_funct7_sr2(insn))) {
         case insn_AMO_funct7_sr2::AMOADD:
             return execute_AMOADD_W(a, pc, mcycle, insn);
@@ -3604,7 +3622,7 @@ static FORCE_INLINE execute_status execute_AMO_W(STATE_ACCESS a, uint64_t &pc, u
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_AMO_D(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_AMO_D(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     switch (static_cast<insn_AMO_funct7_sr2>(insn_get_funct7_sr2(insn))) {
         case insn_AMO_funct7_sr2::AMOADD:
             return execute_AMOADD_D(a, pc, mcycle, insn);
@@ -3634,7 +3652,7 @@ static FORCE_INLINE execute_status execute_AMO_D(STATE_ACCESS a, uint64_t &pc, u
 }
 
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_ADD_MUL_SUB(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_ADD_MUL_SUB(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     // Use ifs instead of a switch to produce fewer branches for the most frequent instructions
     const auto funct7 = static_cast<insn_ADD_MUL_SUB_funct7>(insn_get_funct7(insn));
     if (funct7 == insn_ADD_MUL_SUB_funct7::ADD) {
@@ -3650,7 +3668,7 @@ static FORCE_INLINE execute_status execute_ADD_MUL_SUB(STATE_ACCESS a, uint64_t
 }
 
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SLL_MULH(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SLL_MULH(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     // Use ifs instead of a switch to produce fewer branches for the most frequent instructions
     const auto funct7 = static_cast<insn_SLL_MULH_funct7>(insn_get_funct7(insn));
     if (funct7 == insn_SLL_MULH_funct7::SLL) {
@@ -3663,7 +3681,7 @@ static FORCE_INLINE execute_status execute_SLL_MULH(STATE_ACCESS a, uint64_t &pc
 }
 
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SLT_MULHSU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SLT_MULHSU(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     // Use ifs instead of a switch to produce fewer branches for the most frequent instructions
     const auto funct7 = static_cast<insn_SLT_MULHSU_funct7>(insn_get_funct7(insn));
     if (funct7 == insn_SLT_MULHSU_funct7::SLT) {
@@ -3676,7 +3694,7 @@ static FORCE_INLINE execute_status execute_SLT_MULHSU(STATE_ACCESS a, uint64_t &
 }
 
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SLTU_MULHU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SLTU_MULHU(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     // Use ifs instead of a switch to produce fewer branches for the most frequent instructions
     const auto funct7 = static_cast<insn_SLTU_MULHU_funct7>(insn_get_funct7(insn));
     if (funct7 == insn_SLTU_MULHU_funct7::SLTU) {
@@ -3689,7 +3707,7 @@ static FORCE_INLINE execute_status execute_SLTU_MULHU(STATE_ACCESS a, uint64_t &
 }
 
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_XOR_DIV(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_XOR_DIV(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     // Use ifs instead of a switch to produce fewer branches for the most frequent instructions
     const auto funct7 = static_cast<insn_XOR_DIV_funct7>(insn_get_funct7(insn));
     if (funct7 == insn_XOR_DIV_funct7::XOR) {
@@ -3702,7 +3720,7 @@ static FORCE_INLINE execute_status execute_XOR_DIV(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SRL_DIVU_SRA(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SRL_DIVU_SRA(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     // Use ifs instead of a switch to produce fewer branches for the most frequent instructions
     const auto funct7 = static_cast<insn_SRL_DIVU_SRA_funct7>(insn_get_funct7(insn));
     if (funct7 == insn_SRL_DIVU_SRA_funct7::SRL) {
@@ -3718,7 +3736,7 @@ static FORCE_INLINE execute_status execute_SRL_DIVU_SRA(STATE_ACCESS a, uint64_t
 }
 
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_OR_REM(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_OR_REM(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     // Use ifs instead of a switch to produce fewer branches for the most frequent instructions
     const auto funct7 = static_cast<insn_OR_REM_funct7>(insn_get_funct7(insn));
     if (funct7 == insn_OR_REM_funct7::OR) {
@@ -3731,7 +3749,7 @@ static FORCE_INLINE execute_status execute_OR_REM(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_AND_REMU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_AND_REMU(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     // Use ifs instead of a switch to produce fewer branches for the most frequent instructions
     const auto funct7 = static_cast<insn_AND_REMU_funct7>(insn_get_funct7(insn));
     if (funct7 == insn_AND_REMU_funct7::AND) {
@@ -3744,7 +3762,7 @@ static FORCE_INLINE execute_status execute_AND_REMU(STATE_ACCESS a, uint64_t &pc
 }
 
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_ADDW_MULW_SUBW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_ADDW_MULW_SUBW(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     // Use ifs instead of a switch to produce fewer branches for the most frequent instructions
     const auto funct7 = static_cast<insn_ADDW_MULW_SUBW_funct7>(insn_get_funct7(insn));
     if (funct7 == insn_ADDW_MULW_SUBW_funct7::ADDW) {
@@ -3760,7 +3778,7 @@ static FORCE_INLINE execute_status execute_ADDW_MULW_SUBW(STATE_ACCESS a, uint64
 }
 
 template <rd_kind rd_kind, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_SRLW_DIVUW_SRAW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_SRLW_DIVUW_SRAW(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     // Use ifs instead of a switch to produce fewer branches for the most frequent instructions
     const auto funct7 = static_cast<insn_SRLW_DIVUW_SRAW_funct7>(insn_get_funct7(insn));
     if (funct7 == insn_SRLW_DIVUW_SRAW_funct7::SRLW) {
@@ -3776,7 +3794,8 @@ static FORCE_INLINE execute_status execute_SRLW_DIVUW_SRAW(STATE_ACCESS a, uint6
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_privileged(STATE_ACCESS a, uint64_t &pc, uint64_t &mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_privileged(const STATE_ACCESS a, uint64_t &pc, uint64_t &mcycle,
+    uint32_t insn) {
     switch (static_cast<insn_privileged>(insn)) {
         case insn_privileged::ECALL:
             return execute_ECALL(a, pc, insn);
@@ -3836,7 +3855,7 @@ static inline T float_unbox(uint64_t val) {
 }
 
 template <typename T, typename STATE_ACCESS, typename F>
-static FORCE_INLINE execute_status execute_float_ternary_op_rm(STATE_ACCESS a, uint64_t &pc, uint32_t insn,
+static FORCE_INLINE execute_status execute_float_ternary_op_rm(const STATE_ACCESS a, uint64_t &pc, uint32_t insn,
     const F &f) {
     const uint64_t fcsr = a.read_fcsr();
     // The rounding mode comes from the insn
@@ -3858,7 +3877,8 @@ static FORCE_INLINE execute_status execute_float_ternary_op_rm(STATE_ACCESS a, u
 }
 
 template <typename T, typename STATE_ACCESS, typename F>
-static FORCE_INLINE execute_status execute_float_binary_op_rm(STATE_ACCESS a, uint64_t &pc, uint32_t insn, const F &f) {
+static FORCE_INLINE execute_status execute_float_binary_op_rm(const STATE_ACCESS a, uint64_t &pc, uint32_t insn,
+    const F &f) {
     const uint64_t fcsr = a.read_fcsr();
     // The rounding mode comes from the insn
     const uint32_t rm = insn_get_rm(insn, fcsr);
@@ -3878,7 +3898,8 @@ static FORCE_INLINE execute_status execute_float_binary_op_rm(STATE_ACCESS a, ui
 }
 
 template <typename T, typename STATE_ACCESS, typename F>
-static FORCE_INLINE execute_status execute_float_unary_op_rm(STATE_ACCESS a, uint64_t &pc, uint32_t insn, const F &f) {
+static FORCE_INLINE execute_status execute_float_unary_op_rm(const STATE_ACCESS a, uint64_t &pc, uint32_t insn,
+    const F &f) {
     const uint64_t fcsr = a.read_fcsr();
     // Unary operation should have rs2 set to 0
     if (unlikely(insn_get_rs2(insn) != 0)) {
@@ -3901,7 +3922,7 @@ static FORCE_INLINE execute_status execute_float_unary_op_rm(STATE_ACCESS a, uin
 }
 
 template <typename T, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FS(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FS(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     const uint64_t vaddr = a.read_x(insn_get_rs1(insn));
     const int32_t imm = insn_S_get_imm(insn);
     // A narrower n-bit transfer out of the floating-point
@@ -3918,7 +3939,7 @@ static FORCE_INLINE execute_status execute_FS(STATE_ACCESS a, uint64_t &pc, uint
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FSW(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FSW(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fsw");
     // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((a.read_mstatus() & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
@@ -3928,7 +3949,7 @@ static FORCE_INLINE execute_status execute_FSW(STATE_ACCESS a, uint64_t &pc, uin
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FSD(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FSD(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fsd");
     // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((a.read_mstatus() & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
@@ -3938,7 +3959,7 @@ static FORCE_INLINE execute_status execute_FSD(STATE_ACCESS a, uint64_t &pc, uin
 }
 
 template <typename T, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FL(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FL(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     // Loads the float value from virtual memory
     const uint64_t vaddr = a.read_x(insn_get_rs1(insn));
     const int32_t imm = insn_I_get_imm(insn);
@@ -3954,7 +3975,7 @@ static FORCE_INLINE execute_status execute_FL(STATE_ACCESS a, uint64_t &pc, uint
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FLW(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FLW(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "flw");
     // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((a.read_mstatus() & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
@@ -3964,7 +3985,7 @@ static FORCE_INLINE execute_status execute_FLW(STATE_ACCESS a, uint64_t &pc, uin
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FLD(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FLD(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fld");
     // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((a.read_mstatus() & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
@@ -3974,7 +3995,7 @@ static FORCE_INLINE execute_status execute_FLD(STATE_ACCESS a, uint64_t &pc, uin
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FMADD_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FMADD_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmadd.s");
     return execute_float_ternary_op_rm<uint32_t>(a, pc, insn,
         [](uint32_t s1, uint32_t s2, uint32_t s3, uint32_t rm, uint32_t *fflags) -> uint32_t {
@@ -3983,7 +4004,7 @@ static FORCE_INLINE execute_status execute_FMADD_S(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FMADD_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FMADD_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmadd.d");
     return execute_float_ternary_op_rm<uint64_t>(a, pc, insn,
         [](uint64_t s1, uint64_t s2, uint64_t s3, uint32_t rm, uint32_t *fflags) -> uint64_t {
@@ -3992,7 +4013,7 @@ static FORCE_INLINE execute_status execute_FMADD_D(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FMADD(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FMADD(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((a.read_mstatus() & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
         return raise_illegal_insn_exception(a, pc, insn);
@@ -4008,7 +4029,7 @@ static FORCE_INLINE execute_status execute_FMADD(STATE_ACCESS a, uint64_t &pc, u
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FMSUB_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FMSUB_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmsub.s");
     return execute_float_ternary_op_rm<uint32_t>(a, pc, insn,
         [](uint32_t s1, uint32_t s2, uint32_t s3, uint32_t rm, uint32_t *fflags) -> uint32_t {
@@ -4017,7 +4038,7 @@ static FORCE_INLINE execute_status execute_FMSUB_S(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FMSUB_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FMSUB_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmsub.d");
     return execute_float_ternary_op_rm<uint64_t>(a, pc, insn,
         [](uint64_t s1, uint64_t s2, uint64_t s3, uint32_t rm, uint32_t *fflags) -> uint64_t {
@@ -4026,7 +4047,7 @@ static FORCE_INLINE execute_status execute_FMSUB_D(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FMSUB(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FMSUB(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((a.read_mstatus() & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
         return raise_illegal_insn_exception(a, pc, insn);
@@ -4042,7 +4063,7 @@ static FORCE_INLINE execute_status execute_FMSUB(STATE_ACCESS a, uint64_t &pc, u
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FNMADD_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FNMADD_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fnmadd.s");
     return execute_float_ternary_op_rm<uint32_t>(a, pc, insn,
         [](uint32_t s1, uint32_t s2, uint32_t s3, uint32_t rm, uint32_t *fflags) -> uint32_t {
@@ -4052,7 +4073,7 @@ static FORCE_INLINE execute_status execute_FNMADD_S(STATE_ACCESS a, uint64_t &pc
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FNMADD_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FNMADD_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fnmadd.d");
     return execute_float_ternary_op_rm<uint64_t>(a, pc, insn,
         [](uint64_t s1, uint64_t s2, uint64_t s3, uint32_t rm, uint32_t *fflags) -> uint64_t {
@@ -4062,7 +4083,7 @@ static FORCE_INLINE execute_status execute_FNMADD_D(STATE_ACCESS a, uint64_t &pc
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FNMADD(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FNMADD(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((a.read_mstatus() & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
         return raise_illegal_insn_exception(a, pc, insn);
@@ -4078,7 +4099,7 @@ static FORCE_INLINE execute_status execute_FNMADD(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FNMSUB_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FNMSUB_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fnmsub.s");
     return execute_float_ternary_op_rm<uint32_t>(a, pc, insn,
         [](uint32_t s1, uint32_t s2, uint32_t s3, uint32_t rm, uint32_t *fflags) -> uint32_t {
@@ -4087,7 +4108,7 @@ static FORCE_INLINE execute_status execute_FNMSUB_S(STATE_ACCESS a, uint64_t &pc
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FNMSUB_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FNMSUB_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fnmsub.d");
     return execute_float_ternary_op_rm<uint64_t>(a, pc, insn,
         [](uint64_t s1, uint64_t s2, uint64_t s3, uint32_t rm, uint32_t *fflags) -> uint64_t {
@@ -4096,7 +4117,7 @@ static FORCE_INLINE execute_status execute_FNMSUB_D(STATE_ACCESS a, uint64_t &pc
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FNMSUB(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FNMSUB(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((a.read_mstatus() & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
         return raise_illegal_insn_exception(a, pc, insn);
@@ -4112,7 +4133,7 @@ static FORCE_INLINE execute_status execute_FNMSUB(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FADD_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FADD_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fadd.s");
     return execute_float_binary_op_rm<uint32_t>(a, pc, insn,
         [](uint32_t s1, uint32_t s2, uint32_t rm, uint32_t *fflags) -> uint32_t {
@@ -4121,7 +4142,7 @@ static FORCE_INLINE execute_status execute_FADD_S(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FADD_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FADD_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fadd.d");
     return execute_float_binary_op_rm<uint64_t>(a, pc, insn,
         [](uint64_t s1, uint64_t s2, uint32_t rm, uint32_t *fflags) -> uint64_t {
@@ -4130,7 +4151,7 @@ static FORCE_INLINE execute_status execute_FADD_D(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FSUB_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FSUB_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fsub.s");
     return execute_float_binary_op_rm<uint32_t>(a, pc, insn,
         [](uint32_t s1, uint32_t s2, uint32_t rm, uint32_t *fflags) -> uint32_t {
@@ -4139,7 +4160,7 @@ static FORCE_INLINE execute_status execute_FSUB_S(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FSUB_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FSUB_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fsub.d");
     return execute_float_binary_op_rm<uint64_t>(a, pc, insn,
         [](uint64_t s1, uint64_t s2, uint32_t rm, uint32_t *fflags) -> uint64_t {
@@ -4148,7 +4169,7 @@ static FORCE_INLINE execute_status execute_FSUB_D(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FMUL_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FMUL_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmul.s");
     return execute_float_binary_op_rm<uint32_t>(a, pc, insn,
         [](uint32_t s1, uint32_t s2, uint32_t rm, uint32_t *fflags) -> uint32_t {
@@ -4157,7 +4178,7 @@ static FORCE_INLINE execute_status execute_FMUL_S(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FMUL_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FMUL_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmul.d");
     return execute_float_binary_op_rm<uint64_t>(a, pc, insn,
         [](uint64_t s1, uint64_t s2, uint32_t rm, uint32_t *fflags) -> uint64_t {
@@ -4166,7 +4187,7 @@ static FORCE_INLINE execute_status execute_FMUL_D(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FDIV_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FDIV_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fdiv.s");
     return execute_float_binary_op_rm<uint32_t>(a, pc, insn,
         [](uint32_t s1, uint32_t s2, uint32_t rm, uint32_t *fflags) -> uint32_t {
@@ -4175,7 +4196,7 @@ static FORCE_INLINE execute_status execute_FDIV_S(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FDIV_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FDIV_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fdiv.d");
     return execute_float_binary_op_rm<uint64_t>(a, pc, insn,
         [](uint64_t s1, uint64_t s2, uint32_t rm, uint32_t *fflags) -> uint64_t {
@@ -4184,7 +4205,7 @@ static FORCE_INLINE execute_status execute_FDIV_D(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename T, typename STATE_ACCESS, typename F>
-static FORCE_INLINE execute_status execute_FCLASS(STATE_ACCESS a, uint64_t &pc, uint32_t insn, const F &f) {
+static FORCE_INLINE execute_status execute_FCLASS(const STATE_ACCESS a, uint64_t &pc, uint32_t insn, const F &f) {
     const uint32_t rd = insn_get_rd(insn);
     if (unlikely(rd == 0)) {
         return advance_to_next_insn(a, pc);
@@ -4196,7 +4217,8 @@ static FORCE_INLINE execute_status execute_FCLASS(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename T, typename STATE_ACCESS, typename F>
-static FORCE_INLINE execute_status execute_float_binary_op(STATE_ACCESS a, uint64_t &pc, uint32_t insn, const F &f) {
+static FORCE_INLINE execute_status execute_float_binary_op(const STATE_ACCESS a, uint64_t &pc, uint32_t insn,
+    const F &f) {
     const uint64_t fcsr = a.read_fcsr();
     // We must always check if input operands are properly NaN-boxed.
     T s1 = float_unbox<T>(a.read_f(insn_get_rs1(insn)));
@@ -4210,7 +4232,7 @@ static FORCE_INLINE execute_status execute_float_binary_op(STATE_ACCESS a, uint6
 }
 
 template <typename T, typename STATE_ACCESS, typename F>
-static FORCE_INLINE execute_status execute_float_cmp_op(STATE_ACCESS a, uint64_t &pc, uint32_t insn, const F &f) {
+static FORCE_INLINE execute_status execute_float_cmp_op(const STATE_ACCESS a, uint64_t &pc, uint32_t insn, const F &f) {
     const uint64_t fcsr = a.read_fcsr();
     // We must always check if input operands are properly NaN-boxed.
     T s1 = float_unbox<T>(a.read_f(insn_get_rs1(insn)));
@@ -4228,7 +4250,7 @@ static FORCE_INLINE execute_status execute_float_cmp_op(STATE_ACCESS a, uint64_t
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FSGNJ_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FSGNJ_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fsgnj.s");
     return execute_float_binary_op<uint32_t>(a, pc, insn,
         [](uint32_t s1, uint32_t s2, const uint32_t * /*fflags*/) -> uint32_t {
@@ -4237,7 +4259,7 @@ static FORCE_INLINE execute_status execute_FSGNJ_S(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FSGNJN_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FSGNJN_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fsgnjn.s");
     return execute_float_binary_op<uint32_t>(a, pc, insn,
         [](uint32_t s1, uint32_t s2, const uint32_t * /*fflags*/) -> uint32_t {
@@ -4246,7 +4268,7 @@ static FORCE_INLINE execute_status execute_FSGNJN_S(STATE_ACCESS a, uint64_t &pc
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FSGNJX_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FSGNJX_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fsgnjx.s");
     return execute_float_binary_op<uint32_t>(a, pc, insn,
         [](uint32_t s1, uint32_t s2, const uint32_t * /*fflags*/) -> uint32_t {
@@ -4255,7 +4277,7 @@ static FORCE_INLINE execute_status execute_FSGNJX_S(STATE_ACCESS a, uint64_t &pc
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FSGN_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FSGN_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     switch (static_cast<insn_FSGN_funct3_000000000000>(insn_get_funct3_000000000000(insn))) {
         case insn_FSGN_funct3_000000000000::J:
             return execute_FSGNJ_S(a, pc, insn);
@@ -4269,7 +4291,7 @@ static FORCE_INLINE execute_status execute_FSGN_S(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FSGNJ_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FSGNJ_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fsgnj.d");
     return execute_float_binary_op<uint64_t>(a, pc, insn,
         [](uint64_t s1, uint64_t s2, const uint32_t * /*fflags*/) -> uint64_t {
@@ -4278,7 +4300,7 @@ static FORCE_INLINE execute_status execute_FSGNJ_D(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FSGNJN_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FSGNJN_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fsgnjn.d");
     return execute_float_binary_op<uint64_t>(a, pc, insn,
         [](uint64_t s1, uint64_t s2, const uint32_t * /*fflags*/) -> uint64_t {
@@ -4287,7 +4309,7 @@ static FORCE_INLINE execute_status execute_FSGNJN_D(STATE_ACCESS a, uint64_t &pc
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FSGNJX_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FSGNJX_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fsgnjx.d");
     return execute_float_binary_op<uint64_t>(a, pc, insn,
         [](uint64_t s1, uint64_t s2, const uint32_t * /*fflags*/) -> uint64_t {
@@ -4296,7 +4318,7 @@ static FORCE_INLINE execute_status execute_FSGNJX_D(STATE_ACCESS a, uint64_t &pc
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FSGN_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FSGN_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     switch (static_cast<insn_FSGN_funct3_000000000000>(insn_get_funct3_000000000000(insn))) {
         case insn_FSGN_funct3_000000000000::J:
             return execute_FSGNJ_D(a, pc, insn);
@@ -4310,21 +4332,21 @@ static FORCE_INLINE execute_status execute_FSGN_D(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FMIN_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FMIN_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmin.s");
     return execute_float_binary_op<uint32_t>(a, pc, insn,
         [](uint32_t s1, uint32_t s2, uint32_t *fflags) -> uint32_t { return i_sfloat32::min(s1, s2, fflags); });
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FMAX_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FMAX_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmax.s");
     return execute_float_binary_op<uint32_t>(a, pc, insn,
         [](uint32_t s1, uint32_t s2, uint32_t *fflags) -> uint32_t { return i_sfloat32::max(s1, s2, fflags); });
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FMINMAX_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FMINMAX_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     switch (static_cast<insn_FMIN_FMAX_funct3_000000000000>(insn_get_funct3_000000000000(insn))) {
         case insn_FMIN_FMAX_funct3_000000000000::MIN:
             return execute_FMIN_S(a, pc, insn);
@@ -4336,21 +4358,21 @@ static FORCE_INLINE execute_status execute_FMINMAX_S(STATE_ACCESS a, uint64_t &p
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FMIN_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FMIN_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmin.d");
     return execute_float_binary_op<uint64_t>(a, pc, insn,
         [](uint64_t s1, uint64_t s2, uint32_t *fflags) -> uint64_t { return i_sfloat64::min(s1, s2, fflags); });
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FMAX_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FMAX_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmax.d");
     return execute_float_binary_op<uint64_t>(a, pc, insn,
         [](uint64_t s1, uint64_t s2, uint32_t *fflags) -> uint64_t { return i_sfloat64::max(s1, s2, fflags); });
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FMINMAX_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FMINMAX_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     switch (static_cast<insn_FMIN_FMAX_funct3_000000000000>(insn_get_funct3_000000000000(insn))) {
         case insn_FMIN_FMAX_funct3_000000000000::MIN:
             return execute_FMIN_D(a, pc, insn);
@@ -4362,7 +4384,7 @@ static FORCE_INLINE execute_status execute_FMINMAX_D(STATE_ACCESS a, uint64_t &p
 }
 
 template <typename ST, typename DT, typename STATE_ACCESS, typename F>
-static FORCE_INLINE execute_status execute_FCVT_F_F(STATE_ACCESS a, uint64_t &pc, uint32_t insn, const F &f) {
+static FORCE_INLINE execute_status execute_FCVT_F_F(const STATE_ACCESS a, uint64_t &pc, uint32_t insn, const F &f) {
     const uint64_t fcsr = a.read_fcsr();
     // The rounding mode comes from the insn
     const uint32_t rm = insn_get_rm(insn, fcsr);
@@ -4382,7 +4404,7 @@ static FORCE_INLINE execute_status execute_FCVT_F_F(STATE_ACCESS a, uint64_t &pc
 }
 
 template <typename T, typename STATE_ACCESS, typename F>
-static FORCE_INLINE execute_status execute_FCVT_X_F(STATE_ACCESS a, uint64_t &pc, uint32_t insn, const F &f) {
+static FORCE_INLINE execute_status execute_FCVT_X_F(const STATE_ACCESS a, uint64_t &pc, uint32_t insn, const F &f) {
     const uint64_t fcsr = a.read_fcsr();
     // The rounding mode comes from the insn
     const uint32_t rm = insn_get_rm(insn, fcsr);
@@ -4404,7 +4426,7 @@ static FORCE_INLINE execute_status execute_FCVT_X_F(STATE_ACCESS a, uint64_t &pc
 }
 
 template <typename T, typename STATE_ACCESS, typename F>
-static FORCE_INLINE execute_status execute_FCVT_F_X(STATE_ACCESS a, uint64_t &pc, uint32_t insn, const F &f) {
+static FORCE_INLINE execute_status execute_FCVT_F_X(const STATE_ACCESS a, uint64_t &pc, uint32_t insn, const F &f) {
     const uint64_t fcsr = a.read_fcsr();
     // The rounding mode comes from the insn
     const uint32_t rm = insn_get_rm(insn, fcsr);
@@ -4423,7 +4445,7 @@ static FORCE_INLINE execute_status execute_FCVT_F_X(STATE_ACCESS a, uint64_t &pc
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FCVT_S_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FCVT_S_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.s.d");
     return execute_FCVT_F_F<uint64_t, uint32_t>(a, pc, insn,
         [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint32_t {
@@ -4432,7 +4454,7 @@ static FORCE_INLINE execute_status execute_FCVT_S_D(STATE_ACCESS a, uint64_t &pc
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FCVT_D_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FCVT_D_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.d.s");
     return execute_FCVT_F_F<uint32_t, uint64_t>(a, pc, insn,
         [](uint32_t s1, uint32_t /*rm*/, uint32_t *fflags) -> uint64_t {
@@ -4442,7 +4464,7 @@ static FORCE_INLINE execute_status execute_FCVT_D_S(STATE_ACCESS a, uint64_t &pc
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FSQRT_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FSQRT_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fsqrt.s");
     return execute_float_unary_op_rm<uint32_t>(a, pc, insn, [](uint32_t s1, uint32_t rm, uint32_t *fflags) -> uint32_t {
         return i_sfloat32::sqrt(s1, static_cast<FRM_modes>(rm), fflags);
@@ -4450,7 +4472,7 @@ static FORCE_INLINE execute_status execute_FSQRT_S(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FSQRT_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FSQRT_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fsqrt.d");
     return execute_float_unary_op_rm<uint64_t>(a, pc, insn, [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint64_t {
         return i_sfloat64::sqrt(s1, static_cast<FRM_modes>(rm), fflags);
@@ -4458,7 +4480,7 @@ static FORCE_INLINE execute_status execute_FSQRT_D(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FLE_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FLE_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fle.s");
     return execute_float_cmp_op<uint32_t>(a, pc, insn, [](uint32_t s1, uint32_t s2, uint32_t *fflags) -> uint64_t {
         return static_cast<uint64_t>(i_sfloat32::le(s1, s2, fflags));
@@ -4466,7 +4488,7 @@ static FORCE_INLINE execute_status execute_FLE_S(STATE_ACCESS a, uint64_t &pc, u
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FLT_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FLT_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "flt.s");
     return execute_float_cmp_op<uint32_t>(a, pc, insn, [](uint32_t s1, uint32_t s2, uint32_t *fflags) -> uint64_t {
         return static_cast<uint64_t>(i_sfloat32::lt(s1, s2, fflags));
@@ -4474,7 +4496,7 @@ static FORCE_INLINE execute_status execute_FLT_S(STATE_ACCESS a, uint64_t &pc, u
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FEQ_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FEQ_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "feq.s");
     return execute_float_cmp_op<uint32_t>(a, pc, insn, [](uint32_t s1, uint32_t s2, uint32_t *fflags) -> uint64_t {
         return static_cast<uint64_t>(i_sfloat32::eq(s1, s2, fflags));
@@ -4482,7 +4504,7 @@ static FORCE_INLINE execute_status execute_FEQ_S(STATE_ACCESS a, uint64_t &pc, u
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FCMP_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FCMP_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     switch (static_cast<insn_FCMP_funct3_000000000000>(insn_get_funct3_000000000000(insn))) {
         case insn_FCMP_funct3_000000000000::LT:
             return execute_FLT_S(a, pc, insn);
@@ -4496,7 +4518,7 @@ static FORCE_INLINE execute_status execute_FCMP_S(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FLE_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FLE_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fle.d");
     return execute_float_cmp_op<uint64_t>(a, pc, insn, [](uint64_t s1, uint64_t s2, uint32_t *fflags) -> uint64_t {
         return static_cast<uint64_t>(i_sfloat64::le(s1, s2, fflags));
@@ -4504,7 +4526,7 @@ static FORCE_INLINE execute_status execute_FLE_D(STATE_ACCESS a, uint64_t &pc, u
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FLT_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FLT_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "flt.d");
     return execute_float_cmp_op<uint64_t>(a, pc, insn, [](uint64_t s1, uint64_t s2, uint32_t *fflags) -> uint64_t {
         return static_cast<uint64_t>(i_sfloat64::lt(s1, s2, fflags));
@@ -4512,7 +4534,7 @@ static FORCE_INLINE execute_status execute_FLT_D(STATE_ACCESS a, uint64_t &pc, u
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FEQ_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FEQ_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "feq.d");
     return execute_float_cmp_op<uint64_t>(a, pc, insn, [](uint64_t s1, uint64_t s2, uint32_t *fflags) -> uint64_t {
         return static_cast<uint64_t>(i_sfloat64::eq(s1, s2, fflags));
@@ -4520,7 +4542,7 @@ static FORCE_INLINE execute_status execute_FEQ_D(STATE_ACCESS a, uint64_t &pc, u
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FCMP_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FCMP_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     switch (static_cast<insn_FCMP_funct3_000000000000>(insn_get_funct3_000000000000(insn))) {
         case insn_FCMP_funct3_000000000000::LT:
             return execute_FLT_D(a, pc, insn);
@@ -4534,7 +4556,7 @@ static FORCE_INLINE execute_status execute_FCMP_D(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FCVT_W_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FCVT_W_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.w.s");
     return execute_FCVT_X_F<uint32_t>(a, pc, insn, [](uint32_t s1, uint32_t rm, uint32_t *fflags) -> uint64_t {
         const auto val = i_sfloat32::cvt_f_i<int32_t>(s1, static_cast<FRM_modes>(rm), fflags);
@@ -4544,7 +4566,7 @@ static FORCE_INLINE execute_status execute_FCVT_W_S(STATE_ACCESS a, uint64_t &pc
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FCVT_WU_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FCVT_WU_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.wu.s");
     return execute_FCVT_X_F<uint32_t>(a, pc, insn, [](uint32_t s1, uint32_t rm, uint32_t *fflags) -> uint64_t {
         const auto val = i_sfloat32::cvt_f_i<uint32_t>(s1, static_cast<FRM_modes>(rm), fflags);
@@ -4554,7 +4576,7 @@ static FORCE_INLINE execute_status execute_FCVT_WU_S(STATE_ACCESS a, uint64_t &p
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FCVT_L_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FCVT_L_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.l.s");
     return execute_FCVT_X_F<uint32_t>(a, pc, insn, [](uint32_t s1, uint32_t rm, uint32_t *fflags) -> uint64_t {
         const auto val = i_sfloat32::cvt_f_i<int64_t>(s1, static_cast<FRM_modes>(rm), fflags);
@@ -4563,7 +4585,7 @@ static FORCE_INLINE execute_status execute_FCVT_L_S(STATE_ACCESS a, uint64_t &pc
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FCVT_LU_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FCVT_LU_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.lu.s");
     return execute_FCVT_X_F<uint32_t>(a, pc, insn, [](uint32_t s1, uint32_t rm, uint32_t *fflags) -> uint64_t {
         return i_sfloat32::cvt_f_i<uint64_t>(s1, static_cast<FRM_modes>(rm), fflags);
@@ -4571,7 +4593,7 @@ static FORCE_INLINE execute_status execute_FCVT_LU_S(STATE_ACCESS a, uint64_t &p
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FCVT_W_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FCVT_W_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.w.d");
     return execute_FCVT_X_F<uint64_t>(a, pc, insn, [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint64_t {
         const auto val = i_sfloat64::cvt_f_i<int32_t>(s1, static_cast<FRM_modes>(rm), fflags);
@@ -4581,7 +4603,7 @@ static FORCE_INLINE execute_status execute_FCVT_W_D(STATE_ACCESS a, uint64_t &pc
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FCVT_WU_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FCVT_WU_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.wu.d");
     return execute_FCVT_X_F<uint64_t>(a, pc, insn, [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint64_t {
         const auto val = i_sfloat64::cvt_f_i<uint32_t>(s1, static_cast<FRM_modes>(rm), fflags);
@@ -4591,7 +4613,7 @@ static FORCE_INLINE execute_status execute_FCVT_WU_D(STATE_ACCESS a, uint64_t &p
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FCVT_L_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FCVT_L_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.l.d");
     return execute_FCVT_X_F<uint64_t>(a, pc, insn, [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint64_t {
         const auto val = i_sfloat64::cvt_f_i<int64_t>(s1, static_cast<FRM_modes>(rm), fflags);
@@ -4600,7 +4622,7 @@ static FORCE_INLINE execute_status execute_FCVT_L_D(STATE_ACCESS a, uint64_t &pc
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FCVT_LU_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FCVT_LU_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.lu.d");
     return execute_FCVT_X_F<uint64_t>(a, pc, insn, [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint64_t {
         return i_sfloat64::cvt_f_i<uint64_t>(s1, static_cast<FRM_modes>(rm), fflags);
@@ -4608,7 +4630,7 @@ static FORCE_INLINE execute_status execute_FCVT_LU_D(STATE_ACCESS a, uint64_t &p
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FCVT_S_W(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FCVT_S_W(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.s.w");
     return execute_FCVT_F_X<uint32_t>(a, pc, insn, [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint32_t {
         return i_sfloat32::cvt_i_f(static_cast<int32_t>(s1), static_cast<FRM_modes>(rm), fflags);
@@ -4616,7 +4638,7 @@ static FORCE_INLINE execute_status execute_FCVT_S_W(STATE_ACCESS a, uint64_t &pc
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FCVT_S_WU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FCVT_S_WU(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.s.wu");
     return execute_FCVT_F_X<uint32_t>(a, pc, insn, [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint32_t {
         return i_sfloat32::cvt_i_f(static_cast<uint32_t>(s1), static_cast<FRM_modes>(rm), fflags);
@@ -4624,7 +4646,7 @@ static FORCE_INLINE execute_status execute_FCVT_S_WU(STATE_ACCESS a, uint64_t &p
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FCVT_S_L(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FCVT_S_L(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.s.l");
     return execute_FCVT_F_X<uint32_t>(a, pc, insn, [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint32_t {
         return i_sfloat32::cvt_i_f(static_cast<int64_t>(s1), static_cast<FRM_modes>(rm), fflags);
@@ -4632,7 +4654,7 @@ static FORCE_INLINE execute_status execute_FCVT_S_L(STATE_ACCESS a, uint64_t &pc
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FCVT_S_LU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FCVT_S_LU(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.s.lu");
     return execute_FCVT_F_X<uint32_t>(a, pc, insn, [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint32_t {
         return i_sfloat32::cvt_i_f(s1, static_cast<FRM_modes>(rm), fflags);
@@ -4640,7 +4662,7 @@ static FORCE_INLINE execute_status execute_FCVT_S_LU(STATE_ACCESS a, uint64_t &p
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FCVT_D_W(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FCVT_D_W(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.d.w");
     return execute_FCVT_F_X<uint64_t>(a, pc, insn, [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint64_t {
         return i_sfloat64::cvt_i_f(static_cast<int32_t>(s1), static_cast<FRM_modes>(rm), fflags);
@@ -4648,7 +4670,7 @@ static FORCE_INLINE execute_status execute_FCVT_D_W(STATE_ACCESS a, uint64_t &pc
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FCVT_D_WU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FCVT_D_WU(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.d.wu");
     return execute_FCVT_F_X<uint64_t>(a, pc, insn, [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint64_t {
         return i_sfloat64::cvt_i_f(static_cast<uint32_t>(s1), static_cast<FRM_modes>(rm), fflags);
@@ -4656,7 +4678,7 @@ static FORCE_INLINE execute_status execute_FCVT_D_WU(STATE_ACCESS a, uint64_t &p
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FCVT_D_L(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FCVT_D_L(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.d.l");
     return execute_FCVT_F_X<uint64_t>(a, pc, insn, [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint64_t {
         return i_sfloat64::cvt_i_f(static_cast<int64_t>(s1), static_cast<FRM_modes>(rm), fflags);
@@ -4664,7 +4686,7 @@ static FORCE_INLINE execute_status execute_FCVT_D_L(STATE_ACCESS a, uint64_t &pc
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FCVT_D_LU(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FCVT_D_LU(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fcvt.d.lu");
     return execute_FCVT_F_X<uint64_t>(a, pc, insn, [](uint64_t s1, uint32_t rm, uint32_t *fflags) -> uint64_t {
         return i_sfloat64::cvt_i_f(s1, static_cast<FRM_modes>(rm), fflags);
@@ -4672,7 +4694,7 @@ static FORCE_INLINE execute_status execute_FCVT_D_LU(STATE_ACCESS a, uint64_t &p
 }
 
 template <typename T, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FMV_F_X(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FMV_F_X(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     // Should have funct3 set to 0
     if (unlikely(insn_get_funct3(insn) != 0)) {
         return raise_illegal_insn_exception(a, pc, insn);
@@ -4685,25 +4707,25 @@ static FORCE_INLINE execute_status execute_FMV_F_X(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FMV_W_X(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FMV_W_X(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmv.w.x");
     return execute_FMV_F_X<uint32_t>(a, pc, insn);
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FMV_D_X(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FMV_D_X(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmv.d.x");
     return execute_FMV_F_X<uint64_t>(a, pc, insn);
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FCLASS_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FCLASS_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fclass.s");
     return execute_FCLASS<uint32_t>(a, pc, insn, [](uint32_t s1) -> uint64_t { return i_sfloat32::fclass(s1); });
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FMV_X_W(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FMV_X_W(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmv.x.w");
     const uint32_t rd = insn_get_rd(insn);
     if (unlikely(rd == 0)) {
@@ -4718,7 +4740,7 @@ static FORCE_INLINE execute_status execute_FMV_X_W(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FMV_FCLASS_S(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FMV_FCLASS_S(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     switch (static_cast<insn_FMV_FCLASS_funct3_000000000000>(insn_get_funct3_000000000000(insn))) {
         case insn_FMV_FCLASS_funct3_000000000000::FMV:
             return execute_FMV_X_W(a, pc, insn);
@@ -4730,13 +4752,13 @@ static FORCE_INLINE execute_status execute_FMV_FCLASS_S(STATE_ACCESS a, uint64_t
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FCLASS_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FCLASS_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fclass.d");
     return execute_FCLASS<uint64_t>(a, pc, insn, [](uint64_t s1) -> uint64_t { return i_sfloat64::fclass(s1); });
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FMV_X_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FMV_X_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, insn, "fmv.x.d");
     const uint32_t rd = insn_get_rd(insn);
     if (unlikely(rd == 0)) {
@@ -4748,7 +4770,7 @@ static FORCE_INLINE execute_status execute_FMV_X_D(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FMV_FCLASS_D(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FMV_FCLASS_D(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     switch (static_cast<insn_FMV_FCLASS_funct3_000000000000>(insn_get_funct3_000000000000(insn))) {
         case insn_FMV_FCLASS_funct3_000000000000::FMV:
             return execute_FMV_X_D(a, pc, insn);
@@ -4760,7 +4782,7 @@ static FORCE_INLINE execute_status execute_FMV_FCLASS_D(STATE_ACCESS a, uint64_t
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FCVT_FMV_FCLASS(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FCVT_FMV_FCLASS(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     switch (static_cast<insn_FD_funct7_rs2>(insn_get_funct7_rs2(insn))) {
         case insn_FD_funct7_rs2::FCVT_W_S:
             return execute_FCVT_W_S(a, pc, insn);
@@ -4812,7 +4834,7 @@ static FORCE_INLINE execute_status execute_FCVT_FMV_FCLASS(STATE_ACCESS a, uint6
 }
 
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_FD(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_FD(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((a.read_mstatus() & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
         return raise_illegal_insn_exception(a, pc, insn);
@@ -4856,8 +4878,8 @@ static FORCE_INLINE execute_status execute_FD(STATE_ACCESS a, uint64_t &pc, uint
 }
 
 template <typename T, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_L(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t rd, uint32_t rs1,
-    int32_t imm) {
+static FORCE_INLINE execute_status execute_C_L(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t rd,
+    uint32_t rs1, int32_t imm) {
     const uint64_t vaddr = a.read_x(rs1);
     T val = 0;
     if (unlikely(!read_virtual_memory<T>(a, pc, mcycle, vaddr + imm, &val))) {
@@ -4873,7 +4895,7 @@ static FORCE_INLINE execute_status execute_C_L(STATE_ACCESS a, uint64_t &pc, uin
 }
 
 template <typename T, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_S(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t rs2,
+static FORCE_INLINE execute_status execute_C_S(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t rs2,
     uint32_t rs1, int32_t imm) {
     const uint64_t vaddr = a.read_x(rs1);
     const uint64_t val = a.read_x(rs2);
@@ -4888,7 +4910,7 @@ static FORCE_INLINE execute_status execute_C_S(STATE_ACCESS a, uint64_t &pc, uin
 }
 
 template <typename T, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_FL(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t rd,
+static FORCE_INLINE execute_status execute_C_FL(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t rd,
     uint32_t rs1, int32_t imm) {
     // Loads the float value from virtual memory
     const uint64_t vaddr = a.read_x(rs1);
@@ -4903,7 +4925,7 @@ static FORCE_INLINE execute_status execute_C_FL(STATE_ACCESS a, uint64_t &pc, ui
 }
 
 template <typename T, typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_FS(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t rs2,
+static FORCE_INLINE execute_status execute_C_FS(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t rs2,
     uint32_t rs1, int32_t imm) {
     const uint64_t vaddr = a.read_x(rs1);
     // A narrower n-bit transfer out of the floating-point
@@ -4921,7 +4943,7 @@ static FORCE_INLINE execute_status execute_C_FS(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the C.ADDI4SPN instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_ADDI4SPN(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_ADDI4SPN(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.addi4spn");
     // rd cannot be zero (guaranteed by RISC-V spec design)
     const uint32_t rd = insn_get_CIW_CL_rd_CS_CA_rs2(insn);
@@ -4936,7 +4958,7 @@ static FORCE_INLINE execute_status execute_C_ADDI4SPN(STATE_ACCESS a, uint64_t &
 
 /// \brief Implementation of the C.FLD instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_FLD(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_FLD(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.fld");
     // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((a.read_mstatus() & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
@@ -4950,7 +4972,7 @@ static FORCE_INLINE execute_status execute_C_FLD(STATE_ACCESS a, uint64_t &pc, u
 
 /// \brief Implementation of the C.LW instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_LW(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_LW(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.lw");
     const uint32_t rd = insn_get_CIW_CL_rd_CS_CA_rs2(insn);
     const uint32_t rs1 = insn_get_CL_CS_CA_CB_rs1(insn);
@@ -4960,7 +4982,7 @@ static FORCE_INLINE execute_status execute_C_LW(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the C.LD instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_LD(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_LD(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.ld");
     const uint32_t rd = insn_get_CIW_CL_rd_CS_CA_rs2(insn);
     const uint32_t rs1 = insn_get_CL_CS_CA_CB_rs1(insn);
@@ -4970,7 +4992,7 @@ static FORCE_INLINE execute_status execute_C_LD(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the C.FSD instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_FSD(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_FSD(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.fsd");
     // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((a.read_mstatus() & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
@@ -4984,7 +5006,7 @@ static FORCE_INLINE execute_status execute_C_FSD(STATE_ACCESS a, uint64_t &pc, u
 
 /// \brief Implementation of the C.SW instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_SW(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_SW(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.sw");
     const uint32_t rs1 = insn_get_CL_CS_CA_CB_rs1(insn);
     const uint32_t rs2 = insn_get_CIW_CL_rd_CS_CA_rs2(insn);
@@ -4994,7 +5016,7 @@ static FORCE_INLINE execute_status execute_C_SW(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the C.SD instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_SD(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_SD(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.sd");
     const uint32_t rs1 = insn_get_CL_CS_CA_CB_rs1(insn);
     const uint32_t rs2 = insn_get_CIW_CL_rd_CS_CA_rs2(insn);
@@ -5004,7 +5026,7 @@ static FORCE_INLINE execute_status execute_C_SD(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the C.NOP instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_NOP(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_NOP(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.nop");
     // Really do nothing
     return advance_to_next_insn<2>(a, pc);
@@ -5012,7 +5034,7 @@ static FORCE_INLINE execute_status execute_C_NOP(STATE_ACCESS a, uint64_t &pc, u
 
 /// \brief Implementation of the C.ADDI instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_ADDI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_ADDI(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.addi");
     // rd cannot be zero (guaranteed by jump table)
     const uint32_t rd = insn_get_rd(insn);
@@ -5027,7 +5049,7 @@ static FORCE_INLINE execute_status execute_C_ADDI(STATE_ACCESS a, uint64_t &pc,
 
 /// \brief Implementation of the C.addiw instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_ADDIW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_ADDIW(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.addiw");
     // rd cannot be zero (guaranteed by jump table)
     const uint32_t rd = insn_get_rd(insn);
@@ -5041,7 +5063,7 @@ static FORCE_INLINE execute_status execute_C_ADDIW(STATE_ACCESS a, uint64_t &pc,
 
 /// \brief Implementation of the C.LI instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_LI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_LI(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.li");
     // rd cannot be zero (guaranteed by jump table)
     const uint32_t rd = insn_get_rd(insn);
@@ -5052,7 +5074,7 @@ static FORCE_INLINE execute_status execute_C_LI(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the C.ADDI16SP instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_ADDI16SP(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_ADDI16SP(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.addi16sp");
     // imm cannot be zero (guaranteed by the jump table)
     const int32_t imm = insn_get_C_ADDI16SP_imm(insn);
@@ -5065,7 +5087,7 @@ static FORCE_INLINE execute_status execute_C_ADDI16SP(STATE_ACCESS a, uint64_t &
 
 /// \brief Implementation of the C.LUI instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_LUI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_LUI(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.lui");
     // imm cannot be zero (guaranteed by the jump table)
     const int32_t imm = insn_get_C_LUI_imm(insn);
@@ -5077,7 +5099,7 @@ static FORCE_INLINE execute_status execute_C_LUI(STATE_ACCESS a, uint64_t &pc, u
 
 /// \brief Implementation of the C.SRLI instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_SRLI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_SRLI(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.srli");
     const uint32_t rs1 = insn_get_CL_CS_CA_CB_rs1(insn);
     // imm cannot be zero (guaranteed by the jump table)
@@ -5089,7 +5111,7 @@ static FORCE_INLINE execute_status execute_C_SRLI(STATE_ACCESS a, uint64_t &pc,
 
 /// \brief Implementation of the C.SRAI instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_SRAI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_SRAI(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.srai");
     const uint32_t rs1 = insn_get_CL_CS_CA_CB_rs1(insn);
     // imm cannot be zero (guaranteed by the jump table)
@@ -5101,7 +5123,7 @@ static FORCE_INLINE execute_status execute_C_SRAI(STATE_ACCESS a, uint64_t &pc,
 
 /// \brief Implementation of the C.ANDI instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_ANDI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_ANDI(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.andi");
     const uint32_t rs1 = insn_get_CL_CS_CA_CB_rs1(insn);
     const int32_t imm = insn_get_CI_CB_imm_se(insn);
@@ -5111,7 +5133,7 @@ static FORCE_INLINE execute_status execute_C_ANDI(STATE_ACCESS a, uint64_t &pc,
 }
 
 template <typename STATE_ACCESS, typename F>
-static FORCE_INLINE execute_status execute_C_arithmetic(STATE_ACCESS a, uint64_t &pc, uint32_t insn, const F &f) {
+static FORCE_INLINE execute_status execute_C_arithmetic(const STATE_ACCESS a, uint64_t &pc, uint32_t insn, const F &f) {
     // Ensure rs1 and rs2 are loaded in order: do not nest with call to f() as
     // the order of evaluation of arguments in a function call is undefined.
     const uint32_t rs1 = insn_get_CL_CS_CA_CB_rs1(insn);
@@ -5124,7 +5146,7 @@ static FORCE_INLINE execute_status execute_C_arithmetic(STATE_ACCESS a, uint64_t
 
 /// \brief Implementation of the C.SUB instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_SUB(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_SUB(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.sub");
     return execute_C_arithmetic(a, pc, insn, [](uint64_t rs1_value, uint64_t rs2_value) -> uint64_t {
         uint64_t val = 0;
@@ -5135,7 +5157,7 @@ static FORCE_INLINE execute_status execute_C_SUB(STATE_ACCESS a, uint64_t &pc, u
 
 /// \brief Implementation of the C.XOR instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_XOR(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_XOR(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.xor");
     return execute_C_arithmetic(a, pc, insn,
         [](uint64_t rs1_value, uint64_t rs2_value) -> uint64_t { return rs1_value ^ rs2_value; });
@@ -5143,7 +5165,7 @@ static FORCE_INLINE execute_status execute_C_XOR(STATE_ACCESS a, uint64_t &pc, u
 
 /// \brief Implementation of the C.OR instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_OR(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_OR(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.or");
     return execute_C_arithmetic(a, pc, insn,
         [](uint64_t rs1_value, uint64_t rs2_value) -> uint64_t { return rs1_value | rs2_value; });
@@ -5151,7 +5173,7 @@ static FORCE_INLINE execute_status execute_C_OR(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the C.AND instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_AND(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_AND(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.and");
     return execute_C_arithmetic(a, pc, insn,
         [](uint64_t rs1_value, uint64_t rs2_value) -> uint64_t { return rs1_value & rs2_value; });
@@ -5159,7 +5181,7 @@ static FORCE_INLINE execute_status execute_C_AND(STATE_ACCESS a, uint64_t &pc, u
 
 /// \brief Implementation of the C.SUBW instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_SUBW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_SUBW(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.subw");
     return execute_C_arithmetic(a, pc, insn, [](uint64_t rs1_value, uint64_t rs2_value) -> uint64_t {
         // Convert 64-bit to 32-bit
@@ -5173,7 +5195,7 @@ static FORCE_INLINE execute_status execute_C_SUBW(STATE_ACCESS a, uint64_t &pc,
 
 /// \brief Implementation of the C.ADDW instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_ADDW(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_ADDW(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.addw");
     return execute_C_arithmetic(a, pc, insn, [](uint64_t rs1_value, uint64_t rs2_value) -> uint64_t {
         // Discard upper 32 bits
@@ -5187,7 +5209,7 @@ static FORCE_INLINE execute_status execute_C_ADDW(STATE_ACCESS a, uint64_t &pc,
 
 /// \brief Implementation of the C_J instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_J(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_J(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.j");
     const uint64_t new_pc = pc + static_cast<uint64_t>(insn_get_C_J_imm(insn));
     return execute_jump(a, pc, new_pc);
@@ -5195,7 +5217,7 @@ static FORCE_INLINE execute_status execute_C_J(STATE_ACCESS a, uint64_t &pc, uin
 
 /// \brief Implementation of the C.BEQZ instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_BEQZ(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_BEQZ(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.beqz");
     const uint32_t rs1 = insn_get_CL_CS_CA_CB_rs1(insn);
     if (a.read_x(rs1) == 0) {
@@ -5208,7 +5230,7 @@ static FORCE_INLINE execute_status execute_C_BEQZ(STATE_ACCESS a, uint64_t &pc,
 
 /// \brief Implementation of the C.BNEZ instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_BNEZ(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_BNEZ(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.bnez");
     const uint32_t rs1 = insn_get_CL_CS_CA_CB_rs1(insn);
     if (a.read_x(rs1) != 0) {
@@ -5221,7 +5243,7 @@ static FORCE_INLINE execute_status execute_C_BNEZ(STATE_ACCESS a, uint64_t &pc,
 
 /// \brief Implementation of the C.SLLI instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_SLLI(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_SLLI(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.slli");
     // rd cannot be zero (guaranteed by jump table)
     const uint32_t rd = insn_get_rd(insn);
@@ -5234,7 +5256,7 @@ static FORCE_INLINE execute_status execute_C_SLLI(STATE_ACCESS a, uint64_t &pc,
 
 /// \brief Implementation of the C.FLDSP instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_FLDSP(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_FLDSP(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.fldsp");
     // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((a.read_mstatus() & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
@@ -5247,7 +5269,7 @@ static FORCE_INLINE execute_status execute_C_FLDSP(STATE_ACCESS a, uint64_t &pc,
 
 /// \brief Implementation of the C.LWSP instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_LWSP(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_LWSP(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.lwsp");
     // rd cannot be zero (guaranteed by jump table)
     const uint32_t rd = insn_get_rd(insn);
@@ -5257,7 +5279,7 @@ static FORCE_INLINE execute_status execute_C_LWSP(STATE_ACCESS a, uint64_t &pc,
 
 /// \brief Implementation of the C.LDSP instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_LDSP(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_LDSP(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.ldsp");
     // rd cannot be zero (guaranteed by jump table)
     const uint32_t rd = insn_get_rd(insn);
@@ -5267,7 +5289,7 @@ static FORCE_INLINE execute_status execute_C_LDSP(STATE_ACCESS a, uint64_t &pc,
 
 /// \brief Implementation of the C.JR instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_JR(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_JR(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.jr");
     // rs1 cannot be zero (guaranteed by the jump table)
     const uint32_t rs1 = insn_get_rd(insn);
@@ -5277,7 +5299,7 @@ static FORCE_INLINE execute_status execute_C_JR(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the C.MV instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_MV(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_MV(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.mv");
     // rd cannot be zero (guaranteed by the jump table)
     const uint32_t rd = insn_get_rd(insn);
@@ -5289,7 +5311,7 @@ static FORCE_INLINE execute_status execute_C_MV(STATE_ACCESS a, uint64_t &pc, ui
 
 /// \brief Implementation of the C.EBREAK instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_EBREAK(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_EBREAK(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.ebreak");
     pc = raise_exception(a, pc, MCAUSE_BREAKPOINT, pc);
     return advance_to_raised_exception(a, pc);
@@ -5297,7 +5319,7 @@ static FORCE_INLINE execute_status execute_C_EBREAK(STATE_ACCESS a, uint64_t &pc
 
 /// \brief Implementation of the C.JALR instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_JALR(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_JALR(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.jalr");
     const uint32_t rs1 = insn_get_rd(insn);
     const uint64_t new_pc = a.read_x(rs1) & ~static_cast<uint64_t>(1);
@@ -5308,7 +5330,7 @@ static FORCE_INLINE execute_status execute_C_JALR(STATE_ACCESS a, uint64_t &pc,
 
 /// \brief Implementation of the C.ADD instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_ADD(STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_ADD(const STATE_ACCESS a, uint64_t &pc, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.add");
     // rd cannot be zero (guaranteed by the jump table)
     const uint32_t rd = insn_get_rd(insn);
@@ -5323,7 +5345,7 @@ static FORCE_INLINE execute_status execute_C_ADD(STATE_ACCESS a, uint64_t &pc, u
 
 /// \brief Implementation of the C.FSDSP instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_FSDSP(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_FSDSP(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.fsdsp");
     // If FS is OFF, attempts to read or write the float state will cause an illegal instruction exception.
     if (unlikely((a.read_mstatus() & MSTATUS_FS_MASK) == MSTATUS_FS_OFF)) {
@@ -5336,7 +5358,7 @@ static FORCE_INLINE execute_status execute_C_FSDSP(STATE_ACCESS a, uint64_t &pc,
 
 /// \brief Implementation of the C.SWSP instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_SWSP(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_SWSP(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.swsp");
     const uint32_t rs2 = insn_get_CR_CSS_rs2(insn);
     const int32_t imm = insn_get_C_SWSP_imm(insn);
@@ -5345,7 +5367,7 @@ static FORCE_INLINE execute_status execute_C_SWSP(STATE_ACCESS a, uint64_t &pc,
 
 /// \brief Implementation of the C.SDSP instruction.
 template <typename STATE_ACCESS>
-static FORCE_INLINE execute_status execute_C_SDSP(STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
+static FORCE_INLINE execute_status execute_C_SDSP(const STATE_ACCESS a, uint64_t &pc, uint64_t mcycle, uint32_t insn) {
     [[maybe_unused]] auto note = dump_insn(a, pc, static_cast<uint16_t>(insn), "c.sdsp");
     const uint32_t rs2 = insn_get_CR_CSS_rs2(insn);
     const int32_t imm = insn_get_C_FSDSP_SDSP_imm(insn);
@@ -5368,7 +5390,7 @@ enum class fetch_status : int {
 /// \return Returns fetch_status::success if load succeeded, fetch_status::exception if it caused an exception.
 //          In that case, raise the exception.
 template <typename STATE_ACCESS>
-static FORCE_INLINE fetch_status fetch_translate_pc_slow(STATE_ACCESS a, uint64_t &pc, uint64_t vaddr,
+static FORCE_INLINE fetch_status fetch_translate_pc_slow(const STATE_ACCESS a, uint64_t &pc, uint64_t vaddr,
     i_state_access_fast_addr_t<STATE_ACCESS> &vp_offset, uint64_t &pma_index) {
     uint64_t paddr{};
     // Walk page table and obtain the physical address
@@ -5398,7 +5420,7 @@ static FORCE_INLINE fetch_status fetch_translate_pc_slow(STATE_ACCESS a, uint64_
 /// \return Returns fetch_status::success if load succeeded, fetch_status::exception if it caused an exception.
 //          In that case, raise the exception.
 template <typename STATE_ACCESS>
-static FORCE_INLINE fetch_status fetch_translate_pc(STATE_ACCESS a, uint64_t &pc, uint64_t vaddr,
+static FORCE_INLINE fetch_status fetch_translate_pc(const STATE_ACCESS a, uint64_t &pc, uint64_t vaddr,
     i_state_access_fast_addr_t<STATE_ACCESS> &vp_offset, uint64_t &pma_index) {
     // Try to perform the address translation via TLB first
     const uint64_t slot_index = tlb_slot_index(vaddr);
@@ -5425,8 +5447,8 @@ static FORCE_INLINE fetch_status fetch_translate_pc(STATE_ACCESS a, uint64_t &pc
 /// \return Returns fetch_status::success if load succeeded, fetch_status::exception if it caused an exception.
 //          In that case, raise the exception.
 template <typename STATE_ACCESS>
-static FORCE_INLINE fetch_status fetch_insn(STATE_ACCESS a, uint64_t &pc, uint32_t &insn, uint64_t &last_vaddr_page,
-    i_state_access_fast_addr_t<STATE_ACCESS> &last_vp_offset, uint64_t &last_pma_index) {
+static FORCE_INLINE fetch_status fetch_insn(const STATE_ACCESS a, uint64_t &pc, uint32_t &insn,
+    uint64_t &last_vaddr_page, i_state_access_fast_addr_t<STATE_ACCESS> &last_vp_offset, uint64_t &last_pma_index) {
     [[maybe_unused]] auto note = a.make_scoped_note("fetch_insn");
     i_state_access_fast_addr_t<STATE_ACCESS> faddr{0};
     const uint64_t pc_vaddr_page = tlb_addr_page(pc);
@@ -5484,7 +5506,7 @@ static FORCE_INLINE fetch_status fetch_insn(STATE_ACCESS a, uint64_t &pc, uint32
 
 /// \brief Checks that false brk is consistent with rest of state
 template <typename STATE_ACCESS>
-static void assert_no_brk([[maybe_unused]] STATE_ACCESS a) {
+static void assert_no_brk([[maybe_unused]] const STATE_ACCESS a) {
     assert(get_pending_irq_mask(a) == 0); // LCOV_EXCL_LINE
     assert(a.read_iflags_X() == 0);       // LCOV_EXCL_LINE
     assert(a.read_iflags_Y() == 0);       // LCOV_EXCL_LINE
@@ -5493,7 +5515,7 @@ static void assert_no_brk([[maybe_unused]] STATE_ACCESS a) {
 
 /// \brief Interpreter hot loop
 template <typename STATE_ACCESS>
-static NO_INLINE execute_status interpret_loop(STATE_ACCESS a, uint64_t mcycle_end, uint64_t mcycle) {
+static NO_INLINE execute_status interpret_loop(const STATE_ACCESS a, uint64_t mcycle_end, uint64_t mcycle) {
     // The interpret loop is constantly reading and modifying the pc and mcycle variables,
     // because of this care is taken to make them stack variables that are propagated across inline functions,
     // helping the C++ compiler optimize them into registers instead of stack variables when compiling,
@@ -6051,7 +6073,7 @@ static NO_INLINE execute_status interpret_loop(STATE_ACCESS a, uint64_t mcycle_e
 }
 
 template <typename STATE_ACCESS>
-interpreter_break_reason interpret(STATE_ACCESS a, uint64_t mcycle_end) {
+interpreter_break_reason interpret(const STATE_ACCESS a, uint64_t mcycle_end) {
     static_assert(__BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__, "code assumes little-endian byte ordering");
     static_assert(is_an_i_state_access_v<STATE_ACCESS>, "not an i_state_access");
     static_assert(is_an_i_accept_scoped_note_v<STATE_ACCESS>, "not an i_accept_scoped_notes");
diff --git a/src/is-pristine.h b/src/is-pristine.h
index 458d297fc..7f94c0384 100644
--- a/src/is-pristine.h
+++ b/src/is-pristine.h
@@ -28,7 +28,7 @@ namespace cartesi {
 /// \param length Memory length
 /// \details It's instead to be used in situations where length is equal or less than a page size.
 // NOLINTNEXTLINE(clang-diagnostic-unknown-attributes)
-static inline bool FORCE_OPTIMIZE_O3 is_pristine(const unsigned char *data, size_t length) {
+static inline bool is_pristine(const unsigned char *data, size_t length) {
     // This tight for loop has no branches, and is optimized to SIMD instructions in x86_64,
     // making it very fast to check if a given page is pristine.
     unsigned char bits = 0;
@@ -40,4 +40,4 @@ static inline bool FORCE_OPTIMIZE_O3 is_pristine(const unsigned char *data, size
 
 } // namespace cartesi
 
-#endif
\ No newline at end of file
+#endif
diff --git a/src/machine.cpp b/src/machine.cpp
index a57c0e0d2..d75c1e1f1 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -2326,7 +2326,7 @@ access_log machine::log_send_cmio_response(uint16_t reason, const unsigned char
     get_root_hash(root_hash_before);
     access_log log(log_type);
     // Call send_cmio_response  with the recording state accessor
-    record_send_cmio_state_access a(*this, log);
+    const record_send_cmio_state_access a(*this, log);
     {
         [[maybe_unused]] auto note = a.make_scoped_note("send_cmio_response");
         cartesi::send_cmio_response(a, reason, data, length);
@@ -2393,7 +2393,8 @@ access_log machine::log_reset_uarch(const access_log::type &log_type) {
 void machine::verify_reset_uarch(const hash_type &root_hash_before, const access_log &log,
     const hash_type &root_hash_after) {
     // Verify all intermediate state transitions
-    uarch_replay_state_access a(log, root_hash_before);
+    uarch_replay_state_access::context context{log, root_hash_before};
+    uarch_replay_state_access a(context);
     uarch_reset_state(a);
     a.finish();
     // Make sure the access log ends at the same root hash as the state
@@ -2415,7 +2416,7 @@ access_log machine::log_step_uarch(const access_log::type &log_type) {
     get_root_hash(root_hash_before);
     access_log log(log_type);
     // Call interpret with a logged state access object
-    uarch_record_state_access a(*this, log);
+    const uarch_record_state_access a(*this, log);
     {
         [[maybe_unused]] auto note = a.make_scoped_note("step");
         uarch_step(a);
@@ -2433,7 +2434,8 @@ extern template UArchStepStatus uarch_step(uarch_replay_state_access &a);
 void machine::verify_step_uarch(const hash_type &root_hash_before, const access_log &log,
     const hash_type &root_hash_after) {
     // Verify all intermediate state transitions
-    uarch_replay_state_access a(log, root_hash_before);
+    uarch_replay_state_access::context context{log, root_hash_before};
+    uarch_replay_state_access a(context);
     uarch_step(a);
     a.finish();
     // Make sure the access log ends at the same root hash as the state
@@ -2456,7 +2458,7 @@ uarch_interpreter_break_reason machine::run_uarch(uint64_t uarch_cycle_end) {
     if (m_us.ram.get_istart_E()) {
         throw std::runtime_error("microarchitecture RAM is not present");
     }
-    uarch_state_access a(*this);
+    const uarch_state_access a(*this);
     return uarch_interpret(a, uarch_cycle_end);
 }
 
diff --git a/src/record-send-cmio-state-access.h b/src/record-send-cmio-state-access.h
index cb3d933fb..03f09ea2f 100644
--- a/src/record-send-cmio-state-access.h
+++ b/src/record-send-cmio-state-access.h
@@ -119,7 +119,7 @@ class record_send_cmio_state_access :
     /// \param paligned Physical address of the word in the machine state (Must be aligned to a 64-bit word).
     /// \param val Value to write.
     /// \param text Textual description of the access.
-    void log_before_write(uint64_t paligned, uint64_t val, const char *text) {
+    void log_before_write(uint64_t paligned, uint64_t val, const char *text) const {
         static_assert(machine_merkle_tree::get_log2_word_size() >= log2_size_v<uint64_t>,
             "Merkle tree word size must be at least as large as a machine word");
         if ((paligned & (sizeof(uint64_t) - 1)) != 0) {
@@ -160,7 +160,7 @@ class record_send_cmio_state_access :
 
     /// \brief Updates the Merkle tree after the modification of a word in the machine state.
     /// \param paligned Physical address in the machine state, aligned to a 64-bit word.
-    void update_after_write(uint64_t paligned) {
+    void update_after_write(uint64_t paligned) const {
         assert((paligned & (sizeof(uint64_t) - 1)) == 0);
         [[maybe_unused]] const bool updated = m_m.update_merkle_tree_page(paligned);
         assert(updated);
@@ -171,14 +171,14 @@ class record_send_cmio_state_access :
     /// \param dest Reference to value before writing.
     /// \param val Value to write to \p dest.
     /// \param text Textual description of the access.
-    void log_before_write_write_and_update(uint64_t paligned, uint64_t &dest, uint64_t val, const char *text) {
+    void log_before_write_write_and_update(uint64_t paligned, uint64_t &dest, uint64_t val, const char *text) const {
         assert((paligned & (sizeof(uint64_t) - 1)) == 0);
         log_before_write(paligned, val, text);
         dest = val;
         update_after_write(paligned);
     }
 
-    void log_before_write_word_write_and_update(uint64_t paligned, bool &dest, bool val, const char *text) {
+    void log_before_write_word_write_and_update(uint64_t paligned, bool &dest, bool val, const char *text) const {
         auto dest64 = static_cast<uint64_t>(dest);
         log_before_write_write_and_update(paligned, dest64, static_cast<uint64_t>(val), text);
         dest = (dest64 != 0);
@@ -190,7 +190,7 @@ class record_send_cmio_state_access :
     // -----
     friend i_state_access<record_send_cmio_state_access>;
 
-    void do_write_iflags_Y(uint64_t val) {
+    void do_write_iflags_Y(uint64_t val) const {
         log_before_write_write_and_update(machine_reg_address(machine_reg::iflags_Y), m_m.get_state().iflags.Y, val,
             "iflags.Y");
     }
@@ -200,13 +200,13 @@ class record_send_cmio_state_access :
         return m_m.get_state().iflags.Y;
     }
 
-    void do_write_htif_fromhost(uint64_t val) {
+    void do_write_htif_fromhost(uint64_t val) const {
         log_before_write_write_and_update(machine_reg_address(machine_reg::htif_fromhost),
             m_m.get_state().htif.fromhost, val, "htif.fromhost");
     }
 
     void do_write_memory_with_padding(uint64_t paddr, const unsigned char *data, uint64_t data_length,
-        int write_length_log2_size) {
+        int write_length_log2_size) const {
         if ((paddr & (machine_merkle_tree::get_word_size() - 1)) != 0) {
             throw std::invalid_argument("paddr is not aligned to tree leaf size");
         }
@@ -275,15 +275,15 @@ class record_send_cmio_state_access :
     // -----
     friend i_accept_scoped_notes<record_send_cmio_state_access>;
 
-    void do_push_begin_bracket(const char *text) {
+    void do_push_begin_bracket(const char *text) const {
         m_log.push_begin_bracket(text);
     }
 
-    void do_push_end_bracket(const char *text) {
+    void do_push_end_bracket(const char *text) const {
         m_log.push_end_bracket(text);
     }
 
-    auto do_make_scoped_note(const char *text) {
+    auto do_make_scoped_note(const char *text) const {
         return scoped_note{*this, text};
     }
 };
diff --git a/src/record-step-state-access.h b/src/record-step-state-access.h
index 91c400a88..e5508497e 100644
--- a/src/record-step-state-access.h
+++ b/src/record-step-state-access.h
@@ -191,12 +191,12 @@ class record_step_state_access :
         return m_m.read_reg(reg);
     }
 
-    void log_write_reg(machine_reg reg, uint64_t val) {
+    void log_write_reg(machine_reg reg, uint64_t val) const {
         touch_page(machine_reg_address(reg));
         m_m.write_reg(reg, val);
     }
 
-    uint64_t log_read_tlb(TLB_set_index set_index, uint64_t slot_index, shadow_tlb_what what) {
+    uint64_t log_read_tlb(TLB_set_index set_index, uint64_t slot_index, shadow_tlb_what what) const {
         touch_page(shadow_tlb_get_abs_addr(set_index, slot_index, what));
         return m_m.read_shadow_tlb(set_index, slot_index, what);
     }
@@ -206,11 +206,11 @@ class record_step_state_access :
     // -----
     friend i_prefer_shadow_state<record_step_state_access>;
 
-    uint64_t do_read_shadow_state(shadow_state_what what) {
+    uint64_t do_read_shadow_state(shadow_state_what what) const {
         return log_read_reg(machine_reg_enum(what));
     }
 
-    void do_write_shadow_state(shadow_state_what what, uint64_t val) {
+    void do_write_shadow_state(shadow_state_what what, uint64_t val) const {
         log_write_reg(machine_reg_enum(what), val);
     }
 
@@ -228,14 +228,14 @@ class record_step_state_access :
     }
 
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    bool do_write_memory(uint64_t paddr, const unsigned char *data, uint64_t length) {
+    bool do_write_memory(uint64_t paddr, const unsigned char *data, uint64_t length) const {
         (void) paddr;
         (void) data;
         (void) length;
         throw std::runtime_error("unexpected call to record_step_state_access::write_memory");
     }
 
-    pma_entry &do_read_pma_entry(uint64_t index) {
+    pma_entry &do_read_pma_entry(uint64_t index) const {
         assert(index < PMA_MAX);
         // replay_step_state_access reconstructs a mock_pma_entry from the
         // corresponding istart and ilength fields in the shadow pmas
@@ -247,30 +247,30 @@ class record_step_state_access :
     }
 
     template <typename T, typename A>
-    void do_read_memory_word(host_addr haddr, uint64_t pma_index, T *pval) {
+    void do_read_memory_word(host_addr haddr, uint64_t pma_index, T *pval) const {
         touch_page(m_m.get_paddr(haddr, pma_index));
         *pval = aliased_aligned_read<T, A>(haddr);
     }
 
     template <typename T, typename A>
-    void do_write_memory_word(host_addr haddr, uint64_t pma_index, T val) {
+    void do_write_memory_word(host_addr haddr, uint64_t pma_index, T val) const {
         touch_page(m_m.get_paddr(haddr, pma_index));
         aliased_aligned_write<T, A>(haddr, val);
     }
 
     template <TLB_set_index SET>
-    uint64_t do_read_tlb_vaddr_page(uint64_t slot_index) {
+    uint64_t do_read_tlb_vaddr_page(uint64_t slot_index) const {
         return log_read_tlb(SET, slot_index, shadow_tlb_what::vaddr_page);
     }
 
     template <TLB_set_index SET>
-    uint64_t do_read_tlb_pma_index(uint64_t slot_index) {
+    uint64_t do_read_tlb_pma_index(uint64_t slot_index) const {
         return log_read_tlb(SET, slot_index, shadow_tlb_what::pma_index);
     }
 
     //??D This is still a bit too complicated for my taste
     template <TLB_set_index SET>
-    host_addr do_read_tlb_vp_offset(uint64_t slot_index) {
+    host_addr do_read_tlb_vp_offset(uint64_t slot_index) const {
         // During initialization, replay_step_state_access translates all vp_offset to corresponding vh_offset
         // At deinitialization, it translates them back
         // To do that, it needs the corresponding paddr_page = vaddr_page + vp_offset, and page data itself
@@ -294,7 +294,7 @@ class record_step_state_access :
 
     //??D This is still a bit too complicated for my taste
     template <TLB_set_index SET>
-    void do_write_tlb(uint64_t slot_index, uint64_t vaddr_page, host_addr vh_offset, uint64_t pma_index) {
+    void do_write_tlb(uint64_t slot_index, uint64_t vaddr_page, host_addr vh_offset, uint64_t pma_index) const {
         // During initialization, replay_step_state_access translates all vp_offset to corresponding vh_offset
         // At deinitialization, it translates them back
         // To do that, it needs the corresponding paddr_page = vaddr_page + vp_offset, and page data itself
@@ -320,12 +320,12 @@ class record_step_state_access :
         return m_m.get_host_addr(paddr, pma_index);
     }
 
-    void do_mark_dirty_page(host_addr haddr, uint64_t pma_index) {
+    void do_mark_dirty_page(host_addr haddr, uint64_t pma_index) const {
         // this is a noop in replay_step_state_access, so we do nothing else
         m_m.mark_dirty_page(haddr, pma_index);
     }
 
-    void do_putchar(uint8_t c) { // NOLINT(readability-convert-member-functions-to-static)
+    void do_putchar(uint8_t c) const { // NOLINT(readability-convert-member-functions-to-static)
         os_putchar(c);
     }
 
diff --git a/src/replay-send-cmio-state-access.h b/src/replay-send-cmio-state-access.h
index 51b411d80..d9b2d1e59 100644
--- a/src/replay-send-cmio-state-access.h
+++ b/src/replay-send-cmio-state-access.h
@@ -131,7 +131,7 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
     /// \param log2_size Log2 of access size.
     /// \param text Textual description of the access.
     /// \returns Value read.
-    uint64_t check_read(uint64_t paligned, const char *text) {
+    uint64_t check_read(uint64_t paligned, const char *text) const {
         static_assert(machine_merkle_tree::get_log2_word_size() >= log2_size_v<uint64_t>,
             "Merkle tree word size must be at least as large as a machine word");
         if ((paligned & (sizeof(uint64_t) - 1)) != 0) {
@@ -187,7 +187,7 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
     /// aligned to a 64-bit word.
     /// \param word Word value to write.
     /// \param text Textual description of the access.
-    void check_write(uint64_t paligned, uint64_t word, const char *text) {
+    void check_write(uint64_t paligned, uint64_t word, const char *text) const {
         static_assert(machine_merkle_tree::get_log2_word_size() >= log2_size_v<uint64_t>,
             "Merkle tree word size must be at least as large as a machine word");
         if ((paligned & (sizeof(uint64_t) - 1)) != 0) {
@@ -273,22 +273,20 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
         m_context.next_access++;
     }
 
-    void do_push_bracket(bracket_type & /*type*/, const char * /*text*/) {}
-
-    void do_write_iflags_Y(uint64_t val) {
+    void do_write_iflags_Y(uint64_t val) const {
         check_write(machine_reg_address(machine_reg::iflags_Y), val, "iflags.Y");
     }
 
-    uint64_t do_read_iflags_Y() {
+    uint64_t do_read_iflags_Y() const {
         return check_read(machine_reg_address(machine_reg::iflags_Y), "iflags.Y");
     }
 
-    void do_write_htif_fromhost(uint64_t val) {
+    void do_write_htif_fromhost(uint64_t val) const {
         check_write(machine_reg_address(machine_reg::htif_fromhost), val, "htif.fromhost");
     }
 
     void do_write_memory_with_padding(uint64_t paddr, const unsigned char *data, uint64_t data_length,
-        int write_length_log2_size) {
+        int write_length_log2_size) const {
         hasher_type hasher{};
         if (data == nullptr) {
             throw std::invalid_argument("data is null");
diff --git a/src/replay-step-state-access.h b/src/replay-step-state-access.h
index 38d0f1469..ace83f7fc 100644
--- a/src/replay-step-state-access.h
+++ b/src/replay-step-state-access.h
@@ -403,17 +403,17 @@ class replay_step_state_access :
     //??D we should probably optimize access to the shadow so it doesn't perform a translation every time
     // We can do this by caching the vh_offset trasnslation of the processor shadow page. This is easy if
     // static_assert(sizeof(shadow_state) <= PMA_PAGE_SIZE, "shadow state must fit in single page");
-    void check_write_reg(machine_reg reg, uint64_t val) {
+    void check_write_reg(machine_reg reg, uint64_t val) const {
         const auto haddr = do_get_faddr(machine_reg_address(reg));
         aliased_aligned_write<uint64_t>(haddr, val);
     }
 
-    uint64_t read_pma_istart(uint64_t index) {
+    uint64_t read_pma_istart(uint64_t index) const {
         const auto haddr = do_get_faddr(shadow_pmas_get_pma_abs_addr(index, shadow_pmas_what::istart));
         return aliased_aligned_read<uint64_t>(haddr);
     }
 
-    uint64_t read_pma_ilength(uint64_t index) {
+    uint64_t read_pma_ilength(uint64_t index) const {
         const auto haddr = do_get_faddr(shadow_pmas_get_pma_abs_addr(index, shadow_pmas_what::ilength));
         return aliased_aligned_read<uint64_t>(haddr);
     }
@@ -423,11 +423,11 @@ class replay_step_state_access :
     // -----
     friend i_prefer_shadow_state<replay_step_state_access>;
 
-    uint64_t do_read_shadow_state(shadow_state_what what) {
+    uint64_t do_read_shadow_state(shadow_state_what what) const {
         return check_read_reg(machine_reg_enum(what));
     }
 
-    void do_write_shadow_state(shadow_state_what what, uint64_t val) {
+    void do_write_shadow_state(shadow_state_what what, uint64_t val) const {
         check_write_reg(machine_reg_enum(what), val);
     }
 
@@ -449,7 +449,7 @@ class replay_step_state_access :
     }
 
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    bool do_read_memory(uint64_t paddr, const unsigned char *data, uint64_t length) {
+    bool do_read_memory(uint64_t paddr, const unsigned char *data, uint64_t length) const {
         (void) paddr;
         (void) data;
         (void) length;
@@ -457,14 +457,14 @@ class replay_step_state_access :
     }
 
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    bool do_write_memory(uint64_t paddr, const unsigned char *data, uint64_t length) {
+    bool do_write_memory(uint64_t paddr, const unsigned char *data, uint64_t length) const {
         (void) paddr;
         (void) data;
         (void) length;
         return false;
     }
 
-    mock_pma_entry &do_read_pma_entry(uint64_t index) {
+    mock_pma_entry &do_read_pma_entry(uint64_t index) const {
         assert(index < PMA_MAX);
         // record_step_state_access will have recorded the access to istart and
         // ilength in its implementation of read_pma_entry.
@@ -481,54 +481,54 @@ class replay_step_state_access :
     }
 
     template <typename T, typename A>
-    void do_read_memory_word(host_addr haddr, uint64_t /* pma_index */, T *pval) {
+    void do_read_memory_word(host_addr haddr, uint64_t /* pma_index */, T *pval) const {
         *pval = aliased_aligned_read<T, A>(haddr);
     }
 
     template <typename T, typename A>
-    void do_write_memory_word(host_addr haddr, uint64_t /* pma_index */, T val) {
+    void do_write_memory_word(host_addr haddr, uint64_t /* pma_index */, T val) const {
         aliased_aligned_write<T, A>(haddr, val);
     }
 
     template <typename TYPE>
-    auto check_read_tlb(TLB_set_index set_index, uint64_t slot_index, shadow_tlb_what what) {
+    auto check_read_tlb(TLB_set_index set_index, uint64_t slot_index, shadow_tlb_what what) const {
         const auto haddr = do_get_faddr(shadow_tlb_get_abs_addr(set_index, slot_index, what));
         return aliased_aligned_read<TYPE>(haddr);
     }
 
     template <TLB_set_index SET>
-    uint64_t do_read_tlb_vaddr_page(uint64_t slot_index) {
+    uint64_t do_read_tlb_vaddr_page(uint64_t slot_index) const {
         return check_read_tlb<uint64_t>(SET, slot_index, shadow_tlb_what::vaddr_page);
     }
 
     template <TLB_set_index SET>
-    host_addr do_read_tlb_vp_offset(uint64_t slot_index) {
+    host_addr do_read_tlb_vp_offset(uint64_t slot_index) const {
         return check_read_tlb<host_addr>(SET, slot_index, shadow_tlb_what::vp_offset);
     }
 
     template <TLB_set_index SET>
-    uint64_t do_read_tlb_pma_index(uint64_t slot_index) {
+    uint64_t do_read_tlb_pma_index(uint64_t slot_index) const {
         return check_read_tlb<uint64_t>(SET, slot_index, shadow_tlb_what::pma_index);
     }
 
     template <typename TYPE>
-    auto check_write_tlb(TLB_set_index set_index, uint64_t slot_index, shadow_tlb_what what, TYPE val) {
+    auto check_write_tlb(TLB_set_index set_index, uint64_t slot_index, shadow_tlb_what what, TYPE val) const {
         const auto haddr = do_get_faddr(shadow_tlb_get_abs_addr(set_index, slot_index, what));
         aliased_aligned_write<TYPE>(haddr, val);
     }
 
     template <TLB_set_index SET>
-    void do_write_tlb(uint64_t slot_index, uint64_t vaddr_page, host_addr vh_offset, uint64_t pma_index) {
+    void do_write_tlb(uint64_t slot_index, uint64_t vaddr_page, host_addr vh_offset, uint64_t pma_index) const {
         check_write_tlb(SET, slot_index, shadow_tlb_what::vaddr_page, vaddr_page);
         check_write_tlb(SET, slot_index, shadow_tlb_what::vp_offset, vh_offset);
         check_write_tlb(SET, slot_index, shadow_tlb_what::pma_index, pma_index);
     }
 
-    void do_putchar(uint8_t /*c*/) { // NOLINT(readability-convert-member-functions-to-static)
-        ;                            // do nothing
+    void do_putchar(uint8_t /*c*/) const { // NOLINT(readability-convert-member-functions-to-static)
+        ;                                  // do nothing
     }
 
-    void do_mark_dirty_page(host_addr /* haddr */, uint64_t /* pma_index */) {
+    void do_mark_dirty_page(host_addr /* haddr */, uint64_t /* pma_index */) const {
         // this is a noop since we have no host machine
     }
 
diff --git a/src/state-access.h b/src/state-access.h
index 8c8317640..0bae8585b 100644
--- a/src/state-access.h
+++ b/src/state-access.h
@@ -86,7 +86,7 @@ class state_access :
         return m_m.get_state().x[i];
     }
 
-    void do_write_x(int i, uint64_t val) {
+    void do_write_x(int i, uint64_t val) const {
         assert(i != 0);
         m_m.get_state().x[i] = val;
     }
@@ -95,7 +95,7 @@ class state_access :
         return m_m.get_state().f[i];
     }
 
-    void do_write_f(int i, uint64_t val) {
+    void do_write_f(int i, uint64_t val) const {
         m_m.get_state().f[i] = val;
     }
 
@@ -103,7 +103,7 @@ class state_access :
         return m_m.get_state().pc;
     }
 
-    void do_write_pc(uint64_t val) {
+    void do_write_pc(uint64_t val) const {
         m_m.get_state().pc = val;
     }
 
@@ -111,7 +111,7 @@ class state_access :
         return m_m.get_state().fcsr;
     }
 
-    void do_write_fcsr(uint64_t val) {
+    void do_write_fcsr(uint64_t val) const {
         m_m.get_state().fcsr = val;
     }
 
@@ -119,7 +119,7 @@ class state_access :
         return m_m.get_state().icycleinstret;
     }
 
-    void do_write_icycleinstret(uint64_t val) {
+    void do_write_icycleinstret(uint64_t val) const {
         m_m.get_state().icycleinstret = val;
     }
 
@@ -139,7 +139,7 @@ class state_access :
         return m_m.get_state().mcycle;
     }
 
-    void do_write_mcycle(uint64_t val) {
+    void do_write_mcycle(uint64_t val) const {
         m_m.get_state().mcycle = val;
     }
 
@@ -147,7 +147,7 @@ class state_access :
         return m_m.get_state().mstatus;
     }
 
-    void do_write_mstatus(uint64_t val) {
+    void do_write_mstatus(uint64_t val) const {
         m_m.get_state().mstatus = val;
     }
 
@@ -155,7 +155,7 @@ class state_access :
         return m_m.get_state().menvcfg;
     }
 
-    void do_write_menvcfg(uint64_t val) {
+    void do_write_menvcfg(uint64_t val) const {
         m_m.get_state().menvcfg = val;
     }
 
@@ -163,7 +163,7 @@ class state_access :
         return m_m.get_state().mtvec;
     }
 
-    void do_write_mtvec(uint64_t val) {
+    void do_write_mtvec(uint64_t val) const {
         m_m.get_state().mtvec = val;
     }
 
@@ -171,7 +171,7 @@ class state_access :
         return m_m.get_state().mscratch;
     }
 
-    void do_write_mscratch(uint64_t val) {
+    void do_write_mscratch(uint64_t val) const {
         m_m.get_state().mscratch = val;
     }
 
@@ -179,7 +179,7 @@ class state_access :
         return m_m.get_state().mepc;
     }
 
-    void do_write_mepc(uint64_t val) {
+    void do_write_mepc(uint64_t val) const {
         m_m.get_state().mepc = val;
     }
 
@@ -187,7 +187,7 @@ class state_access :
         return m_m.get_state().mcause;
     }
 
-    void do_write_mcause(uint64_t val) {
+    void do_write_mcause(uint64_t val) const {
         m_m.get_state().mcause = val;
     }
 
@@ -195,7 +195,7 @@ class state_access :
         return m_m.get_state().mtval;
     }
 
-    void do_write_mtval(uint64_t val) {
+    void do_write_mtval(uint64_t val) const {
         m_m.get_state().mtval = val;
     }
 
@@ -203,7 +203,7 @@ class state_access :
         return m_m.get_state().misa;
     }
 
-    void do_write_misa(uint64_t val) {
+    void do_write_misa(uint64_t val) const {
         m_m.get_state().misa = val;
     }
 
@@ -211,7 +211,7 @@ class state_access :
         return m_m.get_state().mie;
     }
 
-    void do_write_mie(uint64_t val) {
+    void do_write_mie(uint64_t val) const {
         m_m.get_state().mie = val;
     }
 
@@ -219,7 +219,7 @@ class state_access :
         return m_m.get_state().mip;
     }
 
-    void do_write_mip(uint64_t val) {
+    void do_write_mip(uint64_t val) const {
         m_m.get_state().mip = val;
     }
 
@@ -227,7 +227,7 @@ class state_access :
         return m_m.get_state().medeleg;
     }
 
-    void do_write_medeleg(uint64_t val) {
+    void do_write_medeleg(uint64_t val) const {
         m_m.get_state().medeleg = val;
     }
 
@@ -235,7 +235,7 @@ class state_access :
         return m_m.get_state().mideleg;
     }
 
-    void do_write_mideleg(uint64_t val) {
+    void do_write_mideleg(uint64_t val) const {
         m_m.get_state().mideleg = val;
     }
 
@@ -243,7 +243,7 @@ class state_access :
         return m_m.get_state().mcounteren;
     }
 
-    void do_write_mcounteren(uint64_t val) {
+    void do_write_mcounteren(uint64_t val) const {
         m_m.get_state().mcounteren = val;
     }
 
@@ -251,7 +251,7 @@ class state_access :
         return m_m.get_state().senvcfg;
     }
 
-    void do_write_senvcfg(uint64_t val) {
+    void do_write_senvcfg(uint64_t val) const {
         m_m.get_state().senvcfg = val;
     }
 
@@ -259,7 +259,7 @@ class state_access :
         return m_m.get_state().stvec;
     }
 
-    void do_write_stvec(uint64_t val) {
+    void do_write_stvec(uint64_t val) const {
         m_m.get_state().stvec = val;
     }
 
@@ -267,7 +267,7 @@ class state_access :
         return m_m.get_state().sscratch;
     }
 
-    void do_write_sscratch(uint64_t val) {
+    void do_write_sscratch(uint64_t val) const {
         m_m.get_state().sscratch = val;
     }
 
@@ -275,7 +275,7 @@ class state_access :
         return m_m.get_state().sepc;
     }
 
-    void do_write_sepc(uint64_t val) {
+    void do_write_sepc(uint64_t val) const {
         m_m.get_state().sepc = val;
     }
 
@@ -283,7 +283,7 @@ class state_access :
         return m_m.get_state().scause;
     }
 
-    void do_write_scause(uint64_t val) {
+    void do_write_scause(uint64_t val) const {
         m_m.get_state().scause = val;
     }
 
@@ -291,7 +291,7 @@ class state_access :
         return m_m.get_state().stval;
     }
 
-    void do_write_stval(uint64_t val) {
+    void do_write_stval(uint64_t val) const {
         m_m.get_state().stval = val;
     }
 
@@ -299,7 +299,7 @@ class state_access :
         return m_m.get_state().satp;
     }
 
-    void do_write_satp(uint64_t val) {
+    void do_write_satp(uint64_t val) const {
         m_m.get_state().satp = val;
     }
 
@@ -307,7 +307,7 @@ class state_access :
         return m_m.get_state().scounteren;
     }
 
-    void do_write_scounteren(uint64_t val) {
+    void do_write_scounteren(uint64_t val) const {
         m_m.get_state().scounteren = val;
     }
 
@@ -315,7 +315,7 @@ class state_access :
         return m_m.get_state().ilrsc;
     }
 
-    void do_write_ilrsc(uint64_t val) {
+    void do_write_ilrsc(uint64_t val) const {
         m_m.get_state().ilrsc = val;
     }
 
@@ -323,7 +323,7 @@ class state_access :
         return m_m.get_state().iprv;
     }
 
-    void do_write_iprv(uint64_t val) {
+    void do_write_iprv(uint64_t val) const {
         m_m.get_state().iprv = val;
     }
 
@@ -331,7 +331,7 @@ class state_access :
         return m_m.get_state().iflags.X;
     }
 
-    void do_write_iflags_X(uint64_t val) {
+    void do_write_iflags_X(uint64_t val) const {
         m_m.get_state().iflags.X = val;
     }
 
@@ -339,7 +339,7 @@ class state_access :
         return m_m.get_state().iflags.Y;
     }
 
-    void do_write_iflags_Y(uint64_t val) {
+    void do_write_iflags_Y(uint64_t val) const {
         m_m.get_state().iflags.Y = val;
     }
 
@@ -347,7 +347,7 @@ class state_access :
         return m_m.get_state().iflags.H;
     }
 
-    void do_write_iflags_H(uint64_t val) {
+    void do_write_iflags_H(uint64_t val) const {
         m_m.get_state().iflags.H = val;
     }
 
@@ -355,7 +355,7 @@ class state_access :
         return m_m.get_state().iunrep;
     }
 
-    void do_write_iunrep(uint64_t val) {
+    void do_write_iunrep(uint64_t val) const {
         m_m.get_state().iunrep = val;
     }
 
@@ -363,7 +363,7 @@ class state_access :
         return m_m.get_state().clint.mtimecmp;
     }
 
-    void do_write_clint_mtimecmp(uint64_t val) {
+    void do_write_clint_mtimecmp(uint64_t val) const {
         m_m.get_state().clint.mtimecmp = val;
     }
 
@@ -371,7 +371,7 @@ class state_access :
         return m_m.get_state().plic.girqpend;
     }
 
-    void do_write_plic_girqpend(uint64_t val) {
+    void do_write_plic_girqpend(uint64_t val) const {
         m_m.get_state().plic.girqpend = val;
     }
 
@@ -379,7 +379,7 @@ class state_access :
         return m_m.get_state().plic.girqsrvd;
     }
 
-    void do_write_plic_girqsrvd(uint64_t val) {
+    void do_write_plic_girqsrvd(uint64_t val) const {
         m_m.get_state().plic.girqsrvd = val;
     }
 
@@ -387,7 +387,7 @@ class state_access :
         return m_m.get_state().htif.fromhost;
     }
 
-    void do_write_htif_fromhost(uint64_t val) {
+    void do_write_htif_fromhost(uint64_t val) const {
         m_m.get_state().htif.fromhost = val;
     }
 
@@ -395,7 +395,7 @@ class state_access :
         return m_m.get_state().htif.tohost;
     }
 
-    void do_write_htif_tohost(uint64_t val) {
+    void do_write_htif_tohost(uint64_t val) const {
         m_m.get_state().htif.tohost = val;
     }
 
@@ -422,7 +422,7 @@ class state_access :
         }
     }
 
-    bool do_write_memory(uint64_t paddr, const unsigned char *data, uint64_t length) {
+    bool do_write_memory(uint64_t paddr, const unsigned char *data, uint64_t length) const {
         //??(edubart): Treating exceptions here is not ideal, we should probably
         // move write_memory() method implementation inside state access later
         try {
@@ -433,14 +433,14 @@ class state_access :
         }
     }
 
-    pma_entry &do_read_pma_entry(uint64_t index) {
+    pma_entry &do_read_pma_entry(uint64_t index) const {
         assert(index < PMA_MAX);
         // NOLINTNEXTLINE(bugprone-narrowing-conversions)
         return m_m.get_state().pmas[static_cast<int>(index)];
     }
 
     void do_write_memory_with_padding(uint64_t paddr, const unsigned char *data, uint64_t data_length,
-        int write_length_log2_size) {
+        int write_length_log2_size) const {
         if (data == nullptr) {
             throw std::runtime_error("data is null");
         }
@@ -455,32 +455,32 @@ class state_access :
     }
 
     template <typename T, typename A = T>
-    void do_read_memory_word(host_addr haddr, uint64_t /* pma_index */, T *pval) {
+    void do_read_memory_word(host_addr haddr, uint64_t /* pma_index */, T *pval) const {
         *pval = aliased_aligned_read<T, A>(haddr);
     }
 
     template <typename T, typename A = T>
-    void do_write_memory_word(host_addr haddr, uint64_t /* pma_index */, T val) {
+    void do_write_memory_word(host_addr haddr, uint64_t /* pma_index */, T val) const {
         aliased_aligned_write<T, A>(haddr, val);
     }
 
     template <TLB_set_index SET>
-    uint64_t do_read_tlb_vaddr_page(uint64_t slot_index) {
+    uint64_t do_read_tlb_vaddr_page(uint64_t slot_index) const {
         return m_m.get_state().tlb.hot[SET][slot_index].vaddr_page;
     }
 
     template <TLB_set_index SET>
-    host_addr do_read_tlb_vp_offset(uint64_t slot_index) {
+    host_addr do_read_tlb_vp_offset(uint64_t slot_index) const {
         return m_m.get_state().tlb.hot[SET][slot_index].vh_offset;
     }
 
     template <TLB_set_index SET>
-    uint64_t do_read_tlb_pma_index(uint64_t slot_index) {
+    uint64_t do_read_tlb_pma_index(uint64_t slot_index) const {
         return m_m.get_state().tlb.cold[SET][slot_index].pma_index;
     }
 
     template <TLB_set_index SET>
-    void do_write_tlb(uint64_t slot_index, uint64_t vaddr_page, host_addr vh_offset, uint64_t pma_index) {
+    void do_write_tlb(uint64_t slot_index, uint64_t vaddr_page, host_addr vh_offset, uint64_t pma_index) const {
         m_m.write_tlb(SET, slot_index, vaddr_page, vh_offset, pma_index);
     }
 
@@ -488,12 +488,12 @@ class state_access :
         return m_m.get_host_addr(paddr, pma_index);
     }
 
-    void do_mark_dirty_page(host_addr haddr, uint64_t pma_index) {
+    void do_mark_dirty_page(host_addr haddr, uint64_t pma_index) const {
         m_m.mark_dirty_page(haddr, pma_index);
     }
 
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    void do_putchar(uint8_t c) {
+    void do_putchar(uint8_t c) const {
         os_putchar(c);
     }
 
@@ -507,16 +507,16 @@ class state_access :
     // -----
     friend i_interactive_state_access<state_access>;
 
-    NO_INLINE auto do_poll_external_interrupts(uint64_t mcycle, uint64_t mcycle_max) {
+    NO_INLINE auto do_poll_external_interrupts(uint64_t mcycle, uint64_t mcycle_max) const {
         return m_m.poll_external_interrupts(mcycle, mcycle_max);
     }
 
-    bool do_get_soft_yield() {
+    bool do_get_soft_yield() const {
         return m_m.get_state().soft_yield;
     }
 
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    int do_getchar() {
+    int do_getchar() const {
         os_poll_tty(0);
         return os_getchar();
     }
@@ -526,15 +526,15 @@ class state_access :
     // -----
     friend i_accept_counters<state_access>;
 
-    void do_increment_counter(const char *name, const char *domain) {
+    void do_increment_counter(const char *name, const char *domain) const {
         m_m.increment_counter(name, domain);
     }
 
-    uint64_t do_read_counter(const char *name, const char *domain) {
+    uint64_t do_read_counter(const char *name, const char *domain) const {
         return m_m.read_counter(name, domain);
     }
 
-    void do_write_counter(uint64_t val, const char *name, const char *domain) {
+    void do_write_counter(uint64_t val, const char *name, const char *domain) const {
         m_m.write_counter(val, name, domain);
     }
 };
diff --git a/src/uarch-interpret.cpp b/src/uarch-interpret.cpp
index 4dcfa9c68..8f9e77308 100644
--- a/src/uarch-interpret.cpp
+++ b/src/uarch-interpret.cpp
@@ -24,9 +24,9 @@
 namespace cartesi {
 
 // Declaration of explicit instantiation in module uarch-step.cpp
-extern template UArchStepStatus uarch_step(uarch_state_access &a);
+extern template UArchStepStatus uarch_step(const uarch_state_access a);
 
-uarch_interpreter_break_reason uarch_interpret(uarch_state_access &a, uint64_t cycle_end) {
+uarch_interpreter_break_reason uarch_interpret(const uarch_state_access a, uint64_t cycle_end) {
     uint64_t cycle = a.read_uarch_cycle();
     if (cycle_end < cycle) {
         throw std::invalid_argument{"uarch_cycle is past"};
diff --git a/src/uarch-interpret.h b/src/uarch-interpret.h
index 295822394..03abd1050 100644
--- a/src/uarch-interpret.h
+++ b/src/uarch-interpret.h
@@ -27,7 +27,7 @@ class uarch_state_access;
 enum class uarch_interpreter_break_reason : int { reached_target_cycle, uarch_halted };
 
 // Run the microarchitecture interpreter until cycle hits a target or a fixed point is reached
-uarch_interpreter_break_reason uarch_interpret(uarch_state_access &a, uint64_t uarch_cycle_end);
+uarch_interpreter_break_reason uarch_interpret(uarch_state_access a, uint64_t uarch_cycle_end);
 
 } // namespace cartesi
 
diff --git a/src/uarch-record-state-access.h b/src/uarch-record-state-access.h
index 05aacf599..0a32243fd 100644
--- a/src/uarch-record-state-access.h
+++ b/src/uarch-record-state-access.h
@@ -73,7 +73,7 @@ class uarch_record_state_access :
     /// \brief Constructor from machine and uarch states.
     /// \param m Reference to machine state.
     /// \param log Reference to log.
-    explicit uarch_record_state_access(machine &m, access_log &log) : m_m(m), m_log(log) {
+    uarch_record_state_access(machine &m, access_log &log) : m_m(m), m_log(log) {
         ;
     }
 
@@ -165,7 +165,7 @@ class uarch_record_state_access :
     }
 
     template <typename WRITE_UPDATE_F>
-    void log_write_access(uint64_t paddr, int log2_size, WRITE_UPDATE_F write_and_update, const char *text) {
+    void log_write_access(uint64_t paddr, int log2_size, WRITE_UPDATE_F write_and_update, const char *text) const {
         access a;
         log_access_type(a, access_type::write);
         log_access_range(a, paddr, log2_size);
@@ -190,7 +190,7 @@ class uarch_record_state_access :
         log_access(std::move(a), text);
     }
 
-    void log_write_reg_access(machine_reg reg, uint64_t val) {
+    void log_write_reg_access(machine_reg reg, uint64_t val) const {
         log_write_access(
             machine_reg_address(reg), log2_size_v<uint64_t>,
             [this, reg, val]() {
@@ -211,7 +211,7 @@ class uarch_record_state_access :
         return log_read_reg_access(machine_reg_enum(what));
     }
 
-    void do_write_shadow_uarch_state(shadow_uarch_state_what what, uint64_t val) {
+    void do_write_shadow_uarch_state(shadow_uarch_state_what what, uint64_t val) const {
         log_write_reg_access(machine_reg_enum(what), val);
     }
 
@@ -224,7 +224,7 @@ class uarch_record_state_access :
         return log_read_word_access(paddr, machine::get_what_name(paddr));
     }
 
-    void do_write_word(uint64_t paddr, uint64_t val) {
+    void do_write_word(uint64_t paddr, uint64_t val) const {
         log_write_access(
             paddr, log2_size_v<uint64_t>,
             [this, paddr, val]() {
@@ -237,7 +237,7 @@ class uarch_record_state_access :
     }
 
     void do_write_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset,
-        uint64_t pma_index) {
+        uint64_t pma_index) const {
         const auto slot_paddr = shadow_tlb_get_abs_addr(set_index, slot_index);
         log_write_access(
             slot_paddr, SHADOW_TLB_SLOT_LOG2_SIZE,
@@ -259,7 +259,7 @@ class uarch_record_state_access :
             "shadow TLB slot must fill at least an entire Merkle tree word");
     }
 
-    void do_reset_uarch() {
+    void do_reset_uarch() const {
         //??D I'd like to add an static_assert or some other guard mechanism to
         // guarantee that uarch.ram and uarch.shadow are alone in the entire
         // span of their common Merkle tree parent node
@@ -276,11 +276,11 @@ class uarch_record_state_access :
     }
 
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    void do_putchar(uint8_t c) {
+    void do_putchar(uint8_t c) const {
         os_putchar(c);
     }
 
-    void do_mark_dirty_page(uint64_t paddr, uint64_t pma_index) {
+    void do_mark_dirty_page(uint64_t paddr, uint64_t pma_index) const {
         // Forward to machine and no need to log
         m_m.mark_dirty_page(paddr, pma_index);
     }
@@ -295,15 +295,15 @@ class uarch_record_state_access :
     // -----
     friend i_accept_scoped_notes<uarch_record_state_access>;
 
-    void do_push_begin_bracket(const char *text) {
+    void do_push_begin_bracket(const char *text) const {
         m_log.push_begin_bracket(text);
     }
 
-    void do_push_end_bracket(const char *text) {
+    void do_push_end_bracket(const char *text) const {
         m_log.push_end_bracket(text);
     }
 
-    auto do_make_scoped_note(const char *text) {
+    auto do_make_scoped_note(const char *text) const {
         return scoped_note{*this, text};
     }
 
diff --git a/src/uarch-replay-state-access.h b/src/uarch-replay-state-access.h
index 8c266830e..091a31967 100644
--- a/src/uarch-replay-state-access.h
+++ b/src/uarch-replay-state-access.h
@@ -51,45 +51,42 @@ class uarch_replay_state_access :
     using hasher_type = tree_type::hasher_type;
     using proof_type = tree_type::proof_type;
 
-    ///< Access log generated by step
-    const std::vector<access> &m_accesses; // NOLINT(cppcoreguidelines-avoid-const-or-ref-data-members)
-    ///< Next access
-    unsigned m_next_access{};
+public:
+    struct context {
+        /// \brief Constructor replay_send_cmio_state_access context
+        /// \param log Access log to be replayed
+        /// \param initial_hash Initial root hash
+        context(const access_log &log, machine_merkle_tree::hash_type initial_hash) :
+            accesses(log.get_accesses()),
+            root_hash(initial_hash) {
+            ;
+        }
+        const std::vector<access> &accesses; // NOLINT(cppcoreguidelines-avoid-const-or-ref-data-members)
+        ///< Index of next access to ne consumed
+        unsigned int next_access{};
+        ///< Root hash before next access
+        machine_merkle_tree::hash_type root_hash;
+        ///< Hasher needed to verify proofs
+        machine_merkle_tree::hasher_type hasher;
+    };
 
-    ///< Root hash before next access
-    hash_type m_root_hash;
-    ///< Hasher needed to verify proofs
-    hasher_type m_hasher;
+private:
+    context &m_context; // NOLINT(cppcoreguidelines-avoid-const-or-ref-data-members)
 
 public:
     /// \brief Constructor from log of word accesses.
-    /// \param log Access log to be replayed
-    /// \param initial_hash  Initial root hash
-    explicit uarch_replay_state_access(const access_log &log, const hash_type &initial_hash) :
-        m_accesses(log.get_accesses()),
-        m_root_hash{initial_hash} {
+    explicit uarch_replay_state_access(uarch_replay_state_access::context &context) : m_context{context} {
         ;
     }
 
-    /// \brief No copy constructor
-    uarch_replay_state_access(const uarch_replay_state_access &) = delete;
-    /// \brief No copy assignment
-    uarch_replay_state_access &operator=(const uarch_replay_state_access &) = delete;
-    /// \brief No move constructor
-    uarch_replay_state_access(uarch_replay_state_access &&) = delete;
-    /// \brief No move assignment
-    uarch_replay_state_access &operator=(uarch_replay_state_access &&) = delete;
-    /// \brief Default destructor
-    ~uarch_replay_state_access() = default;
-
     void finish() {
-        if (m_next_access != m_accesses.size()) {
+        if (m_context.next_access != m_context.accesses.size()) {
             throw std::invalid_argument{"access log was not fully consumed"};
         }
     }
 
     void get_root_hash(hash_type &hash) const {
-        hash = m_root_hash;
+        hash = m_context.root_hash;
     }
 
 private:
@@ -100,7 +97,7 @@ class uarch_replay_state_access :
     }
 
     std::string access_to_report() const {
-        auto index = m_next_access + 1;
+        auto index = m_context.next_access + 1;
         auto digit = index % 10;
         const char *suffix = nullptr;
         switch (digit) {
@@ -139,14 +136,14 @@ class uarch_replay_state_access :
         return {access_paddr, log2_access_size};
     }
 
-    const access &check_access(const char *text) {
-        if (m_next_access >= m_accesses.size()) {
+    const access &check_access(const char *text) const {
+        if (m_context.next_access >= m_context.accesses.size()) {
             throw std::invalid_argument{"log is missing access " + access_to_report() + " to " + text};
         }
-        return m_accesses[m_next_access];
+        return m_context.accesses[m_context.next_access];
     }
 
-    void check_access_type(const access &a, access_type type, const char *text) {
+    void check_access_type(const access &a, access_type type, const char *text) const {
         if (a.get_type() != type) {
             throw std::invalid_argument{
                 "expected " + access_to_report() + " to " + access_type_name(type) + " " + text};
@@ -163,7 +160,8 @@ class uarch_replay_state_access :
         }
     }
 
-    void check_access_range(const access &a, access_type type, uint64_t paddr, uint64_t log2_size, const char *text) {
+    void check_access_range(const access &a, access_type type, uint64_t paddr, uint64_t log2_size,
+        const char *text) const {
         if (a.get_address() != paddr) {
             std::ostringstream err;
             err << "expected " << access_to_report() << " to " << access_type_name(type) << " " << text
@@ -176,16 +174,16 @@ class uarch_replay_state_access :
         }
     }
 
-    auto check_access_siblings_and_read_hash(const access &a, const char *text) {
-        const auto proof = a.make_proof(m_root_hash);
-        if (!proof.verify(m_hasher)) {
+    auto check_access_siblings_and_read_hash(const access &a, const char *text) const {
+        const auto proof = a.make_proof(m_context.root_hash);
+        if (!proof.verify(m_context.hasher)) {
             throw std::invalid_argument{
                 "siblings and read hash do not match root hash before " + access_to_report() + " to " + text};
         }
         return proof;
     }
 
-    const auto &check_written_hash(const access &a, const hash_type &expected_hash, const char *text) {
+    const auto &check_written_hash(const access &a, const hash_type &expected_hash, const char *text) const {
         if (!a.get_written_hash().has_value()) {
             throw std::invalid_argument{"missing written hash of " + std::string(text) + " in " + access_to_report()};
         }
@@ -198,13 +196,13 @@ class uarch_replay_state_access :
         // NOLINTEND(bugprone-unchecked-optional-access)
     }
 
-    const auto &check_read_data(const access &a, const char *text) {
+    const auto &check_read_data(const access &a, const char *text) const {
         if (!a.get_read().has_value()) {
             throw std::invalid_argument{"missing read data for " + std::string(text) + " in " + access_to_report()};
         }
         // check if logged read data hashes to the logged read hash
         // NOLINTBEGIN(bugprone-unchecked-optional-access)
-        const auto computed_read_hash = get_hash(m_hasher, a.get_read().value());
+        const auto computed_read_hash = get_hash(m_context.hasher, a.get_read().value());
         if (a.get_read_hash() != computed_read_hash) {
             throw std::invalid_argument{
                 "read data for " + std::string(text) + " does not match read hash in " + access_to_report()};
@@ -213,35 +211,36 @@ class uarch_replay_state_access :
         // NOLINTEND(bugprone-unchecked-optional-access)
     }
 
-    void check_written_data_if_there(const access &a, const hash_type &written_hash, const char *text) {
+    void check_written_data_if_there(const access &a, const hash_type &written_hash, const char *text) const {
         if (!a.get_written().has_value()) {
             return;
         }
         // NOLINTBEGIN(bugprone-unchecked-optional-access)
-        if (written_hash != get_hash(m_hasher, a.get_written().value())) {
+        if (written_hash != get_hash(m_context.hasher, a.get_written().value())) {
             throw std::invalid_argument{
                 "written data for " + std::string(text) + " does not match written hash in " + access_to_report()};
         }
         // NOLINTEND(bugprone-unchecked-optional-access)
     }
 
-    void check_read_data_if_there(const access &a, const char *text) {
+    void check_read_data_if_there(const access &a, const char *text) const {
         if (!a.get_read().has_value()) {
             return;
         }
         // NOLINTBEGIN(bugprone-unchecked-optional-access)
-        if (a.get_read_hash() != get_hash(m_hasher, a.get_read().value())) {
+        if (a.get_read_hash() != get_hash(m_context.hasher, a.get_read().value())) {
             throw std::invalid_argument{
                 "read data for " + std::string(text) + " does not match read hash in " + access_to_report()};
         }
         // NOLINTEND(bugprone-unchecked-optional-access)
     }
 
-    void update_root_hash(const proof_type &proof, const hash_type &written_hash) {
-        m_root_hash = proof.bubble_up(m_hasher, written_hash);
+    void update_root_hash(const proof_type &proof, const hash_type &written_hash) const {
+        m_context.root_hash = proof.bubble_up(m_context.hasher, written_hash);
     }
 
-    void check_write_access(uint64_t paddr, uint64_t log2_size, const hash_type &expected_hash, const char *text) {
+    void check_write_access(uint64_t paddr, uint64_t log2_size, const hash_type &expected_hash,
+        const char *text) const {
         const auto &a = check_access(text);
         check_access_type(a, access_type::write, text);
         check_access_range(a, access_type::write, paddr, log2_size, text);
@@ -250,10 +249,10 @@ class uarch_replay_state_access :
         check_read_data_if_there(a, text);
         check_written_data_if_there(a, written_hash, text);
         update_root_hash(proof, written_hash);
-        m_next_access++;
+        m_context.next_access++;
     }
 
-    void check_write_word_access(uint64_t paddr, uint64_t val, const char *text) {
+    void check_write_word_access(uint64_t paddr, uint64_t val, const char *text) const {
         const auto log2_size = log2_size_v<uint64_t>;
         const auto &a = check_access(text);
         check_access_type(a, access_type::write, text);
@@ -263,17 +262,17 @@ class uarch_replay_state_access :
         [[maybe_unused]] const auto [access_paddr, access_log2_size] = adjust_access(paddr, log2_size);
         const auto val_offset = paddr - access_paddr;
         replace_word_access_data(val, written_data, val_offset);
-        const auto &written_hash = check_written_hash(a, get_hash(m_hasher, written_data), text);
+        const auto &written_hash = check_written_hash(a, get_hash(m_context.hasher, written_data), text);
         check_written_data_if_there(a, written_hash, text);
         update_root_hash(proof, written_hash);
-        m_next_access++;
+        m_context.next_access++;
     }
 
-    void check_write_reg_access(machine_reg reg, uint64_t val) {
+    void check_write_reg_access(machine_reg reg, uint64_t val) const {
         check_write_word_access(machine_reg_address(reg), val, machine_reg_get_name(reg));
     }
 
-    uint64_t check_read_word_access(uint64_t paddr, const char *text) {
+    uint64_t check_read_word_access(uint64_t paddr, const char *text) const {
         const auto log2_size = log2_size_v<uint64_t>;
         const auto &a = check_access(text);
         check_access_type(a, access_type::read, text);
@@ -283,15 +282,15 @@ class uarch_replay_state_access :
         [[maybe_unused]] const auto [access_paddr, access_log2_size] = adjust_access(paddr, log2_size);
         const auto val_offset = paddr - access_paddr;
         const auto val = get_word_access_data(read_data, val_offset);
-        m_next_access++;
+        m_context.next_access++;
         return val;
     }
 
-    uint64_t check_read_reg_access(machine_reg reg) {
+    uint64_t check_read_reg_access(machine_reg reg) const {
         return check_read_word_access(machine_reg_address(reg), machine_reg_get_name(reg));
     }
 
-    auto get_write_tlb_slot_hash(uint64_t vaddr_page, uint64_t vp_offset, uint64_t pma_index) {
+    auto get_write_tlb_slot_hash(uint64_t vaddr_page, uint64_t vp_offset, uint64_t pma_index) const {
         // Writes to TLB slots have to be atomic.
         // We can only do atomic writes of entire Merkle tree nodes.
         // Therefore, TLB slot must have a power-of-two size, or at least be aligned to it.
@@ -304,7 +303,7 @@ class uarch_replay_state_access :
         shadow_tlb_fill_slot(vaddr_page, vp_offset, pma_index, slot_data);
         hash_type slot_hash{};
         // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        get_merkle_tree_hash(m_hasher, reinterpret_cast<uint8_t *>(&slot_data), sizeof(slot_data),
+        get_merkle_tree_hash(m_context.hasher, reinterpret_cast<uint8_t *>(&slot_data), sizeof(slot_data),
             machine_merkle_tree::get_word_size(), slot_hash);
         return slot_hash;
     }
@@ -314,11 +313,11 @@ class uarch_replay_state_access :
     // -----
     friend i_prefer_shadow_uarch_state<uarch_replay_state_access>;
 
-    uint64_t do_read_shadow_uarch_state(shadow_uarch_state_what what) {
+    uint64_t do_read_shadow_uarch_state(shadow_uarch_state_what what) const {
         return check_read_reg_access(machine_reg_enum(what));
     }
 
-    void do_write_shadow_uarch_state(shadow_uarch_state_what what, uint64_t val) {
+    void do_write_shadow_uarch_state(shadow_uarch_state_what what, uint64_t val) const {
         check_write_reg_access(machine_reg_enum(what), val);
     }
 
@@ -327,30 +326,30 @@ class uarch_replay_state_access :
     // -----
     friend i_uarch_state_access<uarch_replay_state_access>;
 
-    uint64_t do_read_word(uint64_t paddr) {
+    uint64_t do_read_word(uint64_t paddr) const {
         return check_read_word_access(paddr, machine::get_what_name(paddr));
     }
 
-    void do_write_word(uint64_t paddr, uint64_t val) {
+    void do_write_word(uint64_t paddr, uint64_t val) const {
         check_write_word_access(paddr, val, machine::get_what_name(paddr));
     }
 
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    void do_putchar(uint8_t /*c*/) {
+    void do_putchar(uint8_t /*c*/) const {
         ; // do nothing
     }
 
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    void do_mark_dirty_page(uint64_t /*paddr*/, uint64_t /*pma_index*/) {
+    void do_mark_dirty_page(uint64_t /*paddr*/, uint64_t /*pma_index*/) const {
         ; // do nothing
     }
 
-    void do_reset_uarch() {
+    void do_reset_uarch() const {
         check_write_access(UARCH_STATE_START_ADDRESS, UARCH_STATE_LOG2_SIZE, uarch_pristine_state_hash, "uarch.state");
     }
 
     void do_write_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset,
-        uint64_t pma_index) {
+        uint64_t pma_index) const {
         const auto slot_paddr = shadow_tlb_get_abs_addr(set_index, slot_index);
         const auto slot_hash = get_write_tlb_slot_hash(vaddr_page, vp_offset, pma_index);
         check_write_access(slot_paddr, SHADOW_TLB_SLOT_LOG2_SIZE, slot_hash, "tlb.slot");
diff --git a/src/uarch-solidity-compat.h b/src/uarch-solidity-compat.h
index c47a8968a..fd1559056 100644
--- a/src/uarch-solidity-compat.h
+++ b/src/uarch-solidity-compat.h
@@ -50,57 +50,57 @@ using bytes = const unsigned char *;
 // Wrapperfunctions used to access data from the uarch state accessor
 
 template <typename UarchState>
-static inline uint64 readWord(UarchState &a, uint64 paddr) {
+static inline uint64 readWord(const UarchState a, uint64 paddr) {
     return a.read_word(paddr);
 }
 
 template <typename UarchState>
-static inline void writeWord(UarchState &a, uint64 paddr, uint64 val) {
+static inline void writeWord(const UarchState a, uint64 paddr, uint64 val) {
     a.write_word(paddr, val);
 }
 
 template <typename UarchState>
-static inline uint64 readCycle(UarchState &a) {
+static inline uint64 readCycle(const UarchState a) {
     return a.read_uarch_cycle();
 }
 
 template <typename UarchState>
-static inline void writeCycle(UarchState &a, uint64 val) {
+static inline void writeCycle(const UarchState a, uint64 val) {
     a.write_uarch_cycle(val);
 }
 
 template <typename UarchState>
-static inline uint64 readHaltFlag(UarchState &a) {
+static inline uint64 readHaltFlag(const UarchState a) {
     return a.read_uarch_halt_flag();
 }
 
 template <typename UarchState>
-static inline void writeHaltFlag(UarchState &a, uint64 val) {
+static inline void writeHaltFlag(const UarchState a, uint64 val) {
     a.write_uarch_halt_flag(val);
 }
 
 template <typename UarchState>
-static inline uint64 readPc(UarchState &a) {
+static inline uint64 readPc(const UarchState a) {
     return a.read_uarch_pc();
 }
 
 template <typename UarchState>
-static inline void writePc(UarchState &a, uint64 val) {
+static inline void writePc(const UarchState a, uint64 val) {
     a.write_uarch_pc(val);
 }
 
 template <typename UarchState>
-static inline uint64 readX(UarchState &a, uint8 reg) {
+static inline uint64 readX(const UarchState a, uint8 reg) {
     return a.read_uarch_x(reg);
 }
 
 template <typename UarchState>
-static inline void writeX(UarchState &a, uint8 reg, uint64 val) {
+static inline void writeX(const UarchState a, uint8 reg, uint64 val) {
     a.write_uarch_x(reg, val);
 }
 
 template <typename UarchState>
-static inline void resetState(UarchState &a) {
+static inline void resetState(const UarchState a) {
     a.reset_uarch();
 }
 
@@ -131,17 +131,17 @@ static inline void throwRuntimeError(UarchState & /*a*/, const char *message) {
 }
 
 template <typename UarchState>
-static inline void putCharECALL(UarchState &a, uint8 c) {
+static inline void putCharECALL(const UarchState a, uint8 c) {
     a.putchar(c);
 }
 
 template <typename UarchState>
-static inline void markDirtyPageECALL(UarchState &a, uint64 paddr, uint64 pma_index) {
+static inline void markDirtyPageECALL(const UarchState a, uint64 paddr, uint64 pma_index) {
     a.mark_dirty_page(paddr, pma_index);
 }
 
 template <typename UarchState>
-static inline void writeTlbECALL(UarchState &a, uint64 set_index, uint64 slot_index, uint64 vaddr_page,
+static inline void writeTlbECALL(const UarchState a, uint64 set_index, uint64 slot_index, uint64 vaddr_page,
     uint64 vp_offset, uint64 pma_index) {
     a.write_tlb(static_cast<TLB_set_index>(set_index), slot_index, vaddr_page, vp_offset, pma_index);
 }
@@ -228,7 +228,7 @@ void require([[maybe_unused]] T1 condition, [[maybe_unused]] T2 message) {
 }
 
 template <typename UarchState>
-static auto dumpInsn([[maybe_unused]] UarchState &a, [[maybe_unused]] uint64 pc, [[maybe_unused]] uint32 insn,
+static auto dumpInsn([[maybe_unused]] const UarchState a, [[maybe_unused]] uint64 pc, [[maybe_unused]] uint32 insn,
     [[maybe_unused]] const char *name) {
 #ifdef DUMP_UARCH_INSN
     D_PRINTF("ua %08" PRIx64, pc);
diff --git a/src/uarch-state-access.h b/src/uarch-state-access.h
index 806151272..ef52ba558 100644
--- a/src/uarch-state-access.h
+++ b/src/uarch-state-access.h
@@ -52,17 +52,6 @@ class uarch_state_access :
         m_uram_ph_offset = haddr - paddr;
     }
 
-    /// \brief No copy constructor
-    uarch_state_access(const uarch_state_access &) = delete;
-    /// \brief No copy assignment
-    uarch_state_access &operator=(const uarch_state_access &) = delete;
-    /// \brief No move constructor
-    uarch_state_access(uarch_state_access &&) = delete;
-    /// \brief No move assignment
-    uarch_state_access &operator=(uarch_state_access &&) = delete;
-    /// \brief Default destructor
-    ~uarch_state_access() = default;
-
 private:
     // -----
     // i_uarch_state_access interface implementation
@@ -73,7 +62,7 @@ class uarch_state_access :
         return m_m.get_uarch_state().x[i];
     }
 
-    void do_write_uarch_x(int i, uint64_t val) {
+    void do_write_uarch_x(int i, uint64_t val) const {
         assert(i != 0);
         m_m.get_uarch_state().x[i] = val;
     }
@@ -82,7 +71,7 @@ class uarch_state_access :
         return m_m.get_uarch_state().pc;
     }
 
-    void do_write_uarch_pc(uint64_t val) {
+    void do_write_uarch_pc(uint64_t val) const {
         m_m.get_uarch_state().pc = val;
     }
 
@@ -90,7 +79,7 @@ class uarch_state_access :
         return m_m.get_uarch_state().cycle;
     }
 
-    void do_write_uarch_cycle(uint64_t val) {
+    void do_write_uarch_cycle(uint64_t val) const {
         m_m.get_uarch_state().cycle = val;
     }
 
@@ -98,11 +87,11 @@ class uarch_state_access :
         return m_m.get_uarch_state().halt_flag;
     }
 
-    void do_write_uarch_halt_flag(uint64_t v) {
+    void do_write_uarch_halt_flag(uint64_t v) const {
         m_m.get_uarch_state().halt_flag = v;
     }
 
-    uint64_t do_read_word(uint64_t paddr) {
+    uint64_t do_read_word(uint64_t paddr) const {
         if ((paddr & (sizeof(uint64_t) - 1)) != 0) {
             throw std::runtime_error("misaligned read from uarch");
         }
@@ -116,7 +105,7 @@ class uarch_state_access :
         return m_m.read_word(paddr);
     }
 
-    void do_write_word(uint64_t paddr, uint64_t val) {
+    void do_write_word(uint64_t paddr, uint64_t val) const {
         if ((paddr & (sizeof(uint64_t) - 1)) != 0) {
             throw std::runtime_error("misaligned read from uarch");
         }
@@ -132,23 +121,23 @@ class uarch_state_access :
     }
 
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    void do_putchar(uint8_t c) {
+    void do_putchar(uint8_t c) const {
         os_putchar(c);
     }
 
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    void do_mark_dirty_page(uint64_t paddr, uint64_t pma_index) {
+    void do_mark_dirty_page(uint64_t paddr, uint64_t pma_index) const {
         // Forward to machine
         m_m.mark_dirty_page(paddr, pma_index);
     }
 
     void do_write_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset,
-        uint64_t pma_index) {
+        uint64_t pma_index) const {
         // Forward to machine
         m_m.write_shadow_tlb(set_index, slot_index, vaddr_page, vp_offset, pma_index);
     }
 
-    void do_reset_uarch() {
+    void do_reset_uarch() const {
         // Forward to machine
         m_m.reset_uarch();
     }
diff --git a/src/uarch-step.cpp b/src/uarch-step.cpp
index 7c6e97fcb..8243a2dc6 100644
--- a/src/uarch-step.cpp
+++ b/src/uarch-step.cpp
@@ -33,13 +33,13 @@ namespace cartesi {
 // Memory read/write access
 
 template <typename UarchState>
-static inline uint64 readUint64(UarchState &a, uint64 paddr) {
+static inline uint64 readUint64(const UarchState a, uint64 paddr) {
     require((paddr & 7) == 0, "misaligned readUint64 address");
     return readWord(a, paddr);
 }
 
 template <typename UarchState>
-static inline uint32 readUint32(UarchState &a, uint64 paddr) {
+static inline uint32 readUint32(const UarchState a, uint64 paddr) {
     require((paddr & 3) == 0, "misaligned readUint32 address");
     uint64 palign = paddr & ~uint64(7);
     uint32 bitoffset = uint32ShiftLeft(uint32(paddr) & uint32(7), 3);
@@ -48,7 +48,7 @@ static inline uint32 readUint32(UarchState &a, uint64 paddr) {
 }
 
 template <typename UarchState>
-static inline uint16 readUint16(UarchState &a, uint64 paddr) {
+static inline uint16 readUint16(const UarchState a, uint64 paddr) {
     require((paddr & 1) == 0, "misaligned readUint16 address");
     uint64 palign = paddr & ~uint64(7);
     uint32 bitoffset = uint32ShiftLeft(uint32(paddr) & uint32(7), 3);
@@ -57,7 +57,7 @@ static inline uint16 readUint16(UarchState &a, uint64 paddr) {
 }
 
 template <typename UarchState>
-static inline uint8 readUint8(UarchState &a, uint64 paddr) {
+static inline uint8 readUint8(const UarchState a, uint64 paddr) {
     uint64 palign = paddr & ~uint64(7);
     uint32 bitoffset = uint32ShiftLeft(uint32(paddr) & uint32(7), 3);
     uint64 val64 = readUint64(a, palign);
@@ -65,7 +65,7 @@ static inline uint8 readUint8(UarchState &a, uint64 paddr) {
 }
 
 template <typename UarchState>
-static inline void writeUint64(UarchState &a, uint64 paddr, uint64 val) {
+static inline void writeUint64(const UarchState a, uint64 paddr, uint64 val) {
     require((paddr & 7) == 0, "misaligned writeUint64 address");
     writeWord(a, paddr, val);
 }
@@ -84,7 +84,7 @@ static inline uint64 copyBits(uint32 from, uint32 count, uint64 to, uint32 offse
 }
 
 template <typename UarchState>
-static inline void writeUint32(UarchState &a, uint64 paddr, uint32 val) {
+static inline void writeUint32(const UarchState a, uint64 paddr, uint32 val) {
     require((paddr & 3) == 0, "misaligned writeUint32 address");
     uint64 palign = paddr & ~uint64(7);
 
@@ -95,7 +95,7 @@ static inline void writeUint32(UarchState &a, uint64 paddr, uint32 val) {
 }
 
 template <typename UarchState>
-static inline void writeUint16(UarchState &a, uint64 paddr, uint16 val) {
+static inline void writeUint16(const UarchState a, uint64 paddr, uint16 val) {
     require((paddr & 1) == 0, "misaligned writeUint16 address");
     uint64 palign = paddr & ~uint64(7);
     uint32 bitoffset = uint32ShiftLeft(uint32(paddr) & uint32(7), 3);
@@ -105,7 +105,7 @@ static inline void writeUint16(UarchState &a, uint64 paddr, uint16 val) {
 }
 
 template <typename UarchState>
-static inline void writeUint8(UarchState &a, uint64 paddr, uint8 val) {
+static inline void writeUint8(const UarchState a, uint64 paddr, uint8 val) {
     uint64 palign = paddr & ~uint64(7);
     uint32 bitoffset = uint32ShiftLeft(uint32(paddr) & uint32(7), 3);
     uint64 oldval64 = readUint64(a, palign);
@@ -167,18 +167,18 @@ static inline int32 operandSimm12(uint32 insn) {
 // Execute instruction
 
 template <typename UarchState>
-static inline void advancePc(UarchState &a, uint64 pc) {
+static inline void advancePc(const UarchState a, uint64 pc) {
     uint64 newPc = uint64AddUint64(pc, 4);
     return writePc(a, newPc);
 }
 
 template <typename UarchState>
-static inline void branch(UarchState &a, uint64 pc) {
+static inline void branch(const UarchState a, uint64 pc) {
     return writePc(a, pc);
 }
 
 template <typename UarchState>
-static inline void executeLUI(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeLUI(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "lui");
     uint8 rd = operandRd(insn);
     int32 imm = operandImm20(insn);
@@ -189,7 +189,7 @@ static inline void executeLUI(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeAUIPC(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeAUIPC(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "auipc");
     int32 imm = operandImm20(insn);
     uint8 rd = operandRd(insn);
@@ -200,7 +200,7 @@ static inline void executeAUIPC(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeJAL(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeJAL(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "jal");
     int32 imm = operandJimm20(insn);
     uint8 rd = operandRd(insn);
@@ -211,7 +211,7 @@ static inline void executeJAL(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeJALR(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeJALR(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "jalr");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
@@ -224,7 +224,7 @@ static inline void executeJALR(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeBEQ(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeBEQ(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "beq");
     int32 imm = operandSbimm12(insn);
     uint8 rs1 = operandRs1(insn);
@@ -238,7 +238,7 @@ static inline void executeBEQ(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeBNE(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeBNE(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "bne");
     int32 imm = operandSbimm12(insn);
     uint8 rs1 = operandRs1(insn);
@@ -252,7 +252,7 @@ static inline void executeBNE(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeBLT(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeBLT(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "blt");
     int32 imm = operandSbimm12(insn);
     uint8 rs1 = operandRs1(insn);
@@ -266,7 +266,7 @@ static inline void executeBLT(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeBGE(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeBGE(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "bge");
     int32 imm = operandSbimm12(insn);
     uint8 rs1 = operandRs1(insn);
@@ -280,7 +280,7 @@ static inline void executeBGE(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeBLTU(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeBLTU(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "bltu");
     int32 imm = operandSbimm12(insn);
     uint8 rs1 = operandRs1(insn);
@@ -294,7 +294,7 @@ static inline void executeBLTU(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeBGEU(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeBGEU(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "bgeu");
     int32 imm = operandSbimm12(insn);
     uint8 rs1 = operandRs1(insn);
@@ -308,7 +308,7 @@ static inline void executeBGEU(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeLB(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeLB(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "lb");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
@@ -322,7 +322,7 @@ static inline void executeLB(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeLHU(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeLHU(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "lhu");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
@@ -336,7 +336,7 @@ static inline void executeLHU(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeLH(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeLH(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "lh");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
@@ -350,7 +350,7 @@ static inline void executeLH(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeLW(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeLW(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "lw");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
@@ -364,7 +364,7 @@ static inline void executeLW(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeLBU(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeLBU(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "lbu");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
@@ -378,7 +378,7 @@ static inline void executeLBU(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeSB(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeSB(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "sb");
     int32 imm = operandSimm12(insn);
     uint8 rs1 = operandRs1(insn);
@@ -390,7 +390,7 @@ static inline void executeSB(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeSH(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeSH(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "sh");
     int32 imm = operandSimm12(insn);
     uint8 rs1 = operandRs1(insn);
@@ -402,7 +402,7 @@ static inline void executeSH(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeSW(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeSW(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "sw");
     int32 imm = operandSimm12(insn);
     uint8 rs1 = operandRs1(insn);
@@ -414,7 +414,7 @@ static inline void executeSW(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeADDI(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeADDI(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "addi");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
@@ -428,7 +428,7 @@ static inline void executeADDI(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeADDIW(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeADDIW(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "addiw");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
@@ -442,7 +442,7 @@ static inline void executeADDIW(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeSLTI(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeSLTI(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "slti");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
@@ -459,7 +459,7 @@ static inline void executeSLTI(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeSLTIU(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeSLTIU(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "sltiu");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
@@ -476,7 +476,7 @@ static inline void executeSLTIU(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeXORI(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeXORI(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "xori");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
@@ -489,7 +489,7 @@ static inline void executeXORI(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeORI(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeORI(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "ori");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
@@ -502,7 +502,7 @@ static inline void executeORI(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeANDI(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeANDI(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "andi");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
@@ -515,7 +515,7 @@ static inline void executeANDI(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeSLLI(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeSLLI(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "slli");
     int32 imm = operandShamt6(insn);
     uint8 rd = operandRd(insn);
@@ -528,7 +528,7 @@ static inline void executeSLLI(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeSLLIW(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeSLLIW(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "slliw");
     int32 imm = operandShamt5(insn);
     uint8 rd = operandRd(insn);
@@ -541,7 +541,7 @@ static inline void executeSLLIW(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeSRLI(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeSRLI(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "srli");
     int32 imm = operandShamt6(insn);
     uint8 rd = operandRd(insn);
@@ -554,7 +554,7 @@ static inline void executeSRLI(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeSRLW(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeSRLW(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "srlw");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -569,7 +569,7 @@ static inline void executeSRLW(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeSRLIW(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeSRLIW(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "srliw");
     int32 imm = operandShamt5(insn);
     uint8 rd = operandRd(insn);
@@ -583,7 +583,7 @@ static inline void executeSRLIW(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeSRAI(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeSRAI(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "srai");
     int32 imm = operandShamt6(insn);
     uint8 rd = operandRd(insn);
@@ -596,7 +596,7 @@ static inline void executeSRAI(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeSRAIW(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeSRAIW(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "sraiw");
     int32 imm = operandShamt5(insn);
     uint8 rd = operandRd(insn);
@@ -609,7 +609,7 @@ static inline void executeSRAIW(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeADD(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeADD(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "add");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -623,7 +623,7 @@ static inline void executeADD(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeADDW(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeADDW(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "addw");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -638,7 +638,7 @@ static inline void executeADDW(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeSUB(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeSUB(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "sub");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -652,7 +652,7 @@ static inline void executeSUB(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeSUBW(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeSUBW(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "subw");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -667,7 +667,7 @@ static inline void executeSUBW(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeSLL(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeSLL(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "sll");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -681,7 +681,7 @@ static inline void executeSLL(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeSLLW(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeSLLW(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "sllw");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -696,7 +696,7 @@ static inline void executeSLLW(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeSLT(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeSLT(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "slt");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -714,7 +714,7 @@ static inline void executeSLT(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeSLTU(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeSLTU(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "sltu");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -732,7 +732,7 @@ static inline void executeSLTU(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeXOR(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeXOR(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "xor");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -746,7 +746,7 @@ static inline void executeXOR(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeSRL(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeSRL(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "srl");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -760,7 +760,7 @@ static inline void executeSRL(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeSRA(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeSRA(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "sra");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -774,7 +774,7 @@ static inline void executeSRA(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeSRAW(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeSRAW(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "sraw");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -789,7 +789,7 @@ static inline void executeSRAW(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeOR(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeOR(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "or");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -803,7 +803,7 @@ static inline void executeOR(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeAND(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeAND(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "and");
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
@@ -817,13 +817,13 @@ static inline void executeAND(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeFENCE(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeFENCE(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "fence");
     return advancePc(a, pc);
 }
 
 template <typename UarchState>
-static inline void executeLWU(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeLWU(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "lwu");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
@@ -837,7 +837,7 @@ static inline void executeLWU(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeLD(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeLD(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "ld");
     int32 imm = operandImm12(insn);
     uint8 rd = operandRd(insn);
@@ -851,7 +851,7 @@ static inline void executeLD(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeSD(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeSD(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "sd");
     int32 imm = operandSimm12(insn);
     uint8 rs1 = operandRs1(insn);
@@ -863,7 +863,7 @@ static inline void executeSD(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeECALL(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeECALL(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "ecall");
     // ECALL conventions
     // a0--a7 are the same as x10--x17
@@ -899,7 +899,7 @@ static inline void executeECALL(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-static inline void executeEBREAK(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeEBREAK(const UarchState a, uint32 insn, uint64 pc) {
     [[maybe_unused]] auto note = dumpInsn(a, pc, insn, "ebreak");
     throwRuntimeError(a, "uarch aborted");
 }
@@ -930,7 +930,7 @@ static inline bool insnMatchOpcodeFunct3Funct7Sr1(uint32 insn, uint32 opcode, ui
 
 // Decode and execute one instruction
 template <typename UarchState>
-static inline void executeInsn(UarchState &a, uint32 insn, uint64 pc) {
+static inline void executeInsn(const UarchState a, uint32 insn, uint64 pc) {
     if (insnMatchOpcodeFunct3(insn, 0x13, 0x0)) {
         return executeADDI(a, insn, pc);
     }
@@ -1091,7 +1091,7 @@ static inline void executeInsn(UarchState &a, uint32 insn, uint64 pc) {
 }
 
 template <typename UarchState>
-UArchStepStatus uarch_step(UarchState &a) {
+UArchStepStatus uarch_step(const UarchState a) {
     // This must be the first read in order to match the first log access in machine::verify_step_uarch
     uint64 cycle = readCycle(a);
     // do not advance if cycle will overflow
@@ -1112,13 +1112,13 @@ UArchStepStatus uarch_step(UarchState &a) {
 }
 
 // Explicit instantiation for uarch_state_access
-template UArchStepStatus uarch_step(uarch_state_access &a);
+template UArchStepStatus uarch_step(const uarch_state_access a);
 
 // Explicit instantiation for uarch_record_state_access
-template UArchStepStatus uarch_step(uarch_record_state_access &a);
+template UArchStepStatus uarch_step(const uarch_record_state_access a);
 
 // Explicit instantiation for uarch_replay_state_access
-template UArchStepStatus uarch_step(uarch_replay_state_access &a);
+template UArchStepStatus uarch_step(const uarch_replay_state_access a);
 
 } // namespace cartesi
 // NOLINTEND(google-readability-casting,misc-const-correctness,modernize-use-auto,hicpp-use-auto)
diff --git a/src/uarch-step.h b/src/uarch-step.h
index e4972c23d..45a82d3fb 100644
--- a/src/uarch-step.h
+++ b/src/uarch-step.h
@@ -31,7 +31,7 @@ enum class UArchStepStatus : int {
 /// \returns Returns a status code indicating whether and how the microarchitecure was advanced
 /// \details The microarchitecture will not advance if it is at a fixed point
 template <typename STATE_ACCESS>
-UArchStepStatus uarch_step(STATE_ACCESS &a);
+UArchStepStatus uarch_step(STATE_ACCESS a);
 
 } // namespace cartesi
 
diff --git a/uarch/machine-uarch-bridge-state-access.h b/uarch/machine-uarch-bridge-state-access.h
index dbda86744..793b04c4d 100644
--- a/uarch/machine-uarch-bridge-state-access.h
+++ b/uarch/machine-uarch-bridge-state-access.h
@@ -68,23 +68,23 @@ class machine_uarch_bridge_state_access :
     ~machine_uarch_bridge_state_access() = default;
 
 private:
-    uint64_t bridge_read_reg(machine_reg reg) {
+    static uint64_t bridge_read_reg(machine_reg reg) {
         return ua_aliased_aligned_read<uint64_t>(machine_reg_address(reg));
     }
 
-    void bridge_write_reg(machine_reg reg, uint64_t val) {
+    static void bridge_write_reg(machine_reg reg, uint64_t val) {
         ua_aliased_aligned_write<uint64_t>(machine_reg_address(reg), val);
     }
 
-    uint64_t bridge_read_pma_istart(int i) {
+    static uint64_t bridge_read_pma_istart(int i) {
         return ua_aliased_aligned_read<uint64_t>(shadow_pmas_get_pma_abs_addr(i, shadow_pmas_what::istart));
     }
 
-    uint64_t bridge_read_pma_ilength(int i) {
+    static uint64_t bridge_read_pma_ilength(int i) {
         return ua_aliased_aligned_read<uint64_t>(shadow_pmas_get_pma_abs_addr(i, shadow_pmas_what::ilength));
     }
 
-    uint64_t bridge_read_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, shadow_tlb_what what) {
+    static uint64_t bridge_read_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, shadow_tlb_what what) {
         return ua_aliased_aligned_read<uint64_t>(shadow_tlb_get_abs_addr(set_index, slot_index, what));
     }
 
@@ -93,11 +93,11 @@ class machine_uarch_bridge_state_access :
     // -----
     friend i_prefer_shadow_state<machine_uarch_bridge_state_access>;
 
-    uint64_t do_read_shadow_state(shadow_state_what what) {
+    uint64_t do_read_shadow_state(shadow_state_what what) const {
         return bridge_read_reg(machine_reg_enum(what));
     }
 
-    void do_write_shadow_state(shadow_state_what what, uint64_t val) {
+    void do_write_shadow_state(shadow_state_what what, uint64_t val) const {
         bridge_write_reg(machine_reg_enum(what), val);
     }
 
@@ -107,28 +107,28 @@ class machine_uarch_bridge_state_access :
     friend i_state_access<machine_uarch_bridge_state_access>;
 
     template <typename T, typename A>
-    void do_read_memory_word(uint64_t paddr, uint64_t /* pma_index */, T *pval) {
+    void do_read_memory_word(uint64_t paddr, uint64_t /* pma_index */, T *pval) const {
         *pval = ua_aliased_aligned_read<T, A>(paddr);
     }
 
     template <typename T, typename A>
-    void do_write_memory_word(uint64_t paddr, uint64_t /* pma_index */, T val) {
+    void do_write_memory_word(uint64_t paddr, uint64_t /* pma_index */, T val) const {
         ua_aliased_aligned_write<T, A>(paddr, val);
     }
 
-    bool do_read_memory(uint64_t /*paddr*/, unsigned char * /*data*/, uint64_t /*length*/) {
+    bool do_read_memory(uint64_t /*paddr*/, unsigned char * /*data*/, uint64_t /*length*/) const {
         // This is not implemented yet because it's not being used
         abort();
         return false;
     }
 
-    bool do_write_memory(uint64_t /*paddr*/, const unsigned char * /*data*/, uint64_t /*length*/) {
+    bool do_write_memory(uint64_t /*paddr*/, const unsigned char * /*data*/, uint64_t /*length*/) const {
         // This is not implemented yet because it's not being used
         abort();
         return false;
     }
 
-    mock_pma_entry &do_read_pma_entry(uint64_t index) {
+    mock_pma_entry &do_read_pma_entry(uint64_t index) const {
         const uint64_t istart = bridge_read_pma_istart(index);
         const uint64_t ilength = bridge_read_pma_ilength(index);
         // NOLINTNEXTLINE(bugprone-narrowing-conversions)
@@ -145,30 +145,30 @@ class machine_uarch_bridge_state_access :
     }
 
     template <TLB_set_index SET>
-    uint64_t do_read_tlb_vaddr_page(uint64_t slot_index) {
+    uint64_t do_read_tlb_vaddr_page(uint64_t slot_index) const {
         return bridge_read_shadow_tlb(SET, slot_index, shadow_tlb_what::vaddr_page);
     }
 
     template <TLB_set_index SET>
-    uint64_t do_read_tlb_vp_offset(uint64_t slot_index) {
+    uint64_t do_read_tlb_vp_offset(uint64_t slot_index) const {
         return bridge_read_shadow_tlb(SET, slot_index, shadow_tlb_what::vp_offset);
     }
 
     template <TLB_set_index SET>
-    uint64_t do_read_tlb_pma_index(uint64_t slot_index) {
+    uint64_t do_read_tlb_pma_index(uint64_t slot_index) const {
         return bridge_read_shadow_tlb(SET, slot_index, shadow_tlb_what::pma_index);
     }
 
     template <TLB_set_index SET>
-    void do_write_tlb(uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset, uint64_t pma_index) {
+    void do_write_tlb(uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset, uint64_t pma_index) const {
         ua_write_tlb_ECALL(SET, slot_index, vaddr_page, vp_offset, pma_index);
     }
 
-    void do_putchar(uint8_t c) {
+    void do_putchar(uint8_t c) const {
         ua_putchar_ECALL(c);
     }
 
-    void do_mark_dirty_page(uint64_t paddr, uint64_t pma_index) {
+    void do_mark_dirty_page(uint64_t paddr, uint64_t pma_index) const {
         ua_mark_dirty_page_ECALL(paddr, pma_index);
     }
 

From 4bab9fbdb6ff735eb2b214de9d6e932e33eef452 Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Wed, 12 Feb 2025 16:09:54 +0000
Subject: [PATCH 18/82] refactor: make dump_regs work with mcycle and pc

---
 src/interpret.cpp | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/src/interpret.cpp b/src/interpret.cpp
index 2b0879e6f..02a272b65 100644
--- a/src/interpret.cpp
+++ b/src/interpret.cpp
@@ -305,11 +305,8 @@ static void dump_regs(STATE_ACCESS &a) {
     const auto pc = a.read_pc();
     const auto iprv = a.read_iprv();
     const auto mstatus = a.read_mstatus();
-    //??D We would need to receive mcycle as an argument in order to have the
-    //??D up-to-date value for it. As it turns out, this would require many, many
-    //??D changes...
-    // const auto mcycle = a.read_mcycle();
-    // const auto icycleinstret = a.read_icycleinstret();
+    const auto mcycle = a.read_mcycle();
+    const auto icycleinstret = a.read_icycleinstret();
     const auto mideleg = a.read_mideleg();
     const auto mie = a.read_mie();
     const auto mip = a.read_mip();
@@ -333,8 +330,8 @@ static void dump_regs(STATE_ACCESS &a) {
     }
     D_PRINTF("prv=%s", prv_get_name(iprv));
     D_PRINTF(" mstatus=" PRIxREG "\n", mstatus);
-    // D_PRINTF(" cycles=" PRIuREG, mcycle);
-    // D_PRINTF(" insns=" PRIuREG "\n", mcycle - icycleinstret);
+    D_PRINTF(" cycles=" PRIuREG, mcycle);
+    D_PRINTF(" insns=" PRIuREG "\n", mcycle - icycleinstret);
     D_PRINTF("mideleg=" PRIxREG, mideleg);
     D_PRINTF(" mie=" PRIxREG, mie);
     D_PRINTF(" mip=" PRIxREG "\n", mip);
@@ -6029,6 +6026,12 @@ static NO_INLINE execute_status interpret_loop(const STATE_ACCESS a, uint64_t mc
                 // NOLINTEND
                 // clang-format on
 
+#ifdef DUMP_REGS
+                // Commit machine state
+                a.write_pc(pc);
+                a.write_mcycle(mcycle + 1);
+#endif
+
                 // When execute status is above success, we have to deal with special loop conditions,
                 // this is very unlikely to happen most of the time
                 if (unlikely(status > execute_status::success)) {

From 6423fe5f179af12a189192c43ce6813b018870d9 Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Thu, 13 Feb 2025 16:54:39 +0000
Subject: [PATCH 19/82] refactor: add unique_mmap smart pointer and use it

---
 src/jsonrpc-remote-machine.cpp        |   4 +-
 src/machine.cpp                       |  35 ++++-----
 src/merkle-tree-hash.cpp              |   4 +-
 src/os.cpp                            |  11 ++-
 src/os.h                              |   4 +-
 src/pma-constants.h                   |   1 -
 src/pma-defines.h                     |   1 -
 src/pma.cpp                           |  81 ++++---------------
 src/pma.h                             | 108 ++++++++++----------------
 src/record-step-state-access.h        |   2 +-
 src/replay-send-cmio-state-access.h   |   2 +-
 src/replay-step-state-access.h        |   4 +-
 src/unique-c-ptr.h                    |  44 ++++++++---
 tests/misc/test-merkle-tree-hash.cpp  |   4 +-
 uarch/compute-uarch-pristine-hash.cpp |   2 +-
 15 files changed, 126 insertions(+), 181 deletions(-)

diff --git a/src/jsonrpc-remote-machine.cpp b/src/jsonrpc-remote-machine.cpp
index f5f964678..7045909ce 100644
--- a/src/jsonrpc-remote-machine.cpp
+++ b/src/jsonrpc-remote-machine.cpp
@@ -1162,7 +1162,7 @@ static json jsonrpc_machine_read_memory_handler(const json &j, const std::shared
     auto args = parse_args<uint64_t, uint64_t>(j, param_name);
     auto address = std::get<0>(args);
     auto length = std::get<1>(args);
-    auto data = cartesi::unique_calloc<unsigned char>(length);
+    auto data = cartesi::make_unique_calloc<unsigned char>(length);
     session->handler->machine->read_memory(address, data.get(), length);
     return jsonrpc_response_ok(j, cartesi::encode_base64(data.get(), length));
 }
@@ -1196,7 +1196,7 @@ static json jsonrpc_machine_read_virtual_memory_handler(const json &j, const std
     auto args = parse_args<uint64_t, uint64_t>(j, param_name);
     auto address = std::get<0>(args);
     auto length = std::get<1>(args);
-    auto data = cartesi::unique_calloc<unsigned char>(length);
+    auto data = cartesi::make_unique_calloc<unsigned char>(length);
     session->handler->machine->read_virtual_memory(address, data.get(), length);
     return jsonrpc_response_ok(j, cartesi::encode_base64(data.get(), length));
 }
diff --git a/src/machine.cpp b/src/machine.cpp
index d75c1e1f1..8ef260d47 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -51,7 +51,6 @@
 #include "machine-memory-range-descr.h"
 #include "machine-reg.h"
 #include "machine-runtime-config.h"
-#include "os.h"
 #include "plic-factory.h"
 #include "pma-constants.h"
 #include "pma-defines.h"
@@ -384,7 +383,7 @@ machine::machine(machine_config c, machine_runtime_config r) : m_c{std::move(c)}
         }
         // Auto detect flash drive image length
         if (f.length == UINT64_C(-1)) {
-            auto fp = unique_fopen(f.image_filename.c_str(), "rb");
+            auto fp = make_unique_fopen(f.image_filename.c_str(), "rb");
             if (fseek(fp.get(), 0, SEEK_END) != 0) {
                 throw std::system_error{errno, std::generic_category(),
                     "unable to obtain length of image file '"s + f.image_filename + "' when initializing "s +
@@ -524,11 +523,8 @@ machine::machine(machine_config c, machine_runtime_config r) : m_c{std::move(c)}
     // Initialize TLB device.
     // This must be done after all PMA entries are already registered, so we can lookup page addresses
     if (!m_c.tlb.image_filename.empty()) {
-        unsigned char *buf = os_map_file(m_c.tlb.image_filename.c_str(), PMA_SHADOW_TLB_LENGTH, false);
-        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        const auto &shadow_tlb = *reinterpret_cast<const shadow_tlb_state *>(buf);
-        init_tlb(shadow_tlb);
-        os_unmap_file(buf, PMA_SHADOW_TLB_LENGTH);
+        auto shadow_tlb = make_unique_mmap<shadow_tlb_state>(m_c.tlb.image_filename.c_str(), 1, false /* not shared */);
+        init_tlb(*shadow_tlb);
     } else {
         init_tlb();
     }
@@ -573,7 +569,7 @@ machine::machine(machine_config c, machine_runtime_config r) : m_c{std::move(c)}
 
 static void load_hash(const std::string &dir, machine::hash_type &h) {
     auto name = dir + "/hash";
-    auto fp = unique_fopen(name.c_str(), "rb");
+    auto fp = make_unique_fopen(name.c_str(), "rb");
     if (fread(h.data(), 1, h.size(), fp.get()) != h.size()) {
         throw std::runtime_error{"error reading from '" + name + "'"};
     }
@@ -737,9 +733,9 @@ static void store_device_pma(const machine &m, const pma_entry &pma, const std::
     if (!pma.get_istart_IO()) {
         throw std::runtime_error{"attempt to save non-device PMA"};
     }
-    auto scratch = unique_calloc<unsigned char>(PMA_PAGE_SIZE); // will throw if it fails
+    auto scratch = make_unique_calloc<unsigned char>(PMA_PAGE_SIZE); // will throw if it fails
     auto name = machine_config::get_image_filename(dir, pma.get_start(), pma.get_length());
-    auto fp = unique_fopen(name.c_str(), "wb");
+    auto fp = make_unique_fopen(name.c_str(), "wb");
     for (uint64_t page_start_in_range = 0; page_start_in_range < pma.get_length();
         page_start_in_range += PMA_PAGE_SIZE) {
         const unsigned char *page_data = nullptr;
@@ -762,7 +758,7 @@ static void store_memory_pma(const pma_entry &pma, const std::string &dir) {
         throw std::runtime_error{"attempt to save non-memory PMA"};
     }
     auto name = machine_config::get_image_filename(dir, pma.get_start(), pma.get_length());
-    auto fp = unique_fopen(name.c_str(), "wb");
+    auto fp = make_unique_fopen(name.c_str(), "wb");
     const pma_memory &mem = pma.get_memory();
     if (fwrite(mem.get_host_memory(), 1, pma.get_length(), fp.get()) != pma.get_length()) {
         throw std::runtime_error{"error writing to '" + name + "'"};
@@ -938,7 +934,7 @@ void machine::store_pmas(const machine_config &c, const std::string &dir) const
 
 static void store_hash(const machine::hash_type &h, const std::string &dir) {
     auto name = dir + "/hash";
-    auto fp = unique_fopen(name.c_str(), "wb");
+    auto fp = make_unique_fopen(name.c_str(), "wb");
     if (fwrite(h.data(), 1, h.size(), fp.get()) != h.size()) {
         throw std::runtime_error{"error writing to '" + name + "'"};
     }
@@ -1820,7 +1816,7 @@ bool machine::verify_dirty_page_maps() const {
     static_assert(PMA_PAGE_SIZE == machine_merkle_tree::get_page_size(),
         "PMA and machine_merkle_tree page sizes must match");
     machine_merkle_tree::hasher_type h;
-    auto scratch = unique_calloc<unsigned char>(PMA_PAGE_SIZE, std::nothrow_t{});
+    auto scratch = make_unique_calloc<unsigned char>(PMA_PAGE_SIZE, std::nothrow_t{});
     if (!scratch) {
         return false;
     }
@@ -1885,7 +1881,7 @@ bool machine::update_merkle_tree() const {
         // runtime config or as the hardware supports.
         const uint64_t n = get_task_concurrency(m_r.concurrency.update_merkle_tree);
         const bool succeeded = os_parallel_for(n, [&](int j, const parallel_for_mutex &mutex) -> bool {
-            auto scratch = unique_calloc<unsigned char>(PMA_PAGE_SIZE, std::nothrow_t{});
+            auto scratch = make_unique_calloc<unsigned char>(PMA_PAGE_SIZE, std::nothrow_t{});
             if (!scratch) {
                 return false;
             }
@@ -1949,7 +1945,7 @@ bool machine::update_merkle_tree_page(uint64_t address) {
     pma_entry &pma = find_pma_entry(m_merkle_pmas, address, sizeof(uint64_t));
     const uint64_t page_start_in_range = address - pma.get_start();
     machine_merkle_tree::hasher_type h;
-    auto scratch = unique_calloc<unsigned char>(PMA_PAGE_SIZE, std::nothrow_t{});
+    auto scratch = make_unique_calloc<unsigned char>(PMA_PAGE_SIZE, std::nothrow_t{});
     if (!scratch) {
         return false;
     }
@@ -1999,7 +1995,7 @@ machine::hash_type machine::get_merkle_tree_node_hash(uint64_t address, int log2
         throw std::domain_error{"address not aligned to log2_size"};
     }
     const auto size = UINT64_C(1) << log2_size;
-    auto scratch = unique_calloc<unsigned char>(size);
+    auto scratch = make_unique_calloc<unsigned char>(size);
     read_memory(address, scratch.get(), size);
     machine_merkle_tree::hasher_type h;
     machine_merkle_tree::hash_type hash;
@@ -2064,7 +2060,7 @@ machine_merkle_tree::proof_type machine::get_proof(uint64_t address, int log2_si
     if (log2_size < machine_merkle_tree::get_log2_page_size()) {
         const uint64_t length = UINT64_C(1) << log2_size;
         const pma_entry &pma = find_pma_entry(m_merkle_pmas, address, length);
-        auto scratch = unique_calloc<unsigned char>(PMA_PAGE_SIZE);
+        auto scratch = make_unique_calloc<unsigned char>(PMA_PAGE_SIZE);
         const unsigned char *page_data = nullptr;
         // If the PMA range is empty, we know the desired range is
         // entirely outside of any non-pristine PMA.
@@ -2491,16 +2487,15 @@ interpreter_break_reason machine::log_step(uint64_t mcycle_count, const std::str
 interpreter_break_reason machine::verify_step(const hash_type &root_hash_before, const std::string &filename,
     uint64_t mcycle_count, const hash_type &root_hash_after) {
     auto data_length = os_get_file_length(filename.c_str(), "step log file");
-    auto *data = os_map_file(filename.c_str(), data_length, false /* not shared */);
+    auto data = make_unique_mmap<unsigned char>(filename.c_str(), data_length, false /* not shared */);
     replay_step_state_access::context context;
-    replay_step_state_access a(context, data, data_length, root_hash_before);
+    replay_step_state_access a(context, data.get(), data_length, root_hash_before);
     uint64_t mcycle_end{};
     if (__builtin_add_overflow(a.read_mcycle(), mcycle_count, &mcycle_end)) {
         mcycle_end = UINT64_MAX;
     }
     auto break_reason = interpret(a, mcycle_end);
     a.finish(root_hash_after);
-    os_unmap_file(data, data_length);
     return break_reason;
 }
 
diff --git a/src/merkle-tree-hash.cpp b/src/merkle-tree-hash.cpp
index 3531de036..06f695a14 100644
--- a/src/merkle-tree-hash.cpp
+++ b/src/merkle-tree-hash.cpp
@@ -231,7 +231,7 @@ int main(int argc, char *argv[]) {
     // Read from stdin if no input name was given
     auto input_file = unique_file_ptr{stdin};
     if (input_name != nullptr) {
-        input_file = unique_fopen(input_name, "ro", std::nothrow_t{});
+        input_file = make_unique_fopen(input_name, "ro", std::nothrow_t{});
         if (!input_file) {
             error("unable to open input file '%s'\n", input_name);
             return 1;
@@ -240,7 +240,7 @@ int main(int argc, char *argv[]) {
 
     // Allocate buffer for leaf data
     const uint64_t leaf_size = UINT64_C(1) << log2_leaf_size;
-    auto leaf_buf = unique_calloc<unsigned char>(leaf_size, std::nothrow_t{});
+    auto leaf_buf = make_unique_calloc<unsigned char>(leaf_size, std::nothrow_t{});
     if (!leaf_buf) {
         error("unable to allocate leaf buffer\n");
         return 1;
diff --git a/src/os.cpp b/src/os.cpp
index 736ba928c..3db6d7dbc 100644
--- a/src/os.cpp
+++ b/src/os.cpp
@@ -553,7 +553,7 @@ int os_mkdir(const char *path, [[maybe_unused]] int mode) {
 #endif // HAVE_MKDIR
 }
 
-unsigned char *os_map_file(const char *path, uint64_t length, bool shared) {
+void *os_map_file(const char *path, uint64_t length, bool shared) {
     if ((path == nullptr) || *path == '\0') {
         throw std::runtime_error{"image file path must be specified"s};
     }
@@ -585,8 +585,7 @@ unsigned char *os_map_file(const char *path, uint64_t length, bool shared) {
 
     // Try to map image file to host memory
     const int mflag = shared ? MAP_SHARED : MAP_PRIVATE;
-    auto *host_memory =
-        static_cast<unsigned char *>(mmap(nullptr, length, PROT_READ | PROT_WRITE, mflag, backing_file, 0));
+    void *host_memory = mmap(nullptr, length, PROT_READ | PROT_WRITE, mflag, backing_file, 0);
     if (host_memory == MAP_FAILED) { // NOLINT(cppcoreguidelines-pro-type-cstyle-cast,performance-no-int-to-ptr)
         close(backing_file);
         throw std::system_error{errno, std::generic_category(), "could not map image file '"s + path + "' to memory"s};
@@ -632,7 +631,7 @@ unsigned char *os_map_file(const char *path, uint64_t length, bool shared) {
     }
 
     DWORD dwDesiredAccess = shared ? FILE_MAP_WRITE : FILE_MAP_COPY;
-    auto *host_memory = static_cast<unsigned char *>(MapViewOfFile(hFileMappingObject, dwDesiredAccess, 0, 0, length));
+    void *host_memory = MapViewOfFile(hFileMappingObject, dwDesiredAccess, 0, 0, length);
     if (!host_memory) {
         _close(backing_file);
         throw std::system_error{errno, std::generic_category(), "could not map image file '"s + path + "' to memory"s};
@@ -683,7 +682,7 @@ unsigned char *os_map_file(const char *path, uint64_t length, bool shared) {
 #endif // HAVE_MMAP
 }
 
-void os_unmap_file(unsigned char *host_memory, [[maybe_unused]] uint64_t length) {
+void os_unmap_file(void *host_memory, [[maybe_unused]] uint64_t length) {
 #ifdef HAVE_MMAP
     munmap(host_memory, length);
 
@@ -801,7 +800,7 @@ void os_sleep_us(uint64_t timeout_us) {
 }
 
 int64_t os_get_file_length(const char *filename, const char *text) {
-    auto fp = unique_fopen(filename, "rb");
+    auto fp = make_unique_fopen(filename, "rb");
     if (fseek(fp.get(), 0, SEEK_END) != 0) {
         throw std::system_error{errno, std::generic_category(),
             "unable to obtain length of file '"s + filename + "' "s + text};
diff --git a/src/os.h b/src/os.h
index 8c3b144d9..36d58195d 100644
--- a/src/os.h
+++ b/src/os.h
@@ -94,10 +94,10 @@ void os_silence_putchar(bool yes);
 int os_mkdir(const char *path, int mode);
 
 /// \brief Maps a file to memory
-unsigned char *os_map_file(const char *path, uint64_t length, bool shared);
+void *os_map_file(const char *path, uint64_t length, bool shared);
 
 /// \brief Unmaps a file from memory
-void os_unmap_file(unsigned char *host_memory, uint64_t length);
+void os_unmap_file(void *host_memory, uint64_t length);
 
 /// \brief Get time elapsed since its first call with microsecond precision
 int64_t os_now_us();
diff --git a/src/pma-constants.h b/src/pma-constants.h
index 4dd234df5..38d9df885 100644
--- a/src/pma-constants.h
+++ b/src/pma-constants.h
@@ -69,7 +69,6 @@ enum PMA_ranges : uint64_t {
 enum PMA_constants : uint64_t {
     PMA_PAGE_SIZE_LOG2 = EXPAND_UINT64_C(PMA_PAGE_SIZE_LOG2_DEF), ///< log<sub>2</sub> of physical memory page size.
     PMA_PAGE_SIZE = (UINT64_C(1) << PMA_PAGE_SIZE_LOG2_DEF),      ///< Physical memory page size.
-    PMA_WORD_SIZE = EXPAND_UINT64_C(PMA_WORD_SIZE_DEF),           ///< Physical memory word size.
     PMA_MAX = EXPAND_UINT64_C(PMA_MAX_DEF)                        ///< Maximum number of PMAs
 };
 
diff --git a/src/pma-defines.h b/src/pma-defines.h
index 8a69bdbdb..849a92c30 100644
--- a/src/pma-defines.h
+++ b/src/pma-defines.h
@@ -48,7 +48,6 @@
 #define PMA_RAM_START_DEF 0x80000000 ///< RAM start address
 
 #define PMA_PAGE_SIZE_LOG2_DEF 12 ///< log<sub>2</sub> of physical memory page size.
-#define PMA_WORD_SIZE_DEF 8       ///< Physical memory word size.
 #define PMA_MAX_DEF 32            ///< Maximum number of PMAs
 #define PMA_PLIC_MAX_IRQ_DEF 31   ///< Maximum PLIC interrupt
 
diff --git a/src/pma.cpp b/src/pma.cpp
index 5e39cdcb2..6f566cec5 100644
--- a/src/pma.cpp
+++ b/src/pma.cpp
@@ -37,48 +37,18 @@ namespace cartesi {
 
 using namespace std::string_literals;
 
-void pma_memory::release() {
-    if (m_mmapped) {
-        os_unmap_file(m_host_memory, m_length);
-        m_mmapped = false;
-    } else {
-        std::free(m_host_memory); // NOLINT(cppcoreguidelines-no-malloc,hicpp-no-malloc)
-    }
-    m_host_memory = nullptr;
-    m_length = 0;
-}
-
-pma_memory::~pma_memory() {
-    release();
-}
-
-pma_memory::pma_memory(pma_memory &&other) noexcept :
-    m_length{other.m_length},
-    m_host_memory{other.m_host_memory},
-    m_mmapped{other.m_mmapped} {
-    // set other to safe state
-    other.m_host_memory = nullptr;
-    other.m_mmapped = false;
-    other.m_length = 0;
-}
-
-pma_memory::pma_memory(const std::string &description, uint64_t length, const callocd & /*c*/) :
-    m_length{length},
-    m_host_memory{nullptr},
-    m_mmapped{false} {
-    // use calloc to improve performance
-    // NOLINTNEXTLINE(cppcoreguidelines-no-malloc,hicpp-no-malloc,cppcoreguidelines-prefer-member-initializer)
-    m_host_memory = static_cast<unsigned char *>(std::calloc(1, length));
-    if (m_host_memory == nullptr) {
-        throw std::runtime_error{"error allocating memory for "s + description};
-    }
+pma_memory::pma_memory(const std::string &description, uint64_t length, const callocd & /*c*/) try :
+    m_ptr{make_unique_calloc<unsigned char>(length)},
+    m_host_memory{std::get<callocd_ptr>(m_ptr).get()} {
+} catch (std::exception &e) {
+    throw std::runtime_error{e.what() + " when initializing "s + description};
 }
 
 pma_memory::pma_memory(const std::string &description, uint64_t length, const std::string &path, const callocd &c) :
     pma_memory{description, length, c} {
     // Try to load image file, if any
     if (!path.empty()) {
-        auto fp = unique_fopen(path.c_str(), "rb", std::nothrow_t{});
+        auto fp = make_unique_fopen(path.c_str(), "rb", std::nothrow_t{});
         if (!fp) {
             throw std::system_error{errno, std::generic_category(),
                 "error opening image file '"s + path + "' when initializing "s + description};
@@ -88,47 +58,28 @@ pma_memory::pma_memory(const std::string &description, uint64_t length, const st
             throw std::system_error{errno, std::generic_category(),
                 "error obtaining length of image file '"s + path + "' when initializing "s + description};
         }
-        auto file_length = ftell(fp.get());
+        const auto file_length = static_cast<uint64_t>(ftello(fp.get()));
         if (fseek(fp.get(), 0, SEEK_SET) != 0) {
             throw std::system_error{errno, std::generic_category(),
                 "error obtaining length of image file '"s + path + "' when initializing "s + description};
         }
         // Check against PMA range size
-        if (static_cast<uint64_t>(file_length) > length) {
+        if (file_length > length) {
             throw std::runtime_error{"image file '"s + path + "' of "s + description + " is too large for range"s};
         }
         // Read to host memory
-        std::ignore = fread(m_host_memory, 1, length, fp.get());
-        if (ferror(fp.get()) != 0) {
-            throw std::system_error{errno, std::generic_category(),
-                "error reading from image file '"s + path + "' when initializing "s + description};
+        const auto read_length = static_cast<uint64_t>(fread(m_host_memory, 1, length, fp.get()));
+        if (read_length != file_length) {
+            throw std::runtime_error{"error reading from image file '"s + path + "' when initializing "s + description};
         }
     }
 }
 
-pma_memory::pma_memory(const std::string &description, uint64_t length, const std::string &path, const mmapd &m) :
-    m_length{length},
-    m_host_memory{nullptr},
-    m_mmapped{false} {
-    try {
-        m_host_memory = os_map_file(path.c_str(), length, m.shared);
-        m_mmapped = true;
-    } catch (std::exception &e) {
-        throw std::runtime_error{e.what() + " when initializing "s + description};
-    }
-}
-
-pma_memory &pma_memory::operator=(pma_memory &&other) noexcept {
-    release();
-    // copy from other
-    m_host_memory = other.m_host_memory;
-    m_mmapped = other.m_mmapped;
-    m_length = other.m_length;
-    // set other to safe state
-    other.m_host_memory = nullptr;
-    other.m_mmapped = false;
-    other.m_length = 0;
-    return *this;
+pma_memory::pma_memory(const std::string &description, uint64_t length, const std::string &path, const mmapd &m) try :
+    m_ptr{make_unique_mmap<unsigned char>(path.c_str(), length, m.shared)},
+    m_host_memory{std::get<mmapd_ptr>(m_ptr).get()} {
+} catch (std::exception &e) {
+    throw std::runtime_error{e.what() + " when initializing "s + description};
 }
 
 uint64_t pma_entry::get_istart() const {
diff --git a/src/pma.h b/src/pma.h
index 74f96fa05..f30b2e720 100644
--- a/src/pma.h
+++ b/src/pma.h
@@ -28,6 +28,7 @@
 
 #include "pma-constants.h"
 #include "pma-driver.h"
+#include "unique-c-ptr.h"
 
 namespace cartesi {
 
@@ -85,10 +86,7 @@ class pma_device final {
 
     /// \brief Returns context to pass to callbacks.
     void *get_context() const {
-        // Discard qualifier on purpose because the context
-        // is none of our business.
-        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-const-cast)
-        return const_cast<void *>(m_context);
+        return m_context;
     }
 
     /// \brief Returns pointer to driver with callbacks
@@ -105,12 +103,16 @@ class pma_device final {
 /// \brief Data for memory ranges.
 class pma_memory final {
 
-    uint64_t m_length;            ///< Length of memory range (copy of PMA length field).
-    unsigned char *m_host_memory; ///< Start of associated memory region in host.
-    bool m_mmapped;               ///< True if memory was mapped from a file.
+    using callocd_ptr = unique_calloc_ptr<unsigned char>;
+    using mmapd_ptr = unique_mmap_ptr<unsigned char>;
 
-    /// \brief Close file and/or release memory.
-    void release();
+    std::variant<std::monostate, ///< Before initialization
+        callocd_ptr,             ///< Automatic pointer for calloced memory
+        mmapd_ptr                ///< Automatic pointer for mmapped memory
+        >
+        m_ptr;
+
+    unsigned char *m_host_memory; ///< Start of associated memory region in host.
 
 public:
     /// \brief Mmap'd range data (shared or not).
@@ -148,13 +150,13 @@ class pma_memory final {
     pma_memory &operator=(const pma_memory &other) = delete;
 
     /// \brief Move constructor
-    pma_memory(pma_memory &&other) noexcept;
+    pma_memory(pma_memory &&other) noexcept = default;
 
     /// \brief Move assignment
-    pma_memory &operator=(pma_memory &&other) noexcept;
+    pma_memory &operator=(pma_memory &&other) noexcept = default;
 
-    /// \brief Destructor
-    ~pma_memory();
+    /// \brief Default destructor
+    ~pma_memory() = default;
 
     /// \brief Returns start of associated memory region in host
     unsigned char *get_host_memory() {
@@ -165,16 +167,8 @@ class pma_memory final {
     const unsigned char *get_host_memory() const {
         return m_host_memory;
     }
-
-    /// \brief Returns copy of PMA length field (needed for munmap).
-    uint64_t get_length() const {
-        return m_length;
-    }
 };
 
-/// \brief Data for empty memory ranges (nothing, really)
-struct pma_empty final {};
-
 /// \brief Physical Memory Attribute entry.
 /// \details The target's physical memory layout is described by an
 /// array of PMA entries.
@@ -184,7 +178,7 @@ class pma_entry final {
     struct flags {
         // bool M = std::holds_alternative<pma_memory>(data);
         // bool IO = std::holds_alternative<pma_device>(data);
-        // bool E = std::holds_alternative<pma_empty>(data);
+        // bool E = std::holds_alternative<std::monostate>(data);
         bool R;
         bool W;
         bool X;
@@ -204,9 +198,9 @@ class pma_entry final {
 
     std::vector<uint8_t> m_dirty_page_map; ///< Map of dirty pages.
 
-    std::variant<pma_empty, ///< Data specific to E ranges
-        pma_device,         ///< Data specific to IO ranges
-        pma_memory          ///< Data specific to M ranges
+    std::variant<std::monostate, ///< No data (E ranges)
+        pma_device,              ///< Data specific to IO ranges
+        pma_memory               ///< Data specific to M ranges
         >
         m_data;
 
@@ -233,20 +227,13 @@ class pma_entry final {
         m_index{PMA_MAX},
         m_flags{},
         m_peek{pma_peek_error},
-        m_data{pma_empty{}} {
+        m_data{std::monostate{}} {
         ;
     }
 
     /// \brief Default constructor creates an empty entry spanning an empty range
     /// \param description Informative description of PMA entry for use in error messages
-    explicit pma_entry(std::string description = {}) :
-        m_description{std::move(description)},
-        m_start{0},
-        m_length{0},
-        m_index{PMA_MAX},
-        m_flags{},
-        m_peek{pma_peek_error},
-        m_data{pma_empty{}} {
+    explicit pma_entry(std::string description = "empty") : pma_entry{std::move(description), 0, 0} {
         ;
     }
 
@@ -322,16 +309,6 @@ class pma_entry final {
         return m_peek;
     }
 
-    /// \returns data specific to E ranges
-    const pma_empty &get_empty() const {
-        return std::get<pma_empty>(m_data);
-    }
-
-    /// \returns data specific to E ranges
-    pma_empty &get_empty() {
-        return std::get<pma_empty>(m_data);
-    }
-
     /// \returns data specific to M ranges
     const pma_memory &get_memory() const {
         return std::get<pma_memory>(m_data);
@@ -342,12 +319,12 @@ class pma_entry final {
         return std::get<pma_memory>(m_data);
     }
 
-    /// \returns data specific to IO ranges (cannot throw exceptions).
+    /// \returns data specific to memory ranges (cannot throw exceptions, but will crash if not a memory range).
     pma_memory &get_memory_noexcept() {
         return *std::get_if<pma_memory>(&m_data);
     }
 
-    /// \returns data specific to IO ranges (cannot throw exceptions).
+    /// \returns data specific to memory ranges (cannot throw exceptions, but will crash if not a memory range).
     const pma_memory &get_memory_noexcept() const {
         return *std::get_if<pma_memory>(&m_data);
     }
@@ -362,12 +339,12 @@ class pma_entry final {
         return std::get<pma_device>(m_data);
     }
 
-    /// \returns data specific to IO ranges (cannot throw exceptions).
+    /// \returns data specific to IO ranges (cannot throw exceptions, but will crash if not an IO range).
     const pma_device &get_device_noexcept() const {
         return *std::get_if<pma_device>(&m_data);
     }
 
-    /// \returns data specific to IO ranges (cannot throw exceptions).
+    /// \returns data specific to IO ranges (cannot throw exceptions, but will crash if not an IO range).
     pma_device &get_device_noexcept() {
         return *std::get_if<pma_device>(&m_data);
     }
@@ -399,7 +376,7 @@ class pma_entry final {
 
     /// \brief Tells if PMA is an empty range
     bool get_istart_E() const {
-        return std::holds_alternative<pma_empty>(m_data);
+        return std::holds_alternative<std::monostate>(m_data);
     }
 
     /// \brief Tells if PMA range is readable
@@ -433,15 +410,16 @@ class pma_entry final {
     }
 
     /// \brief Mark a given page as dirty
-    /// \param address_in_range Any address within page in range
-    void mark_dirty_page(uint64_t address_in_range) {
+    /// \param offset_in_range Any offset in range within desired page
+    void mark_dirty_page(uint64_t offset_in_range) {
         if (!m_dirty_page_map.empty()) {
-            auto page_number = address_in_range >> PMA_constants::PMA_PAGE_SIZE_LOG2;
-            auto map_index = page_number >> 3;
+            auto page_index = offset_in_range >> PMA_constants::PMA_PAGE_SIZE_LOG2;
+            auto map_index = page_index >> 3;
             assert(map_index < m_dirty_page_map.size());
-            m_dirty_page_map[map_index] |= (1 << (page_number & 7));
+            m_dirty_page_map[map_index] |= (1 << (page_index & 7));
         }
     }
+
     /// \brief Mark all pages in rage as dirty
     /// \param address Start address
     /// \param size Size of range
@@ -466,25 +444,25 @@ class pma_entry final {
     }
 
     /// \brief Mark a given page as clean
-    /// \param address_in_range Any address within page in range
-    void mark_clean_page(uint64_t address_in_range) {
+    /// \param offset_in_range Any offset in range within desired page
+    void mark_clean_page(uint64_t offset_in_range) {
         if (!m_dirty_page_map.empty()) {
-            auto page_number = address_in_range >> PMA_constants::PMA_PAGE_SIZE_LOG2;
-            auto map_index = page_number >> 3;
+            auto page_index = offset_in_range >> PMA_constants::PMA_PAGE_SIZE_LOG2;
+            auto map_index = page_index >> 3;
             assert(map_index < m_dirty_page_map.size());
-            m_dirty_page_map[map_index] &= ~(1 << (page_number & 7));
+            m_dirty_page_map[map_index] &= ~(1 << (page_index & 7));
         }
     }
 
     /// \brief Checks if a given page is marked dirty
-    /// \param address_in_range Any address within page in range
+    /// \param offset_in_range Any offset in range within desired page
     /// \returns true if dirty, false if clean
-    bool is_page_marked_dirty(uint64_t address_in_range) const {
+    bool is_page_marked_dirty(uint64_t offset_in_range) const {
         if (!m_dirty_page_map.empty()) {
-            auto page_number = address_in_range >> PMA_constants::PMA_PAGE_SIZE_LOG2;
-            auto map_index = page_number >> 3;
+            auto page_index = offset_in_range >> PMA_constants::PMA_PAGE_SIZE_LOG2;
+            auto map_index = page_index >> 3;
             assert(map_index < m_dirty_page_map.size());
-            return (m_dirty_page_map[map_index] & (1 << (page_number & 7))) != 0;
+            return (m_dirty_page_map[map_index] & (1 << (page_index & 7))) != 0;
         }
         return true;
     }
@@ -511,7 +489,7 @@ class pma_entry final {
         return address >= get_start() && get_length() >= length && address - get_start() <= get_length() - length;
     }
 
-    /// \brief  Writes data to pma memory
+    /// \brief Writes data to pma memory
     /// \param paddr Destination address within pma range
     /// \param data Source data
     /// \param size Data size
diff --git a/src/record-step-state-access.h b/src/record-step-state-access.h
index e5508497e..d747ed7ff 100644
--- a/src/record-step-state-access.h
+++ b/src/record-step-state-access.h
@@ -103,7 +103,7 @@ class record_step_state_access :
         // We store the page index, instead of the page address.
         // Scratch area is used by the replay to store page hashes, which change during replay
         // This is to work around the lack of dynamic memory allocation when replaying the log in microarchitectures
-        auto fp = unique_fopen(m_context.filename.c_str(), "wb");
+        auto fp = make_unique_fopen(m_context.filename.c_str(), "wb");
         if (fwrite(&page_count, sizeof(page_count), 1, fp.get()) != 1) {
             throw std::runtime_error("Could not write page count to log file");
         }
diff --git a/src/replay-send-cmio-state-access.h b/src/replay-send-cmio-state-access.h
index d9b2d1e59..57354d237 100644
--- a/src/replay-send-cmio-state-access.h
+++ b/src/replay-send-cmio-state-access.h
@@ -326,7 +326,7 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
         const auto &written_hash = access.get_written_hash().value();
         // compute hash of data argument padded with zeroes
         hash_type computed_data_hash{};
-        auto scratch = unique_calloc<unsigned char>(write_length, std::nothrow_t{});
+        auto scratch = make_unique_calloc<unsigned char>(write_length, std::nothrow_t{});
         if (!scratch) {
             throw std::runtime_error("Could not allocate scratch memory");
         }
diff --git a/src/replay-step-state-access.h b/src/replay-step-state-access.h
index ace83f7fc..338965c3c 100644
--- a/src/replay-step-state-access.h
+++ b/src/replay-step-state-access.h
@@ -122,7 +122,7 @@ class replay_step_state_access :
         if (!validate_and_advance_offset(log_size, 0, sizeof(m_context.page_count), 1, &first_page_offset)) {
             interop_throw_runtime_error("page count past end of step log");
         }
-        memcpy(&m_context.page_count, log_image, sizeof(m_context.page_count));
+        m_context.page_count = aliased_aligned_read<uint64_t, uint8_t>(log_image);
         if (m_context.page_count == 0) {
             interop_throw_runtime_error("page count is zero");
         }
@@ -140,7 +140,7 @@ class replay_step_state_access :
                 &first_sibling_offset)) {
             interop_throw_runtime_error("sibling count past end of step log");
         }
-        memcpy(&m_context.sibling_count, log_image + sibling_count_offset, sizeof(m_context.sibling_count));
+        m_context.sibling_count = aliased_aligned_read<uint64_t, uint8_t>(log_image + sibling_count_offset);
 
         // set sibling hashes
         if (!validate_and_advance_offset(log_size, first_sibling_offset, sizeof(hash_type), m_context.sibling_count,
diff --git a/src/unique-c-ptr.h b/src/unique-c-ptr.h
index 077ba9c05..d2ee9368f 100644
--- a/src/unique-c-ptr.h
+++ b/src/unique-c-ptr.h
@@ -14,9 +14,10 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#ifndef UNIQUE_C_PTR
-#define UNIQUE_C_PTR
+#ifndef UNIQUE_C_PTR_H
+#define UNIQUE_C_PTR_H
 
+#include "os.h"
 #include <cerrno>
 #include <cstdio>
 #include <cstdlib>
@@ -29,11 +30,14 @@
 namespace cartesi {
 
 namespace detail {
+
+//??D Cannot use lambda expression to create the deleters because lambda expressions are not copy-assignable
+//??D and we need them to be so we can put pointers using these deleters into containers
+
 struct free_deleter {
     template <typename T>
-    void operator()(T *p) const {
-        // NOLINTNEXTLINE(cppcoreguidelines-no-malloc,hicpp-no-malloc,cppcoreguidelines-pro-type-const-cast)
-        std::free(const_cast<std::remove_const_t<T> *>(p));
+    void operator()(T *ptr) const {
+        std::free(ptr); // NOLINT(cppcoreguidelines-no-malloc,hicpp-no-malloc)
     }
 };
 
@@ -42,6 +46,16 @@ struct fclose_deleter {
         std::ignore = std::fclose(p);
     }
 };
+
+struct mmap_deleter {
+    size_t m_size;
+    explicit mmap_deleter(size_t size) : m_size(size) {};
+    template <typename T>
+    void operator()(T *ptr) const {
+        os_unmap_file(ptr, m_size);
+    }
+};
+
 } // namespace detail
 
 template <typename T>
@@ -50,22 +64,25 @@ using unique_calloc_ptr = std::unique_ptr<T, detail::free_deleter>;
 using unique_file_ptr = std::unique_ptr<FILE, detail::fclose_deleter>;
 
 template <typename T>
-static inline unique_calloc_ptr<T> unique_calloc(size_t nmemb) {
+using unique_mmap_ptr = std::unique_ptr<T, detail::mmap_deleter>;
+
+template <typename T>
+static inline auto make_unique_calloc(size_t nmemb) {
     // NOLINTNEXTLINE(cppcoreguidelines-no-malloc,hicpp-no-malloc)
     T *ptr = static_cast<T *>(calloc(nmemb, sizeof(T)));
-    if (!ptr) {
+    if (ptr == nullptr) {
         throw std::bad_alloc{}; // LCOV_EXCL_LINE
     }
     return unique_calloc_ptr<T>(ptr);
 }
 
 template <typename T>
-static inline unique_calloc_ptr<T> unique_calloc(size_t nmemb, const std::nothrow_t & /*tag*/) {
+static inline auto make_unique_calloc(size_t nmemb, const std::nothrow_t & /*tag*/) {
     // NOLINTNEXTLINE(cppcoreguidelines-no-malloc,hicpp-no-malloc)
     return unique_calloc_ptr<T>(static_cast<T *>(calloc(nmemb, sizeof(T))));
 }
 
-static inline unique_file_ptr unique_fopen(const char *pathname, const char *mode) {
+static inline auto make_unique_fopen(const char *pathname, const char *mode) {
     FILE *fp = fopen(pathname, mode);
     if (fp == nullptr) {
         throw std::system_error(errno, std::generic_category(),
@@ -74,10 +91,17 @@ static inline unique_file_ptr unique_fopen(const char *pathname, const char *mod
     return unique_file_ptr{fp};
 }
 
-static inline unique_file_ptr unique_fopen(const char *pathname, const char *mode, const std::nothrow_t & /*tag*/) {
+static inline auto make_unique_fopen(const char *pathname, const char *mode, const std::nothrow_t & /*tag*/) {
     return unique_file_ptr{fopen(pathname, mode)};
 }
 
+template <typename T>
+static inline auto make_unique_mmap(const char *pathname, size_t nmemb, bool shared) {
+    const size_t size = nmemb * sizeof(T);
+    T *ptr = static_cast<T *>(os_map_file(pathname, size, shared)); // os_map_file throws on error
+    return unique_mmap_ptr<T>(ptr, detail::mmap_deleter{size});
+}
+
 } // namespace cartesi
 
 #endif
diff --git a/tests/misc/test-merkle-tree-hash.cpp b/tests/misc/test-merkle-tree-hash.cpp
index 0d3c93650..1989deff9 100644
--- a/tests/misc/test-merkle-tree-hash.cpp
+++ b/tests/misc/test-merkle-tree-hash.cpp
@@ -201,7 +201,7 @@ int main(int argc, char *argv[]) try {
     // Read from stdin if no input name was given
     auto input_file = unique_file_ptr{stdin};
     if (input_name != nullptr) {
-        input_file = unique_fopen(input_name, "ro", std::nothrow_t{});
+        input_file = make_unique_fopen(input_name, "ro", std::nothrow_t{});
         if (!input_file) {
             error("unable to open input file '%s'\n", input_name);
             return 1;
@@ -210,7 +210,7 @@ int main(int argc, char *argv[]) try {
 
     // Allocate buffer for leaf data
     const uint64_t leaf_size = UINT64_C(1) << log2_leaf_size; // NOLINT(misc-include-cleaner)
-    auto leaf_buf = unique_calloc<unsigned char>(leaf_size, std::nothrow_t{});
+    auto leaf_buf = make_unique_calloc<unsigned char>(leaf_size, std::nothrow_t{});
     if (!leaf_buf) {
         error("unable to allocate leaf buffer\n");
         return 1;
diff --git a/uarch/compute-uarch-pristine-hash.cpp b/uarch/compute-uarch-pristine-hash.cpp
index c68f46184..caf0c09b3 100644
--- a/uarch/compute-uarch-pristine-hash.cpp
+++ b/uarch/compute-uarch-pristine-hash.cpp
@@ -70,7 +70,7 @@ int main(int argc, char *argv[]) try {
     }
 
     // Allocate scratch page buffer
-    auto scratch = unique_calloc<unsigned char>(PMA_PAGE_SIZE, std::nothrow_t{});
+    auto scratch = make_unique_calloc<unsigned char>(PMA_PAGE_SIZE, std::nothrow_t{});
     if (!scratch) {
         throw std::runtime_error("Could not allocate scratch memory");
     }

From c0e7254eaf61d3ef84a753921feeba651fc946ad Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Fri, 14 Feb 2025 17:58:48 +0000
Subject: [PATCH 20/82] refactor: factor machine constructor

---
 src/machine.cpp           | 459 ++++++++++++++++++--------------------
 src/machine.h             | 126 +++++++----
 src/shadow-pmas-factory.h |   2 +-
 3 files changed, 308 insertions(+), 279 deletions(-)

diff --git a/src/machine.cpp b/src/machine.cpp
index 8ef260d47..d542583db 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -149,22 +149,22 @@ pma_entry machine::make_flash_drive_pma_entry(const std::string &description, co
     return make_memory_range_pma_entry(description, c).set_flags(m_flash_drive_flags);
 }
 
-pma_entry machine::make_cmio_rx_buffer_pma_entry(const cmio_config &c) {
+pma_entry machine::make_cmio_rx_buffer_pma_entry(const cmio_buffer_config &c) {
     const auto description = "cmio rx buffer memory range"s;
-    if (!c.rx_buffer.image_filename.empty()) {
+    if (!c.image_filename.empty()) {
         return make_mmapd_memory_pma_entry(description, PMA_CMIO_RX_BUFFER_START, PMA_CMIO_RX_BUFFER_LENGTH,
-            c.rx_buffer.image_filename, c.rx_buffer.shared)
+            c.image_filename, c.shared)
             .set_flags(m_cmio_rx_buffer_flags);
     }
     return make_callocd_memory_pma_entry(description, PMA_CMIO_RX_BUFFER_START, PMA_CMIO_RX_BUFFER_LENGTH)
         .set_flags(m_cmio_rx_buffer_flags);
 }
 
-pma_entry machine::make_cmio_tx_buffer_pma_entry(const cmio_config &c) {
+pma_entry machine::make_cmio_tx_buffer_pma_entry(const cmio_buffer_config &c) {
     const auto description = "cmio tx buffer memory range"s;
-    if (!c.tx_buffer.image_filename.empty()) {
+    if (!c.image_filename.empty()) {
         return make_mmapd_memory_pma_entry(description, PMA_CMIO_TX_BUFFER_START, PMA_CMIO_TX_BUFFER_LENGTH,
-            c.tx_buffer.image_filename, c.tx_buffer.shared)
+            c.image_filename, c.shared)
             .set_flags(m_cmio_tx_buffer_flags);
     }
     return make_callocd_memory_pma_entry(description, PMA_CMIO_TX_BUFFER_START, PMA_CMIO_TX_BUFFER_LENGTH)
@@ -235,44 +235,24 @@ void machine::replace_memory_range(const memory_range_config &range) {
     throw std::invalid_argument{"attempt to replace inexistent memory range"};
 }
 
-void machine::init_tlb() {
-    for (auto set_index : {TLB_CODE, TLB_READ, TLB_WRITE}) {
-        for (uint64_t slot_index = 0; slot_index < TLB_SET_SIZE; ++slot_index) {
-            write_tlb(set_index, slot_index, TLB_INVALID_PAGE, host_addr{}, TLB_INVALID_PMA_INDEX);
-        }
-    }
-}
-
-void machine::init_tlb(const shadow_tlb_state &shadow_tlb) {
-    for (auto set_index : {TLB_CODE, TLB_READ, TLB_WRITE}) {
-        for (uint64_t slot_index = 0; slot_index < TLB_SET_SIZE; ++slot_index) {
-            const auto vaddr_page = shadow_tlb[set_index][slot_index].vaddr_page;
-            const auto vp_offset = shadow_tlb[set_index][slot_index].vp_offset;
-            const auto pma_index = shadow_tlb[set_index][slot_index].pma_index;
-            check_shadow_tlb(set_index, slot_index, vaddr_page, vp_offset, pma_index, "stored TLB is corrupt: "s);
-            write_shadow_tlb(set_index, slot_index, vaddr_page, vp_offset, pma_index);
-        }
-    }
-}
-
-void machine::init_uarch(const uarch_config &config) {
+void machine::init_uarch(const uarch_config &c) {
     using reg = machine_reg;
-    write_reg(reg::uarch_pc, config.processor.pc);
-    write_reg(reg::uarch_cycle, config.processor.cycle);
-    write_reg(reg::uarch_halt_flag, config.processor.halt_flag);
+    write_reg(reg::uarch_pc, c.processor.pc);
+    write_reg(reg::uarch_cycle, c.processor.cycle);
+    write_reg(reg::uarch_halt_flag, c.processor.halt_flag);
     // General purpose registers
     for (int i = 1; i < UARCH_X_REG_COUNT; i++) {
-        write_reg(machine_reg_enum(reg::uarch_x0, i), config.processor.x[i]);
+        write_reg(machine_reg_enum(reg::uarch_x0, i), c.processor.x[i]);
     }
     // Register shadow state
     m_us.shadow_state = make_shadow_uarch_state_pma_entry(PMA_SHADOW_UARCH_STATE_START, PMA_SHADOW_UARCH_STATE_LENGTH);
     // Register RAM
     constexpr auto ram_description = "uarch RAM";
-    if (!config.ram.image_filename.empty()) {
+    if (!c.ram.image_filename.empty()) {
         // Load RAM image from file
-        m_us.ram = make_callocd_memory_pma_entry(ram_description, PMA_UARCH_RAM_START, UARCH_RAM_LENGTH,
-            config.ram.image_filename)
-                       .set_flags(m_ram_flags);
+        m_us.ram =
+            make_callocd_memory_pma_entry(ram_description, PMA_UARCH_RAM_START, UARCH_RAM_LENGTH, c.ram.image_filename)
+                .set_flags(m_ram_flags);
     } else {
         // Load embedded pristine RAM image
         m_us.ram = make_callocd_memory_pma_entry(ram_description, PMA_UARCH_RAM_START, PMA_UARCH_RAM_LENGTH)
@@ -284,98 +264,85 @@ void machine::init_uarch(const uarch_config &config) {
     }
 }
 
-// ??D It is best to leave the std::move() on r because it may one day be necessary!
-// NOLINTNEXTLINE(hicpp-move-const-arg,performance-move-const-arg)
-machine::machine(machine_config c, machine_runtime_config r) : m_c{std::move(c)}, m_r{std::move(r)} {
-
-    init_uarch(m_c.uarch);
+void machine::init_processor(processor_config &p, const machine_runtime_config &r) {
 
-    if (m_c.processor.marchid == UINT64_C(-1)) {
-        m_c.processor.marchid = MARCHID_INIT;
+    if (p.marchid == UINT64_C(-1)) {
+        p.marchid = MARCHID_INIT;
     }
 
-    if (m_c.processor.marchid != MARCHID_INIT && !m_r.skip_version_check) {
+    if (p.marchid != MARCHID_INIT && !r.skip_version_check) {
         throw std::invalid_argument{"marchid mismatch, emulator version is incompatible"};
     }
 
-    if (m_c.processor.mvendorid == UINT64_C(-1)) {
-        m_c.processor.mvendorid = MVENDORID_INIT;
+    if (p.mvendorid == UINT64_C(-1)) {
+        p.mvendorid = MVENDORID_INIT;
     }
 
-    if (m_c.processor.mvendorid != MVENDORID_INIT && !m_r.skip_version_check) {
+    if (p.mvendorid != MVENDORID_INIT && !r.skip_version_check) {
         throw std::invalid_argument{"mvendorid mismatch, emulator version is incompatible"};
     }
 
-    if (m_c.processor.mimpid == UINT64_C(-1)) {
-        m_c.processor.mimpid = MIMPID_INIT;
+    if (p.mimpid == UINT64_C(-1)) {
+        p.mimpid = MIMPID_INIT;
     }
 
-    if (m_c.processor.mimpid != MIMPID_INIT && !m_r.skip_version_check) {
+    if (p.mimpid != MIMPID_INIT && !r.skip_version_check) {
         throw std::invalid_argument{"mimpid mismatch, emulator version is incompatible"};
     }
 
-    m_s.soft_yield = m_r.soft_yield;
-
     // General purpose registers
     for (int i = 1; i < X_REG_COUNT; i++) {
-        write_reg(machine_reg_enum(reg::x0, i), m_c.processor.x[i]);
+        write_reg(machine_reg_enum(reg::x0, i), p.x[i]);
     }
 
     // Floating-point registers
     for (int i = 0; i < F_REG_COUNT; i++) {
-        write_reg(machine_reg_enum(reg::f0, i), m_c.processor.f[i]);
+        write_reg(machine_reg_enum(reg::f0, i), p.f[i]);
     }
 
     // Named registers
-    write_reg(reg::pc, m_c.processor.pc);
-    write_reg(reg::fcsr, m_c.processor.fcsr);
-    write_reg(reg::mcycle, m_c.processor.mcycle);
-    write_reg(reg::icycleinstret, m_c.processor.icycleinstret);
-    write_reg(reg::mstatus, m_c.processor.mstatus);
-    write_reg(reg::mtvec, m_c.processor.mtvec);
-    write_reg(reg::mscratch, m_c.processor.mscratch);
-    write_reg(reg::mepc, m_c.processor.mepc);
-    write_reg(reg::mcause, m_c.processor.mcause);
-    write_reg(reg::mtval, m_c.processor.mtval);
-    write_reg(reg::misa, m_c.processor.misa);
-    write_reg(reg::mie, m_c.processor.mie);
-    write_reg(reg::mip, m_c.processor.mip);
-    write_reg(reg::medeleg, m_c.processor.medeleg);
-    write_reg(reg::mideleg, m_c.processor.mideleg);
-    write_reg(reg::mcounteren, m_c.processor.mcounteren);
-    write_reg(reg::menvcfg, m_c.processor.menvcfg);
-    write_reg(reg::stvec, m_c.processor.stvec);
-    write_reg(reg::sscratch, m_c.processor.sscratch);
-    write_reg(reg::sepc, m_c.processor.sepc);
-    write_reg(reg::scause, m_c.processor.scause);
-    write_reg(reg::stval, m_c.processor.stval);
-    write_reg(reg::satp, m_c.processor.satp);
-    write_reg(reg::scounteren, m_c.processor.scounteren);
-    write_reg(reg::senvcfg, m_c.processor.senvcfg);
-    write_reg(reg::ilrsc, m_c.processor.ilrsc);
-    write_reg(reg::iprv, m_c.processor.iprv);
-    write_reg(reg::iflags_X, m_c.processor.iflags_X);
-    write_reg(reg::iflags_Y, m_c.processor.iflags_Y);
-    write_reg(reg::iflags_H, m_c.processor.iflags_H);
-    write_reg(reg::iunrep, m_c.processor.iunrep);
-
-    // Register RAM
-    if (m_c.ram.image_filename.empty()) {
-        register_pma_entry(make_callocd_memory_pma_entry("RAM"s, PMA_RAM_START, m_c.ram.length).set_flags(m_ram_flags));
-    } else {
-        register_pma_entry(make_callocd_memory_pma_entry("RAM"s, PMA_RAM_START, m_c.ram.length, m_c.ram.image_filename)
-                .set_flags(m_ram_flags));
-    }
-
-    // Register DTB
-    pma_entry &dtb = register_pma_entry((m_c.dtb.image_filename.empty() ?
-            make_callocd_memory_pma_entry("DTB"s, PMA_DTB_START, PMA_DTB_LENGTH) :
-            make_callocd_memory_pma_entry("DTB"s, PMA_DTB_START, PMA_DTB_LENGTH, m_c.dtb.image_filename))
-            .set_flags(m_dtb_flags));
-
+    write_reg(reg::pc, p.pc);
+    write_reg(reg::fcsr, p.fcsr);
+    write_reg(reg::mcycle, p.mcycle);
+    write_reg(reg::icycleinstret, p.icycleinstret);
+    write_reg(reg::mstatus, p.mstatus);
+    write_reg(reg::mtvec, p.mtvec);
+    write_reg(reg::mscratch, p.mscratch);
+    write_reg(reg::mepc, p.mepc);
+    write_reg(reg::mcause, p.mcause);
+    write_reg(reg::mtval, p.mtval);
+    write_reg(reg::misa, p.misa);
+    write_reg(reg::mie, p.mie);
+    write_reg(reg::mip, p.mip);
+    write_reg(reg::medeleg, p.medeleg);
+    write_reg(reg::mideleg, p.mideleg);
+    write_reg(reg::mcounteren, p.mcounteren);
+    write_reg(reg::menvcfg, p.menvcfg);
+    write_reg(reg::stvec, p.stvec);
+    write_reg(reg::sscratch, p.sscratch);
+    write_reg(reg::sepc, p.sepc);
+    write_reg(reg::scause, p.scause);
+    write_reg(reg::stval, p.stval);
+    write_reg(reg::satp, p.satp);
+    write_reg(reg::scounteren, p.scounteren);
+    write_reg(reg::senvcfg, p.senvcfg);
+    write_reg(reg::ilrsc, p.ilrsc);
+    write_reg(reg::iprv, p.iprv);
+    write_reg(reg::iflags_X, p.iflags_X);
+    write_reg(reg::iflags_Y, p.iflags_Y);
+    write_reg(reg::iflags_H, p.iflags_H);
+    write_reg(reg::iunrep, p.iunrep);
+}
+
+void machine::init_ram_pma(const ram_config &ram) {
+    register_pma_entry(
+        make_callocd_memory_pma_entry("RAM"s, PMA_RAM_START, ram.length, ram.image_filename).set_flags(m_ram_flags));
+}
+
+void machine::init_flash_drive_pmas(flash_drive_configs &flash_drive) {
     // Register all flash drives
     int i = 0; // NOLINT(misc-const-correctness)
-    for (auto &f : m_c.flash_drive) {
+    for (auto &f : flash_drive) {
         const std::string flash_description = "flash drive "s + std::to_string(i);
         // Auto detect flash drive start address
         if (f.start == UINT64_C(-1)) {
@@ -400,61 +367,16 @@ machine::machine(machine_config c, machine_runtime_config r) : m_c{std::move(c)}
         register_pma_entry(make_flash_drive_pma_entry(flash_description, f));
         i++;
     }
+}
 
-    // Register cmio memory ranges
-    register_pma_entry(make_cmio_tx_buffer_pma_entry(m_c.cmio));
-    register_pma_entry(make_cmio_rx_buffer_pma_entry(m_c.cmio));
-
-    // Register HTIF device
-    register_pma_entry(make_htif_pma_entry(PMA_HTIF_START, PMA_HTIF_LENGTH));
-
-    // Copy HTIF state to from config to machine
-    write_reg(reg::htif_tohost, m_c.htif.tohost);
-    write_reg(reg::htif_fromhost, m_c.htif.fromhost);
-    // Only command in halt device is command 0 and it is always available
-    const uint64_t htif_ihalt = static_cast<uint64_t>(true) << HTIF_HALT_CMD_HALT;
-    write_reg(reg::htif_ihalt, htif_ihalt);
-    const uint64_t htif_iconsole = static_cast<uint64_t>(m_c.htif.console_getchar) << HTIF_CONSOLE_CMD_GETCHAR |
-        static_cast<uint64_t>(true) << HTIF_CONSOLE_CMD_PUTCHAR;
-    write_reg(reg::htif_iconsole, htif_iconsole);
-    const uint64_t htif_iyield = static_cast<uint64_t>(m_c.htif.yield_manual) << HTIF_YIELD_CMD_MANUAL |
-        static_cast<uint64_t>(m_c.htif.yield_automatic) << HTIF_YIELD_CMD_AUTOMATIC;
-    write_reg(reg::htif_iyield, htif_iyield);
-
-    // Register CLINT device
-    register_pma_entry(make_clint_pma_entry(PMA_CLINT_START, PMA_CLINT_LENGTH));
-    // Copy CLINT state to from config to machine
-    write_reg(reg::clint_mtimecmp, m_c.clint.mtimecmp);
-
-    // Register PLIC device
-    register_pma_entry(make_plic_pma_entry(PMA_PLIC_START, PMA_PLIC_LENGTH));
-    // Copy PLIC state from config to machine
-    write_reg(reg::plic_girqpend, m_c.plic.girqpend);
-    write_reg(reg::plic_girqsrvd, m_c.plic.girqsrvd);
-
-    // Register TLB device
-    register_pma_entry(make_shadow_tlb_pma_entry(PMA_SHADOW_TLB_START, PMA_SHADOW_TLB_LENGTH));
-
-    // Register state shadow device
-    register_pma_entry(make_shadow_state_pma_entry(PMA_SHADOW_STATE_START, PMA_SHADOW_STATE_LENGTH));
-
-    // Register memory range that holds shadow PMA state, keep pointer to populate later
-    shadow_pmas_state *shadow_pmas = nullptr;
-    {
-        auto shadow_pmas_pma_entry = make_shadow_pmas_pma_entry(PMA_SHADOW_PMAS_START, PMA_SHADOW_PMAS_LENGTH);
-        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        shadow_pmas = reinterpret_cast<shadow_pmas_state *>(shadow_pmas_pma_entry.get_memory().get_host_memory());
-        register_pma_entry(std::move(shadow_pmas_pma_entry));
-    }
-
+void machine::init_virtio_pmas(const virtio_configs &v, uint64_t iunrep) {
     // Initialize VirtIO devices
-    if (!m_c.virtio.empty()) {
+    if (!v.empty()) {
         // VirtIO devices are disallowed in unreproducible mode
-        if (m_c.processor.iunrep == 0) {
+        if (iunrep == 0) {
             throw std::invalid_argument{"virtio devices are only supported in unreproducible machines"};
         }
-
-        for (const auto &vdev_config_entry : m_c.virtio) {
+        for (const auto &vdev_config_entry : v) {
             std::visit(
                 [&](const auto &vdev_config) {
                     using T = std::decay_t<decltype(vdev_config)>;
@@ -500,60 +422,53 @@ machine::machine(machine_config c, machine_runtime_config r) : m_c{std::move(c)}
                 vdev_config_entry);
         }
     }
+}
 
-    // Initialize DTB
-    if (m_c.dtb.image_filename.empty()) {
-        // Write the FDT (flattened device tree) into DTB
-        dtb_init(m_c, dtb.get_memory().get_host_memory(), PMA_DTB_LENGTH);
-    }
-
-    // Last, add empty sentinels until we reach capacity (need at least one sentinel)
-    register_pma_entry(make_empty_pma_entry("sentinel"s, 0, 0));
-    // NOLINTNEXTLINE(readability-static-accessed-through-instance)
-    if (m_s.pmas.capacity() != PMA_MAX) {
-        throw std::logic_error{"PMAs array must be able to hold PMA_MAX entries"};
-    }
-    while (m_s.pmas.size() < PMA_MAX) {
-        register_pma_entry(make_empty_pma_entry("sentinel"s, 0, 0));
-    }
-
-    // Populate shadow PMAs
-    populate_shadow_pmas_state(m_s.pmas, shadow_pmas);
-
-    // Initialize TLB device.
-    // This must be done after all PMA entries are already registered, so we can lookup page addresses
-    if (!m_c.tlb.image_filename.empty()) {
-        auto shadow_tlb = make_unique_mmap<shadow_tlb_state>(m_c.tlb.image_filename.c_str(), 1, false /* not shared */);
-        init_tlb(*shadow_tlb);
-    } else {
-        init_tlb();
-    }
-
+void machine::init_htif_pma(const htif_config &h, const htif_runtime_config &r, uint64_t iunrep) {
+    // Register HTIF device
+    register_pma_entry(make_htif_pma_entry(PMA_HTIF_START, PMA_HTIF_LENGTH));
+    // Copy HTIF state to from config to machine
+    write_reg(reg::htif_tohost, h.tohost);
+    write_reg(reg::htif_fromhost, h.fromhost);
+    // Only command in halt device is command 0 and it is always available
+    const uint64_t htif_ihalt = static_cast<uint64_t>(true) << HTIF_HALT_CMD_HALT;
+    write_reg(reg::htif_ihalt, htif_ihalt);
+    const uint64_t htif_iconsole = static_cast<uint64_t>(h.console_getchar) << HTIF_CONSOLE_CMD_GETCHAR |
+        static_cast<uint64_t>(true) << HTIF_CONSOLE_CMD_PUTCHAR;
+    write_reg(reg::htif_iconsole, htif_iconsole);
+    const uint64_t htif_iyield = static_cast<uint64_t>(h.yield_manual) << HTIF_YIELD_CMD_MANUAL |
+        static_cast<uint64_t>(h.yield_automatic) << HTIF_YIELD_CMD_AUTOMATIC;
+    write_reg(reg::htif_iyield, htif_iyield);
     // Initialize TTY if console input is enabled
-    if (m_c.htif.console_getchar || has_virtio_console()) {
-        if (m_c.processor.iunrep == 0) {
+    if (h.console_getchar || has_virtio_console()) {
+        if (iunrep == 0) {
             throw std::invalid_argument{"TTY stdin is only supported in unreproducible machines"};
         }
         os_open_tty();
     }
-    os_silence_putchar(m_r.htif.no_console_putchar);
+    os_silence_putchar(r.no_console_putchar);
+}
 
-    // Disable SIGPIPE handler, because this signal can be raised and terminate the emulator process
-    // when calling write() on closed file descriptors.
-    // This can happen with the stdout console file descriptors or network file descriptors.
-    os_disable_sigpipe();
+void machine::init_cmio_pmas(const cmio_config &c) {
+    // Register cmio memory ranges
+    register_pma_entry(make_cmio_tx_buffer_pma_entry(c.tx_buffer));
+    register_pma_entry(make_cmio_rx_buffer_pma_entry(c.rx_buffer));
+}
 
+void machine::init_merkle_pmas() {
     // Include machine PMAs in set considered by the Merkle tree.
     for (auto &pma : m_s.pmas) {
-        if (!pma.get_istart_E()) {
+        if (pma.get_length() != 0) {
             m_merkle_pmas.push_back(&pma);
         }
     }
     m_merkle_pmas.push_back(&m_us.shadow_state);
     m_merkle_pmas.push_back(&m_us.ram);
-    // Last, add sentinel PMA
-    m_merkle_pmas.push_back(&m_s.empty_pma);
+    // Sort it by increasing start address
+    std::ranges::sort(m_merkle_pmas, [](const auto *a, const auto *b) { return a->get_start() < b->get_start(); });
+}
 
+void machine::init_memory_range_descrs() {
     // Initialize memory range descriptions returned by get_memory_ranges method
     for (const auto *pma : m_merkle_pmas) {
         if (pma->get_length() != 0) {
@@ -562,9 +477,108 @@ machine::machine(machine_config c, machine_runtime_config r) : m_c{std::move(c)}
                 .description = pma->get_description()});
         }
     }
-    // Sort it by increasing start address
-    std::sort(m_mrds.begin(), m_mrds.end(),
-        [](const machine_memory_range_descr &a, const machine_memory_range_descr &b) { return a.start < b.start; });
+}
+
+void machine::init_clint_pma(const clint_config &c) {
+    // Register CLINT device
+    register_pma_entry(make_clint_pma_entry(PMA_CLINT_START, PMA_CLINT_LENGTH));
+    // Copy CLINT state to from config to machine
+    write_reg(reg::clint_mtimecmp, c.mtimecmp);
+}
+
+void machine::init_plic_pma(const plic_config &p) {
+    // Register PLIC device
+    register_pma_entry(make_plic_pma_entry(PMA_PLIC_START, PMA_PLIC_LENGTH));
+    // Copy PLIC state from config to machine
+    write_reg(reg::plic_girqpend, p.girqpend);
+    write_reg(reg::plic_girqsrvd, p.girqsrvd);
+}
+
+void machine::init_sentinel_pmas() {
+    // Last, add empty sentinels until we reach capacity (need at least one sentinel)
+    register_pma_entry(make_empty_pma_entry("sentinel"s, 0, 0));
+    // NOLINTNEXTLINE(readability-static-accessed-through-instance)
+    if (m_s.pmas.capacity() != PMA_MAX) {
+        throw std::logic_error{"PMAs array must be able to hold at least PMA_MAX entries"};
+    }
+    while (m_s.pmas.size() < PMA_MAX) {
+        register_pma_entry(make_empty_pma_entry("sentinel"s, 0, 0));
+    }
+}
+
+void machine::init_shadow_pmas_contents(pma_entry &shadow_pmas) const {
+    // NOLINTBEGIN(cppcoreguidelines-pro-type-reinterpret-cast)
+    shadow_pmas_init(m_s.pmas,
+        reinterpret_cast<shadow_pmas_state *>(shadow_pmas.get_memory_noexcept().get_host_memory()));
+    // NOLINTEND(cppcoreguidelines-pro-type-reinterpret-cast)
+}
+
+void machine::init_tlb_contents(const std::string &image_filename) {
+    if (!image_filename.empty()) {
+        auto shadow_tlb_ptr = make_unique_mmap<shadow_tlb_state>(image_filename.c_str(), 1, false /* not shared */);
+        auto &shadow_tlb = *shadow_tlb_ptr;
+        for (auto set_index : {TLB_CODE, TLB_READ, TLB_WRITE}) {
+            for (uint64_t slot_index = 0; slot_index < TLB_SET_SIZE; ++slot_index) {
+                const auto vaddr_page = shadow_tlb[set_index][slot_index].vaddr_page;
+                const auto vp_offset = shadow_tlb[set_index][slot_index].vp_offset;
+                const auto pma_index = shadow_tlb[set_index][slot_index].pma_index;
+                check_shadow_tlb(set_index, slot_index, vaddr_page, vp_offset, pma_index, "stored TLB is corrupt: "s);
+                write_shadow_tlb(set_index, slot_index, vaddr_page, vp_offset, pma_index);
+            }
+        }
+    } else {
+        for (auto set_index : {TLB_CODE, TLB_READ, TLB_WRITE}) {
+            for (uint64_t slot_index = 0; slot_index < TLB_SET_SIZE; ++slot_index) {
+                write_tlb(set_index, slot_index, TLB_INVALID_PAGE, host_addr{}, TLB_INVALID_PMA_INDEX);
+            }
+        }
+    }
+}
+
+void machine::init_dtb_contents(const machine_config &c, pma_entry &dtb) {
+    if (c.dtb.image_filename.empty()) {
+        dtb_init(c, dtb.get_memory().get_host_memory(), PMA_DTB_LENGTH);
+    }
+}
+
+// ??D It is best to leave the std::move() on r because it may one day be necessary!
+// NOLINTNEXTLINE(hicpp-move-const-arg,performance-move-const-arg)
+machine::machine(machine_config c, machine_runtime_config r) : m_c{std::move(c)}, m_r{std::move(r)} {
+    init_uarch(m_c.uarch);
+    init_processor(m_c.processor, m_r);
+    m_s.soft_yield = m_r.soft_yield;
+    init_ram_pma(m_c.ram);
+    // Will populate when initialization of PMAs is done
+    pma_entry &dtb =
+        register_pma_entry(make_callocd_memory_pma_entry("DTB"s, PMA_DTB_START, PMA_DTB_LENGTH, m_c.dtb.image_filename)
+                .set_flags(m_dtb_flags));
+    init_flash_drive_pmas(m_c.flash_drive);
+    init_cmio_pmas(m_c.cmio);
+    init_htif_pma(m_c.htif, m_r.htif, m_c.processor.iunrep);
+    init_clint_pma(m_c.clint);
+    init_plic_pma(m_c.plic);
+    // Will populate when initialization of PMAs is done
+    register_pma_entry(make_shadow_tlb_pma_entry(PMA_SHADOW_TLB_START, PMA_SHADOW_TLB_LENGTH));
+    register_pma_entry(make_shadow_state_pma_entry(PMA_SHADOW_STATE_START, PMA_SHADOW_STATE_LENGTH));
+    // Will populate when initialization of PMAs is done
+    pma_entry &shpmas = register_pma_entry(make_shadow_pmas_pma_entry(PMA_SHADOW_PMAS_START, PMA_SHADOW_PMAS_LENGTH));
+    init_virtio_pmas(m_c.virtio, m_c.processor.iunrep);
+    init_sentinel_pmas();
+    // Populate shadow PMAs contents.
+    // This must be done after all PMA entries are already registered, so we encode them into the shadow
+    init_shadow_pmas_contents(shpmas);
+    // Initialize TLB contents.
+    // This must be done after all PMA entries are already registered, so we can lookup page addresses
+    init_tlb_contents(m_c.tlb.image_filename);
+    // Initialize DTB contents.
+    // This must be done after all PMA entries are already registered, so we can lookup flash drive parameters
+    init_dtb_contents(m_c, dtb);
+    init_merkle_pmas();
+    init_memory_range_descrs();
+    // Disable SIGPIPE handler, because this signal can be raised and terminate the emulator process
+    // when calling write() on closed file descriptors.
+    // This can happen with the stdout console file descriptors or network file descriptors.
+    os_disable_sigpipe();
 }
 
 static void load_hash(const std::string &dir, machine::hash_type &h) {
@@ -765,21 +779,6 @@ static void store_memory_pma(const pma_entry &pma, const std::string &dir) {
     }
 }
 
-pma_entry &machine::find_pma_entry(uint64_t paddr, uint64_t length) {
-    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-const-cast): remove const to reuse code
-    return const_cast<pma_entry &>(std::as_const(*this).find_pma_entry(paddr, length));
-}
-
-const pma_entry &machine::find_pma_entry(uint64_t paddr, uint64_t length) const {
-    return find_pma_entry(m_s.pmas, paddr, length);
-}
-
-template <typename CONTAINER>
-pma_entry &machine::find_pma_entry(const CONTAINER &pmas, uint64_t paddr, uint64_t length) {
-    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-const-cast): remove const to reuse code
-    return const_cast<pma_entry &>(std::as_const(*this).find_pma_entry(pmas, paddr, length));
-}
-
 uint64_t machine::get_paddr(host_addr haddr, uint64_t pma_index) const {
     return static_cast<uint64_t>(haddr + get_hp_offset(pma_index));
 }
@@ -884,33 +883,17 @@ host_addr machine::get_hp_offset(uint64_t pma_index) const {
     return paddr - haddr;
 }
 
-template <typename CONTAINER>
-const pma_entry &machine::find_pma_entry(const CONTAINER &pmas, uint64_t paddr, uint64_t length) const {
-    for (const auto &p : pmas) {
-        const auto &pma = deref(p);
-        // Stop at first empty PMA
-        if (pma.get_length() == 0) {
-            return pma;
-        }
+//??D now that m_merkle_pmas is sorted by start, maybe change this to a binary search?
+const pma_entry &machine::find_pma_entry(uint64_t paddr, uint64_t length) const {
+    const static auto sentinel = make_empty_pma_entry("sentinel", 0, 0);
+    for (const auto *pma : m_merkle_pmas) {
         // Check if data is in range
-        if (paddr >= pma.get_start() && pma.get_length() >= length &&
-            paddr - pma.get_start() <= pma.get_length() - length) {
-            return pma;
+        if (paddr >= pma->get_start() && pma->get_length() >= length &&
+            paddr - pma->get_start() <= pma->get_length() - length) {
+            return *pma;
         }
     }
-
-    // Last PMA is always the empty range
-    return deref(pmas.back());
-}
-
-template <typename T>
-static inline T &deref(T &t) {
-    return t; // NOLINT(bugprone-return-const-ref-from-parameter)
-}
-
-template <typename T>
-static inline T &deref(T *t) {
-    return *t;
+    return sentinel;
 }
 
 void machine::store_pmas(const machine_config &c, const std::string &dir) const {
@@ -1942,7 +1925,7 @@ bool machine::update_merkle_tree_page(uint64_t address) {
         "PMA and machine_merkle_tree page sizes must match");
     // Align address to beginning of page
     address &= ~(PMA_PAGE_SIZE - 1);
-    pma_entry &pma = find_pma_entry(m_merkle_pmas, address, sizeof(uint64_t));
+    auto &pma = find_pma_entry<uint8_t>(address);
     const uint64_t page_start_in_range = address - pma.get_start();
     machine_merkle_tree::hasher_type h;
     auto scratch = make_unique_calloc<unsigned char>(PMA_PAGE_SIZE, std::nothrow_t{});
@@ -1969,10 +1952,6 @@ bool machine::update_merkle_tree_page(uint64_t address) {
     return m_t.end_update(h);
 }
 
-const boost::container::static_vector<pma_entry, PMA_MAX> &machine::get_pmas() const {
-    return m_s.pmas;
-}
-
 void machine::get_root_hash(hash_type &hash) const {
     if (read_reg(reg::iunrep) != 0) {
         throw std::runtime_error("cannot compute root hash of unreproducible machines");
@@ -2059,7 +2038,7 @@ machine_merkle_tree::proof_type machine::get_proof(uint64_t address, int log2_si
     // or entirely outside it.
     if (log2_size < machine_merkle_tree::get_log2_page_size()) {
         const uint64_t length = UINT64_C(1) << log2_size;
-        const pma_entry &pma = find_pma_entry(m_merkle_pmas, address, length);
+        const auto &pma = find_pma_entry(address, length);
         auto scratch = make_unique_calloc<unsigned char>(PMA_PAGE_SIZE);
         const unsigned char *page_data = nullptr;
         // If the PMA range is empty, we know the desired range is
@@ -2107,7 +2086,7 @@ void machine::read_memory(uint64_t paddr, unsigned char *data, uint64_t length)
     // That first peek reads at most up to the next page boundary.
     // So the inner loop iterations never cross page boundaries.
     for (;;) {
-        const pma_entry &pma = find_pma_entry(m_merkle_pmas, paddr, peek_length);
+        const auto &pma = find_pma_entry(paddr, peek_length);
         const auto peek = pma.get_peek();
         const auto pma_start = pma.get_start();
         const auto pma_empty = pma.get_istart_E();
@@ -2161,7 +2140,7 @@ void machine::write_memory(uint64_t paddr, const unsigned char *data, uint64_t l
     if (data == nullptr) {
         throw std::invalid_argument{"invalid data buffer"};
     }
-    pma_entry &pma = find_pma_entry(m_merkle_pmas, paddr, length);
+    auto &pma = find_pma_entry(paddr, length);
     if (pma.get_istart_IO()) {
         throw std::invalid_argument{"attempted write to device memory range"};
     }
@@ -2178,7 +2157,7 @@ void machine::fill_memory(uint64_t address, uint8_t data, uint64_t length) {
     if (length == 0) {
         return;
     }
-    pma_entry &pma = find_pma_entry(m_merkle_pmas, address, length);
+    auto &pma = find_pma_entry(address, length);
     if (!pma.get_istart_M() || pma.get_istart_E()) {
         throw std::invalid_argument{"address range not entirely in memory PMA"};
     }
@@ -2294,7 +2273,7 @@ void machine::write_word(uint64_t paddr, uint64_t val) {
         return;
     }
     // Otherwise, try the slow path
-    auto &pma = find_pma_entry(m_merkle_pmas, paddr, sizeof(uint64_t));
+    auto &pma = find_pma_entry(paddr, sizeof(uint64_t));
     if (pma.get_istart_E() || !pma.get_istart_M()) {
         std::ostringstream err;
         err << "attempted memory write to " << pma.get_description() << " at address 0x" << std::hex << paddr << "("
diff --git a/src/machine.h b/src/machine.h
index 6a83602c0..03ab519d5 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -23,6 +23,7 @@
 #include <cstdint>
 #include <memory>
 #include <string>
+#include <utility>
 #include <vector>
 
 #include <boost/container/static_vector.hpp>
@@ -96,47 +97,89 @@ class machine final {
     static pma_entry make_flash_drive_pma_entry(const std::string &description, const memory_range_config &c);
 
     /// \brief Creates a new cmio rx buffer PMA entry.
-    // \param c Optional cmio configuration
+    // \param c cmio buffer configuration for rx buffer.
     /// \returns New PMA entry with rx buffer flags already set.
-    static pma_entry make_cmio_rx_buffer_pma_entry(const cmio_config &cmio_config);
+    static pma_entry make_cmio_rx_buffer_pma_entry(const cmio_buffer_config &c);
 
     /// \brief Creates a new cmio tx buffer PMA entry.
-    // \param c Optional cmio configuration
+    // \param c cmio buffer configuration for tx buffer.
     /// \returns New PMA entry with tx buffer flags already set.
-    static pma_entry make_cmio_tx_buffer_pma_entry(const cmio_config &cmio_config);
+    static pma_entry make_cmio_tx_buffer_pma_entry(const cmio_buffer_config &c);
 
     /// \brief Saves PMAs into files for serialization
     /// \param config Machine config to be stored
     /// \param directory Directory where PMAs will be stored
     void store_pmas(const machine_config &config, const std::string &directory) const;
 
-    /// \brief Obtain PMA entry that covers a given physical memory region
-    /// \param pmas Container of pmas to be searched.
-    /// \param s Pointer to machine state.
-    /// \param paddr Start of physical memory region.
-    /// \param length Length of physical memory region.
-    /// \returns Corresponding entry if found, or a sentinel entry
-    /// for an empty range.
-    template <typename CONTAINER>
-    pma_entry &find_pma_entry(const CONTAINER &pmas, uint64_t paddr, uint64_t length);
-
-    template <typename CONTAINER>
-    const pma_entry &find_pma_entry(const CONTAINER &pmas, uint64_t paddr, uint64_t length) const;
-
     /// \brief Returns offset that converts between machine host addresses and target physical addresses
     /// \param pma_index Index of the memory PMA for the desired offset
     host_addr get_hp_offset(uint64_t pma_index) const;
 
-    /// \brief Initializes machine TLB from scratch
-    void init_tlb();
-
-    /// \brief Initializes machine TLB from shadow tlb
-    /// \param shadow_tlb Shadow TLB loaded from disk
-    void init_tlb(const shadow_tlb_state &shadow_tlb);
-
     /// \brief Initializes microarchitecture
-    /// \param config Microarchitecture configuration
-    void init_uarch(const uarch_config &config);
+    /// \param c Microarchitecture configuration
+    void init_uarch(const uarch_config &c);
+
+    /// \brief Initializes registers
+    /// \param p Processor configuration
+    /// \param r Machine runtime configuration
+    void init_processor(processor_config &p, const machine_runtime_config &r);
+
+    /// \brief Initializes RAM PMA
+    /// \param ram RAM configuration
+    void init_ram_pma(const ram_config &ram);
+
+    /// \brief Initializes flash drive PMAs
+    /// \param flash_drive Flash drive configurations
+    void init_flash_drive_pmas(flash_drive_configs &flash_drive);
+
+    /// \brief Initializes VirtIO device PMAs
+    /// \param v VirtIO configurations
+    /// \param iunrep Initial value of iunrep CSR
+    void init_virtio_pmas(const virtio_configs &v, uint64_t iunrep);
+
+    /// \brief Initializes HTIF device PMA
+    /// \param h HTIF configuration
+    /// \param r HTIF runtime configuration
+    /// \param iunrep Initial value of iunrep CSR
+    void init_htif_pma(const htif_config &h, const htif_runtime_config &r, uint64_t iunrep);
+
+    /// \brief Initializes CLINT device PMA
+    /// \param c CLINT configuration
+    void init_clint_pma(const clint_config &c);
+
+    /// \brief Initializes PLIC device PMA
+    /// \param p PLIC configuration
+    void init_plic_pma(const plic_config &p);
+
+    /// \brief Initializes CMIO PMAs
+    /// \param c CMIO configuration
+    void init_cmio_pmas(const cmio_config &c);
+
+    /// \brief Initializes the PMAs used to compute the Merkle tree
+    /// \detail This can only be called after all PMAs have been added
+    void init_merkle_pmas();
+
+    /// \brief Initializes the PMAs descriptions returned by get_memory_ranges()
+    /// \detail This can only be called after the Merkle tree PMAs have been initialized
+    void init_memory_range_descrs();
+
+    /// \brief Fill up PMA list with sentinel empty PMAs
+    void init_sentinel_pmas();
+
+    /// \brief Initializes contents of the shadow PMAs memory
+    /// \param shadow_pmas PMA entry for the shadow PMAs
+    /// \detail This can only be called after all PMAs have been added
+    void init_shadow_pmas_contents(pma_entry &shadow_pmas) const;
+
+    /// \brief Initializes contents of machine TLB, from image in disk or with default values
+    /// \param image_filename File containing image, or empty for default values
+    /// \detail This can only be called after all PMAs have been added
+    void init_tlb_contents(const std::string &image_filename);
+
+    /// \brief Initializes contents of machine DTB, if image was not available
+    /// \param c Machine configuration
+    /// \param dtb PMA entry for the shadow PMAs
+    static void init_dtb_contents(const machine_config &c, pma_entry &dtb);
 
     /// \brief Dumps statistics
     void dump_stats();
@@ -185,7 +228,8 @@ class machine final {
     /// \param mcycle_end Maximum value of mcycle before function returns.
     /// \returns The reason the machine was interrupted.
     /// \details Several conditions can cause the function to break before mcycle reaches mcycle_end. The most
-    ///  frequent scenario is when the program executes a WFI instruction. Another example is when the machine halts.
+    ///  frequent scenario is when the program executes a WFI instruction. Another example is when the machine
+    ///  halts.
     interpreter_break_reason run(uint64_t mcycle_end);
 
     /// \brief Runs the machine for the given mcycle count and generates a log of accessed pages and proof data.
@@ -278,7 +322,8 @@ class machine final {
 
     /// \brief Fill file descriptors to be polled by select() for all VirtIO devices.
     /// \param fds Pointer to sets of read, write and except file descriptors to be updated.
-    /// \param timeout_us Maximum amount of time to wait in microseconds, this may be updated (always to lower values).
+    /// \param timeout_us Maximum amount of time to wait in microseconds, this may be updated (always to lower
+    /// values).
     void prepare_virtio_devices_select(select_fd_sets *fds, uint64_t *timeout_us);
 
     /// \brief Poll file descriptors that were marked as ready by select() for all VirtIO devices.
@@ -290,7 +335,8 @@ class machine final {
 
     /// \brief Poll file descriptors through select() for all VirtIO devices.
     /// \details Basically call prepare_virtio_devices_select(), select() and poll_selected_virtio_devices().
-    /// \param timeout_us Maximum amount of time to wait in microseconds, this may be updated (always to lower values).
+    /// \param timeout_us Maximum amount of time to wait in microseconds, this may be updated (always to lower
+    /// values).
     /// \returns True if an interrupt was requested, false otherwise.
     bool poll_virtio_devices(uint64_t *timeout_us, i_device_state_access *da);
 
@@ -330,7 +376,8 @@ class machine final {
     /// Must be between 3 (for a word) and 64 (for the entire address space), inclusive.
     /// \param proof Receives the proof.
     /// \details If the node is smaller than a page size, then it must lie entirely inside the same PMA range.
-    /// This overload is used to optimize proof generation when the caller knows that the tree is already up to date.
+    /// This overload is used to optimize proof generation when the caller knows that the tree is already up to
+    /// date.
     machine_merkle_tree::proof_type get_proof(uint64_t address, int log2_size,
         skip_merkle_tree_update_t /*unused*/) const;
 
@@ -420,10 +467,6 @@ class machine final {
     /// \returns The corresponding physical address.
     uint64_t translate_virtual_address(uint64_t vaddr);
 
-    /// \brief Get read-only access to container with all PMA entries.
-    /// \returns The container.
-    const boost::container::static_vector<pma_entry, PMA_MAX> &get_pmas() const;
-
     /// \brief Obtain PMA entry from the machine state that covers a given physical memory region
     /// \brief Microarchitecture PMAs are not considered.
     /// \param s Pointer to machine state.
@@ -431,21 +474,28 @@ class machine final {
     /// \param length Length of physical memory region.
     /// \returns Corresponding entry if found, or a sentinel entry
     /// for an empty range.
-    pma_entry &find_pma_entry(uint64_t paddr, uint64_t length);
-
     const pma_entry &find_pma_entry(uint64_t paddr, uint64_t length) const;
 
+    pma_entry &find_pma_entry(uint64_t paddr, uint64_t length) {
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-const-cast)
+        return const_cast<pma_entry &>(std::as_const(*this).find_pma_entry(paddr, length));
+    }
+
     /// \brief Obtain PMA entry covering a physical memory word
     /// \tparam T Type of word.
     /// \param s Pointer to machine state.
     /// \param paddr Target physical address.
-    /// \returns Corresponding entry if found, or a sentinel entry
-    /// for an empty range.
+    /// \returns Corresponding entry if found, or a sentinel entry for an empty range.
     template <typename T>
     const pma_entry &find_pma_entry(uint64_t paddr) const {
         return find_pma_entry(paddr, sizeof(T));
     }
 
+    template <typename T>
+    pma_entry &find_pma_entry(uint64_t paddr) {
+        return find_pma_entry(paddr, sizeof(T));
+    }
+
     /// \brief Go over the write TLB and mark as dirty all pages currently there.
     void mark_write_tlb_dirty_pages() const;
 
diff --git a/src/shadow-pmas-factory.h b/src/shadow-pmas-factory.h
index 008f37bed..f911a8ec6 100644
--- a/src/shadow-pmas-factory.h
+++ b/src/shadow-pmas-factory.h
@@ -30,7 +30,7 @@ namespace cartesi {
 pma_entry make_shadow_pmas_pma_entry(uint64_t start, uint64_t length);
 
 template <typename PMAS>
-void populate_shadow_pmas_state(const PMAS &pmas, shadow_pmas_state *shadow) {
+void shadow_pmas_init(const PMAS &pmas, shadow_pmas_state *shadow) {
     static_assert(sizeof(shadow_pmas_state) == PMA_MAX * 2 * sizeof(uint64_t), "inconsistent shadow PMAs length");
     static_assert(PMA_SHADOW_PMAS_LENGTH >= sizeof(shadow_pmas_state), "shadow PMAs not long enough");
     if (pmas.size() > PMA_MAX) {

From 13c5406468a409b4da9bf846c08f31098ce62a8b Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Sat, 22 Feb 2025 20:57:23 +0000
Subject: [PATCH 21/82] refactor: clean up PMA class strucure

---
 src/Makefile                                  |  65 +-
 ...ge-descr.h => address-range-description.h} |  12 +-
 src/address-range.h                           | 392 ++++++++
 ...shadow-uarch-state.cpp => assert-printf.h} |  19 +-
 src/{clint.cpp => clint-address-range.cpp}    |  30 +-
 src/clint-address-range.h                     |  70 ++
 src/clint-factory.cpp                         |  32 -
 src/clint-factory.h                           |  34 -
 src/clint.h                                   |  50 -
 src/clua-i-virtual-machine.cpp                |   8 +-
 src/dump.h                                    |  10 +-
 src/find-pma-entry.h                          |  37 +-
 src/{htif.cpp => htif-address-range.cpp}      |  17 +-
 src/htif-address-range.h                      |  72 ++
 src/{htif.h => htif-constants.h}              |  25 +-
 src/htif-factory.cpp                          |  32 -
 src/htif-factory.h                            |  31 -
 src/i-state-access.h                          |  17 +-
 src/i-virtual-machine.h                       |   8 +-
 src/interpret.cpp                             |  30 +-
 src/json-util.cpp                             |  20 +-
 src/json-util.h                               |  24 +-
 src/jsonrpc-discover.json                     |  18 +-
 src/jsonrpc-machine-c-api.cpp                 |   1 -
 src/jsonrpc-remote-machine.cpp                |   8 +-
 src/jsonrpc-virtual-machine.cpp               |   8 +-
 src/jsonrpc-virtual-machine.h                 |   4 +-
 src/machine-c-api.cpp                         |  25 +-
 src/machine-c-api.h                           |   6 +-
 src/machine-config.cpp                        |   1 -
 src/machine-reg.h                             |   4 +-
 src/machine-state.h                           |  17 +-
 src/machine.cpp                               | 872 ++++++++++--------
 src/machine.h                                 | 255 ++---
 src/memory-address-range.cpp                  |  90 ++
 src/memory-address-range.h                    | 143 +++
 src/meta.h                                    |   6 +
 src/mock-address-range.h                      | 108 +++
 src/mock-pma-entry.h                          | 169 ----
 src/{plic.cpp => plic-address-range.cpp}      |  35 +-
 src/plic-address-range.h                      |  80 ++
 src/{plic.h => plic-constants.h}              |  19 +-
 src/plic-factory.cpp                          |  32 -
 src/plic-factory.h                            |  34 -
 src/pma-constants.h                           |  67 +-
 src/pma-driver.cpp                            |  35 -
 src/pma-driver.h                              |  67 --
 src/pma.cpp                                   | 220 -----
 src/pma.h                                     | 603 ++----------
 src/pristine-address-range.h                  |  59 ++
 src/record-send-cmio-state-access.h           |  22 +-
 src/record-step-state-access.h                |  16 +-
 src/replay-send-cmio-state-access.h           |   7 -
 src/replay-step-state-access.h                |  30 +-
 src/riscv-constants.h                         |  65 +-
 src/shadow-peek.h                             |  19 +-
 ...actory.cpp => shadow-pmas-address-range.h} |  25 +-
 src/shadow-pmas-factory.h                     |  49 -
 src/shadow-pmas.h                             |   2 -
 ...ory.cpp => shadow-state-address-range.cpp} |  24 +-
 src/shadow-state-address-range.h              |  72 ++
 src/shadow-state-factory.h                    |  37 -
 src/shadow-state.cpp                          |  25 -
 src/shadow-state.h                            |   9 +-
 ...ctory.cpp => shadow-tlb-address-range.cpp} |  25 +-
 src/shadow-tlb-address-range.h                |  72 ++
 src/shadow-tlb-factory.h                      |   2 -
 src/shadow-tlb.cpp                            |  25 -
 src/shadow-tlb.h                              |   3 -
 ...p => shadow-uarch-state-address-range.cpp} |  23 +-
 src/shadow-uarch-state-address-range.h        |  74 ++
 src/shadow-uarch-state-factory.h              |  37 -
 src/shadow-uarch-state.h                      |   6 +-
 src/state-access.h                            |  12 +-
 src/tlb.h                                     |   1 -
 src/translate-virtual-address.h               |   8 +-
 src/uarch-record-state-access.h               |   2 -
 src/uarch-replay-state-access.h               |   1 -
 src/uarch-state-access.h                      |  23 +-
 src/uarch-state.h                             |   8 +-
 src/unique-c-ptr.h                            |  10 +-
 ...io-device.cpp => virtio-address-range.cpp} |  82 +-
 ...virtio-device.h => virtio-address-range.h} |  56 +-
 ...e.cpp => virtio-console-address-range.cpp} |  29 +-
 ...nsole.h => virtio-console-address-range.h} |  23 +-
 src/virtio-factory.cpp                        |  36 -
 src/virtio-factory.h                          |  37 -
 ...o-net.cpp => virtio-net-address-range.cpp} |  37 +-
 ...irtio-net.h => virtio-net-address-range.h} |  74 +-
 src/virtio-net-carrier-tuntap.h               |  60 --
 ...pp => virtio-net-tuntap-address-range.cpp} |  20 +-
 src/virtio-net-tuntap-address-range.h         |  67 ++
 ....cpp => virtio-net-user-address-range.cpp} |  29 +-
 ...lirp.h => virtio-net-user-address-range.h} |  39 +-
 ...p9fs.cpp => virtio-p9fs-address-range.cpp} |  71 +-
 ...tio-p9fs.h => virtio-p9fs-address-range.h} |  30 +-
 src/virtio-serializer.h                       |   2 +-
 src/virtual-machine.cpp                       |   6 +-
 src/virtual-machine.h                         |   4 +-
 tests/lua/cartesi/tests/util.lua              |   2 +-
 tests/lua/create-machines.lua                 |   6 +-
 tests/lua/machine-bind.lua                    |  26 +-
 tests/lua/machine-test.lua                    |  20 +-
 tests/misc/Makefile                           |  14 +-
 tests/misc/test-machine-c-api.cpp             |  15 +-
 tests/misc/test-utils.h                       |   4 +-
 uarch/Makefile                                |  16 +-
 uarch/machine-uarch-bridge-state-access.h     |  26 +-
 uarch/uarch-run.cpp                           |   6 +-
 uarch/uarch-runtime.cpp                       |   4 +
 uarch/uarch-runtime.h                         |  18 +-
 111 files changed, 2713 insertions(+), 2901 deletions(-)
 rename src/{machine-memory-range-descr.h => address-range-description.h} (74%)
 create mode 100644 src/address-range.h
 rename src/{shadow-uarch-state.cpp => assert-printf.h} (76%)
 rename src/{clint.cpp => clint-address-range.cpp} (78%)
 create mode 100644 src/clint-address-range.h
 delete mode 100644 src/clint-factory.cpp
 delete mode 100644 src/clint-factory.h
 delete mode 100644 src/clint.h
 rename src/{htif.cpp => htif-address-range.cpp} (91%)
 create mode 100644 src/htif-address-range.h
 rename src/{htif.h => htif-constants.h} (81%)
 delete mode 100644 src/htif-factory.cpp
 delete mode 100644 src/htif-factory.h
 create mode 100644 src/memory-address-range.cpp
 create mode 100644 src/memory-address-range.h
 create mode 100644 src/mock-address-range.h
 delete mode 100644 src/mock-pma-entry.h
 rename src/{plic.cpp => plic-address-range.cpp} (91%)
 create mode 100644 src/plic-address-range.h
 rename src/{plic.h => plic-constants.h} (86%)
 delete mode 100644 src/plic-factory.cpp
 delete mode 100644 src/plic-factory.h
 delete mode 100644 src/pma-driver.cpp
 delete mode 100644 src/pma-driver.h
 delete mode 100644 src/pma.cpp
 create mode 100644 src/pristine-address-range.h
 rename src/{shadow-pmas-factory.cpp => shadow-pmas-address-range.h} (63%)
 delete mode 100644 src/shadow-pmas-factory.h
 rename src/{shadow-state-factory.cpp => shadow-state-address-range.cpp} (63%)
 create mode 100644 src/shadow-state-address-range.h
 delete mode 100644 src/shadow-state-factory.h
 delete mode 100644 src/shadow-state.cpp
 rename src/{shadow-tlb-factory.cpp => shadow-tlb-address-range.cpp} (64%)
 create mode 100644 src/shadow-tlb-address-range.h
 delete mode 100644 src/shadow-tlb.cpp
 rename src/{shadow-uarch-state-factory.cpp => shadow-uarch-state-address-range.cpp} (66%)
 create mode 100644 src/shadow-uarch-state-address-range.h
 delete mode 100644 src/shadow-uarch-state-factory.h
 rename src/{virtio-device.cpp => virtio-address-range.cpp} (91%)
 rename src/{virtio-device.h => virtio-address-range.h} (93%)
 rename src/{virtio-console.cpp => virtio-console-address-range.cpp} (82%)
 rename src/{virtio-console.h => virtio-console-address-range.h} (76%)
 delete mode 100644 src/virtio-factory.cpp
 delete mode 100644 src/virtio-factory.h
 rename src/{virtio-net.cpp => virtio-net-address-range.cpp} (77%)
 rename src/{virtio-net.h => virtio-net-address-range.h} (73%)
 delete mode 100644 src/virtio-net-carrier-tuntap.h
 rename src/{virtio-net-carrier-tuntap.cpp => virtio-net-tuntap-address-range.cpp} (90%)
 create mode 100644 src/virtio-net-tuntap-address-range.h
 rename src/{virtio-net-carrier-slirp.cpp => virtio-net-user-address-range.cpp} (92%)
 rename src/{virtio-net-carrier-slirp.h => virtio-net-user-address-range.h} (61%)
 rename src/{virtio-p9fs.cpp => virtio-p9fs-address-range.cpp} (96%)
 rename src/{virtio-p9fs.h => virtio-p9fs-address-range.h} (94%)

diff --git a/src/Makefile b/src/Makefile
index ca2249122..214326e2d 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -139,8 +139,8 @@ ifeq ($(slirp),yes)
 # Workaround for building with macports lua-luarocks installation
 machine.o: INCS+=$(SLIRP_INC)
 machine.clang-tidy: INCS+=$(SLIRP_INC)
-virtio-net-carrier-slirp.o: INCS+=$(SLIRP_INC)
-virtio-net-carrier-slirp.clang-tidy: INCS+=$(SLIRP_INC)
+virtio-net-user-address-range.o: INCS+=$(SLIRP_INC)
+virtio-net-user-address-range.clang-tidy: INCS+=$(SLIRP_INC)
 #INCS+=$(SLIRP_INC)
 LIBCARTESI_COMMON_LIBS+=$(SLIRP_LIB)
 else
@@ -350,48 +350,39 @@ c-api: $(LIBCARTESI) $(LIBCARTESI_MERKLE_TREE) $(LIBCARTESI_JSONRPC)
 .PHONY: all generate use clean lint format format-lua check-format check-format-lua luacartesi hash c-api compile_flags.txt
 
 LIBCARTESI_OBJS:= \
-	pma-driver.o \
-	clint.o \
-	clint-factory.o \
-	plic.o \
-	plic-factory.o \
-	virtio-factory.o \
-	virtio-device.o \
-	virtio-console.o \
-	virtio-p9fs.o \
-	virtio-net.o \
-	virtio-net-carrier-tuntap.o \
-	virtio-net-carrier-slirp.o \
-	dtb.o \
-	os.o \
-	htif.o \
-	htif-factory.o \
-	shadow-state.o \
-	shadow-state-factory.o \
-	shadow-pmas-factory.o \
-	shadow-tlb.o \
-	shadow-tlb-factory.o \
-	shadow-uarch-state.o \
-	shadow-uarch-state-factory.o \
-	pma.o \
-	machine.o \
-	machine-config.o \
-	json-util.o \
 	base64.o \
+	clint-address-range.o \
+	dtb.o \
+	htif-address-range.o \
 	interpret.o \
-	virtual-machine.o \
-	sha3.o \
+	json-util.o \
+	machine-c-api.o \
+	machine-config.o \
 	machine-merkle-tree.o \
+	machine.o \
+	memory-address-range.o \
+	os.o \
+	plic-address-range.o \
 	pristine-merkle-tree.o \
-	machine-c-api.o \
+	replay-step-state-access-interop.o \
+	send-cmio-response.o \
+	sha3.o \
+	shadow-state-address-range.o \
+	shadow-tlb-address-range.o \
+	shadow-uarch-state-address-range.o \
+	uarch-pristine-hash.o \
 	uarch-pristine-ram.o \
 	uarch-pristine-state-hash.o \
-	uarch-pristine-hash.o \
-    uarch-interpret.o \
-	uarch-step.o \
 	uarch-reset-state.o \
-	send-cmio-response.o \
-	replay-step-state-access-interop.o
+	uarch-step.o \
+	virtual-machine.o \
+	uarch-interpret.o \
+	virtio-address-range.o \
+	virtio-console-address-range.o \
+	virtio-p9fs-address-range.o \
+	virtio-net-address-range.o \
+	virtio-net-tuntap-address-range.o \
+	virtio-net-user-address-range.o
 
 CARTESI_CLUA_OBJS:= \
 	clua.o \
diff --git a/src/machine-memory-range-descr.h b/src/address-range-description.h
similarity index 74%
rename from src/machine-memory-range-descr.h
rename to src/address-range-description.h
index 787275b9d..325425b98 100644
--- a/src/machine-memory-range-descr.h
+++ b/src/address-range-description.h
@@ -14,8 +14,8 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#ifndef MACHINE_MEMORY_RANGE_DESCR_H
-#define MACHINE_MEMORY_RANGE_DESCR_H
+#ifndef ADDRESS_RANGE_DESCRIPTION_H
+#define ADDRESS_RANGE_DESCRIPTION_H
 
 #include <cstdint>
 #include <string>
@@ -23,15 +23,15 @@
 
 namespace cartesi {
 
-/// \brief Description of memory range used for introspection (i.e., get_memory_ranges())
-struct machine_memory_range_descr {
+/// \brief Description of an address range used for introspection (i.e., get_address_ranges())
+struct address_range_description {
     uint64_t start = 0;      ///< Start of memory range
     uint64_t length = 0;     ///< Length of memory range
     std::string description; ///< User-friendly description for memory range
 };
 
-/// \brief List of memory range descriptions used for introspection (i.e., get_memory_ranges())
-using machine_memory_range_descrs = std::vector<machine_memory_range_descr>;
+/// \brief List of address range descriptions used for introspection (i.e., get_address_ranges())
+using address_range_descriptions = std::vector<address_range_description>;
 
 } // namespace cartesi
 
diff --git a/src/address-range.h b/src/address-range.h
new file mode 100644
index 000000000..8e7bcdb7c
--- /dev/null
+++ b/src/address-range.h
@@ -0,0 +1,392 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef ADDRESS_RANGE_H
+#define ADDRESS_RANGE_H
+
+#include <array>
+#include <bit>
+#include <cinttypes>
+#include <cstdint>
+#include <tuple>
+
+#include "assert-printf.h"
+#include "i-device-state-access.h"
+#include "interpret.h"
+#include "pma.h"
+
+namespace cartesi {
+
+// Forward declarations
+class machine;
+
+/// \file
+/// \brief Physical address range
+
+/// \brief Physical Address Range.
+/// \details The target's physical address layout is described by an array of specializations of such ranges.
+class address_range {
+
+    std::array<char, 32> m_description; ///< Description of address range for use in error messages.
+    uint64_t m_start;                   ///< Target physical address where range starts.
+    uint64_t m_length;                  ///< Length of range, in bytes.
+    uint64_t m_length_bit_ceil;         ///< Smallest power of 2 that is not smaller than length, in bytes.
+    pma_flags m_flags;                  ///< Physical memory attribute flags for range.
+
+public:
+    /// \brief Noexcept constexpr constructor for empty ranges with description
+    /// \detail Can be used to initialize a constexpr empty range
+    template <size_t N>
+    explicit constexpr address_range(const char (&description)[N]) noexcept :
+        m_description{},
+        m_start{0},
+        m_length{0},
+        m_length_bit_ceil{0},
+        m_flags{} {
+        m_flags.E = true;
+        for (unsigned i = 0; i < std::min<unsigned>(N, m_description.size() - 1); ++i) {
+            m_description[i] = description[i];
+        }
+    }
+
+    address_range(const address_range &other) = default;
+    address_range &operator=(const address_range &other) = default;
+    address_range(address_range &&other) = default;
+    address_range &operator=(address_range &&other) = default;
+    constexpr virtual ~address_range() {}; // = default; // doesn't work due to bug in gcc
+
+    template <typename ABRT, size_t N, typename... ARGS>
+    [[noreturn]] static void ABRTF(ABRT abrt, const char (&fmt)[N], ARGS... args) {
+        char buf[256]{};
+        std::ignore = snprintf(buf, std::size(buf), fmt, args...);
+        abrt(buf);
+        __builtin_trap();
+    }
+
+    /// \brief Constructor
+    /// \tparam ABRT type of function used to abort and report errors
+    /// \param description Description of address range for use in error messages (will be copied)
+    /// \param start Target physical address where range starts
+    /// \param length Length of range, in bytes
+    /// \param f Phyical memory attribute flags for range
+    template <typename ABRT>
+    address_range(const char *description, uint64_t start, uint64_t length, const pma_flags &flags, ABRT abrt) :
+        m_description{},
+        m_start{start},
+        m_length{length},
+        m_length_bit_ceil{(length >> 63) == 0 ? std::bit_ceil(length) : 0},
+        m_flags{flags} {
+        // Non-empty description is mandatory
+        if (description == nullptr || *description == '\0') {
+            ABRTF(abrt, "address range 0x%" PRIx64 ":0x%" PRIx64 " has empty description", m_start, m_length);
+        }
+        for (unsigned i = 0; i < m_description.size() - 1 && description[i] != '\0'; ++i) {
+            m_description[i] = description[i];
+        }
+        // All address ranges must be page-aligned
+        if ((m_length & ~PMA_ISTART_START_MASK) != 0) {
+            ABRTF(abrt, "length must be multiple of page size when initializing %s", m_description);
+        }
+        if ((m_start & ~PMA_ISTART_START_MASK) != 0) {
+            ABRTF(abrt, "start of %s (0x%" PRIx64 ") must be aligned to page boundary of %d bytes", m_description,
+                start, PMA_PAGE_SIZE);
+        }
+        // It must be possible to round length up to the next power of two
+        if (m_length_bit_ceil == 0) {
+            ABRTF(abrt, "range too long when initializing %s", m_description);
+        }
+        // Empty range must really be empty
+        if (m_length == 0) {
+            if (m_start != 0) {
+                ABRTF(abrt, "range with length 0 must start at 0 when initializing %s", m_description);
+            }
+            if (!m_flags.E) {
+                ABRTF(abrt, "range with length 0 must be flagged empty when initializing %s", m_description);
+            }
+            if (m_flags.M) {
+                ABRTF(abrt, "memory range cannot be empty when initializing %s", m_description);
+            }
+            if (m_flags.IO) {
+                ABRTF(abrt, "device range cannot be empty when initializing %s", m_description);
+            }
+        }
+        // Non-empty range must either be memory or device
+        if (static_cast<int>(m_flags.M) + static_cast<int>(m_flags.IO) + static_cast<int>(m_flags.E) != 1) {
+            ABRTF(abrt, "range must be one of empty, memory, or device when initializing %s", m_description);
+        }
+    }
+
+    /// \brief Checks if a range of addresses is entirely contained within this range
+    /// \param offset Start of range of interest, relative to start of this range
+    /// \param length Length of range of interest, in bytes
+    /// \returns True if and only if range of interest is entirely contained within this range
+    bool contains_relative(uint64_t offset, uint64_t length) const noexcept {
+        return get_length() >= length && offset <= get_length() - length;
+    }
+
+    /// \brief Checks if a range of addresses is entirely contained within this range
+    /// \param start Target phyisical address of start of range of interest
+    /// \param length Length of range of interest, in bytes
+    /// \returns True if and only if range of interest is entirely contained within this range
+    bool contains_absolute(uint64_t start, uint64_t length) const noexcept {
+        return start >= get_start() && contains_relative(start - get_start(), length);
+    }
+
+    /// \brief Returns PMA flags used during construction
+    /// \returns Flags
+    const pma_flags &get_flags() const noexcept {
+        return m_flags;
+    }
+
+    /// \brief Returns description of address range for use in error messages.
+    /// \returns Description
+    const char *get_description() const noexcept {
+        return m_description.data();
+    }
+
+    /// \brief Returns target physical address where range starts.
+    /// \returns Start of range
+    uint64_t get_start() const noexcept {
+        return m_start;
+    }
+
+    /// \brief Returns length of range, in bytes.
+    /// \returns Length of range
+    uint64_t get_length() const noexcept {
+        return m_length;
+    }
+
+    /// \brief Returns smallest power of 2 that is not smaller than range length, in bytes
+    /// \returns Bit-ceil of length of range
+    uint64_t get_length_bit_ceil() const noexcept {
+        return m_length_bit_ceil;
+    }
+
+    /// \brief Test if address range is occupied by memory
+    /// \returns True if and only if range is occupied by memory
+    bool is_memory() const noexcept {
+        return m_flags.M;
+    }
+
+    /// \brief Test if address range is occupied by a device
+    /// \returns True if and only if range is occupied by a device
+    bool is_device() const noexcept {
+        return m_flags.IO;
+    }
+
+    /// \brief Test if address range is empty
+    /// \returns True if and only if range is empty
+    bool is_empty() const noexcept {
+        return m_flags.E;
+    }
+
+    /// \brief Tests if range is readable
+    /// \returns True if and only if range is readable
+    bool is_readable() const noexcept {
+        return m_flags.R;
+    }
+
+    /// \brief Tests if range is writeable
+    /// \returns True if and only if range is writeable
+    bool is_writeable() const noexcept {
+        return m_flags.W;
+    }
+
+    /// \brief Tests if range is executable
+    /// \returns True if and only if range is executable
+    bool is_executable() const noexcept {
+        return m_flags.X;
+    }
+
+    /// \brief Tests if range is read-idempotent
+    /// \returns True if and only if what is read from range remains there until written to
+    bool is_read_idempotent() const noexcept {
+        return m_flags.IR;
+    }
+
+    /// \brief Tests if range is write-idempotent
+    /// \returns True if and only if what is written to range remains there and can be read until written to again
+    bool is_write_idempotent() const noexcept {
+        return m_flags.IW;
+    }
+
+    /// \brief Returns driver ID associated to range
+    /// \returns Teh driver ID
+    PMA_ISTART_DID get_driver_id() const noexcept {
+        return m_flags.DID;
+    }
+
+    /// \brief Returns packed address range istart field as per whitepaper
+    /// \returns Packed address range istart
+    uint64_t get_istart() const noexcept {
+        return pack_pma_istart(m_flags, m_start);
+    }
+
+    /// \brief Returns encoded addres range ilength field as per whitepaper
+    /// \returns Packed address range ilength
+    /// \details This currently contains only the length itself
+    uint64_t get_ilength() const noexcept {
+        return get_length();
+    }
+
+    /// \brief Read contents from address range with, no side-effects.
+    /// \param m Reference to machine.
+    /// \param offset Offset within range to start reading.
+    /// \param length Number of bytes to read.
+    /// \param data Receives pointer to start of data, or nullptr if data is constant *and* pristine (filled with
+    /// zeros).
+    /// \param scratch Pointer to memory buffer that must be able to hold \p length bytes.
+    /// \returns True if operation succeeded, false otherwise.
+    bool peek(const machine &m, uint64_t offset, uint64_t length, const unsigned char **data,
+        unsigned char *scratch) const noexcept {
+        return do_peek(m, offset, length, data, scratch);
+    };
+
+    // -----
+    // These are only for device ranges
+    // -----
+
+    /// \brief Reads a word from a device
+    /// \param da State access object through which the machine state can be accessed.
+    /// \param offset Where to start reading, relative to start of this range.
+    /// \param log2_size Log<sub>2</sub> of size of value to read (0=uint8_t, 1=uint16_t, 2=uint32_t, 3=uint64_t).
+    /// \param pval Pointer to word where value will be stored.
+    /// \returns True if operation succeeded, false otherwise.
+    bool read_device(i_device_state_access *da, uint64_t offset, int log2_size, uint64_t *pval) const noexcept {
+        return do_read_device(da, offset, log2_size, pval);
+    }
+
+    /// \brief Writes a word to a device
+    /// \param da State access object through which the machine state can be accessed.
+    /// \param offset Where to start reading, relative to start of this range.
+    /// \param log2_size Log<sub>2</sub> of size of value to write (0=uint8_t, 1=uint16_t, 2=uint32_t, 3=uint64_t).
+    /// \param val Value to write.
+    /// \returns execute::failure if operation failed, otherwise a success code if operation succeeded.
+    execute_status write_device(i_device_state_access *da, uint64_t offset, int log2_size, uint64_t val) noexcept {
+        return do_write_device(da, offset, log2_size, val);
+    }
+
+    // -----
+    // These are only for memory ranges
+    // -----
+
+    /// \brief Returns start of associated memory region in host
+    /// \returns Pointer to memory
+    const unsigned char *get_host_memory() const noexcept {
+        return do_get_host_memory();
+    }
+
+    /// \brief Returns start of associated memory region in host
+    /// \returns Pointer to memory
+    unsigned char *get_host_memory() noexcept {
+        return do_get_host_memory();
+    }
+
+    /// \brief Mark a given page as dirty
+    /// \param offset Any offset in range within desired page
+    void mark_dirty_page(uint64_t offset) noexcept {
+        do_mark_dirty_page(offset);
+    }
+
+    /// \brief Mark all pages in a range of interest as dirty
+    /// \param offset Start of range of interest, relative to start of this range
+    /// \param length Length of range of interest, in bytes
+    void mark_dirty_pages(uint64_t offset, uint64_t length) noexcept {
+        auto offset_aligned = offset &= ~(PMA_PAGE_SIZE - 1);
+        const auto length_aligned = length + (offset - offset_aligned);
+        for (; offset_aligned < length_aligned; offset_aligned += PMA_PAGE_SIZE) {
+            mark_dirty_page(offset_aligned);
+        }
+    }
+
+    /// \brief Mark a given page as clean
+    /// \param offset Any offset in range within desired page
+    void mark_clean_page(uint64_t offset) noexcept {
+        do_mark_clean_page(offset);
+    }
+
+    /// \brief Marks all pages in range as clean
+    void mark_pages_clean() noexcept {
+        do_mark_pages_clean();
+    }
+
+    /// \brief Tests if a given page is dirty
+    /// \param offset Any offset in range within desired page
+    /// \returns True if and only if page is marked dirty
+    bool is_page_marked_dirty(uint64_t offset) const noexcept {
+        return do_is_page_marked_dirty(offset);
+    }
+
+private:
+    // Default implementation of peek() always fails
+    virtual bool do_peek(const machine & /*m*/, uint64_t /*offset*/, uint64_t /*length*/,
+        const unsigned char ** /*data*/, unsigned char * /*scratch*/) const noexcept {
+        return false;
+    }
+
+    // Default implementation of read_device() for non-device ranges always fails
+    virtual bool do_read_device(i_device_state_access * /*a*/, uint64_t /*offset*/, int /*log2_size*/,
+        uint64_t * /*val*/) const noexcept {
+        return false;
+    }
+
+    // Default implementation of write_device() for non-device ranges always fails
+    virtual execute_status do_write_device(i_device_state_access * /*a*/, uint64_t /*offset*/, int /* log2_size */,
+        uint64_t /*val*/) noexcept {
+        return execute_status::failure;
+    }
+
+    // Default implementation of get_host_memory() for non-memory ranges returns nullptr
+    virtual const unsigned char *do_get_host_memory() const noexcept {
+        return nullptr;
+    }
+
+    virtual unsigned char *do_get_host_memory() noexcept {
+        return nullptr;
+    }
+
+    // Defaul implemenation always assumes every page is always dirty
+    virtual void do_mark_dirty_page(uint64_t /*offset*/) noexcept {
+        ;
+    }
+
+    virtual void do_mark_clean_page(uint64_t /*offset*/) noexcept {
+        ;
+    }
+
+    virtual void do_mark_pages_clean() noexcept {
+        ;
+    }
+
+    virtual bool do_is_page_marked_dirty(uint64_t /*offset*/) const noexcept {
+        return true;
+    }
+};
+
+template <size_t N>
+constexpr static auto make_empty_address_range(const char (&description)[N]) {
+    return address_range{description};
+}
+
+template <typename ABRT>
+static inline auto make_address_range(const char *description, uint64_t start, uint64_t length, pma_flags f,
+    ABRT abrt) {
+    return address_range{description, start, length, f, abrt};
+}
+
+} // namespace cartesi
+
+#endif // OCCUPIED_ADDRESS_RANGE_H
diff --git a/src/shadow-uarch-state.cpp b/src/assert-printf.h
similarity index 76%
rename from src/shadow-uarch-state.cpp
rename to src/assert-printf.h
index 1cb3d25e3..1bf16b675 100644
--- a/src/shadow-uarch-state.cpp
+++ b/src/assert-printf.h
@@ -14,14 +14,17 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#include "shadow-uarch-state.h"
+#ifndef PRINTF_ASSERT_H
+#define PRINTF_ASSERT_H
 
-#include "pma-driver.h"
+/// \file
+/// \brief Microarchitecture-dependent includes for printf and assert
 
-namespace cartesi {
+#ifdef MICROARCHITECTURE
+#include "uarch-runtime.h"
+#else
+#include <cassert>
+#include <cstdio>
+#endif
 
-const pma_driver shadow_uarch_state_driver = {.name = "SHADOW UARCH",
-    .read = device_read_error,
-    .write = device_write_error};
-
-} // namespace cartesi
+#endif
diff --git a/src/clint.cpp b/src/clint-address-range.cpp
similarity index 78%
rename from src/clint.cpp
rename to src/clint-address-range.cpp
index 55dbfa200..4622fa42e 100644
--- a/src/clint.cpp
+++ b/src/clint-address-range.cpp
@@ -14,19 +14,34 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#include "clint.h"
+#include "clint-address-range.h"
 
 #include <cstdint>
 
 #include "i-device-state-access.h"
 #include "interpret.h"
 #include "pma-constants.h"
-#include "pma-driver.h"
 #include "riscv-constants.h"
 #include "rtc.h"
 
 namespace cartesi {
 
+/// \brief Mapping between CSRs and their relative addresses in CLINT memory
+enum class clint_csr {
+    msip0 = UINT64_C(0), // Machine software interrupt for hart 0
+    mtimecmp = UINT64_C(0x4000),
+    mtime = UINT64_C(0xbff8)
+};
+
+/// \brief Obtains the relative address of the msip0 CSR in HTIF memory.
+static constexpr auto clint_msip0_rel_addr = static_cast<uint64_t>(clint_csr::msip0);
+
+/// \brief Obtains the relative address of the mtime CSR in HTIF memory.
+static constexpr auto clint_mtime_rel_addr = static_cast<uint64_t>(clint_csr::mtime);
+
+/// \brief Obtains the relative address of the mtimecmp CSR in HTIF memory.
+constexpr auto clint_mtimecmp_rel_addr = static_cast<uint64_t>(clint_csr::mtimecmp);
+
 static constexpr uint64_t base(uint64_t v) {
     return v - (v % PMA_PAGE_SIZE);
 }
@@ -61,8 +76,8 @@ static bool clint_read_mtimecmp(i_device_state_access *a, uint64_t *val, int log
     return false;
 }
 
-/// \brief CLINT device read callback. See ::pma_read.
-static bool clint_read(void * /*context*/, i_device_state_access *a, uint64_t offset, uint64_t *val, int log2_size) {
+bool clint_address_range::do_read_device(i_device_state_access *a, uint64_t offset, int log2_size,
+    uint64_t *val) const noexcept {
     switch (offset) {
         case clint_msip0_rel_addr:
             return clint_read_msip(a, val, log2_size);
@@ -76,9 +91,8 @@ static bool clint_read(void * /*context*/, i_device_state_access *a, uint64_t of
     }
 }
 
-/// \brief CLINT device read callback. See ::pma_write.
-static execute_status clint_write(void * /*context*/, i_device_state_access *a, uint64_t offset, uint64_t val,
-    int log2_size) {
+execute_status clint_address_range::do_write_device(i_device_state_access *a, uint64_t offset, int log2_size,
+    uint64_t val) noexcept {
     switch (offset) {
         case clint_msip0_rel_addr:
             if (log2_size == 2) {
@@ -108,6 +122,4 @@ static execute_status clint_write(void * /*context*/, i_device_state_access *a,
     }
 }
 
-const pma_driver clint_driver = {.name = "CLINT", .read = clint_read, .write = clint_write};
-
 } // namespace cartesi
diff --git a/src/clint-address-range.h b/src/clint-address-range.h
new file mode 100644
index 000000000..b1d46aef0
--- /dev/null
+++ b/src/clint-address-range.h
@@ -0,0 +1,70 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef CLINT_ADDRESS_RANGE_H
+#define CLINT_ADDRESS_RANGE_H
+
+#include <cstdint>
+
+#include "pristine-address-range.h"
+
+/// \file
+/// \brief Core-Local Interruptor device.
+
+namespace cartesi {
+
+class clint_address_range final : public pristine_address_range {
+
+    static constexpr pma_flags m_clint_flags{
+        .M = false,
+        .IO = true,
+        .E = false,
+        .R = true,
+        .W = true,
+        .X = false,
+        .IR = false,
+        .IW = false,
+        .DID = PMA_ISTART_DID::CLINT,
+    };
+
+public:
+    template <typename ABRT>
+    clint_address_range(uint64_t start, uint64_t length, ABRT abrt) :
+        pristine_address_range("CLINT device", start, length, m_clint_flags, abrt) {
+        ;
+    }
+
+    clint_address_range(const clint_address_range &other) = default;
+    clint_address_range &operator=(const clint_address_range &other) = default;
+    clint_address_range(clint_address_range &&other) = default;
+    clint_address_range &operator=(clint_address_range &&other) = default;
+    ~clint_address_range() override = default;
+
+private:
+    bool do_read_device(i_device_state_access *a, uint64_t offset, int log2_size,
+        uint64_t *pval) const noexcept override;
+    execute_status do_write_device(i_device_state_access *a, uint64_t offset, int log2_size,
+        uint64_t val) noexcept override;
+};
+
+template <typename ABRT>
+static inline clint_address_range make_clint_address_range(uint64_t start, uint64_t length, ABRT abrt) {
+    return clint_address_range{start, length, abrt};
+}
+
+} // namespace cartesi
+
+#endif
diff --git a/src/clint-factory.cpp b/src/clint-factory.cpp
deleted file mode 100644
index 0dd9ba3e7..000000000
--- a/src/clint-factory.cpp
+++ /dev/null
@@ -1,32 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#include "clint-factory.h"
-
-#include <cstdint>
-
-#include "clint.h"
-#include "pma-constants.h"
-#include "pma.h"
-
-namespace cartesi {
-
-pma_entry make_clint_pma_entry(uint64_t start, uint64_t length) {
-    const pma_entry::flags f{.R = true, .W = true, .X = false, .IR = false, .IW = false, .DID = PMA_ISTART_DID::CLINT};
-    return make_device_pma_entry("CLINT device", start, length, pma_peek_pristine, &clint_driver).set_flags(f);
-}
-
-} // namespace cartesi
diff --git a/src/clint-factory.h b/src/clint-factory.h
deleted file mode 100644
index 1910bfd0e..000000000
--- a/src/clint-factory.h
+++ /dev/null
@@ -1,34 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef CLINT_FACTORY_H
-#define CLINT_FACTORY_H
-
-#include <cstdint>
-
-#include "pma.h"
-
-namespace cartesi {
-
-/// \brief Creates a PMA entry for the CLINT device
-/// \param start Start address for memory range.
-/// \param length Length of memory range.
-/// \returns Corresponding PMA entry
-pma_entry make_clint_pma_entry(uint64_t start, uint64_t length);
-
-} // namespace cartesi
-
-#endif
diff --git a/src/clint.h b/src/clint.h
deleted file mode 100644
index 04d228885..000000000
--- a/src/clint.h
+++ /dev/null
@@ -1,50 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef CLINT_H
-#define CLINT_H
-
-#include <cstdint>
-
-#include "pma-driver.h"
-
-/// \file
-/// \brief Clock interruptor device.
-
-namespace cartesi {
-
-/// \brief Global CLINT device driver instance
-extern const pma_driver clint_driver;
-
-/// \brief Mapping between CSRs and their relative addresses in CLINT memory
-enum class clint_csr {
-    msip0 = UINT64_C(0), // Machine software interrupt for hart 0
-    mtimecmp = UINT64_C(0x4000),
-    mtime = UINT64_C(0xbff8)
-};
-
-/// \brief Obtains the relative address of the msip0 CSR in HTIF memory.
-static constexpr auto clint_msip0_rel_addr = static_cast<uint64_t>(clint_csr::msip0);
-
-/// \brief Obtains the relative address of the mtime CSR in HTIF memory.
-static constexpr auto clint_mtime_rel_addr = static_cast<uint64_t>(clint_csr::mtime);
-
-/// \brief Obtains the relative address of the mtimecmp CSR in HTIF memory.
-constexpr auto clint_mtimecmp_rel_addr = static_cast<uint64_t>(clint_csr::mtimecmp);
-
-} // namespace cartesi
-
-#endif
diff --git a/src/clua-i-virtual-machine.cpp b/src/clua-i-virtual-machine.cpp
index e9a89018d..0380f23a7 100644
--- a/src/clua-i-virtual-machine.cpp
+++ b/src/clua-i-virtual-machine.cpp
@@ -682,12 +682,12 @@ static int machine_obj_index_reset_uarch(lua_State *L) {
     return 0;
 }
 
-/// \brief This is the machine:get_memory_ranges() method implementation.
+/// \brief This is the machine:get_address_ranges() method implementation.
 /// \param L Lua state.
-static int machine_obj_index_get_memory_ranges(lua_State *L) {
+static int machine_obj_index_get_address_ranges(lua_State *L) {
     auto &m = clua_check<clua_managed_cm_ptr<cm_machine>>(L, 1);
     const char *ranges = nullptr;
-    if (cm_get_memory_ranges(m.get(), &ranges) != 0) {
+    if (cm_get_address_ranges(m.get(), &ranges) != 0) {
         return luaL_error(L, "%s", cm_get_last_error_message());
     }
     clua_push_json_table(L, ranges);
@@ -1049,7 +1049,7 @@ static const auto machine_obj_index = cartesi::clua_make_luaL_Reg_array({
     {"destroy", machine_obj_index_destroy},
     {"get_default_config", machine_obj_index_get_default_config},
     {"get_initial_config", machine_obj_index_get_initial_config},
-    {"get_memory_ranges", machine_obj_index_get_memory_ranges},
+    {"get_address_ranges", machine_obj_index_get_address_ranges},
     {"get_proof", machine_obj_index_get_proof},
     {"get_reg_address", machine_obj_index_get_reg_address},
     {"get_root_hash", machine_obj_index_get_root_hash},
diff --git a/src/dump.h b/src/dump.h
index f7c00c538..4cfc8e2c8 100644
--- a/src/dump.h
+++ b/src/dump.h
@@ -18,17 +18,11 @@
 
 #include <tuple>
 
-#ifdef MICROARCHITECTURE
-template <size_t N, typename... ARGS>
-static inline void D_PRINTF(const char (&fmt)[N], ARGS... args) {
-    std::ignore = printf(fmt, args...);
-}
-#else
-#include <cstdio>
+#include "assert-printf.h"
+
 template <size_t N, typename... ARGS>
 static inline auto D_PRINTF(const char (&fmt)[N], ARGS... args) {
     std::ignore = fprintf(stderr, fmt, args...);
 }
-#endif
 
 #endif // DUMP_H
diff --git a/src/find-pma-entry.h b/src/find-pma-entry.h
index 1cb857ca4..73cb36503 100644
--- a/src/find-pma-entry.h
+++ b/src/find-pma-entry.h
@@ -14,15 +14,17 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#ifndef FIND_PMA_ENTRY_H
-#define FIND_PMA_ENTRY_H
+#ifndef FIND_ADDRESS_RANGE_H
+#define FIND_ADDRESS_RANGE_H
 
-#include "compiler-defines.h"
 #include <cstdint>
 
+#include "address-range.h"
+#include "compiler-defines.h"
+
 namespace cartesi {
 
-/// \brief Returns PMAs entry where a word falls.
+/// \brief Returns address range associated to the PMA entry where a word falls.
 /// \tparam T uint8_t, uint16_t, uint32_t, or uint64_t.
 /// \tparam STATE_ACCESS Class of machine state accessor object.
 /// \param a Machine state accessor object.
@@ -30,41 +32,34 @@ namespace cartesi {
 /// \param index Receives index where PMA entry was found.
 /// \returns PMA entry where word falls, or empty sentinel.
 template <typename T, typename STATE_ACCESS>
-auto &find_pma_entry(STATE_ACCESS &a, uint64_t paddr, uint64_t &index) {
-    [[maybe_unused]] auto note = a.make_scoped_note("find_pma_entry");
+address_range &find_pma(const STATE_ACCESS a, uint64_t paddr, uint64_t &index) {
+    [[maybe_unused]] auto note = a.make_scoped_note("find_pma");
     index = 0;
     while (true) {
-        auto &pma = a.read_pma_entry(index);
-        const auto length = pma.get_length();
+        auto &ar = a.read_pma(index);
         // The pmas array always contain a sentinel.
         // It is an entry with zero length.
         // If we hit it, return it
-        if (unlikely(length == 0)) {
-            return pma;
+        if (unlikely(ar.get_length() == 0)) {
+            return ar;
         }
-        // Otherwise, if we found an entry where the access fits, return it
-        // Note the "strange" order of arithmetic operations.
-        // This is to ensure there is no overflow.
-        // Since we know paddr >= start, there is no chance of overflow in the first subtraction.
-        // Since length is at least 4096 (an entire page), there is no chance of overflow in the second subtraction.
-        const auto start = pma.get_start();
-        if (paddr >= start && paddr - start <= length - sizeof(T)) {
-            return pma;
+        if (ar.contains_absolute(paddr, sizeof(T))) {
+            return ar;
         }
         ++index;
     }
 }
 
-/// \brief Returns PMAs entry where a word falls.
+/// \brief Returns address range associated to the PMA entry where a word falls.
 /// \tparam T uint8_t, uint16_t, uint32_t, or uint64_t.
 /// \tparam STATE_ACCESS Class of machine state accessor object.
 /// \param a Machine state accessor object.
 /// \param paddr Target physical address of word.
 /// \returns PMA entry where word falls, or empty sentinel.
 template <typename T, typename STATE_ACCESS>
-FORCE_INLINE auto &find_pma_entry(STATE_ACCESS &a, uint64_t paddr) {
+FORCE_INLINE auto &find_pma(const STATE_ACCESS a, uint64_t paddr) {
     uint64_t index = 0;
-    return find_pma_entry<T>(a, paddr, index);
+    return find_pma<T>(a, paddr, index);
 }
 
 } // namespace cartesi
diff --git a/src/htif.cpp b/src/htif-address-range.cpp
similarity index 91%
rename from src/htif.cpp
rename to src/htif-address-range.cpp
index 1a17d1e02..4af6019ce 100644
--- a/src/htif.cpp
+++ b/src/htif-address-range.cpp
@@ -14,13 +14,12 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#include "htif.h"
+#include "htif-address-range.h"
 
 #include <cstdint>
 
+#include "htif-constants.h"
 #include "i-device-state-access.h"
-#include "interpret.h"
-#include "pma-driver.h"
 
 namespace cartesi {
 
@@ -30,8 +29,8 @@ static constexpr auto htif_ihalt_rel_addr = static_cast<uint64_t>(htif_csr::ihal
 static constexpr auto htif_iconsole_rel_addr = static_cast<uint64_t>(htif_csr::iconsole);
 static constexpr auto htif_iyield_rel_addr = static_cast<uint64_t>(htif_csr::iyield);
 
-/// \brief HTIF device read callback. See ::pma_read.
-static bool htif_read(void * /*context*/, i_device_state_access *a, uint64_t offset, uint64_t *pval, int log2_size) {
+bool htif_address_range::do_read_device(i_device_state_access *a, uint64_t offset, int log2_size,
+    uint64_t *pval) const noexcept {
     // Our HTIF only supports 64-bit reads
     if (log2_size != 3) {
         return false;
@@ -129,9 +128,9 @@ static execute_status htif_write_tohost(i_device_state_access *a, uint64_t tohos
     }
 }
 
-/// \brief HTIF device write callback. See ::pma_write.
-static execute_status htif_write(void * /*context*/, i_device_state_access *a, uint64_t offset, uint64_t val,
-    int log2_size) {
+execute_status htif_address_range::do_write_device(i_device_state_access *a, uint64_t offset, int log2_size,
+    uint64_t val) noexcept {
+
     // Our HTIF only supports 64-bit writes
     if (log2_size != 3) {
         return execute_status::failure;
@@ -150,6 +149,4 @@ static execute_status htif_write(void * /*context*/, i_device_state_access *a, u
     }
 }
 
-const pma_driver htif_driver{.name = "HTIF", .read = htif_read, .write = htif_write};
-
 } // namespace cartesi
diff --git a/src/htif-address-range.h b/src/htif-address-range.h
new file mode 100644
index 000000000..d7fd5cde8
--- /dev/null
+++ b/src/htif-address-range.h
@@ -0,0 +1,72 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef HTIF_ADDRESS_RANGE_H
+#define HTIF_ADDRESS_RANGE_H
+
+#include <cstdint>
+
+#include "i-device-state-access.h"
+#include "pma-constants.h"
+#include "pristine-address-range.h"
+
+/// \file
+/// \brief Host-Target InterFace device.
+
+namespace cartesi {
+
+class htif_address_range final : public pristine_address_range {
+
+    static constexpr pma_flags m_htif_flags{
+        .M = false,
+        .IO = true,
+        .E = false,
+        .R = true,
+        .W = true,
+        .X = false,
+        .IR = false,
+        .IW = false,
+        .DID = PMA_ISTART_DID::HTIF,
+    };
+
+public:
+    template <typename ABRT>
+    htif_address_range(uint64_t start, uint64_t length, ABRT abrt) :
+        pristine_address_range("HTIF device", start, length, m_htif_flags, abrt) {
+        ;
+    }
+
+    htif_address_range(const htif_address_range &other) = default;
+    htif_address_range &operator=(const htif_address_range &other) = default;
+    htif_address_range(htif_address_range &&other) = default;
+    htif_address_range &operator=(htif_address_range &&other) = default;
+    ~htif_address_range() override = default;
+
+private:
+    bool do_read_device(i_device_state_access *a, uint64_t offset, int log2_size,
+        uint64_t *pval) const noexcept override;
+    execute_status do_write_device(i_device_state_access *a, uint64_t offset, int log2_size,
+        uint64_t val) noexcept override;
+};
+
+template <typename ABRT>
+static inline htif_address_range make_htif_address_range(uint64_t start, uint64_t length, ABRT abrt) {
+    return htif_address_range{start, length, abrt};
+}
+
+} // namespace cartesi
+
+#endif
diff --git a/src/htif.h b/src/htif-constants.h
similarity index 81%
rename from src/htif.h
rename to src/htif-constants.h
index b4cb6afc5..1a57a13f6 100644
--- a/src/htif.h
+++ b/src/htif-constants.h
@@ -14,23 +14,23 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#ifndef HTIF_H
-#define HTIF_H
+#ifndef HTIF_CONSTANTS_H
+#define HTIF_CONSTANTS_H
 
 #include <cstdint>
 
 #include "htif-defines.h"
-#include "machine-c-api.h"
-#include "pma-defines.h"
-#include "pma-driver.h"
 
 /// \file
-/// \brief Host-Target interface device.
+/// \brief Host-Target InterFace device.
 
 namespace cartesi {
 
-/// \brief Global HTIF device driver instance
-extern const pma_driver htif_driver;
+// helper for using UINT64_C with defines
+#ifndef EXPAND_UINT64_C
+// NOLINTNEXTLINE(cppcoreguidelines-macro-usage)
+#define EXPAND_UINT64_C(a) UINT64_C(a)
+#endif
 
 // Forward declarations
 /// \brief HTIF shifts
@@ -122,15 +122,6 @@ enum class htif_csr {
     iyield = UINT64_C(0x20)
 };
 
-static_assert(HTIF_YIELD_AUTOMATIC_REASON_PROGRESS_DEF == CM_CMIO_YIELD_AUTOMATIC_REASON_PROGRESS);
-static_assert(HTIF_YIELD_AUTOMATIC_REASON_TX_OUTPUT_DEF == CM_CMIO_YIELD_AUTOMATIC_REASON_TX_OUTPUT);
-static_assert(HTIF_YIELD_AUTOMATIC_REASON_TX_REPORT_DEF == CM_CMIO_YIELD_AUTOMATIC_REASON_TX_REPORT);
-static_assert(HTIF_YIELD_MANUAL_REASON_RX_ACCEPTED_DEF == CM_CMIO_YIELD_MANUAL_REASON_RX_ACCEPTED);
-static_assert(HTIF_YIELD_MANUAL_REASON_RX_REJECTED_DEF == CM_CMIO_YIELD_MANUAL_REASON_RX_REJECTED);
-static_assert(HTIF_YIELD_MANUAL_REASON_TX_EXCEPTION_DEF == CM_CMIO_YIELD_MANUAL_REASON_TX_EXCEPTION);
-static_assert(HTIF_YIELD_REASON_ADVANCE_STATE_DEF == CM_CMIO_YIELD_REASON_ADVANCE_STATE);
-static_assert(HTIF_YIELD_REASON_INSPECT_STATE_DEF == CM_CMIO_YIELD_REASON_INSPECT_STATE);
-
 } // namespace cartesi
 
 #endif
diff --git a/src/htif-factory.cpp b/src/htif-factory.cpp
deleted file mode 100644
index f09b2fb39..000000000
--- a/src/htif-factory.cpp
+++ /dev/null
@@ -1,32 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#include "htif-factory.h"
-
-#include <cstdint>
-
-#include "htif.h"
-#include "pma-constants.h"
-#include "pma.h"
-
-namespace cartesi {
-
-pma_entry make_htif_pma_entry(uint64_t start, uint64_t length) {
-    const pma_entry::flags f{.R = true, .W = true, .X = false, .IR = false, .IW = false, .DID = PMA_ISTART_DID::HTIF};
-    return make_device_pma_entry("HTIF device", start, length, pma_peek_pristine, &htif_driver).set_flags(f);
-}
-
-} // namespace cartesi
diff --git a/src/htif-factory.h b/src/htif-factory.h
deleted file mode 100644
index 1bba5844c..000000000
--- a/src/htif-factory.h
+++ /dev/null
@@ -1,31 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef HTIF_FACTORY_H
-#define HTIF_FACTORY_H
-
-#include <cstdint>
-
-#include "pma.h"
-
-namespace cartesi {
-
-/// \brief Creates a PMA entry for the HTIF device
-pma_entry make_htif_pma_entry(uint64_t start, uint64_t length);
-
-} // namespace cartesi
-
-#endif
diff --git a/src/i-state-access.h b/src/i-state-access.h
index 6e7be2874..4fc9bbb25 100644
--- a/src/i-state-access.h
+++ b/src/i-state-access.h
@@ -36,12 +36,6 @@ namespace cartesi {
 // Forward declarations
 enum class bracket_type;
 
-// Type trait that should return the pma_entry type for a state access class
-template <typename STATE_ACCESS>
-struct i_state_access_pma_entry {};
-template <typename STATE_ACCESS>
-using i_state_access_pma_entry_t = typename i_state_access_pma_entry<STATE_ACCESS>::type;
-
 // Type trait that should return the fast_addr type for a state access class
 template <typename STATE_ACCESS>
 struct i_state_access_fast_addr {};
@@ -121,7 +115,6 @@ class i_state_access { // CRTP
     }
 
 public:
-    using pma_entry = i_state_access_pma_entry_t<DERIVED>;
     using fast_addr = i_state_access_fast_addr_t<DERIVED>;
 
     /// \brief Works as printf if we are dumping state accesses, otherwise does nothing
@@ -274,11 +267,11 @@ class i_state_access { // CRTP
 
     /// \brief Reads PMA entry at a given index.
     /// \param index Index of PMA
-    pma_entry &read_pma_entry(uint64_t index) const {
-        auto &pma = derived().do_read_pma_entry(index);
-        DSA_PRINTF("%s::read_pma_entry(%" PRIu64 ") = {%s, 0x%" PRIx64 ", 0x%" PRIx64 "}\n", get_name(), index,
-            pma_get_DID_name(pma.get_istart_DID()), pma.get_start(), pma.get_length());
-        return pma;
+    address_range &read_pma(uint64_t index) const {
+        auto &ar = derived().do_read_pma(index);
+        DSA_PRINTF("%s::read_address_range(%" PRIu64 ") = {%s, 0x%" PRIx64 ", 0x%" PRIx64 "}\n", get_name(), index,
+            pma_get_DID_name(ar.get_driver_id()), ar.get_start(), ar.get_length());
+        return ar;
     }
 
     /// \brief Converts a target physical address to the implementation-defined fast address
diff --git a/src/i-virtual-machine.h b/src/i-virtual-machine.h
index 2ea1dd3cd..b307d8d6d 100644
--- a/src/i-virtual-machine.h
+++ b/src/i-virtual-machine.h
@@ -21,9 +21,9 @@
 #include <string>
 
 #include "access-log.h"
+#include "address-range-description.h"
 #include "interpret.h"
 #include "machine-config.h"
-#include "machine-memory-range-descr.h"
 #include "machine-merkle-tree.h"
 #include "machine.h"
 #include "uarch-interpret.h"
@@ -200,8 +200,8 @@ class i_virtual_machine {
     }
 
     /// \brief Returns a list of descriptions for all PMA entries registered in the machine, sorted by start
-    virtual machine_memory_range_descrs get_memory_ranges() const {
-        return do_get_memory_ranges();
+    virtual address_range_descriptions get_address_ranges() const {
+        return do_get_address_ranges();
     }
 
     /// \brief Sends cmio response.
@@ -283,7 +283,7 @@ class i_virtual_machine {
     virtual void do_reset_uarch() = 0;
     virtual access_log do_log_reset_uarch(const access_log::type &log_type) = 0;
     virtual uarch_interpreter_break_reason do_run_uarch(uint64_t uarch_cycle_end) = 0;
-    virtual machine_memory_range_descrs do_get_memory_ranges() const = 0;
+    virtual address_range_descriptions do_get_address_ranges() const = 0;
     virtual void do_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length) = 0;
     virtual access_log do_log_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
         const access_log::type &log_type) = 0;
diff --git a/src/interpret.cpp b/src/interpret.cpp
index 02a272b65..282344f4b 100644
--- a/src/interpret.cpp
+++ b/src/interpret.cpp
@@ -995,22 +995,21 @@ static NO_INLINE std::pair<bool, uint64_t> read_virtual_memory_slow(const STATE_
         return {false, pc};
     }
     uint64_t pma_index = 0;
-    const auto &pma = find_pma_entry<T>(a, paddr, pma_index);
-    if (likely(pma.get_istart_R())) {
-        if (likely(pma.get_istart_M())) {
+    const auto &ar = find_pma<T>(a, paddr, pma_index);
+    if (likely(ar.is_readable())) {
+        if (likely(ar.is_memory())) {
             [[maybe_unused]] auto note = a.make_scoped_note("read memory");
             const auto faddr = replace_tlb_entry<TLB_READ>(a, vaddr, paddr, pma_index);
             a.template read_memory_word<T>(faddr, pma_index, pval);
             return {true, pc};
         }
-        if (likely(pma.get_istart_IO())) {
+        if (likely(ar.is_device())) {
             [[maybe_unused]] auto note = a.make_scoped_note("read device");
-            const uint64_t offset = paddr - pma.get_start();
+            const uint64_t offset = paddr - ar.get_start();
             uint64_t val{};
             device_state_access da(a, mcycle);
             // If we do not know how to read, we treat this as a PMA violation
-            const bool status = pma.get_device_noexcept().get_driver()->read(pma.get_device_noexcept().get_context(),
-                &da, offset, &val, log2_size_v<U>);
+            const bool status = ar.read_device(&da, offset, log2_size_v<U>, &val);
             if (likely(status)) {
                 *pval = static_cast<T>(val);
                 // device logs its own state accesses
@@ -1087,18 +1086,17 @@ static NO_INLINE std::pair<execute_status, uint64_t> write_virtual_memory_slow(c
         return {execute_status::failure, pc};
     }
     uint64_t pma_index = 0;
-    auto &pma = find_pma_entry<T>(a, paddr, pma_index);
-    if (likely(pma.get_istart_W())) {
-        if (likely(pma.get_istart_M())) {
+    auto &ar = find_pma<T>(a, paddr, pma_index);
+    if (likely(ar.is_writeable())) {
+        if (likely(ar.is_memory())) {
             const auto faddr = replace_tlb_entry<TLB_WRITE>(a, vaddr, paddr, pma_index);
             a.write_memory_word(faddr, pma_index, static_cast<T>(val64));
             return {execute_status::success, pc};
         }
-        if (likely(pma.get_istart_IO())) {
-            const uint64_t offset = paddr - pma.get_start();
+        if (likely(ar.is_device())) {
+            const uint64_t offset = paddr - ar.get_start();
             device_state_access da(a, mcycle);
-            auto status = pma.get_device_noexcept().get_driver()->write(pma.get_device_noexcept().get_context(), &da,
-                offset, static_cast<U>(static_cast<T>(val64)), log2_size_v<U>);
+            auto status = ar.write_device(&da, offset, log2_size_v<U>, static_cast<U>(static_cast<T>(val64)));
             // If we do not know how to write, we treat this as a PMA violation
             if (likely(status != execute_status::failure)) {
                 return {status, pc};
@@ -5396,10 +5394,10 @@ static FORCE_INLINE fetch_status fetch_translate_pc_slow(const STATE_ACCESS a, u
         return fetch_status::exception;
     }
     // Walk memory map to find the range that contains the physical address
-    const auto &pma = find_pma_entry<uint16_t>(a, paddr, pma_index);
+    const auto &ar = find_pma<uint16_t>(a, paddr, pma_index);
     // We only execute directly from RAM (as in "random access memory")
     // If the range is not memory or not executable, this as a PMA violation
-    if (unlikely(!pma.get_istart_M() || !pma.get_istart_X())) {
+    if (unlikely(!ar.is_memory() || !ar.is_executable())) {
         pc = raise_exception(a, pc, MCAUSE_INSN_ACCESS_FAULT, vaddr);
         return fetch_status::exception;
     }
diff --git a/src/json-util.cpp b/src/json-util.cpp
index 3df07f1ff..e59cf5f6c 100644
--- a/src/json-util.cpp
+++ b/src/json-util.cpp
@@ -33,12 +33,12 @@
 #include <json.hpp>
 
 #include "access-log.h"
+#include "address-range-description.h"
 #include "base64.h"
 #include "bracket-note.h"
 #include "interpret.h"
 #include "jsonrpc-fork-result.h"
 #include "machine-config.h"
-#include "machine-memory-range-descr.h"
 #include "machine-merkle-tree.h"
 #include "machine-runtime-config.h"
 #include "machine.h"
@@ -1639,7 +1639,7 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
     const std::string &path);
 
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, machine_memory_range_descr &value,
+void ju_get_opt_field(const nlohmann::json &j, const K &key, address_range_description &value,
     const std::string &path) {
     if (!contains(j, key)) {
         return;
@@ -1651,23 +1651,23 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, machine_memory_rang
     ju_get_opt_field(jconfig, "description"s, value.description, new_path);
 }
 
-template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key,
-    machine_memory_range_descr &value, const std::string &path);
+template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, address_range_description &value,
+    const std::string &path);
 
 template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key,
-    machine_memory_range_descr &value, const std::string &path);
+    address_range_description &value, const std::string &path);
 
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, machine_memory_range_descrs &value,
+void ju_get_opt_field(const nlohmann::json &j, const K &key, address_range_descriptions &value,
     const std::string &path) {
     ju_get_opt_vector_like_field(j, key, value, path);
 }
 
 template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key,
-    machine_memory_range_descrs &value, const std::string &path);
+    address_range_descriptions &value, const std::string &path);
 
 template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key,
-    machine_memory_range_descrs &value, const std::string &path);
+    address_range_descriptions &value, const std::string &path);
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, fork_result &value, const std::string &path) {
@@ -1997,11 +1997,11 @@ void to_json(nlohmann::json &j, const machine_runtime_config &runtime) {
     };
 }
 
-void to_json(nlohmann::json &j, const machine_memory_range_descr &mrd) {
+void to_json(nlohmann::json &j, const address_range_description &mrd) {
     j = nlohmann::json{{"length", mrd.length}, {"start", mrd.start}, {"description", mrd.description}};
 }
 
-void to_json(nlohmann::json &j, const machine_memory_range_descrs &mrds) {
+void to_json(nlohmann::json &j, const address_range_descriptions &mrds) {
     j = nlohmann::json::array();
     std::transform(mrds.cbegin(), mrds.cend(), std::back_inserter(j),
         [](const auto &a) -> nlohmann::json { return a; });
diff --git a/src/json-util.h b/src/json-util.h
index 8a67c377e..5764a3dff 100644
--- a/src/json-util.h
+++ b/src/json-util.h
@@ -28,11 +28,11 @@
 #include <json.hpp>
 
 #include "access-log.h"
+#include "address-range-description.h"
 #include "bracket-note.h"
 #include "interpret.h"
 #include "jsonrpc-fork-result.h"
 #include "machine-config.h"
-#include "machine-memory-range-descr.h"
 #include "machine-merkle-tree.h"
 #include "machine-runtime-config.h"
 #include "machine.h"
@@ -474,24 +474,24 @@ template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, machine_config &value,
     const std::string &path = "params/");
 
-/// \brief Attempts to load a machine_memory_range_descr object from a field in a JSON object
+/// \brief Attempts to load a address_range_description object from a field in a JSON object
 /// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
 /// \param j JSON object to load from
 /// \param key Key to load value from
 /// \param value Object to store value
 /// \param path Path to j
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, machine_memory_range_descr &value,
+void ju_get_opt_field(const nlohmann::json &j, const K &key, address_range_description &value,
     const std::string &path = "params/");
 
-/// \brief Attempts to load a machine_memory_range_descrs object from a field in a JSON object
+/// \brief Attempts to load a address_range_descriptions object from a field in a JSON object
 /// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
 /// \param j JSON object to load from
 /// \param key Key to load value from
 /// \param value Object to store value
 /// \param path Path to j
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, machine_memory_range_descrs &value,
+void ju_get_opt_field(const nlohmann::json &j, const K &key, address_range_descriptions &value,
     const std::string &path = "params/");
 
 /// \brief Attempts to load a fork_result object from a field in a JSON object
@@ -625,8 +625,8 @@ void to_json(nlohmann::json &j, const concurrency_runtime_config &config);
 void to_json(nlohmann::json &j, const htif_runtime_config &config);
 void to_json(nlohmann::json &j, const machine_runtime_config &runtime);
 void to_json(nlohmann::json &j, const machine::reg &reg);
-void to_json(nlohmann::json &j, const machine_memory_range_descr &mrd);
-void to_json(nlohmann::json &j, const machine_memory_range_descrs &mrds);
+void to_json(nlohmann::json &j, const address_range_description &mrd);
+void to_json(nlohmann::json &j, const address_range_descriptions &mrds);
 void to_json(nlohmann::json &j, const fork_result &fork_result);
 void to_json(nlohmann::json &j, const semantic_version &version);
 
@@ -787,14 +787,14 @@ extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &k
     const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, machine_config &value,
     const std::string &base = "params/");
-extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, machine_memory_range_descr &value,
+extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, address_range_description &value,
     const std::string &base = "params/");
-extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key,
-    machine_memory_range_descr &value, const std::string &base = "params/");
-extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, machine_memory_range_descrs &value,
+extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, address_range_description &value,
+    const std::string &base = "params/");
+extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, address_range_descriptions &value,
     const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key,
-    machine_memory_range_descrs &value, const std::string &base = "params/");
+    address_range_descriptions &value, const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, fork_result &value,
     const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, fork_result &value,
diff --git a/src/jsonrpc-discover.json b/src/jsonrpc-discover.json
index 24a90b15e..aa613250b 100644
--- a/src/jsonrpc-discover.json
+++ b/src/jsonrpc-discover.json
@@ -712,14 +712,14 @@
       }
     },
     {
-      "name": "machine.get_memory_ranges",
-      "summary": "Returns a list with descriptions for all of the machine's memory ranges",
+      "name": "machine.get_address_ranges",
+      "summary": "Returns a list with descriptions for all of the machine's address ranges",
       "params": [],
       "result": {
         "name": "ranges",
-        "description": "Array of memory range descriptions",
+        "description": "Array of address range descriptions",
         "schema": {
-          "$ref": "#/components/schemas/MemoryRangeDescriptionArray"
+          "$ref": "#/components/schemas/AddressRangeDescriptionArray"
         }
       }
     },
@@ -1996,8 +1996,8 @@
           "uarch_halt_flag"
         ]
       },
-      "MemoryRangeDescription": {
-        "title": "MemoryRangeDescription",
+      "AddressRangeDescription": {
+        "title": "AddressRangeDescription",
         "type": "object",
         "properties": {
           "start": {
@@ -2011,11 +2011,11 @@
           }
         }
       },
-      "MemoryRangeDescriptionArray": {
-        "title": "MemoryRangeDescriptionArray",
+      "AddressRangeDescriptionArray": {
+        "title": "AddressRangeDescriptionArray",
         "type": "array",
         "items": {
-          "$ref": "#/components/schemas/MemoryRangeDescription"
+          "$ref": "#/components/schemas/AddressRangeDescription"
         }
       }
     }
diff --git a/src/jsonrpc-machine-c-api.cpp b/src/jsonrpc-machine-c-api.cpp
index db79afdec..30f4d5a4e 100644
--- a/src/jsonrpc-machine-c-api.cpp
+++ b/src/jsonrpc-machine-c-api.cpp
@@ -16,7 +16,6 @@
 
 #include "jsonrpc-machine-c-api.h"
 
-#include <cassert>
 #include <csignal>
 #include <cstdint>
 #include <cstdio>
diff --git a/src/jsonrpc-remote-machine.cpp b/src/jsonrpc-remote-machine.cpp
index 7045909ce..de422fab0 100644
--- a/src/jsonrpc-remote-machine.cpp
+++ b/src/jsonrpc-remote-machine.cpp
@@ -1358,16 +1358,16 @@ static json jsonrpc_machine_verify_dirty_page_maps_handler(const json &j,
     return jsonrpc_response_ok(j, session->handler->machine->verify_dirty_page_maps());
 }
 
-/// \brief JSONRPC handler for the machine.get_memory_ranges method
+/// \brief JSONRPC handler for the machine.get_address_ranges method
 /// \param j JSON request object
 /// \param session HTTP session
 /// \returns JSON response object
-static json jsonrpc_machine_get_memory_ranges_handler(const json &j, const std::shared_ptr<http_session> &session) {
+static json jsonrpc_machine_get_address_ranges_handler(const json &j, const std::shared_ptr<http_session> &session) {
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
     jsonrpc_check_no_params(j);
-    return jsonrpc_response_ok(j, session->handler->machine->get_memory_ranges());
+    return jsonrpc_response_ok(j, session->handler->machine->get_address_ranges());
 }
 
 /// \brief JSONRPC handler for the machine.send_cmio_response method
@@ -1507,7 +1507,7 @@ static json jsonrpc_dispatch_method(const json &j, const std::shared_ptr<http_se
         {"machine.set_runtime_config", jsonrpc_machine_set_runtime_config_handler},
         {"machine.verify_merkle_tree", jsonrpc_machine_verify_merkle_tree_handler},
         {"machine.verify_dirty_page_maps", jsonrpc_machine_verify_dirty_page_maps_handler},
-        {"machine.get_memory_ranges", jsonrpc_machine_get_memory_ranges_handler},
+        {"machine.get_address_ranges", jsonrpc_machine_get_address_ranges_handler},
         {"machine.send_cmio_response", jsonrpc_machine_send_cmio_response_handler},
         {"machine.log_send_cmio_response", jsonrpc_machine_log_send_cmio_response_handler},
         {"machine.verify_send_cmio_response", jsonrpc_machine_verify_send_cmio_response_handler},
diff --git a/src/jsonrpc-virtual-machine.cpp b/src/jsonrpc-virtual-machine.cpp
index 7bc907ef6..455f29e35 100644
--- a/src/jsonrpc-virtual-machine.cpp
+++ b/src/jsonrpc-virtual-machine.cpp
@@ -60,6 +60,7 @@
 #include <json.hpp>
 
 #include "access-log.h"
+#include "address-range-description.h"
 #include "base64.h"
 #include "i-virtual-machine.h"
 #include "interpret.h"
@@ -67,7 +68,6 @@
 #include "jsonrpc-fork-result.h"
 #include "jsonrpc-version.h"
 #include "machine-config.h"
-#include "machine-memory-range-descr.h"
 #include "machine-merkle-tree.h"
 #include "machine-runtime-config.h"
 #include "os-features.h"
@@ -795,9 +795,9 @@ uarch_interpreter_break_reason jsonrpc_virtual_machine::do_run_uarch(uint64_t ua
     return result;
 }
 
-machine_memory_range_descrs jsonrpc_virtual_machine::do_get_memory_ranges() const {
-    machine_memory_range_descrs result;
-    request("machine.get_memory_ranges", std::tie(), result);
+address_range_descriptions jsonrpc_virtual_machine::do_get_address_ranges() const {
+    address_range_descriptions result;
+    request("machine.get_address_ranges", std::tie(), result);
     return result;
 }
 
diff --git a/src/jsonrpc-virtual-machine.h b/src/jsonrpc-virtual-machine.h
index eae517539..3cd564829 100644
--- a/src/jsonrpc-virtual-machine.h
+++ b/src/jsonrpc-virtual-machine.h
@@ -22,11 +22,11 @@
 #include <string>
 
 #include "access-log.h"
+#include "address-range-description.h"
 #include "i-virtual-machine.h"
 #include "interpret.h"
 #include "jsonrpc-fork-result.h"
 #include "machine-config.h"
-#include "machine-memory-range-descr.h"
 #include "machine-merkle-tree.h"
 #include "machine-runtime-config.h"
 #include "semantic-version.h"
@@ -131,7 +131,7 @@ class jsonrpc_virtual_machine final : public i_virtual_machine {
     uint64_t do_read_word(uint64_t address) const override;
     bool do_verify_merkle_tree() const override;
     uarch_interpreter_break_reason do_run_uarch(uint64_t uarch_cycle_end) override;
-    machine_memory_range_descrs do_get_memory_ranges() const override;
+    address_range_descriptions do_get_address_ranges() const override;
     void do_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length) override;
     access_log do_log_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
         const access_log::type &log_type) override;
diff --git a/src/machine-c-api.cpp b/src/machine-c-api.cpp
index b1cc751c2..7aea7ca5d 100644
--- a/src/machine-c-api.cpp
+++ b/src/machine-c-api.cpp
@@ -32,19 +32,19 @@
 #include <variant>
 
 #include "access-log.h"
-#include "htif.h"
+#include "address-range-description.h"
+#include "htif-constants.h"
 #include "i-virtual-machine.h"
 #include "interpret.h"
 #include "json-util.h"
 #include "machine-c-api-internal.h"
 #include "machine-config.h"
-#include "machine-memory-range-descr.h"
 #include "machine-merkle-tree.h"
 #include "machine-reg.h"
 #include "machine-runtime-config.h"
 #include "machine.h"
 #include "os-features.h"
-#include "pma-constants.h"
+#include "pma-defines.h"
 #include "virtual-machine.h"
 
 static std::string &get_last_err_msg_storage() {
@@ -52,6 +52,21 @@ static std::string &get_last_err_msg_storage() {
     return last_err_msg;
 }
 
+static_assert(PMA_CMIO_RX_BUFFER_START_DEF == CM_PMA_CMIO_RX_BUFFER_START);
+static_assert(PMA_CMIO_RX_BUFFER_LOG2_SIZE_DEF == CM_PMA_CMIO_RX_BUFFER_LOG2_SIZE);
+static_assert(PMA_CMIO_TX_BUFFER_START_DEF == CM_PMA_CMIO_TX_BUFFER_START);
+static_assert(PMA_CMIO_TX_BUFFER_LOG2_SIZE_DEF == CM_PMA_CMIO_TX_BUFFER_LOG2_SIZE);
+static_assert(PMA_RAM_START_DEF == CM_PMA_RAM_START);
+
+static_assert(HTIF_YIELD_AUTOMATIC_REASON_PROGRESS_DEF == CM_CMIO_YIELD_AUTOMATIC_REASON_PROGRESS);
+static_assert(HTIF_YIELD_AUTOMATIC_REASON_TX_OUTPUT_DEF == CM_CMIO_YIELD_AUTOMATIC_REASON_TX_OUTPUT);
+static_assert(HTIF_YIELD_AUTOMATIC_REASON_TX_REPORT_DEF == CM_CMIO_YIELD_AUTOMATIC_REASON_TX_REPORT);
+static_assert(HTIF_YIELD_MANUAL_REASON_RX_ACCEPTED_DEF == CM_CMIO_YIELD_MANUAL_REASON_RX_ACCEPTED);
+static_assert(HTIF_YIELD_MANUAL_REASON_RX_REJECTED_DEF == CM_CMIO_YIELD_MANUAL_REASON_RX_REJECTED);
+static_assert(HTIF_YIELD_MANUAL_REASON_TX_EXCEPTION_DEF == CM_CMIO_YIELD_MANUAL_REASON_TX_EXCEPTION);
+static_assert(HTIF_YIELD_REASON_ADVANCE_STATE_DEF == CM_CMIO_YIELD_REASON_ADVANCE_STATE);
+static_assert(HTIF_YIELD_REASON_INSPECT_STATE_DEF == CM_CMIO_YIELD_REASON_INSPECT_STATE);
+
 const char *cm_get_last_error_message() {
     return get_last_err_msg_storage().c_str();
 }
@@ -975,12 +990,12 @@ cm_error cm_destroy(cm_machine *m) try {
     return cm_result_failure();
 }
 
-cm_error cm_get_memory_ranges(const cm_machine *m, const char **ranges) try {
+cm_error cm_get_address_ranges(const cm_machine *m, const char **ranges) try {
     if (ranges == nullptr) {
         throw std::invalid_argument("invalid memory range output");
     }
     const auto *cpp_m = convert_from_c(m);
-    const cartesi::machine_memory_range_descrs cpp_ranges = cpp_m->get_memory_ranges();
+    const cartesi::address_range_descriptions cpp_ranges = cpp_m->get_address_ranges();
     *ranges = cm_set_temp_string(cartesi::to_json(cpp_ranges).dump());
     return cm_result_success();
 } catch (...) {
diff --git a/src/machine-c-api.h b/src/machine-c-api.h
index 8ad49f0c3..36d6ef714 100644
--- a/src/machine-c-api.h
+++ b/src/machine-c-api.h
@@ -472,12 +472,12 @@ CM_API cm_error cm_replace_memory_range(cm_machine *m, uint64_t start, uint64_t
 /// \returns 0 for success, non zero code for error.
 CM_API cm_error cm_get_initial_config(const cm_machine *m, const char **config);
 
-/// \brief Returns a list with all memory ranges in the machine.
+/// \brief Returns a list with all address ranges in the machine.
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
-/// \param ranges Receives the memory ranges as a JSON object in a string,
+/// \param ranges Receives the address ranges as a JSON object in a string,
 /// guaranteed to remain valid only until the next CM_API function is called from the same thread.
 /// \returns 0 for success, non zero code for error.
-CM_API cm_error cm_get_memory_ranges(const cm_machine *m, const char **ranges);
+CM_API cm_error cm_get_address_ranges(const cm_machine *m, const char **ranges);
 
 /// \brief Obtains the root hash of the Merkle tree.
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
diff --git a/src/machine-config.cpp b/src/machine-config.cpp
index df6d4e931..c52a6118d 100644
--- a/src/machine-config.cpp
+++ b/src/machine-config.cpp
@@ -21,7 +21,6 @@
 #include <exception>
 #include <fstream>
 #include <iomanip>
-#include <iostream>
 #include <sstream>
 #include <stdexcept>
 #include <string>
diff --git a/src/machine-reg.h b/src/machine-reg.h
index 48f868b5c..d8865c4a9 100644
--- a/src/machine-reg.h
+++ b/src/machine-reg.h
@@ -17,8 +17,8 @@
 #ifndef MACHINE_REG_H
 #define MACHINE_REG_H
 
-#include "shadow-state.h"
-#include "shadow-uarch-state.h"
+#include "shadow-state-address-range.h"
+#include "shadow-uarch-state-address-range.h"
 
 /// \file
 /// \brief Cartesi machine registers
diff --git a/src/machine-state.h b/src/machine-state.h
index 2d3ae4dbd..8fcfa1c6e 100644
--- a/src/machine-state.h
+++ b/src/machine-state.h
@@ -14,21 +14,19 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#ifndef STATE_H
-#define STATE_H
+#ifndef MACHINE_STATE_H
+#define MACHINE_STATE_H
 
 /// \file
 /// \brief Cartesi machine state structure definition.
 
 #include <array>
 #include <cstdint>
+#include <vector>
 
-#include <boost/container/static_vector.hpp>
-
-#include "pma-constants.h"
-#include "pma.h"
+#include "address-range.h"
 #include "riscv-constants.h"
-#include "shadow-tlb.h"
+#include "tlb.h"
 
 namespace cartesi {
 
@@ -116,10 +114,7 @@ struct machine_state {
     /// Soft yield
     bool soft_yield{};
 
-    /// Map of physical memory ranges
-    boost::container::static_vector<pma_entry, PMA_MAX> pmas;
-
-    pma_entry empty_pma; ///< fallback to PMA for empty range
+    std::vector<uint64_t> pmas; ///< Indices of address ranges that interpret can find
 };
 
 } // namespace cartesi
diff --git a/src/machine.cpp b/src/machine.cpp
index d542583db..da1ffd79e 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -25,6 +25,7 @@
 #include <iomanip>
 #include <iostream>
 #include <memory>
+#include <ranges>
 #include <sstream>
 #include <stdexcept>
 #include <string>
@@ -32,29 +33,28 @@
 #include <type_traits>
 #include <utility>
 #include <variant>
-
-#include <boost/container/static_vector.hpp>
+#include <vector>
 
 #include "access-log.h"
-#include "clint-factory.h"
+#include "address-range-description.h"
+#include "address-range.h"
+#include "clint-address-range.h"
 #include "compiler-defines.h"
 #include "device-state-access.h"
 #include "dtb.h"
 #include "host-addr.h"
-#include "htif-factory.h"
-#include "htif.h"
+#include "htif-address-range.h"
+#include "htif-constants.h"
 #include "i-device-state-access.h"
 #include "i-hasher.h"
 #include "interpret.h"
 #include "is-pristine.h"
 #include "machine-config.h"
-#include "machine-memory-range-descr.h"
 #include "machine-reg.h"
 #include "machine-runtime-config.h"
-#include "plic-factory.h"
+#include "memory-address-range.h"
+#include "plic-address-range.h"
 #include "pma-constants.h"
-#include "pma-defines.h"
-#include "pma.h"
 #include "record-send-cmio-state-access.h"
 #include "record-step-state-access.h"
 #include "replay-send-cmio-state-access.h"
@@ -62,14 +62,10 @@
 #include "riscv-constants.h"
 #include "rtc.h"
 #include "send-cmio-response.h"
-#include "shadow-pmas-factory.h"
-#include "shadow-pmas.h"
-#include "shadow-state-factory.h"
-#include "shadow-state.h"
-#include "shadow-tlb-factory.h"
-#include "shadow-tlb.h"
-#include "shadow-uarch-state-factory.h"
-#include "shadow-uarch-state.h"
+#include "shadow-pmas-address-range.h"
+#include "shadow-state-address-range.h"
+#include "shadow-tlb-address-range.h"
+#include "shadow-uarch-state-address-range.h"
 #include "state-access.h"
 #include "strict-aliasing.h"
 #include "tlb.h"
@@ -85,13 +81,10 @@
 #include "uarch-state-access.h"
 #include "uarch-step.h"
 #include "unique-c-ptr.h"
-#include "virtio-console.h"
-#include "virtio-device.h"
-#include "virtio-factory.h"
-#include "virtio-net-carrier-slirp.h"
-#include "virtio-net-carrier-tuntap.h"
-#include "virtio-net.h"
-#include "virtio-p9fs.h"
+#include "virtio-console-address-range.h"
+#include "virtio-net-tuntap-address-range.h"
+#include "virtio-net-user-address-range.h"
+#include "virtio-p9fs-address-range.h"
 
 /// \file
 /// \brief Cartesi machine implementation
@@ -100,115 +93,55 @@ namespace cartesi {
 
 using namespace std::string_literals;
 
-const pma_entry::flags machine::m_ram_flags{.R = true,
-    .W = true,
-    .X = true,
-    .IR = true,
-    .IW = true,
-    .DID = PMA_ISTART_DID::memory};
-
-// When we pass a RNG seed in a FDT stored in DTB,
-// Linux will wipe out its contents as a security measure,
-// therefore we need to make DTB writable, otherwise boot will hang.
-const pma_entry::flags machine::m_dtb_flags{.R = true,
-    .W = true,
-    .X = true,
-    .IR = true,
-    .IW = true,
-    .DID = PMA_ISTART_DID::memory};
-
-const pma_entry::flags machine::m_flash_drive_flags{.R = true,
-    .W = true,
-    .X = false,
-    .IR = true,
-    .IW = true,
-    .DID = PMA_ISTART_DID::flash_drive};
-
-const pma_entry::flags machine::m_cmio_rx_buffer_flags{.R = true,
-    .W = false,
-    .X = false,
-    .IR = true,
-    .IW = true,
-    .DID = PMA_ISTART_DID::cmio_rx_buffer};
-
-const pma_entry::flags machine::m_cmio_tx_buffer_flags{.R = true,
-    .W = true,
-    .X = false,
-    .IR = true,
-    .IW = true,
-    .DID = PMA_ISTART_DID::cmio_tx_buffer};
-
-pma_entry machine::make_memory_range_pma_entry(const std::string &description, const memory_range_config &c) {
-    if (c.image_filename.empty()) {
-        return make_callocd_memory_pma_entry(description, c.start, c.length);
-    }
-    return make_mmapd_memory_pma_entry(description, c.start, c.length, c.image_filename, c.shared);
-}
-
-pma_entry machine::make_flash_drive_pma_entry(const std::string &description, const memory_range_config &c) {
-    return make_memory_range_pma_entry(description, c).set_flags(m_flash_drive_flags);
-}
-
-pma_entry machine::make_cmio_rx_buffer_pma_entry(const cmio_buffer_config &c) {
-    const auto description = "cmio rx buffer memory range"s;
-    if (!c.image_filename.empty()) {
-        return make_mmapd_memory_pma_entry(description, PMA_CMIO_RX_BUFFER_START, PMA_CMIO_RX_BUFFER_LENGTH,
-            c.image_filename, c.shared)
-            .set_flags(m_cmio_rx_buffer_flags);
-    }
-    return make_callocd_memory_pma_entry(description, PMA_CMIO_RX_BUFFER_START, PMA_CMIO_RX_BUFFER_LENGTH)
-        .set_flags(m_cmio_rx_buffer_flags);
-}
-
-pma_entry machine::make_cmio_tx_buffer_pma_entry(const cmio_buffer_config &c) {
-    const auto description = "cmio tx buffer memory range"s;
-    if (!c.image_filename.empty()) {
-        return make_mmapd_memory_pma_entry(description, PMA_CMIO_TX_BUFFER_START, PMA_CMIO_TX_BUFFER_LENGTH,
-            c.image_filename, c.shared)
-            .set_flags(m_cmio_tx_buffer_flags);
-    }
-    return make_callocd_memory_pma_entry(description, PMA_CMIO_TX_BUFFER_START, PMA_CMIO_TX_BUFFER_LENGTH)
-        .set_flags(m_cmio_tx_buffer_flags);
-}
-
-pma_entry &machine::register_pma_entry(pma_entry &&pma) {
-    if (decltype(m_s.pmas)::capacity() <= m_s.pmas.size()) {
-        throw std::runtime_error{"too many PMAs when adding "s + pma.get_description()};
-    }
-    auto start = pma.get_start();
-    if ((start & (PMA_PAGE_SIZE - 1)) != 0) {
-        throw std::invalid_argument{"start of "s + pma.get_description() + " ("s + std::to_string(start) +
-            ") must be aligned to page boundary of "s + std::to_string(PMA_PAGE_SIZE) + " bytes"s};
-    }
-    auto length = pma.get_length();
-    if ((length & (PMA_PAGE_SIZE - 1)) != 0) {
-        throw std::invalid_argument{"length of "s + pma.get_description() + " ("s + std::to_string(length) +
-            ") must be multiple of page size "s + std::to_string(PMA_PAGE_SIZE)};
-    }
-    // Check PMA range, when not the sentinel PMA entry
-    if (length != 0 || start != 0) {
-        if (length == 0) {
-            throw std::invalid_argument{"length of "s + pma.get_description() + " cannot be zero"s};
-        }
-        // Checks if PMA is in addressable range, safe unsigned overflows
-        if (start > PMA_ADDRESSABLE_MASK || (length - 1) > (PMA_ADDRESSABLE_MASK - start)) {
-            throw std::invalid_argument{
-                "range of "s + pma.get_description() + " must use at most 56 bits to be addressable"s};
-        }
+static const auto throw_invalid_argument = [](const char *err) { throw std::invalid_argument{err}; };
+
+/// \brief Creates a memory address range.
+/// \param d Description of address range for use in error messages.
+/// \param start Target physical address where range starts.
+/// \param length Length of range, in bytes.
+/// \param f Flags for address range.
+/// \param image_filename Path to backing file.
+/// \param shared If true, changes to memory range reflect in backing file.
+/// \returns New address range with flags already set.
+/// \details If \p image_filename is non-empty, return a memory-mapped range, otherwise use calloc.
+static inline auto make_memory_address_range(const std::string &d, uint64_t start, uint64_t length, pma_flags flags,
+    const std::string &image_filename, bool shared) {
+    if (image_filename.empty() && shared) {
+        throw std::invalid_argument{"shared address range requires non-empty image filename when initializing " + d};
+    }
+    if (image_filename.empty() || length > static_cast<uint64_t>(os_get_file_length(image_filename.c_str()))) {
+        return make_callocd_memory_address_range(d, start, length, flags, image_filename);
     }
+    return make_mmapd_memory_address_range(d, start, length, flags, image_filename, shared);
+}
+
+void machine::check_address_range(const address_range &ar, register_where where) {
+    if (!where.interpret && !where.merkle) {
+        throw std::runtime_error{"address range "s + ar.get_description() + " must be registered somwhere"s};
+    }
+    if (where.interpret && m_s.pmas.size() >= PMA_MAX) {
+        throw std::runtime_error{"too many address ranges when adding "s + ar.get_description()};
+    }
+    const auto start = ar.get_start();
+    const auto length = ar.get_length();
+    // Checks if new range is machine addressable space (safe unsigned overflows)
+    if (start > PMA_ADDRESSABLE_MASK || (length > 0 && (length - 1) > (PMA_ADDRESSABLE_MASK - start))) {
+        throw std::invalid_argument{
+            "address range of "s + ar.get_description() + " must use at most 56 bits to be addressable"s};
+    }
+    const auto length_bit_ceil = ar.get_length_bit_ceil();
     // Range A overlaps with B if A starts before B ends and A ends after B starts
-    for (const auto &existing_pma : m_s.pmas) {
-        if (start < existing_pma.get_start() + existing_pma.get_length() && start + length > existing_pma.get_start()) {
-            throw std::invalid_argument{"range of "s + pma.get_description() + " overlaps with range of existing "s +
-                existing_pma.get_description()};
+    for (const auto &existing : m_ars) {
+        const auto existing_start = existing->get_start();
+        const auto existing_length_bit_ceil = existing->get_length_bit_ceil();
+        if (start < existing_start + existing_length_bit_ceil && start + length_bit_ceil > existing_start) {
+            throw std::invalid_argument{"address range of "s + ar.get_description() +
+                " overlaps with address range of existing "s + existing->get_description()};
         }
     }
-    pma.set_index(static_cast<int>(m_s.pmas.size()));
-    m_s.pmas.push_back(std::move(pma));
-    return m_s.pmas.back();
 }
 
-static bool DID_is_protected(PMA_ISTART_DID DID) {
+static bool is_protected(PMA_ISTART_DID DID) {
     switch (DID) {
         case PMA_ISTART_DID::memory:
         case PMA_ISTART_DID::flash_drive:
@@ -220,15 +153,16 @@ static bool DID_is_protected(PMA_ISTART_DID DID) {
     }
 }
 
-void machine::replace_memory_range(const memory_range_config &range) {
-    for (auto &pma : m_s.pmas) {
-        if (pma.get_start() == range.start && pma.get_length() == range.length) {
-            const auto curr = pma.get_istart_DID();
-            if (pma.get_length() == 0 || DID_is_protected(curr)) {
-                throw std::invalid_argument{"attempt to replace a protected range "s + pma.get_description()};
+void machine::replace_memory_range(const memory_range_config &config) {
+    for (auto &existing : m_ars) {
+        if (existing->get_start() == config.start && existing->get_length() == config.length) {
+            if (!existing->is_memory() || is_protected(existing->get_driver_id())) {
+                throw std::invalid_argument{"attempt to replace a protected range "s + existing->get_description()};
             }
-            // replace range preserving original flags
-            pma = make_memory_range_pma_entry(pma.get_description(), range).set_flags(pma.get_flags());
+            // Replace range, preserving original flags.
+            // This will automatically start with all pages dirty.
+            existing = make_moved_unique(make_memory_address_range(existing->get_description(), existing->get_start(),
+                existing->get_length(), existing->get_flags(), config.image_filename, config.shared));
             return;
         }
     }
@@ -245,22 +179,35 @@ void machine::init_uarch(const uarch_config &c) {
         write_reg(machine_reg_enum(reg::uarch_x0, i), c.processor.x[i]);
     }
     // Register shadow state
-    m_us.shadow_state = make_shadow_uarch_state_pma_entry(PMA_SHADOW_UARCH_STATE_START, PMA_SHADOW_UARCH_STATE_LENGTH);
+    m_us.shadow_state = &register_address_range(make_shadow_uarch_state_address_range(PMA_SHADOW_UARCH_STATE_START,
+                                                    PMA_SHADOW_UARCH_STATE_LENGTH, throw_invalid_argument),
+        register_where{.merkle = true, .interpret = false});
     // Register RAM
+    if (uarch_pristine_ram_len > PMA_UARCH_RAM_LENGTH) {
+        throw std::runtime_error("embedded uarch RAM image does not fit in uarch memory");
+    }
+    static constexpr pma_flags uram_flags{
+        .M = true,
+        .IO = false,
+        .E = false,
+        .R = true,
+        .W = true,
+        .X = true,
+        .IR = true,
+        .IW = true,
+        .DID = PMA_ISTART_DID::memory,
+    };
     constexpr auto ram_description = "uarch RAM";
-    if (!c.ram.image_filename.empty()) {
-        // Load RAM image from file
-        m_us.ram =
-            make_callocd_memory_pma_entry(ram_description, PMA_UARCH_RAM_START, UARCH_RAM_LENGTH, c.ram.image_filename)
-                .set_flags(m_ram_flags);
+    if (c.ram.image_filename.empty()) {
+        m_us.ram = &register_address_range(
+            make_callocd_memory_address_range(ram_description, PMA_UARCH_RAM_START, UARCH_RAM_LENGTH, uram_flags),
+            register_where{.merkle = true, .interpret = false});
+        memcpy(m_us.ram->get_host_memory(), uarch_pristine_ram, uarch_pristine_ram_len);
     } else {
-        // Load embedded pristine RAM image
-        m_us.ram = make_callocd_memory_pma_entry(ram_description, PMA_UARCH_RAM_START, PMA_UARCH_RAM_LENGTH)
-                       .set_flags(m_ram_flags);
-        if (uarch_pristine_ram_len > m_us.ram.get_length()) {
-            throw std::runtime_error("embedded uarch RAM image does not fit in uarch ram PMA");
-        }
-        memcpy(m_us.ram.get_memory().get_host_memory(), uarch_pristine_ram, uarch_pristine_ram_len);
+        m_us.ram =
+            &register_address_range(make_memory_address_range(ram_description, PMA_UARCH_RAM_START, UARCH_RAM_LENGTH,
+                                        uram_flags, c.ram.image_filename, false /* not shared */),
+                register_where{.merkle = true, .interpret = false});
     }
 }
 
@@ -334,19 +281,47 @@ void machine::init_processor(processor_config &p, const machine_runtime_config &
     write_reg(reg::iunrep, p.iunrep);
 }
 
-void machine::init_ram_pma(const ram_config &ram) {
-    register_pma_entry(
-        make_callocd_memory_pma_entry("RAM"s, PMA_RAM_START, ram.length, ram.image_filename).set_flags(m_ram_flags));
-}
-
-void machine::init_flash_drive_pmas(flash_drive_configs &flash_drive) {
+void machine::init_ram_ar(const ram_config &ram) {
+    // Flags for RAM
+    static constexpr pma_flags ram_flags{
+        .M = true,
+        .IO = false,
+        .E = false,
+        .R = true,
+        .W = true,
+        .X = true,
+        .IR = true,
+        .IW = true,
+        .DID = PMA_ISTART_DID::memory,
+    };
+    if (ram.length == 0) {
+        throw std::invalid_argument("RAM length cannot be zero");
+    }
+    register_address_range(
+        make_callocd_memory_address_range("RAM"s, PMA_RAM_START, ram.length, ram_flags, ram.image_filename),
+        register_where{.merkle = true, .interpret = true});
+}
+
+void machine::init_flash_drive_ars(flash_drive_configs &flash_drive) {
+    // Flags for flash drives
+    static const pma_flags flash_flags{
+        .M = true,
+        .IO = false,
+        .E = false,
+        .R = true,
+        .W = true,
+        .X = false,
+        .IR = true,
+        .IW = true,
+        .DID = PMA_ISTART_DID::flash_drive,
+    };
     // Register all flash drives
     int i = 0; // NOLINT(misc-const-correctness)
     for (auto &f : flash_drive) {
         const std::string flash_description = "flash drive "s + std::to_string(i);
         // Auto detect flash drive start address
         if (f.start == UINT64_C(-1)) {
-            f.start = PMA_DRIVE_START + PMA_DRIVE_OFFSET_DEF * i;
+            f.start = PMA_DRIVE_START + PMA_DRIVE_OFFSET * i;
         }
         // Auto detect flash drive image length
         if (f.length == UINT64_C(-1)) {
@@ -364,69 +339,80 @@ void machine::init_flash_drive_pmas(flash_drive_configs &flash_drive) {
             }
             f.length = length;
         }
-        register_pma_entry(make_flash_drive_pma_entry(flash_description, f));
+        register_address_range(
+            make_memory_address_range(flash_description, f.start, f.length, flash_flags, f.image_filename, f.shared),
+            register_where{.merkle = true, .interpret = true});
         i++;
     }
 }
 
-void machine::init_virtio_pmas(const virtio_configs &v, uint64_t iunrep) {
+void machine::init_virtio_ars(const virtio_configs &cs, uint64_t iunrep) {
     // Initialize VirtIO devices
-    if (!v.empty()) {
-        // VirtIO devices are disallowed in unreproducible mode
-        if (iunrep == 0) {
-            throw std::invalid_argument{"virtio devices are only supported in unreproducible machines"};
-        }
-        for (const auto &vdev_config_entry : v) {
-            std::visit(
-                [&](const auto &vdev_config) {
-                    using T = std::decay_t<decltype(vdev_config)>;
-                    std::string pma_name = "VirtIO device"; // NOLINT(misc-const-correctness): // no, can't be const
-                    std::unique_ptr<virtio_device> vdev;
-                    if constexpr (std::is_same_v<T, cartesi::virtio_console_config>) {
-                        pma_name = "VirtIO Console";
-                        vdev = std::make_unique<virtio_console>(m_vdevs.size());
-                    } else if constexpr (std::is_same_v<T, cartesi::virtio_p9fs_config>) {
+    if (cs.empty()) {
+        return;
+    }
+    // VirtIO devices are disallowed in unreproducible mode
+    if (iunrep == 0) {
+        throw std::invalid_argument{"virtio devices are only supported in unreproducible machines"};
+    }
+    uint32_t virtio_idx = 0;
+    for (const auto &c : cs) {
+        const auto where = register_where{.merkle = false, .interpret = true};
+        const auto visitor = overloads{
+            [this, virtio_idx, where](const virtio_console_config &) {
+                const auto start = PMA_FIRST_VIRTIO_START + (virtio_idx * PMA_VIRTIO_LENGTH);
+                register_address_range(make_virtio_console_address_range(start, PMA_VIRTIO_LENGTH, virtio_idx), where);
+            },
+            [this, virtio_idx, where](const virtio_p9fs_config &c) {
 #ifdef HAVE_POSIX_FS
-                        pma_name = "VirtIO 9P";
-                        vdev = std::make_unique<virtio_p9fs_device>(m_vdevs.size(), vdev_config.tag,
-                            vdev_config.host_directory);
+                const auto start = PMA_FIRST_VIRTIO_START + (virtio_idx * PMA_VIRTIO_LENGTH);
+                register_address_range(
+                    make_virtio_p9fs_address_range(start, PMA_VIRTIO_LENGTH, virtio_idx, c.tag, c.host_directory),
+                    where);
 #else
-                        throw std::invalid_argument("virtio 9p device is unsupported in this platform");
+                (void) c;
+                (void) this;
+                (void) virtio_idx;
+                (void) where;
+                throw std::invalid_argument{"virtio 9p device is unsupported in this platform"};
 #endif
-                    } else if constexpr (std::is_same_v<T, cartesi::virtio_net_user_config>) {
-#ifdef HAVE_SLIRP
-                        pma_name = "VirtIO Net User";
-                        vdev = std::make_unique<virtio_net>(m_vdevs.size(),
-                            std::make_unique<virtio_net_carrier_slirp>(vdev_config));
+            },
+            [this, virtio_idx, where](const virtio_net_tuntap_config &c) {
+#ifdef HAVE_TUNTAP
+                const auto start = PMA_FIRST_VIRTIO_START + (virtio_idx * PMA_VIRTIO_LENGTH);
+                register_address_range(
+                    make_virtio_net_tuntap_address_range(start, PMA_VIRTIO_LENGTH, virtio_idx, c.iface), where);
 #else
-                        throw std::invalid_argument("virtio network user device is unsupported in this platform");
-
+                (void) c;
+                (void) this;
+                (void) virtio_idx;
+                (void) where;
+                throw std::invalid_argument("virtio network TUN/TAP device is unsupported in this platform");
 #endif
-                    } else if constexpr (std::is_same_v<T, cartesi::virtio_net_tuntap_config>) {
-#ifdef HAVE_TUNTAP
-                        pma_name = "VirtIO Net TUN/TAP";
-                        vdev = std::make_unique<virtio_net>(m_vdevs.size(),
-                            std::make_unique<virtio_net_carrier_tuntap>(vdev_config.iface));
+            },
+            [this, virtio_idx, where](const virtio_net_user_config &c) {
+#ifdef HAVE_SLIRP
+                const auto start = PMA_FIRST_VIRTIO_START + (virtio_idx * PMA_VIRTIO_LENGTH);
+                register_address_range(make_virtio_net_user_address_range(start, PMA_VIRTIO_LENGTH, virtio_idx, c),
+                    where);
 #else
-
-                        throw std::invalid_argument("virtio network TUN/TAP device is unsupported in this platform");
+                (void) c;
+                (void) this;
+                (void) virtio_idx;
+                (void) where;
+                throw std::invalid_argument("virtio network user device is unsupported in this platform");
 #endif
-                    } else {
-                        throw std::invalid_argument("invalid virtio device configuration");
-                    }
-                    register_pma_entry(
-                        make_virtio_pma_entry(PMA_FIRST_VIRTIO_START + (vdev->get_virtio_index() * PMA_VIRTIO_LENGTH),
-                            PMA_VIRTIO_LENGTH, pma_name, &virtio_driver, vdev.get()));
-                    m_vdevs.push_back(std::move(vdev));
-                },
-                vdev_config_entry);
-        }
+            },
+            [](const auto &) { throw std::invalid_argument("invalid virtio device configuration"); }};
+        std::visit(visitor, c);
+        ++virtio_idx;
     }
 }
 
-void machine::init_htif_pma(const htif_config &h, const htif_runtime_config &r, uint64_t iunrep) {
+void machine::init_htif_ar(const htif_config &h) {
     // Register HTIF device
-    register_pma_entry(make_htif_pma_entry(PMA_HTIF_START, PMA_HTIF_LENGTH));
+    register_address_range(make_htif_address_range(PMA_HTIF_START, PMA_HTIF_LENGTH, throw_invalid_argument),
+        register_where{.merkle = false, .interpret = true});
     // Copy HTIF state to from config to machine
     write_reg(reg::htif_tohost, h.tohost);
     write_reg(reg::htif_fromhost, h.fromhost);
@@ -439,78 +425,93 @@ void machine::init_htif_pma(const htif_config &h, const htif_runtime_config &r,
     const uint64_t htif_iyield = static_cast<uint64_t>(h.yield_manual) << HTIF_YIELD_CMD_MANUAL |
         static_cast<uint64_t>(h.yield_automatic) << HTIF_YIELD_CMD_AUTOMATIC;
     write_reg(reg::htif_iyield, htif_iyield);
-    // Initialize TTY if console input is enabled
-    if (h.console_getchar || has_virtio_console()) {
-        if (iunrep == 0) {
-            throw std::invalid_argument{"TTY stdin is only supported in unreproducible machines"};
-        }
-        os_open_tty();
-    }
-    os_silence_putchar(r.no_console_putchar);
-}
-
-void machine::init_cmio_pmas(const cmio_config &c) {
-    // Register cmio memory ranges
-    register_pma_entry(make_cmio_tx_buffer_pma_entry(c.tx_buffer));
-    register_pma_entry(make_cmio_rx_buffer_pma_entry(c.rx_buffer));
 }
 
-void machine::init_merkle_pmas() {
-    // Include machine PMAs in set considered by the Merkle tree.
-    for (auto &pma : m_s.pmas) {
-        if (pma.get_length() != 0) {
-            m_merkle_pmas.push_back(&pma);
-        }
-    }
-    m_merkle_pmas.push_back(&m_us.shadow_state);
-    m_merkle_pmas.push_back(&m_us.ram);
-    // Sort it by increasing start address
-    std::ranges::sort(m_merkle_pmas, [](const auto *a, const auto *b) { return a->get_start() < b->get_start(); });
-}
-
-void machine::init_memory_range_descrs() {
-    // Initialize memory range descriptions returned by get_memory_ranges method
-    for (const auto *pma : m_merkle_pmas) {
-        if (pma->get_length() != 0) {
-            m_mrds.push_back(machine_memory_range_descr{.start = pma->get_start(),
-                .length = pma->get_length(),
-                .description = pma->get_description()});
-        }
-    }
+void machine::init_cmio_ars(const cmio_config &c) {
+    static const pma_flags tx_flags{
+        .M = true,
+        .IO = false,
+        .E = false,
+        .R = true,
+        .W = true,
+        .X = false,
+        .IR = true,
+        .IW = true,
+        .DID = PMA_ISTART_DID::cmio_tx_buffer,
+    };
+    static const pma_flags rx_flags{
+        .M = true,
+        .IO = false,
+        .E = false,
+        .R = true,
+        .W = false,
+        .X = false,
+        .IR = true,
+        .IW = true,
+        .DID = PMA_ISTART_DID::cmio_rx_buffer,
+    };
+    register_address_range(make_memory_address_range("CMIO tx buffer memory range"s, PMA_CMIO_TX_BUFFER_START,
+                               PMA_CMIO_TX_BUFFER_LENGTH, tx_flags, c.tx_buffer.image_filename, c.tx_buffer.shared),
+        register_where{.merkle = true, .interpret = true});
+    register_address_range(make_memory_address_range("CMIO rx buffer memory range"s, PMA_CMIO_RX_BUFFER_START,
+                               PMA_CMIO_RX_BUFFER_LENGTH, rx_flags, c.rx_buffer.image_filename, c.rx_buffer.shared),
+        register_where{.merkle = true, .interpret = true});
+}
+
+void machine::init_merkle_ars() {
+    // Sort indices by the starting address of the range they point to in the m_ars array
+    std::ranges::sort(
+        m_merkle_ars, [](const auto &a, const auto &b) { return a.get_start() < b.get_start(); },
+        [this](const auto i) { return *m_ars[i]; });
+}
+
+void machine::init_ars_descriptions() {
+    // Initialize memory range descriptions returned by get_address_ranges method
+    auto src = m_ars | std::views::filter([](auto &ar) { return ar->get_length() != 0; }) |
+        std::views::transform([](auto &ar) {
+            return address_range_description{.start = ar->get_start(),
+                .length = ar->get_length(),
+                .description = ar->get_description()};
+        });
+    std::ranges::copy(src, std::back_inserter(m_ards));
+    std::ranges::sort(m_ards, [](auto &a, auto &b) { return a.start < b.start; });
 }
 
-void machine::init_clint_pma(const clint_config &c) {
+void machine::init_clint_ar(const clint_config &c) {
     // Register CLINT device
-    register_pma_entry(make_clint_pma_entry(PMA_CLINT_START, PMA_CLINT_LENGTH));
+    register_address_range(make_clint_address_range(PMA_CLINT_START, PMA_CLINT_LENGTH, throw_invalid_argument),
+        register_where{.merkle = false, .interpret = true});
     // Copy CLINT state to from config to machine
     write_reg(reg::clint_mtimecmp, c.mtimecmp);
 }
 
-void machine::init_plic_pma(const plic_config &p) {
+void machine::init_plic_ar(const plic_config &p) {
     // Register PLIC device
-    register_pma_entry(make_plic_pma_entry(PMA_PLIC_START, PMA_PLIC_LENGTH));
+    register_address_range(make_plic_address_range(PMA_PLIC_START, PMA_PLIC_LENGTH, throw_invalid_argument),
+        register_where{.merkle = false, .interpret = true});
     // Copy PLIC state from config to machine
     write_reg(reg::plic_girqpend, p.girqpend);
     write_reg(reg::plic_girqsrvd, p.girqsrvd);
 }
 
-void machine::init_sentinel_pmas() {
+void machine::init_sentinel_ars() {
     // Last, add empty sentinels until we reach capacity (need at least one sentinel)
-    register_pma_entry(make_empty_pma_entry("sentinel"s, 0, 0));
-    // NOLINTNEXTLINE(readability-static-accessed-through-instance)
-    if (m_s.pmas.capacity() != PMA_MAX) {
-        throw std::logic_error{"PMAs array must be able to hold at least PMA_MAX entries"};
-    }
+    // ??D I will remove these sentinels from the list
+    register_address_range(make_empty_address_range("sentinel"), register_where{.merkle = false, .interpret = true});
     while (m_s.pmas.size() < PMA_MAX) {
-        register_pma_entry(make_empty_pma_entry("sentinel"s, 0, 0));
+        register_address_range(make_empty_address_range("sentinel"),
+            register_where{.merkle = false, .interpret = true});
     }
 }
 
-void machine::init_shadow_pmas_contents(pma_entry &shadow_pmas) const {
-    // NOLINTBEGIN(cppcoreguidelines-pro-type-reinterpret-cast)
-    shadow_pmas_init(m_s.pmas,
-        reinterpret_cast<shadow_pmas_state *>(shadow_pmas.get_memory_noexcept().get_host_memory()));
-    // NOLINTEND(cppcoreguidelines-pro-type-reinterpret-cast)
+void machine::init_shadow_pmas_contents(memory_address_range &shadow_pmas) const {
+    static_assert(sizeof(shadow_pmas_state) == PMA_MAX * 2 * sizeof(uint64_t), "inconsistent shadow PMAs length");
+    static_assert(PMA_SHADOW_PMAS_LENGTH >= sizeof(shadow_pmas_state), "shadow PMAs not long enough");
+    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+    auto &dest = *reinterpret_cast<shadow_pmas_state *>(shadow_pmas.get_host_memory());
+    std::ranges::transform(m_s.pmas, dest.begin(), [this](auto i) {
+        return shadow_pmas_entry{.istart = m_ars[i]->get_istart(), .ilength = m_ars[i]->get_ilength()};
+    });
 }
 
 void machine::init_tlb_contents(const std::string &image_filename) {
@@ -535,9 +536,28 @@ void machine::init_tlb_contents(const std::string &image_filename) {
     }
 }
 
-void machine::init_dtb_contents(const machine_config &c, pma_entry &dtb) {
+address_range &machine::init_dtb_ar(const dtb_config &c) {
+    // When we pass a RNG seed in a FDT stored in DTB, Linux will wipe out its contents as a security measure,
+    // therefore we need to make DTB writable, otherwise boot will hang.
+    static constexpr pma_flags dtb_flags{
+        .M = true,
+        .IO = false,
+        .E = false,
+        .R = true,
+        .W = true,
+        .X = true,
+        .IR = true,
+        .IW = true,
+        .DID = PMA_ISTART_DID::memory,
+    };
+    return register_address_range(make_memory_address_range("DTB"s, PMA_DTB_START, PMA_DTB_LENGTH, dtb_flags,
+                                      c.image_filename, false /* not shared */),
+        register_where{.merkle = true, .interpret = true});
+}
+
+void machine::init_dtb_contents(const machine_config &c, address_range &dtb) {
     if (c.dtb.image_filename.empty()) {
-        dtb_init(c, dtb.get_memory().get_host_memory(), PMA_DTB_LENGTH);
+        dtb_init(c, dtb.get_host_memory(), PMA_DTB_LENGTH);
     }
 }
 
@@ -547,23 +567,26 @@ machine::machine(machine_config c, machine_runtime_config r) : m_c{std::move(c)}
     init_uarch(m_c.uarch);
     init_processor(m_c.processor, m_r);
     m_s.soft_yield = m_r.soft_yield;
-    init_ram_pma(m_c.ram);
+    init_ram_ar(m_c.ram);
     // Will populate when initialization of PMAs is done
-    pma_entry &dtb =
-        register_pma_entry(make_callocd_memory_pma_entry("DTB"s, PMA_DTB_START, PMA_DTB_LENGTH, m_c.dtb.image_filename)
-                .set_flags(m_dtb_flags));
-    init_flash_drive_pmas(m_c.flash_drive);
-    init_cmio_pmas(m_c.cmio);
-    init_htif_pma(m_c.htif, m_r.htif, m_c.processor.iunrep);
-    init_clint_pma(m_c.clint);
-    init_plic_pma(m_c.plic);
+    auto &dtb = init_dtb_ar(m_c.dtb);
+    init_flash_drive_ars(m_c.flash_drive);
+    init_cmio_ars(m_c.cmio);
+    init_htif_ar(m_c.htif);
+    init_clint_ar(m_c.clint);
+    init_plic_ar(m_c.plic);
     // Will populate when initialization of PMAs is done
-    register_pma_entry(make_shadow_tlb_pma_entry(PMA_SHADOW_TLB_START, PMA_SHADOW_TLB_LENGTH));
-    register_pma_entry(make_shadow_state_pma_entry(PMA_SHADOW_STATE_START, PMA_SHADOW_STATE_LENGTH));
+    register_address_range(
+        make_shadow_tlb_address_range(PMA_SHADOW_TLB_START, PMA_SHADOW_TLB_LENGTH, throw_invalid_argument),
+        register_where{.merkle = true, .interpret = false});
+    register_address_range(
+        make_shadow_state_address_range(PMA_SHADOW_STATE_START, PMA_SHADOW_STATE_LENGTH, throw_invalid_argument),
+        register_where{.merkle = true, .interpret = false});
     // Will populate when initialization of PMAs is done
-    pma_entry &shpmas = register_pma_entry(make_shadow_pmas_pma_entry(PMA_SHADOW_PMAS_START, PMA_SHADOW_PMAS_LENGTH));
-    init_virtio_pmas(m_c.virtio, m_c.processor.iunrep);
-    init_sentinel_pmas();
+    auto &shpmas = register_address_range(make_shadow_pmas_address_range(PMA_SHADOW_PMAS_START, PMA_SHADOW_PMAS_LENGTH),
+        register_where{.merkle = true, .interpret = true});
+    init_virtio_ars(m_c.virtio, m_c.processor.iunrep);
+    init_sentinel_ars();
     // Populate shadow PMAs contents.
     // This must be done after all PMA entries are already registered, so we encode them into the shadow
     init_shadow_pmas_contents(shpmas);
@@ -573,14 +596,26 @@ machine::machine(machine_config c, machine_runtime_config r) : m_c{std::move(c)}
     // Initialize DTB contents.
     // This must be done after all PMA entries are already registered, so we can lookup flash drive parameters
     init_dtb_contents(m_c, dtb);
-    init_merkle_pmas();
-    init_memory_range_descrs();
+    init_merkle_ars();
+    init_ars_descriptions();
+    init_tty(m_c.htif, m_r.htif, m_c.processor.iunrep);
     // Disable SIGPIPE handler, because this signal can be raised and terminate the emulator process
     // when calling write() on closed file descriptors.
     // This can happen with the stdout console file descriptors or network file descriptors.
     os_disable_sigpipe();
 }
 
+void machine::init_tty(const htif_config &h, const htif_runtime_config &r, uint64_t iunrep) const {
+    // Initialize TTY if console input is enabled
+    if (h.console_getchar || has_virtio_console()) {
+        if (iunrep == 0) {
+            throw std::invalid_argument{"TTY stdin is only supported in unreproducible machines"};
+        }
+        os_open_tty();
+    }
+    os_silence_putchar(r.no_console_putchar);
+}
+
 static void load_hash(const std::string &dir, machine::hash_type &h) {
     auto name = dir + "/hash";
     auto fp = make_unique_fopen(name.c_str(), "rb");
@@ -608,16 +643,16 @@ machine::machine(const std::string &dir, machine_runtime_config r) : machine{mac
 }
 
 void machine::prepare_virtio_devices_select(select_fd_sets *fds, uint64_t *timeout_us) {
-    for (auto &vdev : m_vdevs) {
-        vdev->prepare_select(fds, timeout_us);
+    for (auto *v : m_virtio_ars) {
+        v->prepare_select(fds, timeout_us);
     }
 }
 
 // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
 bool machine::poll_selected_virtio_devices(int select_ret, select_fd_sets *fds, i_device_state_access *da) {
     bool interrupt_requested = false; // NOLINT(misc-const-correctness)
-    for (auto &vdev : m_vdevs) {
-        interrupt_requested |= vdev->poll_selected(select_ret, fds, da);
+    for (auto *v : m_virtio_ars) {
+        interrupt_requested |= v->poll_selected(select_ret, fds, da);
     }
     return interrupt_requested;
 }
@@ -631,13 +666,13 @@ bool machine::poll_virtio_devices(uint64_t *timeout_us, i_device_state_access *d
 }
 
 bool machine::has_virtio_devices() const {
-    return !m_vdevs.empty();
+    return !m_virtio_ars.empty();
 }
 
 bool machine::has_virtio_console() const {
     // When present, the console device is guaranteed to be the first VirtIO device,
     // therefore we only need to check the first device.
-    return !m_vdevs.empty() && m_vdevs[0]->get_device_id() == VIRTIO_DEVICE_CONSOLE;
+    return has_virtio_devices() && m_virtio_ars[0]->get_device_id() == VIRTIO_DEVICE_CONSOLE;
 }
 
 bool machine::has_htif_console() const {
@@ -743,18 +778,16 @@ machine_config machine::get_serialization_config() const {
     return c;
 }
 
-static void store_device_pma(const machine &m, const pma_entry &pma, const std::string &dir) {
-    if (!pma.get_istart_IO()) {
-        throw std::runtime_error{"attempt to save non-device PMA"};
+static void store_device_address_range(const machine &m, const address_range &ar, const std::string &dir) {
+    if (!ar.is_device()) {
+        throw std::runtime_error{"attempt to save non-device address range "s + ar.get_description()};
     }
     auto scratch = make_unique_calloc<unsigned char>(PMA_PAGE_SIZE); // will throw if it fails
-    auto name = machine_config::get_image_filename(dir, pma.get_start(), pma.get_length());
-    auto fp = make_unique_fopen(name.c_str(), "wb");
-    for (uint64_t page_start_in_range = 0; page_start_in_range < pma.get_length();
-        page_start_in_range += PMA_PAGE_SIZE) {
+    auto name = machine_config::get_image_filename(dir, ar.get_start(), ar.get_length());
+    auto fp = make_unique_fopen(name.c_str(), "wb"); // will throw if it fails
+    for (uint64_t offset = 0; offset < ar.get_length(); offset += PMA_PAGE_SIZE) {
         const unsigned char *page_data = nullptr;
-        auto peek = pma.get_peek();
-        if (!peek(pma, m, page_start_in_range, PMA_PAGE_SIZE, &page_data, scratch.get())) {
+        if (!ar.peek(m, offset, PMA_PAGE_SIZE, &page_data, scratch.get())) {
             throw std::runtime_error{"peek failed"};
         }
         if (page_data == nullptr) {
@@ -767,14 +800,13 @@ static void store_device_pma(const machine &m, const pma_entry &pma, const std::
     }
 }
 
-static void store_memory_pma(const pma_entry &pma, const std::string &dir) {
-    if (!pma.get_istart_M()) {
-        throw std::runtime_error{"attempt to save non-memory PMA"};
+static void store_memory_address_range(const address_range &ar, const std::string &dir) {
+    if (!ar.is_memory()) {
+        throw std::runtime_error{"attempt to save non-memory address-range "s + ar.get_description()};
     }
-    auto name = machine_config::get_image_filename(dir, pma.get_start(), pma.get_length());
+    auto name = machine_config::get_image_filename(dir, ar.get_start(), ar.get_length());
     auto fp = make_unique_fopen(name.c_str(), "wb");
-    const pma_memory &mem = pma.get_memory();
-    if (fwrite(mem.get_host_memory(), 1, pma.get_length(), fp.get()) != pma.get_length()) {
+    if (fwrite(ar.get_host_memory(), 1, ar.get_length(), fp.get()) != ar.get_length()) {
         throw std::runtime_error{"error writing to '" + name + "'"};
     }
 }
@@ -788,8 +820,8 @@ host_addr machine::get_host_addr(uint64_t paddr, uint64_t pma_index) const {
 }
 
 void machine::mark_dirty_page(uint64_t paddr, uint64_t pma_index) {
-    auto &pma = m_s.pmas[static_cast<int>(pma_index)];
-    pma.mark_dirty_page(paddr - pma.get_start());
+    auto &ar = read_pma(pma_index);
+    ar.mark_dirty_page(paddr - ar.get_start());
 }
 
 void machine::mark_dirty_page(host_addr haddr, uint64_t pma_index) {
@@ -832,8 +864,8 @@ void machine::check_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, uin
         if (pma_index >= m_s.pmas.size()) {
             throw std::domain_error{prefix + "pma_index is out of range"s};
         }
-        const auto &pma = m_s.pmas[pma_index];
-        if (pma.get_length() == 0 || !pma.get_istart_M()) {
+        const auto &ar = read_pma(pma_index);
+        if (ar.get_length() == 0 || !ar.is_memory()) {
             throw std::invalid_argument{prefix + "pma_index does not point to memory range"s};
         }
         if ((vaddr_page & PAGE_OFFSET_MASK) != 0) {
@@ -843,8 +875,8 @@ void machine::check_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, uin
         if ((paddr_page & PAGE_OFFSET_MASK) != 0) {
             throw std::invalid_argument{prefix + "vp_offset is not aligned"s};
         }
-        const auto pma_end = pma.get_start() + (pma.get_length() - PMA_PAGE_SIZE);
-        if (paddr_page < pma.get_start() || paddr_page > pma_end) {
+        const auto pma_end = ar.get_start() + (ar.get_length() - PMA_PAGE_SIZE);
+        if (paddr_page < ar.get_start() || paddr_page > pma_end) {
             throw std::invalid_argument{prefix + "vp_offset is inconsistent with pma_index"s};
         }
     } else if (pma_index != TLB_INVALID_PMA_INDEX || vp_offset != 0) {
@@ -871,48 +903,40 @@ void machine::write_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, uin
 }
 
 host_addr machine::get_hp_offset(uint64_t pma_index) const {
-    if (pma_index >= m_s.pmas.size()) {
-        throw std::domain_error{"PMA index is out of range (" + std::to_string(pma_index) + ")"};
-    }
-    const auto &pma = m_s.pmas[static_cast<int>(pma_index)];
-    if (!pma.get_istart_M()) {
-        throw std::domain_error{"PMA is not memory (" + pma.get_description() + ")"};
+    const auto &ar = read_pma(pma_index);
+    if (!ar.is_memory()) {
+        throw std::domain_error{"PMA index is not of memory range ("s + ar.get_description() + ")"};
     }
-    auto haddr = cast_ptr_to_host_addr(pma.get_memory().get_host_memory());
-    auto paddr = pma.get_start();
+    auto haddr = cast_ptr_to_host_addr(ar.get_host_memory());
+    auto paddr = ar.get_start();
     return paddr - haddr;
 }
 
-//??D now that m_merkle_pmas is sorted by start, maybe change this to a binary search?
-const pma_entry &machine::find_pma_entry(uint64_t paddr, uint64_t length) const {
-    const static auto sentinel = make_empty_pma_entry("sentinel", 0, 0);
-    for (const auto *pma : m_merkle_pmas) {
-        // Check if data is in range
-        if (paddr >= pma->get_start() && pma->get_length() >= length &&
-            paddr - pma->get_start() <= pma->get_length() - length) {
-            return *pma;
+//??D now that m_merkle_ars is sorted by start, maybe change this to a binary search?
+const address_range &machine::find_address_range(uint64_t paddr, uint64_t length) const noexcept {
+    static constexpr auto sentinel = make_empty_address_range("sentinel");
+    for (const auto &ar : m_ars) {
+        if (ar->contains_absolute(paddr, length)) {
+            return *ar;
         }
     }
     return sentinel;
 }
 
-void machine::store_pmas(const machine_config &c, const std::string &dir) const {
+void machine::store_address_ranges(const machine_config &c, const std::string &dir) const {
     if (read_reg(reg::iunrep) != 0) {
         throw std::runtime_error{"cannot store PMAs of unreproducible machines"};
     }
-    store_memory_pma(find_pma_entry<uint64_t>(PMA_DTB_START), dir);
-    store_memory_pma(find_pma_entry<uint64_t>(PMA_RAM_START), dir);
-    store_device_pma(*this, find_pma_entry<uint64_t>(PMA_SHADOW_TLB_START), dir);
-    // Could iterate over PMAs checking for those with a drive DID
-    // but this is easier
+    store_memory_address_range(find_address_range<uint64_t>(PMA_DTB_START), dir);
+    store_memory_address_range(find_address_range<uint64_t>(PMA_RAM_START), dir);
+    store_device_address_range(*this, find_address_range<uint64_t>(PMA_SHADOW_TLB_START), dir);
+    // Could iterate over PMAs checking for those with a drive DID but this is easier
     for (const auto &f : c.flash_drive) {
-        store_memory_pma(find_pma_entry<uint64_t>(f.start), dir);
-    }
-    store_memory_pma(find_pma_entry<uint64_t>(PMA_CMIO_RX_BUFFER_START), dir);
-    store_memory_pma(find_pma_entry<uint64_t>(PMA_CMIO_TX_BUFFER_START), dir);
-    if (!m_us.ram.get_istart_E()) {
-        store_memory_pma(m_us.ram, dir);
+        store_memory_address_range(find_address_range<uint64_t>(f.start), dir);
     }
+    store_memory_address_range(find_address_range<uint64_t>(PMA_CMIO_RX_BUFFER_START), dir);
+    store_memory_address_range(find_address_range<uint64_t>(PMA_CMIO_TX_BUFFER_START), dir);
+    store_memory_address_range(find_address_range<uint64_t>(PMA_UARCH_RAM_START), dir);
 }
 
 static void store_hash(const machine::hash_type &h, const std::string &dir) {
@@ -937,7 +961,7 @@ void machine::store(const std::string &dir) const {
     }
     auto c = get_serialization_config();
     c.store(dir);
-    store_pmas(c, dir);
+    store_address_ranges(c, dir);
 }
 
 void machine::dump_insn_hist() {
@@ -1782,15 +1806,16 @@ void machine::mark_write_tlb_dirty_pages() const {
         if (hot_slot.vaddr_page != TLB_INVALID_PAGE) {
             auto haddr_page = hot_slot.vaddr_page + hot_slot.vh_offset;
             const auto &cold_slot = cold_set[slot_index];
-            if (cold_slot.pma_index >= m_s.pmas.size()) {
+            // NOLINTNEXTLINE(cppcoreguidelines-pro-type-const-cast)
+            auto &ar = const_cast<address_range &>(read_pma(cold_slot.pma_index));
+            if (ar.get_length() == 0 || !ar.is_memory()) {
                 throw std::runtime_error{"could not mark dirty page for a TLB entry: TLB is corrupt"};
             }
             auto paddr_page = get_paddr(haddr_page, cold_slot.pma_index);
-            pma_entry &pma = m_s.pmas[cold_slot.pma_index];
-            if (!pma.contains(paddr_page, PMA_PAGE_SIZE)) {
+            if (!ar.contains_absolute(paddr_page, PMA_PAGE_SIZE)) {
                 throw std::runtime_error{"could not mark dirty page for a TLB entry: TLB is corrupt"};
             }
-            pma.mark_dirty_page(paddr_page - pma.get_start());
+            ar.mark_dirty_page(paddr_page - ar.get_start());
         }
     }
 }
@@ -1807,19 +1832,17 @@ bool machine::verify_dirty_page_maps() const {
     // Go over the write TLB and mark as dirty all pages currently there
     mark_write_tlb_dirty_pages();
     // Now go over all memory PMAs verifying that all dirty pages are marked
-    for (const auto &pma : m_s.pmas) {
-        auto peek = pma.get_peek();
-        for (uint64_t page_start_in_range = 0; page_start_in_range < pma.get_length();
-            page_start_in_range += PMA_PAGE_SIZE) {
-            const uint64_t page_address = pma.get_start() + page_start_in_range;
-            if (pma.get_istart_M()) {
+    for (const auto &ar : m_ars) {
+        for (uint64_t offset = 0; offset < ar->get_length(); offset += PMA_PAGE_SIZE) {
+            const uint64_t page_address = ar->get_start() + offset;
+            if (ar->is_memory()) {
                 const unsigned char *page_data = nullptr;
-                peek(pma, *this, page_start_in_range, PMA_PAGE_SIZE, &page_data, scratch.get());
+                ar->peek(*this, offset, PMA_PAGE_SIZE, &page_data, scratch.get());
                 hash_type stored;
                 hash_type real;
                 m_t.get_page_node_hash(page_address, stored);
                 m_t.get_page_node_hash(h, page_data, real);
-                const bool marked_dirty = pma.is_page_marked_dirty(page_start_in_range);
+                const bool marked_dirty = ar->is_page_marked_dirty(offset);
                 const bool is_dirty = (real != stored);
                 if (is_dirty && !marked_dirty) {
                     broken = true;
@@ -1829,8 +1852,8 @@ bool machine::verify_dirty_page_maps() const {
                     std::cerr << "  got " << real << '\n';
                     break;
                 }
-            } else if (pma.get_istart_IO()) {
-                if (!pma.is_page_marked_dirty(page_start_in_range)) {
+            } else if (ar->is_device()) {
+                if (!ar->is_page_marked_dirty(offset)) {
                     broken = true;
                     std::cerr << std::setfill('0') << std::setw(8) << std::hex << page_address
                               << " should have been dirty\n";
@@ -1856,10 +1879,9 @@ bool machine::update_merkle_tree() const {
     mark_write_tlb_dirty_pages();
     // Now go over all PMAs and updating the Merkle tree
     m_t.begin_update();
-    for (const auto &pma : m_merkle_pmas) {
-        auto peek = pma->get_peek();
+    for (auto &ar : m_merkle_ars | std::views::transform([this](auto i) -> address_range & { return *m_ars[i]; })) {
         // Each PMA has a number of pages
-        auto pages_in_range = (pma->get_length() + PMA_PAGE_SIZE - 1) / PMA_PAGE_SIZE;
+        auto pages_in_range = (ar.get_length() + PMA_PAGE_SIZE - 1) / PMA_PAGE_SIZE;
         // For each PMA, we launch as many threads (n) as defined on concurrency
         // runtime config or as the hardware supports.
         const uint64_t n = get_task_concurrency(m_r.concurrency.update_merkle_tree);
@@ -1872,15 +1894,15 @@ bool machine::update_merkle_tree() const {
             // Thread j is responsible for page i if i % n == j.
             for (uint64_t i = j; i < pages_in_range; i += n) {
                 const uint64_t page_start_in_range = i * PMA_PAGE_SIZE;
-                const uint64_t page_address = pma->get_start() + page_start_in_range;
+                const uint64_t page_address = ar.get_start() + page_start_in_range;
                 const unsigned char *page_data = nullptr;
                 // Skip any clean pages
-                if (!pma->is_page_marked_dirty(page_start_in_range)) {
+                if (!ar.is_page_marked_dirty(page_start_in_range)) {
                     continue;
                 }
                 // If the peek failed, or if it returned a page for update but
                 // we failed updating it, the entire process failed
-                if (!peek(*pma, *this, page_start_in_range, PMA_PAGE_SIZE, &page_data, scratch.get())) {
+                if (!ar.peek(*this, page_start_in_range, PMA_PAGE_SIZE, &page_data, scratch.get())) {
                     return false;
                 }
                 if (page_data != nullptr) {
@@ -1914,7 +1936,7 @@ bool machine::update_merkle_tree() const {
             return false;
         }
         // Otherwise, mark all pages in PMA as clean and move on to next
-        pma->mark_pages_clean();
+        ar.mark_pages_clean();
     }
     const bool ret = m_t.end_update(gh);
     return ret;
@@ -1925,8 +1947,8 @@ bool machine::update_merkle_tree_page(uint64_t address) {
         "PMA and machine_merkle_tree page sizes must match");
     // Align address to beginning of page
     address &= ~(PMA_PAGE_SIZE - 1);
-    auto &pma = find_pma_entry<uint8_t>(address);
-    const uint64_t page_start_in_range = address - pma.get_start();
+    auto &ar = find_address_range<uint8_t>(address);
+    const uint64_t page_start_in_range = address - ar.get_start();
     machine_merkle_tree::hasher_type h;
     auto scratch = make_unique_calloc<unsigned char>(PMA_PAGE_SIZE, std::nothrow_t{});
     if (!scratch) {
@@ -1934,13 +1956,12 @@ bool machine::update_merkle_tree_page(uint64_t address) {
     }
     m_t.begin_update();
     const unsigned char *page_data = nullptr;
-    auto peek = pma.get_peek();
-    if (!peek(pma, *this, page_start_in_range, PMA_PAGE_SIZE, &page_data, scratch.get())) {
+    if (!ar.peek(*this, page_start_in_range, PMA_PAGE_SIZE, &page_data, scratch.get())) {
         m_t.end_update(h);
         return false;
     }
     if (page_data != nullptr) {
-        const uint64_t page_address = pma.get_start() + page_start_in_range;
+        const uint64_t page_address = ar.get_start() + page_start_in_range;
         hash_type hash;
         m_t.get_page_node_hash(h, page_data, hash);
         if (!m_t.update_page_node_hash(page_address, hash)) {
@@ -1948,7 +1969,7 @@ bool machine::update_merkle_tree_page(uint64_t address) {
             return false;
         }
     }
-    pma.mark_clean_page(page_start_in_range);
+    ar.mark_clean_page(page_start_in_range);
     return m_t.end_update(h);
 }
 
@@ -2038,17 +2059,16 @@ machine_merkle_tree::proof_type machine::get_proof(uint64_t address, int log2_si
     // or entirely outside it.
     if (log2_size < machine_merkle_tree::get_log2_page_size()) {
         const uint64_t length = UINT64_C(1) << log2_size;
-        const auto &pma = find_pma_entry(address, length);
+        const auto &ar = find_address_range(address, length);
         auto scratch = make_unique_calloc<unsigned char>(PMA_PAGE_SIZE);
         const unsigned char *page_data = nullptr;
         // If the PMA range is empty, we know the desired range is
         // entirely outside of any non-pristine PMA.
         // Therefore, the entire page where it lies is also pristine
         // Otherwise, the entire desired range is inside it.
-        if (!pma.get_istart_E()) {
-            const uint64_t page_start_in_range = (address - pma.get_start()) & (~(PMA_PAGE_SIZE - 1));
-            auto peek = pma.get_peek();
-            if (!peek(pma, *this, page_start_in_range, PMA_PAGE_SIZE, &page_data, scratch.get())) {
+        if (ar.get_length() != 0) {
+            const uint64_t page_start_in_range = (address - ar.get_start()) & (~(PMA_PAGE_SIZE - 1));
+            if (!ar.peek(*this, page_start_in_range, PMA_PAGE_SIZE, &page_data, scratch.get())) {
                 throw std::runtime_error{"PMA peek failed"};
             }
         }
@@ -2066,6 +2086,27 @@ machine_merkle_tree::proof_type machine::get_proof(uint64_t address, int log2_si
     return get_proof(address, log2_size, skip_merkle_tree_update);
 }
 
+template <typename F>
+static inline void foreach_aligned_chunk(uint64_t start, uint64_t length, uint64_t alignment, F f) {
+    // Optional first chunk brings start to alignment
+    if (const auto rem = start % alignment; rem != 0) {
+        const auto first_length = std::min(length, alignment - rem);
+        f(start, first_length);
+        start += first_length;
+        length -= first_length;
+    }
+    // Intermediate chunks start aligned and cover exactly alignment bytes
+    while (length >= alignment) {
+        f(start, alignment);
+        start += alignment;
+        length -= alignment;
+    }
+    // Last chunk completes the span
+    if (length != 0) {
+        f(start, length);
+    }
+}
+
 void machine::read_memory(uint64_t paddr, unsigned char *data, uint64_t length) const {
     if (length == 0) {
         return;
@@ -2073,6 +2114,8 @@ void machine::read_memory(uint64_t paddr, unsigned char *data, uint64_t length)
     if (data == nullptr) {
         throw std::invalid_argument{"invalid data buffer"};
     }
+    //??D this loop can be much improved and simplified... I don't remember why I am going page
+    //??D by page when inside an occupied address range... Will fix.
     // Compute the distance between the initial paddr and the first page boundary
     const uint64_t align_paddr = (paddr & PAGE_OFFSET_MASK) != 0 ? (paddr | PAGE_OFFSET_MASK) + 1 : paddr;
     uint64_t align_length = align_paddr - paddr;
@@ -2080,25 +2123,24 @@ void machine::read_memory(uint64_t paddr, unsigned char *data, uint64_t length)
     align_length = (align_length == 0) ? page_size : align_length;
     // First peek goes at most to the next page boundary, or up to length
     uint64_t peek_length = std::min(align_length, length);
-    // The outer loop finds the PMA for all peeks performed by the inner loop
-    // The inner loop peeks at most min(page_size, length) from the PMA per iteration
+    // The outer loop finds the address range for all peeks performed by the inner loop
+    // The inner loop peeks at most min(page_size, length) from the range per iteration
     // All peeks but the absolute first peek start at a page boundary.
     // That first peek reads at most up to the next page boundary.
     // So the inner loop iterations never cross page boundaries.
     for (;;) {
-        const auto &pma = find_pma_entry(paddr, peek_length);
-        const auto peek = pma.get_peek();
-        const auto pma_start = pma.get_start();
-        const auto pma_empty = pma.get_istart_E();
-        const auto pma_length = pma.get_length();
-        // If the PMA is empty, the inner loop will break after a single iteration.
+        const auto &ar = find_address_range(paddr, peek_length);
+        const auto pma_start = ar.get_start();
+        const auto occupied = ar.get_length() != 0;
+        const auto pma_length = ar.get_length();
+        // If we are in an unoccupied range, the inner loop will break after a single iteration.
         // But it is safe to return pristine data for that one iteration, without even peeking.
         // This is because the inner iteration never reads past a page boundary, and the next
-        // non-empty PMA starts at the earliest on the next page boundary after paddr.
+        // occupied range starts at the earliest on the next page boundary after paddr.
         for (;;) {
             const unsigned char *peek_data = nullptr;
-            // If non-empty PMA, peek, otherwise leave peek_data as nullptr (i.e. pristine)
-            if (!pma_empty && !peek(pma, *this, paddr - pma_start, peek_length, &peek_data, data)) {
+            // If we found an occupied range, peek, otherwise leave peek_data as nullptr (i.e. pristine)
+            if (occupied && !ar.peek(*this, paddr - pma_start, peek_length, &peek_data, data)) {
                 throw std::runtime_error{"peek failed"};
             }
             // If the chunk is pristine, copy zero data to buffer
@@ -2117,13 +2159,13 @@ void machine::read_memory(uint64_t paddr, unsigned char *data, uint64_t length)
             paddr += peek_length;
             data += peek_length;
             peek_length = std::min(page_size, length);
-            // If the PMA was empty, break to check if next read is in another PMA
-            if (pma_empty) {
+            // If we are outside any valid range, break to check if next read hits a valid range
+            if (!occupied) {
                 break;
             }
-            // If the next read does not fit in current PMA, break to get the next one
+            // If the next read does not fit in current range, break to get the next one
             // There can be no overflow in the condition.
-            // Since the PMA is non-empty, (paddr-pma_start) >= 0.
+            // Since the range is occupied, (paddr-pma_start) >= 0.
             // Moreover, pma_length >= page_size.
             // Since, peek_length <= page_size, we get (pma_length-peek_length) >= 0.
             if (paddr - pma_start >= pma_length - peek_length) {
@@ -2140,28 +2182,51 @@ void machine::write_memory(uint64_t paddr, const unsigned char *data, uint64_t l
     if (data == nullptr) {
         throw std::invalid_argument{"invalid data buffer"};
     }
-    auto &pma = find_pma_entry(paddr, length);
-    if (pma.get_istart_IO()) {
+    auto &ar = find_address_range(paddr, length);
+    if (ar.is_device()) {
         throw std::invalid_argument{"attempted write to device memory range"};
     }
-    if (!pma.get_istart_M() || pma.get_istart_E()) {
-        throw std::invalid_argument{"address range not entirely in single memory range"};
+    if (ar.get_length() == 0 || !ar.is_memory()) {
+        throw std::invalid_argument{"address range to write is not entirely in single memory range"};
     }
-    if (DID_is_protected(pma.get_istart_DID())) {
+    if (is_protected(ar.get_driver_id())) {
         throw std::invalid_argument{"attempt to write to protected memory range"};
     }
-    pma.write_memory(paddr, data, length);
+    foreach_aligned_chunk(paddr, length, PMA_PAGE_SIZE, [&ar, paddr, data](auto chunk_start, auto chunk_length) {
+        const auto *src = data + (chunk_start - paddr);
+        const auto offset = chunk_start - ar.get_start();
+        auto *dest = ar.get_host_memory() + offset;
+        if (memcmp(dest, src, chunk_length) != 0) {
+            // Page is different, we have to copy memory
+            memcpy(dest, src, chunk_length);
+            ar.mark_dirty_page(offset);
+        }
+    });
 }
 
-void machine::fill_memory(uint64_t address, uint8_t data, uint64_t length) {
+void machine::fill_memory(uint64_t paddr, uint8_t val, uint64_t length) {
     if (length == 0) {
         return;
     }
-    auto &pma = find_pma_entry(address, length);
-    if (!pma.get_istart_M() || pma.get_istart_E()) {
-        throw std::invalid_argument{"address range not entirely in memory PMA"};
+    auto &ar = find_address_range(paddr, length);
+    if (ar.is_device()) {
+        throw std::invalid_argument{"attempted fill to device memory range"};
+    }
+    if (ar.get_length() == 0 || !ar.is_memory()) {
+        throw std::invalid_argument{"address range to fill is not entirely in memory PMA"};
     }
-    pma.fill_memory(address, data, length);
+    if (is_protected(ar.get_driver_id())) {
+        throw std::invalid_argument{"attempt fill to protected memory range"};
+    }
+    // The case of filling a range with zeros is special and optimized for uarch reset
+    foreach_aligned_chunk(paddr, length, PMA_PAGE_SIZE, [&ar, val](auto chunk_start, auto chunk_length) {
+        const auto offset = chunk_start - ar.get_start();
+        const auto dest = ar.get_host_memory() + offset;
+        if (val != 0 || !is_pristine(dest, chunk_length)) {
+            memset(dest, val, chunk_length);
+            ar.mark_dirty_page(offset);
+        }
+    });
 }
 
 void machine::read_virtual_memory(uint64_t vaddr_start, unsigned char *data, uint64_t length) {
@@ -2273,21 +2338,22 @@ void machine::write_word(uint64_t paddr, uint64_t val) {
         return;
     }
     // Otherwise, try the slow path
-    auto &pma = find_pma_entry(paddr, sizeof(uint64_t));
-    if (pma.get_istart_E() || !pma.get_istart_M()) {
+    auto &ar = find_address_range(paddr, sizeof(uint64_t));
+    if (ar.get_length() == 0 || !ar.is_memory() || ar.get_host_memory() == nullptr) {
         std::ostringstream err;
-        err << "attempted memory write to " << pma.get_description() << " at address 0x" << std::hex << paddr << "("
+        err << "attempted memory write to " << ar.get_description() << " at address 0x" << std::hex << paddr << "("
             << std::dec << paddr << ")";
         throw std::runtime_error{err.str()};
     }
-    if (!pma.get_istart_W()) {
+    if (!ar.is_writeable()) {
         std::ostringstream err;
-        err << "attempted memory write to (non-writeable) " << pma.get_description() << " at address 0x" << std::hex
-            << paddr << "(" << std::dec << paddr << ")";
+        err << "attempted memory write to read-only " << ar.get_description() << " at address 0x" << std::hex << paddr
+            << "(" << std::dec << paddr << ")";
         throw std::runtime_error{err.str()};
     }
-    const auto offset = paddr - pma.get_start();
-    aliased_aligned_write<uint64_t>(pma.get_memory().get_host_memory() + offset, val);
+    const auto offset = paddr - ar.get_start();
+    aliased_aligned_write<uint64_t>(ar.get_host_memory() + offset, val);
+    ar.mark_dirty_page(offset);
 }
 
 void machine::send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length) {
@@ -2339,12 +2405,13 @@ void machine::reset_uarch() {
         write_reg(machine_reg_enum(reg::uarch_x0, i), UARCH_X_INIT);
     }
     // Load embedded pristine RAM image
-    if (uarch_pristine_ram_len > m_us.ram.get_length()) {
-        throw std::runtime_error("embedded uarch ram image does not fit in uarch ram pma");
-    }
+    const auto uram_length = m_us.ram->get_length();
+    const auto uram_start = m_us.ram->get_start();
     // Reset RAM to initial state
-    m_us.ram.fill_memory(m_us.ram.get_start(), 0, m_us.ram.get_length());
-    m_us.ram.write_memory(m_us.ram.get_start(), uarch_pristine_ram, uarch_pristine_ram_len);
+    write_memory(uram_start, uarch_pristine_ram, uarch_pristine_ram_len);
+    if (uram_length > uarch_pristine_ram_len) {
+        fill_memory(uram_start + uarch_pristine_ram_len, 0, uram_length - uarch_pristine_ram_len);
+    }
 }
 
 access_log machine::log_reset_uarch(const access_log::type &log_type) {
@@ -2384,8 +2451,8 @@ void machine::verify_reset_uarch(const hash_type &root_hash_before, const access
 extern template UArchStepStatus uarch_step(uarch_record_state_access &a);
 
 access_log machine::log_step_uarch(const access_log::type &log_type) {
-    if (m_us.ram.get_istart_E()) {
-        throw std::runtime_error("microarchitecture RAM is not present");
+    if (read_reg(reg::iunrep) != 0) {
+        throw std::runtime_error("microarchitecture cannot be used with unreproducible machines");
     }
     hash_type root_hash_before;
     get_root_hash(root_hash_before);
@@ -2430,9 +2497,6 @@ uarch_interpreter_break_reason machine::run_uarch(uint64_t uarch_cycle_end) {
     if (read_reg(reg::iunrep) != 0) {
         throw std::runtime_error("microarchitecture cannot be used with unreproducible machines");
     }
-    if (m_us.ram.get_istart_E()) {
-        throw std::runtime_error("microarchitecture RAM is not present");
-    }
     const uarch_state_access a(*this);
     return uarch_interpret(a, uarch_cycle_end);
 }
diff --git a/src/machine.h b/src/machine.h
index 03ab519d5..34cfe8164 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -26,26 +26,25 @@
 #include <utility>
 #include <vector>
 
-#include <boost/container/static_vector.hpp>
 #include <unordered_map>
 
 #include "access-log.h"
+#include "address-range-description.h"
+#include "address-range.h"
 #include "host-addr.h"
 #include "i-device-state-access.h"
 #include "interpret.h"
 #include "machine-config.h"
-#include "machine-memory-range-descr.h"
 #include "machine-merkle-tree.h"
 #include "machine-reg.h"
 #include "machine-runtime-config.h"
 #include "machine-state.h"
 #include "os.h"
 #include "pma-constants.h"
-#include "pma.h"
 #include "shadow-tlb.h"
 #include "uarch-interpret.h"
 #include "uarch-state.h"
-#include "virtio-device.h"
+#include "virtio-address-range.h"
 
 namespace cartesi {
 
@@ -61,55 +60,74 @@ constexpr skip_merkle_tree_update_t skip_merkle_tree_update;
 /// \brief Cartesi Machine implementation
 class machine final {
 private:
-    mutable machine_state m_s;              ///< Big machine state
-    mutable uarch_state m_us;               ///< Microarchitecture state
-    mutable machine_merkle_tree m_t;        ///< Merkle tree of state
-    std::vector<pma_entry *> m_merkle_pmas; ///< PMAs considered by the Merkle tree: from big machine and uarch
-    machine_config m_c;                     ///< Copy of initialization config
-    machine_runtime_config m_r;             ///< Copy of initialization runtime config
-    machine_memory_range_descrs m_mrds;     ///< List of memory ranges returned by get_memory_ranges().
-
-    boost::container::static_vector<std::unique_ptr<virtio_device>, VIRTIO_MAX> m_vdevs; ///< Array of VirtIO devices
-
-    static const pma_entry::flags m_dtb_flags;            ///< PMA flags used for DTB
-    static const pma_entry::flags m_ram_flags;            ///< PMA flags used for RAM
-    static const pma_entry::flags m_flash_drive_flags;    ///< PMA flags used for flash drives
-    static const pma_entry::flags m_cmio_rx_buffer_flags; ///< PMA flags used for cmio rx buffer
-    static const pma_entry::flags m_cmio_tx_buffer_flags; ///< PMA flags used for cmio tx buffer
-
-    std::unordered_map<std::string, uint64_t> m_counters;
-
-    /// \brief Allocates a new PMA entry.
-    /// \param pma PMA entry to add to machine.
-    /// \returns Reference to corresponding entry in machine state.
-    pma_entry &register_pma_entry(pma_entry &&pma);
-
-    /// \brief Creates a new PMA entry reflecting a memory range configuration.
-    /// \param description Informative description of PMA entry for use in error messages
-    /// \param c Memory range configuration.
-    /// \returns New PMA entry (with default flags).
-    static pma_entry make_memory_range_pma_entry(const std::string &description, const memory_range_config &c);
-
-    /// \brief Creates a new flash drive PMA entry.
-    /// \param description Informative description of PMA entry for use in error messages
-    /// \param c Memory range configuration.
-    /// \returns New PMA entry with flash drive flags already set.
-    static pma_entry make_flash_drive_pma_entry(const std::string &description, const memory_range_config &c);
-
-    /// \brief Creates a new cmio rx buffer PMA entry.
-    // \param c cmio buffer configuration for rx buffer.
-    /// \returns New PMA entry with rx buffer flags already set.
-    static pma_entry make_cmio_rx_buffer_pma_entry(const cmio_buffer_config &c);
-
-    /// \brief Creates a new cmio tx buffer PMA entry.
-    // \param c cmio buffer configuration for tx buffer.
-    /// \returns New PMA entry with tx buffer flags already set.
-    static pma_entry make_cmio_tx_buffer_pma_entry(const cmio_buffer_config &c);
-
-    /// \brief Saves PMAs into files for serialization
+    mutable machine_state m_s;                                 ///< Big machine state
+    mutable uarch_state m_us;                                  ///< Microarchitecture state
+    mutable std::vector<std::unique_ptr<address_range>> m_ars; ///< All address ranges
+    mutable machine_merkle_tree m_t;                           ///< Merkle tree of state
+    machine_config m_c;                                        ///< Copy of initialization config
+    machine_runtime_config m_r;                                ///< Copy of initialization runtime config
+    std::vector<uint64_t> m_merkle_ars;                   ///< Indices of address ranges that the Mekrle tree can find
+    std::vector<virtio_address_range *> m_virtio_ars;     ///< VirtIO address ranges
+    address_range_descriptions m_ards;                    ///< Address range descriptions listed by get_address_ranges()
+    std::unordered_map<std::string, uint64_t> m_counters; ///< Counters used for statistics collection
+
+    ///< Where to register an address range
+    struct register_where {
+        bool merkle;    //< Register with Merkle tree, so it appears in the root hash
+        bool interpret; //< Register so interpret can see (and it also appears as a PMA entries in memory)
+    };
+
+    /// \brief Checks if address range can be registered.
+    /// \param ar Address range object to register.
+    /// \param where Where to register the address range.
+    void check_address_range(const address_range &ar, register_where where);
+
+    /// \brief Registers a new address range.
+    /// \tparam AR An address range or derived type.
+    /// \param ar The address range object to register (as an r-value).
+    /// \param where Where to register the address range.
+    /// \returns Reference to address range object after it is moved inside the machine.
+    /// \details The r-value address range is moved to the heap, and the pointer holding it is added to a container.
+    /// Once the address range is moved to the heap, its address will remain valid until it is replaced by
+    /// a call to replace_memory_range(), or until the machine is destroyed.
+    /// This means pointers to address ranges remain valid even after subsequent calls to register_address_range(),
+    /// but may be invalidated by calls to replace_address_range().
+    /// For a stronger guarantee, when an address range is replaced, the pointer to the new address range
+    /// overwrites the pointer to the old address range at the same index in the container.
+    /// This means the an index into the container that owns all address ranges will always refers to same address range
+    /// after subsequent calls to register_address_range() and  calls to replace_address_range() as well.
+    /// \details Besides the container that stores the address ranges, the machine maintains subsets of address ranges.
+    /// The "merkle" address range container lists the indices of the address ranges taht will be considered by
+    /// the Merkle tree during the computation of the state hash.
+    /// The "interpret" address range container lists the indices of the address ranges that will be visible from within
+    /// the interpreter.
+    /// When registering an address range with the machine, one must specify \p where else to register it.
+    /// The "virtio" address range container holds pointers to every virtio address range that has been registered.
+    template <typename AR>
+    AR &register_address_range(AR &&ar, register_where where)
+        requires std::is_rvalue_reference_v<AR &&> && std::derived_from<AR, address_range>
+    {
+        check_address_range(ar, where);                     // Check if we can register it
+        auto ptr = make_moved_unique(std::forward<AR>(ar)); // Move object to heap, now owned by ptr
+        AR &ar_ref = *ptr;                                  // Get reference to object, already in heap, to return later
+        const auto index = m_ars.size();                    // Get index new address range will occupy
+        m_ars.push_back(std::move(ptr));                    // Move ptr to list of address ranges
+        if (where.interpret) {                              // Register with interpreter
+            m_s.pmas.push_back(index);
+        }
+        if (where.merkle) { // Register with Merkle tree
+            m_merkle_ars.push_back(index);
+        }
+        if constexpr (std::is_convertible_v<AR *, virtio_address_range *>) { // Register with VirtIO
+            m_virtio_ars.push_back(&ar_ref);
+        }
+        return ar_ref; // Return reference to object in heap
+    }
+
+    /// \brief Saves address ranges into files for serialization
     /// \param config Machine config to be stored
-    /// \param directory Directory where PMAs will be stored
-    void store_pmas(const machine_config &config, const std::string &directory) const;
+    /// \param directory Directory where address ranges will be stored
+    void store_address_ranges(const machine_config &config, const std::string &directory) const;
 
     /// \brief Returns offset that converts between machine host addresses and target physical addresses
     /// \param pma_index Index of the memory PMA for the desired offset
@@ -124,62 +142,70 @@ class machine final {
     /// \param r Machine runtime configuration
     void init_processor(processor_config &p, const machine_runtime_config &r);
 
-    /// \brief Initializes RAM PMA
+    /// \brief Initializes RAM address range
     /// \param ram RAM configuration
-    void init_ram_pma(const ram_config &ram);
+    void init_ram_ar(const ram_config &ram);
 
     /// \brief Initializes flash drive PMAs
     /// \param flash_drive Flash drive configurations
-    void init_flash_drive_pmas(flash_drive_configs &flash_drive);
+    void init_flash_drive_ars(flash_drive_configs &flash_drive);
 
     /// \brief Initializes VirtIO device PMAs
-    /// \param v VirtIO configurations
+    /// \param cs VirtIO configurations
     /// \param iunrep Initial value of iunrep CSR
-    void init_virtio_pmas(const virtio_configs &v, uint64_t iunrep);
+    void init_virtio_ars(const virtio_configs &cs, uint64_t iunrep);
+
+    /// \brief Initializes HTIF device address range
+    /// \param h HTIF configuration
+    void init_htif_ar(const htif_config &h);
 
-    /// \brief Initializes HTIF device PMA
+    /// \brief Initializes TTY if needed
     /// \param h HTIF configuration
     /// \param r HTIF runtime configuration
     /// \param iunrep Initial value of iunrep CSR
-    void init_htif_pma(const htif_config &h, const htif_runtime_config &r, uint64_t iunrep);
+    void init_tty(const htif_config &h, const htif_runtime_config &r, uint64_t iunrep) const;
 
-    /// \brief Initializes CLINT device PMA
+    /// \brief Initializes CLINT device address range
     /// \param c CLINT configuration
-    void init_clint_pma(const clint_config &c);
+    void init_clint_ar(const clint_config &c);
 
-    /// \brief Initializes PLIC device PMA
+    /// \brief Initializes PLIC device address range
     /// \param p PLIC configuration
-    void init_plic_pma(const plic_config &p);
+    void init_plic_ar(const plic_config &p);
 
-    /// \brief Initializes CMIO PMAs
+    /// \brief Initializes CMIO address ranges
     /// \param c CMIO configuration
-    void init_cmio_pmas(const cmio_config &c);
+    void init_cmio_ars(const cmio_config &c);
 
-    /// \brief Initializes the PMAs used to compute the Merkle tree
-    /// \detail This can only be called after all PMAs have been added
-    void init_merkle_pmas();
+    /// \brief Initializes the address ranges involced in the Merkle tree
+    /// \detail This can only be called after all address ranges have been registerd
+    void init_merkle_ars();
 
-    /// \brief Initializes the PMAs descriptions returned by get_memory_ranges()
-    /// \detail This can only be called after the Merkle tree PMAs have been initialized
-    void init_memory_range_descrs();
+    /// \brief Initializes the address range descriptions returned by get_address_ranges()
+    /// \detail This can only be called after all address ranges have been registered
+    void init_ars_descriptions();
 
-    /// \brief Fill up PMA list with sentinel empty PMAs
-    void init_sentinel_pmas();
+    /// \brief Fill up address range list with sentinels
+    void init_sentinel_ars();
 
     /// \brief Initializes contents of the shadow PMAs memory
     /// \param shadow_pmas PMA entry for the shadow PMAs
     /// \detail This can only be called after all PMAs have been added
-    void init_shadow_pmas_contents(pma_entry &shadow_pmas) const;
+    void init_shadow_pmas_contents(memory_address_range &shadow_pmas) const;
 
     /// \brief Initializes contents of machine TLB, from image in disk or with default values
     /// \param image_filename File containing image, or empty for default values
     /// \detail This can only be called after all PMAs have been added
     void init_tlb_contents(const std::string &image_filename);
 
+    /// \brief Initializes DTB address range
+    /// \param c DTB configuration
+    address_range &init_dtb_ar(const dtb_config &c);
+
     /// \brief Initializes contents of machine DTB, if image was not available
     /// \param c Machine configuration
     /// \param dtb PMA entry for the shadow PMAs
-    static void init_dtb_contents(const machine_config &c, pma_entry &dtb);
+    static void init_dtb_contents(const machine_config &c, address_range &dtb);
 
     /// \brief Dumps statistics
     void dump_stats();
@@ -303,8 +329,8 @@ class machine final {
     }
 
     /// \brief Returns a list of descriptions for all PMA entries registered in the machine, sorted by start
-    machine_memory_range_descrs get_memory_ranges() const {
-        return m_mrds;
+    address_range_descriptions get_address_ranges() const {
+        return m_ards;
     }
 
     /// \brief Wait for external interrupts requests.
@@ -439,16 +465,18 @@ class machine final {
     /// \brief Writes a chunk of data to machine memory, by its target physical address and length.
     /// \param paddr Target physical address to start writing to.
     /// \param data Buffer that contains data to write. Must be at least \p length bytes long.
-    /// \param length Number of bytes to write starting from \p data to \p paddr.
+    /// \param length Number of bytes to write from \p data to \p paddr.
     /// \details Unlike read_memory(), the entire chunk of data, from \p paddr to \p paddr + \p length,
-    /// must reside entirely in the same memory range. Moreover, it cannot be mapped to a device.
+    /// must reside entirely in the same address range. Moreover, it cannot be mapped to a device.
     void write_memory(uint64_t paddr, const unsigned char *data, uint64_t length);
 
     /// \brief Fills a memory range with a single byte.
-    /// \param address Physical address to start filling.
-    /// \param data Byte to fill memory with.
-    /// \param length Size of memory range to fill.
-    void fill_memory(uint64_t address, uint8_t data, uint64_t length);
+    /// \param paddr Target physical address to start filling.
+    /// \param val Byte to fill memory with.
+    /// \param length Number of bytes to write starting at \p paddr.
+    /// \details Unlike read_memory(), the entire chunk of data, from \p paddr to \p paddr + \p length,
+    /// must reside entirely in the same address range. Moreover, it cannot be mapped to a device.
+    void fill_memory(uint64_t paddr, uint8_t val, uint64_t length);
 
     /// \brief Reads a chunk of data from the machine virtual memory.
     /// \param vaddr_start Virtual address to start reading.
@@ -467,33 +495,51 @@ class machine final {
     /// \returns The corresponding physical address.
     uint64_t translate_virtual_address(uint64_t vaddr);
 
-    /// \brief Obtain PMA entry from the machine state that covers a given physical memory region
-    /// \brief Microarchitecture PMAs are not considered.
-    /// \param s Pointer to machine state.
-    /// \param paddr Start of physical memory region.
-    /// \param length Length of physical memory region.
-    /// \returns Corresponding entry if found, or a sentinel entry
-    /// for an empty range.
-    const pma_entry &find_pma_entry(uint64_t paddr, uint64_t length) const;
+    /// \brief Returns the address range associated to the PMA at a given index
+    /// \param index Index of desired address range
+    /// \returns Desired address range, or an empty sentinel if index is out of bounds
+    const address_range &read_pma(uint64_t index) const noexcept {
+        if (index >= m_s.pmas.size()) {
+            static constexpr address_range sentinel{"sentinel"};
+            return sentinel;
+        }
+        // NOLINTNEXTLINE(bugprone-narrowing-conversions)
+        return *m_ars[static_cast<int>(m_s.pmas[static_cast<int>(index)])];
+    }
+
+    /// \brief Returns the address range associated to the PMA at a given index
+    /// \param index Index of desired address range
+    /// \returns Desired address range, or an empty sentinel if index is out of bounds
+    address_range &read_pma(uint64_t index) noexcept {
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-const-cast)
+        return const_cast<address_range &>(std::as_const(*this).read_pma(index));
+    }
+
+    /// \brief Obtain address range from the machine state that covers a given physical memory region
+    /// \param paddr Target physical address of start of region.
+    /// \param length Length of region, in bytes.
+    /// \returns Corresponding address range if found, or an empty sentinel otherwise.
+    /// \warning Microarchitecture address ranges are not considered in the search.
+    const address_range &find_address_range(uint64_t paddr, uint64_t length) const noexcept;
 
-    pma_entry &find_pma_entry(uint64_t paddr, uint64_t length) {
+    address_range &find_address_range(uint64_t paddr, uint64_t length) noexcept {
         // NOLINTNEXTLINE(cppcoreguidelines-pro-type-const-cast)
-        return const_cast<pma_entry &>(std::as_const(*this).find_pma_entry(paddr, length));
+        return const_cast<address_range &>(std::as_const(*this).find_address_range(paddr, length));
     }
 
-    /// \brief Obtain PMA entry covering a physical memory word
+    /// \brief Obtain address range from the machine state that covers a given word in physical memory
     /// \tparam T Type of word.
-    /// \param s Pointer to machine state.
-    /// \param paddr Target physical address.
-    /// \returns Corresponding entry if found, or a sentinel entry for an empty range.
+    /// \param paddr Target physical address of word.
+    /// \returns Corresponding address range if found, or an empty sentinel otherwise.
+    /// \warning Microarchitecture address ranges are not considered in the search.
     template <typename T>
-    const pma_entry &find_pma_entry(uint64_t paddr) const {
-        return find_pma_entry(paddr, sizeof(T));
+    const address_range &find_address_range(uint64_t paddr) const {
+        return find_address_range(paddr, sizeof(T));
     }
 
     template <typename T>
-    pma_entry &find_pma_entry(uint64_t paddr) {
-        return find_pma_entry(paddr, sizeof(T));
+    address_range &find_address_range(uint64_t paddr) {
+        return find_address_range(paddr, sizeof(T));
     }
 
     /// \brief Go over the write TLB and mark as dirty all pages currently there.
@@ -519,10 +565,9 @@ class machine final {
     void set_runtime_config(machine_runtime_config r);
 
     /// \brief Replaces a memory range.
-    /// \param range Configuration of the new memory range.
-    /// \details The machine must contain an existing memory range
-    /// matching the start and length specified in range.
-    void replace_memory_range(const memory_range_config &range);
+    /// \param config Configuration of the new memory range.
+    /// \details The machine must contain an existing memory range matching the start and length specified in range.
+    void replace_memory_range(const memory_range_config &config);
 
     /// \brief Sends cmio response
     /// \param reason Reason for sending response.
diff --git a/src/memory-address-range.cpp b/src/memory-address-range.cpp
new file mode 100644
index 000000000..a8d05ec63
--- /dev/null
+++ b/src/memory-address-range.cpp
@@ -0,0 +1,90 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#include "memory-address-range.h"
+
+namespace cartesi {
+
+using namespace std::string_literals;
+
+class base_error : public std::invalid_argument {
+public:
+    explicit base_error(const char *err) : std::invalid_argument{err} {
+        ;
+    }
+};
+
+memory_address_range::memory_address_range(const std::string &description, uint64_t start, uint64_t length,
+    const pma_flags &flags, const std::string &image_filename, const mmapd &m) try :
+    address_range(description.c_str(), start, length, flags, [](const char *err) { throw base_error{err}; }),
+    m_ptr{make_unique_mmap<unsigned char>(image_filename.c_str(), length, m.shared)},
+    m_host_memory{std::get<mmapd_ptr>(m_ptr).get()} {
+    if (!is_memory()) {
+        throw std::invalid_argument{"memory range must be flagged memory when initializing "s + description};
+    }
+    m_dirty_page_map.resize((get_length() / (8 * PMA_PAGE_SIZE)) + 1, 0xff);
+} catch (base_error &b) {
+    throw; // already contains the description
+} catch (std::exception &e) {
+    throw std::invalid_argument{e.what() + " when initializing "s + description};
+} catch (...) {
+    throw std::invalid_argument{"unknown exception when initializing "s + description};
+}
+
+memory_address_range::memory_address_range(const std::string &description, uint64_t start, uint64_t length,
+    const pma_flags &flags, const std::string &image_filename, const callocd & /*c*/) try :
+    address_range(description.c_str(), start, length, flags, [](const char *err) { throw base_error{err}; }),
+    m_ptr{make_unique_calloc<unsigned char>(length)},
+    m_host_memory{std::get<callocd_ptr>(m_ptr).get()} {
+    if (!is_memory()) {
+        throw std::invalid_argument{"memory range must be flagged memory when initializing "s + description};
+    }
+    m_dirty_page_map.resize((length / (8 * PMA_PAGE_SIZE)) + 1, 0xff);
+    // Try to load image file, if any
+    if (!image_filename.empty()) {
+        auto fp = make_unique_fopen(image_filename.c_str(), "rb", std::nothrow_t{});
+        if (!fp) {
+            throw std::system_error{errno, std::generic_category(), "error opening image file '"s + image_filename};
+        }
+        // Get file size
+        if (fseek(fp.get(), 0, SEEK_END) != 0) {
+            throw std::system_error{errno, std::generic_category(),
+                "error obtaining length of image file '"s + image_filename};
+        }
+        const auto file_length = static_cast<uint64_t>(ftello(fp.get()));
+        if (fseek(fp.get(), 0, SEEK_SET) != 0) {
+            throw std::system_error{errno, std::generic_category(),
+                "error obtaining length of image file '"s + image_filename};
+        }
+        // Check against PMA range size
+        if (file_length > length) {
+            throw std::runtime_error{"image file '"s + image_filename + "' is too large for range"s};
+        }
+        // Read to host memory
+        const auto read_length = static_cast<uint64_t>(fread(m_host_memory, 1, file_length, fp.get()));
+        if (read_length != file_length) {
+            throw std::runtime_error{"error reading from image file '"s + image_filename};
+        }
+    }
+} catch (base_error &b) {
+    throw; // already contains the description
+} catch (std::exception &e) {
+    throw std::invalid_argument{e.what() + " when initializing "s + description};
+} catch (...) {
+    throw std::invalid_argument{"unknown exception when initializing "s + description};
+}
+
+} // namespace cartesi
diff --git a/src/memory-address-range.h b/src/memory-address-range.h
new file mode 100644
index 000000000..7beb6a56f
--- /dev/null
+++ b/src/memory-address-range.h
@@ -0,0 +1,143 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef MEMORY_ADDRESS_RANGE_H
+#define MEMORY_ADDRESS_RANGE_H
+
+#include <cassert>
+#include <variant>
+
+#include "address-range.h"
+#include "unique-c-ptr.h"
+
+namespace cartesi {
+
+// Forward declarations
+class machine;
+
+/// \file
+/// \brief An address range occupied by memory
+
+class memory_address_range : public address_range {
+
+    using callocd_ptr = unique_calloc_ptr<unsigned char>;
+    using mmapd_ptr = unique_mmap_ptr<unsigned char>;
+
+    std::variant<std::monostate, ///< Before initialization
+        callocd_ptr,             ///< Automatic pointer for calloced memory
+        mmapd_ptr                ///< Automatic pointer for mmapped memory
+        >
+        m_ptr;
+
+    unsigned char *m_host_memory;          ///< Start of associated memory region in host.
+    std::vector<uint8_t> m_dirty_page_map; ///< Map of dirty pages.
+
+public:
+    using ptr_type = std::unique_ptr<memory_address_range>;
+
+    /// \brief Mmap'd range data (shared or not).
+    struct mmapd {
+        bool shared;
+    };
+
+    /// \brief Constructor for mmap'd ranges.
+    /// \param description Description of address range for use in error messages
+    /// \param start Start of address range
+    /// \param length Length of address range
+    /// \param flags Range flags
+    /// \param image_filename Path to backing file.
+    /// \param m Mmap'd range data (shared or not).
+    memory_address_range(const std::string &description, uint64_t start, uint64_t length, const pma_flags &flags,
+        const std::string &image_filename, const mmapd &m);
+
+    /// \brief Calloc'd range data (just a tag).
+    struct callocd {};
+
+    /// \brief Constructor for calloc'd ranges.
+    /// \param description Description of address range for use in error messages
+    /// \param start Start of address range
+    /// \param length Length of address range
+    /// \param flags Range flags
+    /// \param image_filename Path to backing file.
+    /// \param c Calloc'd range data (just a tag).
+    memory_address_range(const std::string &description, uint64_t start, uint64_t length, const pma_flags &flags,
+        const std::string &image_filename, const callocd & /*c*/);
+
+    memory_address_range(const memory_address_range &) = delete;
+    memory_address_range &operator=(const memory_address_range &) = delete;
+    memory_address_range &operator=(memory_address_range &&) noexcept = delete;
+
+    ~memory_address_range() override = default;
+    memory_address_range(memory_address_range &&) noexcept = default;
+
+private:
+    unsigned char *do_get_host_memory() noexcept override {
+        return m_host_memory;
+    }
+
+    const unsigned char *do_get_host_memory() const noexcept override {
+        return m_host_memory;
+    }
+
+    void do_mark_dirty_page(uint64_t offset) noexcept override {
+        auto page_index = offset >> PMA_constants::PMA_PAGE_SIZE_LOG2;
+        auto map_index = page_index >> 3;
+        assert(map_index < m_dirty_page_map.size());
+        m_dirty_page_map[map_index] |= (1 << (page_index & 7));
+    }
+
+    void do_mark_clean_page(uint64_t offset) noexcept override {
+        auto page_index = offset >> PMA_constants::PMA_PAGE_SIZE_LOG2;
+        auto map_index = page_index >> 3;
+        assert(map_index < m_dirty_page_map.size());
+        m_dirty_page_map[map_index] &= ~(1 << (page_index & 7));
+    }
+
+    void do_mark_pages_clean() noexcept override {
+        std::fill(m_dirty_page_map.begin(), m_dirty_page_map.end(), 0);
+    }
+
+    bool do_is_page_marked_dirty(uint64_t offset) const noexcept override {
+        auto page_index = offset >> PMA_constants::PMA_PAGE_SIZE_LOG2;
+        auto map_index = page_index >> 3;
+        assert(map_index < m_dirty_page_map.size());
+        return (m_dirty_page_map[map_index] & (1 << (page_index & 7))) != 0;
+    }
+
+    bool do_peek(const machine & /*m*/, uint64_t offset, uint64_t length, const unsigned char **data,
+        unsigned char * /*scratch*/) const noexcept override {
+        if (contains_relative(offset, length)) {
+            *data = get_host_memory() + offset;
+            return true;
+        }
+        *data = nullptr;
+        return false;
+    }
+};
+
+static inline auto make_callocd_memory_address_range(const std::string &description, uint64_t start, uint64_t length,
+    pma_flags flags, const std::string &image_filename = {}) {
+    return memory_address_range{description, start, length, flags, image_filename, memory_address_range::callocd{}};
+}
+
+static inline auto make_mmapd_memory_address_range(const std::string &description, uint64_t start, uint64_t length,
+    pma_flags flags, const std::string &image_filename, bool shared) {
+    return memory_address_range{description, start, length, flags, image_filename, memory_address_range::mmapd{shared}};
+}
+
+} // namespace cartesi
+
+#endif
diff --git a/src/meta.h b/src/meta.h
index 1a1f28a10..1bf94a03c 100644
--- a/src/meta.h
+++ b/src/meta.h
@@ -85,6 +85,12 @@ struct log2_size<uint64_t> {
     static constexpr int value = 3;
 };
 
+// helper type for visitor
+template <class... Ts>
+struct overloads : Ts... {
+    using Ts::operator()...;
+};
+
 /// \endcond
 
 } // namespace cartesi
diff --git a/src/mock-address-range.h b/src/mock-address-range.h
new file mode 100644
index 000000000..30b3cc5a9
--- /dev/null
+++ b/src/mock-address-range.h
@@ -0,0 +1,108 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef MOCK_ADDRESS_RANGE_H
+#define MOCK_ADDRESS_RANGE_H
+
+#include <array>
+#include <utility>
+#include <variant>
+
+#include "address-range.h"
+#include "clint-address-range.h"
+#include "htif-address-range.h"
+#include "plic-address-range.h"
+#include "pma.h"
+#include "shadow-state-address-range.h"
+#include "shadow-tlb-address-range.h"
+
+namespace cartesi {
+
+using mock_address_range = std::variant<std::monostate, address_range, clint_address_range, htif_address_range,
+    plic_address_range, shadow_state_address_range, shadow_tlb_address_range>;
+
+using mock_address_ranges = std::array<mock_address_range, PMA_MAX>;
+
+template <typename AR, typename ABRT>
+static inline mock_address_range check_mock_flags(AR &&ar, const pma_flags &flags, ABRT abrt)
+    requires std::is_rvalue_reference_v<AR &&> && std::derived_from<AR, address_range>
+{
+    if (ar.get_flags() != flags) {
+        abrt("incompatible flags in mock address range");
+        __builtin_trap();
+        return std::monostate{};
+    }
+    return std::forward<AR>(ar);
+}
+
+template <typename ABRT>
+static inline mock_address_range make_mock_address_range(uint64_t istart, uint64_t ilength, ABRT abrt) {
+    uint64_t start{};
+    auto flags = unpack_pma_istart(istart, start);
+    if (flags.M) {
+        return make_address_range(pma_get_DID_name(flags.DID), start, ilength, flags, abrt);
+    }
+    if (flags.E) {
+        return make_address_range("empty", start, ilength, flags, abrt);
+    }
+    switch (flags.DID) {
+        case PMA_ISTART_DID::shadow_state:
+            return check_mock_flags(make_shadow_state_address_range(start, ilength, abrt), flags, abrt);
+        case PMA_ISTART_DID::shadow_TLB:
+            return check_mock_flags(make_shadow_tlb_address_range(start, ilength, abrt), flags, abrt);
+        case PMA_ISTART_DID::CLINT:
+            return check_mock_flags(make_clint_address_range(start, ilength, abrt), flags, abrt);
+        case PMA_ISTART_DID::PLIC:
+            return check_mock_flags(make_plic_address_range(start, ilength, abrt), flags, abrt);
+        case PMA_ISTART_DID::HTIF:
+            return check_mock_flags(make_htif_address_range(start, ilength, abrt), flags, abrt);
+        default:
+            abrt("unhandled mock address range");
+            __builtin_trap();
+            return std::monostate{};
+    }
+};
+
+template <typename ABRT>
+address_range &get_mock_address_range(mock_address_range &mock, ABRT abrt) {
+    //??D I'm hoping the compiler optimizes this to what amounts to an if and a cast
+    static_assert(std::is_same_v<std::variant_alternative_t<0, mock_address_range>, std::monostate>);
+    switch (mock.index()) {
+        case 1:
+            return std::get<1>(mock);
+        case 2:
+            return std::get<2>(mock);
+        case 3:
+            return std::get<3>(mock);
+        case 4:
+            return std::get<4>(mock);
+        case 5:
+            return std::get<5>(mock);
+        case 6:
+            return std::get<6>(mock);
+        default: {
+            static auto unhandled = make_empty_address_range("unhandled mock address range");
+            abrt("unhandled mock address range");
+            __builtin_trap();
+            return unhandled;
+        }
+    }
+    static_assert(std::variant_size_v<mock_address_range> == 7);
+}
+
+} // namespace cartesi
+
+#endif
diff --git a/src/mock-pma-entry.h b/src/mock-pma-entry.h
deleted file mode 100644
index 75cda69cb..000000000
--- a/src/mock-pma-entry.h
+++ /dev/null
@@ -1,169 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef MOCK_PMA_ENTRY_H
-#define MOCK_PMA_ENTRY_H
-
-#include "clint.h"
-#include "htif.h"
-#include "plic.h"
-#include "pma-constants.h"
-#include "shadow-state.h"
-#include "shadow-tlb.h"
-
-namespace cartesi {
-
-class mock_pma_entry {
-public:
-    struct flags {
-        bool M;
-        bool IO;
-        bool E;
-        bool R;
-        bool W;
-        bool X;
-        bool IR;
-        bool IW;
-        PMA_ISTART_DID DID;
-    };
-
-private:
-    uint64_t m_pma_index;
-    uint64_t m_start;
-    uint64_t m_length;
-    flags m_flags;
-    const pma_driver *m_driver{nullptr};
-
-    static constexpr flags split_flags(uint64_t istart) {
-        flags f{};
-        f.M = ((istart & PMA_ISTART_M_MASK) >> PMA_ISTART_M_SHIFT) != 0;
-        f.IO = ((istart & PMA_ISTART_IO_MASK) >> PMA_ISTART_IO_SHIFT) != 0;
-        f.E = ((istart & PMA_ISTART_E_MASK) >> PMA_ISTART_E_SHIFT) != 0;
-        f.R = ((istart & PMA_ISTART_R_MASK) >> PMA_ISTART_R_SHIFT) != 0;
-        f.W = ((istart & PMA_ISTART_W_MASK) >> PMA_ISTART_W_SHIFT) != 0;
-        f.X = ((istart & PMA_ISTART_X_MASK) >> PMA_ISTART_X_SHIFT) != 0;
-        f.IR = ((istart & PMA_ISTART_IR_MASK) >> PMA_ISTART_IR_SHIFT) != 0;
-        f.IW = ((istart & PMA_ISTART_IW_MASK) >> PMA_ISTART_IW_SHIFT) != 0;
-        f.DID = static_cast<PMA_ISTART_DID>((istart & PMA_ISTART_DID_MASK) >> PMA_ISTART_DID_SHIFT);
-        return f;
-    }
-
-public:
-    template <typename ERR_F>
-    mock_pma_entry(uint64_t pma_index, uint64_t istart, uint64_t ilength, ERR_F errf) :
-        m_pma_index{pma_index},
-        m_start{istart & PMA_ISTART_START_MASK},
-        m_length{ilength},
-        m_flags{split_flags(istart)} {
-        if (m_flags.IO) {
-            switch (m_flags.DID) {
-                case PMA_ISTART_DID::shadow_state:
-                    m_driver = &shadow_state_driver;
-                    break;
-                case PMA_ISTART_DID::shadow_TLB:
-                    m_driver = &shadow_tlb_driver;
-                    break;
-                case PMA_ISTART_DID::CLINT:
-                    m_driver = &clint_driver;
-                    break;
-                case PMA_ISTART_DID::PLIC:
-                    m_driver = &plic_driver;
-                    break;
-                case PMA_ISTART_DID::HTIF:
-                    m_driver = &htif_driver;
-                    break;
-                default:
-                    errf("unsupported device in mock_pma_entry");
-                    break;
-            }
-        }
-    }
-
-    uint64_t get_index() const {
-        return m_pma_index;
-    }
-
-    flags get_flags() const {
-        return m_flags;
-    }
-
-    uint64_t get_start() const {
-        return m_start;
-    }
-
-    uint64_t get_length() const {
-        return m_length;
-    }
-
-    bool get_istart_M() const {
-        return m_flags.M;
-    }
-
-    bool get_istart_IO() const {
-        return m_flags.IO;
-    }
-
-    bool get_istart_E() const {
-        return m_flags.E;
-    }
-
-    bool get_istart_R() const {
-        return m_flags.R;
-    }
-
-    bool get_istart_W() const {
-        return m_flags.W;
-    }
-
-    bool get_istart_X() const {
-        return m_flags.X;
-    }
-
-    bool get_istart_IR() const {
-        return m_flags.IR;
-    }
-
-    PMA_ISTART_DID get_istart_DID() const {
-        return m_flags.DID;
-    }
-
-    const auto *get_driver() const {
-        return m_driver;
-    }
-
-    const auto &get_device_noexcept() const {
-        return *this;
-    }
-
-    static void *get_context() {
-        return nullptr;
-    }
-
-    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-    void mark_dirty_page(uint64_t address_in_range) {
-        (void) address_in_range;
-        // Dummy implementation.
-    }
-};
-
-template <typename ERR_F>
-static inline mock_pma_entry make_mock_pma_entry(uint64_t index, uint64_t istart, uint64_t ilength, ERR_F errf) {
-    return mock_pma_entry{index, istart, ilength, errf};
-}
-
-} // namespace cartesi
-
-#endif
diff --git a/src/plic.cpp b/src/plic-address-range.cpp
similarity index 91%
rename from src/plic.cpp
rename to src/plic-address-range.cpp
index 3eac5b174..cd8148561 100644
--- a/src/plic.cpp
+++ b/src/plic-address-range.cpp
@@ -14,17 +14,14 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#include "plic.h"
+#include "plic-address-range.h"
 
-#include <cassert>
+#include "assert-printf.h"
 #include <cstdint>
-#include <cstdio>
 
 #include "i-device-state-access.h"
 #include "interpret.h"
 #include "pma-constants.h"
-#include "pma-defines.h"
-#include "pma-driver.h"
 #include "riscv-constants.h"
 
 // Enable these defines to debug PLIC
@@ -52,7 +49,7 @@ static uint32_t plic_read_pending(i_device_state_access *a) {
 }
 
 /// \brief Called only by the driver when it begins serving a pending interrupt request.
-static bool plic_read_claim_complete(i_device_state_access *a, uint64_t *val) {
+static bool plic_read_claim_complete(i_device_state_access *a, uint64_t *pval) {
     const uint32_t girqpend = a->read_plic_girqpend();
     uint32_t girqsrvd = a->read_plic_girqsrvd();
     uint32_t ipmask = girqpend & ~girqsrvd;
@@ -68,7 +65,7 @@ static bool plic_read_claim_complete(i_device_state_access *a, uint64_t *val) {
         girqsrvd |= irq_mask;
         a->write_plic_girqsrvd(girqsrvd);
         // The PLIC will then return the interrupt source id to the target
-        *val = irq_id;
+        *pval = irq_id;
         // If all pending interrupts have been served, reset mip.
         ipmask = girqpend & ~girqsrvd;
         if (ipmask == 0) {
@@ -76,10 +73,10 @@ static bool plic_read_claim_complete(i_device_state_access *a, uint64_t *val) {
         }
     } else {
         // The PLIC will return an id of zero, if there were no pending interrupts for the target
-        *val = 0;
+        *pval = 0;
     }
 #ifdef DEBUG_PLIC
-    std::ignore = fprintf(stderr, "plic: claim irq_id=%d\n", (int) *val);
+    std::ignore = fprintf(stderr, "plic: claim irq_id=%d\n", (int) *pval);
 #endif
     return true;
 }
@@ -108,8 +105,8 @@ static execute_status plic_write_claim_complete(i_device_state_access *a, uint32
     return execute_status::success;
 }
 
-/// \brief PLIC device read callback. See ::pma_read.
-static bool plic_read(void * /*context*/, i_device_state_access *a, uint64_t offset, uint64_t *val, int log2_size) {
+bool plic_address_range::do_read_device(i_device_state_access *a, uint64_t offset, int log2_size,
+    uint64_t *pval) const noexcept {
 #ifdef DEBUG_PLIC_MMIO
     std::ignore = fprintf(stderr, "plic: mmio read offset=0x%lx log2_size=%d\n", (long) offset, log2_size);
 #endif
@@ -153,28 +150,28 @@ static bool plic_read(void * /*context*/, i_device_state_access *a, uint64_t off
         case plic_csr_rel_addr::priority31:
             // A valid implementation can hardwire all input priority levels.
             // We hardwire all supported interrupt sources to the lowest priority
-            *val = PLIC_LOWEST_IRQ_PRIORITY;
+            *pval = PLIC_LOWEST_IRQ_PRIORITY;
             return true;
         case plic_csr_rel_addr::pending:
-            *val = plic_read_pending(a);
+            *pval = plic_read_pending(a);
             return true;
         case plic_csr_rel_addr::enabled:
             // A valid implementation can hardwire interrupt routing to a fixed hart context.
             // We hardwire all supported interrupt source to be always enabled in context 0.
-            *val = PLIC_ENABLED_IRQ_MASK;
+            *pval = PLIC_ENABLED_IRQ_MASK;
             return true;
         case plic_csr_rel_addr::claim_complete:
-            return plic_read_claim_complete(a, val);
+            return plic_read_claim_complete(a, pval);
         default:
             // Other PLIC CSRs are WARL hardwired to 0
-            *val = 0;
+            *pval = 0;
             return true;
     }
 }
 
 /// \brief PLIC device read callback. See ::pma_write.
-static execute_status plic_write(void * /*context*/, i_device_state_access *a, uint64_t offset, uint64_t val,
-    int log2_size) {
+execute_status plic_address_range::do_write_device(i_device_state_access *a, uint64_t offset, int log2_size,
+    uint64_t val) noexcept {
 #ifdef DEBUG_PLIC_MMIO
     std::ignore =
         fprintf(stderr, "plic: mmio write offset=0x%lx log2_size=%d val=0x%x\n", (long) offset, log2_size, (int) val);
@@ -220,6 +217,4 @@ void plic_reset_pending_irq(i_device_state_access *a, uint32_t irq_id) {
     }
 }
 
-const pma_driver plic_driver = {.name = "PLIC", .read = plic_read, .write = plic_write};
-
 } // namespace cartesi
diff --git a/src/plic-address-range.h b/src/plic-address-range.h
new file mode 100644
index 000000000..e430a1974
--- /dev/null
+++ b/src/plic-address-range.h
@@ -0,0 +1,80 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef PLIC_ADDRESS_RANGE_H
+#define PLIC_ADDRESS_RANGE_H
+
+#include <cstdint>
+
+#include "i-device-state-access.h"
+#include "plic-constants.h"
+#include "pristine-address-range.h"
+
+/// \file
+/// \brief Platform-Level Interrupt Controller address range.
+
+namespace cartesi {
+
+/// \brief Sets a new pending interrupt request.
+/// \details This is called only by devices to notify an external interrupt.
+void plic_set_pending_irq(i_device_state_access *a, uint32_t irq_id);
+
+/// \brief Clears a pending interrupt request.
+/// \details This is called only by devices to remove an external interrupt notification.
+void plic_reset_pending_irq(i_device_state_access *a, uint32_t irq_id);
+
+class plic_address_range final : public pristine_address_range {
+
+    static constexpr pma_flags m_plic_flags{
+        .M = false,
+        .IO = true,
+        .E = false,
+        .R = true,
+        .W = true,
+        .X = false,
+        .IR = false,
+        .IW = false,
+        .DID = PMA_ISTART_DID::PLIC,
+    };
+
+public:
+    template <typename ABRT>
+    plic_address_range(uint64_t start, uint64_t length, ABRT abrt) :
+        pristine_address_range("PLIC device", start, length, m_plic_flags, abrt) {
+        ;
+    }
+
+    plic_address_range(const plic_address_range &other) = default;
+    plic_address_range &operator=(const plic_address_range &other) = default;
+    plic_address_range(plic_address_range &&other) = default;
+    plic_address_range &operator=(plic_address_range &&other) = default;
+    ~plic_address_range() override = default;
+
+private:
+    bool do_read_device(i_device_state_access *a, uint64_t offset, int log2_size,
+        uint64_t *pval) const noexcept override;
+    execute_status do_write_device(i_device_state_access *a, uint64_t offset, int log2_size,
+        uint64_t val) noexcept override;
+};
+
+template <typename ABRT>
+static inline plic_address_range make_plic_address_range(uint64_t start, uint64_t length, ABRT abrt) {
+    return plic_address_range{start, length, abrt};
+}
+
+} // namespace cartesi
+
+#endif
diff --git a/src/plic.h b/src/plic-constants.h
similarity index 86%
rename from src/plic.h
rename to src/plic-constants.h
index a719e1402..d6eda8311 100644
--- a/src/plic.h
+++ b/src/plic-constants.h
@@ -14,15 +14,13 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#ifndef PLIC_H
-#define PLIC_H
+#ifndef PLIC_CONSTANTS_H
+#define PLIC_CONSTANTS_H
 
 #include <cstdint>
 
-#include "pma-driver.h"
-
 /// \file
-/// \brief Clock interruptor device.
+/// \brief Platform-Level Interrupt Controller constants.
 
 namespace cartesi {
 
@@ -74,17 +72,6 @@ enum plic_csr_rel_addr : uint64_t {
     // .. Interrupt threshold and claim_complete for other sources and contexts (unsupported)
 };
 
-/// \brief Sets a new pending interrupt request.
-/// \details This is called only by devices to notify an external interrupt.
-void plic_set_pending_irq(i_device_state_access *a, uint32_t irq_id);
-
-/// \brief Clears a pending interrupt request.
-/// \details This is called only by devices to remove an external interrupt notification.
-void plic_reset_pending_irq(i_device_state_access *a, uint32_t irq_id);
-
-/// \brief Global PLIC device driver instance
-extern const pma_driver plic_driver;
-
 } // namespace cartesi
 
 #endif
diff --git a/src/plic-factory.cpp b/src/plic-factory.cpp
deleted file mode 100644
index 01bb24686..000000000
--- a/src/plic-factory.cpp
+++ /dev/null
@@ -1,32 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#include "plic-factory.h"
-
-#include <cstdint>
-
-#include "plic.h"
-#include "pma-constants.h"
-#include "pma.h"
-
-namespace cartesi {
-
-pma_entry make_plic_pma_entry(uint64_t start, uint64_t length) {
-    const pma_entry::flags f{.R = true, .W = true, .X = false, .IR = false, .IW = false, .DID = PMA_ISTART_DID::PLIC};
-    return make_device_pma_entry("PLIC device", start, length, pma_peek_pristine, &plic_driver).set_flags(f);
-}
-
-} // namespace cartesi
diff --git a/src/plic-factory.h b/src/plic-factory.h
deleted file mode 100644
index 5ac9e26d6..000000000
--- a/src/plic-factory.h
+++ /dev/null
@@ -1,34 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef PLIC_FACTORY_H
-#define PLIC_FACTORY_H
-
-#include <cstdint>
-
-#include "pma.h"
-
-namespace cartesi {
-
-/// \brief Creates a PMA entry for the PLIC device
-/// \param start Start address for memory range.
-/// \param length Length of memory range.
-/// \returns Corresponding PMA entry
-pma_entry make_plic_pma_entry(uint64_t start, uint64_t length);
-
-} // namespace cartesi
-
-#endif
diff --git a/src/pma-constants.h b/src/pma-constants.h
index 38d9df885..723437296 100644
--- a/src/pma-constants.h
+++ b/src/pma-constants.h
@@ -19,14 +19,10 @@
 
 #include <cstdint>
 
-#include "machine-c-api.h"
 #include "pma-defines.h"
 
 namespace cartesi {
 
-/// \file
-/// \brief Physical memory attributes constants.
-
 /// \brief Fixed PMA ranges.
 enum PMA_ranges : uint64_t {
     PMA_SHADOW_STATE_START = EXPAND_UINT64_C(PMA_SHADOW_STATE_START_DEF),   ///< Start of processor shadow range
@@ -93,7 +89,7 @@ enum PMA_ISTART_shifts {
     PMA_ISTART_IR_SHIFT = 6,
     PMA_ISTART_IW_SHIFT = 7,
     PMA_ISTART_DID_SHIFT = 8,
-    PMA_ISTART_START_SHIFT = 12,
+    PMA_ISTART_START_SHIFT = PMA_PAGE_SIZE_LOG2_DEF
 };
 
 /// \brief PMA istart masks
@@ -112,57 +108,20 @@ enum PMA_ISTART_masks : uint64_t {
 
 /// \brief PMA device ids
 enum class PMA_ISTART_DID {
-    memory = PMA_MEMORY_DID_DEF,                   ///< DID for memory
-    shadow_state = PMA_SHADOW_STATE_DID_DEF,       ///< DID for shadow device
-    shadow_pmas = PMA_SHADOW_PMAS_DID_DEF,         ///< DID for shadow pma array device
-    shadow_TLB = PMA_SHADOW_TLB_DID_DEF,           ///< DID for shadow TLB device
-    flash_drive = PMA_FLASH_DRIVE_DID_DEF,         ///< DID for drive device
-    CLINT = PMA_CLINT_DID_DEF,                     ///< DID for CLINT device
-    PLIC = PMA_PLIC_DID_DEF,                       ///< DID for PLIC device
-    HTIF = PMA_HTIF_DID_DEF,                       ///< DID for HTIF device
-    VIRTIO = PMA_VIRTIO_DID_DEF,                   ///< DID for VirtIO devices
-    cmio_rx_buffer = PMA_CMIO_RX_BUFFER_DID_DEF,   ///< DID for cmio receive buffer
-    cmio_tx_buffer = PMA_CMIO_TX_BUFFER_DID_DEF,   ///< DID for cmio transmit buffer
-    shadow_uarch = PMA_SHADOW_UARCH_STATE_DID_DEF, ///< DID for shadow uarch state device
+    memory = PMA_MEMORY_DID_DEF,                         ///< DID for memory
+    shadow_state = PMA_SHADOW_STATE_DID_DEF,             ///< DID for shadow device
+    shadow_pmas = PMA_SHADOW_PMAS_DID_DEF,               ///< DID for shadow pma array device
+    shadow_TLB = PMA_SHADOW_TLB_DID_DEF,                 ///< DID for shadow TLB device
+    flash_drive = PMA_FLASH_DRIVE_DID_DEF,               ///< DID for drive device
+    CLINT = PMA_CLINT_DID_DEF,                           ///< DID for CLINT device
+    PLIC = PMA_PLIC_DID_DEF,                             ///< DID for PLIC device
+    HTIF = PMA_HTIF_DID_DEF,                             ///< DID for HTIF device
+    VIRTIO = PMA_VIRTIO_DID_DEF,                         ///< DID for VirtIO devices
+    cmio_rx_buffer = PMA_CMIO_RX_BUFFER_DID_DEF,         ///< DID for cmio receive buffer
+    cmio_tx_buffer = PMA_CMIO_TX_BUFFER_DID_DEF,         ///< DID for cmio transmit buffer
+    shadow_uarch_state = PMA_SHADOW_UARCH_STATE_DID_DEF, ///< DID for shadow uarch state device
 };
 
-static constexpr const char *pma_get_DID_name(PMA_ISTART_DID did) {
-    switch (did) {
-        case PMA_ISTART_DID::memory:
-            return "DID.memory";
-        case PMA_ISTART_DID::shadow_state:
-            return "DID.shadow_state";
-        case PMA_ISTART_DID::shadow_pmas:
-            return "DID.shadow_pmas";
-        case PMA_ISTART_DID::shadow_TLB:
-            return "DID.shadow_TLB";
-        case PMA_ISTART_DID::flash_drive:
-            return "DID.flash_drive";
-        case PMA_ISTART_DID::CLINT:
-            return "DID.CLINT";
-        case PMA_ISTART_DID::PLIC:
-            return "DID.PLIC";
-        case PMA_ISTART_DID::HTIF:
-            return "DID.HTIF";
-        case PMA_ISTART_DID::VIRTIO:
-            return "DID.VIRTIO";
-        case PMA_ISTART_DID::cmio_rx_buffer:
-            return "DID.cmio_rx_buffer";
-        case PMA_ISTART_DID::cmio_tx_buffer:
-            return "DID.cmio_tx_buffer";
-        case PMA_ISTART_DID::shadow_uarch:
-            return "DID.shadow_uarch";
-        default:
-            return "DID.unknown";
-    }
-}
-
-static_assert(PMA_CMIO_RX_BUFFER_START_DEF == CM_PMA_CMIO_RX_BUFFER_START);
-static_assert(PMA_CMIO_RX_BUFFER_LOG2_SIZE_DEF == CM_PMA_CMIO_RX_BUFFER_LOG2_SIZE);
-static_assert(PMA_CMIO_TX_BUFFER_START_DEF == CM_PMA_CMIO_TX_BUFFER_START);
-static_assert(PMA_CMIO_TX_BUFFER_LOG2_SIZE_DEF == CM_PMA_CMIO_TX_BUFFER_LOG2_SIZE);
-static_assert(PMA_RAM_START_DEF == CM_PMA_RAM_START);
-
 } // namespace cartesi
 
 #endif
diff --git a/src/pma-driver.cpp b/src/pma-driver.cpp
deleted file mode 100644
index cc5b38e9e..000000000
--- a/src/pma-driver.cpp
+++ /dev/null
@@ -1,35 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#include "pma-driver.h"
-
-#include <cstdint>
-
-#include "interpret.h"
-
-namespace cartesi {
-
-bool device_read_error(void * /*context*/, i_device_state_access * /*a*/, uint64_t /*offset*/, uint64_t * /*val*/,
-    int /*log2_size*/) {
-    return false;
-}
-
-execute_status device_write_error(void * /*context*/, i_device_state_access * /*a*/, uint64_t /*offset*/,
-    uint64_t /*val*/, int /*log2_size*/) {
-    return execute_status::failure;
-}
-
-} // namespace cartesi
diff --git a/src/pma-driver.h b/src/pma-driver.h
deleted file mode 100644
index c3534610b..000000000
--- a/src/pma-driver.h
+++ /dev/null
@@ -1,67 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef PMA_DRIVER_H
-#define PMA_DRIVER_H
-
-#include <cstdint>
-
-#include "interpret.h"
-
-namespace cartesi {
-
-/// \file
-/// \brief Declares pma_driver, which provides callback functions for reading and writing to device memory ranges
-
-// Forward declarations
-class i_device_state_access;
-
-/// \brief Prototype for callback invoked when machine wants to read from a device range.
-/// \param context Device-specific context
-/// \param da Object through which the machine state can be accessed.
-/// \param offset Offset of requested value from range base address.
-/// \param val Pointer to word where value will be stored.
-/// \param log2_size log<sub>2</sub> of size of value to read (0 = uint8_t, 1 = uint16_t, 2 = uint32_t, 3 = uint64_t).
-/// \returns True if operation succeeded, false otherwise.
-using device_read = bool (*)(void *context, i_device_state_access *da, uint64_t offset, uint64_t *val, int log2_size);
-
-/// \brief Default read callback issues error on reads.
-bool device_read_error(void *context, i_device_state_access *da, uint64_t offset, uint64_t *val, int log2_size);
-
-/// \brief Prototype for callback invoked when machine wants to write to a range.
-/// \param context Device-specific context
-/// \param da Object through which the machine state can be accessed.
-/// \param offset Offset of requested value from range base address.
-/// \param val Word to be written at \p offset.
-/// \param log2_size log<sub>2</sub> of size of value to read (0 = uint8_t, 1 = uint16_t, 2 = uint32_t, 3 = uint64_t).
-/// \returns execute::failure if operation failed, otherwise other success enumeration if operation succeeded.
-using device_write = execute_status (*)(void *context, i_device_state_access *da, uint64_t offset, uint64_t val,
-    int log2_size);
-
-/// \brief Default write callback issues error on write.
-execute_status device_write_error(void *context, i_device_state_access *da, uint64_t offset, uint64_t val,
-    int log2_size);
-
-/// \brief Driver for device memory ranges.
-struct pma_driver final {
-    const char *name{""};
-    device_read read{device_read_error};
-    device_write write{device_write_error};
-};
-
-} // namespace cartesi
-
-#endif
diff --git a/src/pma.cpp b/src/pma.cpp
deleted file mode 100644
index 6f566cec5..000000000
--- a/src/pma.cpp
+++ /dev/null
@@ -1,220 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#include "pma.h"
-
-#include <algorithm>
-#include <cerrno>
-#include <cstdint>
-#include <cstdio>
-#include <cstdlib>
-#include <cstring>
-#include <exception>
-#include <string>
-#include <system_error>
-#include <tuple>
-
-#include "is-pristine.h"
-#include "os.h"
-#include "pma-constants.h"
-#include "pma-driver.h"
-#include "unique-c-ptr.h"
-
-namespace cartesi {
-
-using namespace std::string_literals;
-
-pma_memory::pma_memory(const std::string &description, uint64_t length, const callocd & /*c*/) try :
-    m_ptr{make_unique_calloc<unsigned char>(length)},
-    m_host_memory{std::get<callocd_ptr>(m_ptr).get()} {
-} catch (std::exception &e) {
-    throw std::runtime_error{e.what() + " when initializing "s + description};
-}
-
-pma_memory::pma_memory(const std::string &description, uint64_t length, const std::string &path, const callocd &c) :
-    pma_memory{description, length, c} {
-    // Try to load image file, if any
-    if (!path.empty()) {
-        auto fp = make_unique_fopen(path.c_str(), "rb", std::nothrow_t{});
-        if (!fp) {
-            throw std::system_error{errno, std::generic_category(),
-                "error opening image file '"s + path + "' when initializing "s + description};
-        }
-        // Get file size
-        if (fseek(fp.get(), 0, SEEK_END) != 0) {
-            throw std::system_error{errno, std::generic_category(),
-                "error obtaining length of image file '"s + path + "' when initializing "s + description};
-        }
-        const auto file_length = static_cast<uint64_t>(ftello(fp.get()));
-        if (fseek(fp.get(), 0, SEEK_SET) != 0) {
-            throw std::system_error{errno, std::generic_category(),
-                "error obtaining length of image file '"s + path + "' when initializing "s + description};
-        }
-        // Check against PMA range size
-        if (file_length > length) {
-            throw std::runtime_error{"image file '"s + path + "' of "s + description + " is too large for range"s};
-        }
-        // Read to host memory
-        const auto read_length = static_cast<uint64_t>(fread(m_host_memory, 1, length, fp.get()));
-        if (read_length != file_length) {
-            throw std::runtime_error{"error reading from image file '"s + path + "' when initializing "s + description};
-        }
-    }
-}
-
-pma_memory::pma_memory(const std::string &description, uint64_t length, const std::string &path, const mmapd &m) try :
-    m_ptr{make_unique_mmap<unsigned char>(path.c_str(), length, m.shared)},
-    m_host_memory{std::get<mmapd_ptr>(m_ptr).get()} {
-} catch (std::exception &e) {
-    throw std::runtime_error{e.what() + " when initializing "s + description};
-}
-
-uint64_t pma_entry::get_istart() const {
-    uint64_t istart = m_start;
-    istart |= (static_cast<uint64_t>(get_istart_M()) << PMA_ISTART_M_SHIFT);
-    istart |= (static_cast<uint64_t>(get_istart_IO()) << PMA_ISTART_IO_SHIFT);
-    istart |= (static_cast<uint64_t>(get_istart_E()) << PMA_ISTART_E_SHIFT);
-    istart |= (static_cast<uint64_t>(get_istart_R()) << PMA_ISTART_R_SHIFT);
-    istart |= (static_cast<uint64_t>(get_istart_W()) << PMA_ISTART_W_SHIFT);
-    istart |= (static_cast<uint64_t>(get_istart_X()) << PMA_ISTART_X_SHIFT);
-    istart |= (static_cast<uint64_t>(get_istart_IR()) << PMA_ISTART_IR_SHIFT);
-    istart |= (static_cast<uint64_t>(get_istart_IW()) << PMA_ISTART_IW_SHIFT);
-    istart |= (static_cast<uint64_t>(get_istart_DID()) << PMA_ISTART_DID_SHIFT);
-    return istart;
-}
-
-uint64_t pma_entry::get_ilength() const {
-    return m_length;
-}
-
-void pma_entry::write_memory(uint64_t paddr, const unsigned char *data, uint64_t size) {
-    if (!get_istart_M() || get_istart_E()) {
-        throw std::invalid_argument{"address range not entirely in memory PMA"};
-    }
-    if (!contains(paddr, size)) {
-        throw std::invalid_argument{"range not contained in pma"};
-    }
-    if (data == nullptr) {
-        throw std::invalid_argument{"invalid data buffer"};
-    }
-    // The case of writing a large range chunk is special and optimized for uarch reset
-    if (size > PMA_PAGE_SIZE) {
-        // Copy in chunks of page size, to avoid marking dirty pages unnecessarily
-        for (uint64_t offset = 0; offset < size; offset += PMA_PAGE_SIZE) {
-            const uint64_t paddr_offset = paddr + offset;
-            const uint64_t chunk_len = std::min<uint64_t>(PMA_PAGE_SIZE, size - offset);
-            const unsigned char *src = data + offset;
-            unsigned char *dest = get_memory().get_host_memory() + (paddr_offset - get_start());
-            if (memcmp(dest, src, chunk_len) != 0) {
-                // Page is different, we have to copy memory
-                memcpy(dest, src, chunk_len);
-                mark_dirty_pages(paddr + offset, chunk_len);
-            }
-        }
-    } else {
-        memcpy(get_memory().get_host_memory() + (paddr - get_start()), data, size);
-        mark_dirty_pages(paddr, size);
-    }
-}
-
-void pma_entry::fill_memory(uint64_t paddr, unsigned char value, uint64_t size) {
-    if (!get_istart_M() || get_istart_E()) {
-        throw std::invalid_argument{"address range not entirely in memory PMA"};
-    }
-    if (!contains(paddr, size)) {
-        throw std::invalid_argument{"range not contained in pma"};
-    }
-    // The case of filling a large range with zeros is special and optimized for uarch reset
-    if (value == 0 && size > PMA_PAGE_SIZE) {
-        // Fill in chunks of page size, to avoid marking dirty pages unnecessarily
-        for (uint64_t offset = 0; offset < size; offset += PMA_PAGE_SIZE) {
-            const uint64_t paddr_offset = paddr + offset;
-            const uint64_t chunk_len = std::min<uint64_t>(PMA_PAGE_SIZE, size - offset);
-            unsigned char *dest = get_memory().get_host_memory() + (paddr_offset - get_start());
-            if (!is_pristine(dest, chunk_len)) {
-                // Page is different, we have to fill memory
-                memset(dest, 0, chunk_len);
-                mark_dirty_pages(paddr + offset, chunk_len);
-            }
-        }
-    } else {
-        memset(get_memory().get_host_memory() + (paddr - get_start()), value, size);
-        mark_dirty_pages(paddr, size);
-    }
-}
-
-bool pma_peek_error(const pma_entry & /*pma*/, const machine & /*m*/, uint64_t /*offset*/, uint64_t /*length*/,
-    const unsigned char ** /*page_data*/, unsigned char * /*scratch*/) {
-    return false;
-}
-
-bool pma_peek_pristine(const pma_entry &pma, const machine & /*m*/, uint64_t offset, uint64_t length,
-    const unsigned char **data, unsigned char * /*scratch*/) {
-    *data = nullptr;
-    return length <= pma.get_length() && offset <= pma.get_length() - length;
-}
-
-/// \brief Memory range peek callback. See pma_peek.
-static bool memory_peek(const pma_entry &pma, const machine & /*m*/, uint64_t offset, uint64_t length,
-    const unsigned char **data, unsigned char * /*scratch*/) {
-    // If desired data does not fit in range, return error
-    if (length > pma.get_length() || offset > pma.get_length() - length) {
-        *data = nullptr;
-        return false;
-    }
-    // Otherwise, return pointer directly into host memory
-    *data = pma.get_memory().get_host_memory() + offset;
-    return true;
-}
-
-pma_entry make_mmapd_memory_pma_entry(const std::string &description, uint64_t start, uint64_t length,
-    const std::string &path, bool shared) {
-    if (length == 0) {
-        throw std::invalid_argument{description + " length cannot be zero"s};
-    }
-    return pma_entry{description, start, length, pma_memory{description, length, path, pma_memory::mmapd{shared}},
-        memory_peek};
-}
-
-pma_entry make_callocd_memory_pma_entry(const std::string &description, uint64_t start, uint64_t length) {
-    if (length == 0) {
-        throw std::invalid_argument{description + " length cannot be zero"s};
-    }
-    return pma_entry{description, start, length, pma_memory{description, length, pma_memory::callocd{}}, memory_peek};
-}
-
-pma_entry make_callocd_memory_pma_entry(const std::string &description, uint64_t start, uint64_t length,
-    const std::string &path) {
-    if (length == 0) {
-        throw std::invalid_argument{description + " length cannot be zero"s};
-    }
-    return pma_entry{description, start, length, pma_memory{description, length, path, pma_memory::callocd{}},
-        memory_peek};
-}
-
-pma_entry make_device_pma_entry(const std::string &description, uint64_t start, uint64_t length, pma_peek peek,
-    const pma_driver *driver, void *context) {
-    if (length == 0) {
-        throw std::invalid_argument{description + " length cannot be zero"s};
-    }
-    return pma_entry{description, start, length, pma_device{description, driver, context}, peek};
-}
-
-pma_entry make_empty_pma_entry(const std::string &description, uint64_t start, uint64_t length) {
-    return pma_entry{description, start, length};
-}
-
-} // namespace cartesi
diff --git a/src/pma.h b/src/pma.h
index f30b2e720..eef556cb0 100644
--- a/src/pma.h
+++ b/src/pma.h
@@ -17,545 +17,88 @@
 #ifndef PMA_H
 #define PMA_H
 
-#include <algorithm>
-#include <cassert>
 #include <cstdint>
-#include <stdexcept>
-#include <string>
-#include <utility>
-#include <variant>
-#include <vector>
 
 #include "pma-constants.h"
-#include "pma-driver.h"
-#include "unique-c-ptr.h"
 
 namespace cartesi {
 
-// Forward declarations
-class pma_entry;
-class machine;
-
 /// \file
-/// \brief Physical memory attributes interface
-
-/// \brief Prototype for callback invoked when machine wants to peek into a range with no side-effects.
-/// \param pma Reference to corresponding PMA entry.
-/// \param m Reference to associated machine.
-/// \param offset Offset within range to start reading.
-/// \param length Number of bytes to read.
-/// \param data Receives pointer to start of data, or nullptr if data is constant *and* pristine.
-/// \param scratch Pointer to memory buffer that must be able to hold \p length bytes.
-/// \returns True if operation succeeded, false otherwise.
-using pma_peek = bool (*)(const pma_entry &pma, const machine &m, uint64_t offset, uint64_t length,
-    const unsigned char **data, unsigned char *scratch);
-
-/// \brief Default peek callback issues error on peeks.
-bool pma_peek_error(const pma_entry & /*pma*/, const machine & /*m*/, uint64_t /*offset*/, uint64_t /*length*/,
-    const unsigned char ** /*data*/, unsigned char * /*scratch*/);
-
-/// \brief Default peek callback for pristine ranges.
-bool pma_peek_pristine(const pma_entry & /*pma*/, const machine & /*m*/, uint64_t offset, uint64_t length,
-    const unsigned char **data, unsigned char * /*scratch*/);
-
-/// \brief Data for IO ranges.
-class pma_device final {
-
-    const pma_driver *m_driver; ///< Driver with callbacks.
-    void *m_context;            ///< Context to pass to callbacks.
-
-public:
-    /// \brief Constructor from entries.
-    /// \param description Informative description of PMA entry for use in error messages
-    /// \param context Context to pass to callbacks.
-    /// \param driver Pointer to driver with callbacks.
-    pma_device(const std::string & /*description*/, const pma_driver *driver, void *context) :
-        m_driver{driver},
-        m_context{context} {}
-    ~pma_device() = default;
-
-    pma_device(const pma_device &other) = delete;
-    pma_device(pma_device &&other) = default;
-    pma_device &operator=(const pma_device &other) = delete;
-    pma_device &operator=(pma_device &&other) = default;
-
-    /// \brief Returns context to pass to callbacks.
-    void *get_context() {
-        return m_context;
-    }
-
-    /// \brief Returns context to pass to callbacks.
-    void *get_context() const {
-        return m_context;
-    }
-
-    /// \brief Returns pointer to driver with callbacks
-    const pma_driver *get_driver() const {
-        return m_driver;
-    }
-};
-
-// For performance reasons, we can't possibly invoke a
-// function every time we want to read from a memory
-// range, so memory ranges do not use a driver like
-// IO ranges do. So we use naked pointers to host memory.
-
-/// \brief Data for memory ranges.
-class pma_memory final {
-
-    using callocd_ptr = unique_calloc_ptr<unsigned char>;
-    using mmapd_ptr = unique_mmap_ptr<unsigned char>;
-
-    std::variant<std::monostate, ///< Before initialization
-        callocd_ptr,             ///< Automatic pointer for calloced memory
-        mmapd_ptr                ///< Automatic pointer for mmapped memory
-        >
-        m_ptr;
-
-    unsigned char *m_host_memory; ///< Start of associated memory region in host.
-
-public:
-    /// \brief Mmap'd range data (shared or not).
-    struct mmapd {
-        bool shared;
-    };
-
-    /// \brief Constructor for mmap'd ranges.
-    /// \param description Informative description of PMA entry for use in error messages
-    /// \param length Length of range.
-    /// \param path Path for backing file.
-    /// \param m Mmap'd range data (shared or not).
-    pma_memory(const std::string &description, uint64_t length, const std::string &path, const mmapd &m);
-
-    /// \brief Calloc'd range data (just a tag).
-    struct callocd {};
-
-    /// \brief Constructor for calloc'd ranges.
-    /// \param description Informative description of PMA entry for use in error messages
-    /// \param length Length of range.
-    /// \param path Path for backing file.
-    /// \param c Calloc'd range data (just a tag).
-    pma_memory(const std::string &description, uint64_t length, const std::string &path, const callocd &c);
-
-    /// \brief Constructor for calloc'd ranges.
-    /// \param description Informative description of PMA entry for use in error messages
-    /// \param length Length of range.
-    /// \param c Calloc'd range data (just a tag).
-    pma_memory(const std::string &description, uint64_t length, const callocd &c);
-
-    /// \brief No copy constructor
-    pma_memory(const pma_memory &other) = delete;
-
-    /// \brief No copy assignment
-    pma_memory &operator=(const pma_memory &other) = delete;
-
-    /// \brief Move constructor
-    pma_memory(pma_memory &&other) noexcept = default;
-
-    /// \brief Move assignment
-    pma_memory &operator=(pma_memory &&other) noexcept = default;
-
-    /// \brief Default destructor
-    ~pma_memory() = default;
-
-    /// \brief Returns start of associated memory region in host
-    unsigned char *get_host_memory() {
-        return m_host_memory;
-    }
-
-    /// \brief Returns start of associated memory region in host
-    const unsigned char *get_host_memory() const {
-        return m_host_memory;
-    }
-};
-
-/// \brief Physical Memory Attribute entry.
-/// \details The target's physical memory layout is described by an
-/// array of PMA entries.
-class pma_entry final {
-public:
-    ///< Exploded flags for PMA entry.
-    struct flags {
-        // bool M = std::holds_alternative<pma_memory>(data);
-        // bool IO = std::holds_alternative<pma_device>(data);
-        // bool E = std::holds_alternative<std::monostate>(data);
-        bool R;
-        bool W;
-        bool X;
-        bool IR;
-        bool IW;
-        PMA_ISTART_DID DID;
-    };
-
-private:
-    std::string m_description; ///< Informative description of PMA entry for use in error messages.
-    uint64_t m_start;          ///< Start of physical memory range in target.
-    uint64_t m_length;         ///< Length of physical memory range in target.
-    int m_index;               ///< PMA entry index in target.
-    flags m_flags;             ///< PMA Flags
-
-    pma_peek m_peek; ///< Callback for peek operations.
-
-    std::vector<uint8_t> m_dirty_page_map; ///< Map of dirty pages.
-
-    std::variant<std::monostate, ///< No data (E ranges)
-        pma_device,              ///< Data specific to IO ranges
-        pma_memory               ///< Data specific to M ranges
-        >
-        m_data;
-
-public:
-    /// \brief No copy constructor
-    pma_entry(const pma_entry &) = delete;
-    /// \brief No copy assignment
-    pma_entry &operator=(const pma_entry &) = delete;
-    /// \brief Default move constructor
-    pma_entry(pma_entry &&) = default;
-    /// \brief Default move assignment
-    pma_entry &operator=(pma_entry &&) = default;
-    /// \bried Default destructor
-    ~pma_entry() = default;
-
-    /// \brief Constructor for empty entry
-    /// \param description Informative description of PMA entry for use in error messages
-    /// \param start Start of range.
-    /// \param length Length of range.
-    explicit pma_entry(std::string description, uint64_t start, uint64_t length) :
-        m_description{std::move(description)},
-        m_start{start},
-        m_length{length},
-        m_index{PMA_MAX},
-        m_flags{},
-        m_peek{pma_peek_error},
-        m_data{std::monostate{}} {
-        ;
-    }
-
-    /// \brief Default constructor creates an empty entry spanning an empty range
-    /// \param description Informative description of PMA entry for use in error messages
-    explicit pma_entry(std::string description = "empty") : pma_entry{std::move(description), 0, 0} {
-        ;
-    }
-
-    /// \brief Constructor for memory entry
-    /// \param description Informative description of PMA entry for use in error messages
-    /// \param start Start of range.
-    /// \param length Length of range.
-    /// \param memory Memory PMA holding range data
-    /// \param peek Function used to extract a page of data from the range
-    explicit pma_entry(std::string description, uint64_t start, uint64_t length, pma_memory &&memory,
-        pma_peek peek = pma_peek_error) :
-        m_description{std::move(description)},
-        m_start{start},
-        m_length{length},
-        m_index{PMA_MAX},
-        m_flags{},
-        m_peek{peek},
-        m_data{std::move(memory)} {
-        // allocate dirty page map and mark all pages as dirty
-        m_dirty_page_map.resize((length / (8 * PMA_PAGE_SIZE)) + 1, 0xff);
-    }
-
-    /// \brief Constructor for device entry
-    /// \param description Informative description of PMA entry for use in error messages
-    /// \param start Start of range.
-    /// \param length Length of range.
-    /// \param device Device PMA controlling range data
-    /// \param peek Function used to extract a page of data from the range
-    explicit pma_entry(std::string description, uint64_t start, uint64_t length, pma_device &&device,
-        pma_peek peek = pma_peek_error) :
-        m_description{std::move(description)},
-        m_start{start},
-        m_length{length},
-        m_index{PMA_MAX},
-        m_flags{},
-        m_peek{peek},
-        m_data{std::move(device)} {
-        ;
-    }
-
-    /// \brief Set PMA entry index in target.
-    void set_index(int index) {
-        m_index = index;
-    }
-
-    /// \brief Returns PMA entry index in target.
-    int get_index() const {
-        return m_index;
-    }
-
-    /// \brief Set flags for lvalue references
-    /// \param f New flags.
-    pma_entry &set_flags(flags f) & {
-        m_flags = f;
-        return *this;
-    }
-
-    /// \brief Set flags for rvalue references
-    /// \param f New flags.
-    pma_entry &&set_flags(flags f) && {
-        m_flags = f;
-        return std::move(*this);
-    }
-
-    /// \brief Get flags
-    /// \return Flags
-    flags get_flags() const {
-        return m_flags;
-    }
-
-    /// \brief Returns the peek callback for the range.
-    pma_peek get_peek() const {
-        return m_peek;
-    }
-
-    /// \returns data specific to M ranges
-    const pma_memory &get_memory() const {
-        return std::get<pma_memory>(m_data);
-    }
-
-    /// \returns data specific to M ranges
-    pma_memory &get_memory() {
-        return std::get<pma_memory>(m_data);
-    }
-
-    /// \returns data specific to memory ranges (cannot throw exceptions, but will crash if not a memory range).
-    pma_memory &get_memory_noexcept() {
-        return *std::get_if<pma_memory>(&m_data);
-    }
-
-    /// \returns data specific to memory ranges (cannot throw exceptions, but will crash if not a memory range).
-    const pma_memory &get_memory_noexcept() const {
-        return *std::get_if<pma_memory>(&m_data);
-    }
-
-    /// \returns data specific to IO ranges
-    const pma_device &get_device() const {
-        return std::get<pma_device>(m_data);
-    }
-
-    /// \returns data specific to IO ranges
-    pma_device &get_device() {
-        return std::get<pma_device>(m_data);
-    }
-
-    /// \returns data specific to IO ranges (cannot throw exceptions, but will crash if not an IO range).
-    const pma_device &get_device_noexcept() const {
-        return *std::get_if<pma_device>(&m_data);
-    }
-
-    /// \returns data specific to IO ranges (cannot throw exceptions, but will crash if not an IO range).
-    pma_device &get_device_noexcept() {
-        return *std::get_if<pma_device>(&m_data);
-    }
-
-    /// \brief Returns packed PMA istart field as per whitepaper
-    uint64_t get_istart() const;
-
-    /// \brief Returns start of physical memory range in target.
-    uint64_t get_start() const {
-        return m_start;
-    }
-    /// \brief Returns length of physical memory range in target.
-    uint64_t get_length() const {
-        return m_length;
-    }
-
-    /// \brief Returns encoded PMA ilength field as per whitepaper
-    uint64_t get_ilength() const;
-
-    /// \brief Tells if PMA is a memory range
-    bool get_istart_M() const {
-        return std::holds_alternative<pma_memory>(m_data);
-    }
-
-    /// \brief Tells if PMA is a device range
-    bool get_istart_IO() const {
-        return std::holds_alternative<pma_device>(m_data);
-    }
-
-    /// \brief Tells if PMA is an empty range
-    bool get_istart_E() const {
-        return std::holds_alternative<std::monostate>(m_data);
-    }
-
-    /// \brief Tells if PMA range is readable
-    bool get_istart_R() const {
-        return m_flags.R;
-    }
-
-    /// \brief Tells if PMA range is writable
-    bool get_istart_W() const {
-        return m_flags.W;
-    }
-
-    /// \brief Tells if PMA range is executable
-    bool get_istart_X() const {
-        return m_flags.X;
-    }
-
-    /// \brief Tells if reads to PMA range are idempotent
-    bool get_istart_IR() const {
-        return m_flags.IR;
-    }
-
-    /// \brief Tells if writes to PMA range are idempotent
-    bool get_istart_IW() const {
-        return m_flags.IW;
-    }
-
-    /// \brief Returns the id of the device that owns the range
-    PMA_ISTART_DID get_istart_DID() const {
-        return m_flags.DID;
-    }
-
-    /// \brief Mark a given page as dirty
-    /// \param offset_in_range Any offset in range within desired page
-    void mark_dirty_page(uint64_t offset_in_range) {
-        if (!m_dirty_page_map.empty()) {
-            auto page_index = offset_in_range >> PMA_constants::PMA_PAGE_SIZE_LOG2;
-            auto map_index = page_index >> 3;
-            assert(map_index < m_dirty_page_map.size());
-            m_dirty_page_map[map_index] |= (1 << (page_index & 7));
-        }
-    }
-
-    /// \brief Mark all pages in rage as dirty
-    /// \param address Start address
-    /// \param size Size of range
-    void mark_dirty_pages(uint64_t address, uint64_t size) {
-        if (m_dirty_page_map.empty()) {
-            return;
-        }
-        if (!get_istart_M() || get_istart_E()) {
-            throw std::invalid_argument{"address range not entirely in memory PMA"};
-        }
-        if (!contains(address, size)) {
-            throw std::invalid_argument{"range not contained in pma"};
-        }
-        constexpr const auto log2_page_size = PMA_constants::PMA_PAGE_SIZE_LOG2;
-        uint64_t page_in_range = ((address - get_start()) >> log2_page_size) << log2_page_size;
-        constexpr const auto page_size = PMA_constants::PMA_PAGE_SIZE;
-        auto npages = (size + page_size - 1) / page_size;
-        for (decltype(npages) i = 0; i < npages; ++i) {
-            mark_dirty_page(page_in_range);
-            page_in_range += page_size;
-        }
-    }
-
-    /// \brief Mark a given page as clean
-    /// \param offset_in_range Any offset in range within desired page
-    void mark_clean_page(uint64_t offset_in_range) {
-        if (!m_dirty_page_map.empty()) {
-            auto page_index = offset_in_range >> PMA_constants::PMA_PAGE_SIZE_LOG2;
-            auto map_index = page_index >> 3;
-            assert(map_index < m_dirty_page_map.size());
-            m_dirty_page_map[map_index] &= ~(1 << (page_index & 7));
-        }
-    }
-
-    /// \brief Checks if a given page is marked dirty
-    /// \param offset_in_range Any offset in range within desired page
-    /// \returns true if dirty, false if clean
-    bool is_page_marked_dirty(uint64_t offset_in_range) const {
-        if (!m_dirty_page_map.empty()) {
-            auto page_index = offset_in_range >> PMA_constants::PMA_PAGE_SIZE_LOG2;
-            auto map_index = page_index >> 3;
-            assert(map_index < m_dirty_page_map.size());
-            return (m_dirty_page_map[map_index] & (1 << (page_index & 7))) != 0;
-        }
-        return true;
-    }
-
-    /// \brief Marks all pages in range as clean
-    void mark_pages_clean() {
-        std::fill(m_dirty_page_map.begin(), m_dirty_page_map.end(), 0);
-    }
-
-    /// \brief Returns PMA description as a string
-    /// \returns Description
-    const std::string &get_description() const {
-        return m_description;
-    }
-
-    /// \brief Checks if a memory range is within this PMA boundaries
-    /// \param address Address
-    /// \param length Length
-    /// \return true if this PMA contains the given range
-    bool contains(uint64_t address, uint64_t length) const {
-        if (get_istart_E()) {
-            return false;
-        }
-        return address >= get_start() && get_length() >= length && address - get_start() <= get_length() - length;
-    }
-
-    /// \brief Writes data to pma memory
-    /// \param paddr Destination address within pma range
-    /// \param data Source data
-    /// \param size Data size
-    void write_memory(uint64_t paddr, const unsigned char *data, uint64_t size);
-
-    /// \brief  Fills pma memory with a given value
-    /// \param paddr Destination address within pma range
-    /// \param value Value to write
-    /// \param size Data size
-    void fill_memory(uint64_t paddr, unsigned char value, uint64_t size);
+/// \brief Physical memory attributes.
+
+static constexpr const char *pma_get_DID_name(PMA_ISTART_DID did) {
+    switch (did) {
+        case PMA_ISTART_DID::memory:
+            return "DID.memory";
+        case PMA_ISTART_DID::shadow_state:
+            return "DID.shadow_state";
+        case PMA_ISTART_DID::shadow_pmas:
+            return "DID.shadow_pmas";
+        case PMA_ISTART_DID::shadow_TLB:
+            return "DID.shadow_TLB";
+        case PMA_ISTART_DID::flash_drive:
+            return "DID.flash_drive";
+        case PMA_ISTART_DID::CLINT:
+            return "DID.CLINT";
+        case PMA_ISTART_DID::PLIC:
+            return "DID.PLIC";
+        case PMA_ISTART_DID::HTIF:
+            return "DID.HTIF";
+        case PMA_ISTART_DID::VIRTIO:
+            return "DID.VIRTIO";
+        case PMA_ISTART_DID::cmio_rx_buffer:
+            return "DID.cmio_rx_buffer";
+        case PMA_ISTART_DID::cmio_tx_buffer:
+            return "DID.cmio_tx_buffer";
+        case PMA_ISTART_DID::shadow_uarch_state:
+            return "DID.shadow_uarch";
+        default:
+            return "DID.unknown";
+    }
+}
+
+///< Unpacked attribute flags
+struct pma_flags {
+    bool M;             ///< is memory
+    bool IO;            ///< is device
+    bool E;             ///< is empty
+    bool R;             ///< is readable
+    bool W;             ///< is writeable
+    bool X;             ///< is executable
+    bool IR;            ///< is read-idempotent
+    bool IW;            ///< is write-idempotent
+    PMA_ISTART_DID DID; ///< driver id
+
+    // Defaulted comparison operator
+    bool operator==(const pma_flags &) const = default;
 };
 
-/// \brief Creates a PMA entry for a new memory range initially filled with zeros.
-/// \param description Informative description of PMA entry for use in error messages
-/// \param start Start of PMA range.
-/// \param length Length of PMA range.
-/// \returns Corresponding PMA entry
-pma_entry make_callocd_memory_pma_entry(const std::string &description, uint64_t start, uint64_t length);
-
-/// \brief Creates a PMA entry for a new memory range initially filled with the contents of a backing file.
-/// \param description Informative description of PMA entry for use in error messages
-/// \param start Start of PMA range.
-/// \param length Length of PMA range.
-/// \param path Path to backing file.
-/// \returns Corresponding PMA entry
-pma_entry make_callocd_memory_pma_entry(const std::string &description, uint64_t start, uint64_t length,
-    const std::string &path);
-
-/// \brief Creates a PMA entry for a new memory region using the host's
-/// mmap functionality.
-/// \param description Informative description of PMA entry for use in error messages
-/// \param start Start of physical memory range in the target address
-/// space on which to map the memory region.
-/// \param length Length of physical memory range in the
-/// target address space on which to map the memory region.
-/// \param path Reference to a string containing the filename
-/// for the backing file in the host with the contents of the memory region.
-/// \param shared Whether target modifications to the memory region are
-/// reflected in the host's backing file.
-/// \returns Corresponding PMA entry
-/// \details \p length must match the size of the backing file.
-/// This function is typically used to map flash drives.
-pma_entry make_mmapd_memory_pma_entry(const std::string &description, uint64_t start, uint64_t length,
-    const std::string &path, bool shared);
-
-/// \brief Creates a PMA entry for a new memory-mapped IO device.
-/// \param description Informative description of PMA entry for use in error messages
-/// \param start Start of physical memory range in the target address
-/// space on which to map the device.
-/// \param length Length of physical memory range in the
-/// target address space on which to map the device.
-/// \param peek Peek callback for the range.
-/// \param driver Pointer to driver with callbacks.
-/// \param context Pointer to context to be passed to callbacks.
-/// \returns Corresponding PMA entry
-pma_entry make_device_pma_entry(const std::string &description, uint64_t start, uint64_t length, pma_peek peek,
-    const pma_driver *driver, void *context = nullptr);
-
-/// \brief Creates an empty PMA entry.
-/// \param description Informative description of PMA entry for use in error messages
-/// \param start Start of physical memory range in the target address
-/// space on which to map the device.
-/// \param length Length of physical memory range in the
-/// target address space on which to map the device.
-/// \returns Corresponding PMA entry
-pma_entry make_empty_pma_entry(const std::string &description, uint64_t start, uint64_t length);
+static constexpr pma_flags unpack_pma_istart(uint64_t istart, uint64_t &start) {
+    start = istart & PMA_ISTART_START_MASK;
+    return pma_flags{.M = ((istart & PMA_ISTART_M_MASK) >> PMA_ISTART_M_SHIFT) != 0,
+        .IO = ((istart & PMA_ISTART_IO_MASK) >> PMA_ISTART_IO_SHIFT) != 0,
+        .E = ((istart & PMA_ISTART_E_MASK) >> PMA_ISTART_E_SHIFT) != 0,
+        .R = ((istart & PMA_ISTART_R_MASK) >> PMA_ISTART_R_SHIFT) != 0,
+        .W = ((istart & PMA_ISTART_W_MASK) >> PMA_ISTART_W_SHIFT) != 0,
+        .X = ((istart & PMA_ISTART_X_MASK) >> PMA_ISTART_X_SHIFT) != 0,
+        .IR = ((istart & PMA_ISTART_IR_MASK) >> PMA_ISTART_IR_SHIFT) != 0,
+        .IW = ((istart & PMA_ISTART_IW_MASK) >> PMA_ISTART_IW_SHIFT) != 0,
+        .DID = static_cast<PMA_ISTART_DID>((istart & PMA_ISTART_DID_MASK) >> PMA_ISTART_DID_SHIFT)};
+}
+
+static constexpr uint64_t pack_pma_istart(const pma_flags &flags, uint64_t start) {
+    uint64_t istart = start;
+    istart |= (static_cast<uint64_t>(flags.M) << PMA_ISTART_M_SHIFT);
+    istart |= (static_cast<uint64_t>(flags.IO) << PMA_ISTART_IO_SHIFT);
+    istart |= (static_cast<uint64_t>(flags.E) << PMA_ISTART_E_SHIFT);
+    istart |= (static_cast<uint64_t>(flags.R) << PMA_ISTART_R_SHIFT);
+    istart |= (static_cast<uint64_t>(flags.W) << PMA_ISTART_W_SHIFT);
+    istart |= (static_cast<uint64_t>(flags.X) << PMA_ISTART_X_SHIFT);
+    istart |= (static_cast<uint64_t>(flags.IR) << PMA_ISTART_IR_SHIFT);
+    istart |= (static_cast<uint64_t>(flags.IW) << PMA_ISTART_IW_SHIFT);
+    istart |= (static_cast<uint64_t>(flags.DID) << PMA_ISTART_DID_SHIFT);
+    return istart;
+}
 
 } // namespace cartesi
 
diff --git a/src/pristine-address-range.h b/src/pristine-address-range.h
new file mode 100644
index 000000000..f59a6aae5
--- /dev/null
+++ b/src/pristine-address-range.h
@@ -0,0 +1,59 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef PRISTINE_ADDRESS_RANGE_H
+#define PRISTINE_ADDRESS_RANGE_H
+
+#include "address-range.h"
+
+namespace cartesi {
+
+// Forward declarations
+class machine;
+
+/// \file
+/// \brief An address range that appears pristine in the state
+
+class pristine_address_range : public address_range {
+public:
+    /// \brief Constructor
+    /// \param description Description of address range for use in error messages
+    /// \param start Target physical address where range starts
+    /// \param length Length of range, in bytes
+    /// \param f Phyical memory attribute flags for range
+    template <typename ABRT>
+    pristine_address_range(const char *description, uint64_t start, uint64_t length, pma_flags f, ABRT abrt) :
+        address_range{description, start, length, f, abrt} {
+        ;
+    }
+
+    pristine_address_range(const pristine_address_range &other) = default;
+    pristine_address_range &operator=(const pristine_address_range &other) = default;
+    pristine_address_range(pristine_address_range &&other) = default;
+    pristine_address_range &operator=(pristine_address_range &&other) = default;
+    ~pristine_address_range() override = default;
+
+private:
+    bool do_peek(const machine & /*m*/, uint64_t offset, uint64_t length, const unsigned char **data,
+        unsigned char * /*scratch*/) const noexcept override {
+        *data = nullptr;
+        return contains_relative(offset, length);
+    }
+};
+
+} // namespace cartesi
+
+#endif
diff --git a/src/record-send-cmio-state-access.h b/src/record-send-cmio-state-access.h
index 03f09ea2f..575957d7b 100644
--- a/src/record-send-cmio-state-access.h
+++ b/src/record-send-cmio-state-access.h
@@ -35,18 +35,12 @@
 #include "machine-state.h"
 #include "machine.h"
 #include "meta.h"
-#include "pma.h"
 #include "shadow-state.h"
 
 namespace cartesi {
 
 class record_send_cmio_state_access;
 
-// Type trait that should return the pma_entry type for a state access class
-template <>
-struct i_state_access_pma_entry<record_send_cmio_state_access> {
-    using type = pma_entry;
-};
 // Type trait that should return the fast_addr type for a state access class
 template <>
 struct i_state_access_fast_addr<record_send_cmio_state_access> {
@@ -218,9 +212,9 @@ class record_send_cmio_state_access :
             throw std::invalid_argument("write_length is less than data_length");
         }
         // We need to compute the hash of the existing data before writing
-        // Find the target pma entry
-        auto &pma = m_m.find_pma_entry(paddr, write_length);
-        if (pma.get_istart_E()) {
+        // Find the target address range
+        auto &ar = m_m.find_address_range(paddr, write_length);
+        if (!ar.is_memory()) {
             throw std::invalid_argument("address range not entirely in memory PMA");
         }
         access a{};
@@ -236,7 +230,7 @@ class record_send_cmio_state_access :
         a.set_read_hash(proof.get_target_hash());
         if (m_log.get_log_type().has_large_data()) {
             access_data &data = a.get_read().emplace(write_length);
-            memcpy(data.data(), pma.get_memory().get_host_memory(), write_length);
+            memcpy(data.data(), ar.get_host_memory(), write_length);
         }
 
         // We just store the sibling hashes in the access because this is the only missing piece of data needed to
@@ -245,21 +239,23 @@ class record_send_cmio_state_access :
 
         // write data to memory
         m_m.write_memory(paddr, data, data_length);
+
         if (write_length > data_length) {
             m_m.fill_memory(paddr + data_length, 0, write_length - data_length);
         }
         // we have to update the merkle tree after every write
         m_m.update_merkle_tree();
+
         // log hash and written data
         // NOLINTBEGIN(bugprone-unchecked-optional-access)
         a.get_written_hash().emplace();
         hasher_type hasher{};
-        const auto offset = paddr - pma.get_start();
-        get_merkle_tree_hash(hasher, pma.get_memory().get_host_memory() + offset, write_length,
+        const auto offset = paddr - ar.get_start();
+        get_merkle_tree_hash(hasher, ar.get_host_memory() + offset, write_length,
             machine_merkle_tree::get_word_size(), a.get_written_hash().value());
         if (m_log.get_log_type().has_large_data()) {
             access_data &data = a.get_written().emplace(write_length);
-            memcpy(data.data(), pma.get_memory().get_host_memory() + offset, write_length);
+            memcpy(data.data(), ar.get_host_memory() + offset, write_length);
         }
         // NOLINTEND(bugprone-unchecked-optional-access)
         m_log.push_access(a, "cmio rx buffer");
diff --git a/src/record-step-state-access.h b/src/record-step-state-access.h
index d747ed7ff..710b3328a 100644
--- a/src/record-step-state-access.h
+++ b/src/record-step-state-access.h
@@ -17,6 +17,7 @@
 #ifndef RECORD_STEP_STATE_ACCESS_H
 #define RECORD_STEP_STATE_ACCESS_H
 
+#include <cassert>
 #include <map>
 #include <optional>
 #include <vector>
@@ -26,7 +27,7 @@
 #include "i-prefer-shadow-state.h"
 #include "i-state-access.h"
 #include "machine.h"
-#include "shadow-pmas.h"
+#include "shadow-pmas-address-range.h"
 #include "shadow-tlb.h"
 #include "unique-c-ptr.h"
 
@@ -34,11 +35,6 @@ namespace cartesi {
 
 class record_step_state_access;
 
-// Type trait that should return the pma_entry type for a state access class
-template <>
-struct i_state_access_pma_entry<record_step_state_access> {
-    using type = pma_entry;
-};
 // Type trait that should return the fast_addr type for a state access class
 template <>
 struct i_state_access_fast_addr<record_step_state_access> {
@@ -131,7 +127,6 @@ class record_step_state_access :
     }
 
 private:
-    using pma_entry_type = pma_entry;
     using fast_addr_type = host_addr;
 
     /// \brief Mark a page as touched and save its contents
@@ -235,15 +230,14 @@ class record_step_state_access :
         throw std::runtime_error("unexpected call to record_step_state_access::write_memory");
     }
 
-    pma_entry &do_read_pma_entry(uint64_t index) const {
+    address_range &do_read_pma(uint64_t index) const {
         assert(index < PMA_MAX);
-        // replay_step_state_access reconstructs a mock_pma_entry from the
+        // replay_step_state_access reconstructs a mock_address_range from the
         // corresponding istart and ilength fields in the shadow pmas
         // so we mark the page where they live here
         touch_page(shadow_pmas_get_pma_abs_addr(index, shadow_pmas_what::istart));
         touch_page(shadow_pmas_get_pma_abs_addr(index, shadow_pmas_what::ilength));
-        // NOLINTNEXTLINE(bugprone-narrowing-conversions)
-        return m_m.get_state().pmas[static_cast<int>(index)];
+        return m_m.read_pma(index);
     }
 
     template <typename T, typename A>
diff --git a/src/replay-send-cmio-state-access.h b/src/replay-send-cmio-state-access.h
index 57354d237..f22449b05 100644
--- a/src/replay-send-cmio-state-access.h
+++ b/src/replay-send-cmio-state-access.h
@@ -20,7 +20,6 @@
 /// \file
 /// \brief State access implementation that replays recorded state accesses
 
-#include <cassert>
 #include <cstdint>
 #include <cstring>
 #include <ios>
@@ -34,7 +33,6 @@
 #include "i-state-access.h"
 #include "machine-merkle-tree.h"
 #include "meta.h"
-#include "mock-pma-entry.h"
 #include "riscv-constants.h"
 #include "shadow-state.h"
 #include "unique-c-ptr.h"
@@ -43,11 +41,6 @@ namespace cartesi {
 
 class replay_send_cmio_state_access;
 
-// Type trait that should return the pma_entry type for a state access class
-template <>
-struct i_state_access_pma_entry<replay_send_cmio_state_access> {
-    using type = mock_pma_entry;
-};
 // Type trait that should return the fast_addr type for a state access class
 template <>
 struct i_state_access_fast_addr<replay_send_cmio_state_access> {
diff --git a/src/replay-step-state-access.h b/src/replay-step-state-access.h
index 338965c3c..baf0e6ec6 100644
--- a/src/replay-step-state-access.h
+++ b/src/replay-step-state-access.h
@@ -17,6 +17,7 @@
 #ifndef REPLAY_STEP_STATE_ACCESS_H
 #define REPLAY_STEP_STATE_ACCESS_H
 
+#include <cassert>
 #include <cstdlib>
 #include <optional>
 
@@ -25,11 +26,11 @@
 #include "i-accept-scoped-notes.h"
 #include "i-prefer-shadow-state.h"
 #include "i-state-access.h"
-#include "mock-pma-entry.h"
+#include "mock-address-range.h"
 #include "pma-constants.h"
 #include "replay-step-state-access-interop.h"
 #include "riscv-constants.h"
-#include "shadow-pmas.h"
+#include "shadow-pmas-address-range.h"
 #include "shadow-state.h"
 #include "shadow-tlb.h"
 #include "shadow-uarch-state.h"
@@ -44,11 +45,6 @@ namespace cartesi {
 
 class replay_step_state_access;
 
-// Type trait that should return the pma_entry type for a state access class
-template <>
-struct i_state_access_pma_entry<replay_step_state_access> {
-    using type = mock_pma_entry;
-};
 // Type trait that should return the fast_addr type for a state access class
 template <>
 struct i_state_access_fast_addr<replay_step_state_access> {
@@ -92,11 +88,11 @@ class replay_step_state_access :
     };
 
     struct context {
-        uint64_t page_count{0};                                    ///< Number of pages in the step log
-        page_type *pages{nullptr};                                 ///< Array of page data
-        uint64_t sibling_count{0};                                 ///< Number of sibling hashes in the step log
-        hash_type *sibling_hashes{nullptr};                        ///< Array of sibling hashes
-        std::array<std::optional<mock_pma_entry>, PMA_MAX> pmas{}; ///< Array of PMA entries
+        uint64_t page_count{0};             ///< Number of pages in the step log
+        page_type *pages{nullptr};          ///< Array of page data
+        uint64_t sibling_count{0};          ///< Number of sibling hashes in the step log
+        hash_type *sibling_hashes{nullptr}; ///< Array of sibling hashes
+        mock_address_ranges ars{};          ///< Array of address ranges
     };
 
 private:
@@ -464,7 +460,7 @@ class replay_step_state_access :
         return false;
     }
 
-    mock_pma_entry &do_read_pma_entry(uint64_t index) const {
+    address_range &do_read_pma(uint64_t index) const {
         assert(index < PMA_MAX);
         // record_step_state_access will have recorded the access to istart and
         // ilength in its implementation of read_pma_entry.
@@ -472,12 +468,12 @@ class replay_step_state_access :
         const uint64_t ilength = read_pma_ilength(index);
         // NOLINTNEXTLINE(bugprone-narrowing-conversions)
         const int i = static_cast<int>(index);
-        if (!m_context.pmas[i]) {
-            m_context.pmas[i] =
-                make_mock_pma_entry(index, istart, ilength, [](const char *err) { interop_throw_runtime_error(err); });
+        const auto abrt = [](const char *err) { interop_throw_runtime_error(err); };
+        if (std::holds_alternative<std::monostate>(m_context.ars[i])) {
+            m_context.ars[i] = make_mock_address_range(istart, ilength, abrt);
         }
         // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
-        return m_context.pmas[index].value();
+        return get_mock_address_range(m_context.ars[index], abrt);
     }
 
     template <typename T, typename A>
diff --git a/src/riscv-constants.h b/src/riscv-constants.h
index c298ac510..8d2ffca82 100644
--- a/src/riscv-constants.h
+++ b/src/riscv-constants.h
@@ -21,7 +21,6 @@
 
 #include "machine-c-version.h"
 #include "pma-constants.h"
-#include "pma-defines.h"
 
 /// \file
 /// \brief RISC-V constants
@@ -441,38 +440,38 @@ enum CARTESI_init : uint64_t {
     MTVAL_INIT = UINT64_C(0),                                                          ///< Initial value for mtval
     MISA_INIT = (MISA_MXL_VALUE << MISA_MXL_SHIFT) | MISA_EXT_S_MASK | MISA_EXT_U_MASK | MISA_EXT_I_MASK |
         MISA_EXT_M_MASK | MISA_EXT_A_MASK | MISA_EXT_F_MASK | MISA_EXT_D_MASK |
-        MISA_EXT_C_MASK,                ///< Initial value for misa
-    MIE_INIT = UINT64_C(0),             ///< Initial value for mie
-    MIP_INIT = UINT64_C(0),             ///< Initial value for mip
-    MEDELEG_INIT = UINT64_C(0),         ///< Initial value for medeleg
-    MIDELEG_INIT = UINT64_C(0),         ///< Initial value for mideleg
-    MCOUNTEREN_INIT = UINT64_C(0),      ///< Initial value for mcounteren
-    STVEC_INIT = UINT64_C(0),           ///< Initial value for stvec
-    SSCRATCH_INIT = UINT64_C(0),        ///< Initial value for sscratch
-    SEPC_INIT = UINT64_C(0),            ///< Initial value for sepc
-    SCAUSE_INIT = UINT64_C(0),          ///< Initial value for scause
-    STVAL_INIT = UINT64_C(0),           ///< Initial value for stval
-    SATP_INIT = UINT64_C(0),            ///< Initial value for satp
-    SCOUNTEREN_INIT = UINT64_C(0),      ///< Initial value for scounteren
-    ILRSC_INIT = UINT64_C(-1),          ///< Initial value for ilrsc
-    IPRV_INIT = PRV_M,                  ///< Initial value for iprv
-    IFLAGS_X_INIT = UINT64_C(0),        ///< Initial value for iflags_X
-    IFLAGS_Y_INIT = UINT64_C(0),        ///< Initial value for iflags_Y
-    IFLAGS_H_INIT = UINT64_C(0),        ///< Initial value for iflags_H
-    IUNREP_INIT = UINT64_C(0),          ///< Initial value for iunrep
-    MTIMECMP_INIT = UINT64_C(0),        ///< Initial value for mtimecmp
-    GIRQPEND_INIT = UINT64_C(0),        ///< Initial value for girqpend
-    GIRQSRVD_INIT = UINT64_C(0),        ///< Initial value for girqsrvd
-    FROMHOST_INIT = UINT64_C(0),        ///< Initial value for fromhost
-    TOHOST_INIT = UINT64_C(0),          ///< Initial value for tohost
-    MENVCFG_INIT = UINT64_C(0),         ///< Initial value for menvcfg
-    SENVCFG_INIT = UINT64_C(0),         ///< Initial value for senvcfg
-    UARCH_HALT_FLAG_INIT = UINT64_C(0), ///< Initial value for microarchitecture halt flag
-    UARCH_X_INIT = UINT64_C(0),         ///< Initial value for microarchitecture general purpose register x
-    UARCH_PC_INIT = EXPAND_UINT64_C(PMA_UARCH_RAM_START_DEF), ///< Initial value for microarchitecture pc
-    UARCH_CYCLE_INIT = UINT64_C(0),                           ///< Initial value for microarchitecture cycle
-    MHARTID_INIT = UINT64_C(0),                               ///< Initial mhartid
-    FDTADDR_INIT = PMA_DTB_START,                             ///< Initial FDT address
+        MISA_EXT_C_MASK,                 ///< Initial value for misa
+    MIE_INIT = UINT64_C(0),              ///< Initial value for mie
+    MIP_INIT = UINT64_C(0),              ///< Initial value for mip
+    MEDELEG_INIT = UINT64_C(0),          ///< Initial value for medeleg
+    MIDELEG_INIT = UINT64_C(0),          ///< Initial value for mideleg
+    MCOUNTEREN_INIT = UINT64_C(0),       ///< Initial value for mcounteren
+    STVEC_INIT = UINT64_C(0),            ///< Initial value for stvec
+    SSCRATCH_INIT = UINT64_C(0),         ///< Initial value for sscratch
+    SEPC_INIT = UINT64_C(0),             ///< Initial value for sepc
+    SCAUSE_INIT = UINT64_C(0),           ///< Initial value for scause
+    STVAL_INIT = UINT64_C(0),            ///< Initial value for stval
+    SATP_INIT = UINT64_C(0),             ///< Initial value for satp
+    SCOUNTEREN_INIT = UINT64_C(0),       ///< Initial value for scounteren
+    ILRSC_INIT = UINT64_C(-1),           ///< Initial value for ilrsc
+    IPRV_INIT = PRV_M,                   ///< Initial value for iprv
+    IFLAGS_X_INIT = UINT64_C(0),         ///< Initial value for iflags_X
+    IFLAGS_Y_INIT = UINT64_C(0),         ///< Initial value for iflags_Y
+    IFLAGS_H_INIT = UINT64_C(0),         ///< Initial value for iflags_H
+    IUNREP_INIT = UINT64_C(0),           ///< Initial value for iunrep
+    MTIMECMP_INIT = UINT64_C(0),         ///< Initial value for mtimecmp
+    GIRQPEND_INIT = UINT64_C(0),         ///< Initial value for girqpend
+    GIRQSRVD_INIT = UINT64_C(0),         ///< Initial value for girqsrvd
+    FROMHOST_INIT = UINT64_C(0),         ///< Initial value for fromhost
+    TOHOST_INIT = UINT64_C(0),           ///< Initial value for tohost
+    MENVCFG_INIT = UINT64_C(0),          ///< Initial value for menvcfg
+    SENVCFG_INIT = UINT64_C(0),          ///< Initial value for senvcfg
+    UARCH_HALT_FLAG_INIT = UINT64_C(0),  ///< Initial value for microarchitecture halt flag
+    UARCH_X_INIT = UINT64_C(0),          ///< Initial value for microarchitecture general purpose register x
+    UARCH_PC_INIT = PMA_UARCH_RAM_START, ///< Initial value for microarchitecture pc
+    UARCH_CYCLE_INIT = UINT64_C(0),      ///< Initial value for microarchitecture cycle
+    MHARTID_INIT = UINT64_C(0),          ///< Initial mhartid
+    FDTADDR_INIT = PMA_DTB_START,        ///< Initial FDT address
 
     // Registers
     REG_X0 = UINT64_C(0), //< zero - hardwired zero
diff --git a/src/shadow-peek.h b/src/shadow-peek.h
index 9275edfda..8d094bc80 100644
--- a/src/shadow-peek.h
+++ b/src/shadow-peek.h
@@ -18,35 +18,34 @@
 #define SHADOW_PEEK_H
 
 #include <cstdint>
-#include <cstring>
-
-#include "machine-reg.h"
-#include "machine.h"
-#include "pma.h"
 
 namespace cartesi {
 
+// Forward declarations
+class machine;
+class address_range;
+
 /// \file
 /// \brief Peeks part of a shadow
 template <typename READ_REG_F>
-static bool shadow_peek(READ_REG_F read_reg, const pma_entry &pma, const machine &m, uint64_t offset, uint64_t length,
-    const unsigned char **data, unsigned char *scratch) {
+static bool shadow_peek(READ_REG_F read_reg, const address_range &ar, const machine &m, uint64_t offset,
+    uint64_t length, const unsigned char **data, unsigned char *scratch) {
     // Must be inside range
-    if (!pma.contains(pma.get_start() + offset, length)) {
+    if (!ar.contains_relative(offset, length)) {
         *data = nullptr;
         return false;
     }
     // Initial, potentially partial register read
     const uint64_t offset_aligned = offset & ~(sizeof(uint64_t) - 1);
     if (offset > offset_aligned) {
-        const auto val = read_reg(m, pma.get_start() + offset_aligned);
+        const auto val = read_reg(m, ar.get_start() + offset_aligned);
         const auto partial = offset - offset_aligned;
         memcpy(scratch, &val, partial);
         length -= partial;
         offset += partial;
     }
     // Now we are aligned, do all complete registers
-    const uint64_t paddr_start = pma.get_start() + offset;
+    const uint64_t paddr_start = ar.get_start() + offset;
     const uint64_t length_aligned = length & ~(sizeof(uint64_t) - 1);
     const uint64_t paddr_end = paddr_start + length_aligned;
     for (uint64_t paddr = paddr_start; paddr < paddr_end; paddr += sizeof(uint64_t)) {
diff --git a/src/shadow-pmas-factory.cpp b/src/shadow-pmas-address-range.h
similarity index 63%
rename from src/shadow-pmas-factory.cpp
rename to src/shadow-pmas-address-range.h
index 251660213..fd380a342 100644
--- a/src/shadow-pmas-factory.cpp
+++ b/src/shadow-pmas-address-range.h
@@ -14,23 +14,36 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#include "shadow-pmas-factory.h"
+#ifndef SHADOW_PMAS_ADDRESS_RANGE_H
+#define SHADOW_PMAS_ADDRESS_RANGE_H
 
 #include <cstdint>
+#include <stdexcept>
 
+#include "memory-address-range.h"
 #include "pma-constants.h"
-#include "pma.h"
+#include "shadow-pmas.h"
+
+/// \file
+/// \brief Shadow device.
 
 namespace cartesi {
 
-pma_entry make_shadow_pmas_pma_entry(uint64_t start, uint64_t length) {
-    const pma_entry::flags f{.R = true,
+static inline auto make_shadow_pmas_address_range(uint64_t start, uint64_t length) {
+    static constexpr pma_flags shadow_pmas_flags{
+        .M = true,
+        .IO = false,
+        .E = false,
+        .R = true,
         .W = false,
         .X = false,
         .IR = false,
         .IW = false,
-        .DID = PMA_ISTART_DID::shadow_pmas};
-    return make_callocd_memory_pma_entry("shadow PMAs", start, length).set_flags(f);
+        .DID = PMA_ISTART_DID::shadow_pmas,
+    };
+    return make_callocd_memory_address_range("shadow PMAs", start, length, shadow_pmas_flags);
 }
 
 } // namespace cartesi
+
+#endif
diff --git a/src/shadow-pmas-factory.h b/src/shadow-pmas-factory.h
deleted file mode 100644
index f911a8ec6..000000000
--- a/src/shadow-pmas-factory.h
+++ /dev/null
@@ -1,49 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef SHADOW_PMAS_FACTORY_H
-#define SHADOW_PMAS_FACTORY_H
-
-#include <cstdint>
-
-/// \file
-/// \brief Shadow device.
-
-#include "pma.h"
-#include "shadow-pmas.h"
-
-namespace cartesi {
-
-pma_entry make_shadow_pmas_pma_entry(uint64_t start, uint64_t length);
-
-template <typename PMAS>
-void shadow_pmas_init(const PMAS &pmas, shadow_pmas_state *shadow) {
-    static_assert(sizeof(shadow_pmas_state) == PMA_MAX * 2 * sizeof(uint64_t), "inconsistent shadow PMAs length");
-    static_assert(PMA_SHADOW_PMAS_LENGTH >= sizeof(shadow_pmas_state), "shadow PMAs not long enough");
-    if (pmas.size() > PMA_MAX) {
-        throw std::invalid_argument{"more PMAs than shadow PMAs can hold"};
-    }
-    unsigned index = 0;
-    for (const auto &pma : pmas) {
-        (*shadow)[index].istart = pma.get_istart();
-        (*shadow)[index].ilength = pma.get_ilength();
-        ++index;
-    }
-}
-
-} // namespace cartesi
-
-#endif
diff --git a/src/shadow-pmas.h b/src/shadow-pmas.h
index 95f5837e7..6e7ea2fca 100644
--- a/src/shadow-pmas.h
+++ b/src/shadow-pmas.h
@@ -18,12 +18,10 @@
 #define SHADOW_PMAS_H
 
 #include <array>
-#include <cassert>
 #include <cstdint>
 
 #include "compiler-defines.h"
 #include "pma-constants.h"
-#include "pma-driver.h"
 
 /// \file
 /// \brief Shadow device.
diff --git a/src/shadow-state-factory.cpp b/src/shadow-state-address-range.cpp
similarity index 63%
rename from src/shadow-state-factory.cpp
rename to src/shadow-state-address-range.cpp
index 959e745e3..d2944946c 100644
--- a/src/shadow-state-factory.cpp
+++ b/src/shadow-state-address-range.cpp
@@ -14,26 +14,22 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#include "shadow-state-factory.h"
+#include "shadow-state-address-range.h"
 
 #include <cstdint>
 
 #include "machine-reg.h"
 #include "machine.h"
-#include "pma-constants.h"
-#include "pma.h"
 #include "shadow-peek.h"
-#include "shadow-state.h"
 
 namespace cartesi {
 
-/// \brief Shadow device peek callback. See ::pma_peek.
-static bool shadow_state_peek(const pma_entry &pma, const machine &m, uint64_t offset, uint64_t length,
-    const unsigned char **data, unsigned char *scratch) {
+bool shadow_state_address_range::do_peek(const machine &m, uint64_t offset, uint64_t length, const unsigned char **data,
+    unsigned char *scratch) const noexcept {
     // If past useful range
     if (offset >= sizeof(shadow_state)) {
         *data = nullptr;
-        return length <= pma.get_length() && offset <= pma.get_length() - length;
+        return contains_relative(offset, length);
     }
     // Otherwise, copy and return register data
     return shadow_peek(
@@ -45,17 +41,7 @@ static bool shadow_state_peek(const pma_entry &pma, const machine &m, uint64_t o
             }
             return val;
         },
-        pma, m, offset, length, data, scratch);
-}
-
-pma_entry make_shadow_state_pma_entry(uint64_t start, uint64_t length) {
-    const pma_entry::flags f{.R = false,
-        .W = false,
-        .X = false,
-        .IR = false,
-        .IW = false,
-        .DID = PMA_ISTART_DID::shadow_state};
-    return make_device_pma_entry("shadow state", start, length, shadow_state_peek, &shadow_state_driver).set_flags(f);
+        *this, m, offset, length, data, scratch);
 }
 
 } // namespace cartesi
diff --git a/src/shadow-state-address-range.h b/src/shadow-state-address-range.h
new file mode 100644
index 000000000..59b350601
--- /dev/null
+++ b/src/shadow-state-address-range.h
@@ -0,0 +1,72 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef SHADOW_STATE_ADDRESS_RANGE_H
+#define SHADOW_STATE_ADDRESS_RANGE_H
+
+#include <cstddef>
+#include <cstdint>
+
+#include "address-range.h"
+#include "shadow-state.h"
+
+/// \file
+/// \brief Shadow state address range.
+
+namespace cartesi {
+
+class shadow_state_address_range final : public address_range {
+
+    static constexpr pma_flags m_shadow_state_flags{
+        .M = false,
+        .IO = true,
+        .E = false,
+        .R = false,
+        .W = false,
+        .X = false,
+        .IR = false,
+        .IW = false,
+        .DID = PMA_ISTART_DID::shadow_state,
+    };
+
+public:
+    template <typename ABRT>
+    shadow_state_address_range(uint64_t start, uint64_t length, ABRT abrt) :
+        address_range("shadow state", start, length, m_shadow_state_flags, abrt) {
+        ;
+    }
+
+    shadow_state_address_range(const shadow_state_address_range &) = default;
+    shadow_state_address_range &operator=(const shadow_state_address_range &) = default;
+    shadow_state_address_range(shadow_state_address_range &&) noexcept = default;
+    shadow_state_address_range &operator=(shadow_state_address_range &&) noexcept = default;
+    ~shadow_state_address_range() override = default;
+
+private:
+#ifndef MICROARCHITECTURE
+    bool do_peek(const machine &m, uint64_t offset, uint64_t length, const unsigned char **data,
+        unsigned char *scratch) const noexcept override;
+#endif
+};
+
+template <typename ABRT>
+static inline shadow_state_address_range make_shadow_state_address_range(uint64_t start, uint64_t length, ABRT abrt) {
+    return shadow_state_address_range{start, length, abrt};
+}
+
+} // namespace cartesi
+
+#endif
diff --git a/src/shadow-state-factory.h b/src/shadow-state-factory.h
deleted file mode 100644
index 6fef5f66f..000000000
--- a/src/shadow-state-factory.h
+++ /dev/null
@@ -1,37 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef SHADOW_STATE_FACTORY_H
-#define SHADOW_STATE_FACTORY_H
-
-#include <cstdint>
-
-/// \file
-/// \brief Shadow device.
-
-#include "pma.h"
-
-namespace cartesi {
-
-/// \brief Creates a PMA entry for the shadow device
-/// \param start Start address for memory range.
-/// \param length Length of memory range.
-/// \returns Corresponding PMA entry
-pma_entry make_shadow_state_pma_entry(uint64_t start, uint64_t length);
-
-} // namespace cartesi
-
-#endif
diff --git a/src/shadow-state.cpp b/src/shadow-state.cpp
deleted file mode 100644
index 6cc463e29..000000000
--- a/src/shadow-state.cpp
+++ /dev/null
@@ -1,25 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#include "shadow-state.h"
-
-#include "pma-driver.h"
-
-namespace cartesi {
-
-const pma_driver shadow_state_driver = {.name = "SHADOW STATE", .read = device_read_error, .write = device_write_error};
-
-} // namespace cartesi
diff --git a/src/shadow-state.h b/src/shadow-state.h
index 4efbc3b00..73766cde8 100644
--- a/src/shadow-state.h
+++ b/src/shadow-state.h
@@ -17,17 +17,16 @@
 #ifndef SHADOW_STATE_H
 #define SHADOW_STATE_H
 
-#include <cassert>
 #include <cstddef>
 #include <cstdint>
 
+#include "address-range.h"
 #include "compiler-defines.h"
 #include "pma-constants.h"
-#include "pma-driver.h"
 #include "riscv-constants.h"
 
 /// \file
-/// \brief Shadow device.
+/// \brief Shadow state definitions.
 
 namespace cartesi {
 
@@ -194,6 +193,7 @@ static constexpr shadow_state_what shadow_state_get_what(uint64_t paddr) {
         (paddr & (sizeof(uint64_t) - 1)) != 0) {
         return shadow_state_what::unknown_;
     }
+    // NOLINTNEXTLINE(clang-analyzer-optin.core.EnumCastOutOfRange)
     return static_cast<shadow_state_what>(paddr);
 }
 
@@ -427,9 +427,6 @@ static constexpr const char *shadow_state_get_what_name(shadow_state_what what)
     return "state.unknown_";
 }
 
-/// \brief Global instance of the processor shadow device driver.
-extern const pma_driver shadow_state_driver;
-
 } // namespace cartesi
 
 #endif
diff --git a/src/shadow-tlb-factory.cpp b/src/shadow-tlb-address-range.cpp
similarity index 64%
rename from src/shadow-tlb-factory.cpp
rename to src/shadow-tlb-address-range.cpp
index e3cefa319..d9f52fc96 100644
--- a/src/shadow-tlb-factory.cpp
+++ b/src/shadow-tlb-address-range.cpp
@@ -14,26 +14,21 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#include "shadow-tlb-factory.h"
+#include "shadow-tlb-address-range.h"
 
 #include <cstdint>
 
 #include "machine.h"
-#include "pma-constants.h"
-#include "pma.h"
 #include "shadow-peek.h"
-#include "shadow-tlb.h"
-#include "tlb.h"
 
 namespace cartesi {
 
-/// \brief TLB device peek callback. See ::pma_peek.
-static bool shadow_tlb_peek(const pma_entry &pma, const machine &m, uint64_t offset, uint64_t length,
-    const unsigned char **data, unsigned char *scratch) {
+bool shadow_tlb_address_range::do_peek(const machine &m, uint64_t offset, uint64_t length, const unsigned char **data,
+    unsigned char *scratch) const noexcept {
     // If past useful range
     if (offset >= sizeof(shadow_tlb_state)) {
         *data = nullptr;
-        return length <= pma.get_length() && offset <= pma.get_length() - length;
+        return contains_relative(offset, length);
     }
     // Otherwise, copy and return register data
     return shadow_peek(
@@ -47,17 +42,7 @@ static bool shadow_tlb_peek(const pma_entry &pma, const machine &m, uint64_t off
             }
             return val;
         },
-        pma, m, offset, length, data, scratch);
-}
-
-pma_entry make_shadow_tlb_pma_entry(uint64_t start, uint64_t length) {
-    const pma_entry::flags f{.R = false,
-        .W = false,
-        .X = false,
-        .IR = false,
-        .IW = false,
-        .DID = PMA_ISTART_DID::shadow_TLB};
-    return make_device_pma_entry("shadow TLB", start, length, shadow_tlb_peek, &shadow_tlb_driver).set_flags(f);
+        *this, m, offset, length, data, scratch);
 }
 
 } // namespace cartesi
diff --git a/src/shadow-tlb-address-range.h b/src/shadow-tlb-address-range.h
new file mode 100644
index 000000000..1956ba99b
--- /dev/null
+++ b/src/shadow-tlb-address-range.h
@@ -0,0 +1,72 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef SHADOW_TLB_ADDRESS_RANGE_H
+#define SHADOW_TLB_ADDRESS_RANGE_H
+
+#include <cstddef>
+#include <cstdint>
+
+#include "address-range.h"
+#include "shadow-state.h"
+
+/// \file
+/// \brief Shadow state address range.
+
+namespace cartesi {
+
+class shadow_tlb_address_range final : public address_range {
+
+    static constexpr pma_flags m_shadow_tlb_flags{
+        .M = false,
+        .IO = true,
+        .E = false,
+        .R = false,
+        .W = false,
+        .X = false,
+        .IR = false,
+        .IW = false,
+        .DID = PMA_ISTART_DID::shadow_TLB,
+    };
+
+public:
+    template <typename ABRT>
+    shadow_tlb_address_range(uint64_t start, uint64_t length, ABRT abrt) :
+        address_range("shadow TLB", start, length, m_shadow_tlb_flags, abrt) {
+        ;
+    }
+
+    shadow_tlb_address_range(const shadow_tlb_address_range &) = default;
+    shadow_tlb_address_range &operator=(const shadow_tlb_address_range &) = default;
+    shadow_tlb_address_range(shadow_tlb_address_range &&) noexcept = default;
+    shadow_tlb_address_range &operator=(shadow_tlb_address_range &&) noexcept = default;
+    ~shadow_tlb_address_range() override = default;
+
+private:
+#ifndef MICROARCHITECTURE
+    bool do_peek(const machine &m, uint64_t offset, uint64_t length, const unsigned char **data,
+        unsigned char *scratch) const noexcept override;
+#endif
+};
+
+template <typename ABRT>
+static inline shadow_tlb_address_range make_shadow_tlb_address_range(uint64_t start, uint64_t length, ABRT abrt) {
+    return shadow_tlb_address_range{start, length, abrt};
+}
+
+} // namespace cartesi
+
+#endif
diff --git a/src/shadow-tlb-factory.h b/src/shadow-tlb-factory.h
index 6c699a9e9..b372d7a67 100644
--- a/src/shadow-tlb-factory.h
+++ b/src/shadow-tlb-factory.h
@@ -22,8 +22,6 @@
 
 #include <cstdint>
 
-#include "pma.h"
-
 namespace cartesi {
 
 /// \brief Creates a PMA entry for the TLB device
diff --git a/src/shadow-tlb.cpp b/src/shadow-tlb.cpp
deleted file mode 100644
index f883c9287..000000000
--- a/src/shadow-tlb.cpp
+++ /dev/null
@@ -1,25 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#include "shadow-tlb.h"
-
-#include "pma-driver.h"
-
-namespace cartesi {
-
-const pma_driver shadow_tlb_driver = {.name = "SHADOW TLB", .read = device_read_error, .write = device_write_error};
-
-} // namespace cartesi
diff --git a/src/shadow-tlb.h b/src/shadow-tlb.h
index 508682e63..c7b6df025 100644
--- a/src/shadow-tlb.h
+++ b/src/shadow-tlb.h
@@ -26,7 +26,6 @@
 #include <cstdint>
 
 #include "compiler-defines.h"
-#include "pma-driver.h"
 #include "tlb.h"
 
 namespace cartesi {
@@ -61,8 +60,6 @@ using shadow_tlb_state = std::array<shadow_tlb_set, TLB_LAST_ + 1>; // one set f
 
 static_assert(PMA_SHADOW_TLB_LENGTH >= sizeof(shadow_tlb_state), "TLB state must fit in TLB shadow");
 
-extern const pma_driver shadow_tlb_driver;
-
 /// \brief List of field types
 enum class shadow_tlb_what : uint64_t {
     vaddr_page = offsetof(shadow_tlb_slot, vaddr_page),
diff --git a/src/shadow-uarch-state-factory.cpp b/src/shadow-uarch-state-address-range.cpp
similarity index 66%
rename from src/shadow-uarch-state-factory.cpp
rename to src/shadow-uarch-state-address-range.cpp
index bc5284c13..b4d19b54c 100644
--- a/src/shadow-uarch-state-factory.cpp
+++ b/src/shadow-uarch-state-address-range.cpp
@@ -14,26 +14,25 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#include "shadow-uarch-state-factory.h"
+#include "shadow-uarch-state-address-range.h"
 
 #include <cstdint>
 
 #include "machine-reg.h"
 #include "machine.h"
 #include "pma-constants.h"
-#include "pma.h"
 #include "shadow-peek.h"
 #include "shadow-uarch-state.h"
 
 namespace cartesi {
 
 /// \brief Shadow uarch state device peek callback. See ::pma_peek.
-static bool shadow_uarch_state_peek(const pma_entry &pma, const machine &m, uint64_t offset, uint64_t length,
-    const unsigned char **data, unsigned char *scratch) {
+bool shadow_uarch_state_address_range::do_peek(const machine &m, uint64_t offset, uint64_t length,
+    const unsigned char **data, unsigned char *scratch) const noexcept {
     // If past useful range
     if (offset >= sizeof(shadow_uarch_state)) {
         *data = nullptr;
-        return length <= pma.get_length() && offset <= pma.get_length() - length;
+        return contains_relative(offset, length);
     }
     // Otherwise, copy and return register data
     return shadow_peek(
@@ -45,19 +44,7 @@ static bool shadow_uarch_state_peek(const pma_entry &pma, const machine &m, uint
             }
             return val;
         },
-        pma, m, offset, length, data, scratch);
-}
-
-pma_entry make_shadow_uarch_state_pma_entry(uint64_t start, uint64_t length) {
-    const pma_entry::flags f{.R = false,
-        .W = false,
-        .X = false,
-        .IR = false,
-        .IW = false,
-        .DID = PMA_ISTART_DID::shadow_uarch};
-    return make_device_pma_entry("shadow uarch state", start, length, shadow_uarch_state_peek,
-        &shadow_uarch_state_driver)
-        .set_flags(f);
+        *this, m, offset, length, data, scratch);
 }
 
 } // namespace cartesi
diff --git a/src/shadow-uarch-state-address-range.h b/src/shadow-uarch-state-address-range.h
new file mode 100644
index 000000000..f9b286111
--- /dev/null
+++ b/src/shadow-uarch-state-address-range.h
@@ -0,0 +1,74 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef SHADOW_UARCH_STATE_ADDRESS_RANGE_H
+#define SHADOW_UARCH_STATE_ADDRESS_RANGE_H
+
+#include <cstddef>
+#include <cstdint>
+
+#include "address-range.h"
+#include "shadow-uarch-state.h"
+
+/// \file
+/// \brief Shadow uarch state address range.
+
+namespace cartesi {
+
+class shadow_uarch_state_address_range final : public address_range {
+
+    static constexpr pma_flags m_shadow_uarch_state_flags{
+        .M = false,
+        .IO = true,
+        .E = false,
+        .R = false,
+        .W = false,
+        .X = false,
+        .IR = false,
+        .IW = false,
+        .DID = PMA_ISTART_DID::shadow_uarch_state,
+    };
+
+public:
+    template <typename ABRT>
+    shadow_uarch_state_address_range(uint64_t start, uint64_t length, ABRT abrt) :
+        address_range("shadow uarch state", start, length, m_shadow_uarch_state_flags, abrt) {
+        ;
+    }
+
+    shadow_uarch_state_address_range(const shadow_uarch_state_address_range &) = delete;
+    shadow_uarch_state_address_range &operator=(const shadow_uarch_state_address_range &) = delete;
+    shadow_uarch_state_address_range &operator=(shadow_uarch_state_address_range &&) noexcept = delete;
+
+    shadow_uarch_state_address_range(shadow_uarch_state_address_range &&) noexcept = default;
+    ~shadow_uarch_state_address_range() override = default;
+
+private:
+#ifndef MICROARCHITECTURE
+    bool do_peek(const machine &m, uint64_t offset, uint64_t length, const unsigned char **data,
+        unsigned char *scratch) const noexcept override;
+#endif
+};
+
+template <typename ABRT>
+static inline shadow_uarch_state_address_range make_shadow_uarch_state_address_range(uint64_t start, uint64_t length,
+    ABRT abrt) {
+    return shadow_uarch_state_address_range{start, length, abrt};
+}
+
+} // namespace cartesi
+
+#endif
diff --git a/src/shadow-uarch-state-factory.h b/src/shadow-uarch-state-factory.h
deleted file mode 100644
index 6c8e450b4..000000000
--- a/src/shadow-uarch-state-factory.h
+++ /dev/null
@@ -1,37 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef SHADOW_UARCH_STATE_FACTORY_H
-#define SHADOW_UARCH_STATE_FACTORY_H
-
-#include <cstdint>
-
-/// \file
-/// \brief Shadow uarch state device.
-
-#include "pma.h"
-
-namespace cartesi {
-
-/// \brief Creates a PMA entry for the shadow uarch state device
-/// \param start Start address for memory range.
-/// \param length Length of memory range.
-/// \returns Corresponding PMA entry
-pma_entry make_shadow_uarch_state_pma_entry(uint64_t start, uint64_t length);
-
-} // namespace cartesi
-
-#endif
diff --git a/src/shadow-uarch-state.h b/src/shadow-uarch-state.h
index d161dcd27..a5ff6d92e 100644
--- a/src/shadow-uarch-state.h
+++ b/src/shadow-uarch-state.h
@@ -17,12 +17,10 @@
 #ifndef SHADOW_UARCH_STATE_H
 #define SHADOW_UARCH_STATE_H
 
-#include <cassert>
 #include <cstddef>
 #include <cstdint>
 
 #include "compiler-defines.h"
-#include "pma-driver.h"
 #include "riscv-constants.h"
 
 /// \file
@@ -82,6 +80,7 @@ static constexpr shadow_uarch_state_what shadow_uarch_state_get_what(uint64_t pa
         (paddr & (sizeof(uint64_t) - 1)) != 0) {
         return shadow_uarch_state_what::unknown_;
     }
+    // NOLINTNEXTLINE(clang-analyzer-optin.core.EnumCastOutOfRange)
     return static_cast<shadow_uarch_state_what>(paddr);
 }
 
@@ -173,9 +172,6 @@ static constexpr const char *shadow_uarch_state_get_what_name(shadow_uarch_state
     return "uarch.unknown_";
 }
 
-/// \brief Global instance of  theprocessor shadow uarch state device driver.
-extern const pma_driver shadow_uarch_state_driver;
-
 } // namespace cartesi
 
 #endif
diff --git a/src/state-access.h b/src/state-access.h
index 0bae8585b..86c4c883f 100644
--- a/src/state-access.h
+++ b/src/state-access.h
@@ -37,7 +37,6 @@
 #include "machine.h"
 #include "os.h"
 #include "pma-constants.h"
-#include "pma.h"
 #include "riscv-constants.h"
 #include "shadow-tlb.h"
 #include "strict-aliasing.h"
@@ -46,11 +45,6 @@ namespace cartesi {
 
 class state_access;
 
-// Type trait that should return the pma_entry type for a state access class
-template <>
-struct i_state_access_pma_entry<state_access> {
-    using type = pma_entry;
-};
 // Type trait that should return the fast_addr type for a state access class
 template <>
 struct i_state_access_fast_addr<state_access> {
@@ -433,10 +427,8 @@ class state_access :
         }
     }
 
-    pma_entry &do_read_pma_entry(uint64_t index) const {
-        assert(index < PMA_MAX);
-        // NOLINTNEXTLINE(bugprone-narrowing-conversions)
-        return m_m.get_state().pmas[static_cast<int>(index)];
+    address_range &do_read_pma(uint64_t index) const {
+        return m_m.read_pma(index);
     }
 
     void do_write_memory_with_padding(uint64_t paddr, const unsigned char *data, uint64_t data_length,
diff --git a/src/tlb.h b/src/tlb.h
index 2baa96918..0383e7da1 100644
--- a/src/tlb.h
+++ b/src/tlb.h
@@ -27,7 +27,6 @@
 
 #include "host-addr.h"
 #include "pma-constants.h"
-#include "pma-driver.h"
 #include "riscv-constants.h"
 
 namespace cartesi {
diff --git a/src/translate-virtual-address.h b/src/translate-virtual-address.h
index 5a740a29a..3d8b536f4 100644
--- a/src/translate-virtual-address.h
+++ b/src/translate-virtual-address.h
@@ -60,8 +60,8 @@ namespace cartesi {
 template <typename STATE_ACCESS>
 static inline bool write_ram_uint64(STATE_ACCESS a, uint64_t paddr, uint64_t val) {
     uint64_t pma_index = 0;
-    auto &pma = find_pma_entry<uint64_t>(a, paddr, pma_index);
-    if (unlikely(!pma.get_istart_M() || !pma.get_istart_W())) {
+    auto &ar = find_pma<uint64_t>(a, paddr, pma_index);
+    if (unlikely(!ar.is_memory() || !ar.is_writeable())) {
         return false;
     }
     const auto faddr = a.get_faddr(paddr, pma_index);
@@ -81,8 +81,8 @@ static inline bool write_ram_uint64(STATE_ACCESS a, uint64_t paddr, uint64_t val
 template <typename STATE_ACCESS>
 static inline bool read_ram_uint64(STATE_ACCESS a, uint64_t paddr, uint64_t *pval) {
     uint64_t pma_index = 0;
-    auto &pma = find_pma_entry<uint64_t>(a, paddr, pma_index);
-    if (unlikely(!pma.get_istart_M() || !pma.get_istart_R())) {
+    auto &ar = find_pma<uint64_t>(a, paddr, pma_index);
+    if (unlikely(!ar.is_memory() || !ar.is_readable())) {
         return false;
     }
     const auto faddr = a.get_faddr(paddr, pma_index);
diff --git a/src/uarch-record-state-access.h b/src/uarch-record-state-access.h
index 0a32243fd..498c4681f 100644
--- a/src/uarch-record-state-access.h
+++ b/src/uarch-record-state-access.h
@@ -19,7 +19,6 @@
 
 /// \file
 /// \brief State access implementation that record and logs all accesses
-#include <cassert>
 #include <cstdint>
 #include <cstring>
 #include <stdexcept>
@@ -35,7 +34,6 @@
 #include "machine-merkle-tree.h"
 #include "machine.h"
 #include "meta.h"
-#include "pma.h"
 #include "riscv-constants.h"
 #include "shadow-tlb.h"
 #include "shadow-uarch-state.h"
diff --git a/src/uarch-replay-state-access.h b/src/uarch-replay-state-access.h
index 091a31967..070f871e1 100644
--- a/src/uarch-replay-state-access.h
+++ b/src/uarch-replay-state-access.h
@@ -20,7 +20,6 @@
 /// \file
 /// \brief State access implementation that replays recorded state accesses
 
-#include <cassert>
 #include <cstdint>
 #include <cstring>
 #include <ios>
diff --git a/src/uarch-state-access.h b/src/uarch-state-access.h
index ef52ba558..fc1b7ef45 100644
--- a/src/uarch-state-access.h
+++ b/src/uarch-state-access.h
@@ -46,8 +46,8 @@ class uarch_state_access :
     /// \param m Reference to machine state.
     explicit uarch_state_access(machine &m) : m_m(m) {
         const auto &uram = m_m.get_uarch_state().ram;
-        const auto haddr = cast_ptr_to_host_addr(uram.get_memory_noexcept().get_host_memory());
-        const auto paddr = uram.get_start();
+        const auto haddr = cast_ptr_to_host_addr(uram->get_host_memory());
+        const auto paddr = uram->get_start();
         // initialize translation cache from paddr in uarch RAM to host address
         m_uram_ph_offset = haddr - paddr;
     }
@@ -92,30 +92,11 @@ class uarch_state_access :
     }
 
     uint64_t do_read_word(uint64_t paddr) const {
-        if ((paddr & (sizeof(uint64_t) - 1)) != 0) {
-            throw std::runtime_error("misaligned read from uarch");
-        }
-        // If the word is in UARCH_RAM, read it directly
-        // ??D This is an optimization that makes 15% difference in run_uarch tests
-        if (m_m.get_uarch_state().ram.contains(paddr, sizeof(uint64_t))) {
-            auto haddr = m_uram_ph_offset + paddr;
-            return aliased_aligned_read<uint64_t>(haddr);
-        }
         // Forward to machine
         return m_m.read_word(paddr);
     }
 
     void do_write_word(uint64_t paddr, uint64_t val) const {
-        if ((paddr & (sizeof(uint64_t) - 1)) != 0) {
-            throw std::runtime_error("misaligned read from uarch");
-        }
-        // If the word is in UARCH_RAM, write it directly
-        // ??D This is an optimization that makes 15% difference in run_uarch tests
-        if (m_m.get_uarch_state().ram.contains(paddr, sizeof(uint64_t))) {
-            auto haddr = m_uram_ph_offset + paddr;
-            aliased_aligned_write<uint64_t>(haddr, val);
-            return;
-        }
         // Forward to machine
         m_m.write_word(paddr, val);
     }
diff --git a/src/uarch-state.h b/src/uarch-state.h
index f028c5027..51c0db901 100644
--- a/src/uarch-state.h
+++ b/src/uarch-state.h
@@ -22,8 +22,9 @@
 
 #include <array>
 #include <cstdint>
+#include <memory>
 
-#include "pma.h"
+#include "memory-address-range.h"
 #include "riscv-constants.h"
 
 namespace cartesi {
@@ -42,9 +43,8 @@ struct uarch_state {
     std::array<uint64_t, UARCH_X_REG_COUNT> x{}; ///< Register file.
     uint64_t cycle{};                            ///< Cycles counter
     uint64_t halt_flag{};
-    pma_entry shadow_state; ///< Shadow uarch state
-    pma_entry ram;          ///< Memory range for micro RAM
-    pma_entry empty_pma;    ///< Empty range fallback
+    address_range *shadow_state{}; ///< Shadow uarch state
+    memory_address_range *ram{};   ///< Memory range for uarch RAM
 };
 
 } // namespace cartesi
diff --git a/src/unique-c-ptr.h b/src/unique-c-ptr.h
index d2ee9368f..965ab7523 100644
--- a/src/unique-c-ptr.h
+++ b/src/unique-c-ptr.h
@@ -17,7 +17,6 @@
 #ifndef UNIQUE_C_PTR_H
 #define UNIQUE_C_PTR_H
 
-#include "os.h"
 #include <cerrno>
 #include <cstdio>
 #include <cstdlib>
@@ -27,6 +26,8 @@
 #include <tuple>
 #include <type_traits>
 
+#include "os.h"
+
 namespace cartesi {
 
 namespace detail {
@@ -102,6 +103,13 @@ static inline auto make_unique_mmap(const char *pathname, size_t nmemb, bool sha
     return unique_mmap_ptr<T>(ptr, detail::mmap_deleter{size});
 }
 
+template <typename T>
+static auto inline make_moved_unique(T &&t)
+    requires std::is_rvalue_reference_v<T &&>
+{
+    return std::make_unique<T>(std::forward<T>(t));
+}
+
 } // namespace cartesi
 
 #endif
diff --git a/src/virtio-device.cpp b/src/virtio-address-range.cpp
similarity index 91%
rename from src/virtio-device.cpp
rename to src/virtio-address-range.cpp
index d3a5d90ca..67335103c 100644
--- a/src/virtio-device.cpp
+++ b/src/virtio-address-range.cpp
@@ -19,17 +19,17 @@
 // #define DEBUG_VIRTIO_MMIO
 // #define DEBUG_VIRTIO_ERRORS
 
-#include "virtio-device.h"
+#include "virtio-address-range.h"
 
 #include <algorithm>
 #include <cassert>
 #include <cstdint>
+#include <stdexcept>
 
 #include "i-device-state-access.h"
 #include "interpret.h"
 #include "os.h"
-#include "plic.h"
-#include "pma-driver.h"
+#include "plic-address-range.h"
 #include "strict-aliasing.h"
 
 namespace cartesi {
@@ -303,14 +303,16 @@ bool virtq::consume_desc(i_device_state_access *a, uint16_t desc_idx, uint32_t w
     return true;
 }
 
-virtio_device::virtio_device(uint32_t virtio_idx, uint32_t device_id, uint64_t device_features,
-    uint32_t config_space_size) :
+virtio_address_range::virtio_address_range(const char *description, uint64_t start, uint64_t length,
+    uint32_t virtio_idx, uint32_t device_id, uint64_t device_features, uint32_t config_space_size) :
+    pristine_address_range(description, start, length, m_virtio_flags,
+        [](const char *err) { throw std::invalid_argument{err}; }),
     virtio_idx(virtio_idx),
     device_id(device_id),
     device_features(device_features | VIRTIO_F_VERSION_1),
     config_space_size(config_space_size) {}
 
-void virtio_device::reset(i_device_state_access *a) {
+void virtio_address_range::reset(i_device_state_access *a) {
     on_device_reset();
     // The device MUST initialize device status to 0 upon reset.
     device_status = 0;
@@ -336,7 +338,7 @@ void virtio_device::reset(i_device_state_access *a) {
     reset_irq(a, VIRTIO_INT_STATUS_USED_BUFFER | VIRTIO_INT_STATUS_CONFIG_CHANGE);
 }
 
-void virtio_device::set_irq(i_device_state_access *a, uint32_t add_int_status) {
+void virtio_address_range::set_irq(i_device_state_access *a, uint32_t add_int_status) {
     int_status |= add_int_status;
 #ifdef DEBUG_VIRTIO
     std::ignore = fprintf(stderr, "virtio[%d]: set_irq int_status=%d\n", virtio_idx, int_status);
@@ -347,7 +349,7 @@ void virtio_device::set_irq(i_device_state_access *a, uint32_t add_int_status) {
     }
 }
 
-void virtio_device::reset_irq(i_device_state_access *a, uint32_t rem_int_status) {
+void virtio_address_range::reset_irq(i_device_state_access *a, uint32_t rem_int_status) {
     int_status &= ~rem_int_status;
 #ifdef DEBUG_VIRTIO
     std::ignore = fprintf(stderr, "virtio[%d]: reset_irq int_status=%d\n", virtio_idx, int_status);
@@ -361,7 +363,7 @@ void virtio_device::reset_irq(i_device_state_access *a, uint32_t rem_int_status)
     }
 }
 
-void virtio_device::notify_queue_used(i_device_state_access *a) {
+void virtio_address_range::notify_queue_used(i_device_state_access *a) {
 #if defined(DEBUG_VIRTIO)
     std::ignore = fprintf(stderr, "virtio[%d]: notify_queue_used\n", virtio_idx);
 #endif
@@ -371,7 +373,7 @@ void virtio_device::notify_queue_used(i_device_state_access *a) {
     }
 }
 
-void virtio_device::notify_device_needs_reset(i_device_state_access *a) {
+void virtio_address_range::notify_device_needs_reset(i_device_state_access *a) {
     // A fatal failure happened while processing a queue.
 #if defined(DEBUG_VIRTIO) || defined(DEBUG_VIRTIO_ERRORS)
     std::ignore = fprintf(stderr, "virtio[%d]: notify_device_needs_reset\n", virtio_idx);
@@ -383,7 +385,7 @@ void virtio_device::notify_device_needs_reset(i_device_state_access *a) {
     notify_config_change(a);
 }
 
-void virtio_device::notify_config_change(i_device_state_access *a) {
+void virtio_address_range::notify_config_change(i_device_state_access *a) {
     // Whenever device changes the configuration, we MUST changed its config generation,
     // so the driver knows that it should re-read its configuration.
     config_generation++;
@@ -397,7 +399,7 @@ void virtio_device::notify_config_change(i_device_state_access *a) {
     }
 }
 
-bool virtio_device::prepare_queue_write(i_device_state_access *a, uint32_t queue_idx, uint16_t *pdesc_idx,
+bool virtio_address_range::prepare_queue_write(i_device_state_access *a, uint32_t queue_idx, uint16_t *pdesc_idx,
     uint32_t *pwrite_avail_len) const {
     *pdesc_idx = 0;
     *pwrite_avail_len = 0;
@@ -439,8 +441,8 @@ bool virtio_device::prepare_queue_write(i_device_state_access *a, uint32_t queue
     return true;
 }
 
-bool virtio_device::consume_queue(i_device_state_access *a, uint32_t queue_idx, uint16_t desc_idx, uint32_t written_len,
-    uint16_t used_flags) {
+bool virtio_address_range::consume_queue(i_device_state_access *a, uint32_t queue_idx, uint16_t desc_idx,
+    uint32_t written_len, uint16_t used_flags) {
     // A device MUST NOT consume buffers or send any used buffer notifications to the driver before DRIVER_OK.
     assert(driver_ok);
     assert(queue_idx < VIRTIO_QUEUE_COUNT);
@@ -454,7 +456,7 @@ bool virtio_device::consume_queue(i_device_state_access *a, uint32_t queue_idx,
     return vq.consume_desc(a, desc_idx, written_len, used_flags);
 }
 
-void virtio_device::on_device_queue_notify(i_device_state_access *a, uint32_t queue_idx) {
+void virtio_address_range::on_device_queue_notify(i_device_state_access *a, uint32_t queue_idx) {
     // The device MUST NOT consume buffers or notify the driver before DRIVER_OK
     if (!driver_ok) {
         return;
@@ -504,13 +506,13 @@ void virtio_device::on_device_queue_notify(i_device_state_access *a, uint32_t qu
     }
 }
 
-void virtio_device::prepare_select(select_fd_sets * /*fds*/, uint64_t * /*timeout_us*/) {}
+void virtio_address_range::prepare_select(select_fd_sets * /*fds*/, uint64_t * /*timeout_us*/) {}
 
-bool virtio_device::poll_selected(int /*select_ret*/, select_fd_sets * /*fds*/, i_device_state_access * /*da*/) {
+bool virtio_address_range::poll_selected(int /*select_ret*/, select_fd_sets * /*fds*/, i_device_state_access * /*da*/) {
     return false;
 };
 
-bool virtio_device::poll_nowait(i_device_state_access *da) {
+bool virtio_address_range::poll_nowait(i_device_state_access *da) {
     uint64_t timeout_us = 0;
     return os_select_fds(
         [&](select_fd_sets *fds, uint64_t *timeout_us) -> void { this->prepare_select(fds, timeout_us); },
@@ -518,17 +520,18 @@ bool virtio_device::poll_nowait(i_device_state_access *da) {
         &timeout_us);
 }
 
-uint64_t virtio_device::read_shm_base(uint32_t /*shm_sel*/) {
+uint64_t virtio_address_range::read_shm_base(uint32_t /*shm_sel*/) const {
     // Reading from a non-existent region results in a base of 0xffffffffffffffff.
     return UINT64_C(-1);
 }
 
-uint64_t virtio_device::read_shm_length(uint32_t /*shm_sel*/) {
+uint64_t virtio_address_range::read_shm_length(uint32_t /*shm_sel*/) const {
     // Reading from a non-existent region results in a length of 0xffffffffffffffff.
     return UINT64_C(-1);
 }
 
-bool virtio_device::mmio_read_config(i_device_state_access * /*a*/, uint64_t offset, uint32_t *pval, int log2_size) {
+bool virtio_address_range::mmio_read_config(i_device_state_access * /*a*/, uint64_t offset, uint32_t *pval,
+    int log2_size) const {
     const int size = 1 << log2_size;
     // Only accept aligned reads
     if ((offset & (size - 1)) != 0) {
@@ -556,7 +559,7 @@ bool virtio_device::mmio_read_config(i_device_state_access * /*a*/, uint64_t off
     }
 }
 
-execute_status virtio_device::mmio_write_config(i_device_state_access * /*a*/, uint64_t offset, uint32_t val,
+execute_status virtio_address_range::mmio_write_config(i_device_state_access * /*a*/, uint64_t offset, uint32_t val,
     int log2_size) {
     const int size = 1 << log2_size;
     // Only accept aligned writes
@@ -585,7 +588,7 @@ execute_status virtio_device::mmio_write_config(i_device_state_access * /*a*/, u
     }
 }
 
-bool virtio_device::mmio_read(i_device_state_access *a, uint64_t offset, uint32_t *pval, int log2_size) {
+bool virtio_address_range::mmio_read(i_device_state_access *a, uint64_t offset, uint32_t *pval, int log2_size) const {
     // If offset is equal or greater than VIRTIO_MMIO_CONFIG, the driver is actually reading a device config
     if (offset >= VIRTIO_MMIO_CONFIG) {
         return mmio_read_config(a, offset - VIRTIO_MMIO_CONFIG, pval, log2_size);
@@ -662,7 +665,8 @@ bool virtio_device::mmio_read(i_device_state_access *a, uint64_t offset, uint32_
     }
 }
 
-execute_status virtio_device::mmio_write(i_device_state_access *a, uint64_t offset, uint32_t val, int log2_size) {
+execute_status virtio_address_range::mmio_write(i_device_state_access *a, uint64_t offset, uint32_t val,
+    int log2_size) {
     // If offset is equal or greater than VIRTIO_MMIO_CONFIG, the driver is actually writing a device config
     if (offset >= VIRTIO_MMIO_CONFIG) {
         return mmio_write_config(a, offset - VIRTIO_MMIO_CONFIG, val, log2_size);
@@ -802,45 +806,41 @@ execute_status virtio_device::mmio_write(i_device_state_access *a, uint64_t offs
     }
 }
 
-/// \brief VirtIO device read callback. See ::pma_read.
-static bool virtio_read(void *context, i_device_state_access *a, uint64_t offset, uint64_t *pval, int log2_size) {
-    auto *vdev = static_cast<virtio_device *>(context);
+bool virtio_address_range::do_read_device(i_device_state_access *a, uint64_t offset, int log2_size,
+    uint64_t *pval) const noexcept {
     uint32_t val32 = 0;
-    const bool status = vdev->mmio_read(a, offset, &val32, log2_size);
+    const bool status = mmio_read(a, offset, &val32, log2_size);
     if (status) {
         *pval = val32;
     }
 #ifdef DEBUG_VIRTIO_MMIO
-    std::ignore = fprintf(stderr, "virtio[%d]: mmio_read  offset=0x%03lx (%s) value=%d size=%d\n",
-        vdev->get_virtio_index(), offset, get_virtio_mmio_offset_name(offset), val32, 1 << log2_size);
+    std::ignore = fprintf(stderr, "virtio[%d]: mmio_read  offset=0x%03lx (%s) value=%d size=%d\n", get_virtio_index(),
+        offset, get_virtio_mmio_offset_name(offset), val32, 1 << log2_size);
 #endif
 #if defined(DEBUG_VIRTIO_MMIO) || defined(DEBUG_VIRTIO_ERRORS)
     if (!status) {
-        std::ignore = fprintf(stderr, "virtio[%d]: mmio_read FAILED!  offset=0x%03lx(%s) size=%d\n",
-            vdev->get_virtio_index(), offset, get_virtio_mmio_offset_name(offset), 1 << log2_size);
+        std::ignore = fprintf(stderr, "virtio[%d]: mmio_read FAILED!  offset=0x%03lx(%s) size=%d\n", get_virtio_index(),
+            offset, get_virtio_mmio_offset_name(offset), 1 << log2_size);
     }
 #endif
     return status;
 }
 
 /// \brief VirtIO device read callback. See ::pma_write.
-static execute_status virtio_write(void *context, i_device_state_access *a, uint64_t offset, uint64_t val,
-    int log2_size) {
-    auto *vdev = static_cast<virtio_device *>(context);
+execute_status virtio_address_range::do_write_device(i_device_state_access *a, uint64_t offset, int log2_size,
+    uint64_t val) noexcept {
 #ifdef DEBUG_VIRTIO_MMIO
-    std::ignore = fprintf(stderr, "virtio[%d]: mmio_write offset=0x%03lx (%s) value=%ld size=%d\n",
-        vdev->get_virtio_index(), offset, get_virtio_mmio_offset_name(offset), val, 1 << log2_size);
+    std::ignore = fprintf(stderr, "virtio[%d]: mmio_write offset=0x%03lx (%s) value=%ld size=%d\n", get_virtio_index(),
+        offset, get_virtio_mmio_offset_name(offset), val, 1 << log2_size);
 #endif
-    const execute_status status = vdev->mmio_write(a, offset, val, log2_size);
+    const execute_status status = mmio_write(a, offset, val, log2_size);
 #if defined(DEBUG_VIRTIO_MMIO) || defined(DEBUG_VIRTIO_ERRORS)
     if (status == execute_status::failure) {
         std::ignore = fprintf(stderr, "virtio[%d]: mmio_write FAILED! offset=0x%03lx (%s) value=%ld size=%d\n",
-            vdev->get_virtio_index(), offset, get_virtio_mmio_offset_name(offset), val, 1 << log2_size);
+            get_virtio_index(), offset, get_virtio_mmio_offset_name(offset), val, 1 << log2_size);
     }
 #endif
     return status;
 }
 
-const pma_driver virtio_driver = {.name = "VirtIO", .read = virtio_read, .write = virtio_write};
-
 } // namespace cartesi
diff --git a/src/virtio-device.h b/src/virtio-address-range.h
similarity index 93%
rename from src/virtio-device.h
rename to src/virtio-address-range.h
index d7ab76cee..f3f90bc93 100644
--- a/src/virtio-device.h
+++ b/src/virtio-address-range.h
@@ -14,17 +14,15 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#ifndef VIRTIO_DEVICE_H
-#define VIRTIO_DEVICE_H
+#ifndef VIRTIO_ADDRESS_RANGE_H
+#define VIRTIO_ADDRESS_RANGE_H
 
 #include <array>
 #include <cstdint>
 #include <cstring>
 
-#include "i-device-state-access.h"
-#include "interpret.h"
 #include "os.h"
-#include "pma-driver.h"
+#include "pristine-address-range.h"
 
 namespace cartesi {
 
@@ -245,7 +243,7 @@ struct virtq {
 };
 
 /// \brief VirtIO device common interface
-class virtio_device {
+class virtio_address_range : public pristine_address_range {
     uint32_t virtio_idx = 0;          ///< VirtIO device index
     uint32_t int_status = 0;          ///< Interrupt status mask (see virtio_status)
     uint32_t device_id = 0;           ///< Device id (see virtio_devices)
@@ -259,6 +257,18 @@ class virtio_device {
     uint32_t config_generation = 0;   ///< Configuration generation counter
     uint32_t config_space_size = 0;   ///< Configuration size
 
+    static constexpr pma_flags m_virtio_flags{
+        .M = false,
+        .IO = true,
+        .E = false,
+        .R = true,
+        .W = true,
+        .X = false,
+        .IR = false,
+        .IW = false,
+        .DID = PMA_ISTART_DID::VIRTIO,
+    };
+
 protected:
     // NOLINTBEGIN(cppcoreguidelines-non-private-member-variables-in-classes)
     bool driver_ok = false; ///< True when the device was successfully initialized by the driver
@@ -270,14 +280,15 @@ class virtio_device {
     // NOLINTEND(cppcoreguidelines-non-private-member-variables-in-classes)
 
 public:
-    explicit virtio_device(uint32_t virtio_idx, uint32_t device_id, uint64_t device_features,
-        uint32_t config_space_size);
-    virtio_device() = delete;
-    virtual ~virtio_device() = default;
-    virtio_device(const virtio_device &other) = delete;
-    virtio_device(virtio_device &&other) = delete;
-    virtio_device &operator=(const virtio_device &other) = delete;
-    virtio_device &operator=(virtio_device &&other) = delete;
+    explicit virtio_address_range(const char *description, uint64_t start, uint64_t length, uint32_t virtio_idx,
+        uint32_t device_id, uint64_t device_features, uint32_t config_space_size);
+
+    virtio_address_range(const virtio_address_range &other) = delete;
+    virtio_address_range &operator=(const virtio_address_range &other) = delete;
+    virtio_address_range &operator=(virtio_address_range &&other) = delete;
+
+    virtio_address_range(virtio_address_range &&other) = default;
+    ~virtio_address_range() override = default;
 
     /// \brief Reset device to uninitialize state, cleaning all its internal state.
     /// \details This is only requested by the driver when a fatal failure occurs
@@ -360,18 +371,18 @@ class virtio_device {
 
     /// \brief Reads device's shared memory base address.
     /// \returns Guest a valid physical address, or -1 in case shared memory is not supported by the device.
-    virtual uint64_t read_shm_base(uint32_t shm_sel);
+    virtual uint64_t read_shm_base(uint32_t shm_sel) const;
 
     /// \brief Reads device's shared memory length.
     /// \returns Length in bytes, or -1 in case shared memory is not supported by the device.
-    virtual uint64_t read_shm_length(uint32_t shm_sel);
+    virtual uint64_t read_shm_length(uint32_t shm_sel) const;
 
     /// \brief Reads a value from device's configuration space.
     /// \param offset Offset to be read.
     /// \param pval Receives the value.
     /// \param log2_size log2 of size of value to read.
     /// \returns True if there are no errors, false otherwise.
-    bool mmio_read_config(i_device_state_access *a, uint64_t offset, uint32_t *pval, int log2_size);
+    bool mmio_read_config(i_device_state_access *a, uint64_t offset, uint32_t *pval, int log2_size) const;
 
     /// \brief Writes a value to device's configuration space.
     /// \param offset Offset to write to.
@@ -385,7 +396,7 @@ class virtio_device {
     /// \param pval Receives the value.
     /// \param log2_size log2 of size of value to read.
     /// \returns True if there are no errors, false otherwise.
-    bool mmio_read(i_device_state_access *a, uint64_t offset, uint32_t *pval, int log2_size);
+    bool mmio_read(i_device_state_access *a, uint64_t offset, uint32_t *pval, int log2_size) const;
 
     /// \brief Writes a value to the device.
     /// \param offset Offset to be written.
@@ -408,10 +419,13 @@ class virtio_device {
     uint32_t get_device_id() const {
         return device_id;
     }
-};
 
-/// \brief Global VirtIO driver instance
-extern const pma_driver virtio_driver;
+private:
+    bool do_read_device(i_device_state_access *a, uint64_t offset, int log2_size,
+        uint64_t *pval) const noexcept override;
+    execute_status do_write_device(i_device_state_access *a, uint64_t offset, int log2_size,
+        uint64_t val) noexcept override;
+};
 
 } // namespace cartesi
 
diff --git a/src/virtio-console.cpp b/src/virtio-console-address-range.cpp
similarity index 82%
rename from src/virtio-console.cpp
rename to src/virtio-console-address-range.cpp
index 86f7b3c4d..d0b585554 100644
--- a/src/virtio-console.cpp
+++ b/src/virtio-console-address-range.cpp
@@ -14,7 +14,7 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#include "virtio-console.h"
+#include "virtio-console-address-range.h"
 
 #include <algorithm>
 #include <array>
@@ -22,24 +22,24 @@
 
 #include "i-device-state-access.h"
 #include "os.h"
-#include "virtio-device.h"
 
 namespace cartesi {
 
-virtio_console::virtio_console(uint32_t virtio_idx) :
-    virtio_device(virtio_idx, VIRTIO_DEVICE_CONSOLE, VIRTIO_CONSOLE_F_SIZE, sizeof(virtio_console_config_space)) {}
+virtio_console_address_range::virtio_console_address_range(uint64_t start, uint64_t length, uint32_t virtio_idx) :
+    virtio_address_range("VirtIO Console", start, length, virtio_idx, VIRTIO_DEVICE_CONSOLE, VIRTIO_CONSOLE_F_SIZE,
+        sizeof(virtio_console_config_space)) {}
 
-void virtio_console::on_device_reset() {
+void virtio_console_address_range::on_device_reset() {
     m_stdin_ready = false;
 }
 
-void virtio_console::on_device_ok(i_device_state_access *a) {
+void virtio_console_address_range::on_device_ok(i_device_state_access *a) {
     // Upon initialization, we need to notify the initial console size
     notify_console_size_to_guest(a);
 }
 
-bool virtio_console::on_device_queue_available(i_device_state_access *a, uint32_t queue_idx, uint16_t desc_idx,
-    uint32_t read_avail_len, uint32_t /*write_avail_len*/) {
+bool virtio_console_address_range::on_device_queue_available(i_device_state_access *a, uint32_t queue_idx,
+    uint16_t desc_idx, uint32_t read_avail_len, uint32_t /*write_avail_len*/) {
     if (queue_idx == VIRTIO_CONSOLE_RECEIVEQ) { // Guest has a new slot available in the write queue
         // Do nothing, host stdin characters will be written to the guest in the next poll
         return false;
@@ -52,8 +52,8 @@ bool virtio_console::on_device_queue_available(i_device_state_access *a, uint32_
     return false;
 }
 
-bool virtio_console::write_next_chars_to_host(i_device_state_access *a, uint32_t queue_idx, uint16_t desc_idx,
-    uint32_t read_avail_len) {
+bool virtio_console_address_range::write_next_chars_to_host(i_device_state_access *a, uint32_t queue_idx,
+    uint16_t desc_idx, uint32_t read_avail_len) {
     const virtq &vq = queue[queue_idx];
     // Read stdout characters from queue buffer in chunks
     std::array<uint8_t, TTY_BUF_SIZE> chunk{};
@@ -75,7 +75,7 @@ bool virtio_console::write_next_chars_to_host(i_device_state_access *a, uint32_t
     return true;
 }
 
-bool virtio_console::write_next_chars_to_guest(i_device_state_access *a) {
+bool virtio_console_address_range::write_next_chars_to_guest(i_device_state_access *a) {
     if (!driver_ok) {
         return false;
     }
@@ -115,7 +115,7 @@ bool virtio_console::write_next_chars_to_guest(i_device_state_access *a) {
     return true;
 }
 
-bool virtio_console::notify_console_size_to_guest(i_device_state_access *a) {
+bool virtio_console_address_range::notify_console_size_to_guest(i_device_state_access *a) {
     // Get current console size
     uint16_t cols{};
     uint16_t rows{};
@@ -131,7 +131,7 @@ bool virtio_console::notify_console_size_to_guest(i_device_state_access *a) {
     return true;
 }
 
-void virtio_console::prepare_select(select_fd_sets *fds, uint64_t *timeout_us) {
+void virtio_console_address_range::prepare_select(select_fd_sets *fds, uint64_t *timeout_us) {
     // Ignore if driver is not initialized
     if (!driver_ok) {
         return;
@@ -154,8 +154,9 @@ void virtio_console::prepare_select(select_fd_sets *fds, uint64_t *timeout_us) {
     os_prepare_tty_select(fds);
 }
 
-bool virtio_console::poll_selected(int select_ret, select_fd_sets *fds, i_device_state_access *da) {
+bool virtio_console_address_range::poll_selected(int select_ret, select_fd_sets *fds, i_device_state_access *da) {
     // Ignore if driver is not initialized or stdin is not ready
+
     if (!driver_ok || !m_stdin_ready) {
         return false;
     }
diff --git a/src/virtio-console.h b/src/virtio-console-address-range.h
similarity index 76%
rename from src/virtio-console.h
rename to src/virtio-console-address-range.h
index 757a9a892..3f68c410c 100644
--- a/src/virtio-console.h
+++ b/src/virtio-console-address-range.h
@@ -14,14 +14,12 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#ifndef VIRTIO_CONSOLE_H
-#define VIRTIO_CONSOLE_H
+#ifndef VIRTIO_CONSOLE_ADDRESS_RANGE_H
+#define VIRTIO_CONSOLE_ADDRESS_RANGE_H
 
 #include <cstdint>
 
-#include "i-device-state-access.h"
-#include "os.h"
-#include "virtio-device.h"
+#include "virtio-address-range.h"
 
 namespace cartesi {
 
@@ -47,11 +45,18 @@ struct virtio_console_config_space {
 };
 
 /// \brief VirtIO console device
-class virtio_console final : public virtio_device {
+class virtio_console_address_range final : public virtio_address_range {
     bool m_stdin_ready = false;
 
 public:
-    explicit virtio_console(uint32_t virtio_idx);
+    explicit virtio_console_address_range(uint64_t start, uint64_t length, uint32_t virtio_idx);
+
+    virtio_console_address_range(const virtio_console_address_range &other) = delete;
+    virtio_console_address_range &operator=(const virtio_console_address_range &other) = delete;
+    virtio_console_address_range &operator=(virtio_console_address_range &&other) = delete;
+
+    virtio_console_address_range(virtio_console_address_range &&other) = default;
+    ~virtio_console_address_range() override = default;
 
     void on_device_reset() override;
     void on_device_ok(i_device_state_access *a) override;
@@ -72,6 +77,10 @@ class virtio_console final : public virtio_device {
     }
 };
 
+static inline auto make_virtio_console_address_range(uint64_t start, uint64_t length, uint32_t virtio_idx) {
+    return virtio_console_address_range{start, length, virtio_idx};
+}
+
 } // namespace cartesi
 
 #endif
diff --git a/src/virtio-factory.cpp b/src/virtio-factory.cpp
deleted file mode 100644
index 762033d6c..000000000
--- a/src/virtio-factory.cpp
+++ /dev/null
@@ -1,36 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#include "virtio-factory.h"
-
-#include <cstdint>
-#include <string>
-
-#include "pma-constants.h"
-#include "pma-driver.h"
-#include "pma.h"
-
-namespace cartesi {
-
-pma_entry make_virtio_pma_entry(uint64_t start, uint64_t length, const std::string &description,
-    const pma_driver *driver, void *context) {
-    const pma_entry::flags f{.R = true, .W = true, .X = false, .IR = false, .IW = false, .DID = PMA_ISTART_DID::VIRTIO};
-    // VirtIO devices are not verifiable yet,
-    // therefore peek will always fail and cause an runtime error when updating the Merkle tree.
-    return make_device_pma_entry(description, start, length, pma_peek_error, driver, context).set_flags(f);
-}
-
-} // namespace cartesi
diff --git a/src/virtio-factory.h b/src/virtio-factory.h
deleted file mode 100644
index 51899096c..000000000
--- a/src/virtio-factory.h
+++ /dev/null
@@ -1,37 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef VIRTIO_FACTORY_H
-#define VIRTIO_FACTORY_H
-
-#include <cstdint>
-#include <string>
-
-#include "pma-driver.h"
-#include "pma.h"
-
-namespace cartesi {
-
-/// \brief Creates a PMA entry for a VirtIO device
-/// \param start Start address for memory range.
-/// \param length Length of memory range.
-/// \returns Corresponding PMA entry
-pma_entry make_virtio_pma_entry(uint64_t start, uint64_t length, const std::string &description,
-    const pma_driver *driver, void *context);
-
-} // namespace cartesi
-
-#endif
diff --git a/src/virtio-net.cpp b/src/virtio-net-address-range.cpp
similarity index 77%
rename from src/virtio-net.cpp
rename to src/virtio-net-address-range.cpp
index f114f7489..653881973 100644
--- a/src/virtio-net.cpp
+++ b/src/virtio-net-address-range.cpp
@@ -14,7 +14,7 @@
 // along with the machine-emulator. If not, see http://www.gnu.org/licenses/.
 //
 
-#include "virtio-net.h"
+#include "virtio-net-address-range.h"
 
 #if defined(HAVE_SLIRP) || defined(HAVE_TUNTAP)
 
@@ -24,24 +24,23 @@
 
 #include "i-device-state-access.h"
 #include "os.h"
-#include "virtio-device.h"
 
 namespace cartesi {
 
-virtio_net::virtio_net(uint32_t virtio_idx, std::unique_ptr<virtio_net_carrier> &&carrier) :
-    virtio_device(virtio_idx, VIRTIO_DEVICE_NETWORK, 0, 0),
-    m_carrier(std::move(carrier)) {}
+virtio_net_address_range::virtio_net_address_range(const char *description, uint64_t start, uint64_t length,
+    uint32_t virtio_idx) :
+    virtio_address_range(description, start, length, virtio_idx, VIRTIO_DEVICE_NETWORK, 0, 0) {}
 
-void virtio_net::on_device_reset() {
-    m_carrier->reset();
+void virtio_net_address_range::on_device_reset() {
+    net_reset();
 }
 
-void virtio_net::on_device_ok(i_device_state_access * /*a*/) {
+void virtio_net_address_range::on_device_ok(i_device_state_access * /*a*/) {
     // Nothing to do.
 }
 
-bool virtio_net::on_device_queue_available(i_device_state_access *a, uint32_t queue_idx, uint16_t desc_idx,
-    uint32_t read_avail_len, uint32_t /*write_avail_len*/) {
+bool virtio_net_address_range::on_device_queue_available(i_device_state_access *a, uint32_t queue_idx,
+    uint16_t desc_idx, uint32_t read_avail_len, uint32_t /*write_avail_len*/) {
     if (queue_idx == VIRTIO_NET_RECEIVEQ) { // Guest has a new slot available in the write queue
         // Write any pending packets from host to guest
         return poll_nowait(a);
@@ -60,19 +59,19 @@ bool virtio_net::on_device_queue_available(i_device_state_access *a, uint32_t qu
     return false;
 }
 
-void virtio_net::prepare_select(select_fd_sets *fds, uint64_t *timeout_us) {
+void virtio_net_address_range::prepare_select(select_fd_sets *fds, uint64_t *timeout_us) {
     if (!driver_ok) {
         return;
     }
-    m_carrier->do_prepare_select(fds, timeout_us);
+    net_prepare_select(fds, timeout_us);
 }
 
-bool virtio_net::poll_selected(int select_ret, select_fd_sets *fds, i_device_state_access *da) {
+bool virtio_net_address_range::poll_selected(int select_ret, select_fd_sets *fds, i_device_state_access *da) {
     if (!driver_ok) {
         return false;
     }
     // Is there any pending to be read from the host?
-    if (!m_carrier->do_poll_selected(select_ret, fds)) {
+    if (!net_poll_selected(select_ret, fds)) {
         return false;
     }
     bool interrupt_requested = false;
@@ -84,12 +83,12 @@ bool virtio_net::poll_selected(int select_ret, select_fd_sets *fds, i_device_sta
     return interrupt_requested;
 }
 
-bool virtio_net::write_next_packet_to_host(i_device_state_access *a, uint32_t queue_idx, uint16_t desc_idx,
-    uint32_t read_avail_len) {
+bool virtio_net_address_range::write_next_packet_to_host(i_device_state_access *a, uint32_t queue_idx,
+    uint16_t desc_idx, uint32_t read_avail_len) {
     virtq &vq = queue[queue_idx];
     // Write a single packet to the network interface
     uint32_t read_len{};
-    if (!m_carrier->write_packet_to_host(a, vq, desc_idx, read_avail_len, &read_len)) {
+    if (!net_write_packet_to_host(a, vq, desc_idx, read_avail_len, &read_len)) {
         notify_device_needs_reset(a);
         return false;
     }
@@ -101,7 +100,7 @@ bool virtio_net::write_next_packet_to_host(i_device_state_access *a, uint32_t qu
     return true;
 }
 
-bool virtio_net::read_next_packet_from_host(i_device_state_access *a) {
+bool virtio_net_address_range::read_next_packet_from_host(i_device_state_access *a) {
     // Bytes from host must be written to queue 0
     constexpr uint32_t queue_idx = VIRTIO_NET_RECEIVEQ;
     virtq &vq = queue[queue_idx];
@@ -119,7 +118,7 @@ bool virtio_net::read_next_packet_from_host(i_device_state_access *a) {
     }
     // Read a single packet from the network interface
     uint32_t written_len{};
-    if (!m_carrier->read_packet_from_host(a, vq, desc_idx, write_avail_len, &written_len)) {
+    if (!net_read_packet_from_host(a, vq, desc_idx, write_avail_len, &written_len)) {
         notify_device_needs_reset(a);
         return false;
     }
diff --git a/src/virtio-net.h b/src/virtio-net-address-range.h
similarity index 73%
rename from src/virtio-net.h
rename to src/virtio-net-address-range.h
index b17c09aab..806b53311 100644
--- a/src/virtio-net.h
+++ b/src/virtio-net-address-range.h
@@ -14,8 +14,8 @@
 // along with the machine-emulator. If not, see http://www.gnu.org/licenses/.
 //
 
-#ifndef VIRTIO_NET_H
-#define VIRTIO_NET_H
+#ifndef VIRTIO_NET_ADDRESS_RANGE_H
+#define VIRTIO_NET_ADDRESS_RANGE_H
 
 #include "os-features.h"
 
@@ -26,7 +26,7 @@
 
 #include "i-device-state-access.h"
 #include "os.h"
-#include "virtio-device.h"
+#include "virtio-address-range.h"
 
 namespace cartesi {
 
@@ -53,26 +53,39 @@ enum virtio_net_virtq : uint32_t {
     VIRTIO_NET_TRANSMITQ = 1, ///< Queue of packets from guest to host
 };
 
-/// \brief Generic interface for a network carrier on the host.
-/// \details The sole purpose of a network carrier
-/// is to carry incoming or outgoing packets between the host and the guest.
-class virtio_net_carrier {
+/// \brief VirtIO net device
+class virtio_net_address_range : public virtio_address_range {
 public:
-    virtio_net_carrier() = default;
-    virtual ~virtio_net_carrier() = default;
-    virtio_net_carrier(const virtio_net_carrier &other) = delete;
-    virtio_net_carrier(virtio_net_carrier &&other) = delete;
-    virtio_net_carrier &operator=(const virtio_net_carrier &other) = delete;
-    virtio_net_carrier &operator=(virtio_net_carrier &&other) = delete;
+    virtio_net_address_range(const char *description, uint64_t start, uint64_t length, uint32_t virtio_idx);
+
+    virtio_net_address_range(const virtio_net_address_range &other) = delete;
+    virtio_net_address_range &operator=(const virtio_net_address_range &other) = delete;
+    virtio_net_address_range &operator=(virtio_net_address_range &&other) = delete;
+
+    virtio_net_address_range(virtio_net_address_range &&other) = default;
+    ~virtio_net_address_range() override = default;
+
+    void on_device_reset() override;
+    void on_device_ok(i_device_state_access *a) override;
+    bool on_device_queue_available(i_device_state_access *a, uint32_t queue_idx, uint16_t desc_idx,
+        uint32_t read_avail_len, uint32_t write_avail_len) override;
 
+    void prepare_select(select_fd_sets *fds, uint64_t *timeout_us) override;
+    bool poll_selected(int select_ret, select_fd_sets *fds, i_device_state_access *da) override;
+
+    bool write_next_packet_to_host(i_device_state_access *a, uint32_t queue_idx, uint16_t desc_idx,
+        uint32_t read_avail_len);
+    bool read_next_packet_from_host(i_device_state_access *a);
+
+protected:
     /// \brief Reset carrier internal state, discarding all network state.
-    virtual void reset() = 0;
+    virtual void net_reset() = 0;
 
     /// \brief Fill file descriptors to be polled by select().
-    virtual void do_prepare_select(select_fd_sets *fds, uint64_t *timeout_us) = 0;
+    virtual void net_prepare_select(select_fd_sets *fds, uint64_t *timeout_us) = 0;
 
     /// \brief Poll file descriptors that were marked as ready by select().
-    virtual bool do_poll_selected(int select_ret, select_fd_sets *fds) = 0;
+    virtual bool net_poll_selected(int select_ret, select_fd_sets *fds) = 0;
 
     /// \brief Called for carrying outgoing packets from the guest to the host.
     /// \param vq Queue reference.
@@ -82,8 +95,8 @@ class virtio_net_carrier {
     /// \returns True on success, false otherwise.
     /// \details This function will return true even if when the write queue is full,
     /// pread_len will be set to 0 in this case and the packet dropped.
-    virtual bool write_packet_to_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx, uint32_t read_avail_len,
-        uint32_t *pread_len) = 0;
+    virtual bool net_write_packet_to_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx,
+        uint32_t read_avail_len, uint32_t *pread_len) = 0;
 
     /// \brief Called for carrying incoming packets from the host to the guest.
     /// \param vq Queue reference.
@@ -93,29 +106,8 @@ class virtio_net_carrier {
     /// \returns True on success, false otherwise.
     /// \details This function will true even if when there are no more packets to write,
     /// pwritten_len will be set to 0 in this case.
-    virtual bool read_packet_from_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx, uint32_t write_avail_len,
-        uint32_t *pwritten_len) = 0;
-};
-
-/// \brief VirtIO net device
-class virtio_net final : public virtio_device {
-public:
-    virtio_net(uint32_t virtio_idx, std::unique_ptr<virtio_net_carrier> &&carrier);
-
-    void on_device_reset() override;
-    void on_device_ok(i_device_state_access *a) override;
-    bool on_device_queue_available(i_device_state_access *a, uint32_t queue_idx, uint16_t desc_idx,
-        uint32_t read_avail_len, uint32_t write_avail_len) override;
-
-    void prepare_select(select_fd_sets *fds, uint64_t *timeout_us) override;
-    bool poll_selected(int select_ret, select_fd_sets *fds, i_device_state_access *da) override;
-
-    bool write_next_packet_to_host(i_device_state_access *a, uint32_t queue_idx, uint16_t desc_idx,
-        uint32_t read_avail_len);
-    bool read_next_packet_from_host(i_device_state_access *a);
-
-private:
-    std::unique_ptr<virtio_net_carrier> m_carrier;
+    virtual bool net_read_packet_from_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx,
+        uint32_t write_avail_len, uint32_t *pwritten_len) = 0;
 };
 
 } // namespace cartesi
diff --git a/src/virtio-net-carrier-tuntap.h b/src/virtio-net-carrier-tuntap.h
deleted file mode 100644
index 392cdd86e..000000000
--- a/src/virtio-net-carrier-tuntap.h
+++ /dev/null
@@ -1,60 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef VIRTIO_NET_CARRIER_TUNTAP_H
-#define VIRTIO_NET_CARRIER_TUNTAP_H
-
-#include "os-features.h"
-
-#ifdef HAVE_TUNTAP
-
-#include <cstdint>
-#include <string>
-
-#include "i-device-state-access.h"
-#include "os.h"
-#include "virtio-device.h"
-#include "virtio-net.h"
-
-namespace cartesi {
-
-class virtio_net_carrier_tuntap final : public virtio_net_carrier {
-    int m_tapfd = -1;
-
-public:
-    explicit virtio_net_carrier_tuntap(const std::string &tap_name);
-    ~virtio_net_carrier_tuntap() override;
-    virtio_net_carrier_tuntap(const virtio_net_carrier_tuntap &other) = delete;
-    virtio_net_carrier_tuntap(virtio_net_carrier_tuntap &&other) = delete;
-    virtio_net_carrier_tuntap &operator=(const virtio_net_carrier_tuntap &other) = delete;
-    virtio_net_carrier_tuntap &operator=(virtio_net_carrier_tuntap &&other) = delete;
-
-    void reset() override;
-
-    void do_prepare_select(select_fd_sets *fds, uint64_t *timeout_us) override;
-    bool do_poll_selected(int select_ret, select_fd_sets *fds) override;
-
-    bool write_packet_to_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx, uint32_t read_avail_len,
-        uint32_t *pread_len) override;
-    bool read_packet_from_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx, uint32_t write_avail_len,
-        uint32_t *pwritten_len) override;
-};
-
-} // namespace cartesi
-
-#endif // HAVE_TUNTAP
-
-#endif
diff --git a/src/virtio-net-carrier-tuntap.cpp b/src/virtio-net-tuntap-address-range.cpp
similarity index 90%
rename from src/virtio-net-carrier-tuntap.cpp
rename to src/virtio-net-tuntap-address-range.cpp
index 4da7a3188..68aaa596c 100644
--- a/src/virtio-net-carrier-tuntap.cpp
+++ b/src/virtio-net-tuntap-address-range.cpp
@@ -52,7 +52,7 @@
 
 // #define DEBUG_VIRTIO_ERRORS
 
-#include "virtio-net-carrier-tuntap.h"
+#include "virtio-net-tuntap-address-range.h"
 
 #ifdef HAVE_TUNTAP
 
@@ -74,8 +74,6 @@
 
 #include "i-device-state-access.h"
 #include "os.h"
-#include "virtio-device.h"
-#include "virtio-net.h"
 
 // Include TUN/TAP headers
 #ifdef __linux__
@@ -90,7 +88,9 @@ constexpr const char NET_TUN_DEV[] = "/dev/tun";
 
 namespace cartesi {
 
-virtio_net_carrier_tuntap::virtio_net_carrier_tuntap(const std::string &tap_name) {
+virtio_net_tuntap_address_range::virtio_net_tuntap_address_range(uint64_t start, uint64_t length, uint32_t virtio_idx,
+    const std::string &tap_name) :
+    virtio_net_address_range("VirtIO Net TUN/TAP", start, length, virtio_idx) {
     // Open the tun device
     const int flags = O_RDWR | // Read/write
         O_NONBLOCK |           // Read/write should never block
@@ -113,30 +113,30 @@ virtio_net_carrier_tuntap::virtio_net_carrier_tuntap(const std::string &tap_name
     m_tapfd = fd;
 }
 
-virtio_net_carrier_tuntap::~virtio_net_carrier_tuntap() {
+virtio_net_tuntap_address_range::~virtio_net_tuntap_address_range() {
     if (m_tapfd != -1) {
         close(m_tapfd);
     }
 }
 
-void virtio_net_carrier_tuntap::reset() {
+void virtio_net_tuntap_address_range::net_reset() {
     // Nothing to do.
 }
 
-void virtio_net_carrier_tuntap::do_prepare_select(select_fd_sets *fds, uint64_t * /*timeout_us*/) {
+void virtio_net_tuntap_address_range::net_prepare_select(select_fd_sets *fds, uint64_t * /*timeout_us*/) {
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
     auto *readfds = reinterpret_cast<fd_set *>(fds->readfds);
     FD_SET(m_tapfd, readfds);
     fds->maxfd = std::max(m_tapfd, fds->maxfd);
 }
 
-bool virtio_net_carrier_tuntap::do_poll_selected(int select_ret, select_fd_sets *fds) {
+bool virtio_net_tuntap_address_range::net_poll_selected(int select_ret, select_fd_sets *fds) {
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
     auto *readfds = reinterpret_cast<fd_set *>(fds->readfds);
     return select_ret > 0 && FD_ISSET(m_tapfd, readfds);
 }
 
-bool virtio_net_carrier_tuntap::write_packet_to_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx,
+bool virtio_net_tuntap_address_range::net_write_packet_to_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx,
     uint32_t read_avail_len, uint32_t *pread_len) {
     // Determinate packet size
     const uint32_t packet_len = read_avail_len - VIRTIO_NET_ETHERNET_FRAME_OFFSET;
@@ -182,7 +182,7 @@ bool virtio_net_carrier_tuntap::write_packet_to_host(i_device_state_access *a, v
     return true;
 }
 
-bool virtio_net_carrier_tuntap::read_packet_from_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx,
+bool virtio_net_tuntap_address_range::net_read_packet_from_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx,
     uint32_t write_avail_len, uint32_t *pwritten_len) {
     // Write network to queue buffer in chunks
     std::array<uint8_t, VIRTIO_NET_ETHERNET_MAX_LENGTH> packet_buf{};
diff --git a/src/virtio-net-tuntap-address-range.h b/src/virtio-net-tuntap-address-range.h
new file mode 100644
index 000000000..cd3328dbe
--- /dev/null
+++ b/src/virtio-net-tuntap-address-range.h
@@ -0,0 +1,67 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef VIRTIO_NET_TUNTAP_ADDRESS_RANGE_H
+#define VIRTIO_NET_TUNTAP_ADDRESS_RANGE_H
+
+#include "os-features.h"
+
+#ifdef HAVE_TUNTAP
+
+#include <cstdint>
+#include <string>
+
+#include "i-device-state-access.h"
+#include "os.h"
+#include "virtio-net-address-range.h"
+
+namespace cartesi {
+
+class virtio_net_tuntap_address_range final : public virtio_net_address_range {
+    int m_tapfd = -1;
+
+public:
+    virtio_net_tuntap_address_range(uint64_t start, uint64_t length, uint32_t virtio_idx, const std::string &tap_name);
+
+    virtio_net_tuntap_address_range(const virtio_net_tuntap_address_range &other) = delete;
+    virtio_net_tuntap_address_range &operator=(const virtio_net_tuntap_address_range &other) = delete;
+    virtio_net_tuntap_address_range &operator=(virtio_net_tuntap_address_range &&other) = delete;
+
+    virtio_net_tuntap_address_range(virtio_net_tuntap_address_range &&other) = default;
+    ~virtio_net_tuntap_address_range() override;
+
+protected:
+    void net_reset() override;
+
+    void net_prepare_select(select_fd_sets *fds, uint64_t *timeout_us) override;
+    bool net_poll_selected(int select_ret, select_fd_sets *fds) override;
+
+    bool net_write_packet_to_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx, uint32_t read_avail_len,
+        uint32_t *pread_len) override;
+    bool net_read_packet_from_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx, uint32_t write_avail_len,
+        uint32_t *pwritten_len) override;
+};
+
+static inline auto make_virtio_net_tuntap_address_range(uint64_t start, uint64_t length, uint32_t virtio_idx,
+    const std::string &tap_name) {
+    return virtio_net_tuntap_address_range{start, length, virtio_idx, tap_name};
+}
+
+} // namespace cartesi
+
+#endif // HAVE_TUNTAP
+
+#endif
diff --git a/src/virtio-net-carrier-slirp.cpp b/src/virtio-net-user-address-range.cpp
similarity index 92%
rename from src/virtio-net-carrier-slirp.cpp
rename to src/virtio-net-user-address-range.cpp
index 4c51b1849..d5b03ec2b 100644
--- a/src/virtio-net-carrier-slirp.cpp
+++ b/src/virtio-net-user-address-range.cpp
@@ -53,7 +53,7 @@
 
 // #define DEBUG_VIRTIO_ERRORS
 
-#include "virtio-net-carrier-slirp.h"
+#include "virtio-net-user-address-range.h"
 
 #ifdef HAVE_SLIRP
 
@@ -74,8 +74,6 @@
 #include "i-device-state-access.h"
 #include "machine-config.h"
 #include "os.h"
-#include "virtio-device.h"
-#include "virtio-net.h"
 
 using namespace std::string_literals;
 
@@ -84,7 +82,7 @@ namespace cartesi {
 //??D why ssize_t?
 static ssize_t slirp_send_packet(const void *buf, size_t len, void *opaque) {
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-    auto *carrier = reinterpret_cast<virtio_net_carrier_slirp *>(opaque);
+    auto *carrier = reinterpret_cast<virtio_net_user_address_range *>(opaque);
     if (carrier->send_packets.size() >= SLIRP_MAX_PENDING_PACKETS) {
         // Too many send_packets in the write queue, we can just drop it.
         // Network re-transmission can recover from this.
@@ -130,7 +128,7 @@ static int64_t slirp_clock_get_ns(void * /*opaque*/) {
 
 static void *slirp_timer_new(SlirpTimerCb cb, void *cb_opaque, void *opaque) {
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-    auto *carrier = reinterpret_cast<virtio_net_carrier_slirp *>(opaque);
+    auto *carrier = reinterpret_cast<virtio_net_user_address_range *>(opaque);
     try {
         auto *timer = new slirp_timer;
         timer->cb = cb;
@@ -145,7 +143,7 @@ static void *slirp_timer_new(SlirpTimerCb cb, void *cb_opaque, void *opaque) {
 
 static void slirp_timer_free(void *timer_ptr, void *opaque) {
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-    auto *carrier = reinterpret_cast<virtio_net_carrier_slirp *>(opaque);
+    auto *carrier = reinterpret_cast<virtio_net_user_address_range *>(opaque);
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
     auto *timer = reinterpret_cast<slirp_timer *>(timer_ptr);
     if (timer != nullptr) {
@@ -159,7 +157,7 @@ static void slirp_timer_free(void *timer_ptr, void *opaque) {
 
 static void slirp_timer_mod(void *timer_ptr, int64_t expire_timer_msec, void *opaque) {
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-    auto *carrier = reinterpret_cast<virtio_net_carrier_slirp *>(opaque);
+    auto *carrier = reinterpret_cast<virtio_net_user_address_range *>(opaque);
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
     auto *timer = reinterpret_cast<slirp_timer *>(timer_ptr);
     if ((timer != nullptr) && carrier->timers.find(timer) != carrier->timers.end()) {
@@ -179,7 +177,10 @@ static void slirp_notify(void * /*opaque*/) {
     // Nothing to do
 }
 
-virtio_net_carrier_slirp::virtio_net_carrier_slirp(const cartesi::virtio_net_user_config &config) {
+virtio_net_user_address_range::virtio_net_user_address_range(uint64_t start, uint64_t length, uint32_t virtio_idx,
+    const cartesi::virtio_net_user_config &config) :
+    virtio_net_address_range("VirtIO Net User", start, length, virtio_idx) {
+
     // Configure slirp
     slirp_cfg.version = std::min<int>(SLIRP_CONFIG_VERSION_MAX, SLIRP_VERSION);
     slirp_cfg.restricted = 0;                                             // Don't isolate the guest from the host
@@ -226,7 +227,7 @@ virtio_net_carrier_slirp::virtio_net_carrier_slirp(const cartesi::virtio_net_use
     }
 }
 
-virtio_net_carrier_slirp::~virtio_net_carrier_slirp() {
+virtio_net_user_address_range::~virtio_net_user_address_range() {
     // Cleanup slirp
     if (slirp != nullptr) {
         slirp_cleanup(slirp);
@@ -239,7 +240,7 @@ virtio_net_carrier_slirp::~virtio_net_carrier_slirp() {
     timers.clear();
 }
 
-void virtio_net_carrier_slirp::reset() {
+void virtio_net_user_address_range::net_reset() {
     // Nothing to do, we don't want to reset slirp to not lose network state.
 }
 
@@ -282,7 +283,7 @@ static int slirp_get_revents_cb(int fd, void *opaque) {
     return event;
 }
 
-void virtio_net_carrier_slirp::do_prepare_select(select_fd_sets *fds, uint64_t *timeout_us) {
+void virtio_net_user_address_range::net_prepare_select(select_fd_sets *fds, uint64_t *timeout_us) {
     // Did device reset and slirp failed to reinitialize?
     if (slirp == nullptr) {
         return;
@@ -305,7 +306,7 @@ void virtio_net_carrier_slirp::do_prepare_select(select_fd_sets *fds, uint64_t *
     }
 }
 
-bool virtio_net_carrier_slirp::do_poll_selected(int select_ret, select_fd_sets *fds) {
+bool virtio_net_user_address_range::net_poll_selected(int select_ret, select_fd_sets *fds) {
     // Did device reset and slirp failed to reinitialize?
     if (slirp == nullptr) {
         return false;
@@ -332,7 +333,7 @@ bool virtio_net_carrier_slirp::do_poll_selected(int select_ret, select_fd_sets *
     return !send_packets.empty();
 }
 
-bool virtio_net_carrier_slirp::write_packet_to_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx,
+bool virtio_net_user_address_range::net_write_packet_to_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx,
     uint32_t read_avail_len, uint32_t *pread_len) {
     // Did device reset and slirp failed to reinitialize?
     if (slirp == nullptr) {
@@ -361,7 +362,7 @@ bool virtio_net_carrier_slirp::write_packet_to_host(i_device_state_access *a, vi
     return true;
 }
 
-bool virtio_net_carrier_slirp::read_packet_from_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx,
+bool virtio_net_user_address_range::net_read_packet_from_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx,
     uint32_t write_avail_len, uint32_t *pwritten_len) {
     // If no packet was send by slirp, we can just ignore.
     if (send_packets.empty()) {
diff --git a/src/virtio-net-carrier-slirp.h b/src/virtio-net-user-address-range.h
similarity index 61%
rename from src/virtio-net-carrier-slirp.h
rename to src/virtio-net-user-address-range.h
index c71aa3b49..9798ad66f 100644
--- a/src/virtio-net-carrier-slirp.h
+++ b/src/virtio-net-user-address-range.h
@@ -14,8 +14,8 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#ifndef VIRTIO_NET_CARRIER_SLIRP_H
-#define VIRTIO_NET_CARRIER_SLIRP_H
+#ifndef VIRTIO_NET_USER_ADDRESS_RANGE_H
+#define VIRTIO_NET_USER_ADDRESS_RANGE_H
 
 #include "os-features.h"
 
@@ -35,8 +35,7 @@
 #include "i-device-state-access.h"
 #include "machine-config.h"
 #include "os.h"
-#include "virtio-device.h"
-#include "virtio-net.h"
+#include "virtio-net-address-range.h"
 
 /// \brief Slirp constants
 enum slirp_constants {
@@ -66,7 +65,7 @@ struct slirp_packet {
     std::array<unsigned char, VIRTIO_NET_ETHERNET_MAX_LENGTH> buf{};
 };
 
-class virtio_net_carrier_slirp final : public virtio_net_carrier {
+class virtio_net_user_address_range final : public virtio_net_address_range {
 public:
     Slirp *slirp = nullptr;
     SlirpConfig slirp_cfg{};
@@ -74,24 +73,32 @@ class virtio_net_carrier_slirp final : public virtio_net_carrier {
     std::list<slirp_packet> send_packets;
     std::unordered_set<slirp_timer *> timers;
 
-    explicit virtio_net_carrier_slirp(const cartesi::virtio_net_user_config &config);
-    ~virtio_net_carrier_slirp() override;
-    virtio_net_carrier_slirp(const virtio_net_carrier_slirp &other) = delete;
-    virtio_net_carrier_slirp(virtio_net_carrier_slirp &&other) = delete;
-    virtio_net_carrier_slirp &operator=(const virtio_net_carrier_slirp &other) = delete;
-    virtio_net_carrier_slirp &operator=(virtio_net_carrier_slirp &&other) = delete;
+    virtio_net_user_address_range(uint64_t start, uint64_t length, uint32_t virtio_idx,
+        const virtio_net_user_config &config);
 
-    void reset() override;
+    virtio_net_user_address_range(const virtio_net_user_address_range &other) = delete;
+    virtio_net_user_address_range &operator=(const virtio_net_user_address_range &other) = delete;
+    virtio_net_user_address_range &operator=(virtio_net_user_address_range &&other) = delete;
 
-    void do_prepare_select(select_fd_sets *fds, uint64_t *timeout_us) override;
-    bool do_poll_selected(int select_ret, select_fd_sets *fds) override;
+    virtio_net_user_address_range(virtio_net_user_address_range &&other) = default;
+    ~virtio_net_user_address_range() override;
 
-    bool write_packet_to_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx, uint32_t read_avail_len,
+    void net_reset() override;
+
+    void net_prepare_select(select_fd_sets *fds, uint64_t *timeout_us) override;
+    bool net_poll_selected(int select_ret, select_fd_sets *fds) override;
+
+    bool net_write_packet_to_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx, uint32_t read_avail_len,
         uint32_t *pread_len) override;
-    bool read_packet_from_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx, uint32_t write_avail_len,
+    bool net_read_packet_from_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx, uint32_t write_avail_len,
         uint32_t *pwritten_len) override;
 };
 
+static inline auto make_virtio_net_user_address_range(uint64_t start, uint64_t length, uint32_t virtio_idx,
+    const virtio_net_user_config &config) {
+    return virtio_net_user_address_range{start, length, virtio_idx, config};
+}
+
 } // namespace cartesi
 
 #endif // HAVE_SLIRP
diff --git a/src/virtio-p9fs.cpp b/src/virtio-p9fs-address-range.cpp
similarity index 96%
rename from src/virtio-p9fs.cpp
rename to src/virtio-p9fs-address-range.cpp
index cba680a68..728066b30 100644
--- a/src/virtio-p9fs.cpp
+++ b/src/virtio-p9fs-address-range.cpp
@@ -32,7 +32,7 @@
 // Enable this define to debug VirtIO Plan 9 filesystem operations
 // #define DEBUG_VIRTIO_P9FS
 
-#include "virtio-p9fs.h"
+#include "virtio-p9fs-address-range.h"
 
 #ifdef HAVE_POSIX_FS
 
@@ -68,7 +68,7 @@
 #include <unistd.h>
 
 #include "i-device-state-access.h"
-#include "virtio-device.h"
+#include "virtio-address-range.h"
 #include "virtio-serializer.h"
 
 #ifdef _WIN32
@@ -1056,9 +1056,10 @@ static bool is_name_legal(const std::string &name) {
     return true;
 }
 
-virtio_p9fs_device::virtio_p9fs_device(uint32_t virtio_idx, const std::string &mount_tag,
-    const std::string &root_path) :
-    virtio_device(virtio_idx, VIRTIO_DEVICE_9P, VIRTIO_9P_F_MOUNT_TAG, mount_tag.length() + sizeof(uint16_t)),
+virtio_p9fs_address_range::virtio_p9fs_address_range(uint64_t start, uint64_t length, uint32_t virtio_idx,
+    const std::string &mount_tag, const std::string &root_path) :
+    virtio_address_range("VirtIO 9P", start, length, virtio_idx, VIRTIO_DEVICE_9P, VIRTIO_9P_F_MOUNT_TAG,
+        mount_tag.length() + sizeof(uint16_t)),
     m_msize(P9_MAX_MSIZE),
     m_root_path(root_path) {
     if (root_path.length() + 1 >= P9_ROOT_PATH_MAX) {
@@ -1077,7 +1078,7 @@ virtio_p9fs_device::virtio_p9fs_device(uint32_t virtio_idx, const std::string &m
     config->mount_tag_len = mount_tag.length();
 }
 
-virtio_p9fs_device::~virtio_p9fs_device() {
+virtio_p9fs_address_range::~virtio_p9fs_address_range() {
     // Close all file descriptors
     for (auto &it : m_fids) {
         p9_fid_state *fidp = &it.second;
@@ -1086,7 +1087,7 @@ virtio_p9fs_device::~virtio_p9fs_device() {
     m_fids.clear();
 }
 
-void virtio_p9fs_device::on_device_reset() {
+void virtio_p9fs_address_range::on_device_reset() {
     m_msize = P9_MAX_MSIZE;
     // Close all file descriptors
     for (auto &it : m_fids) {
@@ -1096,12 +1097,12 @@ void virtio_p9fs_device::on_device_reset() {
     m_fids.clear();
 }
 
-void virtio_p9fs_device::on_device_ok(i_device_state_access * /*a*/) {
+void virtio_p9fs_address_range::on_device_ok(i_device_state_access * /*a*/) {
     // Nothing to do.
 }
 
-bool virtio_p9fs_device::on_device_queue_available(i_device_state_access *a, uint32_t queue_idx, uint16_t desc_idx,
-    uint32_t /*read_avail_len*/, uint32_t /*write_avail_len*/) {
+bool virtio_p9fs_address_range::on_device_queue_available(i_device_state_access *a, uint32_t queue_idx,
+    uint16_t desc_idx, uint32_t /*read_avail_len*/, uint32_t /*write_avail_len*/) {
     // We are only interested in queue 0 notifications
     if (queue_idx != 0) {
         return false;
@@ -1194,7 +1195,7 @@ bool virtio_p9fs_device::on_device_queue_available(i_device_state_access *a, uin
     }
 }
 
-bool virtio_p9fs_device::op_statfs(virtq_unserializer &&mmsg, uint16_t tag) {
+bool virtio_p9fs_address_range::op_statfs(virtq_unserializer &&mmsg, uint16_t tag) {
     virtq_unserializer msg = std::move(mmsg);
     uint32_t fid{};
     if (!msg.unpack(&fid)) {
@@ -1248,7 +1249,7 @@ bool virtio_p9fs_device::op_statfs(virtq_unserializer &&mmsg, uint16_t tag) {
 #endif
 }
 
-bool virtio_p9fs_device::op_lopen(virtq_unserializer &&mmsg, uint16_t tag) {
+bool virtio_p9fs_address_range::op_lopen(virtq_unserializer &&mmsg, uint16_t tag) {
     virtq_unserializer msg = std::move(mmsg);
     uint32_t fid{};
     uint32_t flags{};
@@ -1324,7 +1325,7 @@ bool virtio_p9fs_device::op_lopen(virtq_unserializer &&mmsg, uint16_t tag) {
     return true;
 }
 
-bool virtio_p9fs_device::op_lcreate(virtq_unserializer &&mmsg, uint16_t tag) {
+bool virtio_p9fs_address_range::op_lcreate(virtq_unserializer &&mmsg, uint16_t tag) {
     virtq_unserializer msg = std::move(mmsg);
     uint32_t fid{};
     uint32_t flags{};
@@ -1392,7 +1393,7 @@ bool virtio_p9fs_device::op_lcreate(virtq_unserializer &&mmsg, uint16_t tag) {
     return true;
 }
 
-bool virtio_p9fs_device::op_symlink(virtq_unserializer &&mmsg, uint16_t tag) {
+bool virtio_p9fs_address_range::op_symlink(virtq_unserializer &&mmsg, uint16_t tag) {
     virtq_unserializer msg = std::move(mmsg);
     uint32_t dfid{};
     uint32_t gid{};
@@ -1447,7 +1448,7 @@ bool virtio_p9fs_device::op_symlink(virtq_unserializer &&mmsg, uint16_t tag) {
 #endif
 }
 
-bool virtio_p9fs_device::op_mknod(virtq_unserializer &&mmsg, uint16_t tag) {
+bool virtio_p9fs_address_range::op_mknod(virtq_unserializer &&mmsg, uint16_t tag) {
     virtq_unserializer msg = std::move(mmsg);
     uint32_t dfid{};
     uint32_t mode{};
@@ -1505,7 +1506,7 @@ bool virtio_p9fs_device::op_mknod(virtq_unserializer &&mmsg, uint16_t tag) {
 #endif
 }
 
-bool virtio_p9fs_device::op_setattr(virtq_unserializer &&mmsg, uint16_t tag) {
+bool virtio_p9fs_address_range::op_setattr(virtq_unserializer &&mmsg, uint16_t tag) {
     virtq_unserializer msg = std::move(mmsg);
     uint32_t fid{};
     uint32_t mask{};
@@ -1646,7 +1647,7 @@ bool virtio_p9fs_device::op_setattr(virtq_unserializer &&mmsg, uint16_t tag) {
     return send_ok(msg, tag, P9_RSETATTR);
 }
 
-bool virtio_p9fs_device::op_readlink(virtq_unserializer &&mmsg, uint16_t tag) {
+bool virtio_p9fs_address_range::op_readlink(virtq_unserializer &&mmsg, uint16_t tag) {
     virtq_unserializer msg = std::move(mmsg);
     uint32_t fid{};
     if (!msg.unpack(&fid)) {
@@ -1679,7 +1680,7 @@ bool virtio_p9fs_device::op_readlink(virtq_unserializer &&mmsg, uint16_t tag) {
 #endif
 }
 
-bool virtio_p9fs_device::op_getattr(virtq_unserializer &&mmsg, uint16_t tag) {
+bool virtio_p9fs_address_range::op_getattr(virtq_unserializer &&mmsg, uint16_t tag) {
     virtq_unserializer msg = std::move(mmsg);
     uint32_t fid{};
     uint64_t mask{};
@@ -1789,7 +1790,7 @@ bool virtio_p9fs_device::op_getattr(virtq_unserializer &&mmsg, uint16_t tag) {
     return send_reply(std::move(out_msg), tag, P9_RGETATTR);
 }
 
-bool virtio_p9fs_device::op_lock(virtq_unserializer &&mmsg, uint16_t tag) {
+bool virtio_p9fs_address_range::op_lock(virtq_unserializer &&mmsg, uint16_t tag) {
     virtq_unserializer msg = std::move(mmsg);
     uint32_t fid{};
     uint8_t type{};
@@ -1847,7 +1848,7 @@ bool virtio_p9fs_device::op_lock(virtq_unserializer &&mmsg, uint16_t tag) {
 #endif
 }
 
-bool virtio_p9fs_device::op_getlock(virtq_unserializer &&mmsg, uint16_t tag) {
+bool virtio_p9fs_address_range::op_getlock(virtq_unserializer &&mmsg, uint16_t tag) {
     virtq_unserializer msg = std::move(mmsg);
     uint32_t fid{};
     uint8_t type{};
@@ -1891,7 +1892,7 @@ bool virtio_p9fs_device::op_getlock(virtq_unserializer &&mmsg, uint16_t tag) {
 #endif
 }
 
-bool virtio_p9fs_device::op_readdir(virtq_unserializer &&mmsg, uint16_t tag) {
+bool virtio_p9fs_address_range::op_readdir(virtq_unserializer &&mmsg, uint16_t tag) {
     virtq_unserializer msg = std::move(mmsg);
     uint32_t fid{};
     uint64_t offset{};
@@ -2000,7 +2001,7 @@ bool virtio_p9fs_device::op_readdir(virtq_unserializer &&mmsg, uint16_t tag) {
     return send_reply(std::move(out_msg), tag, P9_RREADDIR);
 }
 
-bool virtio_p9fs_device::op_fsync(virtq_unserializer &&mmsg, uint16_t tag) {
+bool virtio_p9fs_address_range::op_fsync(virtq_unserializer &&mmsg, uint16_t tag) {
     virtq_unserializer msg = std::move(mmsg);
     uint32_t fid{};
     if (!msg.unpack(&fid)) {
@@ -2022,7 +2023,7 @@ bool virtio_p9fs_device::op_fsync(virtq_unserializer &&mmsg, uint16_t tag) {
     return send_ok(msg, tag, P9_RFSYNC);
 }
 
-bool virtio_p9fs_device::op_link(virtq_unserializer &&mmsg, uint16_t tag) {
+bool virtio_p9fs_address_range::op_link(virtq_unserializer &&mmsg, uint16_t tag) {
     virtq_unserializer msg = std::move(mmsg);
     uint32_t dfid{};
     uint32_t fid{};
@@ -2060,7 +2061,7 @@ bool virtio_p9fs_device::op_link(virtq_unserializer &&mmsg, uint16_t tag) {
 #endif
 }
 
-bool virtio_p9fs_device::op_mkdir(virtq_unserializer &&mmsg, uint16_t tag) {
+bool virtio_p9fs_address_range::op_mkdir(virtq_unserializer &&mmsg, uint16_t tag) {
     virtq_unserializer msg = std::move(mmsg);
     uint32_t dfid{};
     uint32_t mode{};
@@ -2116,7 +2117,7 @@ bool virtio_p9fs_device::op_mkdir(virtq_unserializer &&mmsg, uint16_t tag) {
     return true;
 }
 
-bool virtio_p9fs_device::op_renameat(virtq_unserializer &&mmsg, uint16_t tag) {
+bool virtio_p9fs_address_range::op_renameat(virtq_unserializer &&mmsg, uint16_t tag) {
     virtq_unserializer msg = std::move(mmsg);
     uint32_t oldfid{};
     uint32_t newfid{};
@@ -2162,7 +2163,7 @@ bool virtio_p9fs_device::op_renameat(virtq_unserializer &&mmsg, uint16_t tag) {
     return true;
 }
 
-bool virtio_p9fs_device::op_unlinkat(virtq_unserializer &&mmsg, uint16_t tag) {
+bool virtio_p9fs_address_range::op_unlinkat(virtq_unserializer &&mmsg, uint16_t tag) {
     virtq_unserializer msg = std::move(mmsg);
     uint32_t dfid{};
     uint32_t flags{};
@@ -2196,7 +2197,7 @@ bool virtio_p9fs_device::op_unlinkat(virtq_unserializer &&mmsg, uint16_t tag) {
     return send_ok(msg, tag, P9_RUNLINKAT);
 }
 
-bool virtio_p9fs_device::op_version(virtq_unserializer &&mmsg, uint16_t tag) {
+bool virtio_p9fs_address_range::op_version(virtq_unserializer &&mmsg, uint16_t tag) {
     virtq_unserializer msg = std::move(mmsg);
     char version[32]{};
     uint32_t msize{};
@@ -2217,7 +2218,7 @@ bool virtio_p9fs_device::op_version(virtq_unserializer &&mmsg, uint16_t tag) {
     return send_reply(std::move(out_msg), tag, P9_RVERSION);
 }
 
-bool virtio_p9fs_device::op_attach(virtq_unserializer &&mmsg, uint16_t tag) {
+bool virtio_p9fs_address_range::op_attach(virtq_unserializer &&mmsg, uint16_t tag) {
     virtq_unserializer msg = std::move(mmsg);
     uint32_t fid{};
     uint32_t afid{};
@@ -2259,7 +2260,7 @@ bool virtio_p9fs_device::op_attach(virtq_unserializer &&mmsg, uint16_t tag) {
     return true;
 }
 
-bool virtio_p9fs_device::op_walk(virtq_unserializer &&mmsg, uint16_t tag) {
+bool virtio_p9fs_address_range::op_walk(virtq_unserializer &&mmsg, uint16_t tag) {
     virtq_unserializer msg = std::move(mmsg);
     uint32_t fid{};
     uint32_t newfid{};
@@ -2356,7 +2357,7 @@ bool virtio_p9fs_device::op_walk(virtq_unserializer &&mmsg, uint16_t tag) {
     return true;
 }
 
-bool virtio_p9fs_device::op_read(virtq_unserializer &&mmsg, uint16_t tag) {
+bool virtio_p9fs_address_range::op_read(virtq_unserializer &&mmsg, uint16_t tag) {
     virtq_unserializer msg = std::move(mmsg);
     uint32_t fid{};
     uint64_t offset{};
@@ -2391,7 +2392,7 @@ bool virtio_p9fs_device::op_read(virtq_unserializer &&mmsg, uint16_t tag) {
     return send_reply(std::move(out_msg), tag, P9_RREAD);
 }
 
-bool virtio_p9fs_device::op_write(virtq_unserializer &&mmsg, uint16_t tag) {
+bool virtio_p9fs_address_range::op_write(virtq_unserializer &&mmsg, uint16_t tag) {
     virtq_unserializer msg = std::move(mmsg);
     uint32_t fid{};
     uint64_t offset{};
@@ -2426,7 +2427,7 @@ bool virtio_p9fs_device::op_write(virtq_unserializer &&mmsg, uint16_t tag) {
     return send_reply(std::move(out_msg), tag, P9_RREAD);
 }
 
-bool virtio_p9fs_device::op_clunk(virtq_unserializer &&mmsg, uint16_t tag) {
+bool virtio_p9fs_address_range::op_clunk(virtq_unserializer &&mmsg, uint16_t tag) {
     virtq_unserializer msg = std::move(mmsg);
     uint32_t fid{};
     if (!msg.unpack(&fid)) {
@@ -2452,7 +2453,7 @@ bool virtio_p9fs_device::op_clunk(virtq_unserializer &&mmsg, uint16_t tag) {
     return send_ok(msg, tag, P9_RCLUNK);
 }
 
-bool virtio_p9fs_device::send_reply(virtq_serializer &&mout_msg, uint16_t tag, p9_opcode opcode) {
+bool virtio_p9fs_address_range::send_reply(virtq_serializer &&mout_msg, uint16_t tag, p9_opcode opcode) {
     virtq_serializer out_msg = std::move(mout_msg);
 #ifdef DEBUG_VIRTIO_P9FS
     if (opcode != P9_RLERROR) {
@@ -2477,12 +2478,12 @@ bool virtio_p9fs_device::send_reply(virtq_serializer &&mout_msg, uint16_t tag, p
     return true;
 }
 
-bool virtio_p9fs_device::send_ok(const virtq_unserializer &in_msg, uint16_t tag, p9_opcode opcode) {
+bool virtio_p9fs_address_range::send_ok(const virtq_unserializer &in_msg, uint16_t tag, p9_opcode opcode) {
     virtq_serializer out_msg(in_msg.a, in_msg.vq, in_msg.queue_idx, in_msg.desc_idx, P9_OUT_MSG_OFFSET);
     return send_reply(std::move(out_msg), tag, opcode);
 }
 
-bool virtio_p9fs_device::send_error(const virtq_unserializer &in_msg, uint16_t tag, p9_error error) {
+bool virtio_p9fs_address_range::send_error(const virtq_unserializer &in_msg, uint16_t tag, p9_error error) {
 #ifdef DEBUG_VIRTIO_P9FS
     if (error == P9_EPROTO) {
         std::ignore = fprintf(stderr, "p9fs PROTOCOL ERROR: tag=%d\n", tag);
diff --git a/src/virtio-p9fs.h b/src/virtio-p9fs-address-range.h
similarity index 94%
rename from src/virtio-p9fs.h
rename to src/virtio-p9fs-address-range.h
index 761727a31..1fe94b9ac 100644
--- a/src/virtio-p9fs.h
+++ b/src/virtio-p9fs-address-range.h
@@ -14,8 +14,8 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#ifndef VIRTIO_P9FS_H
-#define VIRTIO_P9FS_H
+#ifndef VIRTIO_P9FS_ADDRESS_RANGE_H
+#define VIRTIO_P9FS_ADDRESS_RANGE_H
 
 #include "os-features.h"
 
@@ -29,7 +29,7 @@
 
 #include "compiler-defines.h"
 #include "i-device-state-access.h"
-#include "virtio-device.h"
+#include "virtio-address-range.h"
 #include "virtio-serializer.h"
 
 namespace cartesi {
@@ -396,18 +396,21 @@ struct virtio_p9fs_config_space {
 };
 
 /// \brief VirtIO Plan 9 filesystem device
-class virtio_p9fs_device final : public virtio_device {
+class virtio_p9fs_address_range final : public virtio_address_range {
     uint32_t m_msize = 0;
     std::string m_root_path;
     std::unordered_map<uint32_t, p9_fid_state> m_fids;
 
 public:
-    virtio_p9fs_device(uint32_t virtio_idx, const std::string &mount_tag, const std::string &root_path);
-    ~virtio_p9fs_device() override;
-    virtio_p9fs_device(const virtio_p9fs_device &other) = delete;
-    virtio_p9fs_device(virtio_p9fs_device &&other) = delete;
-    virtio_p9fs_device &operator=(const virtio_p9fs_device &other) = delete;
-    virtio_p9fs_device &operator=(virtio_p9fs_device &&other) = delete;
+    virtio_p9fs_address_range(uint64_t start, uint64_t length, uint32_t virtio_idx, const std::string &mount_tag,
+        const std::string &root_path);
+
+    virtio_p9fs_address_range(const virtio_p9fs_address_range &other) = delete;
+    virtio_p9fs_address_range &operator=(const virtio_p9fs_address_range &other) = delete;
+    virtio_p9fs_address_range &operator=(virtio_p9fs_address_range &&other) = delete;
+
+    virtio_p9fs_address_range(virtio_p9fs_address_range &&other) = default;
+    ~virtio_p9fs_address_range() override;
 
     void on_device_reset() override;
     void on_device_ok(i_device_state_access *a) override;
@@ -456,8 +459,13 @@ class virtio_p9fs_device final : public virtio_device {
     }
 };
 
+static inline auto make_virtio_p9fs_address_range(uint64_t start, uint64_t length, uint32_t virtio_idx,
+    const std::string &mount_tag, const std::string &root_path) {
+    return virtio_p9fs_address_range{start, length, virtio_idx, mount_tag, root_path};
+}
+
 } // namespace cartesi
 
 #endif // HAVE_POSIX_FS
 
-#endif
+#endif // VIRTIO_P9FS_ADDRESS_RANGE_H
diff --git a/src/virtio-serializer.h b/src/virtio-serializer.h
index c5624ecd8..32942c85c 100644
--- a/src/virtio-serializer.h
+++ b/src/virtio-serializer.h
@@ -22,7 +22,7 @@
 #include <cstring>
 
 #include "i-device-state-access.h"
-#include "virtio-device.h"
+#include "virtio-address-range.h"
 
 namespace cartesi {
 
diff --git a/src/virtual-machine.cpp b/src/virtual-machine.cpp
index 0c4d4f3c3..b2ff88abd 100644
--- a/src/virtual-machine.cpp
+++ b/src/virtual-machine.cpp
@@ -20,10 +20,10 @@
 #include <string>
 
 #include "access-log.h"
+#include "address-range-description.h"
 #include "i-virtual-machine.h"
 #include "interpret.h"
 #include "machine-config.h"
-#include "machine-memory-range-descr.h"
 #include "machine-merkle-tree.h"
 #include "machine-runtime-config.h"
 #include "machine.h"
@@ -163,8 +163,8 @@ uarch_interpreter_break_reason virtual_machine::do_run_uarch(uint64_t uarch_cycl
     return get_machine()->run_uarch(uarch_cycle_end);
 }
 
-machine_memory_range_descrs virtual_machine::do_get_memory_ranges() const {
-    return get_machine()->get_memory_ranges();
+address_range_descriptions virtual_machine::do_get_address_ranges() const {
+    return get_machine()->get_address_ranges();
 }
 
 void virtual_machine::do_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length) {
diff --git a/src/virtual-machine.h b/src/virtual-machine.h
index 64e9340c7..b3096af03 100644
--- a/src/virtual-machine.h
+++ b/src/virtual-machine.h
@@ -21,10 +21,10 @@
 #include <string>
 
 #include "access-log.h"
+#include "address-range-description.h"
 #include "i-virtual-machine.h"
 #include "interpret.h"
 #include "machine-config.h"
-#include "machine-memory-range-descr.h"
 #include "machine-merkle-tree.h"
 #include "machine-runtime-config.h"
 #include "machine.h"
@@ -72,7 +72,7 @@ class virtual_machine : public i_virtual_machine {
     void do_reset_uarch() override;
     access_log do_log_reset_uarch(const access_log::type &log_type) override;
     uarch_interpreter_break_reason do_run_uarch(uint64_t uarch_cycle_end) override;
-    machine_memory_range_descrs do_get_memory_ranges() const override;
+    address_range_descriptions do_get_address_ranges() const override;
     void do_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length) override;
     access_log do_log_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
         const access_log::type &log_type) override;
diff --git a/tests/lua/cartesi/tests/util.lua b/tests/lua/cartesi/tests/util.lua
index b63eac9b6..b5398d0f7 100644
--- a/tests/lua/cartesi/tests/util.lua
+++ b/tests/lua/cartesi/tests/util.lua
@@ -249,7 +249,7 @@ test_util.merkle_hash = merkle_hash
 function test_util.calculate_emulator_hash(machine)
     local tree = test_util.new_back_merkle_tree(64, PAGE_LOG2_SIZE)
     local last = 0
-    for _, v in ipairs(machine:get_memory_ranges()) do
+    for _, v in ipairs(machine:get_address_ranges()) do
         tree:pad_back((v.start - last) >> PAGE_LOG2_SIZE)
         local finish = v.start + v.length
         for j = v.start, finish - 1, PAGE_SIZE do
diff --git a/tests/lua/create-machines.lua b/tests/lua/create-machines.lua
index 10175d2bd..bf33183b5 100755
--- a/tests/lua/create-machines.lua
+++ b/tests/lua/create-machines.lua
@@ -213,9 +213,11 @@ rollup-init sh /home/dapp/s.sh
 )
 
 -- Should not work with shared buffers
-create_machine("shared-rx-buffer-machine", "rollup accept", function(config)
+local ret, err = pcall(create_machine, "shared-rx-buffer-machine", "rollup accept", function(config)
     config.cmio.rx_buffer.shared = true
 end)
-create_machine("shared-tx-buffer-machine", "rollup accept", function(config)
+assert(not ret, "should have failed")
+ret, err = pcall(create_machine, "shared-tx-buffer-machine", "rollup accept", function(config)
     config.cmio.tx_buffer.shared = true
 end)
+assert(not ret, "should have failed")
diff --git a/tests/lua/machine-bind.lua b/tests/lua/machine-bind.lua
index 8e050748b..58a7587de 100755
--- a/tests/lua/machine-bind.lua
+++ b/tests/lua/machine-bind.lua
@@ -25,7 +25,7 @@ local remote_address
 local test_path = "./"
 local concurrency_update_merkle_tree = util.parse_number(os.getenv("CARTESI_CONCURRENCY_UPDATE_MERKLE_TREE")) or 0
 
--- local lua_cmd = arg[-1] .. " -e "
+local lua_cmd = arg[-1] .. " -e "
 
 -- There is no UINT64_MAX in Lua, so we have to use the signed representation
 local MAX_MCYCLE = -1
@@ -642,9 +642,12 @@ end)
 print("\n\n check memory reading/writing")
 do_test("written and read values should match", function(machine)
     -- Check mem write and mem read
-    machine:write_memory(0x800000FF, "mydataol12345678", 0x10)
-    local memory_read = machine:read_memory(0x800000FF, 0x10)
-    assert(memory_read == "mydataol12345678")
+    local written = "mydataol12345678"
+    machine:write_memory(0x800000FF, written)
+    local read = machine:read_memory(0x800000FF, written:len())
+    if read ~= written then
+        error(string.format("expected %q (got %q)", written, read))
+    end
 end)
 
 print("\n\n dump step log to console")
@@ -1101,7 +1104,6 @@ test_util.make_do_test(build_machine, machine_type, {
     check_error_find(err, "illegal instruction")
 end)
 
---[==[
 do_test("uarch ecall putchar should print char to console", function()
     local lua_code = [[ "
                                  local cartesi = require 'cartesi'
@@ -1110,9 +1112,9 @@ do_test("uarch ecall putchar should print char to console", function()
                                  local initial_reg_values = {}
                                  local program = {
                                     (cartesi.UARCH_ECALL_FN_PUTCHAR << 20) | 0x00893, -- li	a7,putchar
-                                    0x05800813, -- li	a6,'X''
+                                    0x05800513, -- li a0,'X'
                                     0x00000073, -- ecall
-                                }
+                                 }
                                  local uarch_ram_path = test_util.create_test_uarch_program(program)
                                  local machine = cartesi.machine {
                                  processor = initial_reg_values,
@@ -1134,7 +1136,6 @@ do_test("uarch ecall putchar should print char to console", function()
     print("--------------------------")
     assert(output == expected_output, "Output does not match expected output:\n" .. expected_output)
 end)
---]==]
 
 print("\n\ntesting send cmio response ")
 
@@ -1172,6 +1173,14 @@ local function assert_access(accesses, index, expected_key_and_values)
     end
 end
 
+local function dump_pmas(machine)
+    for _, v in ipairs(machine:get_address_ranges()) do
+        local filename = string.format("%016x--%016x.bin", v.start, v.length)
+        local file <close> = assert(io.open(filename, "w"))
+        assert(file:write(machine:read_memory(v.start, v.length)))
+    end
+end
+
 local function test_send_cmio_input_with_different_arguments()
     local data = string.rep("a", 1 << cartesi.PMA_CMIO_RX_BUFFER_LOG2_SIZE)
     local reason = 1
@@ -1213,6 +1222,7 @@ local function test_send_cmio_input_with_different_arguments()
                     | (large_data and cartesi.ACCESS_LOG_TYPE_LARGE_DATA or 0)
                 assert_before_cmio_response_sent(machine)
                 local root_hash_before = machine:get_root_hash()
+                dump_pmas(machine)
                 local log = machine:log_send_cmio_response(reason, data, log_type)
                 assert_after_cmio_response_sent(machine)
                 local root_hash_after = machine:get_root_hash()
diff --git a/tests/lua/machine-test.lua b/tests/lua/machine-test.lua
index 8b608ce09..7520c9e4c 100755
--- a/tests/lua/machine-test.lua
+++ b/tests/lua/machine-test.lua
@@ -197,7 +197,7 @@ do_test("proof check should pass", function(machine)
 
     -- Find ram memory range
     local ram
-    for _, v in ipairs(machine:get_memory_ranges()) do
+    for _, v in ipairs(machine:get_address_ranges()) do
         if v.description == "RAM" then
             ram = v
         end
@@ -350,26 +350,28 @@ test_util.make_do_test(build_machine, machine_type, {
         },
     },
 })("should replace flash drive and read something", function(machine)
-    local rootfs_length = machine:get_initial_config().flash_drive[1].length
+    local rootfs = machine:get_initial_config().flash_drive[1]
     -- Create temp flash file
     local input_path = test_path .. "input.raw"
-    local command = "echo 'test data 1234567890' > "
+    local replaced_data = 'test data 1234567890'
+    local command = string.format("echo '%s' > ", replaced_data)
         .. input_path
         .. " && truncate -s "
-        .. tostring(rootfs_length)
+        .. tostring(rootfs.length)
         .. " "
         .. input_path
     local p = assert(io.popen(command))
     p:close()
 
-    local flash_address_start = 0x80000000000000
+    machine:read_memory(rootfs.start, 20)
 
-    machine:read_memory(flash_address_start, 20)
+    machine:replace_memory_range(rootfs.start, rootfs.length, true, input_path)
 
-    machine:replace_memory_range(flash_address_start, rootfs_length, true, input_path)
+    local read_data = machine:read_memory(rootfs.start, 20)
 
-    local flash_data = machine:read_memory(flash_address_start, 20)
-    assert(flash_data == "test data 1234567890", "data read from replaced flash failed")
+    if (read_data ~= replaced_data) then
+        error(string.format("expected to read %q from replaced drive (got %q)", replaced_data, read_data))
+    end
     os.remove(input_path)
 end)
 
diff --git a/tests/misc/Makefile b/tests/misc/Makefile
index f4a2eeffb..84b6a8f4f 100644
--- a/tests/misc/Makefile
+++ b/tests/misc/Makefile
@@ -95,7 +95,7 @@ CLANG_FORMAT=clang-format
 CLANG_FORMAT_FILES:=$(wildcard *.cpp) $(wildcard *.h)
 
 INCS=-I../../src -I../../third-party/tiny_sha3 -I../../third-party/nlohmann-json -I../../third-party/downloads
-WARNS=-Wall -Wpedantic
+WARNS=-Wall -Wpedantic $(BOOST_INC)
 
 CXXFLAGS+=-O2 -g -std=gnu++20 -fvisibility=hidden $(INCS) $(UBFLAGS) $(WARNS)
 
@@ -109,11 +109,17 @@ all: $(BUILDDIR)/test-merkle-tree-hash $(BUILDDIR)/test-machine-c-api
 	$(info libcartesi.a and/or libcartesi_merkle_tree.a were not found! Build them first.)
 	@exit 1
 
-$(BUILDDIR)/test-merkle-tree-hash: test-merkle-tree-hash.cpp ../../src/libcartesi.a ../../src/libcartesi_merkle_tree.a
+$(BUILDDIR)/test-merkle-tree-hash: test-merkle-tree-hash.o ../../src/libcartesi.a ../../src/libcartesi_merkle_tree.a
 	$(CXX) -o $@ $^ $(CXXFLAGS)
 
-$(BUILDDIR)/test-machine-c-api: test-machine-c-api.cpp ../../src/libcartesi.a ../../src/libcartesi_merkle_tree.a
-	$(CXX) -o $@ $^ $(CXXFLAGS) $(BOOST_INC) $(LIBCARTESI_LIBS)
+$(BUILDDIR)/test-machine-c-api: test-machine-c-api.o ../../src/libcartesi.a ../../src/libcartesi_merkle_tree.a
+	$(CXX) -o $@ $^ $(CXXFLAGS) $(LIBCARTESI_LIBS)
+
+%.o: %.cpp
+	$(CXX) $(CXXFLAGS) -c -o $@ $<
+
+%.o: %.c
+	$(CC) $(CFLAGS) -c -o $@ $<
 
 %.clang-tidy: %.cpp
 	@$(CLANG_TIDY) --header-filter='$(CLANG_TIDY_HEADER_FILTER)' $(CLANG_TIDY_FLAGS) $< -- $(CXXFLAGS) $(BOOST_INC) 2>/dev/null
diff --git a/tests/misc/test-machine-c-api.cpp b/tests/misc/test-machine-c-api.cpp
index 2be54e96c..cf806288c 100644
--- a/tests/misc/test-machine-c-api.cpp
+++ b/tests/misc/test-machine-c-api.cpp
@@ -145,16 +145,13 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(create_machine_null_machine_test, incomplete_mach
 }
 
 BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_pma_overlapping_test, incomplete_machine_fixture) {
-    _machine_config["flash_drive"] =
-        nlohmann::json{nlohmann::json{nlohmann::json{"start", 0x80000000000000}, nlohmann::json{"length", 0x3c00000},
-                           nlohmann::json{"shared", true}},
-            nlohmann::json{nlohmann::json{"start", 0x7ffffffffff000}, nlohmann::json{"length", 0x2000},
-                nlohmann::json{"shared", true}}};
+    _machine_config["flash_drive"] = nlohmann::json{{{"start", 0x80000000000000}, {"length", 0x3c00000}},
+        {{"start", 0x7ffffffffff000}, {"length", 0x2000}}};
     cm_error error_code = cm_create_new(_machine_config.dump().c_str(), nullptr, &_machine);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 
     std::string result = cm_get_last_error_message();
-    std::string origin("range of flash drive 1 overlaps with range of existing flash drive 0");
+    std::string origin("address range of flash drive 1 overlaps with address range of existing flash drive 0");
     BOOST_CHECK_EQUAL(origin, result);
 }
 
@@ -162,7 +159,7 @@ class machine_flash_simple_fixture : public incomplete_machine_fixture {
 public:
     machine_flash_simple_fixture() {
         _machine_config["flash_drive"] = {
-            {{"start", 0x80000000000000}, {"length", 0x3c00000}, {"shared", true}, {"image_filename", ""}}};
+            {{"start", 0x80000000000000}, {"length", 0x3c00000}, {"shared", false}, {"image_filename", ""}}};
     }
 
     machine_flash_simple_fixture(const machine_flash_simple_fixture &other) = delete;
@@ -178,7 +175,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_invalid_alignment_test, mach
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 
     std::string result = cm_get_last_error_message();
-    std::string origin("start of flash drive 0 (36028797018963967) must be aligned to page boundary of 4096 bytes");
+    std::string origin("start of flash drive 0 (0x7fffffffffffff) must be aligned to page boundary of 4096 bytes");
     BOOST_CHECK_EQUAL(origin, result);
 }
 
@@ -190,7 +187,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_not_addressable_test, machin
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 
     std::string result = cm_get_last_error_message();
-    std::string origin("range of flash drive 0 must use at most 56 bits to be addressable");
+    std::string origin("address range of flash drive 0 must use at most 56 bits to be addressable");
     BOOST_CHECK_EQUAL(origin, result);
 }
 
diff --git a/tests/misc/test-utils.h b/tests/misc/test-utils.h
index 660ada53e..9934c0fd4 100644
--- a/tests/misc/test-utils.h
+++ b/tests/misc/test-utils.h
@@ -92,10 +92,10 @@ static hash_type calculate_emulator_hash(cm_machine *machine) {
     std::string page;
     page.resize(detail::MERKLE_PAGE_SIZE);
     const char *ranges_jsonstr{};
-    if (cm_get_memory_ranges(machine, &ranges_jsonstr) != 0) {
+    if (cm_get_address_ranges(machine, &ranges_jsonstr) != 0) {
         throw std::runtime_error{cm_get_last_error_message()};
     }
-    const auto mrds = cartesi::from_json<cartesi::machine_memory_range_descrs>(ranges_jsonstr);
+    const auto mrds = cartesi::from_json<cartesi::address_range_descriptions>(ranges_jsonstr);
     uint64_t last = 0;
     for (auto m : mrds) {
         tree.pad_back((m.start - last) >> detail::MERKLE_PAGE_LOG2_SIZE);
diff --git a/uarch/Makefile b/uarch/Makefile
index 6b93c1d7a..43aef034b 100644
--- a/uarch/Makefile
+++ b/uarch/Makefile
@@ -58,7 +58,9 @@ CFLAGS := -march=rv64i -mabi=lp64 -Wl,--gc-sections $(OPTFLAGS) $(UBFLAGS) $(WAR
 	$(UARCH_DEFS) \
 	$(TOOLCHAIN_INCS)
 
-CXXFLAGS := -std=c++20 -fno-rtti
+CXXFLAGS := -std=c++20 -fno-rtti \
+	-fno-threadsafe-statics \
+	-fno-use-cxa-atexit
 
 UARCH_SOURCES=\
 	third-party/printf/printf.c \
@@ -68,13 +70,9 @@ UARCH_SOURCES=\
 
 EMULATOR_SOURCES=\
 	$(EMULATOR_SRC_DIR)/interpret.cpp \
-	$(EMULATOR_SRC_DIR)/pma-driver.cpp \
-	$(EMULATOR_SRC_DIR)/htif.cpp \
-	$(EMULATOR_SRC_DIR)/shadow-tlb.cpp \
-	$(EMULATOR_SRC_DIR)/shadow-state.cpp \
-	$(EMULATOR_SRC_DIR)/shadow-uarch-state.cpp \
-	$(EMULATOR_SRC_DIR)/plic.cpp \
-	$(EMULATOR_SRC_DIR)/clint.cpp
+	$(EMULATOR_SRC_DIR)/htif-address-range.cpp \
+	$(EMULATOR_SRC_DIR)/plic-address-range.cpp \
+	$(EMULATOR_SRC_DIR)/clint-address-range.cpp
 
 COMPUTE_SOURCES=\
 	compute-uarch-pristine-hash.cpp \
@@ -167,4 +165,4 @@ clean-auto-generated:
 	@rm -f uarch-pristine-hash.c uarch-pristine-ram.c
 
 clean: clean-executables clean-auto-generated
-	@rm -f *.ld *.elf *.bin *.tmp link.ld $(UARCH_OBJS) $(EMULATOR_OBJS) $(COMPUTE_OBJS) *.clang-tidy *.insn.txt *.objdump
+	@rm -f *.ld *.elf *.bin *.tmp link.ld $(UARCH_OBJS) $(EMULATOR_OBJS) $(COMPUTE_OBJS) uarch-ram-entry.o *.clang-tidy *.insn.txt *.objdump
diff --git a/uarch/machine-uarch-bridge-state-access.h b/uarch/machine-uarch-bridge-state-access.h
index 793b04c4d..bcf842a8d 100644
--- a/uarch/machine-uarch-bridge-state-access.h
+++ b/uarch/machine-uarch-bridge-state-access.h
@@ -26,10 +26,11 @@
 #include "i-prefer-shadow-state.h"
 #include "i-state-access.h"
 #include "machine-reg.h"
-#include "mock-pma-entry.h"
+#include "mock-address-range.h"
 #include "pma-constants.h"
 #include "riscv-constants.h"
 #include "shadow-pmas.h"
+#include "shadow-tlb.h"
 #include "uarch-constants.h"
 #include "uarch-defines.h"
 #include "uarch-ecall.h"
@@ -39,11 +40,6 @@ namespace cartesi {
 
 class machine_uarch_bridge_state_access;
 
-// Type trait that should return the pma_entry type for a state access class
-template <>
-struct i_state_access_pma_entry<machine_uarch_bridge_state_access> {
-    using type = mock_pma_entry;
-};
 // Type trait that should return the fast_addr type for a state access class
 template <>
 struct i_state_access_fast_addr<machine_uarch_bridge_state_access> {
@@ -57,10 +53,10 @@ class machine_uarch_bridge_state_access :
     public i_prefer_shadow_state<machine_uarch_bridge_state_access> {
 
     // NOLINTNEXTLINE(cppcoreguidelines-avoid-const-or-ref-data-members)
-    std::array<std::optional<mock_pma_entry>, PMA_MAX> &m_pmas;
+    mock_address_ranges &m_ars;
 
 public:
-    machine_uarch_bridge_state_access(std::array<std::optional<mock_pma_entry>, PMA_MAX> &pmas) : m_pmas(pmas) {}
+    machine_uarch_bridge_state_access(std::array<mock_address_range, PMA_MAX> &ars) : m_ars(ars) {}
     machine_uarch_bridge_state_access(const machine_uarch_bridge_state_access &other) = default;
     machine_uarch_bridge_state_access(machine_uarch_bridge_state_access &&other) = default;
     machine_uarch_bridge_state_access &operator=(const machine_uarch_bridge_state_access &other) = delete;
@@ -118,26 +114,32 @@ class machine_uarch_bridge_state_access :
 
     bool do_read_memory(uint64_t /*paddr*/, unsigned char * /*data*/, uint64_t /*length*/) const {
         // This is not implemented yet because it's not being used
+        assert(false && "read_memory() unexpectedly called");
         abort();
         return false;
     }
 
     bool do_write_memory(uint64_t /*paddr*/, const unsigned char * /*data*/, uint64_t /*length*/) const {
         // This is not implemented yet because it's not being used
+        assert(false && "write_memory() unexpectedly called");
         abort();
         return false;
     }
 
-    mock_pma_entry &do_read_pma_entry(uint64_t index) const {
+    address_range &do_read_pma(uint64_t index) const {
+        constexpr const auto throw_abort = [](const char * /*err*/) {
+            assert(false && "read_address_range() failed");
+            abort();
+        };
         const uint64_t istart = bridge_read_pma_istart(index);
         const uint64_t ilength = bridge_read_pma_ilength(index);
         // NOLINTNEXTLINE(bugprone-narrowing-conversions)
         int i = static_cast<int>(index);
-        if (!m_pmas[i]) {
-            m_pmas[i] = make_mock_pma_entry(index, istart, ilength, [](const char * /*err*/) { abort(); });
+        if (std::holds_alternative<std::monostate>(m_ars[i])) {
+            m_ars[i] = make_mock_address_range(istart, ilength, throw_abort);
         }
         // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
-        return m_pmas[i].value();
+        return get_mock_address_range(m_ars[i], throw_abort);
     }
 
     uint64_t do_get_faddr(uint64_t paddr, uint64_t /* pma_index */) const {
diff --git a/uarch/uarch-run.cpp b/uarch/uarch-run.cpp
index d1b54dfa0..354a2f069 100644
--- a/uarch/uarch-run.cpp
+++ b/uarch/uarch-run.cpp
@@ -19,7 +19,7 @@
 #include "compiler-defines.h"
 #include "interpret.h"
 #include "machine-uarch-bridge-state-access.h"
-#include "mock-pma-entry.h"
+#include "mock-address-range.h"
 #include "uarch-constants.h"
 #include "uarch-ecall.h"
 
@@ -31,7 +31,7 @@ using namespace cartesi;
 
 // Let the state accessor be on static memory storage to speed up uarch initialization
 // NOLINTNEXTLINE(cppcoreguidelines-avoid-non-const-global-variables)
-std::array<std::optional<mock_pma_entry>, PMA_MAX> pmas;
+mock_address_ranges ars;
 
 namespace cartesi {
 
@@ -43,7 +43,7 @@ extern template interpreter_break_reason interpret(machine_uarch_bridge_state_ac
 /// \brief  Advances one mcycle by executing the "big machine interpreter" compiled to the microarchitecture
 /// \return This function never returns
 extern "C" NO_RETURN void interpret_next_mcycle_with_uarch() {
-    machine_uarch_bridge_state_access a(pmas);
+    machine_uarch_bridge_state_access a(ars);
     const uint64_t mcycle_end = a.read_mcycle() + 1;
     interpret(a, mcycle_end);
     // Finished executing a whole mcycle: halt the microarchitecture
diff --git a/uarch/uarch-runtime.cpp b/uarch/uarch-runtime.cpp
index 932544cef..0fa655c1e 100644
--- a/uarch/uarch-runtime.cpp
+++ b/uarch/uarch-runtime.cpp
@@ -26,6 +26,10 @@ extern "C" void __cxa_pure_virtual() {
     abort();
 }
 
+extern "C" int atexit(void (*)(void)) {
+    return 0;
+}
+
 // NOLINTNEXTLINE(cert-dcl54-cpp,misc-new-delete-overloads,hicpp-new-delete-operators)
 void operator delete(void * /*ptr*/) {}
 
diff --git a/uarch/uarch-runtime.h b/uarch/uarch-runtime.h
index dc28fdbfb..30fc05178 100644
--- a/uarch/uarch-runtime.h
+++ b/uarch/uarch-runtime.h
@@ -23,12 +23,22 @@
 #include <inttypes.h>
 #include <stddef.h>
 
+#ifndef NDEBUG
 // NOLINTNEXTLINE(cppcoreguidelines-macro-usage)
 #define assert(a)                                                                                                      \
-    if (!(a)) {                                                                                                        \
-        printf("Assertion failed\n");                                                                                  \
-        abort();                                                                                                       \
-    }
+    do {                                                                                                               \
+        if (!(a)) {                                                                                                    \
+            printf("Assertion failed: %s, %s:%d, %s\n", #a, __FILE__, __LINE__, __func__);                             \
+            abort();                                                                                                   \
+        }                                                                                                              \
+    } while (0)
+#else
+// NOLINTNEXTLINE(cppcoreguidelines-macro-usage)
+#define assert(a)
+#endif
+
+// NOLINTNEXTLINE(cppcoreguidelines-macro-usage)
+#define fprintf(f, ...) printf(__VA_ARGS__)
 
 extern "C" NO_RETURN void abort();
 

From 63ae3a6054c09e69ca27e2a2942fbdbbbbef1cd7 Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Fri, 28 Feb 2025 20:40:49 +0000
Subject: [PATCH 22/82] refactor: use NVI pattern on virtio classes

---
 src/address-range.h                     |  1 +
 src/virtio-address-range.cpp            |  5 +--
 src/virtio-address-range.h              | 36 +++++++++++++++----
 src/virtio-console-address-range.cpp    | 10 +++---
 src/virtio-console-address-range.h      | 16 ++++-----
 src/virtio-net-address-range.cpp        | 10 +++---
 src/virtio-net-address-range.h          | 47 +++++++++++++++++--------
 src/virtio-net-tuntap-address-range.cpp | 14 ++++----
 src/virtio-net-tuntap-address-range.h   | 14 ++++----
 src/virtio-net-user-address-range.cpp   | 10 +++---
 src/virtio-net-user-address-range.h     | 13 ++++---
 src/virtio-p9fs-address-range.cpp       |  6 ++--
 src/virtio-p9fs-address-range.h         | 11 +++---
 13 files changed, 117 insertions(+), 76 deletions(-)

diff --git a/src/address-range.h b/src/address-range.h
index 8e7bcdb7c..801f79ece 100644
--- a/src/address-range.h
+++ b/src/address-range.h
@@ -66,6 +66,7 @@ class address_range {
     address_range &operator=(const address_range &other) = default;
     address_range(address_range &&other) = default;
     address_range &operator=(address_range &&other) = default;
+    // NOLINTNEXTLINE(hicpp-use-equals-default,modernize-use-equals-default)
     constexpr virtual ~address_range() {}; // = default; // doesn't work due to bug in gcc
 
     template <typename ABRT, size_t N, typename... ARGS>
diff --git a/src/virtio-address-range.cpp b/src/virtio-address-range.cpp
index 67335103c..92dbf0fc9 100644
--- a/src/virtio-address-range.cpp
+++ b/src/virtio-address-range.cpp
@@ -506,9 +506,10 @@ void virtio_address_range::on_device_queue_notify(i_device_state_access *a, uint
     }
 }
 
-void virtio_address_range::prepare_select(select_fd_sets * /*fds*/, uint64_t * /*timeout_us*/) {}
+void virtio_address_range::do_prepare_select(select_fd_sets * /*fds*/, uint64_t * /*timeout_us*/) {}
 
-bool virtio_address_range::poll_selected(int /*select_ret*/, select_fd_sets * /*fds*/, i_device_state_access * /*da*/) {
+bool virtio_address_range::do_poll_selected(int /*select_ret*/, select_fd_sets * /*fds*/,
+    i_device_state_access * /*da*/) {
     return false;
 };
 
diff --git a/src/virtio-address-range.h b/src/virtio-address-range.h
index f3f90bc93..4e45c0159 100644
--- a/src/virtio-address-range.h
+++ b/src/virtio-address-range.h
@@ -335,10 +335,14 @@ class virtio_address_range : public pristine_address_range {
         uint16_t used_flags = 0);
 
     /// \brief Called when driver request a device reset, this function must clean-up all device internal state.
-    virtual void on_device_reset() = 0;
+    void on_device_reset() {
+        do_on_device_reset();
+    }
 
     /// \brief Called when driver finish initializing the device.
-    virtual void on_device_ok(i_device_state_access *a) = 0;
+    void on_device_ok(i_device_state_access *a) {
+        do_on_device_ok(a);
+    }
 
     /// \brief Process driver notification for pending available queue's descriptors.
     /// \params queue_idx Index for the queue that is has an available descriptor to be processed.
@@ -349,20 +353,26 @@ class virtio_address_range : public pristine_address_range {
     /// \param desc_idx Queue's available descriptor index.
     /// \param read_avail_len Total readable length in the descriptor buffer.
     /// \param write_avail_len Total writable length in the descriptor buffer.
-    virtual bool on_device_queue_available(i_device_state_access *a, uint32_t queue_idx, uint16_t desc_idx,
-        uint32_t read_avail_len, uint32_t write_avail_len) = 0;
+    bool on_device_queue_available(i_device_state_access *a, uint32_t queue_idx, uint16_t desc_idx,
+        uint32_t read_avail_len, uint32_t write_avail_len) {
+        return do_on_device_queue_available(a, queue_idx, desc_idx, read_avail_len, write_avail_len);
+    }
 
     /// \brief Fill file descriptors to be polled by select().
     /// \param fds Pointer to sets of read, write and except file descriptors to be updated.
     /// \param timeout_us Maximum amount of time to wait, this may be updated (always to lower values).
-    virtual void prepare_select(select_fd_sets *fds, uint64_t *timeout_us);
+    void prepare_select(select_fd_sets *fds, uint64_t *timeout_us) {
+        do_prepare_select(fds, timeout_us);
+    }
 
     /// \brief Poll file descriptors that were marked as ready by select().
     /// \param select_ret Return value from the most recent select() call.
     /// \param fds Pointer to sets of read, write and except file descriptors to be checked.
     /// \returns True if an interrupt was requested, false otherwise.
     /// \details This function process pending events and trigger interrupt requests (if any).
-    virtual bool poll_selected(int select_ret, select_fd_sets *fds, i_device_state_access *da);
+    bool poll_selected(int select_ret, select_fd_sets *fds, i_device_state_access *da) {
+        return do_poll_selected(select_ret, fds, da);
+    }
 
     /// \brief Poll pending events without waiting (non-blocking).
     /// \details Basically call prepare_select(), select() and poll_selected() with timeout set to 0.
@@ -421,10 +431,24 @@ class virtio_address_range : public pristine_address_range {
     }
 
 private:
+    // Address range interface
     bool do_read_device(i_device_state_access *a, uint64_t offset, int log2_size,
         uint64_t *pval) const noexcept override;
+
     execute_status do_write_device(i_device_state_access *a, uint64_t offset, int log2_size,
         uint64_t val) noexcept override;
+
+    // VirtIO address range interface
+    virtual void do_on_device_reset() = 0;
+
+    virtual void do_on_device_ok(i_device_state_access *a) = 0;
+
+    virtual bool do_on_device_queue_available(i_device_state_access *a, uint32_t queue_idx, uint16_t desc_idx,
+        uint32_t read_avail_len, uint32_t write_avail_len) = 0;
+
+    virtual void do_prepare_select(select_fd_sets *fds, uint64_t *timeout_us);
+
+    virtual bool do_poll_selected(int select_ret, select_fd_sets *fds, i_device_state_access *da);
 };
 
 } // namespace cartesi
diff --git a/src/virtio-console-address-range.cpp b/src/virtio-console-address-range.cpp
index d0b585554..cbf476ebe 100644
--- a/src/virtio-console-address-range.cpp
+++ b/src/virtio-console-address-range.cpp
@@ -29,16 +29,16 @@ virtio_console_address_range::virtio_console_address_range(uint64_t start, uint6
     virtio_address_range("VirtIO Console", start, length, virtio_idx, VIRTIO_DEVICE_CONSOLE, VIRTIO_CONSOLE_F_SIZE,
         sizeof(virtio_console_config_space)) {}
 
-void virtio_console_address_range::on_device_reset() {
+void virtio_console_address_range::do_on_device_reset() {
     m_stdin_ready = false;
 }
 
-void virtio_console_address_range::on_device_ok(i_device_state_access *a) {
+void virtio_console_address_range::do_on_device_ok(i_device_state_access *a) {
     // Upon initialization, we need to notify the initial console size
     notify_console_size_to_guest(a);
 }
 
-bool virtio_console_address_range::on_device_queue_available(i_device_state_access *a, uint32_t queue_idx,
+bool virtio_console_address_range::do_on_device_queue_available(i_device_state_access *a, uint32_t queue_idx,
     uint16_t desc_idx, uint32_t read_avail_len, uint32_t /*write_avail_len*/) {
     if (queue_idx == VIRTIO_CONSOLE_RECEIVEQ) { // Guest has a new slot available in the write queue
         // Do nothing, host stdin characters will be written to the guest in the next poll
@@ -131,7 +131,7 @@ bool virtio_console_address_range::notify_console_size_to_guest(i_device_state_a
     return true;
 }
 
-void virtio_console_address_range::prepare_select(select_fd_sets *fds, uint64_t *timeout_us) {
+void virtio_console_address_range::do_prepare_select(select_fd_sets *fds, uint64_t *timeout_us) {
     // Ignore if driver is not initialized
     if (!driver_ok) {
         return;
@@ -154,7 +154,7 @@ void virtio_console_address_range::prepare_select(select_fd_sets *fds, uint64_t
     os_prepare_tty_select(fds);
 }
 
-bool virtio_console_address_range::poll_selected(int select_ret, select_fd_sets *fds, i_device_state_access *da) {
+bool virtio_console_address_range::do_poll_selected(int select_ret, select_fd_sets *fds, i_device_state_access *da) {
     // Ignore if driver is not initialized or stdin is not ready
 
     if (!driver_ok || !m_stdin_ready) {
diff --git a/src/virtio-console-address-range.h b/src/virtio-console-address-range.h
index 3f68c410c..109c0ad7a 100644
--- a/src/virtio-console-address-range.h
+++ b/src/virtio-console-address-range.h
@@ -58,23 +58,23 @@ class virtio_console_address_range final : public virtio_address_range {
     virtio_console_address_range(virtio_console_address_range &&other) = default;
     ~virtio_console_address_range() override = default;
 
-    void on_device_reset() override;
-    void on_device_ok(i_device_state_access *a) override;
-    bool on_device_queue_available(i_device_state_access *a, uint32_t queue_idx, uint16_t desc_idx,
-        uint32_t read_avail_len, uint32_t write_avail_len) override;
-
     bool write_next_chars_to_host(i_device_state_access *a, uint32_t queue_idx, uint16_t desc_idx,
         uint32_t read_avail_len);
     bool write_next_chars_to_guest(i_device_state_access *a);
     bool notify_console_size_to_guest(i_device_state_access *a);
 
-    void prepare_select(select_fd_sets *fds, uint64_t *timeout_us) override;
-    bool poll_selected(int select_ret, select_fd_sets *fds, i_device_state_access *da) override;
-
     virtio_console_config_space *get_config() {
         // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
         return reinterpret_cast<virtio_console_config_space *>(config_space.data());
     }
+
+private:
+    void do_prepare_select(select_fd_sets *fds, uint64_t *timeout_us) override;
+    bool do_poll_selected(int select_ret, select_fd_sets *fds, i_device_state_access *da) override;
+    void do_on_device_reset() override;
+    void do_on_device_ok(i_device_state_access *a) override;
+    bool do_on_device_queue_available(i_device_state_access *a, uint32_t queue_idx, uint16_t desc_idx,
+        uint32_t read_avail_len, uint32_t write_avail_len) override;
 };
 
 static inline auto make_virtio_console_address_range(uint64_t start, uint64_t length, uint32_t virtio_idx) {
diff --git a/src/virtio-net-address-range.cpp b/src/virtio-net-address-range.cpp
index 653881973..169e6637a 100644
--- a/src/virtio-net-address-range.cpp
+++ b/src/virtio-net-address-range.cpp
@@ -31,15 +31,15 @@ virtio_net_address_range::virtio_net_address_range(const char *description, uint
     uint32_t virtio_idx) :
     virtio_address_range(description, start, length, virtio_idx, VIRTIO_DEVICE_NETWORK, 0, 0) {}
 
-void virtio_net_address_range::on_device_reset() {
+void virtio_net_address_range::do_on_device_reset() {
     net_reset();
 }
 
-void virtio_net_address_range::on_device_ok(i_device_state_access * /*a*/) {
+void virtio_net_address_range::do_on_device_ok(i_device_state_access * /*a*/) {
     // Nothing to do.
 }
 
-bool virtio_net_address_range::on_device_queue_available(i_device_state_access *a, uint32_t queue_idx,
+bool virtio_net_address_range::do_on_device_queue_available(i_device_state_access *a, uint32_t queue_idx,
     uint16_t desc_idx, uint32_t read_avail_len, uint32_t /*write_avail_len*/) {
     if (queue_idx == VIRTIO_NET_RECEIVEQ) { // Guest has a new slot available in the write queue
         // Write any pending packets from host to guest
@@ -59,14 +59,14 @@ bool virtio_net_address_range::on_device_queue_available(i_device_state_access *
     return false;
 }
 
-void virtio_net_address_range::prepare_select(select_fd_sets *fds, uint64_t *timeout_us) {
+void virtio_net_address_range::do_prepare_select(select_fd_sets *fds, uint64_t *timeout_us) {
     if (!driver_ok) {
         return;
     }
     net_prepare_select(fds, timeout_us);
 }
 
-bool virtio_net_address_range::poll_selected(int select_ret, select_fd_sets *fds, i_device_state_access *da) {
+bool virtio_net_address_range::do_poll_selected(int select_ret, select_fd_sets *fds, i_device_state_access *da) {
     if (!driver_ok) {
         return false;
     }
diff --git a/src/virtio-net-address-range.h b/src/virtio-net-address-range.h
index 806b53311..2afbd1f1a 100644
--- a/src/virtio-net-address-range.h
+++ b/src/virtio-net-address-range.h
@@ -65,27 +65,24 @@ class virtio_net_address_range : public virtio_address_range {
     virtio_net_address_range(virtio_net_address_range &&other) = default;
     ~virtio_net_address_range() override = default;
 
-    void on_device_reset() override;
-    void on_device_ok(i_device_state_access *a) override;
-    bool on_device_queue_available(i_device_state_access *a, uint32_t queue_idx, uint16_t desc_idx,
-        uint32_t read_avail_len, uint32_t write_avail_len) override;
-
-    void prepare_select(select_fd_sets *fds, uint64_t *timeout_us) override;
-    bool poll_selected(int select_ret, select_fd_sets *fds, i_device_state_access *da) override;
-
     bool write_next_packet_to_host(i_device_state_access *a, uint32_t queue_idx, uint16_t desc_idx,
         uint32_t read_avail_len);
     bool read_next_packet_from_host(i_device_state_access *a);
 
-protected:
     /// \brief Reset carrier internal state, discarding all network state.
-    virtual void net_reset() = 0;
+    void net_reset() {
+        do_net_reset();
+    }
 
     /// \brief Fill file descriptors to be polled by select().
-    virtual void net_prepare_select(select_fd_sets *fds, uint64_t *timeout_us) = 0;
+    void net_prepare_select(select_fd_sets *fds, uint64_t *timeout_us) {
+        do_net_prepare_select(fds, timeout_us);
+    }
 
     /// \brief Poll file descriptors that were marked as ready by select().
-    virtual bool net_poll_selected(int select_ret, select_fd_sets *fds) = 0;
+    bool net_poll_selected(int select_ret, select_fd_sets *fds) {
+        return do_net_poll_selected(select_ret, fds);
+    }
 
     /// \brief Called for carrying outgoing packets from the guest to the host.
     /// \param vq Queue reference.
@@ -95,8 +92,10 @@ class virtio_net_address_range : public virtio_address_range {
     /// \returns True on success, false otherwise.
     /// \details This function will return true even if when the write queue is full,
     /// pread_len will be set to 0 in this case and the packet dropped.
-    virtual bool net_write_packet_to_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx,
-        uint32_t read_avail_len, uint32_t *pread_len) = 0;
+    bool net_write_packet_to_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx, uint32_t read_avail_len,
+        uint32_t *pread_len) {
+        return do_net_write_packet_to_host(a, vq, desc_idx, read_avail_len, pread_len);
+    }
 
     /// \brief Called for carrying incoming packets from the host to the guest.
     /// \param vq Queue reference.
@@ -106,7 +105,25 @@ class virtio_net_address_range : public virtio_address_range {
     /// \returns True on success, false otherwise.
     /// \details This function will true even if when there are no more packets to write,
     /// pwritten_len will be set to 0 in this case.
-    virtual bool net_read_packet_from_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx,
+    bool net_read_packet_from_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx, uint32_t write_avail_len,
+        uint32_t *pwritten_len) {
+        return do_net_read_packet_from_host(a, vq, desc_idx, write_avail_len, pwritten_len);
+    }
+
+private:
+    void do_on_device_reset() override;
+    void do_on_device_ok(i_device_state_access *a) override;
+    bool do_on_device_queue_available(i_device_state_access *a, uint32_t queue_idx, uint16_t desc_idx,
+        uint32_t read_avail_len, uint32_t write_avail_len) override;
+    void do_prepare_select(select_fd_sets *fds, uint64_t *timeout_us) override;
+    bool do_poll_selected(int select_ret, select_fd_sets *fds, i_device_state_access *da) override;
+
+    virtual void do_net_reset() = 0;
+    virtual void do_net_prepare_select(select_fd_sets *fds, uint64_t *timeout_us) = 0;
+    virtual bool do_net_poll_selected(int select_ret, select_fd_sets *fds) = 0;
+    virtual bool do_net_write_packet_to_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx,
+        uint32_t read_avail_len, uint32_t *pread_len) = 0;
+    virtual bool do_net_read_packet_from_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx,
         uint32_t write_avail_len, uint32_t *pwritten_len) = 0;
 };
 
diff --git a/src/virtio-net-tuntap-address-range.cpp b/src/virtio-net-tuntap-address-range.cpp
index 68aaa596c..63d61c867 100644
--- a/src/virtio-net-tuntap-address-range.cpp
+++ b/src/virtio-net-tuntap-address-range.cpp
@@ -119,25 +119,25 @@ virtio_net_tuntap_address_range::~virtio_net_tuntap_address_range() {
     }
 }
 
-void virtio_net_tuntap_address_range::net_reset() {
+void virtio_net_tuntap_address_range::do_net_reset() {
     // Nothing to do.
 }
 
-void virtio_net_tuntap_address_range::net_prepare_select(select_fd_sets *fds, uint64_t * /*timeout_us*/) {
+void virtio_net_tuntap_address_range::do_net_prepare_select(select_fd_sets *fds, uint64_t * /*timeout_us*/) {
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
     auto *readfds = reinterpret_cast<fd_set *>(fds->readfds);
     FD_SET(m_tapfd, readfds);
     fds->maxfd = std::max(m_tapfd, fds->maxfd);
 }
 
-bool virtio_net_tuntap_address_range::net_poll_selected(int select_ret, select_fd_sets *fds) {
+bool virtio_net_tuntap_address_range::do_net_poll_selected(int select_ret, select_fd_sets *fds) {
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
     auto *readfds = reinterpret_cast<fd_set *>(fds->readfds);
     return select_ret > 0 && FD_ISSET(m_tapfd, readfds);
 }
 
-bool virtio_net_tuntap_address_range::net_write_packet_to_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx,
-    uint32_t read_avail_len, uint32_t *pread_len) {
+bool virtio_net_tuntap_address_range::do_net_write_packet_to_host(i_device_state_access *a, virtq &vq,
+    uint16_t desc_idx, uint32_t read_avail_len, uint32_t *pread_len) {
     // Determinate packet size
     const uint32_t packet_len = read_avail_len - VIRTIO_NET_ETHERNET_FRAME_OFFSET;
     if (packet_len > VIRTIO_NET_ETHERNET_MAX_LENGTH) {
@@ -182,8 +182,8 @@ bool virtio_net_tuntap_address_range::net_write_packet_to_host(i_device_state_ac
     return true;
 }
 
-bool virtio_net_tuntap_address_range::net_read_packet_from_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx,
-    uint32_t write_avail_len, uint32_t *pwritten_len) {
+bool virtio_net_tuntap_address_range::do_net_read_packet_from_host(i_device_state_access *a, virtq &vq,
+    uint16_t desc_idx, uint32_t write_avail_len, uint32_t *pwritten_len) {
     // Write network to queue buffer in chunks
     std::array<uint8_t, VIRTIO_NET_ETHERNET_MAX_LENGTH> packet_buf{};
     // Set errno to zero because read() will not set it when it returns zero (end of file)
diff --git a/src/virtio-net-tuntap-address-range.h b/src/virtio-net-tuntap-address-range.h
index cd3328dbe..afaf814a6 100644
--- a/src/virtio-net-tuntap-address-range.h
+++ b/src/virtio-net-tuntap-address-range.h
@@ -43,15 +43,13 @@ class virtio_net_tuntap_address_range final : public virtio_net_address_range {
     virtio_net_tuntap_address_range(virtio_net_tuntap_address_range &&other) = default;
     ~virtio_net_tuntap_address_range() override;
 
-protected:
-    void net_reset() override;
-
-    void net_prepare_select(select_fd_sets *fds, uint64_t *timeout_us) override;
-    bool net_poll_selected(int select_ret, select_fd_sets *fds) override;
-
-    bool net_write_packet_to_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx, uint32_t read_avail_len,
+private:
+    void do_net_reset() override;
+    void do_net_prepare_select(select_fd_sets *fds, uint64_t *timeout_us) override;
+    bool do_net_poll_selected(int select_ret, select_fd_sets *fds) override;
+    bool do_net_write_packet_to_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx, uint32_t read_avail_len,
         uint32_t *pread_len) override;
-    bool net_read_packet_from_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx, uint32_t write_avail_len,
+    bool do_net_read_packet_from_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx, uint32_t write_avail_len,
         uint32_t *pwritten_len) override;
 };
 
diff --git a/src/virtio-net-user-address-range.cpp b/src/virtio-net-user-address-range.cpp
index d5b03ec2b..ed3e9fc42 100644
--- a/src/virtio-net-user-address-range.cpp
+++ b/src/virtio-net-user-address-range.cpp
@@ -240,7 +240,7 @@ virtio_net_user_address_range::~virtio_net_user_address_range() {
     timers.clear();
 }
 
-void virtio_net_user_address_range::net_reset() {
+void virtio_net_user_address_range::do_net_reset() {
     // Nothing to do, we don't want to reset slirp to not lose network state.
 }
 
@@ -283,7 +283,7 @@ static int slirp_get_revents_cb(int fd, void *opaque) {
     return event;
 }
 
-void virtio_net_user_address_range::net_prepare_select(select_fd_sets *fds, uint64_t *timeout_us) {
+void virtio_net_user_address_range::do_net_prepare_select(select_fd_sets *fds, uint64_t *timeout_us) {
     // Did device reset and slirp failed to reinitialize?
     if (slirp == nullptr) {
         return;
@@ -306,7 +306,7 @@ void virtio_net_user_address_range::net_prepare_select(select_fd_sets *fds, uint
     }
 }
 
-bool virtio_net_user_address_range::net_poll_selected(int select_ret, select_fd_sets *fds) {
+bool virtio_net_user_address_range::do_net_poll_selected(int select_ret, select_fd_sets *fds) {
     // Did device reset and slirp failed to reinitialize?
     if (slirp == nullptr) {
         return false;
@@ -333,7 +333,7 @@ bool virtio_net_user_address_range::net_poll_selected(int select_ret, select_fd_
     return !send_packets.empty();
 }
 
-bool virtio_net_user_address_range::net_write_packet_to_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx,
+bool virtio_net_user_address_range::do_net_write_packet_to_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx,
     uint32_t read_avail_len, uint32_t *pread_len) {
     // Did device reset and slirp failed to reinitialize?
     if (slirp == nullptr) {
@@ -362,7 +362,7 @@ bool virtio_net_user_address_range::net_write_packet_to_host(i_device_state_acce
     return true;
 }
 
-bool virtio_net_user_address_range::net_read_packet_from_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx,
+bool virtio_net_user_address_range::do_net_read_packet_from_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx,
     uint32_t write_avail_len, uint32_t *pwritten_len) {
     // If no packet was send by slirp, we can just ignore.
     if (send_packets.empty()) {
diff --git a/src/virtio-net-user-address-range.h b/src/virtio-net-user-address-range.h
index 9798ad66f..dcf17fff9 100644
--- a/src/virtio-net-user-address-range.h
+++ b/src/virtio-net-user-address-range.h
@@ -83,14 +83,13 @@ class virtio_net_user_address_range final : public virtio_net_address_range {
     virtio_net_user_address_range(virtio_net_user_address_range &&other) = default;
     ~virtio_net_user_address_range() override;
 
-    void net_reset() override;
-
-    void net_prepare_select(select_fd_sets *fds, uint64_t *timeout_us) override;
-    bool net_poll_selected(int select_ret, select_fd_sets *fds) override;
-
-    bool net_write_packet_to_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx, uint32_t read_avail_len,
+private:
+    void do_net_reset() override;
+    void do_net_prepare_select(select_fd_sets *fds, uint64_t *timeout_us) override;
+    bool do_net_poll_selected(int select_ret, select_fd_sets *fds) override;
+    bool do_net_write_packet_to_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx, uint32_t read_avail_len,
         uint32_t *pread_len) override;
-    bool net_read_packet_from_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx, uint32_t write_avail_len,
+    bool do_net_read_packet_from_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx, uint32_t write_avail_len,
         uint32_t *pwritten_len) override;
 };
 
diff --git a/src/virtio-p9fs-address-range.cpp b/src/virtio-p9fs-address-range.cpp
index 728066b30..7719af652 100644
--- a/src/virtio-p9fs-address-range.cpp
+++ b/src/virtio-p9fs-address-range.cpp
@@ -1087,7 +1087,7 @@ virtio_p9fs_address_range::~virtio_p9fs_address_range() {
     m_fids.clear();
 }
 
-void virtio_p9fs_address_range::on_device_reset() {
+void virtio_p9fs_address_range::do_on_device_reset() {
     m_msize = P9_MAX_MSIZE;
     // Close all file descriptors
     for (auto &it : m_fids) {
@@ -1097,11 +1097,11 @@ void virtio_p9fs_address_range::on_device_reset() {
     m_fids.clear();
 }
 
-void virtio_p9fs_address_range::on_device_ok(i_device_state_access * /*a*/) {
+void virtio_p9fs_address_range::do_on_device_ok(i_device_state_access * /*a*/) {
     // Nothing to do.
 }
 
-bool virtio_p9fs_address_range::on_device_queue_available(i_device_state_access *a, uint32_t queue_idx,
+bool virtio_p9fs_address_range::do_on_device_queue_available(i_device_state_access *a, uint32_t queue_idx,
     uint16_t desc_idx, uint32_t /*read_avail_len*/, uint32_t /*write_avail_len*/) {
     // We are only interested in queue 0 notifications
     if (queue_idx != 0) {
diff --git a/src/virtio-p9fs-address-range.h b/src/virtio-p9fs-address-range.h
index 1fe94b9ac..e7fc119bb 100644
--- a/src/virtio-p9fs-address-range.h
+++ b/src/virtio-p9fs-address-range.h
@@ -412,11 +412,6 @@ class virtio_p9fs_address_range final : public virtio_address_range {
     virtio_p9fs_address_range(virtio_p9fs_address_range &&other) = default;
     ~virtio_p9fs_address_range() override;
 
-    void on_device_reset() override;
-    void on_device_ok(i_device_state_access *a) override;
-    bool on_device_queue_available(i_device_state_access *a, uint32_t queue_idx, uint16_t desc_idx,
-        uint32_t read_avail_len, uint32_t write_avail_len) override;
-
     bool op_statfs(virtq_unserializer &&msg, uint16_t tag);
     bool op_lopen(virtq_unserializer &&msg, uint16_t tag);
     bool op_lcreate(virtq_unserializer &&msg, uint16_t tag);
@@ -457,6 +452,12 @@ class virtio_p9fs_address_range final : public virtio_address_range {
     uint32_t get_iounit() const {
         return std::min<uint32_t>(m_msize - P9_IOUNIT_HEADER_SIZE, P9_IOUNIT_MAX);
     }
+
+private:
+    void do_on_device_reset() override;
+    void do_on_device_ok(i_device_state_access *a) override;
+    bool do_on_device_queue_available(i_device_state_access *a, uint32_t queue_idx, uint16_t desc_idx,
+        uint32_t read_avail_len, uint32_t write_avail_len) override;
 };
 
 static inline auto make_virtio_p9fs_address_range(uint64_t start, uint64_t length, uint32_t virtio_idx,

From 72a9c91e375aefa3cac50d746c4ba3c51d4750da Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Sat, 1 Mar 2025 17:13:57 +0000
Subject: [PATCH 23/82] refactor: shadow PMAs becomes PMAS memory range

---
 src/address-range.h                           |  2 +-
 src/machine.cpp                               | 25 +++--
 src/machine.h                                 |  4 +-
 src/mock-address-range.h                      |  2 +-
 src/pma-constants.h                           |  5 +-
 src/pma-defines.h                             | 23 +++--
 src/pma.h                                     | 69 ++++++++++++-
 ...s-address-range.h => pmas-address-range.h} | 15 ++-
 src/record-step-state-access.h                |  6 +-
 src/replay-step-state-access.h                |  7 +-
 src/shadow-pmas.h                             | 96 -------------------
 tests/lua/machine-test.lua                    |  4 +-
 12 files changed, 109 insertions(+), 149 deletions(-)
 rename src/{shadow-pmas-address-range.h => pmas-address-range.h} (73%)
 delete mode 100644 src/shadow-pmas.h

diff --git a/src/address-range.h b/src/address-range.h
index 801f79ece..58ca773f3 100644
--- a/src/address-range.h
+++ b/src/address-range.h
@@ -233,7 +233,7 @@ class address_range {
     /// \brief Returns packed address range istart field as per whitepaper
     /// \returns Packed address range istart
     uint64_t get_istart() const noexcept {
-        return pack_pma_istart(m_flags, m_start);
+        return pma_pack_istart(m_flags, m_start);
     }
 
     /// \brief Returns encoded addres range ilength field as per whitepaper
diff --git a/src/machine.cpp b/src/machine.cpp
index da1ffd79e..dab1920aa 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -54,7 +54,8 @@
 #include "machine-runtime-config.h"
 #include "memory-address-range.h"
 #include "plic-address-range.h"
-#include "pma-constants.h"
+#include "pma.h"
+#include "pmas-address-range.h"
 #include "record-send-cmio-state-access.h"
 #include "record-step-state-access.h"
 #include "replay-send-cmio-state-access.h"
@@ -62,7 +63,6 @@
 #include "riscv-constants.h"
 #include "rtc.h"
 #include "send-cmio-response.h"
-#include "shadow-pmas-address-range.h"
 #include "shadow-state-address-range.h"
 #include "shadow-tlb-address-range.h"
 #include "shadow-uarch-state-address-range.h"
@@ -504,14 +504,13 @@ void machine::init_sentinel_ars() {
     }
 }
 
-void machine::init_shadow_pmas_contents(memory_address_range &shadow_pmas) const {
-    static_assert(sizeof(shadow_pmas_state) == PMA_MAX * 2 * sizeof(uint64_t), "inconsistent shadow PMAs length");
-    static_assert(PMA_SHADOW_PMAS_LENGTH >= sizeof(shadow_pmas_state), "shadow PMAs not long enough");
+void machine::init_pmas_contents(memory_address_range &pmas) const {
+    static_assert(sizeof(pmas_state) == PMA_MAX * 2 * sizeof(uint64_t), "inconsistent PMAs state length");
+    static_assert(PMA_PMAS_LENGTH >= sizeof(pmas_state), "PMAs address range too short");
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-    auto &dest = *reinterpret_cast<shadow_pmas_state *>(shadow_pmas.get_host_memory());
-    std::ranges::transform(m_s.pmas, dest.begin(), [this](auto i) {
-        return shadow_pmas_entry{.istart = m_ars[i]->get_istart(), .ilength = m_ars[i]->get_ilength()};
-    });
+    auto &dest = *reinterpret_cast<pmas_state *>(pmas.get_host_memory());
+    std::ranges::transform(m_s.pmas, dest.begin(),
+        [this](auto i) { return pma_entry{.istart = m_ars[i]->get_istart(), .ilength = m_ars[i]->get_ilength()}; });
 }
 
 void machine::init_tlb_contents(const std::string &image_filename) {
@@ -583,13 +582,13 @@ machine::machine(machine_config c, machine_runtime_config r) : m_c{std::move(c)}
         make_shadow_state_address_range(PMA_SHADOW_STATE_START, PMA_SHADOW_STATE_LENGTH, throw_invalid_argument),
         register_where{.merkle = true, .interpret = false});
     // Will populate when initialization of PMAs is done
-    auto &shpmas = register_address_range(make_shadow_pmas_address_range(PMA_SHADOW_PMAS_START, PMA_SHADOW_PMAS_LENGTH),
+    auto &shpmas = register_address_range(make_pmas_address_range(PMA_PMAS_START, PMA_PMAS_LENGTH),
         register_where{.merkle = true, .interpret = true});
     init_virtio_ars(m_c.virtio, m_c.processor.iunrep);
     init_sentinel_ars();
     // Populate shadow PMAs contents.
     // This must be done after all PMA entries are already registered, so we encode them into the shadow
-    init_shadow_pmas_contents(shpmas);
+    init_pmas_contents(shpmas);
     // Initialize TLB contents.
     // This must be done after all PMA entries are already registered, so we can lookup page addresses
     init_tlb_contents(m_c.tlb.image_filename);
@@ -2016,8 +2015,8 @@ const char *machine::get_what_name(uint64_t paddr) {
     if (paddr >= PMA_SHADOW_STATE_START && paddr - PMA_SHADOW_STATE_START < PMA_SHADOW_STATE_LENGTH) {
         return shadow_state_get_what_name(shadow_state_get_what(paddr));
     }
-    if (paddr >= PMA_SHADOW_PMAS_START && paddr - PMA_SHADOW_PMAS_START < PMA_SHADOW_PMAS_LENGTH) {
-        return shadow_pmas_get_what_name(shadow_pmas_get_what(paddr));
+    if (paddr >= PMA_PMAS_START && paddr - PMA_PMAS_START < PMA_PMAS_LENGTH) {
+        return pma_get_what_name(pma_get_what(paddr));
     }
     if (paddr >= PMA_SHADOW_UARCH_STATE_START && paddr - PMA_SHADOW_UARCH_STATE_START < PMA_SHADOW_UARCH_STATE_LENGTH) {
         return shadow_uarch_state_get_what_name(shadow_uarch_state_get_what(paddr));
diff --git a/src/machine.h b/src/machine.h
index 34cfe8164..cf75ac872 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -189,9 +189,9 @@ class machine final {
     void init_sentinel_ars();
 
     /// \brief Initializes contents of the shadow PMAs memory
-    /// \param shadow_pmas PMA entry for the shadow PMAs
+    /// \param pmas PMA entry for the shadow PMAs
     /// \detail This can only be called after all PMAs have been added
-    void init_shadow_pmas_contents(memory_address_range &shadow_pmas) const;
+    void init_pmas_contents(memory_address_range &pmas) const;
 
     /// \brief Initializes contents of machine TLB, from image in disk or with default values
     /// \param image_filename File containing image, or empty for default values
diff --git a/src/mock-address-range.h b/src/mock-address-range.h
index 30b3cc5a9..b79ede8d0 100644
--- a/src/mock-address-range.h
+++ b/src/mock-address-range.h
@@ -51,7 +51,7 @@ static inline mock_address_range check_mock_flags(AR &&ar, const pma_flags &flag
 template <typename ABRT>
 static inline mock_address_range make_mock_address_range(uint64_t istart, uint64_t ilength, ABRT abrt) {
     uint64_t start{};
-    auto flags = unpack_pma_istart(istart, start);
+    auto flags = pma_unpack_istart(istart, start);
     if (flags.M) {
         return make_address_range(pma_get_DID_name(flags.DID), start, ilength, flags, abrt);
     }
diff --git a/src/pma-constants.h b/src/pma-constants.h
index 723437296..14a589a11 100644
--- a/src/pma-constants.h
+++ b/src/pma-constants.h
@@ -27,8 +27,8 @@ namespace cartesi {
 enum PMA_ranges : uint64_t {
     PMA_SHADOW_STATE_START = EXPAND_UINT64_C(PMA_SHADOW_STATE_START_DEF),   ///< Start of processor shadow range
     PMA_SHADOW_STATE_LENGTH = EXPAND_UINT64_C(PMA_SHADOW_STATE_LENGTH_DEF), ///< Length of processor shadow range
-    PMA_SHADOW_PMAS_START = EXPAND_UINT64_C(PMA_SHADOW_PMAS_START_DEF),     ///< Start of pma board shadow range
-    PMA_SHADOW_PMAS_LENGTH = EXPAND_UINT64_C(PMA_SHADOW_PMAS_LENGTH_DEF),   ///< Length of pma board shadow range
+    PMA_PMAS_START = EXPAND_UINT64_C(PMA_PMAS_START_DEF),                   ///< Start of pma board shadow range
+    PMA_PMAS_LENGTH = EXPAND_UINT64_C(PMA_PMAS_LENGTH_DEF),                 ///< Length of pma board shadow range
     PMA_DTB_START = EXPAND_UINT64_C(PMA_DTB_START_DEF),                     ///< Start of DTB range
     PMA_DTB_LENGTH = EXPAND_UINT64_C(PMA_DTB_LENGTH_DEF),                   ///< Length of DTB range
     PMA_SHADOW_TLB_START = EXPAND_UINT64_C(PMA_SHADOW_TLB_START_DEF),       ///< Start of TLB shadow range
@@ -110,7 +110,6 @@ enum PMA_ISTART_masks : uint64_t {
 enum class PMA_ISTART_DID {
     memory = PMA_MEMORY_DID_DEF,                         ///< DID for memory
     shadow_state = PMA_SHADOW_STATE_DID_DEF,             ///< DID for shadow device
-    shadow_pmas = PMA_SHADOW_PMAS_DID_DEF,               ///< DID for shadow pma array device
     shadow_TLB = PMA_SHADOW_TLB_DID_DEF,                 ///< DID for shadow TLB device
     flash_drive = PMA_FLASH_DRIVE_DID_DEF,               ///< DID for drive device
     CLINT = PMA_CLINT_DID_DEF,                           ///< DID for CLINT device
diff --git a/src/pma-defines.h b/src/pma-defines.h
index 849a92c30..8ad7dfff4 100644
--- a/src/pma-defines.h
+++ b/src/pma-defines.h
@@ -19,8 +19,8 @@
 // NOLINTBEGIN(cppcoreguidelines-macro-usage,cppcoreguidelines-macro-to-enum,modernize-macro-to-enum)
 #define PMA_SHADOW_STATE_START_DEF 0x0            ///< Shadow start address
 #define PMA_SHADOW_STATE_LENGTH_DEF 0x1000        ///< Shadow length in bytes
-#define PMA_SHADOW_PMAS_START_DEF 0x10000         ///< PMA Array start address
-#define PMA_SHADOW_PMAS_LENGTH_DEF 0x1000         ///< PMA Array length in bytes
+#define PMA_PMAS_START_DEF 0x10000                ///< PMA Array start address
+#define PMA_PMAS_LENGTH_DEF 0x1000                ///< PMA Array length in bytes
 #define PMA_SHADOW_TLB_START_DEF 0x20000          ///< TLB start address
 #define PMA_SHADOW_TLB_LENGTH_DEF 0x6000          ///< TLB length in bytes
 #define PMA_SHADOW_UARCH_STATE_START_DEF 0x400000 ///< microarchitecture shadow state start address
@@ -53,16 +53,15 @@
 
 #define PMA_MEMORY_DID_DEF 0              ///< Device ID for memory
 #define PMA_SHADOW_STATE_DID_DEF 1        ///< Device ID for shadow state device
-#define PMA_SHADOW_PMAS_DID_DEF 2         ///< Device ID for shadow pma array device
-#define PMA_FLASH_DRIVE_DID_DEF 3         ///< Device ID for flash drive device
-#define PMA_CLINT_DID_DEF 4               ///< Device ID for CLINT device
-#define PMA_HTIF_DID_DEF 5                ///< Device ID for HTIF device
-#define PMA_SHADOW_TLB_DID_DEF 6          ///< Device ID for shadow TLB device
-#define PMA_CMIO_RX_BUFFER_DID_DEF 7      ///< Device ID for cmio RX buffer
-#define PMA_CMIO_TX_BUFFER_DID_DEF 8      ///< Device ID for cmio TX buffer
-#define PMA_PLIC_DID_DEF 10               ///< Device ID for PLIC device
-#define PMA_VIRTIO_DID_DEF 11             ///< Device ID for VirtIO devices
-#define PMA_SHADOW_UARCH_STATE_DID_DEF 12 ///< Device ID for uarch shadow state device
+#define PMA_FLASH_DRIVE_DID_DEF 2         ///< Device ID for flash drive device
+#define PMA_CLINT_DID_DEF 3               ///< Device ID for CLINT device
+#define PMA_HTIF_DID_DEF 4                ///< Device ID for HTIF device
+#define PMA_SHADOW_TLB_DID_DEF 5          ///< Device ID for shadow TLB device
+#define PMA_CMIO_RX_BUFFER_DID_DEF 6      ///< Device ID for cmio RX buffer
+#define PMA_CMIO_TX_BUFFER_DID_DEF 7      ///< Device ID for cmio TX buffer
+#define PMA_PLIC_DID_DEF 9                ///< Device ID for PLIC device
+#define PMA_VIRTIO_DID_DEF 10             ///< Device ID for VirtIO devices
+#define PMA_SHADOW_UARCH_STATE_DID_DEF 11 ///< Device ID for uarch shadow state device
 
 // helper for using UINT64_C with defines
 #ifndef EXPAND_UINT64_C
diff --git a/src/pma.h b/src/pma.h
index eef556cb0..19ac32fb1 100644
--- a/src/pma.h
+++ b/src/pma.h
@@ -17,8 +17,10 @@
 #ifndef PMA_H
 #define PMA_H
 
+#include <array>
 #include <cstdint>
 
+#include "compiler-defines.h"
 #include "pma-constants.h"
 
 namespace cartesi {
@@ -32,8 +34,6 @@ static constexpr const char *pma_get_DID_name(PMA_ISTART_DID did) {
             return "DID.memory";
         case PMA_ISTART_DID::shadow_state:
             return "DID.shadow_state";
-        case PMA_ISTART_DID::shadow_pmas:
-            return "DID.shadow_pmas";
         case PMA_ISTART_DID::shadow_TLB:
             return "DID.shadow_TLB";
         case PMA_ISTART_DID::flash_drive:
@@ -73,7 +73,7 @@ struct pma_flags {
     bool operator==(const pma_flags &) const = default;
 };
 
-static constexpr pma_flags unpack_pma_istart(uint64_t istart, uint64_t &start) {
+static constexpr pma_flags pma_unpack_istart(uint64_t istart, uint64_t &start) {
     start = istart & PMA_ISTART_START_MASK;
     return pma_flags{.M = ((istart & PMA_ISTART_M_MASK) >> PMA_ISTART_M_SHIFT) != 0,
         .IO = ((istart & PMA_ISTART_IO_MASK) >> PMA_ISTART_IO_SHIFT) != 0,
@@ -86,7 +86,7 @@ static constexpr pma_flags unpack_pma_istart(uint64_t istart, uint64_t &start) {
         .DID = static_cast<PMA_ISTART_DID>((istart & PMA_ISTART_DID_MASK) >> PMA_ISTART_DID_SHIFT)};
 }
 
-static constexpr uint64_t pack_pma_istart(const pma_flags &flags, uint64_t start) {
+static constexpr uint64_t pma_pack_istart(const pma_flags &flags, uint64_t start) {
     uint64_t istart = start;
     istart |= (static_cast<uint64_t>(flags.M) << PMA_ISTART_M_SHIFT);
     istart |= (static_cast<uint64_t>(flags.IO) << PMA_ISTART_IO_SHIFT);
@@ -100,6 +100,67 @@ static constexpr uint64_t pack_pma_istart(const pma_flags &flags, uint64_t start
     return istart;
 }
 
+/// \brief Shadow memory layout
+struct PACKED pma_entry {
+    uint64_t istart;
+    uint64_t ilength;
+};
+
+using pmas_state = std::array<pma_entry, PMA_MAX>;
+
+/// \brief List of field types
+enum class pma_what : uint64_t {
+    istart = offsetof(pma_entry, istart),
+    ilength = offsetof(pma_entry, ilength),
+    unknown_ = UINT64_C(1) << 63, // Outside of RISC-V address space
+};
+
+/// \brief Obtains the absolute address of a PMA entry.
+/// \param p Index of desired PMA entry
+/// \returns The address.
+static constexpr uint64_t pma_get_abs_addr(uint64_t p) {
+    return PMA_PMAS_START + (p * sizeof(pma_entry));
+}
+
+/// \brief Obtains the absolute address of a PMA entry.
+/// \param p Index of desired PMA entry
+/// \param what Desired field
+/// \returns The address.
+static constexpr uint64_t pma_get_abs_addr(uint64_t p, pma_what what) {
+    return pma_get_abs_addr(p) + static_cast<uint64_t>(what);
+}
+
+static constexpr pma_what pma_get_what(uint64_t paddr) {
+    if (paddr < PMA_PMAS_START || paddr - PMA_PMAS_START >= sizeof(pmas_state) ||
+        (paddr & (sizeof(uint64_t) - 1)) != 0) {
+        return pma_what::unknown_;
+    }
+    //??D First condition ensures offset = (paddr-PMA_PMAS_START) >= 0
+    //??D Second ensures offset < sizeof(pmas_state)
+    //??D Third ensures offset is aligned to sizeof(uint64_t)
+    //??D pma_entry only contains uint64_t fields
+    //??D pmas_state_what contains one entry with the offset of each field in pma_entry
+    //??D I don't see how the cast can produce something outside the enum...
+    // NOLINTNEXTLINE(clang-analyzer-optin.core.EnumCastOutOfRange)
+    return pma_what{(paddr - PMA_PMAS_START) % sizeof(pma_entry)};
+}
+
+static constexpr const char *pma_get_what_name(pma_what what) {
+    const auto paddr = static_cast<uint64_t>(what);
+    if (paddr >= sizeof(pma_entry) || (paddr & (sizeof(uint64_t) - 1)) != 0) {
+        return "pma.unknown_";
+    }
+    switch (what) {
+        case pma_what::istart:
+            return "pma.istart";
+        case pma_what::ilength:
+            return "pma.ilength";
+        case pma_what::unknown_:
+            return "pma.unknown_";
+    }
+    return "pmas.unknown_";
+}
+
 } // namespace cartesi
 
 #endif
diff --git a/src/shadow-pmas-address-range.h b/src/pmas-address-range.h
similarity index 73%
rename from src/shadow-pmas-address-range.h
rename to src/pmas-address-range.h
index fd380a342..4a2ce8f07 100644
--- a/src/shadow-pmas-address-range.h
+++ b/src/pmas-address-range.h
@@ -14,23 +14,22 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#ifndef SHADOW_PMAS_ADDRESS_RANGE_H
-#define SHADOW_PMAS_ADDRESS_RANGE_H
+#ifndef PMAS_ADDRESS_RANGE_H
+#define PMAS_ADDRESS_RANGE_H
 
 #include <cstdint>
 #include <stdexcept>
 
 #include "memory-address-range.h"
-#include "pma-constants.h"
-#include "shadow-pmas.h"
+#include "pma.h"
 
 /// \file
 /// \brief Shadow device.
 
 namespace cartesi {
 
-static inline auto make_shadow_pmas_address_range(uint64_t start, uint64_t length) {
-    static constexpr pma_flags shadow_pmas_flags{
+static inline auto make_pmas_address_range(uint64_t start, uint64_t length) {
+    static constexpr pma_flags m_flags{
         .M = true,
         .IO = false,
         .E = false,
@@ -39,9 +38,9 @@ static inline auto make_shadow_pmas_address_range(uint64_t start, uint64_t lengt
         .X = false,
         .IR = false,
         .IW = false,
-        .DID = PMA_ISTART_DID::shadow_pmas,
+        .DID = PMA_ISTART_DID::memory,
     };
-    return make_callocd_memory_address_range("shadow PMAs", start, length, shadow_pmas_flags);
+    return make_callocd_memory_address_range("PMAs", start, length, m_flags);
 }
 
 } // namespace cartesi
diff --git a/src/record-step-state-access.h b/src/record-step-state-access.h
index 710b3328a..c3df12494 100644
--- a/src/record-step-state-access.h
+++ b/src/record-step-state-access.h
@@ -27,7 +27,7 @@
 #include "i-prefer-shadow-state.h"
 #include "i-state-access.h"
 #include "machine.h"
-#include "shadow-pmas-address-range.h"
+#include "pma.h"
 #include "shadow-tlb.h"
 #include "unique-c-ptr.h"
 
@@ -235,8 +235,8 @@ class record_step_state_access :
         // replay_step_state_access reconstructs a mock_address_range from the
         // corresponding istart and ilength fields in the shadow pmas
         // so we mark the page where they live here
-        touch_page(shadow_pmas_get_pma_abs_addr(index, shadow_pmas_what::istart));
-        touch_page(shadow_pmas_get_pma_abs_addr(index, shadow_pmas_what::ilength));
+        touch_page(pma_get_abs_addr(index, pma_what::istart));
+        touch_page(pma_get_abs_addr(index, pma_what::ilength));
         return m_m.read_pma(index);
     }
 
diff --git a/src/replay-step-state-access.h b/src/replay-step-state-access.h
index baf0e6ec6..933506236 100644
--- a/src/replay-step-state-access.h
+++ b/src/replay-step-state-access.h
@@ -27,10 +27,9 @@
 #include "i-prefer-shadow-state.h"
 #include "i-state-access.h"
 #include "mock-address-range.h"
-#include "pma-constants.h"
+#include "pma.h"
 #include "replay-step-state-access-interop.h"
 #include "riscv-constants.h"
-#include "shadow-pmas-address-range.h"
 #include "shadow-state.h"
 #include "shadow-tlb.h"
 #include "shadow-uarch-state.h"
@@ -405,12 +404,12 @@ class replay_step_state_access :
     }
 
     uint64_t read_pma_istart(uint64_t index) const {
-        const auto haddr = do_get_faddr(shadow_pmas_get_pma_abs_addr(index, shadow_pmas_what::istart));
+        const auto haddr = do_get_faddr(pma_get_abs_addr(index, pma_what::istart));
         return aliased_aligned_read<uint64_t>(haddr);
     }
 
     uint64_t read_pma_ilength(uint64_t index) const {
-        const auto haddr = do_get_faddr(shadow_pmas_get_pma_abs_addr(index, shadow_pmas_what::ilength));
+        const auto haddr = do_get_faddr(pma_get_abs_addr(index, pma_what::ilength));
         return aliased_aligned_read<uint64_t>(haddr);
     }
 
diff --git a/src/shadow-pmas.h b/src/shadow-pmas.h
deleted file mode 100644
index 6e7ea2fca..000000000
--- a/src/shadow-pmas.h
+++ /dev/null
@@ -1,96 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef SHADOW_PMAS_H
-#define SHADOW_PMAS_H
-
-#include <array>
-#include <cstdint>
-
-#include "compiler-defines.h"
-#include "pma-constants.h"
-
-/// \file
-/// \brief Shadow device.
-
-namespace cartesi {
-
-/// \brief Shadow memory layout
-
-struct PACKED shadow_pmas_entry {
-    uint64_t istart;
-    uint64_t ilength;
-};
-
-using shadow_pmas_state = std::array<shadow_pmas_entry, PMA_MAX>;
-
-/// \brief List of field types
-enum class shadow_pmas_what : uint64_t {
-    istart = offsetof(shadow_pmas_entry, istart),
-    ilength = offsetof(shadow_pmas_entry, ilength),
-    unknown_ = UINT64_C(1) << 63, // Outside of RISC-V address space
-};
-
-/// \brief Obtains the absolute address of a PMA entry in shadow memory.
-/// \param p Index of desired shadow PMA entry
-/// \returns The address.
-static constexpr uint64_t shadow_pmas_get_pma_abs_addr(uint64_t p) {
-    return PMA_SHADOW_PMAS_START + (p * sizeof(shadow_pmas_entry));
-}
-
-/// \brief Obtains the absolute address of a PMA entry in shadow memory.
-/// \param p Index of desired shadow PMA entry
-/// \param what Desired field
-/// \returns The address.
-static constexpr uint64_t shadow_pmas_get_pma_abs_addr(uint64_t p, shadow_pmas_what what) {
-    return shadow_pmas_get_pma_abs_addr(p) + static_cast<uint64_t>(what);
-}
-
-static constexpr shadow_pmas_what shadow_pmas_get_what(uint64_t paddr) {
-    if (paddr < PMA_SHADOW_PMAS_START || paddr - PMA_SHADOW_PMAS_START >= sizeof(shadow_pmas_state) ||
-        (paddr & (sizeof(uint64_t) - 1)) != 0) {
-        return shadow_pmas_what::unknown_;
-    }
-    //??D First condition ensures offset = (paddr-PMA_SHADOW_PMAS_START) >= 0
-    //??D Second ensures offset < sizeof(shadow_pmas_state)
-    //??D Third ensures offset is aligned to sizeof(uint64_t)
-    //??D shadow_pmas_entry only contains uint64_t fields
-    //??D shadow_pmas_state_what contains one entry with the offset of each field in shadow_pmas_entry
-    //??D I don't see how the cast can produce something outside the enum...
-    // NOLINTNEXTLINE(clang-analyzer-optin.core.EnumCastOutOfRange)
-    return shadow_pmas_what{(paddr - PMA_SHADOW_PMAS_START) % sizeof(shadow_pmas_entry)};
-}
-
-static constexpr const char *shadow_pmas_get_what_name(shadow_pmas_what what) {
-    const auto paddr = static_cast<uint64_t>(what);
-    if (paddr >= sizeof(shadow_pmas_entry) || (paddr & (sizeof(uint64_t) - 1)) != 0) {
-        return "pma.unknown_";
-    }
-    using reg = shadow_pmas_what;
-    switch (what) {
-        case reg::istart:
-            return "pma.istart";
-        case reg::ilength:
-            return "pma.ilength";
-        case reg::unknown_:
-            return "pma.unknown_";
-    }
-    return "pmas.unknown_";
-}
-
-} // namespace cartesi
-
-#endif
diff --git a/tests/lua/machine-test.lua b/tests/lua/machine-test.lua
index 7520c9e4c..616dc5604 100755
--- a/tests/lua/machine-test.lua
+++ b/tests/lua/machine-test.lua
@@ -353,7 +353,7 @@ test_util.make_do_test(build_machine, machine_type, {
     local rootfs = machine:get_initial_config().flash_drive[1]
     -- Create temp flash file
     local input_path = test_path .. "input.raw"
-    local replaced_data = 'test data 1234567890'
+    local replaced_data = "test data 1234567890"
     local command = string.format("echo '%s' > ", replaced_data)
         .. input_path
         .. " && truncate -s "
@@ -369,7 +369,7 @@ test_util.make_do_test(build_machine, machine_type, {
 
     local read_data = machine:read_memory(rootfs.start, 20)
 
-    if (read_data ~= replaced_data) then
+    if read_data ~= replaced_data then
         error(string.format("expected to read %q from replaced drive (got %q)", replaced_data, read_data))
     end
     os.remove(input_path)

From 208063b392f02fcf23d301e3a1c42dba0163d232 Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Sun, 2 Mar 2025 13:07:41 +0000
Subject: [PATCH 24/82] refactor: split PMA and AR constants

PMA is only used for the two-word description of address ranges in memory
All other constants use AR (for address range)
Also simplified machine::read_memory()
---
 src/Makefile                                |  24 +-
 src/address-range-constants.h               |  77 ++++++
 src/address-range-defines.h                 |  58 +++++
 src/address-range.h                         |  22 +-
 src/clint-address-range.cpp                 |   4 +-
 src/clint-address-range.h                   |   2 +-
 src/clua-cartesi.cpp                        |  10 +-
 src/dtb.cpp                                 |  38 +--
 src/{find-pma-entry.h => find-pmas-entry.h} |   0
 src/htif-address-range.h                    |   4 +-
 src/i-state-access.h                        |   2 +-
 src/interpret.cpp                           |   2 +-
 src/jsonrpc-virtual-machine.cpp             |   2 +-
 src/machine-c-api.cpp                       |  14 +-
 src/machine-c-api.h                         |  14 +-
 src/machine-config.cpp                      |  14 +-
 src/machine.cpp                             | 265 ++++++++++----------
 src/machine.h                               |   2 +-
 src/memory-address-range.cpp                |   8 +-
 src/memory-address-range.h                  |  14 +-
 src/mock-address-range.h                    |   8 +-
 src/plic-address-range.cpp                  |  10 +-
 src/plic-address-range.h                    |   2 +-
 src/plic-constants.h                        |   1 +
 src/pma-constants.h                         | 126 ----------
 src/pma-defines.h                           |  71 ------
 src/pmas-address-range.h                    |   4 +-
 src/pmas-constants.h                        |  77 ++++++
 src/pmas-defines.h                          |  41 +++
 src/{pma.h => pmas.h}                       |  65 ++---
 src/pristine-address-range.h                |   2 +-
 src/record-send-cmio-state-access.h         |   4 +-
 src/record-step-state-access.h              |   6 +-
 src/replay-step-state-access.h              |  31 ++-
 src/riscv-constants.h                       |  69 ++---
 src/send-cmio-response.cpp                  |   6 +-
 src/shadow-state-address-range.h            |   2 +-
 src/shadow-state.h                          | 218 ++++++++--------
 src/shadow-tlb-address-range.h              |   2 +-
 src/shadow-tlb-factory.h                    |   2 +-
 src/shadow-tlb.h                            |   8 +-
 src/shadow-uarch-state-address-range.cpp    |   4 +-
 src/shadow-uarch-state-address-range.h      |   2 +-
 src/shadow-uarch-state.h                    |  74 +++---
 src/state-access.h                          |   2 +-
 src/tlb.h                                   |   2 +-
 src/translate-virtual-address.h             |   2 +-
 src/uarch-constants.h                       |  16 +-
 src/uarch-defines.h                         |   4 +-
 src/uarch-replay-state-access.h             |   4 +-
 src/virtio-address-range.cpp                |   2 +-
 src/virtio-address-range.h                  |   2 +-
 tests/lua/create-machines.lua               |   4 +-
 tests/lua/htif-cmio.lua                     |   8 +-
 tests/lua/machine-bind.lua                  |  73 +++---
 tests/lua/machine-test.lua                  |   4 +-
 tests/machine/src/access.S                  |   4 +-
 tests/machine/src/bootstrap.S               |   4 +-
 tests/machine/src/clint_ops.S               |  26 +-
 tests/machine/src/compressed.S              |   4 +-
 tests/machine/src/csr_counters.S            |   4 +-
 tests/machine/src/csr_semantics.S           |   4 +-
 tests/machine/src/dont_write_x0.S           |   4 +-
 tests/machine/src/ebreak.S                  |   4 +-
 tests/machine/src/htif_cmio.S               |   9 +-
 tests/machine/src/htif_console.S            |   2 +-
 tests/machine/src/htif_invalid_ops.S        |  20 +-
 tests/machine/src/htif_util.h               |   4 +-
 tests/machine/src/htif_yield.S              |   6 +-
 tests/machine/src/illegal_insn.S            |   4 +-
 tests/machine/src/interrupts.S              |   6 +-
 tests/machine/src/lrsc_semantics.S          |   6 +-
 tests/machine/src/mcycle_overflow.S         |   4 +-
 tests/machine/src/mcycle_write.S            |   4 +-
 tests/machine/src/mtime_interrupt.S         |   6 +-
 tests/machine/src/pte_reserved_exception.S  |   4 +-
 tests/machine/src/sd_pma_overflow.S         |   4 +-
 tests/machine/src/shadow_ops.S              |  26 +-
 tests/machine/src/translate_vaddr.S         |   4 +-
 tests/machine/src/version_check.S           |   4 +-
 tests/machine/src/xpie_exceptions.S         |   4 +-
 tests/misc/test-machine-c-api.cpp           |   6 +-
 third-party/riscv-arch-test                 |   2 +-
 uarch/compute-uarch-pristine-hash.cpp       |  14 +-
 uarch/machine-uarch-bridge-state-access.h   |   7 +-
 uarch/uarch-ram-entry.S                     |   6 +-
 uarch/uarch-ram.ld.in                       |  12 +-
 87 files changed, 896 insertions(+), 856 deletions(-)
 create mode 100644 src/address-range-constants.h
 create mode 100644 src/address-range-defines.h
 rename src/{find-pma-entry.h => find-pmas-entry.h} (100%)
 delete mode 100644 src/pma-constants.h
 delete mode 100644 src/pma-defines.h
 create mode 100644 src/pmas-constants.h
 create mode 100644 src/pmas-defines.h
 rename src/{pma.h => pmas.h} (73%)

diff --git a/src/Makefile b/src/Makefile
index 214326e2d..d170c1660 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -175,19 +175,19 @@ DEFS+=-D_FILE_OFFSET_BITS=64
 DEFS+=-DJSON_HAS_FILESYSTEM=0
 
 ifeq ($(dump),yes)
-DUMP_DEFS+=-DDUMP_ILLEGAL_INSN_EXCEPTIONS
-DUMP_DEFS+=-DDUMP_EXCEPTIONS
-DUMP_DEFS+=-DDUMP_INTERRUPTS
-DUMP_DEFS+=-DDUMP_MMU_EXCEPTIONS
-DUMP_DEFS+=-DDUMP_INVALID_CSR
-DUMP_DEFS+=-DDUMP_REGS
-DUMP_DEFS+=-DDUMP_INSN_HIST
-DUMP_DEFS+=-DDUMP_STATS
+#DUMP_DEFS+=-DDUMP_ILLEGAL_INSN_EXCEPTIONS
+#DUMP_DEFS+=-DDUMP_EXCEPTIONS
+#DUMP_DEFS+=-DDUMP_INTERRUPTS
+#DUMP_DEFS+=-DDUMP_MMU_EXCEPTIONS
+#DUMP_DEFS+=-DDUMP_INVALID_CSR
+#DUMP_DEFS+=-DDUMP_REGS
+#DUMP_DEFS+=-DDUMP_INSN_HIST
+#DUMP_DEFS+=-DDUMP_STATS
 DUMP_DEFS+=-DDUMP_INSN
-DUMP_DEFS+=-DDUMP_UARCH_INSN
-DUMP_DEFS+=-DDUMP_SCOPED_NOTE
-DUMP_DEFS+=-DDUMP_STATE_ACCESS
-DUMP_DEFS+=-DDUMP_UARCH_STATE_ACCESS
+#DUMP_DEFS+=-DDUMP_UARCH_INSN
+#DUMP_DEFS+=-DDUMP_SCOPED_NOTE
+#DUMP_DEFS+=-DDUMP_STATE_ACCESS
+#DUMP_DEFS+=-DDUMP_UARCH_STATE_ACCESS
 endif
 DEFS += $(DUMP_DEFS)
 # Pass down UARCH_DEFS to sub-makefiles
diff --git a/src/address-range-constants.h b/src/address-range-constants.h
new file mode 100644
index 000000000..1c4fdb65f
--- /dev/null
+++ b/src/address-range-constants.h
@@ -0,0 +1,77 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef ADDRESS_RANGE_CONSTANTS_H
+#define ADDRESS_RANGE_CONSTANTS_H
+
+#include <cstdint>
+
+#include "address-range-defines.h"
+
+namespace cartesi {
+
+/// \brief Fixed address ranges.
+enum AR_ranges : uint64_t {
+    AR_SHADOW_STATE_START = EXPAND_UINT64_C(AR_SHADOW_STATE_START_DEF),   ///< Start of shadow state range
+    AR_SHADOW_STATE_LENGTH = EXPAND_UINT64_C(AR_SHADOW_STATE_LENGTH_DEF), ///< Length of shadow state range
+    AR_PMAS_START = EXPAND_UINT64_C(AR_PMAS_START_DEF),                   ///< Start of PMAS list range
+    AR_PMAS_LENGTH = EXPAND_UINT64_C(AR_PMAS_LENGTH_DEF),                 ///< Length of PMAS list range
+    AR_DTB_START = EXPAND_UINT64_C(AR_DTB_START_DEF),                     ///< Start of DTB range
+    AR_DTB_LENGTH = EXPAND_UINT64_C(AR_DTB_LENGTH_DEF),                   ///< Length of DTB range
+    AR_SHADOW_TLB_START = EXPAND_UINT64_C(AR_SHADOW_TLB_START_DEF),       ///< Start of shadow TLB range
+    AR_SHADOW_TLB_LENGTH = EXPAND_UINT64_C(AR_SHADOW_TLB_LENGTH_DEF),     ///< Length of shadow TLB range
+    AR_SHADOW_UARCH_STATE_START =
+        EXPAND_UINT64_C(AR_SHADOW_UARCH_STATE_START_DEF), ///< Start of uarch shadow state range
+    AR_SHADOW_UARCH_STATE_LENGTH =
+        EXPAND_UINT64_C(AR_SHADOW_UARCH_STATE_LENGTH_DEF),                  ///< Length of uarch shadow state range
+    AR_CLINT_START = EXPAND_UINT64_C(AR_CLINT_START_DEF),                   ///< Start of CLINT range
+    AR_CLINT_LENGTH = EXPAND_UINT64_C(AR_CLINT_LENGTH_DEF),                 ///< Length of CLINT range
+    AR_PLIC_START = EXPAND_UINT64_C(AR_PLIC_START_DEF),                     ///< Start of PLIC range
+    AR_PLIC_LENGTH = EXPAND_UINT64_C(AR_PLIC_LENGTH_DEF),                   ///< Length of PLIC range
+    AR_HTIF_START = EXPAND_UINT64_C(AR_HTIF_START_DEF),                     ///< Start of HTIF range
+    AR_HTIF_LENGTH = EXPAND_UINT64_C(AR_HTIF_LENGTH_DEF),                   ///< Length of HTIF range
+    AR_UARCH_RAM_START = EXPAND_UINT64_C(AR_UARCH_RAM_START_DEF),           ///< Start of uarch RAM range
+    AR_UARCH_RAM_LENGTH = EXPAND_UINT64_C(AR_UARCH_RAM_LENGTH_DEF),         ///< Length of uarch RAM range
+    AR_CMIO_RX_BUFFER_START = EXPAND_UINT64_C(AR_CMIO_RX_BUFFER_START_DEF), ///< Start of CMIO RX buffer range
+    AR_CMIO_RX_BUFFER_LOG2_SIZE = EXPAND_UINT64_C(AR_CMIO_RX_BUFFER_LOG2_SIZE_DEF), ///< Log2 of CMIO RX buffer range
+    AR_CMIO_RX_BUFFER_LENGTH = (UINT64_C(1) << AR_CMIO_RX_BUFFER_LOG2_SIZE_DEF),    ///< Length of CMIO RX buffer range
+    AR_CMIO_TX_BUFFER_START = EXPAND_UINT64_C(AR_CMIO_TX_BUFFER_START_DEF),         ///< Start of CMIO TX buffer range
+    AR_CMIO_TX_BUFFER_LOG2_SIZE = EXPAND_UINT64_C(AR_CMIO_TX_BUFFER_LOG2_SIZE_DEF), ///< Log2 of CMIO TX buffer range
+    AR_CMIO_TX_BUFFER_LENGTH = (UINT64_C(1) << AR_CMIO_TX_BUFFER_LOG2_SIZE_DEF),    ///< Length of CMIO TX buffer range
+    AR_DRIVE_START = EXPAND_UINT64_C(AR_DRIVE_START_DEF),   ///< Start address for flash drive ranges
+    AR_DRIVE_OFFSET = EXPAND_UINT64_C(AR_DRIVE_OFFSET_DEF), ///< Offset for extra flash drive ranges
+
+    AR_FIRST_VIRTIO_START = EXPAND_UINT64_C(AR_FIRST_VIRTIO_START_DEF), ///< Start of first VIRTIO range
+    AR_VIRTIO_LENGTH = EXPAND_UINT64_C(AR_VIRTIO_LENGTH_DEF),           ///< Length of each VIRTIO range
+    AR_LAST_VIRTIO_END = EXPAND_UINT64_C(AR_LAST_VIRTIO_END_DEF),       ///< End of last VIRTIO range
+
+    AR_RAM_START = EXPAND_UINT64_C(AR_RAM_START_DEF), ///< Start of RAM range
+};
+
+/// \brief PMA constants.
+enum AR_constants : uint64_t {
+    AR_PAGE_SIZE_LOG2 = EXPAND_UINT64_C(AR_PAGE_SIZE_LOG2_DEF), ///< Log<sub>2</sub> of physical memory page size.
+    AR_PAGE_SIZE = (UINT64_C(1) << AR_PAGE_SIZE_LOG2_DEF),      ///< Physical memory page size.
+};
+
+/// \brief PMA masks.
+enum AR_masks : uint64_t {
+    AR_ADDRESSABLE_MASK = ((UINT64_C(1) << 56) - 1) ///< Mask for addressable ranges.
+};
+
+} // namespace cartesi
+
+#endif
diff --git a/src/address-range-defines.h b/src/address-range-defines.h
new file mode 100644
index 000000000..4f49e9141
--- /dev/null
+++ b/src/address-range-defines.h
@@ -0,0 +1,58 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef AR_DEFINES_H
+#define AR_DEFINES_H
+
+// NOLINTBEGIN(cppcoreguidelines-macro-usage,cppcoreguidelines-macro-to-enum,modernize-macro-to-enum)
+#define AR_SHADOW_STATE_START_DEF 0x0            ///< Shadow start address
+#define AR_SHADOW_STATE_LENGTH_DEF 0x1000        ///< Shadow length in bytes
+#define AR_PMAS_START_DEF 0x10000                ///< PMA Array start address
+#define AR_PMAS_LENGTH_DEF 0x1000                ///< PMA Array length in bytes
+#define AR_SHADOW_TLB_START_DEF 0x20000          ///< TLB start address
+#define AR_SHADOW_TLB_LENGTH_DEF 0x6000          ///< TLB length in bytes
+#define AR_SHADOW_UARCH_STATE_START_DEF 0x400000 ///< microarchitecture shadow state start address
+#define AR_SHADOW_UARCH_STATE_LENGTH_DEF 0x1000  ///< microarchitecture shadow state length
+#define AR_UARCH_RAM_START_DEF 0x600000          ///< microarchitecture RAM start address
+#define AR_UARCH_RAM_LENGTH_DEF 0x200000         ///< microarchitecture RAM length
+#define AR_CLINT_START_DEF 0x2000000             ///< CLINT start address
+#define AR_CLINT_LENGTH_DEF 0xC0000              ///< CLINT length in bytes
+#define AR_PLIC_START_DEF 0x40100000             ///< Start of PLIC range
+#define AR_PLIC_LENGTH_DEF 0x00400000            ///< Length of PLIC range
+#define AR_HTIF_START_DEF 0x40008000             ///< HTIF base address (to_host)
+#define AR_HTIF_LENGTH_DEF 0x1000                ///< HTIF length in bytes
+#define AR_FIRST_VIRTIO_START_DEF 0x40010000     ///< Start of first VIRTIO range
+#define AR_VIRTIO_LENGTH_DEF 0x1000              ///< Length of each VIRTIO range
+#define AR_LAST_VIRTIO_END_DEF 0x40020000        ///< End of last VIRTIO range
+#define AR_DTB_START_DEF 0x7ff00000              ///< DTB start address
+#define AR_DTB_LENGTH_DEF 0x100000               ///< DTB length in bytes
+#define AR_CMIO_RX_BUFFER_START_DEF 0x60000000   ///< CMIO RX buffer start address
+#define AR_CMIO_RX_BUFFER_LOG2_SIZE_DEF 21       ///< log<sub>2</sub> of CMIO RX buffer length in bytes
+#define AR_CMIO_TX_BUFFER_START_DEF 0x60800000   ///< CMIO TX buffer start address
+#define AR_CMIO_TX_BUFFER_LOG2_SIZE_DEF 21       ///< log<sub>2</sub> of CMIO TX buffer length in bytes
+#define AR_DRIVE_START_DEF 0x80000000000000      ///< Start PMA address for flash drives
+#define AR_DRIVE_OFFSET_DEF 0x10000000000000     ///< PMA offset for extra flash drives
+
+#define AR_RAM_START_DEF 0x80000000 ///< RAM start address
+
+#define AR_PAGE_SIZE_LOG2_DEF 12 ///< log<sub>2</sub> of physical memory page size.
+
+// helper for using UINT64_C with defines
+#ifndef EXPAND_UINT64_C
+#define EXPAND_UINT64_C(a) UINT64_C(a)
+#endif
+// NOLINTEND(cppcoreguidelines-macro-usage,cppcoreguidelines-macro-to-enum,modernize-macro-to-enum)
+#endif /* end of include guard: AR_DEFINES_H */
diff --git a/src/address-range.h b/src/address-range.h
index 58ca773f3..354e5f80b 100644
--- a/src/address-range.h
+++ b/src/address-range.h
@@ -26,7 +26,7 @@
 #include "assert-printf.h"
 #include "i-device-state-access.h"
 #include "interpret.h"
-#include "pma.h"
+#include "pmas.h"
 
 namespace cartesi {
 
@@ -44,7 +44,7 @@ class address_range {
     uint64_t m_start;                   ///< Target physical address where range starts.
     uint64_t m_length;                  ///< Length of range, in bytes.
     uint64_t m_length_bit_ceil;         ///< Smallest power of 2 that is not smaller than length, in bytes.
-    pma_flags m_flags;                  ///< Physical memory attribute flags for range.
+    pmas_flags m_flags;                 ///< Physical memory attribute flags for range.
 
 public:
     /// \brief Noexcept constexpr constructor for empty ranges with description
@@ -84,7 +84,7 @@ class address_range {
     /// \param length Length of range, in bytes
     /// \param f Phyical memory attribute flags for range
     template <typename ABRT>
-    address_range(const char *description, uint64_t start, uint64_t length, const pma_flags &flags, ABRT abrt) :
+    address_range(const char *description, uint64_t start, uint64_t length, const pmas_flags &flags, ABRT abrt) :
         m_description{},
         m_start{start},
         m_length{length},
@@ -98,12 +98,12 @@ class address_range {
             m_description[i] = description[i];
         }
         // All address ranges must be page-aligned
-        if ((m_length & ~PMA_ISTART_START_MASK) != 0) {
+        if ((m_length & ~AR_ISTART_START_MASK) != 0) {
             ABRTF(abrt, "length must be multiple of page size when initializing %s", m_description);
         }
-        if ((m_start & ~PMA_ISTART_START_MASK) != 0) {
+        if ((m_start & ~AR_ISTART_START_MASK) != 0) {
             ABRTF(abrt, "start of %s (0x%" PRIx64 ") must be aligned to page boundary of %d bytes", m_description,
-                start, PMA_PAGE_SIZE);
+                start, AR_PAGE_SIZE);
         }
         // It must be possible to round length up to the next power of two
         if (m_length_bit_ceil == 0) {
@@ -148,7 +148,7 @@ class address_range {
 
     /// \brief Returns PMA flags used during construction
     /// \returns Flags
-    const pma_flags &get_flags() const noexcept {
+    const pmas_flags &get_flags() const noexcept {
         return m_flags;
     }
 
@@ -233,7 +233,7 @@ class address_range {
     /// \brief Returns packed address range istart field as per whitepaper
     /// \returns Packed address range istart
     uint64_t get_istart() const noexcept {
-        return pma_pack_istart(m_flags, m_start);
+        return pmas_pack_istart(m_flags, m_start);
     }
 
     /// \brief Returns encoded addres range ilength field as per whitepaper
@@ -306,9 +306,9 @@ class address_range {
     /// \param offset Start of range of interest, relative to start of this range
     /// \param length Length of range of interest, in bytes
     void mark_dirty_pages(uint64_t offset, uint64_t length) noexcept {
-        auto offset_aligned = offset &= ~(PMA_PAGE_SIZE - 1);
+        auto offset_aligned = offset &= ~(AR_PAGE_SIZE - 1);
         const auto length_aligned = length + (offset - offset_aligned);
-        for (; offset_aligned < length_aligned; offset_aligned += PMA_PAGE_SIZE) {
+        for (; offset_aligned < length_aligned; offset_aligned += AR_PAGE_SIZE) {
             mark_dirty_page(offset_aligned);
         }
     }
@@ -383,7 +383,7 @@ constexpr static auto make_empty_address_range(const char (&description)[N]) {
 }
 
 template <typename ABRT>
-static inline auto make_address_range(const char *description, uint64_t start, uint64_t length, pma_flags f,
+static inline auto make_address_range(const char *description, uint64_t start, uint64_t length, pmas_flags f,
     ABRT abrt) {
     return address_range{description, start, length, f, abrt};
 }
diff --git a/src/clint-address-range.cpp b/src/clint-address-range.cpp
index 4622fa42e..9ffeb0416 100644
--- a/src/clint-address-range.cpp
+++ b/src/clint-address-range.cpp
@@ -20,7 +20,7 @@
 
 #include "i-device-state-access.h"
 #include "interpret.h"
-#include "pma-constants.h"
+#include "pmas-constants.h"
 #include "riscv-constants.h"
 #include "rtc.h"
 
@@ -43,7 +43,7 @@ static constexpr auto clint_mtime_rel_addr = static_cast<uint64_t>(clint_csr::mt
 constexpr auto clint_mtimecmp_rel_addr = static_cast<uint64_t>(clint_csr::mtimecmp);
 
 static constexpr uint64_t base(uint64_t v) {
-    return v - (v % PMA_PAGE_SIZE);
+    return v - (v % AR_PAGE_SIZE);
 }
 
 static bool clint_read_msip(i_device_state_access *a, uint64_t *val, int log2_size) {
diff --git a/src/clint-address-range.h b/src/clint-address-range.h
index b1d46aef0..96b024075 100644
--- a/src/clint-address-range.h
+++ b/src/clint-address-range.h
@@ -28,7 +28,7 @@ namespace cartesi {
 
 class clint_address_range final : public pristine_address_range {
 
-    static constexpr pma_flags m_clint_flags{
+    static constexpr pmas_flags m_clint_flags{
         .M = false,
         .IO = true,
         .E = false,
diff --git a/src/clua-cartesi.cpp b/src/clua-cartesi.cpp
index 232638c87..f39ee3250 100644
--- a/src/clua-cartesi.cpp
+++ b/src/clua-cartesi.cpp
@@ -220,11 +220,11 @@ CM_API int luaopen_cartesi(lua_State *L) {
     clua_setintegerfield(L, CM_CMIO_YIELD_MANUAL_REASON_TX_EXCEPTION, "CMIO_YIELD_MANUAL_REASON_TX_EXCEPTION", -1);
     clua_setintegerfield(L, CM_CMIO_YIELD_REASON_ADVANCE_STATE, "CMIO_YIELD_REASON_ADVANCE_STATE", -1);
     clua_setintegerfield(L, CM_CMIO_YIELD_REASON_INSPECT_STATE, "CMIO_YIELD_REASON_INSPECT_STATE", -1);
-    clua_setintegerfield(L, CM_PMA_CMIO_RX_BUFFER_START, "PMA_CMIO_RX_BUFFER_START", -1);
-    clua_setintegerfield(L, CM_PMA_CMIO_RX_BUFFER_LOG2_SIZE, "PMA_CMIO_RX_BUFFER_LOG2_SIZE", -1);
-    clua_setintegerfield(L, CM_PMA_CMIO_TX_BUFFER_START, "PMA_CMIO_TX_BUFFER_START", -1);
-    clua_setintegerfield(L, CM_PMA_CMIO_TX_BUFFER_LOG2_SIZE, "PMA_CMIO_TX_BUFFER_LOG2_SIZE", -1);
-    clua_setintegerfield(L, CM_PMA_RAM_START, "PMA_RAM_START", -1);
+    clua_setintegerfield(L, CM_AR_CMIO_RX_BUFFER_START, "AR_CMIO_RX_BUFFER_START", -1);
+    clua_setintegerfield(L, CM_AR_CMIO_RX_BUFFER_LOG2_SIZE, "AR_CMIO_RX_BUFFER_LOG2_SIZE", -1);
+    clua_setintegerfield(L, CM_AR_CMIO_TX_BUFFER_START, "AR_CMIO_TX_BUFFER_START", -1);
+    clua_setintegerfield(L, CM_AR_CMIO_TX_BUFFER_LOG2_SIZE, "AR_CMIO_TX_BUFFER_LOG2_SIZE", -1);
+    clua_setintegerfield(L, CM_AR_RAM_START, "AR_RAM_START", -1);
     // Set other constants used by internal tests
     clua_setintegerfield(L, UARCH_STATE_START_ADDRESS, "UARCH_STATE_START_ADDRESS", -1);
     clua_setintegerfield(L, UARCH_STATE_LOG2_SIZE, "UARCH_STATE_LOG2_SIZE", -1);
diff --git a/src/dtb.cpp b/src/dtb.cpp
index 5d0914896..7024fd3ad 100644
--- a/src/dtb.cpp
+++ b/src/dtb.cpp
@@ -24,10 +24,12 @@
 #include <stdexcept>
 #include <string>
 
+#include "address-range-constants.h"
 #include "fdt-builder.h"
 #include "machine-c-version.h"
 #include "machine-config.h"
-#include "pma-constants.h"
+#include "plic-constants.h"
+#include "pmas-constants.h"
 #include "riscv-constants.h"
 #include "rng-seed.h"
 #include "rtc.h"
@@ -119,38 +121,38 @@ void dtb_init(const machine_config &c, unsigned char *dtb_start, uint64_t dtb_le
             fdt.prop_string("compatible", "ucbbar,riscvemu-bar-soc\0simple-bus"s);
             fdt.prop_empty("ranges");
             { // clint
-                fdt.begin_node_num("clint", PMA_CLINT_START);
+                fdt.begin_node_num("clint", AR_CLINT_START);
                 fdt.prop_string("compatible", "riscv,clint0");
-                fdt.prop_u64_list<2>("reg", {PMA_CLINT_START, PMA_CLINT_LENGTH});
+                fdt.prop_u64_list<2>("reg", {AR_CLINT_START, AR_CLINT_LENGTH});
                 fdt.prop_u32_list<4>("interrupts-extended",
                     {INTC_PHANDLE, MIP_MSIP_SHIFT, INTC_PHANDLE, MIP_MTIP_SHIFT});
                 fdt.end_node();
             }
             { // plic
-                fdt.begin_node_num("plic", PMA_PLIC_START);
+                fdt.begin_node_num("plic", AR_PLIC_START);
                 fdt.prop_u32("#interrupt-cells", 1);
                 fdt.prop_empty("interrupt-controller");
                 fdt.prop_string("compatible", "riscv,plic0");
-                fdt.prop_u32("riscv,ndev", PMA_PLIC_MAX_IRQ);
-                fdt.prop_u64_list<2>("reg", {PMA_PLIC_START, PMA_PLIC_LENGTH});
+                fdt.prop_u32("riscv,ndev", PLIC_MAX_IRQ);
+                fdt.prop_u64_list<2>("reg", {AR_PLIC_START, AR_PLIC_LENGTH});
                 fdt.prop_u32_list<4>("interrupts-extended",
                     {INTC_PHANDLE, MIP_SEIP_SHIFT, INTC_PHANDLE, MIP_MEIP_SHIFT});
                 fdt.prop_u32("phandle", PLIC_PHANDLE);
                 fdt.end_node();
             }
             { // htif
-                fdt.begin_node_num("htif", PMA_HTIF_START);
+                fdt.begin_node_num("htif", AR_HTIF_START);
                 fdt.prop_string("compatible", "ucb,htif0");
-                fdt.prop_u64_list<2>("reg", {PMA_HTIF_START, PMA_HTIF_LENGTH});
+                fdt.prop_u64_list<2>("reg", {AR_HTIF_START, AR_HTIF_LENGTH});
                 fdt.prop_u32_list<2>("interrupts-extended", {INTC_PHANDLE, X_HOST});
                 fdt.end_node();
             }
             for (uint32_t virtio_idx = 0; virtio_idx < c.virtio.size(); ++virtio_idx) { // virtio
-                const uint64_t virtio_paddr = PMA_FIRST_VIRTIO_START + (virtio_idx * PMA_VIRTIO_LENGTH);
+                const uint64_t virtio_paddr = AR_FIRST_VIRTIO_START + (virtio_idx * AR_VIRTIO_LENGTH);
                 const uint32_t plic_irq_id = virtio_idx + 1;
                 fdt.begin_node_num("virtio", virtio_paddr);
                 fdt.prop_string("compatible", "virtio,mmio");
-                fdt.prop_u64_list<2>("reg", {virtio_paddr, PMA_VIRTIO_LENGTH});
+                fdt.prop_u64_list<2>("reg", {virtio_paddr, AR_VIRTIO_LENGTH});
                 fdt.prop_u32_list<2>("interrupts-extended", {PLIC_PHANDLE, plic_irq_id});
                 fdt.end_node();
             }
@@ -158,9 +160,9 @@ void dtb_init(const machine_config &c, unsigned char *dtb_start, uint64_t dtb_le
         }
 
         { // memory
-            fdt.begin_node_num("memory", PMA_RAM_START);
+            fdt.begin_node_num("memory", AR_RAM_START);
             fdt.prop_string("device_type", "memory");
-            fdt.prop_u64_list<2>("reg", {PMA_RAM_START, c.ram.length});
+            fdt.prop_u64_list<2>("reg", {AR_RAM_START, c.ram.length});
             fdt.end_node();
         }
 
@@ -170,8 +172,8 @@ void dtb_init(const machine_config &c, unsigned char *dtb_start, uint64_t dtb_le
             fdt.prop_u32("#size-cells", 2);
             fdt.prop_empty("ranges");
             { // reserve 256KB for firmware M-mode code (such as OpenSBI)
-                fdt.begin_node_num("fw_resv", PMA_RAM_START);
-                fdt.prop_u64_list<2>("reg", {PMA_RAM_START, 0x40000});
+                fdt.begin_node_num("fw_resv", AR_RAM_START);
+                fdt.prop_u64_list<2>("reg", {AR_RAM_START, 0x40000});
                 fdt.prop_empty("no-map");
                 fdt.end_node();
             }
@@ -193,13 +195,13 @@ void dtb_init(const machine_config &c, unsigned char *dtb_start, uint64_t dtb_le
         fdt.prop_u32("#size-cells", 2);
         fdt.prop_string("compatible", "ctsi-cmio");
         { // rx_buffer
-            fdt.begin_node_num("rx_buffer", PMA_CMIO_RX_BUFFER_START);
-            fdt.prop_u64_list<2>("reg", {PMA_CMIO_RX_BUFFER_START, PMA_CMIO_RX_BUFFER_LENGTH});
+            fdt.begin_node_num("rx_buffer", AR_CMIO_RX_BUFFER_START);
+            fdt.prop_u64_list<2>("reg", {AR_CMIO_RX_BUFFER_START, AR_CMIO_RX_BUFFER_LENGTH});
             fdt.end_node();
         }
         { // tx_buffer
-            fdt.begin_node_num("tx_buffer", PMA_CMIO_TX_BUFFER_START);
-            fdt.prop_u64_list<2>("reg", {PMA_CMIO_TX_BUFFER_START, PMA_CMIO_TX_BUFFER_LENGTH});
+            fdt.begin_node_num("tx_buffer", AR_CMIO_TX_BUFFER_START);
+            fdt.prop_u64_list<2>("reg", {AR_CMIO_TX_BUFFER_START, AR_CMIO_TX_BUFFER_LENGTH});
             fdt.end_node();
         }
         fdt.end_node();
diff --git a/src/find-pma-entry.h b/src/find-pmas-entry.h
similarity index 100%
rename from src/find-pma-entry.h
rename to src/find-pmas-entry.h
diff --git a/src/htif-address-range.h b/src/htif-address-range.h
index d7fd5cde8..c19ec87e5 100644
--- a/src/htif-address-range.h
+++ b/src/htif-address-range.h
@@ -20,7 +20,7 @@
 #include <cstdint>
 
 #include "i-device-state-access.h"
-#include "pma-constants.h"
+#include "pmas-constants.h"
 #include "pristine-address-range.h"
 
 /// \file
@@ -30,7 +30,7 @@ namespace cartesi {
 
 class htif_address_range final : public pristine_address_range {
 
-    static constexpr pma_flags m_htif_flags{
+    static constexpr pmas_flags m_htif_flags{
         .M = false,
         .IO = true,
         .E = false,
diff --git a/src/i-state-access.h b/src/i-state-access.h
index 4fc9bbb25..9af18c05f 100644
--- a/src/i-state-access.h
+++ b/src/i-state-access.h
@@ -270,7 +270,7 @@ class i_state_access { // CRTP
     address_range &read_pma(uint64_t index) const {
         auto &ar = derived().do_read_pma(index);
         DSA_PRINTF("%s::read_address_range(%" PRIu64 ") = {%s, 0x%" PRIx64 ", 0x%" PRIx64 "}\n", get_name(), index,
-            pma_get_DID_name(ar.get_driver_id()), ar.get_start(), ar.get_length());
+            pmas_get_DID_name(ar.get_driver_id()), ar.get_start(), ar.get_length());
         return ar;
     }
 
diff --git a/src/interpret.cpp b/src/interpret.cpp
index 282344f4b..30507daa7 100644
--- a/src/interpret.cpp
+++ b/src/interpret.cpp
@@ -103,7 +103,7 @@
 #include "compiler-defines.h"
 #include "device-state-access.h"
 #include "dump.h"
-#include "find-pma-entry.h"
+#include "find-pmas-entry.h"
 #include "i-accept-counters.h"
 #include "i-interactive-state-access.h"
 #include "i-state-access.h"
diff --git a/src/jsonrpc-virtual-machine.cpp b/src/jsonrpc-virtual-machine.cpp
index 455f29e35..c2606d5bb 100644
--- a/src/jsonrpc-virtual-machine.cpp
+++ b/src/jsonrpc-virtual-machine.cpp
@@ -15,6 +15,7 @@
 //
 
 #include "jsonrpc-virtual-machine.h"
+#include "os-features.h"
 
 #include <cassert>
 #include <cerrno>
@@ -70,7 +71,6 @@
 #include "machine-config.h"
 #include "machine-merkle-tree.h"
 #include "machine-runtime-config.h"
-#include "os-features.h"
 #include "os.h"
 #include "scope-exit.h"
 #include "semantic-version.h"
diff --git a/src/machine-c-api.cpp b/src/machine-c-api.cpp
index 7aea7ca5d..1bde476c3 100644
--- a/src/machine-c-api.cpp
+++ b/src/machine-c-api.cpp
@@ -44,7 +44,7 @@
 #include "machine-runtime-config.h"
 #include "machine.h"
 #include "os-features.h"
-#include "pma-defines.h"
+#include "pmas-defines.h"
 #include "virtual-machine.h"
 
 static std::string &get_last_err_msg_storage() {
@@ -52,11 +52,11 @@ static std::string &get_last_err_msg_storage() {
     return last_err_msg;
 }
 
-static_assert(PMA_CMIO_RX_BUFFER_START_DEF == CM_PMA_CMIO_RX_BUFFER_START);
-static_assert(PMA_CMIO_RX_BUFFER_LOG2_SIZE_DEF == CM_PMA_CMIO_RX_BUFFER_LOG2_SIZE);
-static_assert(PMA_CMIO_TX_BUFFER_START_DEF == CM_PMA_CMIO_TX_BUFFER_START);
-static_assert(PMA_CMIO_TX_BUFFER_LOG2_SIZE_DEF == CM_PMA_CMIO_TX_BUFFER_LOG2_SIZE);
-static_assert(PMA_RAM_START_DEF == CM_PMA_RAM_START);
+static_assert(AR_CMIO_RX_BUFFER_START_DEF == CM_AR_CMIO_RX_BUFFER_START);
+static_assert(AR_CMIO_RX_BUFFER_LOG2_SIZE_DEF == CM_AR_CMIO_RX_BUFFER_LOG2_SIZE);
+static_assert(AR_CMIO_TX_BUFFER_START_DEF == CM_AR_CMIO_TX_BUFFER_START);
+static_assert(AR_CMIO_TX_BUFFER_LOG2_SIZE_DEF == CM_AR_CMIO_TX_BUFFER_LOG2_SIZE);
+static_assert(AR_RAM_START_DEF == CM_AR_RAM_START);
 
 static_assert(HTIF_YIELD_AUTOMATIC_REASON_PROGRESS_DEF == CM_CMIO_YIELD_AUTOMATIC_REASON_PROGRESS);
 static_assert(HTIF_YIELD_AUTOMATIC_REASON_TX_OUTPUT_DEF == CM_CMIO_YIELD_AUTOMATIC_REASON_TX_OUTPUT);
@@ -1038,7 +1038,7 @@ cm_error cm_receive_cmio_request(const cm_machine *m, uint8_t *cmd, uint16_t *re
             if (data_length > *length) {
                 throw std::invalid_argument{"data buffer length is too small"};
             }
-            cpp_m->read_memory(cartesi::PMA_CMIO_TX_BUFFER_START, data, data_length);
+            cpp_m->read_memory(cartesi::AR_CMIO_TX_BUFFER_START, data, data_length);
         }
     }
     if (cmd != nullptr) {
diff --git a/src/machine-c-api.h b/src/machine-c-api.h
index 36d6ef714..d4ced6bb8 100644
--- a/src/machine-c-api.h
+++ b/src/machine-c-api.h
@@ -51,13 +51,13 @@ typedef enum cm_constant {
 } cm_constant;
 
 /// \brief Physical memory addresses (only the most useful are exposed in the API).
-typedef enum cm_pma_constant {
-    CM_PMA_CMIO_RX_BUFFER_START = 0x60000000,
-    CM_PMA_CMIO_RX_BUFFER_LOG2_SIZE = 21,
-    CM_PMA_CMIO_TX_BUFFER_START = 0x60800000,
-    CM_PMA_CMIO_TX_BUFFER_LOG2_SIZE = 21,
-    CM_PMA_RAM_START = 0x80000000,
-} cm_pma_constant;
+typedef enum cm_pmas_constant {
+    CM_AR_CMIO_RX_BUFFER_START = 0x60000000,
+    CM_AR_CMIO_RX_BUFFER_LOG2_SIZE = 21,
+    CM_AR_CMIO_TX_BUFFER_START = 0x60800000,
+    CM_AR_CMIO_TX_BUFFER_LOG2_SIZE = 21,
+    CM_AR_RAM_START = 0x80000000,
+} cm_pmas_constant;
 
 /// \brief Error codes returned from the C API.
 typedef enum cm_error {
diff --git a/src/machine-config.cpp b/src/machine-config.cpp
index c52a6118d..cfd5f28b5 100644
--- a/src/machine-config.cpp
+++ b/src/machine-config.cpp
@@ -29,7 +29,7 @@
 #include <json.hpp>
 
 #include "json-util.h"
-#include "pma-constants.h"
+#include "pmas-constants.h"
 
 static constexpr uint32_t archive_version = 5;
 
@@ -50,17 +50,17 @@ std::string machine_config::get_config_filename(const std::string &dir) {
 }
 
 static void adjust_image_filenames(machine_config &c, const std::string &dir) {
-    c.dtb.image_filename = machine_config::get_image_filename(dir, PMA_DTB_START, PMA_DTB_LENGTH);
-    c.ram.image_filename = machine_config::get_image_filename(dir, PMA_RAM_START, c.ram.length);
-    c.tlb.image_filename = machine_config::get_image_filename(dir, PMA_SHADOW_TLB_START, PMA_SHADOW_TLB_LENGTH);
+    c.dtb.image_filename = machine_config::get_image_filename(dir, AR_DTB_START, AR_DTB_LENGTH);
+    c.ram.image_filename = machine_config::get_image_filename(dir, AR_RAM_START, c.ram.length);
+    c.tlb.image_filename = machine_config::get_image_filename(dir, AR_SHADOW_TLB_START, AR_SHADOW_TLB_LENGTH);
     for (auto &f : c.flash_drive) {
         f.image_filename = machine_config::get_image_filename(dir, f);
     }
-    c.uarch.ram.image_filename = machine_config::get_image_filename(dir, PMA_UARCH_RAM_START, PMA_UARCH_RAM_LENGTH);
+    c.uarch.ram.image_filename = machine_config::get_image_filename(dir, AR_UARCH_RAM_START, AR_UARCH_RAM_LENGTH);
     c.cmio.rx_buffer.image_filename =
-        machine_config::get_image_filename(dir, PMA_CMIO_RX_BUFFER_START, PMA_CMIO_RX_BUFFER_LENGTH);
+        machine_config::get_image_filename(dir, AR_CMIO_RX_BUFFER_START, AR_CMIO_RX_BUFFER_LENGTH);
     c.cmio.tx_buffer.image_filename =
-        machine_config::get_image_filename(dir, PMA_CMIO_TX_BUFFER_START, PMA_CMIO_TX_BUFFER_LENGTH);
+        machine_config::get_image_filename(dir, AR_CMIO_TX_BUFFER_START, AR_CMIO_TX_BUFFER_LENGTH);
 }
 
 machine_config machine_config::load(const std::string &dir) {
diff --git a/src/machine.cpp b/src/machine.cpp
index dab1920aa..5dd705ed7 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -15,6 +15,7 @@
 //
 
 #include "machine.h"
+#include "os-features.h"
 
 #include <algorithm>
 #include <array>
@@ -54,8 +55,8 @@
 #include "machine-runtime-config.h"
 #include "memory-address-range.h"
 #include "plic-address-range.h"
-#include "pma.h"
 #include "pmas-address-range.h"
+#include "pmas.h"
 #include "record-send-cmio-state-access.h"
 #include "record-step-state-access.h"
 #include "replay-send-cmio-state-access.h"
@@ -104,7 +105,7 @@ static const auto throw_invalid_argument = [](const char *err) { throw std::inva
 /// \param shared If true, changes to memory range reflect in backing file.
 /// \returns New address range with flags already set.
 /// \details If \p image_filename is non-empty, return a memory-mapped range, otherwise use calloc.
-static inline auto make_memory_address_range(const std::string &d, uint64_t start, uint64_t length, pma_flags flags,
+static inline auto make_memory_address_range(const std::string &d, uint64_t start, uint64_t length, pmas_flags flags,
     const std::string &image_filename, bool shared) {
     if (image_filename.empty() && shared) {
         throw std::invalid_argument{"shared address range requires non-empty image filename when initializing " + d};
@@ -125,7 +126,7 @@ void machine::check_address_range(const address_range &ar, register_where where)
     const auto start = ar.get_start();
     const auto length = ar.get_length();
     // Checks if new range is machine addressable space (safe unsigned overflows)
-    if (start > PMA_ADDRESSABLE_MASK || (length > 0 && (length - 1) > (PMA_ADDRESSABLE_MASK - start))) {
+    if (start > AR_ADDRESSABLE_MASK || (length > 0 && (length - 1) > (AR_ADDRESSABLE_MASK - start))) {
         throw std::invalid_argument{
             "address range of "s + ar.get_description() + " must use at most 56 bits to be addressable"s};
     }
@@ -179,14 +180,14 @@ void machine::init_uarch(const uarch_config &c) {
         write_reg(machine_reg_enum(reg::uarch_x0, i), c.processor.x[i]);
     }
     // Register shadow state
-    m_us.shadow_state = &register_address_range(make_shadow_uarch_state_address_range(PMA_SHADOW_UARCH_STATE_START,
-                                                    PMA_SHADOW_UARCH_STATE_LENGTH, throw_invalid_argument),
+    m_us.shadow_state = &register_address_range(make_shadow_uarch_state_address_range(AR_SHADOW_UARCH_STATE_START,
+                                                    AR_SHADOW_UARCH_STATE_LENGTH, throw_invalid_argument),
         register_where{.merkle = true, .interpret = false});
     // Register RAM
-    if (uarch_pristine_ram_len > PMA_UARCH_RAM_LENGTH) {
+    if (uarch_pristine_ram_len > AR_UARCH_RAM_LENGTH) {
         throw std::runtime_error("embedded uarch RAM image does not fit in uarch memory");
     }
-    static constexpr pma_flags uram_flags{
+    static constexpr pmas_flags uram_flags{
         .M = true,
         .IO = false,
         .E = false,
@@ -200,12 +201,12 @@ void machine::init_uarch(const uarch_config &c) {
     constexpr auto ram_description = "uarch RAM";
     if (c.ram.image_filename.empty()) {
         m_us.ram = &register_address_range(
-            make_callocd_memory_address_range(ram_description, PMA_UARCH_RAM_START, UARCH_RAM_LENGTH, uram_flags),
+            make_callocd_memory_address_range(ram_description, AR_UARCH_RAM_START, UARCH_RAM_LENGTH, uram_flags),
             register_where{.merkle = true, .interpret = false});
         memcpy(m_us.ram->get_host_memory(), uarch_pristine_ram, uarch_pristine_ram_len);
     } else {
         m_us.ram =
-            &register_address_range(make_memory_address_range(ram_description, PMA_UARCH_RAM_START, UARCH_RAM_LENGTH,
+            &register_address_range(make_memory_address_range(ram_description, AR_UARCH_RAM_START, UARCH_RAM_LENGTH,
                                         uram_flags, c.ram.image_filename, false /* not shared */),
                 register_where{.merkle = true, .interpret = false});
     }
@@ -283,7 +284,7 @@ void machine::init_processor(processor_config &p, const machine_runtime_config &
 
 void machine::init_ram_ar(const ram_config &ram) {
     // Flags for RAM
-    static constexpr pma_flags ram_flags{
+    static constexpr pmas_flags ram_flags{
         .M = true,
         .IO = false,
         .E = false,
@@ -298,13 +299,13 @@ void machine::init_ram_ar(const ram_config &ram) {
         throw std::invalid_argument("RAM length cannot be zero");
     }
     register_address_range(
-        make_callocd_memory_address_range("RAM"s, PMA_RAM_START, ram.length, ram_flags, ram.image_filename),
+        make_callocd_memory_address_range("RAM"s, AR_RAM_START, ram.length, ram_flags, ram.image_filename),
         register_where{.merkle = true, .interpret = true});
 }
 
 void machine::init_flash_drive_ars(flash_drive_configs &flash_drive) {
     // Flags for flash drives
-    static const pma_flags flash_flags{
+    static const pmas_flags flash_flags{
         .M = true,
         .IO = false,
         .E = false,
@@ -321,7 +322,7 @@ void machine::init_flash_drive_ars(flash_drive_configs &flash_drive) {
         const std::string flash_description = "flash drive "s + std::to_string(i);
         // Auto detect flash drive start address
         if (f.start == UINT64_C(-1)) {
-            f.start = PMA_DRIVE_START + PMA_DRIVE_OFFSET * i;
+            f.start = AR_DRIVE_START + AR_DRIVE_OFFSET * i;
         }
         // Auto detect flash drive image length
         if (f.length == UINT64_C(-1)) {
@@ -360,14 +361,14 @@ void machine::init_virtio_ars(const virtio_configs &cs, uint64_t iunrep) {
         const auto where = register_where{.merkle = false, .interpret = true};
         const auto visitor = overloads{
             [this, virtio_idx, where](const virtio_console_config &) {
-                const auto start = PMA_FIRST_VIRTIO_START + (virtio_idx * PMA_VIRTIO_LENGTH);
-                register_address_range(make_virtio_console_address_range(start, PMA_VIRTIO_LENGTH, virtio_idx), where);
+                const auto start = AR_FIRST_VIRTIO_START + (virtio_idx * AR_VIRTIO_LENGTH);
+                register_address_range(make_virtio_console_address_range(start, AR_VIRTIO_LENGTH, virtio_idx), where);
             },
             [this, virtio_idx, where](const virtio_p9fs_config &c) {
 #ifdef HAVE_POSIX_FS
-                const auto start = PMA_FIRST_VIRTIO_START + (virtio_idx * PMA_VIRTIO_LENGTH);
+                const auto start = AR_FIRST_VIRTIO_START + (virtio_idx * AR_VIRTIO_LENGTH);
                 register_address_range(
-                    make_virtio_p9fs_address_range(start, PMA_VIRTIO_LENGTH, virtio_idx, c.tag, c.host_directory),
+                    make_virtio_p9fs_address_range(start, AR_VIRTIO_LENGTH, virtio_idx, c.tag, c.host_directory),
                     where);
 #else
                 (void) c;
@@ -379,9 +380,9 @@ void machine::init_virtio_ars(const virtio_configs &cs, uint64_t iunrep) {
             },
             [this, virtio_idx, where](const virtio_net_tuntap_config &c) {
 #ifdef HAVE_TUNTAP
-                const auto start = PMA_FIRST_VIRTIO_START + (virtio_idx * PMA_VIRTIO_LENGTH);
+                const auto start = AR_FIRST_VIRTIO_START + (virtio_idx * AR_VIRTIO_LENGTH);
                 register_address_range(
-                    make_virtio_net_tuntap_address_range(start, PMA_VIRTIO_LENGTH, virtio_idx, c.iface), where);
+                    make_virtio_net_tuntap_address_range(start, AR_VIRTIO_LENGTH, virtio_idx, c.iface), where);
 #else
                 (void) c;
                 (void) this;
@@ -392,8 +393,8 @@ void machine::init_virtio_ars(const virtio_configs &cs, uint64_t iunrep) {
             },
             [this, virtio_idx, where](const virtio_net_user_config &c) {
 #ifdef HAVE_SLIRP
-                const auto start = PMA_FIRST_VIRTIO_START + (virtio_idx * PMA_VIRTIO_LENGTH);
-                register_address_range(make_virtio_net_user_address_range(start, PMA_VIRTIO_LENGTH, virtio_idx, c),
+                const auto start = AR_FIRST_VIRTIO_START + (virtio_idx * AR_VIRTIO_LENGTH);
+                register_address_range(make_virtio_net_user_address_range(start, AR_VIRTIO_LENGTH, virtio_idx, c),
                     where);
 #else
                 (void) c;
@@ -411,7 +412,7 @@ void machine::init_virtio_ars(const virtio_configs &cs, uint64_t iunrep) {
 
 void machine::init_htif_ar(const htif_config &h) {
     // Register HTIF device
-    register_address_range(make_htif_address_range(PMA_HTIF_START, PMA_HTIF_LENGTH, throw_invalid_argument),
+    register_address_range(make_htif_address_range(AR_HTIF_START, AR_HTIF_LENGTH, throw_invalid_argument),
         register_where{.merkle = false, .interpret = true});
     // Copy HTIF state to from config to machine
     write_reg(reg::htif_tohost, h.tohost);
@@ -428,7 +429,7 @@ void machine::init_htif_ar(const htif_config &h) {
 }
 
 void machine::init_cmio_ars(const cmio_config &c) {
-    static const pma_flags tx_flags{
+    static const pmas_flags tx_flags{
         .M = true,
         .IO = false,
         .E = false,
@@ -439,7 +440,7 @@ void machine::init_cmio_ars(const cmio_config &c) {
         .IW = true,
         .DID = PMA_ISTART_DID::cmio_tx_buffer,
     };
-    static const pma_flags rx_flags{
+    static const pmas_flags rx_flags{
         .M = true,
         .IO = false,
         .E = false,
@@ -450,11 +451,11 @@ void machine::init_cmio_ars(const cmio_config &c) {
         .IW = true,
         .DID = PMA_ISTART_DID::cmio_rx_buffer,
     };
-    register_address_range(make_memory_address_range("CMIO tx buffer memory range"s, PMA_CMIO_TX_BUFFER_START,
-                               PMA_CMIO_TX_BUFFER_LENGTH, tx_flags, c.tx_buffer.image_filename, c.tx_buffer.shared),
+    register_address_range(make_memory_address_range("CMIO tx buffer memory range"s, AR_CMIO_TX_BUFFER_START,
+                               AR_CMIO_TX_BUFFER_LENGTH, tx_flags, c.tx_buffer.image_filename, c.tx_buffer.shared),
         register_where{.merkle = true, .interpret = true});
-    register_address_range(make_memory_address_range("CMIO rx buffer memory range"s, PMA_CMIO_RX_BUFFER_START,
-                               PMA_CMIO_RX_BUFFER_LENGTH, rx_flags, c.rx_buffer.image_filename, c.rx_buffer.shared),
+    register_address_range(make_memory_address_range("CMIO rx buffer memory range"s, AR_CMIO_RX_BUFFER_START,
+                               AR_CMIO_RX_BUFFER_LENGTH, rx_flags, c.rx_buffer.image_filename, c.rx_buffer.shared),
         register_where{.merkle = true, .interpret = true});
 }
 
@@ -479,7 +480,7 @@ void machine::init_ars_descriptions() {
 
 void machine::init_clint_ar(const clint_config &c) {
     // Register CLINT device
-    register_address_range(make_clint_address_range(PMA_CLINT_START, PMA_CLINT_LENGTH, throw_invalid_argument),
+    register_address_range(make_clint_address_range(AR_CLINT_START, AR_CLINT_LENGTH, throw_invalid_argument),
         register_where{.merkle = false, .interpret = true});
     // Copy CLINT state to from config to machine
     write_reg(reg::clint_mtimecmp, c.mtimecmp);
@@ -487,7 +488,7 @@ void machine::init_clint_ar(const clint_config &c) {
 
 void machine::init_plic_ar(const plic_config &p) {
     // Register PLIC device
-    register_address_range(make_plic_address_range(PMA_PLIC_START, PMA_PLIC_LENGTH, throw_invalid_argument),
+    register_address_range(make_plic_address_range(AR_PLIC_START, AR_PLIC_LENGTH, throw_invalid_argument),
         register_where{.merkle = false, .interpret = true});
     // Copy PLIC state from config to machine
     write_reg(reg::plic_girqpend, p.girqpend);
@@ -506,11 +507,11 @@ void machine::init_sentinel_ars() {
 
 void machine::init_pmas_contents(memory_address_range &pmas) const {
     static_assert(sizeof(pmas_state) == PMA_MAX * 2 * sizeof(uint64_t), "inconsistent PMAs state length");
-    static_assert(PMA_PMAS_LENGTH >= sizeof(pmas_state), "PMAs address range too short");
+    static_assert(AR_PMAS_LENGTH >= sizeof(pmas_state), "PMAs address range too short");
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
     auto &dest = *reinterpret_cast<pmas_state *>(pmas.get_host_memory());
     std::ranges::transform(m_s.pmas, dest.begin(),
-        [this](auto i) { return pma_entry{.istart = m_ars[i]->get_istart(), .ilength = m_ars[i]->get_ilength()}; });
+        [this](auto i) { return pmas_entry{.istart = m_ars[i]->get_istart(), .ilength = m_ars[i]->get_ilength()}; });
 }
 
 void machine::init_tlb_contents(const std::string &image_filename) {
@@ -538,7 +539,7 @@ void machine::init_tlb_contents(const std::string &image_filename) {
 address_range &machine::init_dtb_ar(const dtb_config &c) {
     // When we pass a RNG seed in a FDT stored in DTB, Linux will wipe out its contents as a security measure,
     // therefore we need to make DTB writable, otherwise boot will hang.
-    static constexpr pma_flags dtb_flags{
+    static constexpr pmas_flags dtb_flags{
         .M = true,
         .IO = false,
         .E = false,
@@ -549,14 +550,14 @@ address_range &machine::init_dtb_ar(const dtb_config &c) {
         .IW = true,
         .DID = PMA_ISTART_DID::memory,
     };
-    return register_address_range(make_memory_address_range("DTB"s, PMA_DTB_START, PMA_DTB_LENGTH, dtb_flags,
+    return register_address_range(make_memory_address_range("DTB"s, AR_DTB_START, AR_DTB_LENGTH, dtb_flags,
                                       c.image_filename, false /* not shared */),
         register_where{.merkle = true, .interpret = true});
 }
 
 void machine::init_dtb_contents(const machine_config &c, address_range &dtb) {
     if (c.dtb.image_filename.empty()) {
-        dtb_init(c, dtb.get_host_memory(), PMA_DTB_LENGTH);
+        dtb_init(c, dtb.get_host_memory(), AR_DTB_LENGTH);
     }
 }
 
@@ -576,13 +577,13 @@ machine::machine(machine_config c, machine_runtime_config r) : m_c{std::move(c)}
     init_plic_ar(m_c.plic);
     // Will populate when initialization of PMAs is done
     register_address_range(
-        make_shadow_tlb_address_range(PMA_SHADOW_TLB_START, PMA_SHADOW_TLB_LENGTH, throw_invalid_argument),
+        make_shadow_tlb_address_range(AR_SHADOW_TLB_START, AR_SHADOW_TLB_LENGTH, throw_invalid_argument),
         register_where{.merkle = true, .interpret = false});
     register_address_range(
-        make_shadow_state_address_range(PMA_SHADOW_STATE_START, PMA_SHADOW_STATE_LENGTH, throw_invalid_argument),
+        make_shadow_state_address_range(AR_SHADOW_STATE_START, AR_SHADOW_STATE_LENGTH, throw_invalid_argument),
         register_where{.merkle = true, .interpret = false});
     // Will populate when initialization of PMAs is done
-    auto &shpmas = register_address_range(make_pmas_address_range(PMA_PMAS_START, PMA_PMAS_LENGTH),
+    auto &shpmas = register_address_range(make_pmas_address_range(AR_PMAS_START, AR_PMAS_LENGTH),
         register_where{.merkle = true, .interpret = true});
     init_virtio_ars(m_c.virtio, m_c.processor.iunrep);
     init_sentinel_ars();
@@ -781,19 +782,19 @@ static void store_device_address_range(const machine &m, const address_range &ar
     if (!ar.is_device()) {
         throw std::runtime_error{"attempt to save non-device address range "s + ar.get_description()};
     }
-    auto scratch = make_unique_calloc<unsigned char>(PMA_PAGE_SIZE); // will throw if it fails
+    auto scratch = make_unique_calloc<unsigned char>(AR_PAGE_SIZE); // will throw if it fails
     auto name = machine_config::get_image_filename(dir, ar.get_start(), ar.get_length());
     auto fp = make_unique_fopen(name.c_str(), "wb"); // will throw if it fails
-    for (uint64_t offset = 0; offset < ar.get_length(); offset += PMA_PAGE_SIZE) {
+    for (uint64_t offset = 0; offset < ar.get_length(); offset += AR_PAGE_SIZE) {
         const unsigned char *page_data = nullptr;
-        if (!ar.peek(m, offset, PMA_PAGE_SIZE, &page_data, scratch.get())) {
+        if (!ar.peek(m, offset, AR_PAGE_SIZE, &page_data, scratch.get())) {
             throw std::runtime_error{"peek failed"};
         }
         if (page_data == nullptr) {
-            memset(scratch.get(), 0, PMA_PAGE_SIZE);
+            memset(scratch.get(), 0, AR_PAGE_SIZE);
             page_data = scratch.get();
         }
-        if (fwrite(page_data, 1, PMA_PAGE_SIZE, fp.get()) != PMA_PAGE_SIZE) {
+        if (fwrite(page_data, 1, AR_PAGE_SIZE, fp.get()) != AR_PAGE_SIZE) {
             throw std::system_error{errno, std::generic_category(), "error writing to '" + name + "'"};
         }
     }
@@ -874,8 +875,8 @@ void machine::check_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, uin
         if ((paddr_page & PAGE_OFFSET_MASK) != 0) {
             throw std::invalid_argument{prefix + "vp_offset is not aligned"s};
         }
-        const auto pma_end = ar.get_start() + (ar.get_length() - PMA_PAGE_SIZE);
-        if (paddr_page < ar.get_start() || paddr_page > pma_end) {
+        const auto pmas_end = ar.get_start() + (ar.get_length() - AR_PAGE_SIZE);
+        if (paddr_page < ar.get_start() || paddr_page > pmas_end) {
             throw std::invalid_argument{prefix + "vp_offset is inconsistent with pma_index"s};
         }
     } else if (pma_index != TLB_INVALID_PMA_INDEX || vp_offset != 0) {
@@ -926,16 +927,16 @@ void machine::store_address_ranges(const machine_config &c, const std::string &d
     if (read_reg(reg::iunrep) != 0) {
         throw std::runtime_error{"cannot store PMAs of unreproducible machines"};
     }
-    store_memory_address_range(find_address_range<uint64_t>(PMA_DTB_START), dir);
-    store_memory_address_range(find_address_range<uint64_t>(PMA_RAM_START), dir);
-    store_device_address_range(*this, find_address_range<uint64_t>(PMA_SHADOW_TLB_START), dir);
+    store_memory_address_range(find_address_range<uint64_t>(AR_DTB_START), dir);
+    store_memory_address_range(find_address_range<uint64_t>(AR_RAM_START), dir);
+    store_device_address_range(*this, find_address_range<uint64_t>(AR_SHADOW_TLB_START), dir);
     // Could iterate over PMAs checking for those with a drive DID but this is easier
     for (const auto &f : c.flash_drive) {
         store_memory_address_range(find_address_range<uint64_t>(f.start), dir);
     }
-    store_memory_address_range(find_address_range<uint64_t>(PMA_CMIO_RX_BUFFER_START), dir);
-    store_memory_address_range(find_address_range<uint64_t>(PMA_CMIO_TX_BUFFER_START), dir);
-    store_memory_address_range(find_address_range<uint64_t>(PMA_UARCH_RAM_START), dir);
+    store_memory_address_range(find_address_range<uint64_t>(AR_CMIO_RX_BUFFER_START), dir);
+    store_memory_address_range(find_address_range<uint64_t>(AR_CMIO_TX_BUFFER_START), dir);
+    store_memory_address_range(find_address_range<uint64_t>(AR_UARCH_RAM_START), dir);
 }
 
 static void store_hash(const machine::hash_type &h, const std::string &dir) {
@@ -1811,7 +1812,7 @@ void machine::mark_write_tlb_dirty_pages() const {
                 throw std::runtime_error{"could not mark dirty page for a TLB entry: TLB is corrupt"};
             }
             auto paddr_page = get_paddr(haddr_page, cold_slot.pma_index);
-            if (!ar.contains_absolute(paddr_page, PMA_PAGE_SIZE)) {
+            if (!ar.contains_absolute(paddr_page, AR_PAGE_SIZE)) {
                 throw std::runtime_error{"could not mark dirty page for a TLB entry: TLB is corrupt"};
             }
             ar.mark_dirty_page(paddr_page - ar.get_start());
@@ -1820,10 +1821,10 @@ void machine::mark_write_tlb_dirty_pages() const {
 }
 
 bool machine::verify_dirty_page_maps() const {
-    static_assert(PMA_PAGE_SIZE == machine_merkle_tree::get_page_size(),
+    static_assert(AR_PAGE_SIZE == machine_merkle_tree::get_page_size(),
         "PMA and machine_merkle_tree page sizes must match");
     machine_merkle_tree::hasher_type h;
-    auto scratch = make_unique_calloc<unsigned char>(PMA_PAGE_SIZE, std::nothrow_t{});
+    auto scratch = make_unique_calloc<unsigned char>(AR_PAGE_SIZE, std::nothrow_t{});
     if (!scratch) {
         return false;
     }
@@ -1832,11 +1833,11 @@ bool machine::verify_dirty_page_maps() const {
     mark_write_tlb_dirty_pages();
     // Now go over all memory PMAs verifying that all dirty pages are marked
     for (const auto &ar : m_ars) {
-        for (uint64_t offset = 0; offset < ar->get_length(); offset += PMA_PAGE_SIZE) {
+        for (uint64_t offset = 0; offset < ar->get_length(); offset += AR_PAGE_SIZE) {
             const uint64_t page_address = ar->get_start() + offset;
             if (ar->is_memory()) {
                 const unsigned char *page_data = nullptr;
-                ar->peek(*this, offset, PMA_PAGE_SIZE, &page_data, scratch.get());
+                ar->peek(*this, offset, AR_PAGE_SIZE, &page_data, scratch.get());
                 hash_type stored;
                 hash_type real;
                 m_t.get_page_node_hash(page_address, stored);
@@ -1872,7 +1873,7 @@ static uint64_t get_task_concurrency(uint64_t value) {
 
 bool machine::update_merkle_tree() const {
     machine_merkle_tree::hasher_type gh;
-    static_assert(PMA_PAGE_SIZE == machine_merkle_tree::get_page_size(),
+    static_assert(AR_PAGE_SIZE == machine_merkle_tree::get_page_size(),
         "PMA and machine_merkle_tree page sizes must match");
     // Go over the write TLB and mark as dirty all pages currently there
     mark_write_tlb_dirty_pages();
@@ -1880,19 +1881,19 @@ bool machine::update_merkle_tree() const {
     m_t.begin_update();
     for (auto &ar : m_merkle_ars | std::views::transform([this](auto i) -> address_range & { return *m_ars[i]; })) {
         // Each PMA has a number of pages
-        auto pages_in_range = (ar.get_length() + PMA_PAGE_SIZE - 1) / PMA_PAGE_SIZE;
+        auto pages_in_range = (ar.get_length() + AR_PAGE_SIZE - 1) / AR_PAGE_SIZE;
         // For each PMA, we launch as many threads (n) as defined on concurrency
         // runtime config or as the hardware supports.
         const uint64_t n = get_task_concurrency(m_r.concurrency.update_merkle_tree);
         const bool succeeded = os_parallel_for(n, [&](int j, const parallel_for_mutex &mutex) -> bool {
-            auto scratch = make_unique_calloc<unsigned char>(PMA_PAGE_SIZE, std::nothrow_t{});
+            auto scratch = make_unique_calloc<unsigned char>(AR_PAGE_SIZE, std::nothrow_t{});
             if (!scratch) {
                 return false;
             }
             machine_merkle_tree::hasher_type h;
             // Thread j is responsible for page i if i % n == j.
             for (uint64_t i = j; i < pages_in_range; i += n) {
-                const uint64_t page_start_in_range = i * PMA_PAGE_SIZE;
+                const uint64_t page_start_in_range = i * AR_PAGE_SIZE;
                 const uint64_t page_address = ar.get_start() + page_start_in_range;
                 const unsigned char *page_data = nullptr;
                 // Skip any clean pages
@@ -1901,11 +1902,11 @@ bool machine::update_merkle_tree() const {
                 }
                 // If the peek failed, or if it returned a page for update but
                 // we failed updating it, the entire process failed
-                if (!ar.peek(*this, page_start_in_range, PMA_PAGE_SIZE, &page_data, scratch.get())) {
+                if (!ar.peek(*this, page_start_in_range, AR_PAGE_SIZE, &page_data, scratch.get())) {
                     return false;
                 }
                 if (page_data != nullptr) {
-                    if (is_pristine(page_data, PMA_PAGE_SIZE)) {
+                    if (is_pristine(page_data, AR_PAGE_SIZE)) {
                         // The update_page_node_hash function in the machine_merkle_tree is not thread
                         // safe, so we protect it with a mutex
                         const parallel_for_mutex_guard lock(mutex);
@@ -1942,20 +1943,20 @@ bool machine::update_merkle_tree() const {
 }
 
 bool machine::update_merkle_tree_page(uint64_t address) {
-    static_assert(PMA_PAGE_SIZE == machine_merkle_tree::get_page_size(),
+    static_assert(AR_PAGE_SIZE == machine_merkle_tree::get_page_size(),
         "PMA and machine_merkle_tree page sizes must match");
     // Align address to beginning of page
-    address &= ~(PMA_PAGE_SIZE - 1);
+    address &= ~(AR_PAGE_SIZE - 1);
     auto &ar = find_address_range<uint8_t>(address);
     const uint64_t page_start_in_range = address - ar.get_start();
     machine_merkle_tree::hasher_type h;
-    auto scratch = make_unique_calloc<unsigned char>(PMA_PAGE_SIZE, std::nothrow_t{});
+    auto scratch = make_unique_calloc<unsigned char>(AR_PAGE_SIZE, std::nothrow_t{});
     if (!scratch) {
         return false;
     }
     m_t.begin_update();
     const unsigned char *page_data = nullptr;
-    if (!ar.peek(*this, page_start_in_range, PMA_PAGE_SIZE, &page_data, scratch.get())) {
+    if (!ar.peek(*this, page_start_in_range, AR_PAGE_SIZE, &page_data, scratch.get())) {
         m_t.end_update(h);
         return false;
     }
@@ -2003,22 +2004,22 @@ machine::hash_type machine::get_merkle_tree_node_hash(uint64_t address, int log2
 }
 
 const char *machine::get_what_name(uint64_t paddr) {
-    if (paddr >= PMA_UARCH_RAM_START && paddr - PMA_UARCH_RAM_START < PMA_UARCH_RAM_LENGTH) {
+    if (paddr >= AR_UARCH_RAM_START && paddr - AR_UARCH_RAM_START < AR_UARCH_RAM_LENGTH) {
         return "uarch.ram";
     }
     // If in shadow, return refined name
-    if (paddr >= PMA_SHADOW_TLB_START && paddr - PMA_SHADOW_TLB_START < PMA_SHADOW_TLB_LENGTH) {
+    if (paddr >= AR_SHADOW_TLB_START && paddr - AR_SHADOW_TLB_START < AR_SHADOW_TLB_LENGTH) {
         [[maybe_unused]] TLB_set_index set_index{};
         [[maybe_unused]] uint64_t slot_index{};
         return shadow_tlb_get_what_name(shadow_tlb_get_what(paddr, set_index, slot_index));
     }
-    if (paddr >= PMA_SHADOW_STATE_START && paddr - PMA_SHADOW_STATE_START < PMA_SHADOW_STATE_LENGTH) {
+    if (paddr >= AR_SHADOW_STATE_START && paddr - AR_SHADOW_STATE_START < AR_SHADOW_STATE_LENGTH) {
         return shadow_state_get_what_name(shadow_state_get_what(paddr));
     }
-    if (paddr >= PMA_PMAS_START && paddr - PMA_PMAS_START < PMA_PMAS_LENGTH) {
-        return pma_get_what_name(pma_get_what(paddr));
+    if (paddr >= AR_PMAS_START && paddr - AR_PMAS_START < AR_PMAS_LENGTH) {
+        return pmas_get_what_name(pmas_get_what(paddr));
     }
-    if (paddr >= PMA_SHADOW_UARCH_STATE_START && paddr - PMA_SHADOW_UARCH_STATE_START < PMA_SHADOW_UARCH_STATE_LENGTH) {
+    if (paddr >= AR_SHADOW_UARCH_STATE_START && paddr - AR_SHADOW_UARCH_STATE_START < AR_SHADOW_UARCH_STATE_LENGTH) {
         return shadow_uarch_state_get_what_name(shadow_uarch_state_get_what(paddr));
     }
     return "memory";
@@ -2037,7 +2038,7 @@ bool machine::verify_merkle_tree() const {
 
 machine_merkle_tree::proof_type machine::get_proof(uint64_t address, int log2_size,
     skip_merkle_tree_update_t /*unused*/) const {
-    static_assert(PMA_PAGE_SIZE == machine_merkle_tree::get_page_size(),
+    static_assert(AR_PAGE_SIZE == machine_merkle_tree::get_page_size(),
         "PMA and machine_merkle_tree page sizes must match");
     // Check for valid target node size
     if (log2_size > machine_merkle_tree::get_log2_root_size() ||
@@ -2059,15 +2060,15 @@ machine_merkle_tree::proof_type machine::get_proof(uint64_t address, int log2_si
     if (log2_size < machine_merkle_tree::get_log2_page_size()) {
         const uint64_t length = UINT64_C(1) << log2_size;
         const auto &ar = find_address_range(address, length);
-        auto scratch = make_unique_calloc<unsigned char>(PMA_PAGE_SIZE);
+        auto scratch = make_unique_calloc<unsigned char>(AR_PAGE_SIZE);
         const unsigned char *page_data = nullptr;
         // If the PMA range is empty, we know the desired range is
         // entirely outside of any non-pristine PMA.
         // Therefore, the entire page where it lies is also pristine
         // Otherwise, the entire desired range is inside it.
         if (ar.get_length() != 0) {
-            const uint64_t page_start_in_range = (address - ar.get_start()) & (~(PMA_PAGE_SIZE - 1));
-            if (!ar.peek(*this, page_start_in_range, PMA_PAGE_SIZE, &page_data, scratch.get())) {
+            const uint64_t page_start_in_range = (address - ar.get_start()) & (~(AR_PAGE_SIZE - 1));
+            if (!ar.peek(*this, page_start_in_range, AR_PAGE_SIZE, &page_data, scratch.get())) {
                 throw std::runtime_error{"PMA peek failed"};
             }
         }
@@ -2113,65 +2114,54 @@ void machine::read_memory(uint64_t paddr, unsigned char *data, uint64_t length)
     if (data == nullptr) {
         throw std::invalid_argument{"invalid data buffer"};
     }
-    //??D this loop can be much improved and simplified... I don't remember why I am going page
-    //??D by page when inside an occupied address range... Will fix.
-    // Compute the distance between the initial paddr and the first page boundary
-    const uint64_t align_paddr = (paddr & PAGE_OFFSET_MASK) != 0 ? (paddr | PAGE_OFFSET_MASK) + 1 : paddr;
-    uint64_t align_length = align_paddr - paddr;
-    const uint64_t page_size = PMA_PAGE_SIZE;
-    align_length = (align_length == 0) ? page_size : align_length;
-    // First peek goes at most to the next page boundary, or up to length
-    uint64_t peek_length = std::min(align_length, length);
-    // The outer loop finds the address range for all peeks performed by the inner loop
-    // The inner loop peeks at most min(page_size, length) from the range per iteration
-    // All peeks but the absolute first peek start at a page boundary.
-    // That first peek reads at most up to the next page boundary.
-    // So the inner loop iterations never cross page boundaries.
-    for (;;) {
-        const auto &ar = find_address_range(paddr, peek_length);
-        const auto pma_start = ar.get_start();
-        const auto occupied = ar.get_length() != 0;
-        const auto pma_length = ar.get_length();
-        // If we are in an unoccupied range, the inner loop will break after a single iteration.
-        // But it is safe to return pristine data for that one iteration, without even peeking.
-        // This is because the inner iteration never reads past a page boundary, and the next
-        // occupied range starts at the earliest on the next page boundary after paddr.
-        for (;;) {
+    uint64_t gap_start = 0;
+    auto view = m_merkle_ars | // Indices of Mekrle tree address ranges
+        std::views::transform(
+            [this](auto i) -> address_range & { return *m_ars[i]; }) |        // Now address ranges themselves
+        std::views::drop_while([paddr, &gap_start](const address_range &ar) { // Only those that end after paddr
+            const auto ar_end = ar.get_start() + ar.get_length();
+            if (paddr >= ar_end) {
+                gap_start = ar_end;
+                return true;
+            }
+            return false;
+        });
+    for (auto &ar : view) {
+        const auto ar_start = ar.get_start();
+        // Write as much as possible from pristine gap between last address range and current address range
+        if (paddr >= gap_start && paddr < ar_start) {
+            const auto from_gap = std::min(ar_start - paddr, length);
+            memset(data, 0, from_gap);
+            length -= from_gap;
+            paddr += from_gap;
+            data += from_gap;
+        }
+        gap_start = ar_start + ar.get_length();
+        // Write as much as possible from current address range
+        if (paddr >= ar_start && paddr < gap_start) {
+            const auto from_ar = std::min(gap_start - paddr, length);
             const unsigned char *peek_data = nullptr;
-            // If we found an occupied range, peek, otherwise leave peek_data as nullptr (i.e. pristine)
-            if (occupied && !ar.peek(*this, paddr - pma_start, peek_length, &peek_data, data)) {
+            if (!ar.peek(*this, paddr - ar_start, from_ar, &peek_data, data)) {
                 throw std::runtime_error{"peek failed"};
             }
-            // If the chunk is pristine, copy zero data to buffer
             if (peek_data == nullptr) {
-                memset(data, 0, peek_length);
-                // If peek returned pointer to internal buffer, copy to data buffer
+                // If the chunk is pristine, copy zero data to buffer
+                memset(data, 0, from_ar);
             } else if (peek_data != data) {
-                memcpy(data, peek_data, peek_length);
+                // If peek returned pointer to internal buffer, copy to data buffer
+                memcpy(data, peek_data, from_ar);
             }
-            // Otherwise, peek copied data straight into the data buffer
-            // If we read everything we wanted to read, we are done
-            length -= peek_length;
+            // Otherwise, peek already copied to data buffer
+            length -= from_ar;
             if (length == 0) {
                 return;
             }
-            paddr += peek_length;
-            data += peek_length;
-            peek_length = std::min(page_size, length);
-            // If we are outside any valid range, break to check if next read hits a valid range
-            if (!occupied) {
-                break;
-            }
-            // If the next read does not fit in current range, break to get the next one
-            // There can be no overflow in the condition.
-            // Since the range is occupied, (paddr-pma_start) >= 0.
-            // Moreover, pma_length >= page_size.
-            // Since, peek_length <= page_size, we get (pma_length-peek_length) >= 0.
-            if (paddr - pma_start >= pma_length - peek_length) {
-                break;
-            }
+            paddr += from_ar;
+            data += from_ar;
         }
     }
+    // Finish up with pristine padding after last address range
+    memset(data, 0, length);
 }
 
 void machine::write_memory(uint64_t paddr, const unsigned char *data, uint64_t length) {
@@ -2191,7 +2181,7 @@ void machine::write_memory(uint64_t paddr, const unsigned char *data, uint64_t l
     if (is_protected(ar.get_driver_id())) {
         throw std::invalid_argument{"attempt to write to protected memory range"};
     }
-    foreach_aligned_chunk(paddr, length, PMA_PAGE_SIZE, [&ar, paddr, data](auto chunk_start, auto chunk_length) {
+    foreach_aligned_chunk(paddr, length, AR_PAGE_SIZE, [&ar, paddr, data](auto chunk_start, auto chunk_length) {
         const auto *src = data + (chunk_start - paddr);
         const auto offset = chunk_start - ar.get_start();
         auto *dest = ar.get_host_memory() + offset;
@@ -2218,7 +2208,7 @@ void machine::fill_memory(uint64_t paddr, uint8_t val, uint64_t length) {
         throw std::invalid_argument{"attempt fill to protected memory range"};
     }
     // The case of filling a range with zeros is special and optimized for uarch reset
-    foreach_aligned_chunk(paddr, length, PMA_PAGE_SIZE, [&ar, val](auto chunk_start, auto chunk_length) {
+    foreach_aligned_chunk(paddr, length, AR_PAGE_SIZE, [&ar, val](auto chunk_start, auto chunk_length) {
         const auto offset = chunk_start - ar.get_start();
         const auto dest = ar.get_host_memory() + offset;
         if (val != 0 || !is_pristine(dest, chunk_length)) {
@@ -2237,17 +2227,17 @@ void machine::read_virtual_memory(uint64_t vaddr_start, unsigned char *data, uin
         throw std::invalid_argument{"invalid data buffer"};
     }
     const uint64_t vaddr_limit = vaddr_start + length;
-    const uint64_t vaddr_page_start = vaddr_start & ~(PMA_PAGE_SIZE - 1);                       // align page backward
-    const uint64_t vaddr_page_limit = (vaddr_limit + PMA_PAGE_SIZE - 1) & ~(PMA_PAGE_SIZE - 1); // align page forward
+    const uint64_t vaddr_page_start = vaddr_start & ~(AR_PAGE_SIZE - 1);                      // align page backward
+    const uint64_t vaddr_page_limit = (vaddr_limit + AR_PAGE_SIZE - 1) & ~(AR_PAGE_SIZE - 1); // align page forward
     // copy page by page, because we need to perform address translation again for each page
-    for (uint64_t vaddr_page = vaddr_page_start; vaddr_page < vaddr_page_limit; vaddr_page += PMA_PAGE_SIZE) {
+    for (uint64_t vaddr_page = vaddr_page_start; vaddr_page < vaddr_page_limit; vaddr_page += AR_PAGE_SIZE) {
         uint64_t paddr_page = 0;
         if (!cartesi::translate_virtual_address<state_access, false>(a, &paddr_page, vaddr_page, PTE_XWR_R_SHIFT)) {
             throw std::domain_error{"page fault"};
         }
         uint64_t paddr = paddr_page;
         uint64_t vaddr = vaddr_page;
-        uint64_t chunklen = std::min<uint64_t>(PMA_PAGE_SIZE, vaddr_limit - vaddr);
+        uint64_t chunklen = std::min<uint64_t>(AR_PAGE_SIZE, vaddr_limit - vaddr);
         if (vaddr_page < vaddr_start) {
             const uint64_t off = vaddr_start - vaddr_page;
             paddr += off;
@@ -2268,10 +2258,10 @@ void machine::write_virtual_memory(uint64_t vaddr_start, const unsigned char *da
         throw std::invalid_argument{"invalid data buffer"};
     }
     const uint64_t vaddr_limit = vaddr_start + length;
-    const uint64_t vaddr_page_start = vaddr_start & ~(PMA_PAGE_SIZE - 1);                       // align page backward
-    const uint64_t vaddr_page_limit = (vaddr_limit + PMA_PAGE_SIZE - 1) & ~(PMA_PAGE_SIZE - 1); // align page forward
+    const uint64_t vaddr_page_start = vaddr_start & ~(AR_PAGE_SIZE - 1);                      // align page backward
+    const uint64_t vaddr_page_limit = (vaddr_limit + AR_PAGE_SIZE - 1) & ~(AR_PAGE_SIZE - 1); // align page forward
     // copy page by page, because we need to perform address translation again for each page
-    for (uint64_t vaddr_page = vaddr_page_start; vaddr_page < vaddr_page_limit; vaddr_page += PMA_PAGE_SIZE) {
+    for (uint64_t vaddr_page = vaddr_page_start; vaddr_page < vaddr_page_limit; vaddr_page += AR_PAGE_SIZE) {
         uint64_t paddr_page = 0;
         // perform address translation using read access mode,
         // so we can write any reachable virtual memory range
@@ -2280,7 +2270,7 @@ void machine::write_virtual_memory(uint64_t vaddr_start, const unsigned char *da
         }
         uint64_t paddr = paddr_page;
         uint64_t vaddr = vaddr_page;
-        uint64_t chunklen = std::min<uint64_t>(PMA_PAGE_SIZE, vaddr_limit - vaddr);
+        uint64_t chunklen = std::min<uint64_t>(AR_PAGE_SIZE, vaddr_limit - vaddr);
         if (vaddr_page < vaddr_start) {
             const uint64_t off = vaddr_start - vaddr_page;
             paddr += off;
@@ -2319,7 +2309,7 @@ void machine::write_word(uint64_t paddr, uint64_t val) {
         throw std::domain_error{"attempted misaligned write to word"};
     }
     // If in shadow, forward to write_reg
-    if (paddr >= PMA_SHADOW_STATE_START && paddr - PMA_SHADOW_STATE_START < PMA_SHADOW_STATE_LENGTH) {
+    if (paddr >= AR_SHADOW_STATE_START && paddr - AR_SHADOW_STATE_START < AR_SHADOW_STATE_LENGTH) {
         auto reg = shadow_state_get_what(paddr);
         if (reg == shadow_state_what::unknown_) {
             throw std::runtime_error("unhandled write to shadow state");
@@ -2328,7 +2318,7 @@ void machine::write_word(uint64_t paddr, uint64_t val) {
         return;
     }
     // If in uarch shadow, forward to write_reg
-    if (paddr >= PMA_SHADOW_UARCH_STATE_START && paddr - PMA_SHADOW_UARCH_STATE_START < PMA_SHADOW_UARCH_STATE_LENGTH) {
+    if (paddr >= AR_SHADOW_UARCH_STATE_START && paddr - AR_SHADOW_UARCH_STATE_START < AR_SHADOW_UARCH_STATE_LENGTH) {
         auto reg = shadow_uarch_state_get_what(paddr);
         if (reg == shadow_uarch_state_what::unknown_) {
             throw std::runtime_error("unhandled write to shadow uarch state");
@@ -2506,8 +2496,9 @@ interpreter_break_reason machine::log_step(uint64_t mcycle_count, const std::str
     }
     // Ensure that the microarchitecture is reset
     auto current_uarch_state_hash =
-        get_merkle_tree_node_hash(PMA_SHADOW_UARCH_STATE_START, UARCH_STATE_LOG2_SIZE, skip_merkle_tree_update);
+        get_merkle_tree_node_hash(AR_SHADOW_UARCH_STATE_START, UARCH_STATE_LOG2_SIZE, skip_merkle_tree_update);
     if (current_uarch_state_hash != get_uarch_pristine_state_hash()) {
+        get_merkle_tree_node_hash(AR_SHADOW_UARCH_STATE_START, UARCH_STATE_LOG2_SIZE, skip_merkle_tree_update);
         throw std::runtime_error{"microarchitecture is not reset"};
     }
     hash_type root_hash_before;
diff --git a/src/machine.h b/src/machine.h
index cf75ac872..06ca721ea 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -40,7 +40,7 @@
 #include "machine-runtime-config.h"
 #include "machine-state.h"
 #include "os.h"
-#include "pma-constants.h"
+#include "pmas-constants.h"
 #include "shadow-tlb.h"
 #include "uarch-interpret.h"
 #include "uarch-state.h"
diff --git a/src/memory-address-range.cpp b/src/memory-address-range.cpp
index a8d05ec63..da61d5d12 100644
--- a/src/memory-address-range.cpp
+++ b/src/memory-address-range.cpp
@@ -28,14 +28,14 @@ class base_error : public std::invalid_argument {
 };
 
 memory_address_range::memory_address_range(const std::string &description, uint64_t start, uint64_t length,
-    const pma_flags &flags, const std::string &image_filename, const mmapd &m) try :
+    const pmas_flags &flags, const std::string &image_filename, const mmapd &m) try :
     address_range(description.c_str(), start, length, flags, [](const char *err) { throw base_error{err}; }),
     m_ptr{make_unique_mmap<unsigned char>(image_filename.c_str(), length, m.shared)},
     m_host_memory{std::get<mmapd_ptr>(m_ptr).get()} {
     if (!is_memory()) {
         throw std::invalid_argument{"memory range must be flagged memory when initializing "s + description};
     }
-    m_dirty_page_map.resize((get_length() / (8 * PMA_PAGE_SIZE)) + 1, 0xff);
+    m_dirty_page_map.resize((get_length() / (8 * AR_PAGE_SIZE)) + 1, 0xff);
 } catch (base_error &b) {
     throw; // already contains the description
 } catch (std::exception &e) {
@@ -45,14 +45,14 @@ memory_address_range::memory_address_range(const std::string &description, uint6
 }
 
 memory_address_range::memory_address_range(const std::string &description, uint64_t start, uint64_t length,
-    const pma_flags &flags, const std::string &image_filename, const callocd & /*c*/) try :
+    const pmas_flags &flags, const std::string &image_filename, const callocd & /*c*/) try :
     address_range(description.c_str(), start, length, flags, [](const char *err) { throw base_error{err}; }),
     m_ptr{make_unique_calloc<unsigned char>(length)},
     m_host_memory{std::get<callocd_ptr>(m_ptr).get()} {
     if (!is_memory()) {
         throw std::invalid_argument{"memory range must be flagged memory when initializing "s + description};
     }
-    m_dirty_page_map.resize((length / (8 * PMA_PAGE_SIZE)) + 1, 0xff);
+    m_dirty_page_map.resize((length / (8 * AR_PAGE_SIZE)) + 1, 0xff);
     // Try to load image file, if any
     if (!image_filename.empty()) {
         auto fp = make_unique_fopen(image_filename.c_str(), "rb", std::nothrow_t{});
diff --git a/src/memory-address-range.h b/src/memory-address-range.h
index 7beb6a56f..e7b828147 100644
--- a/src/memory-address-range.h
+++ b/src/memory-address-range.h
@@ -60,7 +60,7 @@ class memory_address_range : public address_range {
     /// \param flags Range flags
     /// \param image_filename Path to backing file.
     /// \param m Mmap'd range data (shared or not).
-    memory_address_range(const std::string &description, uint64_t start, uint64_t length, const pma_flags &flags,
+    memory_address_range(const std::string &description, uint64_t start, uint64_t length, const pmas_flags &flags,
         const std::string &image_filename, const mmapd &m);
 
     /// \brief Calloc'd range data (just a tag).
@@ -73,7 +73,7 @@ class memory_address_range : public address_range {
     /// \param flags Range flags
     /// \param image_filename Path to backing file.
     /// \param c Calloc'd range data (just a tag).
-    memory_address_range(const std::string &description, uint64_t start, uint64_t length, const pma_flags &flags,
+    memory_address_range(const std::string &description, uint64_t start, uint64_t length, const pmas_flags &flags,
         const std::string &image_filename, const callocd & /*c*/);
 
     memory_address_range(const memory_address_range &) = delete;
@@ -93,14 +93,14 @@ class memory_address_range : public address_range {
     }
 
     void do_mark_dirty_page(uint64_t offset) noexcept override {
-        auto page_index = offset >> PMA_constants::PMA_PAGE_SIZE_LOG2;
+        auto page_index = offset >> AR_constants::AR_PAGE_SIZE_LOG2;
         auto map_index = page_index >> 3;
         assert(map_index < m_dirty_page_map.size());
         m_dirty_page_map[map_index] |= (1 << (page_index & 7));
     }
 
     void do_mark_clean_page(uint64_t offset) noexcept override {
-        auto page_index = offset >> PMA_constants::PMA_PAGE_SIZE_LOG2;
+        auto page_index = offset >> AR_constants::AR_PAGE_SIZE_LOG2;
         auto map_index = page_index >> 3;
         assert(map_index < m_dirty_page_map.size());
         m_dirty_page_map[map_index] &= ~(1 << (page_index & 7));
@@ -111,7 +111,7 @@ class memory_address_range : public address_range {
     }
 
     bool do_is_page_marked_dirty(uint64_t offset) const noexcept override {
-        auto page_index = offset >> PMA_constants::PMA_PAGE_SIZE_LOG2;
+        auto page_index = offset >> AR_constants::AR_PAGE_SIZE_LOG2;
         auto map_index = page_index >> 3;
         assert(map_index < m_dirty_page_map.size());
         return (m_dirty_page_map[map_index] & (1 << (page_index & 7))) != 0;
@@ -129,12 +129,12 @@ class memory_address_range : public address_range {
 };
 
 static inline auto make_callocd_memory_address_range(const std::string &description, uint64_t start, uint64_t length,
-    pma_flags flags, const std::string &image_filename = {}) {
+    pmas_flags flags, const std::string &image_filename = {}) {
     return memory_address_range{description, start, length, flags, image_filename, memory_address_range::callocd{}};
 }
 
 static inline auto make_mmapd_memory_address_range(const std::string &description, uint64_t start, uint64_t length,
-    pma_flags flags, const std::string &image_filename, bool shared) {
+    pmas_flags flags, const std::string &image_filename, bool shared) {
     return memory_address_range{description, start, length, flags, image_filename, memory_address_range::mmapd{shared}};
 }
 
diff --git a/src/mock-address-range.h b/src/mock-address-range.h
index b79ede8d0..5f51ff520 100644
--- a/src/mock-address-range.h
+++ b/src/mock-address-range.h
@@ -25,7 +25,7 @@
 #include "clint-address-range.h"
 #include "htif-address-range.h"
 #include "plic-address-range.h"
-#include "pma.h"
+#include "pmas.h"
 #include "shadow-state-address-range.h"
 #include "shadow-tlb-address-range.h"
 
@@ -37,7 +37,7 @@ using mock_address_range = std::variant<std::monostate, address_range, clint_add
 using mock_address_ranges = std::array<mock_address_range, PMA_MAX>;
 
 template <typename AR, typename ABRT>
-static inline mock_address_range check_mock_flags(AR &&ar, const pma_flags &flags, ABRT abrt)
+static inline mock_address_range check_mock_flags(AR &&ar, const pmas_flags &flags, ABRT abrt)
     requires std::is_rvalue_reference_v<AR &&> && std::derived_from<AR, address_range>
 {
     if (ar.get_flags() != flags) {
@@ -51,9 +51,9 @@ static inline mock_address_range check_mock_flags(AR &&ar, const pma_flags &flag
 template <typename ABRT>
 static inline mock_address_range make_mock_address_range(uint64_t istart, uint64_t ilength, ABRT abrt) {
     uint64_t start{};
-    auto flags = pma_unpack_istart(istart, start);
+    auto flags = pmas_unpack_istart(istart, start);
     if (flags.M) {
-        return make_address_range(pma_get_DID_name(flags.DID), start, ilength, flags, abrt);
+        return make_address_range(pmas_get_DID_name(flags.DID), start, ilength, flags, abrt);
     }
     if (flags.E) {
         return make_address_range("empty", start, ilength, flags, abrt);
diff --git a/src/plic-address-range.cpp b/src/plic-address-range.cpp
index cd8148561..fe7a01357 100644
--- a/src/plic-address-range.cpp
+++ b/src/plic-address-range.cpp
@@ -21,7 +21,7 @@
 
 #include "i-device-state-access.h"
 #include "interpret.h"
-#include "pma-constants.h"
+#include "pmas-constants.h"
 #include "riscv-constants.h"
 
 // Enable these defines to debug PLIC
@@ -86,7 +86,7 @@ static execute_status plic_write_claim_complete(i_device_state_access *a, uint32
 #ifdef DEBUG_PLIC
     std::ignore = fprintf(stderr, "plic: claim complete irq_id=%d\n", val);
 #endif
-    if (val >= 1 && val <= PMA_PLIC_MAX_IRQ_DEF) {
+    if (val >= 1 && val <= PLIC_MAX_IRQ) {
         // On completing, we need to clear its corresponding girqsrvd mask
         const uint32_t girqpend = a->read_plic_girqpend();
         uint32_t girqsrvd = a->read_plic_girqsrvd();
@@ -112,7 +112,7 @@ bool plic_address_range::do_read_device(i_device_state_access *a, uint64_t offse
 #endif
 
     // Our PLIC only supports aligned 32-bit reads
-    if (((offset & 3) != 0) || log2_size != 2 || offset > PMA_PLIC_LENGTH) {
+    if (((offset & 3) != 0) || log2_size != 2 || offset > AR_PLIC_LENGTH) {
         return false;
     }
 
@@ -169,7 +169,7 @@ bool plic_address_range::do_read_device(i_device_state_access *a, uint64_t offse
     }
 }
 
-/// \brief PLIC device read callback. See ::pma_write.
+/// \brief PLIC device read callback. See ::pmas_write.
 execute_status plic_address_range::do_write_device(i_device_state_access *a, uint64_t offset, int log2_size,
     uint64_t val) noexcept {
 #ifdef DEBUG_PLIC_MMIO
@@ -178,7 +178,7 @@ execute_status plic_address_range::do_write_device(i_device_state_access *a, uin
 #endif
 
     // Our PLIC only supports aligned 32-bit reads
-    if (((offset & 3) != 0) || log2_size != 2 || offset > PMA_PLIC_LENGTH) {
+    if (((offset & 3) != 0) || log2_size != 2 || offset > AR_PLIC_LENGTH) {
         return execute_status::failure;
     }
 
diff --git a/src/plic-address-range.h b/src/plic-address-range.h
index e430a1974..76ab71de8 100644
--- a/src/plic-address-range.h
+++ b/src/plic-address-range.h
@@ -38,7 +38,7 @@ void plic_reset_pending_irq(i_device_state_access *a, uint32_t irq_id);
 
 class plic_address_range final : public pristine_address_range {
 
-    static constexpr pma_flags m_plic_flags{
+    static constexpr pmas_flags m_plic_flags{
         .M = false,
         .IO = true,
         .E = false,
diff --git a/src/plic-constants.h b/src/plic-constants.h
index d6eda8311..db3e15ca0 100644
--- a/src/plic-constants.h
+++ b/src/plic-constants.h
@@ -27,6 +27,7 @@ namespace cartesi {
 enum PLIC_constants : uint64_t {
     PLIC_ENABLED_IRQ_MASK = UINT64_C(0xfffffffe), // Interrupt mask for all enabled interrupt sources (1-31)
     PLIC_LOWEST_IRQ_PRIORITY = 1,
+    PLIC_MAX_IRQ = 31 ///< Maximum PLIC interrupt
 };
 
 /// \brief Mapping between CSRs and their relative addresses in PLIC memory
diff --git a/src/pma-constants.h b/src/pma-constants.h
deleted file mode 100644
index 14a589a11..000000000
--- a/src/pma-constants.h
+++ /dev/null
@@ -1,126 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef PMA_CONSTANTS_H
-#define PMA_CONSTANTS_H
-
-#include <cstdint>
-
-#include "pma-defines.h"
-
-namespace cartesi {
-
-/// \brief Fixed PMA ranges.
-enum PMA_ranges : uint64_t {
-    PMA_SHADOW_STATE_START = EXPAND_UINT64_C(PMA_SHADOW_STATE_START_DEF),   ///< Start of processor shadow range
-    PMA_SHADOW_STATE_LENGTH = EXPAND_UINT64_C(PMA_SHADOW_STATE_LENGTH_DEF), ///< Length of processor shadow range
-    PMA_PMAS_START = EXPAND_UINT64_C(PMA_PMAS_START_DEF),                   ///< Start of pma board shadow range
-    PMA_PMAS_LENGTH = EXPAND_UINT64_C(PMA_PMAS_LENGTH_DEF),                 ///< Length of pma board shadow range
-    PMA_DTB_START = EXPAND_UINT64_C(PMA_DTB_START_DEF),                     ///< Start of DTB range
-    PMA_DTB_LENGTH = EXPAND_UINT64_C(PMA_DTB_LENGTH_DEF),                   ///< Length of DTB range
-    PMA_SHADOW_TLB_START = EXPAND_UINT64_C(PMA_SHADOW_TLB_START_DEF),       ///< Start of TLB shadow range
-    PMA_SHADOW_TLB_LENGTH = EXPAND_UINT64_C(PMA_SHADOW_TLB_LENGTH_DEF),     ///< Length of TLB shadow range
-    PMA_SHADOW_UARCH_STATE_START =
-        EXPAND_UINT64_C(PMA_SHADOW_UARCH_STATE_START_DEF), ///< Start of microarchitecture shadow state range
-    PMA_SHADOW_UARCH_STATE_LENGTH =
-        EXPAND_UINT64_C(PMA_SHADOW_UARCH_STATE_LENGTH_DEF),         ///< Length of microarchitecture shadow state  range
-    PMA_CLINT_START = EXPAND_UINT64_C(PMA_CLINT_START_DEF),         ///< Start of CLINT range
-    PMA_CLINT_LENGTH = EXPAND_UINT64_C(PMA_CLINT_LENGTH_DEF),       ///< Length of CLINT range
-    PMA_PLIC_START = EXPAND_UINT64_C(PMA_PLIC_START_DEF),           ///< Start of PLIC range
-    PMA_PLIC_LENGTH = EXPAND_UINT64_C(PMA_PLIC_LENGTH_DEF),         ///< Length of PLIC range
-    PMA_HTIF_START = EXPAND_UINT64_C(PMA_HTIF_START_DEF),           ///< Start of HTIF range
-    PMA_HTIF_LENGTH = EXPAND_UINT64_C(PMA_HTIF_LENGTH_DEF),         ///< Length of HTIF range
-    PMA_UARCH_RAM_START = EXPAND_UINT64_C(PMA_UARCH_RAM_START_DEF), ///< Start of microarchitecture RAM range
-    PMA_UARCH_RAM_LENGTH = EXPAND_UINT64_C(PMA_UARCH_RAM_LENGTH_DEF),         ///< Length of microarchitecture RAM range
-    PMA_CMIO_RX_BUFFER_START = EXPAND_UINT64_C(PMA_CMIO_RX_BUFFER_START_DEF), ///< Start of CMIO RX buffer range
-    PMA_CMIO_RX_BUFFER_LOG2_SIZE = EXPAND_UINT64_C(PMA_CMIO_RX_BUFFER_LOG2_SIZE_DEF), ///< Log2 of CMIO RX buffer range
-    PMA_CMIO_RX_BUFFER_LENGTH = (UINT64_C(1) << PMA_CMIO_RX_BUFFER_LOG2_SIZE_DEF), ///< Length of CMIO RX buffer range
-    PMA_CMIO_TX_BUFFER_START = EXPAND_UINT64_C(PMA_CMIO_TX_BUFFER_START_DEF),      ///< Start of CMIO TX buffer range
-    PMA_CMIO_TX_BUFFER_LOG2_SIZE = EXPAND_UINT64_C(PMA_CMIO_TX_BUFFER_LOG2_SIZE_DEF), ///< Log2 of CMIO TX buffer range
-    PMA_CMIO_TX_BUFFER_LENGTH = (UINT64_C(1) << PMA_CMIO_TX_BUFFER_LOG2_SIZE_DEF), ///< Length of CMIO TX buffer range
-    PMA_DRIVE_START = EXPAND_UINT64_C(PMA_DRIVE_START_DEF),   ///< Start PMA address for flash drives
-    PMA_DRIVE_OFFSET = EXPAND_UINT64_C(PMA_DRIVE_OFFSET_DEF), ///< PMA offset for extra flash drives
-
-    PMA_FIRST_VIRTIO_START = EXPAND_UINT64_C(PMA_FIRST_VIRTIO_START_DEF), ///< Start of first VIRTIO range
-    PMA_VIRTIO_LENGTH = EXPAND_UINT64_C(PMA_VIRTIO_LENGTH_DEF),           ///< Length of each VIRTIO range
-    PMA_LAST_VIRTIO_END = EXPAND_UINT64_C(PMA_LAST_VIRTIO_END_DEF),       ///< End of last VIRTIO range
-
-    PMA_RAM_START = EXPAND_UINT64_C(PMA_RAM_START_DEF), ///< Start of RAM range
-};
-
-/// \brief PMA constants.
-enum PMA_constants : uint64_t {
-    PMA_PAGE_SIZE_LOG2 = EXPAND_UINT64_C(PMA_PAGE_SIZE_LOG2_DEF), ///< log<sub>2</sub> of physical memory page size.
-    PMA_PAGE_SIZE = (UINT64_C(1) << PMA_PAGE_SIZE_LOG2_DEF),      ///< Physical memory page size.
-    PMA_MAX = EXPAND_UINT64_C(PMA_MAX_DEF)                        ///< Maximum number of PMAs
-};
-
-/// \brief PMA PLIC constants.
-enum PMA_plic_constants : uint64_t {
-    PMA_PLIC_MAX_IRQ = EXPAND_UINT64_C(PMA_PLIC_MAX_IRQ_DEF), ///< Maximum PLIC interrupt
-};
-
-/// \brief PMA masks.
-enum PMA_masks : uint64_t {
-    PMA_ADDRESSABLE_MASK = ((UINT64_C(1) << 56) - 1) ///< Mask for addressable PMA ranges.
-};
-
-/// \brief PMA istart shifts
-enum PMA_ISTART_shifts {
-    PMA_ISTART_M_SHIFT = 0,
-    PMA_ISTART_IO_SHIFT = 1,
-    PMA_ISTART_E_SHIFT = 2,
-    PMA_ISTART_R_SHIFT = 3,
-    PMA_ISTART_W_SHIFT = 4,
-    PMA_ISTART_X_SHIFT = 5,
-    PMA_ISTART_IR_SHIFT = 6,
-    PMA_ISTART_IW_SHIFT = 7,
-    PMA_ISTART_DID_SHIFT = 8,
-    PMA_ISTART_START_SHIFT = PMA_PAGE_SIZE_LOG2_DEF
-};
-
-/// \brief PMA istart masks
-enum PMA_ISTART_masks : uint64_t {
-    PMA_ISTART_M_MASK = UINT64_C(1) << PMA_ISTART_M_SHIFT,         ///< Memory range
-    PMA_ISTART_IO_MASK = UINT64_C(1) << PMA_ISTART_IO_SHIFT,       ///< Device range
-    PMA_ISTART_E_MASK = UINT64_C(1) << PMA_ISTART_E_SHIFT,         ///< Empty range
-    PMA_ISTART_R_MASK = UINT64_C(1) << PMA_ISTART_R_SHIFT,         ///< Readable
-    PMA_ISTART_W_MASK = UINT64_C(1) << PMA_ISTART_W_SHIFT,         ///< Writable
-    PMA_ISTART_X_MASK = UINT64_C(1) << PMA_ISTART_X_SHIFT,         ///< Executable
-    PMA_ISTART_IR_MASK = UINT64_C(1) << PMA_ISTART_IR_SHIFT,       ///< Idempotent reads
-    PMA_ISTART_IW_MASK = UINT64_C(1) << PMA_ISTART_IW_SHIFT,       ///< Idempotent writes
-    PMA_ISTART_DID_MASK = UINT64_C(15) << PMA_ISTART_DID_SHIFT,    ///< Device id
-    PMA_ISTART_START_MASK = UINT64_C(-1) << PMA_ISTART_START_SHIFT ///< Start of range
-};
-
-/// \brief PMA device ids
-enum class PMA_ISTART_DID {
-    memory = PMA_MEMORY_DID_DEF,                         ///< DID for memory
-    shadow_state = PMA_SHADOW_STATE_DID_DEF,             ///< DID for shadow device
-    shadow_TLB = PMA_SHADOW_TLB_DID_DEF,                 ///< DID for shadow TLB device
-    flash_drive = PMA_FLASH_DRIVE_DID_DEF,               ///< DID for drive device
-    CLINT = PMA_CLINT_DID_DEF,                           ///< DID for CLINT device
-    PLIC = PMA_PLIC_DID_DEF,                             ///< DID for PLIC device
-    HTIF = PMA_HTIF_DID_DEF,                             ///< DID for HTIF device
-    VIRTIO = PMA_VIRTIO_DID_DEF,                         ///< DID for VirtIO devices
-    cmio_rx_buffer = PMA_CMIO_RX_BUFFER_DID_DEF,         ///< DID for cmio receive buffer
-    cmio_tx_buffer = PMA_CMIO_TX_BUFFER_DID_DEF,         ///< DID for cmio transmit buffer
-    shadow_uarch_state = PMA_SHADOW_UARCH_STATE_DID_DEF, ///< DID for shadow uarch state device
-};
-
-} // namespace cartesi
-
-#endif
diff --git a/src/pma-defines.h b/src/pma-defines.h
deleted file mode 100644
index 8ad7dfff4..000000000
--- a/src/pma-defines.h
+++ /dev/null
@@ -1,71 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef PMA_DEFINES_H
-#define PMA_DEFINES_H
-// NOLINTBEGIN(cppcoreguidelines-macro-usage,cppcoreguidelines-macro-to-enum,modernize-macro-to-enum)
-#define PMA_SHADOW_STATE_START_DEF 0x0            ///< Shadow start address
-#define PMA_SHADOW_STATE_LENGTH_DEF 0x1000        ///< Shadow length in bytes
-#define PMA_PMAS_START_DEF 0x10000                ///< PMA Array start address
-#define PMA_PMAS_LENGTH_DEF 0x1000                ///< PMA Array length in bytes
-#define PMA_SHADOW_TLB_START_DEF 0x20000          ///< TLB start address
-#define PMA_SHADOW_TLB_LENGTH_DEF 0x6000          ///< TLB length in bytes
-#define PMA_SHADOW_UARCH_STATE_START_DEF 0x400000 ///< microarchitecture shadow state start address
-#define PMA_SHADOW_UARCH_STATE_LENGTH_DEF 0x1000  ///< microarchitecture shadow state length
-#define PMA_UARCH_RAM_START_DEF 0x600000          ///< microarchitecture RAM start address
-#define PMA_UARCH_RAM_LENGTH_DEF 0x200000         ///< microarchitecture RAM length
-#define PMA_CLINT_START_DEF 0x2000000             ///< CLINT start address
-#define PMA_CLINT_LENGTH_DEF 0xC0000              ///< CLINT length in bytes
-#define PMA_PLIC_START_DEF 0x40100000             ///< Start of PLIC range
-#define PMA_PLIC_LENGTH_DEF 0x00400000            ///< Length of PLIC range
-#define PMA_HTIF_START_DEF 0x40008000             ///< HTIF base address (to_host)
-#define PMA_HTIF_LENGTH_DEF 0x1000                ///< HTIF length in bytes
-#define PMA_FIRST_VIRTIO_START_DEF 0x40010000     ///< Start of first VIRTIO range
-#define PMA_VIRTIO_LENGTH_DEF 0x1000              ///< Length of each VIRTIO range
-#define PMA_LAST_VIRTIO_END_DEF 0x40020000        ///< End of last VIRTIO range
-#define PMA_DTB_START_DEF 0x7ff00000              ///< DTB start address
-#define PMA_DTB_LENGTH_DEF 0x100000               ///< DTB length in bytes
-#define PMA_CMIO_RX_BUFFER_START_DEF 0x60000000   ///< CMIO RX buffer start address
-#define PMA_CMIO_RX_BUFFER_LOG2_SIZE_DEF 21       ///< log<sub>2</sub> of CMIO RX buffer length in bytes
-#define PMA_CMIO_TX_BUFFER_START_DEF 0x60800000   ///< CMIO TX buffer start address
-#define PMA_CMIO_TX_BUFFER_LOG2_SIZE_DEF 21       ///< log<sub>2</sub> of CMIO TX buffer length in bytes
-#define PMA_DRIVE_START_DEF 0x80000000000000      ///< Start PMA address for flash drives
-#define PMA_DRIVE_OFFSET_DEF 0x10000000000000     ///< PMA offset for extra flash drives
-
-#define PMA_RAM_START_DEF 0x80000000 ///< RAM start address
-
-#define PMA_PAGE_SIZE_LOG2_DEF 12 ///< log<sub>2</sub> of physical memory page size.
-#define PMA_MAX_DEF 32            ///< Maximum number of PMAs
-#define PMA_PLIC_MAX_IRQ_DEF 31   ///< Maximum PLIC interrupt
-
-#define PMA_MEMORY_DID_DEF 0              ///< Device ID for memory
-#define PMA_SHADOW_STATE_DID_DEF 1        ///< Device ID for shadow state device
-#define PMA_FLASH_DRIVE_DID_DEF 2         ///< Device ID for flash drive device
-#define PMA_CLINT_DID_DEF 3               ///< Device ID for CLINT device
-#define PMA_HTIF_DID_DEF 4                ///< Device ID for HTIF device
-#define PMA_SHADOW_TLB_DID_DEF 5          ///< Device ID for shadow TLB device
-#define PMA_CMIO_RX_BUFFER_DID_DEF 6      ///< Device ID for cmio RX buffer
-#define PMA_CMIO_TX_BUFFER_DID_DEF 7      ///< Device ID for cmio TX buffer
-#define PMA_PLIC_DID_DEF 9                ///< Device ID for PLIC device
-#define PMA_VIRTIO_DID_DEF 10             ///< Device ID for VirtIO devices
-#define PMA_SHADOW_UARCH_STATE_DID_DEF 11 ///< Device ID for uarch shadow state device
-
-// helper for using UINT64_C with defines
-#ifndef EXPAND_UINT64_C
-#define EXPAND_UINT64_C(a) UINT64_C(a)
-#endif
-// NOLINTEND(cppcoreguidelines-macro-usage,cppcoreguidelines-macro-to-enum,modernize-macro-to-enum)
-#endif /* end of include guard: PMA_DEFINES_H */
diff --git a/src/pmas-address-range.h b/src/pmas-address-range.h
index 4a2ce8f07..960f20e41 100644
--- a/src/pmas-address-range.h
+++ b/src/pmas-address-range.h
@@ -21,7 +21,7 @@
 #include <stdexcept>
 
 #include "memory-address-range.h"
-#include "pma.h"
+#include "pmas.h"
 
 /// \file
 /// \brief Shadow device.
@@ -29,7 +29,7 @@
 namespace cartesi {
 
 static inline auto make_pmas_address_range(uint64_t start, uint64_t length) {
-    static constexpr pma_flags m_flags{
+    static constexpr pmas_flags m_flags{
         .M = true,
         .IO = false,
         .E = false,
diff --git a/src/pmas-constants.h b/src/pmas-constants.h
new file mode 100644
index 000000000..fa6aaae09
--- /dev/null
+++ b/src/pmas-constants.h
@@ -0,0 +1,77 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef PMAS_CONSTANTS_H
+#define PMAS_CONSTANTS_H
+
+#include <cstdint>
+
+#include "pmas-defines.h"
+
+namespace cartesi {
+
+/// \brief PMA constants.
+enum PMA_constants : uint64_t {
+    PMA_MAX = EXPAND_UINT64_C(PMA_MAX_DEF) ///< Maximum number of PMAs
+};
+
+/// \brief PMA istart shifts
+enum PMA_ISTART_shifts {
+    PMA_ISTART_M_SHIFT = 0,
+    PMA_ISTART_IO_SHIFT = 1,
+    PMA_ISTART_E_SHIFT = 2,
+    PMA_ISTART_R_SHIFT = 3,
+    PMA_ISTART_W_SHIFT = 4,
+    PMA_ISTART_X_SHIFT = 5,
+    PMA_ISTART_IR_SHIFT = 6,
+    PMA_ISTART_IW_SHIFT = 7,
+    PMA_ISTART_DID_SHIFT = 8,
+    AR_ISTART_START_SHIFT = 12
+};
+
+/// \brief PMA istart masks
+enum PMA_ISTART_masks : uint64_t {
+    PMA_ISTART_M_MASK = UINT64_C(1) << PMA_ISTART_M_SHIFT,       ///< Memory range
+    PMA_ISTART_IO_MASK = UINT64_C(1) << PMA_ISTART_IO_SHIFT,     ///< Device range
+    PMA_ISTART_E_MASK = UINT64_C(1) << PMA_ISTART_E_SHIFT,       ///< Empty range
+    PMA_ISTART_R_MASK = UINT64_C(1) << PMA_ISTART_R_SHIFT,       ///< Readable
+    PMA_ISTART_W_MASK = UINT64_C(1) << PMA_ISTART_W_SHIFT,       ///< Writable
+    PMA_ISTART_X_MASK = UINT64_C(1) << PMA_ISTART_X_SHIFT,       ///< Executable
+    PMA_ISTART_IR_MASK = UINT64_C(1) << PMA_ISTART_IR_SHIFT,     ///< Idempotent reads
+    PMA_ISTART_IW_MASK = UINT64_C(1) << PMA_ISTART_IW_SHIFT,     ///< Idempotent writes
+    PMA_ISTART_DID_MASK = UINT64_C(15) << PMA_ISTART_DID_SHIFT,  ///< Device id
+    AR_ISTART_START_MASK = UINT64_C(-1) << AR_ISTART_START_SHIFT ///< Start of range
+};
+
+/// \brief PMA device ids
+enum class PMA_ISTART_DID : uint8_t {
+    empty = PMA_EMPTY_DID_DEF,                           ///< DID for empty range
+    memory = PMA_MEMORY_DID_DEF,                         ///< DID for memory
+    shadow_state = PMA_SHADOW_STATE_DID_DEF,             ///< DID for shadow state
+    shadow_TLB = PMA_SHADOW_TLB_DID_DEF,                 ///< DID for shadow TLB
+    flash_drive = PMA_FLASH_DRIVE_DID_DEF,               ///< DID for flash drives
+    CLINT = PMA_CLINT_DID_DEF,                           ///< DID for CLINT device
+    PLIC = PMA_PLIC_DID_DEF,                             ///< DID for PLIC device
+    HTIF = PMA_HTIF_DID_DEF,                             ///< DID for HTIF device
+    VIRTIO = PMA_VIRTIO_DID_DEF,                         ///< DID for VirtIO devices
+    cmio_rx_buffer = PMA_CMIO_RX_BUFFER_DID_DEF,         ///< DID for cmio receive buffer
+    cmio_tx_buffer = PMA_CMIO_TX_BUFFER_DID_DEF,         ///< DID for cmio transmit buffer
+    shadow_uarch_state = PMA_SHADOW_UARCH_STATE_DID_DEF, ///< DID for shadow uarch state
+};
+
+} // namespace cartesi
+
+#endif
diff --git a/src/pmas-defines.h b/src/pmas-defines.h
new file mode 100644
index 000000000..38008e7c7
--- /dev/null
+++ b/src/pmas-defines.h
@@ -0,0 +1,41 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef PMA_DEFINES_H
+#define PMA_DEFINES_H
+// NOLINTBEGIN(cppcoreguidelines-macro-usage,cppcoreguidelines-macro-to-enum,modernize-macro-to-enum)
+
+#define PMA_MAX_DEF 32 ///< Maximum number of PMAs
+
+#define PMA_EMPTY_DID_DEF 0               ///< Device ID for empty range
+#define PMA_MEMORY_DID_DEF 1              ///< Device ID for memory
+#define PMA_SHADOW_STATE_DID_DEF 2        ///< Device ID for shadow state device
+#define PMA_FLASH_DRIVE_DID_DEF 3         ///< Device ID for flash drive device
+#define PMA_CLINT_DID_DEF 4               ///< Device ID for CLINT device
+#define PMA_HTIF_DID_DEF 5                ///< Device ID for HTIF device
+#define PMA_SHADOW_TLB_DID_DEF 6          ///< Device ID for shadow TLB device
+#define PMA_CMIO_RX_BUFFER_DID_DEF 7      ///< Device ID for cmio RX buffer
+#define PMA_CMIO_TX_BUFFER_DID_DEF 8      ///< Device ID for cmio TX buffer
+#define PMA_PLIC_DID_DEF 10               ///< Device ID for PLIC device
+#define PMA_VIRTIO_DID_DEF 11             ///< Device ID for VirtIO devices
+#define PMA_SHADOW_UARCH_STATE_DID_DEF 12 ///< Device ID for uarch shadow state device
+
+// helper for using UINT64_C with defines
+#ifndef EXPAND_UINT64_C
+#define EXPAND_UINT64_C(a) UINT64_C(a)
+#endif
+// NOLINTEND(cppcoreguidelines-macro-usage,cppcoreguidelines-macro-to-enum,modernize-macro-to-enum)
+#endif /* end of include guard: PMA_DEFINES_H */
diff --git a/src/pma.h b/src/pmas.h
similarity index 73%
rename from src/pma.h
rename to src/pmas.h
index 19ac32fb1..fe178e0e4 100644
--- a/src/pma.h
+++ b/src/pmas.h
@@ -14,21 +14,23 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#ifndef PMA_H
-#define PMA_H
+#ifndef PMAS_H
+#define PMAS_H
 
 #include <array>
+#include <cstddef>
 #include <cstdint>
 
+#include "address-range-constants.h"
 #include "compiler-defines.h"
-#include "pma-constants.h"
+#include "pmas-constants.h"
 
 namespace cartesi {
 
 /// \file
 /// \brief Physical memory attributes.
 
-static constexpr const char *pma_get_DID_name(PMA_ISTART_DID did) {
+static constexpr const char *pmas_get_DID_name(PMA_ISTART_DID did) {
     switch (did) {
         case PMA_ISTART_DID::memory:
             return "DID.memory";
@@ -58,7 +60,7 @@ static constexpr const char *pma_get_DID_name(PMA_ISTART_DID did) {
 }
 
 ///< Unpacked attribute flags
-struct pma_flags {
+struct pmas_flags {
     bool M;             ///< is memory
     bool IO;            ///< is device
     bool E;             ///< is empty
@@ -70,12 +72,12 @@ struct pma_flags {
     PMA_ISTART_DID DID; ///< driver id
 
     // Defaulted comparison operator
-    bool operator==(const pma_flags &) const = default;
+    bool operator==(const pmas_flags &) const = default;
 };
 
-static constexpr pma_flags pma_unpack_istart(uint64_t istart, uint64_t &start) {
-    start = istart & PMA_ISTART_START_MASK;
-    return pma_flags{.M = ((istart & PMA_ISTART_M_MASK) >> PMA_ISTART_M_SHIFT) != 0,
+static constexpr pmas_flags pmas_unpack_istart(uint64_t istart, uint64_t &start) {
+    start = istart & AR_ISTART_START_MASK;
+    return pmas_flags{.M = ((istart & PMA_ISTART_M_MASK) >> PMA_ISTART_M_SHIFT) != 0,
         .IO = ((istart & PMA_ISTART_IO_MASK) >> PMA_ISTART_IO_SHIFT) != 0,
         .E = ((istart & PMA_ISTART_E_MASK) >> PMA_ISTART_E_SHIFT) != 0,
         .R = ((istart & PMA_ISTART_R_MASK) >> PMA_ISTART_R_SHIFT) != 0,
@@ -86,7 +88,7 @@ static constexpr pma_flags pma_unpack_istart(uint64_t istart, uint64_t &start) {
         .DID = static_cast<PMA_ISTART_DID>((istart & PMA_ISTART_DID_MASK) >> PMA_ISTART_DID_SHIFT)};
 }
 
-static constexpr uint64_t pma_pack_istart(const pma_flags &flags, uint64_t start) {
+static constexpr uint64_t pmas_pack_istart(const pmas_flags &flags, uint64_t start) {
     uint64_t istart = start;
     istart |= (static_cast<uint64_t>(flags.M) << PMA_ISTART_M_SHIFT);
     istart |= (static_cast<uint64_t>(flags.IO) << PMA_ISTART_IO_SHIFT);
@@ -101,61 +103,60 @@ static constexpr uint64_t pma_pack_istart(const pma_flags &flags, uint64_t start
 }
 
 /// \brief Shadow memory layout
-struct PACKED pma_entry {
+struct PACKED pmas_entry {
     uint64_t istart;
     uint64_t ilength;
 };
 
-using pmas_state = std::array<pma_entry, PMA_MAX>;
+using pmas_state = std::array<pmas_entry, PMA_MAX>;
 
 /// \brief List of field types
-enum class pma_what : uint64_t {
-    istart = offsetof(pma_entry, istart),
-    ilength = offsetof(pma_entry, ilength),
+enum class pmas_what : uint64_t {
+    istart = offsetof(pmas_entry, istart),
+    ilength = offsetof(pmas_entry, ilength),
     unknown_ = UINT64_C(1) << 63, // Outside of RISC-V address space
 };
 
 /// \brief Obtains the absolute address of a PMA entry.
 /// \param p Index of desired PMA entry
 /// \returns The address.
-static constexpr uint64_t pma_get_abs_addr(uint64_t p) {
-    return PMA_PMAS_START + (p * sizeof(pma_entry));
+static constexpr uint64_t pmas_get_abs_addr(uint64_t p) {
+    return AR_PMAS_START + (p * sizeof(pmas_entry));
 }
 
 /// \brief Obtains the absolute address of a PMA entry.
 /// \param p Index of desired PMA entry
 /// \param what Desired field
 /// \returns The address.
-static constexpr uint64_t pma_get_abs_addr(uint64_t p, pma_what what) {
-    return pma_get_abs_addr(p) + static_cast<uint64_t>(what);
+static constexpr uint64_t pmas_get_abs_addr(uint64_t p, pmas_what what) {
+    return pmas_get_abs_addr(p) + static_cast<uint64_t>(what);
 }
 
-static constexpr pma_what pma_get_what(uint64_t paddr) {
-    if (paddr < PMA_PMAS_START || paddr - PMA_PMAS_START >= sizeof(pmas_state) ||
-        (paddr & (sizeof(uint64_t) - 1)) != 0) {
-        return pma_what::unknown_;
+static constexpr pmas_what pmas_get_what(uint64_t paddr) {
+    if (paddr < AR_PMAS_START || paddr - AR_PMAS_START >= sizeof(pmas_state) || (paddr & (sizeof(uint64_t) - 1)) != 0) {
+        return pmas_what::unknown_;
     }
-    //??D First condition ensures offset = (paddr-PMA_PMAS_START) >= 0
+    //??D First condition ensures offset = (paddr-AR_PMAS_START) >= 0
     //??D Second ensures offset < sizeof(pmas_state)
     //??D Third ensures offset is aligned to sizeof(uint64_t)
-    //??D pma_entry only contains uint64_t fields
-    //??D pmas_state_what contains one entry with the offset of each field in pma_entry
+    //??D pmas_entry only contains uint64_t fields
+    //??D pmas_state_what contains one entry with the offset of each field in pmas_entry
     //??D I don't see how the cast can produce something outside the enum...
     // NOLINTNEXTLINE(clang-analyzer-optin.core.EnumCastOutOfRange)
-    return pma_what{(paddr - PMA_PMAS_START) % sizeof(pma_entry)};
+    return pmas_what{(paddr - AR_PMAS_START) % sizeof(pmas_entry)};
 }
 
-static constexpr const char *pma_get_what_name(pma_what what) {
+static constexpr const char *pmas_get_what_name(pmas_what what) {
     const auto paddr = static_cast<uint64_t>(what);
-    if (paddr >= sizeof(pma_entry) || (paddr & (sizeof(uint64_t) - 1)) != 0) {
+    if (paddr >= sizeof(pmas_entry) || (paddr & (sizeof(uint64_t) - 1)) != 0) {
         return "pma.unknown_";
     }
     switch (what) {
-        case pma_what::istart:
+        case pmas_what::istart:
             return "pma.istart";
-        case pma_what::ilength:
+        case pmas_what::ilength:
             return "pma.ilength";
-        case pma_what::unknown_:
+        case pmas_what::unknown_:
             return "pma.unknown_";
     }
     return "pmas.unknown_";
diff --git a/src/pristine-address-range.h b/src/pristine-address-range.h
index f59a6aae5..9324e6e71 100644
--- a/src/pristine-address-range.h
+++ b/src/pristine-address-range.h
@@ -35,7 +35,7 @@ class pristine_address_range : public address_range {
     /// \param length Length of range, in bytes
     /// \param f Phyical memory attribute flags for range
     template <typename ABRT>
-    pristine_address_range(const char *description, uint64_t start, uint64_t length, pma_flags f, ABRT abrt) :
+    pristine_address_range(const char *description, uint64_t start, uint64_t length, pmas_flags f, ABRT abrt) :
         address_range{description, start, length, f, abrt} {
         ;
     }
diff --git a/src/record-send-cmio-state-access.h b/src/record-send-cmio-state-access.h
index 575957d7b..8fdedeb6a 100644
--- a/src/record-send-cmio-state-access.h
+++ b/src/record-send-cmio-state-access.h
@@ -251,8 +251,8 @@ class record_send_cmio_state_access :
         a.get_written_hash().emplace();
         hasher_type hasher{};
         const auto offset = paddr - ar.get_start();
-        get_merkle_tree_hash(hasher, ar.get_host_memory() + offset, write_length,
-            machine_merkle_tree::get_word_size(), a.get_written_hash().value());
+        get_merkle_tree_hash(hasher, ar.get_host_memory() + offset, write_length, machine_merkle_tree::get_word_size(),
+            a.get_written_hash().value());
         if (m_log.get_log_type().has_large_data()) {
             access_data &data = a.get_written().emplace(write_length);
             memcpy(data.data(), ar.get_host_memory() + offset, write_length);
diff --git a/src/record-step-state-access.h b/src/record-step-state-access.h
index c3df12494..e1cc987a5 100644
--- a/src/record-step-state-access.h
+++ b/src/record-step-state-access.h
@@ -27,7 +27,7 @@
 #include "i-prefer-shadow-state.h"
 #include "i-state-access.h"
 #include "machine.h"
-#include "pma.h"
+#include "pmas.h"
 #include "shadow-tlb.h"
 #include "unique-c-ptr.h"
 
@@ -235,8 +235,8 @@ class record_step_state_access :
         // replay_step_state_access reconstructs a mock_address_range from the
         // corresponding istart and ilength fields in the shadow pmas
         // so we mark the page where they live here
-        touch_page(pma_get_abs_addr(index, pma_what::istart));
-        touch_page(pma_get_abs_addr(index, pma_what::ilength));
+        touch_page(pmas_get_abs_addr(index, pmas_what::istart));
+        touch_page(pmas_get_abs_addr(index, pmas_what::ilength));
         return m_m.read_pma(index);
     }
 
diff --git a/src/replay-step-state-access.h b/src/replay-step-state-access.h
index 933506236..01c5a9ac1 100644
--- a/src/replay-step-state-access.h
+++ b/src/replay-step-state-access.h
@@ -27,7 +27,7 @@
 #include "i-prefer-shadow-state.h"
 #include "i-state-access.h"
 #include "mock-address-range.h"
-#include "pma.h"
+#include "pmas.h"
 #include "replay-step-state-access-interop.h"
 #include "riscv-constants.h"
 #include "shadow-state.h"
@@ -76,7 +76,7 @@ class replay_step_state_access :
     public i_prefer_shadow_state<replay_step_state_access> {
 public:
     using address_type = uint64_t;
-    using data_type = unsigned char[PMA_PAGE_SIZE];
+    using data_type = unsigned char[AR_PAGE_SIZE];
     using hash_type = std::array<unsigned char, interop_machine_hash_byte_size>;
     static_assert(sizeof(hash_type) == interop_machine_hash_byte_size);
 
@@ -199,7 +199,7 @@ class replay_step_state_access :
     /// \param paddr The physical address of the page
     /// \return A pointer to the page_type structure if found, nullptr otherwise
     page_type *try_find_page(uint64_t paddr_page) const {
-        const auto page_index = paddr_page >> PMA_PAGE_SIZE_LOG2;
+        const auto page_index = paddr_page >> AR_PAGE_SIZE_LOG2;
         uint64_t min{0};
         uint64_t max{m_context.page_count};
         while (min < max) {
@@ -305,7 +305,7 @@ class replay_step_state_access :
                 if (page_log == nullptr) {
                     continue;
                 }
-                const auto paddr_page = page_log->index << PMA_PAGE_SIZE_LOG2;
+                const auto paddr_page = page_log->index << AR_PAGE_SIZE_LOG2;
                 const auto vp_offset = paddr_page - vaddr_page;
                 aliased_aligned_write<uint64_t>(vp_offset_field_haddr, vp_offset);
             }
@@ -335,14 +335,13 @@ class replay_step_state_access :
         //??D But in the end, we should only update those pages that we touched
         //??D May improve performance when we are running this on ZK
         for (uint64_t i = 0; i < m_context.page_count; i++) {
-            interop_merkle_tree_hash(m_context.pages[i].data, PMA_PAGE_SIZE,
+            interop_merkle_tree_hash(m_context.pages[i].data, AR_PAGE_SIZE,
                 // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
                 reinterpret_cast<interop_hash_type>(&m_context.pages[i].hash));
         }
         size_t next_page = 0;
         size_t next_sibling = 0;
-        auto root_hash =
-            compute_root_hash_impl(0, interop_log2_root_size - PMA_PAGE_SIZE_LOG2, next_page, next_sibling);
+        auto root_hash = compute_root_hash_impl(0, interop_log2_root_size - AR_PAGE_SIZE_LOG2, next_page, next_sibling);
         if (next_page != m_context.page_count) {
             interop_throw_runtime_error("too many pages in log");
         }
@@ -389,7 +388,7 @@ class replay_step_state_access :
 
     //??D we should probably optimize access to the shadow so it doesn't perform a translation every time
     // We can do this by caching the vh_offset trasnslation of the processor shadow page. This is easy if
-    // static_assert(sizeof(shadow_state) <= PMA_PAGE_SIZE, "shadow state must fit in single page");
+    // static_assert(sizeof(shadow_state) <= AR_PAGE_SIZE, "shadow state must fit in single page");
     uint64_t check_read_reg(machine_reg reg) const {
         const auto haddr = do_get_faddr(machine_reg_address(reg));
         return aliased_aligned_read<uint64_t>(haddr);
@@ -397,19 +396,19 @@ class replay_step_state_access :
 
     //??D we should probably optimize access to the shadow so it doesn't perform a translation every time
     // We can do this by caching the vh_offset trasnslation of the processor shadow page. This is easy if
-    // static_assert(sizeof(shadow_state) <= PMA_PAGE_SIZE, "shadow state must fit in single page");
+    // static_assert(sizeof(shadow_state) <= AR_PAGE_SIZE, "shadow state must fit in single page");
     void check_write_reg(machine_reg reg, uint64_t val) const {
         const auto haddr = do_get_faddr(machine_reg_address(reg));
         aliased_aligned_write<uint64_t>(haddr, val);
     }
 
-    uint64_t read_pma_istart(uint64_t index) const {
-        const auto haddr = do_get_faddr(pma_get_abs_addr(index, pma_what::istart));
+    uint64_t read_pmas_istart(uint64_t index) const {
+        const auto haddr = do_get_faddr(pmas_get_abs_addr(index, pmas_what::istart));
         return aliased_aligned_read<uint64_t>(haddr);
     }
 
-    uint64_t read_pma_ilength(uint64_t index) const {
-        const auto haddr = do_get_faddr(pma_get_abs_addr(index, pma_what::ilength));
+    uint64_t read_pmas_ilength(uint64_t index) const {
+        const auto haddr = do_get_faddr(pmas_get_abs_addr(index, pmas_what::ilength));
         return aliased_aligned_read<uint64_t>(haddr);
     }
 
@@ -462,9 +461,9 @@ class replay_step_state_access :
     address_range &do_read_pma(uint64_t index) const {
         assert(index < PMA_MAX);
         // record_step_state_access will have recorded the access to istart and
-        // ilength in its implementation of read_pma_entry.
-        const uint64_t istart = read_pma_istart(index);
-        const uint64_t ilength = read_pma_ilength(index);
+        // ilength in its implementation of read_pmas_entry.
+        const uint64_t istart = read_pmas_istart(index);
+        const uint64_t ilength = read_pmas_ilength(index);
         // NOLINTNEXTLINE(bugprone-narrowing-conversions)
         const int i = static_cast<int>(index);
         const auto abrt = [](const char *err) { interop_throw_runtime_error(err); };
diff --git a/src/riscv-constants.h b/src/riscv-constants.h
index 8d2ffca82..91853ba30 100644
--- a/src/riscv-constants.h
+++ b/src/riscv-constants.h
@@ -19,8 +19,9 @@
 
 #include <cstdint>
 
+#include "address-range-constants.h"
 #include "machine-c-version.h"
-#include "pma-constants.h"
+#include "pmas-constants.h"
 
 /// \file
 /// \brief RISC-V constants
@@ -424,7 +425,7 @@ enum COUNTEREN_rw_masks : uint64_t {
 enum CARTESI_init : uint64_t {
     // The machines starts executing instructions from RAM start by default,
     // and expects a working firmware to be available there.
-    PC_INIT = PMA_RAM_START,                       ///< Initial value for pc
+    PC_INIT = AR_RAM_START,                        ///< Initial value for pc
     FCSR_INIT = UINT64_C(0),                       ///< Initial value for fcsr
     MVENDORID_INIT = UINT64_C(0x6361727465736920), ///< Initial value for mvendorid
     MARCHID_INIT = CM_MARCHID,                     ///< Initial value for marchid
@@ -440,38 +441,38 @@ enum CARTESI_init : uint64_t {
     MTVAL_INIT = UINT64_C(0),                                                          ///< Initial value for mtval
     MISA_INIT = (MISA_MXL_VALUE << MISA_MXL_SHIFT) | MISA_EXT_S_MASK | MISA_EXT_U_MASK | MISA_EXT_I_MASK |
         MISA_EXT_M_MASK | MISA_EXT_A_MASK | MISA_EXT_F_MASK | MISA_EXT_D_MASK |
-        MISA_EXT_C_MASK,                 ///< Initial value for misa
-    MIE_INIT = UINT64_C(0),              ///< Initial value for mie
-    MIP_INIT = UINT64_C(0),              ///< Initial value for mip
-    MEDELEG_INIT = UINT64_C(0),          ///< Initial value for medeleg
-    MIDELEG_INIT = UINT64_C(0),          ///< Initial value for mideleg
-    MCOUNTEREN_INIT = UINT64_C(0),       ///< Initial value for mcounteren
-    STVEC_INIT = UINT64_C(0),            ///< Initial value for stvec
-    SSCRATCH_INIT = UINT64_C(0),         ///< Initial value for sscratch
-    SEPC_INIT = UINT64_C(0),             ///< Initial value for sepc
-    SCAUSE_INIT = UINT64_C(0),           ///< Initial value for scause
-    STVAL_INIT = UINT64_C(0),            ///< Initial value for stval
-    SATP_INIT = UINT64_C(0),             ///< Initial value for satp
-    SCOUNTEREN_INIT = UINT64_C(0),       ///< Initial value for scounteren
-    ILRSC_INIT = UINT64_C(-1),           ///< Initial value for ilrsc
-    IPRV_INIT = PRV_M,                   ///< Initial value for iprv
-    IFLAGS_X_INIT = UINT64_C(0),         ///< Initial value for iflags_X
-    IFLAGS_Y_INIT = UINT64_C(0),         ///< Initial value for iflags_Y
-    IFLAGS_H_INIT = UINT64_C(0),         ///< Initial value for iflags_H
-    IUNREP_INIT = UINT64_C(0),           ///< Initial value for iunrep
-    MTIMECMP_INIT = UINT64_C(0),         ///< Initial value for mtimecmp
-    GIRQPEND_INIT = UINT64_C(0),         ///< Initial value for girqpend
-    GIRQSRVD_INIT = UINT64_C(0),         ///< Initial value for girqsrvd
-    FROMHOST_INIT = UINT64_C(0),         ///< Initial value for fromhost
-    TOHOST_INIT = UINT64_C(0),           ///< Initial value for tohost
-    MENVCFG_INIT = UINT64_C(0),          ///< Initial value for menvcfg
-    SENVCFG_INIT = UINT64_C(0),          ///< Initial value for senvcfg
-    UARCH_HALT_FLAG_INIT = UINT64_C(0),  ///< Initial value for microarchitecture halt flag
-    UARCH_X_INIT = UINT64_C(0),          ///< Initial value for microarchitecture general purpose register x
-    UARCH_PC_INIT = PMA_UARCH_RAM_START, ///< Initial value for microarchitecture pc
-    UARCH_CYCLE_INIT = UINT64_C(0),      ///< Initial value for microarchitecture cycle
-    MHARTID_INIT = UINT64_C(0),          ///< Initial mhartid
-    FDTADDR_INIT = PMA_DTB_START,        ///< Initial FDT address
+        MISA_EXT_C_MASK,                ///< Initial value for misa
+    MIE_INIT = UINT64_C(0),             ///< Initial value for mie
+    MIP_INIT = UINT64_C(0),             ///< Initial value for mip
+    MEDELEG_INIT = UINT64_C(0),         ///< Initial value for medeleg
+    MIDELEG_INIT = UINT64_C(0),         ///< Initial value for mideleg
+    MCOUNTEREN_INIT = UINT64_C(0),      ///< Initial value for mcounteren
+    STVEC_INIT = UINT64_C(0),           ///< Initial value for stvec
+    SSCRATCH_INIT = UINT64_C(0),        ///< Initial value for sscratch
+    SEPC_INIT = UINT64_C(0),            ///< Initial value for sepc
+    SCAUSE_INIT = UINT64_C(0),          ///< Initial value for scause
+    STVAL_INIT = UINT64_C(0),           ///< Initial value for stval
+    SATP_INIT = UINT64_C(0),            ///< Initial value for satp
+    SCOUNTEREN_INIT = UINT64_C(0),      ///< Initial value for scounteren
+    ILRSC_INIT = UINT64_C(-1),          ///< Initial value for ilrsc
+    IPRV_INIT = PRV_M,                  ///< Initial value for iprv
+    IFLAGS_X_INIT = UINT64_C(0),        ///< Initial value for iflags_X
+    IFLAGS_Y_INIT = UINT64_C(0),        ///< Initial value for iflags_Y
+    IFLAGS_H_INIT = UINT64_C(0),        ///< Initial value for iflags_H
+    IUNREP_INIT = UINT64_C(0),          ///< Initial value for iunrep
+    MTIMECMP_INIT = UINT64_C(0),        ///< Initial value for mtimecmp
+    GIRQPEND_INIT = UINT64_C(0),        ///< Initial value for girqpend
+    GIRQSRVD_INIT = UINT64_C(0),        ///< Initial value for girqsrvd
+    FROMHOST_INIT = UINT64_C(0),        ///< Initial value for fromhost
+    TOHOST_INIT = UINT64_C(0),          ///< Initial value for tohost
+    MENVCFG_INIT = UINT64_C(0),         ///< Initial value for menvcfg
+    SENVCFG_INIT = UINT64_C(0),         ///< Initial value for senvcfg
+    UARCH_HALT_FLAG_INIT = UINT64_C(0), ///< Initial value for microarchitecture halt flag
+    UARCH_X_INIT = UINT64_C(0),         ///< Initial value for microarchitecture general purpose register x
+    UARCH_PC_INIT = AR_UARCH_RAM_START, ///< Initial value for microarchitecture pc
+    UARCH_CYCLE_INIT = UINT64_C(0),     ///< Initial value for microarchitecture cycle
+    MHARTID_INIT = UINT64_C(0),         ///< Initial mhartid
+    FDTADDR_INIT = AR_DTB_START,        ///< Initial FDT address
 
     // Registers
     REG_X0 = UINT64_C(0), //< zero - hardwired zero
diff --git a/src/send-cmio-response.cpp b/src/send-cmio-response.cpp
index 4e41cd401..058640687 100644
--- a/src/send-cmio-response.cpp
+++ b/src/send-cmio-response.cpp
@@ -22,7 +22,7 @@
 #include "send-cmio-response.h"
 
 #include "machine-merkle-tree.h"
-#include "pma-constants.h"
+#include "pmas-constants.h"
 #include "record-send-cmio-state-access.h"
 #include "replay-send-cmio-state-access.h"
 #include "state-access.h"
@@ -45,10 +45,10 @@ void send_cmio_response(STATE_ACCESS a, uint16 reason, bytes data, uint32 dataLe
         if (uint32ShiftLeft(1, writeLengthLog2Size) < dataLength) {
             writeLengthLog2Size += 1;
         }
-        if (writeLengthLog2Size > PMA_CMIO_RX_BUFFER_LOG2_SIZE) {
+        if (writeLengthLog2Size > AR_CMIO_RX_BUFFER_LOG2_SIZE) {
             throwRuntimeError(a, "CMIO response data is too large");
         }
-        writeMemoryWithPadding(a, PMA_CMIO_RX_BUFFER_START, data, dataLength, writeLengthLog2Size);
+        writeMemoryWithPadding(a, AR_CMIO_RX_BUFFER_START, data, dataLength, writeLengthLog2Size);
     }
     // Write data length and reason to fromhost
     const uint64 mask16 = uint64ShiftLeft(1, 16) - 1;
diff --git a/src/shadow-state-address-range.h b/src/shadow-state-address-range.h
index 59b350601..45023bb42 100644
--- a/src/shadow-state-address-range.h
+++ b/src/shadow-state-address-range.h
@@ -30,7 +30,7 @@ namespace cartesi {
 
 class shadow_state_address_range final : public address_range {
 
-    static constexpr pma_flags m_shadow_state_flags{
+    static constexpr pmas_flags m_shadow_state_flags{
         .M = false,
         .IO = true,
         .E = false,
diff --git a/src/shadow-state.h b/src/shadow-state.h
index 73766cde8..57ebad79c 100644
--- a/src/shadow-state.h
+++ b/src/shadow-state.h
@@ -22,7 +22,7 @@
 
 #include "address-range.h"
 #include "compiler-defines.h"
-#include "pma-constants.h"
+#include "pmas-constants.h"
 #include "riscv-constants.h"
 
 /// \file
@@ -79,117 +79,117 @@ struct PACKED shadow_state {
 };
 
 enum class shadow_state_what : uint64_t {
-    x0 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[0]),
-    x1 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[1]),
-    x2 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[2]),
-    x3 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[3]),
-    x4 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[4]),
-    x5 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[5]),
-    x6 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[6]),
-    x7 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[7]),
-    x8 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[8]),
-    x9 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[9]),
-    x10 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[10]),
-    x11 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[11]),
-    x12 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[12]),
-    x13 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[13]),
-    x14 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[14]),
-    x15 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[15]),
-    x16 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[16]),
-    x17 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[17]),
-    x18 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[18]),
-    x19 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[19]),
-    x20 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[20]),
-    x21 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[21]),
-    x22 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[22]),
-    x23 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[23]),
-    x24 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[24]),
-    x25 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[25]),
-    x26 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[26]),
-    x27 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[27]),
-    x28 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[28]),
-    x29 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[29]),
-    x30 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[30]),
-    x31 = PMA_SHADOW_STATE_START + offsetof(shadow_state, x[31]),
-    f0 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[0]),
-    f1 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[1]),
-    f2 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[2]),
-    f3 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[3]),
-    f4 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[4]),
-    f5 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[5]),
-    f6 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[6]),
-    f7 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[7]),
-    f8 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[8]),
-    f9 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[9]),
-    f10 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[10]),
-    f11 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[11]),
-    f12 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[12]),
-    f13 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[13]),
-    f14 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[14]),
-    f15 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[15]),
-    f16 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[16]),
-    f17 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[17]),
-    f18 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[18]),
-    f19 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[19]),
-    f20 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[20]),
-    f21 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[21]),
-    f22 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[22]),
-    f23 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[23]),
-    f24 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[24]),
-    f25 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[25]),
-    f26 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[26]),
-    f27 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[27]),
-    f28 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[28]),
-    f29 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[29]),
-    f30 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[30]),
-    f31 = PMA_SHADOW_STATE_START + offsetof(shadow_state, f[31]),
-    pc = PMA_SHADOW_STATE_START + offsetof(shadow_state, pc),
-    fcsr = PMA_SHADOW_STATE_START + offsetof(shadow_state, fcsr),
-    mvendorid = PMA_SHADOW_STATE_START + offsetof(shadow_state, mvendorid),
-    marchid = PMA_SHADOW_STATE_START + offsetof(shadow_state, marchid),
-    mimpid = PMA_SHADOW_STATE_START + offsetof(shadow_state, mimpid),
-    mcycle = PMA_SHADOW_STATE_START + offsetof(shadow_state, mcycle),
-    icycleinstret = PMA_SHADOW_STATE_START + offsetof(shadow_state, icycleinstret),
-    mstatus = PMA_SHADOW_STATE_START + offsetof(shadow_state, mstatus),
-    mtvec = PMA_SHADOW_STATE_START + offsetof(shadow_state, mtvec),
-    mscratch = PMA_SHADOW_STATE_START + offsetof(shadow_state, mscratch),
-    mepc = PMA_SHADOW_STATE_START + offsetof(shadow_state, mepc),
-    mcause = PMA_SHADOW_STATE_START + offsetof(shadow_state, mcause),
-    mtval = PMA_SHADOW_STATE_START + offsetof(shadow_state, mtval),
-    misa = PMA_SHADOW_STATE_START + offsetof(shadow_state, misa),
-    mie = PMA_SHADOW_STATE_START + offsetof(shadow_state, mie),
-    mip = PMA_SHADOW_STATE_START + offsetof(shadow_state, mip),
-    medeleg = PMA_SHADOW_STATE_START + offsetof(shadow_state, medeleg),
-    mideleg = PMA_SHADOW_STATE_START + offsetof(shadow_state, mideleg),
-    mcounteren = PMA_SHADOW_STATE_START + offsetof(shadow_state, mcounteren),
-    menvcfg = PMA_SHADOW_STATE_START + offsetof(shadow_state, menvcfg),
-    stvec = PMA_SHADOW_STATE_START + offsetof(shadow_state, stvec),
-    sscratch = PMA_SHADOW_STATE_START + offsetof(shadow_state, sscratch),
-    sepc = PMA_SHADOW_STATE_START + offsetof(shadow_state, sepc),
-    scause = PMA_SHADOW_STATE_START + offsetof(shadow_state, scause),
-    stval = PMA_SHADOW_STATE_START + offsetof(shadow_state, stval),
-    satp = PMA_SHADOW_STATE_START + offsetof(shadow_state, satp),
-    scounteren = PMA_SHADOW_STATE_START + offsetof(shadow_state, scounteren),
-    senvcfg = PMA_SHADOW_STATE_START + offsetof(shadow_state, senvcfg),
-    ilrsc = PMA_SHADOW_STATE_START + offsetof(shadow_state, ilrsc),
-    iprv = PMA_SHADOW_STATE_START + offsetof(shadow_state, iprv),
-    iflags_X = PMA_SHADOW_STATE_START + offsetof(shadow_state, iflags_X),
-    iflags_Y = PMA_SHADOW_STATE_START + offsetof(shadow_state, iflags_Y),
-    iflags_H = PMA_SHADOW_STATE_START + offsetof(shadow_state, iflags_H),
-    iunrep = PMA_SHADOW_STATE_START + offsetof(shadow_state, iunrep),
-    clint_mtimecmp = PMA_SHADOW_STATE_START + offsetof(shadow_state, clint_mtimecmp),
-    plic_girqpend = PMA_SHADOW_STATE_START + offsetof(shadow_state, plic_girqpend),
-    plic_girqsrvd = PMA_SHADOW_STATE_START + offsetof(shadow_state, plic_girqsrvd),
-    htif_tohost = PMA_SHADOW_STATE_START + offsetof(shadow_state, htif_tohost),
-    htif_fromhost = PMA_SHADOW_STATE_START + offsetof(shadow_state, htif_fromhost),
-    htif_ihalt = PMA_SHADOW_STATE_START + offsetof(shadow_state, htif_ihalt),
-    htif_iconsole = PMA_SHADOW_STATE_START + offsetof(shadow_state, htif_iconsole),
-    htif_iyield = PMA_SHADOW_STATE_START + offsetof(shadow_state, htif_iyield),
+    x0 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[0]),
+    x1 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[1]),
+    x2 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[2]),
+    x3 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[3]),
+    x4 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[4]),
+    x5 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[5]),
+    x6 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[6]),
+    x7 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[7]),
+    x8 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[8]),
+    x9 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[9]),
+    x10 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[10]),
+    x11 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[11]),
+    x12 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[12]),
+    x13 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[13]),
+    x14 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[14]),
+    x15 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[15]),
+    x16 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[16]),
+    x17 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[17]),
+    x18 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[18]),
+    x19 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[19]),
+    x20 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[20]),
+    x21 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[21]),
+    x22 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[22]),
+    x23 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[23]),
+    x24 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[24]),
+    x25 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[25]),
+    x26 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[26]),
+    x27 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[27]),
+    x28 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[28]),
+    x29 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[29]),
+    x30 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[30]),
+    x31 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[31]),
+    f0 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[0]),
+    f1 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[1]),
+    f2 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[2]),
+    f3 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[3]),
+    f4 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[4]),
+    f5 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[5]),
+    f6 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[6]),
+    f7 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[7]),
+    f8 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[8]),
+    f9 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[9]),
+    f10 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[10]),
+    f11 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[11]),
+    f12 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[12]),
+    f13 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[13]),
+    f14 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[14]),
+    f15 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[15]),
+    f16 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[16]),
+    f17 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[17]),
+    f18 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[18]),
+    f19 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[19]),
+    f20 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[20]),
+    f21 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[21]),
+    f22 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[22]),
+    f23 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[23]),
+    f24 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[24]),
+    f25 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[25]),
+    f26 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[26]),
+    f27 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[27]),
+    f28 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[28]),
+    f29 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[29]),
+    f30 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[30]),
+    f31 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[31]),
+    pc = AR_SHADOW_STATE_START + offsetof(shadow_state, pc),
+    fcsr = AR_SHADOW_STATE_START + offsetof(shadow_state, fcsr),
+    mvendorid = AR_SHADOW_STATE_START + offsetof(shadow_state, mvendorid),
+    marchid = AR_SHADOW_STATE_START + offsetof(shadow_state, marchid),
+    mimpid = AR_SHADOW_STATE_START + offsetof(shadow_state, mimpid),
+    mcycle = AR_SHADOW_STATE_START + offsetof(shadow_state, mcycle),
+    icycleinstret = AR_SHADOW_STATE_START + offsetof(shadow_state, icycleinstret),
+    mstatus = AR_SHADOW_STATE_START + offsetof(shadow_state, mstatus),
+    mtvec = AR_SHADOW_STATE_START + offsetof(shadow_state, mtvec),
+    mscratch = AR_SHADOW_STATE_START + offsetof(shadow_state, mscratch),
+    mepc = AR_SHADOW_STATE_START + offsetof(shadow_state, mepc),
+    mcause = AR_SHADOW_STATE_START + offsetof(shadow_state, mcause),
+    mtval = AR_SHADOW_STATE_START + offsetof(shadow_state, mtval),
+    misa = AR_SHADOW_STATE_START + offsetof(shadow_state, misa),
+    mie = AR_SHADOW_STATE_START + offsetof(shadow_state, mie),
+    mip = AR_SHADOW_STATE_START + offsetof(shadow_state, mip),
+    medeleg = AR_SHADOW_STATE_START + offsetof(shadow_state, medeleg),
+    mideleg = AR_SHADOW_STATE_START + offsetof(shadow_state, mideleg),
+    mcounteren = AR_SHADOW_STATE_START + offsetof(shadow_state, mcounteren),
+    menvcfg = AR_SHADOW_STATE_START + offsetof(shadow_state, menvcfg),
+    stvec = AR_SHADOW_STATE_START + offsetof(shadow_state, stvec),
+    sscratch = AR_SHADOW_STATE_START + offsetof(shadow_state, sscratch),
+    sepc = AR_SHADOW_STATE_START + offsetof(shadow_state, sepc),
+    scause = AR_SHADOW_STATE_START + offsetof(shadow_state, scause),
+    stval = AR_SHADOW_STATE_START + offsetof(shadow_state, stval),
+    satp = AR_SHADOW_STATE_START + offsetof(shadow_state, satp),
+    scounteren = AR_SHADOW_STATE_START + offsetof(shadow_state, scounteren),
+    senvcfg = AR_SHADOW_STATE_START + offsetof(shadow_state, senvcfg),
+    ilrsc = AR_SHADOW_STATE_START + offsetof(shadow_state, ilrsc),
+    iprv = AR_SHADOW_STATE_START + offsetof(shadow_state, iprv),
+    iflags_X = AR_SHADOW_STATE_START + offsetof(shadow_state, iflags_X),
+    iflags_Y = AR_SHADOW_STATE_START + offsetof(shadow_state, iflags_Y),
+    iflags_H = AR_SHADOW_STATE_START + offsetof(shadow_state, iflags_H),
+    iunrep = AR_SHADOW_STATE_START + offsetof(shadow_state, iunrep),
+    clint_mtimecmp = AR_SHADOW_STATE_START + offsetof(shadow_state, clint_mtimecmp),
+    plic_girqpend = AR_SHADOW_STATE_START + offsetof(shadow_state, plic_girqpend),
+    plic_girqsrvd = AR_SHADOW_STATE_START + offsetof(shadow_state, plic_girqsrvd),
+    htif_tohost = AR_SHADOW_STATE_START + offsetof(shadow_state, htif_tohost),
+    htif_fromhost = AR_SHADOW_STATE_START + offsetof(shadow_state, htif_fromhost),
+    htif_ihalt = AR_SHADOW_STATE_START + offsetof(shadow_state, htif_ihalt),
+    htif_iconsole = AR_SHADOW_STATE_START + offsetof(shadow_state, htif_iconsole),
+    htif_iyield = AR_SHADOW_STATE_START + offsetof(shadow_state, htif_iyield),
     unknown_ = UINT64_C(1) << 63, // Outside of RISC-V address space
 };
 
 static constexpr shadow_state_what shadow_state_get_what(uint64_t paddr) {
-    if (paddr < PMA_SHADOW_STATE_START || paddr - PMA_SHADOW_STATE_START >= sizeof(shadow_state) ||
+    if (paddr < AR_SHADOW_STATE_START || paddr - AR_SHADOW_STATE_START >= sizeof(shadow_state) ||
         (paddr & (sizeof(uint64_t) - 1)) != 0) {
         return shadow_state_what::unknown_;
     }
@@ -203,7 +203,7 @@ static constexpr shadow_state_what shadow_state_get_what(shadow_state_what what,
 
 static constexpr const char *shadow_state_get_what_name(shadow_state_what what) {
     const auto paddr = static_cast<uint64_t>(what);
-    if (paddr < PMA_SHADOW_STATE_START || paddr - PMA_SHADOW_STATE_START >= sizeof(shadow_state) ||
+    if (paddr < AR_SHADOW_STATE_START || paddr - AR_SHADOW_STATE_START >= sizeof(shadow_state) ||
         (paddr & (sizeof(uint64_t) - 1)) != 0) {
         return "state.unknown_";
     }
diff --git a/src/shadow-tlb-address-range.h b/src/shadow-tlb-address-range.h
index 1956ba99b..7067e94fe 100644
--- a/src/shadow-tlb-address-range.h
+++ b/src/shadow-tlb-address-range.h
@@ -30,7 +30,7 @@ namespace cartesi {
 
 class shadow_tlb_address_range final : public address_range {
 
-    static constexpr pma_flags m_shadow_tlb_flags{
+    static constexpr pmas_flags m_shadow_tlb_flags{
         .M = false,
         .IO = true,
         .E = false,
diff --git a/src/shadow-tlb-factory.h b/src/shadow-tlb-factory.h
index b372d7a67..635b63d3e 100644
--- a/src/shadow-tlb-factory.h
+++ b/src/shadow-tlb-factory.h
@@ -28,7 +28,7 @@ namespace cartesi {
 /// \param start Start address for memory range.
 /// \param length Length of memory range.
 /// \returns Corresponding PMA entry
-pma_entry make_shadow_tlb_pma_entry(uint64_t start, uint64_t length);
+pmas_entry make_shadow_tlb_pmas_entry(uint64_t start, uint64_t length);
 
 } // namespace cartesi
 
diff --git a/src/shadow-tlb.h b/src/shadow-tlb.h
index c7b6df025..f6e9bfeee 100644
--- a/src/shadow-tlb.h
+++ b/src/shadow-tlb.h
@@ -58,7 +58,7 @@ using shadow_tlb_set = std::array<shadow_tlb_slot, TLB_SET_SIZE>;
 /// \brief Shadow TLB memory layout
 using shadow_tlb_state = std::array<shadow_tlb_set, TLB_LAST_ + 1>; // one set for code, one for read and one for write
 
-static_assert(PMA_SHADOW_TLB_LENGTH >= sizeof(shadow_tlb_state), "TLB state must fit in TLB shadow");
+static_assert(AR_SHADOW_TLB_LENGTH >= sizeof(shadow_tlb_state), "TLB state must fit in TLB shadow");
 
 /// \brief List of field types
 enum class shadow_tlb_what : uint64_t {
@@ -70,7 +70,7 @@ enum class shadow_tlb_what : uint64_t {
 };
 
 static constexpr uint64_t shadow_tlb_get_abs_addr(TLB_set_index set_index, uint64_t slot_index) {
-    return PMA_SHADOW_TLB_START + (set_index * sizeof(shadow_tlb_set)) + (slot_index * sizeof(shadow_tlb_slot));
+    return AR_SHADOW_TLB_START + (set_index * sizeof(shadow_tlb_set)) + (slot_index * sizeof(shadow_tlb_slot));
 }
 
 static constexpr uint64_t shadow_tlb_get_abs_addr(TLB_set_index set_index, uint64_t slot_index, shadow_tlb_what what) {
@@ -78,11 +78,11 @@ static constexpr uint64_t shadow_tlb_get_abs_addr(TLB_set_index set_index, uint6
 }
 
 static constexpr shadow_tlb_what shadow_tlb_get_what(uint64_t paddr, TLB_set_index &set_index, uint64_t &slot_index) {
-    if (paddr < PMA_SHADOW_TLB_START || paddr - PMA_SHADOW_TLB_START >= sizeof(shadow_tlb_state) ||
+    if (paddr < AR_SHADOW_TLB_START || paddr - AR_SHADOW_TLB_START >= sizeof(shadow_tlb_state) ||
         (paddr & (sizeof(uint64_t) - 1)) != 0) {
         return shadow_tlb_what::unknown_;
     }
-    paddr -= PMA_SHADOW_TLB_START;
+    paddr -= AR_SHADOW_TLB_START;
     set_index = TLB_set_index{paddr / sizeof(shadow_tlb_set)};
     slot_index = (paddr % sizeof(shadow_tlb_set)) / sizeof(shadow_tlb_slot);
     return shadow_tlb_what{paddr % sizeof(shadow_tlb_slot)};
diff --git a/src/shadow-uarch-state-address-range.cpp b/src/shadow-uarch-state-address-range.cpp
index b4d19b54c..61dfdf649 100644
--- a/src/shadow-uarch-state-address-range.cpp
+++ b/src/shadow-uarch-state-address-range.cpp
@@ -20,13 +20,13 @@
 
 #include "machine-reg.h"
 #include "machine.h"
-#include "pma-constants.h"
+#include "pmas-constants.h"
 #include "shadow-peek.h"
 #include "shadow-uarch-state.h"
 
 namespace cartesi {
 
-/// \brief Shadow uarch state device peek callback. See ::pma_peek.
+/// \brief Shadow uarch state device peek callback. See ::pmas_peek.
 bool shadow_uarch_state_address_range::do_peek(const machine &m, uint64_t offset, uint64_t length,
     const unsigned char **data, unsigned char *scratch) const noexcept {
     // If past useful range
diff --git a/src/shadow-uarch-state-address-range.h b/src/shadow-uarch-state-address-range.h
index f9b286111..cc2972f5b 100644
--- a/src/shadow-uarch-state-address-range.h
+++ b/src/shadow-uarch-state-address-range.h
@@ -30,7 +30,7 @@ namespace cartesi {
 
 class shadow_uarch_state_address_range final : public address_range {
 
-    static constexpr pma_flags m_shadow_uarch_state_flags{
+    static constexpr pmas_flags m_shadow_uarch_state_flags{
         .M = false,
         .IO = true,
         .E = false,
diff --git a/src/shadow-uarch-state.h b/src/shadow-uarch-state.h
index a5ff6d92e..ded6e0201 100644
--- a/src/shadow-uarch-state.h
+++ b/src/shadow-uarch-state.h
@@ -37,46 +37,46 @@ struct PACKED shadow_uarch_state {
 };
 
 enum class shadow_uarch_state_what : uint64_t {
-    uarch_halt_flag = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, halt_flag),
-    uarch_cycle = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, cycle),
-    uarch_pc = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, pc),
-    uarch_x0 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[0]),
-    uarch_x1 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[1]),
-    uarch_x2 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[2]),
-    uarch_x3 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[3]),
-    uarch_x4 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[4]),
-    uarch_x5 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[5]),
-    uarch_x6 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[6]),
-    uarch_x7 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[7]),
-    uarch_x8 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[8]),
-    uarch_x9 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[9]),
-    uarch_x10 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[10]),
-    uarch_x11 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[11]),
-    uarch_x12 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[12]),
-    uarch_x13 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[13]),
-    uarch_x14 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[14]),
-    uarch_x15 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[15]),
-    uarch_x16 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[16]),
-    uarch_x17 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[17]),
-    uarch_x18 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[18]),
-    uarch_x19 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[19]),
-    uarch_x20 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[20]),
-    uarch_x21 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[21]),
-    uarch_x22 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[22]),
-    uarch_x23 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[23]),
-    uarch_x24 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[24]),
-    uarch_x25 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[25]),
-    uarch_x26 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[26]),
-    uarch_x27 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[27]),
-    uarch_x28 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[28]),
-    uarch_x29 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[29]),
-    uarch_x30 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[30]),
-    uarch_x31 = PMA_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[31]),
+    uarch_halt_flag = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, halt_flag),
+    uarch_cycle = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, cycle),
+    uarch_pc = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, pc),
+    uarch_x0 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[0]),
+    uarch_x1 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[1]),
+    uarch_x2 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[2]),
+    uarch_x3 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[3]),
+    uarch_x4 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[4]),
+    uarch_x5 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[5]),
+    uarch_x6 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[6]),
+    uarch_x7 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[7]),
+    uarch_x8 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[8]),
+    uarch_x9 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[9]),
+    uarch_x10 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[10]),
+    uarch_x11 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[11]),
+    uarch_x12 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[12]),
+    uarch_x13 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[13]),
+    uarch_x14 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[14]),
+    uarch_x15 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[15]),
+    uarch_x16 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[16]),
+    uarch_x17 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[17]),
+    uarch_x18 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[18]),
+    uarch_x19 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[19]),
+    uarch_x20 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[20]),
+    uarch_x21 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[21]),
+    uarch_x22 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[22]),
+    uarch_x23 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[23]),
+    uarch_x24 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[24]),
+    uarch_x25 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[25]),
+    uarch_x26 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[26]),
+    uarch_x27 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[27]),
+    uarch_x28 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[28]),
+    uarch_x29 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[29]),
+    uarch_x30 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[30]),
+    uarch_x31 = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, x[31]),
     unknown_ = UINT64_C(1) << 63, // Outside of RISC-V address space
 };
 
 static constexpr shadow_uarch_state_what shadow_uarch_state_get_what(uint64_t paddr) {
-    if (paddr < PMA_SHADOW_UARCH_STATE_START || paddr - PMA_SHADOW_UARCH_STATE_START >= sizeof(shadow_uarch_state) ||
+    if (paddr < AR_SHADOW_UARCH_STATE_START || paddr - AR_SHADOW_UARCH_STATE_START >= sizeof(shadow_uarch_state) ||
         (paddr & (sizeof(uint64_t) - 1)) != 0) {
         return shadow_uarch_state_what::unknown_;
     }
@@ -90,7 +90,7 @@ static constexpr shadow_uarch_state_what shadow_uarch_state_get_what(shadow_uarc
 
 static constexpr const char *shadow_uarch_state_get_what_name(shadow_uarch_state_what what) {
     const auto paddr = static_cast<uint64_t>(what);
-    if (paddr < PMA_SHADOW_UARCH_STATE_START || paddr - PMA_SHADOW_UARCH_STATE_START >= sizeof(shadow_uarch_state) ||
+    if (paddr < AR_SHADOW_UARCH_STATE_START || paddr - AR_SHADOW_UARCH_STATE_START >= sizeof(shadow_uarch_state) ||
         (paddr & (sizeof(uint64_t) - 1)) != 0) {
         return "uarch.unknown_";
     }
diff --git a/src/state-access.h b/src/state-access.h
index 86c4c883f..6f079853a 100644
--- a/src/state-access.h
+++ b/src/state-access.h
@@ -36,7 +36,7 @@
 #include "machine-state.h"
 #include "machine.h"
 #include "os.h"
-#include "pma-constants.h"
+#include "pmas-constants.h"
 #include "riscv-constants.h"
 #include "shadow-tlb.h"
 #include "strict-aliasing.h"
diff --git a/src/tlb.h b/src/tlb.h
index 0383e7da1..f78905b1d 100644
--- a/src/tlb.h
+++ b/src/tlb.h
@@ -26,7 +26,7 @@
 #include <cstdint>
 
 #include "host-addr.h"
-#include "pma-constants.h"
+#include "pmas-constants.h"
 #include "riscv-constants.h"
 
 namespace cartesi {
diff --git a/src/translate-virtual-address.h b/src/translate-virtual-address.h
index 3d8b536f4..73b11d0bb 100644
--- a/src/translate-virtual-address.h
+++ b/src/translate-virtual-address.h
@@ -46,7 +46,7 @@
 #include <cstdint>
 
 #include "compiler-defines.h"
-#include "find-pma-entry.h"
+#include "find-pmas-entry.h"
 #include "riscv-constants.h"
 
 namespace cartesi {
diff --git a/src/uarch-constants.h b/src/uarch-constants.h
index da52db2e2..6930cc527 100644
--- a/src/uarch-constants.h
+++ b/src/uarch-constants.h
@@ -17,8 +17,7 @@
 #ifndef UARCH_CONSTANTS_H
 #define UARCH_CONSTANTS_H
 
-#include "pma-constants.h"
-#include "pma-defines.h"
+#include "address-range-constants.h"
 #include "uarch-defines.h"
 
 #include <cstdint>
@@ -32,10 +31,10 @@ enum uarch_state_constants : uint64_t {
     UARCH_STATE_LOG2_SIZE = EXPAND_UINT64_C(UARCH_STATE_LOG2_SIZE_DEF), ///< Log2 size of the uarch state: shadow + ram
     UARCH_STATE_CHILD_LOG2_SIZE = UARCH_STATE_LOG2_SIZE - 1, ///< Log2 size of a uarch state child: shadow or ram
     UARCH_SHADOW_START_ADDRESS =
-        EXPAND_UINT64_C(PMA_SHADOW_UARCH_STATE_START_DEF), ///< Start address of the shadow uarch state
-    UARCH_SHADOW_LENGTH = EXPAND_UINT64_C(PMA_SHADOW_UARCH_STATE_LENGTH_DEF),   ///< Length of the shadow uarch state
-    UARCH_RAM_START_ADDRESS = EXPAND_UINT64_C(PMA_UARCH_RAM_START_DEF),         ///< Start address of the uarch ram
-    UARCH_RAM_LENGTH = EXPAND_UINT64_C(PMA_UARCH_RAM_LENGTH_DEF),               ///< Length of the uarch ram
+        EXPAND_UINT64_C(AR_SHADOW_UARCH_STATE_START_DEF), ///< Start address of the shadow uarch state
+    UARCH_SHADOW_LENGTH = EXPAND_UINT64_C(AR_SHADOW_UARCH_STATE_LENGTH_DEF),    ///< Length of the shadow uarch state
+    UARCH_RAM_START_ADDRESS = EXPAND_UINT64_C(AR_UARCH_RAM_START_DEF),          ///< Start address of the uarch ram
+    UARCH_RAM_LENGTH = EXPAND_UINT64_C(AR_UARCH_RAM_LENGTH_DEF),                ///< Length of the uarch ram
     UARCH_STATE_ALIGN_MASK = (EXPAND_UINT64_C(1) << UARCH_STATE_LOG2_SIZE) - 1, ///< Mask for uarch state alignment
     UARCH_STATE_MASK = ~UARCH_STATE_ALIGN_MASK,                                 ///< Mask for uarch state address space
     UARCH_STATE_CHILD_ALIGN_MASK =
@@ -58,9 +57,8 @@ static_assert(UARCH_SHADOW_LENGTH <= (static_cast<uint64_t>(1) << UARCH_STATE_CH
     "UARCH_SHADOW_LENGTH is too big");
 static_assert(UARCH_SHADOW_START_ADDRESS < UARCH_RAM_START_ADDRESS,
     "UARCH_SHADOW_START_ADDRESS must be smaller than UARCH_RAN_START_ADDRESS");
-static_assert((UARCH_SHADOW_LENGTH & (PMA_PAGE_SIZE - 1)) == 0,
-    "UARCH_SHADOW_LENGTH must be multiple of PMA_PAGE_SIZE");
-static_assert((UARCH_RAM_LENGTH & (PMA_PAGE_SIZE - 1)) == 0, "UARCH_RAM_LENGTH must be multiple of PMA_PAGE_SIZE");
+static_assert((UARCH_SHADOW_LENGTH & (AR_PAGE_SIZE - 1)) == 0, "UARCH_SHADOW_LENGTH must be multiple of AR_PAGE_SIZE");
+static_assert((UARCH_RAM_LENGTH & (AR_PAGE_SIZE - 1)) == 0, "UARCH_RAM_LENGTH must be multiple of AR_PAGE_SIZE");
 
 /// \brief ecall function codes
 enum uarch_ecall_functions : uint64_t {
diff --git a/src/uarch-defines.h b/src/uarch-defines.h
index c5d3abb8b..db2aabac4 100644
--- a/src/uarch-defines.h
+++ b/src/uarch-defines.h
@@ -17,10 +17,10 @@
 #ifndef UARCH_DEFINES_H
 #define UARCH_DEFINES_H
 
-#include "pma-defines.h"
+#include "address-range-defines.h"
 // NOLINTBEGIN(cppcoreguidelines-macro-usage,cppcoreguidelines-macro-to-enum,modernize-macro-to-enum)
 /// \brief Start address of the entire uarch memory range: shadow and ram
-#define UARCH_STATE_START_ADDRESS_DEF PMA_SHADOW_UARCH_STATE_START_DEF
+#define UARCH_STATE_START_ADDRESS_DEF AR_SHADOW_UARCH_STATE_START_DEF
 
 /// \brief Log2 size of the entire uarch memory range: shadow and ram
 #define UARCH_STATE_LOG2_SIZE_DEF 22
diff --git a/src/uarch-replay-state-access.h b/src/uarch-replay-state-access.h
index 070f871e1..b651b3170 100644
--- a/src/uarch-replay-state-access.h
+++ b/src/uarch-replay-state-access.h
@@ -344,7 +344,8 @@ class uarch_replay_state_access :
     }
 
     void do_reset_uarch() const {
-        check_write_access(UARCH_STATE_START_ADDRESS, UARCH_STATE_LOG2_SIZE, uarch_pristine_state_hash, "uarch.state");
+        check_write_access(UARCH_STATE_START_ADDRESS, UARCH_STATE_LOG2_SIZE, get_uarch_pristine_state_hash(),
+            "uarch.state");
     }
 
     void do_write_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset,
@@ -357,7 +358,6 @@ class uarch_replay_state_access :
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
     constexpr const char *do_get_name() const {
         return "uarch_replay_state_access";
->>>>>>> 1e5dc22 (refactor: clean up uarch state access mechanism)
     }
 
     // -----
diff --git a/src/virtio-address-range.cpp b/src/virtio-address-range.cpp
index 92dbf0fc9..25e196889 100644
--- a/src/virtio-address-range.cpp
+++ b/src/virtio-address-range.cpp
@@ -827,7 +827,7 @@ bool virtio_address_range::do_read_device(i_device_state_access *a, uint64_t off
     return status;
 }
 
-/// \brief VirtIO device read callback. See ::pma_write.
+/// \brief VirtIO device read callback. See ::pmas_write.
 execute_status virtio_address_range::do_write_device(i_device_state_access *a, uint64_t offset, int log2_size,
     uint64_t val) noexcept {
 #ifdef DEBUG_VIRTIO_MMIO
diff --git a/src/virtio-address-range.h b/src/virtio-address-range.h
index 4e45c0159..337f3b784 100644
--- a/src/virtio-address-range.h
+++ b/src/virtio-address-range.h
@@ -257,7 +257,7 @@ class virtio_address_range : public pristine_address_range {
     uint32_t config_generation = 0;   ///< Configuration generation counter
     uint32_t config_space_size = 0;   ///< Configuration size
 
-    static constexpr pma_flags m_virtio_flags{
+    static constexpr pmas_flags m_virtio_flags{
         .M = false,
         .IO = true,
         .E = false,
diff --git a/tests/lua/create-machines.lua b/tests/lua/create-machines.lua
index bf33183b5..37935b58c 100755
--- a/tests/lua/create-machines.lua
+++ b/tests/lua/create-machines.lua
@@ -213,11 +213,11 @@ rollup-init sh /home/dapp/s.sh
 )
 
 -- Should not work with shared buffers
-local ret, err = pcall(create_machine, "shared-rx-buffer-machine", "rollup accept", function(config)
+local ret = pcall(create_machine, "shared-rx-buffer-machine", "rollup accept", function(config)
     config.cmio.rx_buffer.shared = true
 end)
 assert(not ret, "should have failed")
-ret, err = pcall(create_machine, "shared-tx-buffer-machine", "rollup accept", function(config)
+ret = pcall(create_machine, "shared-tx-buffer-machine", "rollup accept", function(config)
     config.cmio.tx_buffer.shared = true
 end)
 assert(not ret, "should have failed")
diff --git a/tests/lua/htif-cmio.lua b/tests/lua/htif-cmio.lua
index 60d0ae858..935732a14 100755
--- a/tests/lua/htif-cmio.lua
+++ b/tests/lua/htif-cmio.lua
@@ -41,14 +41,14 @@ local function test(config)
     local machine <close> = cartesi.machine(config)
 
     -- fill input with `pattern`
-    local rx_length = 1 << cartesi.PMA_CMIO_RX_BUFFER_LOG2_SIZE
-    machine:write_memory(cartesi.PMA_CMIO_RX_BUFFER_START, string.rep(pattern, rx_length / 8), rx_length)
+    local rx_length = 1 << cartesi.AR_CMIO_RX_BUFFER_LOG2_SIZE
+    machine:write_memory(cartesi.AR_CMIO_RX_BUFFER_START, string.rep(pattern, rx_length / 8), rx_length)
 
     machine:run(math.maxinteger)
 
     -- check that buffers got filled in with `pattern`
-    local tx_length = 1 << cartesi.PMA_CMIO_TX_BUFFER_LOG2_SIZE
-    assert(string.rep(pattern, tx_length / 8) == machine:read_memory(cartesi.PMA_CMIO_TX_BUFFER_START, tx_length))
+    local tx_length = 1 << cartesi.AR_CMIO_TX_BUFFER_LOG2_SIZE
+    assert(string.rep(pattern, tx_length / 8) == machine:read_memory(cartesi.AR_CMIO_TX_BUFFER_START, tx_length))
 
     assert(machine:read_reg("iflags_H") ~= 0)
 
diff --git a/tests/lua/machine-bind.lua b/tests/lua/machine-bind.lua
index 58a7587de..dc020adcf 100755
--- a/tests/lua/machine-bind.lua
+++ b/tests/lua/machine-bind.lua
@@ -1141,7 +1141,7 @@ print("\n\ntesting send cmio response ")
 
 do_test("send_cmio_response fails if iflags.Y is not set", function(machine)
     local reason = 1
-    local data = string.rep("a", 1 << cartesi.PMA_CMIO_RX_BUFFER_LOG2_SIZE)
+    local data = string.rep("a", 1 << cartesi.AR_CMIO_RX_BUFFER_LOG2_SIZE)
     machine:write_reg("iflags_Y", 0)
     assert(machine:read_reg("iflags_Y") == 0)
     test_util.assert_error("iflags.Y is not set", function()
@@ -1154,7 +1154,7 @@ end)
 
 do_test("send_cmio_response fails if data is too big", function(machine)
     local reason = 1
-    local data_too_big = string.rep("a", 1 + (1 << cartesi.PMA_CMIO_RX_BUFFER_LOG2_SIZE))
+    local data_too_big = string.rep("a", 1 + (1 << cartesi.AR_CMIO_RX_BUFFER_LOG2_SIZE))
     machine:write_reg("iflags_Y", 1)
     test_util.assert_error("CMIO response data is too large", function()
         machine:send_cmio_response(reason, data_too_big)
@@ -1173,31 +1173,23 @@ local function assert_access(accesses, index, expected_key_and_values)
     end
 end
 
-local function dump_pmas(machine)
-    for _, v in ipairs(machine:get_address_ranges()) do
-        local filename = string.format("%016x--%016x.bin", v.start, v.length)
-        local file <close> = assert(io.open(filename, "w"))
-        assert(file:write(machine:read_memory(v.start, v.length)))
-    end
-end
-
 local function test_send_cmio_input_with_different_arguments()
-    local data = string.rep("a", 1 << cartesi.PMA_CMIO_RX_BUFFER_LOG2_SIZE)
+    local data = string.rep("a", 1 << cartesi.AR_CMIO_RX_BUFFER_LOG2_SIZE)
     local reason = 1
-    local max_rx_buffer_len = 1 << cartesi.PMA_CMIO_RX_BUFFER_LOG2_SIZE
-    local data_hash = test_util.merkle_hash(data, 0, cartesi.PMA_CMIO_RX_BUFFER_LOG2_SIZE)
+    local max_rx_buffer_len = 1 << cartesi.AR_CMIO_RX_BUFFER_LOG2_SIZE
+    local data_hash = test_util.merkle_hash(data, 0, cartesi.AR_CMIO_RX_BUFFER_LOG2_SIZE)
     local all_zeros = string.rep("\0", max_rx_buffer_len)
-    local all_zeros_hash = test_util.merkle_hash(all_zeros, 0, cartesi.PMA_CMIO_RX_BUFFER_LOG2_SIZE)
+    local all_zeros_hash = test_util.merkle_hash(all_zeros, 0, cartesi.AR_CMIO_RX_BUFFER_LOG2_SIZE)
     -- prepares and asserts the state before send_cmio_response is called
     local function assert_before_cmio_response_sent(machine)
         machine:write_reg("iflags_Y", 1)
         -- initial rx buffer should be all zeros
-        assert(machine:read_memory(cartesi.PMA_CMIO_RX_BUFFER_START, max_rx_buffer_len) == all_zeros)
+        assert(machine:read_memory(cartesi.AR_CMIO_RX_BUFFER_START, max_rx_buffer_len) == all_zeros)
     end
     -- asserts that the machine state is as expected after send_cmio_response is called
     local function assert_after_cmio_response_sent(machine)
         -- rx buffer should now contain the data
-        assert(machine:read_memory(cartesi.PMA_CMIO_RX_BUFFER_START, max_rx_buffer_len) == data)
+        assert(machine:read_memory(cartesi.AR_CMIO_RX_BUFFER_START, max_rx_buffer_len) == data)
         -- iflags.Y should be cleared
         assert(machine:read_reg("iflags_Y") == 0)
         -- fromhost should reflect the reason and data length
@@ -1222,7 +1214,6 @@ local function test_send_cmio_input_with_different_arguments()
                     | (large_data and cartesi.ACCESS_LOG_TYPE_LARGE_DATA or 0)
                 assert_before_cmio_response_sent(machine)
                 local root_hash_before = machine:get_root_hash()
-                dump_pmas(machine)
                 local log = machine:log_send_cmio_response(reason, data, log_type)
                 assert_after_cmio_response_sent(machine)
                 local root_hash_after = machine:get_root_hash()
@@ -1236,8 +1227,8 @@ local function test_send_cmio_input_with_different_arguments()
                 })
                 assert_access(accesses, 2, {
                     type = "write",
-                    address = cartesi.PMA_CMIO_RX_BUFFER_START,
-                    log2_size = cartesi.PMA_CMIO_RX_BUFFER_LOG2_SIZE,
+                    address = cartesi.AR_CMIO_RX_BUFFER_START,
+                    log2_size = cartesi.AR_CMIO_RX_BUFFER_LOG2_SIZE,
                     read_hash = all_zeros_hash,
                     read = large_data and all_zeros or nil,
                     written_hash = data_hash,
@@ -1295,7 +1286,7 @@ do_test("send_cmio_response with different data sizes", function(machine)
         { data_len = (1 << 20) + 1, write_len = 1 << 21 },
         { data_len = 1 << 21, write_len = 1 << 21 },
     }
-    local rx_buffer_size = 1 << cartesi.PMA_CMIO_RX_BUFFER_LOG2_SIZE
+    local rx_buffer_size = 1 << cartesi.AR_CMIO_RX_BUFFER_LOG2_SIZE
     local initial_rx_buffer = string.rep("x", rx_buffer_size)
     local reason = 1
     local function padded_data(data, len, padding)
@@ -1312,8 +1303,8 @@ do_test("send_cmio_response with different data sizes", function(machine)
                     logging
                 )
             )
-            machine:write_memory(cartesi.PMA_CMIO_RX_BUFFER_START, initial_rx_buffer)
-            assert(machine:read_memory(cartesi.PMA_CMIO_RX_BUFFER_START, rx_buffer_size) == initial_rx_buffer)
+            machine:write_memory(cartesi.AR_CMIO_RX_BUFFER_START, initial_rx_buffer)
+            assert(machine:read_memory(cartesi.AR_CMIO_RX_BUFFER_START, rx_buffer_size) == initial_rx_buffer)
             local data = string.rep("a", case.data_len)
             machine:write_reg("iflags_Y", 1)
             if logging then
@@ -1326,7 +1317,7 @@ do_test("send_cmio_response with different data sizes", function(machine)
             end
             local expected_rx_buffer = padded_data(data, case.write_len, "\0")
                 .. string.rep("x", rx_buffer_size - case.write_len)
-            local new_rx_buffer = machine:read_memory(cartesi.PMA_CMIO_RX_BUFFER_START, rx_buffer_size)
+            local new_rx_buffer = machine:read_memory(cartesi.AR_CMIO_RX_BUFFER_START, rx_buffer_size)
             assert(
                 new_rx_buffer == expected_rx_buffer,
                 string.format(
@@ -1342,15 +1333,15 @@ do_test("send_cmio_response with different data sizes", function(machine)
 end)
 
 do_test("send_cmio_response of zero bytes", function(machine)
-    local rx_buffer_size = 1 << cartesi.PMA_CMIO_RX_BUFFER_LOG2_SIZE
+    local rx_buffer_size = 1 << cartesi.AR_CMIO_RX_BUFFER_LOG2_SIZE
     local initial_rx_buffer = string.rep("x", rx_buffer_size)
-    machine:write_memory(cartesi.PMA_CMIO_RX_BUFFER_START, initial_rx_buffer)
-    assert(machine:read_memory(cartesi.PMA_CMIO_RX_BUFFER_START, rx_buffer_size) == initial_rx_buffer)
+    machine:write_memory(cartesi.AR_CMIO_RX_BUFFER_START, initial_rx_buffer)
+    assert(machine:read_memory(cartesi.AR_CMIO_RX_BUFFER_START, rx_buffer_size) == initial_rx_buffer)
     machine:write_reg("iflags_Y", 1)
     local reason = 1
     local data = ""
     machine:send_cmio_response(reason, data)
-    local new_rx_buffer = machine:read_memory(cartesi.PMA_CMIO_RX_BUFFER_START, rx_buffer_size)
+    local new_rx_buffer = machine:read_memory(cartesi.AR_CMIO_RX_BUFFER_START, rx_buffer_size)
     assert(new_rx_buffer == initial_rx_buffer, "rx_buffer should not have been modified")
     assert(machine:read_reg("iflags_Y") == 0, "iflags.Y should be cleared")
     -- log and verify
@@ -1366,8 +1357,8 @@ end)
 local function test_cmio_buffers_backed_by_files()
     local rx_filename = os.tmpname()
     local tx_filename = os.tmpname()
-    local rx_init_data = string.rep("R", 1 << cartesi.PMA_CMIO_RX_BUFFER_LOG2_SIZE)
-    local tx_init_data = string.rep("T", 1 << cartesi.PMA_CMIO_TX_BUFFER_LOG2_SIZE)
+    local rx_init_data = string.rep("R", 1 << cartesi.AR_CMIO_RX_BUFFER_LOG2_SIZE)
+    local tx_init_data = string.rep("T", 1 << cartesi.AR_CMIO_TX_BUFFER_LOG2_SIZE)
     local deleter = {}
     setmetatable(deleter, {
         __gc = function()
@@ -1382,8 +1373,8 @@ local function test_cmio_buffers_backed_by_files()
     local tx = assert(io.open(tx_filename, "w+"))
     tx:write(tx_init_data)
     tx:close()
-    local tx_new_data = string.rep("x", 1 << cartesi.PMA_CMIO_TX_BUFFER_LOG2_SIZE)
-    local rx_new_data = string.rep("y", 1 << cartesi.PMA_CMIO_RX_BUFFER_LOG2_SIZE)
+    local tx_new_data = string.rep("x", 1 << cartesi.AR_CMIO_TX_BUFFER_LOG2_SIZE)
+    local rx_new_data = string.rep("y", 1 << cartesi.AR_CMIO_RX_BUFFER_LOG2_SIZE)
 
     test_util.make_do_test(build_machine, machine_type, {
         cmio = {
@@ -1391,13 +1382,13 @@ local function test_cmio_buffers_backed_by_files()
             tx_buffer = { image_filename = tx_filename, shared = false },
         },
     })("cmio buffers initialized from backing files", function(machine)
-        local rx_data = machine:read_memory(cartesi.PMA_CMIO_RX_BUFFER_START, 1 << cartesi.PMA_CMIO_RX_BUFFER_LOG2_SIZE)
+        local rx_data = machine:read_memory(cartesi.AR_CMIO_RX_BUFFER_START, 1 << cartesi.AR_CMIO_RX_BUFFER_LOG2_SIZE)
         assert(rx_data == rx_init_data, "rx buffer data does not match")
-        local tx_data = machine:read_memory(cartesi.PMA_CMIO_TX_BUFFER_START, 1 << cartesi.PMA_CMIO_TX_BUFFER_LOG2_SIZE)
+        local tx_data = machine:read_memory(cartesi.AR_CMIO_TX_BUFFER_START, 1 << cartesi.AR_CMIO_TX_BUFFER_LOG2_SIZE)
         assert(tx_data == tx_init_data, "tx buffer data does not match")
         -- write new data to buffers to later assert that it was not written to the files
-        machine:write_memory(cartesi.PMA_CMIO_RX_BUFFER_START, rx_new_data)
-        machine:write_memory(cartesi.PMA_CMIO_TX_BUFFER_START, tx_new_data)
+        machine:write_memory(cartesi.AR_CMIO_RX_BUFFER_START, rx_new_data)
+        machine:write_memory(cartesi.AR_CMIO_TX_BUFFER_START, tx_new_data)
     end)
     -- the shared=false from last test should prevent saving the new data to files
     test_util.make_do_test(build_machine, machine_type, {
@@ -1406,13 +1397,13 @@ local function test_cmio_buffers_backed_by_files()
             tx_buffer = { image_filename = tx_filename, shared = true },
         },
     })("cmio buffers initialized from backing files should not change", function(machine)
-        local rx_data = machine:read_memory(cartesi.PMA_CMIO_RX_BUFFER_START, 1 << cartesi.PMA_CMIO_RX_BUFFER_LOG2_SIZE)
+        local rx_data = machine:read_memory(cartesi.AR_CMIO_RX_BUFFER_START, 1 << cartesi.AR_CMIO_RX_BUFFER_LOG2_SIZE)
         assert(rx_data == rx_init_data, "rx buffer data does not match")
-        local tx_data = machine:read_memory(cartesi.PMA_CMIO_TX_BUFFER_START, 1 << cartesi.PMA_CMIO_TX_BUFFER_LOG2_SIZE)
+        local tx_data = machine:read_memory(cartesi.AR_CMIO_TX_BUFFER_START, 1 << cartesi.AR_CMIO_TX_BUFFER_LOG2_SIZE)
         assert(tx_data == tx_init_data, "tx buffer data does not match")
         -- write new data to buffers to later assert that it was written to the files
-        machine:write_memory(cartesi.PMA_CMIO_RX_BUFFER_START, rx_new_data)
-        machine:write_memory(cartesi.PMA_CMIO_TX_BUFFER_START, tx_new_data)
+        machine:write_memory(cartesi.AR_CMIO_RX_BUFFER_START, rx_new_data)
+        machine:write_memory(cartesi.AR_CMIO_TX_BUFFER_START, tx_new_data)
     end)
     -- the shared=true from last test should save memory changes to files
     test_util.make_do_test(build_machine, machine_type, {
@@ -1421,9 +1412,9 @@ local function test_cmio_buffers_backed_by_files()
             tx_buffer = { image_filename = tx_filename, shared = false },
         },
     })("cmio buffer files should be modified by last write_memory", function(machine)
-        local rx_data = machine:read_memory(cartesi.PMA_CMIO_RX_BUFFER_START, 1 << cartesi.PMA_CMIO_RX_BUFFER_LOG2_SIZE)
+        local rx_data = machine:read_memory(cartesi.AR_CMIO_RX_BUFFER_START, 1 << cartesi.AR_CMIO_RX_BUFFER_LOG2_SIZE)
         assert(rx_data == rx_new_data, "rx buffer data does not match")
-        local tx_data = machine:read_memory(cartesi.PMA_CMIO_TX_BUFFER_START, 1 << cartesi.PMA_CMIO_TX_BUFFER_LOG2_SIZE)
+        local tx_data = machine:read_memory(cartesi.AR_CMIO_TX_BUFFER_START, 1 << cartesi.AR_CMIO_TX_BUFFER_LOG2_SIZE)
         assert(tx_data == tx_new_data, "tx buffer data does not match")
     end)
 end
diff --git a/tests/lua/machine-test.lua b/tests/lua/machine-test.lua
index 616dc5604..0fe7a0a7e 100755
--- a/tests/lua/machine-test.lua
+++ b/tests/lua/machine-test.lua
@@ -155,7 +155,7 @@ do_test("machine halt and yield flags and config matches", function(machine)
     local initial_config = machine:get_initial_config()
     -- test_util.print_table(initial_config)
     assert(initial_config["processor"]["marchid"] == cartesi.MARCHID, "marchid value does not match")
-    assert(initial_config["processor"]["pc"] == cartesi.PMA_RAM_START, "pc value does not match")
+    assert(initial_config["processor"]["pc"] == cartesi.AR_RAM_START, "pc value does not match")
     assert(initial_config["ram"]["length"] == 1048576, "ram length value does not match")
     -- Check machine is not halted
     assert(machine:read_reg("iflags_H") == 0, "machine shouldn't be halted")
@@ -291,7 +291,7 @@ end
 
 print("\n\nwrite something to ram memory and check if hash and proof matches")
 do_test("proof  and root hash should match", function(machine)
-    local ram_address_start = cartesi.PMA_RAM_START
+    local ram_address_start = cartesi.AR_RAM_START
 
     -- Find proof for first KB of ram
     local initial_ram_proof = machine:get_proof(ram_address_start, 10)
diff --git a/tests/machine/src/access.S b/tests/machine/src/access.S
index 24470c76f..d73d08f1f 100644
--- a/tests/machine/src/access.S
+++ b/tests/machine/src/access.S
@@ -15,7 +15,7 @@
  */
 
 
-#include <pma-defines.h>
+#include <address-range-defines.h>
 
 #define exit_imm(imm) \
     li gp, imm; \
@@ -139,6 +139,6 @@ exit:
     srli gp, gp, 15;
     ori gp, gp, 1;
 1:
-    li t0, PMA_HTIF_START_DEF
+    li t0, AR_HTIF_START_DEF
     sd gp, 0(t0);
     j 1b; // Should not be necessary
diff --git a/tests/machine/src/bootstrap.S b/tests/machine/src/bootstrap.S
index 9cf8bdc4b..a20ce4f21 100644
--- a/tests/machine/src/bootstrap.S
+++ b/tests/machine/src/bootstrap.S
@@ -15,13 +15,13 @@
  */
 
 
-#include <pma-defines.h>
+#include <address-range-defines.h>
 
 .section .text.init;
 .align 2;
 .global _start;
 _start:
 
-	li t0, PMA_RAM_START_DEF; // converted to 2 instructions addiw and slli
+	li t0, AR_RAM_START_DEF; // converted to 2 instructions addiw and slli
 	csrr a0, mhartid;
 	jr t0;
diff --git a/tests/machine/src/clint_ops.S b/tests/machine/src/clint_ops.S
index 2e8342078..69ea8d05e 100644
--- a/tests/machine/src/clint_ops.S
+++ b/tests/machine/src/clint_ops.S
@@ -17,7 +17,7 @@
 
 // This programs exercise load/writes in the CLINT device.
 
-#include <pma-defines.h>
+#include <address-range-defines.h>
 
 // Uses HTIF to exit the emulator with exit code in an immediate
 #define exit_imm(imm) \
@@ -49,12 +49,12 @@ _start:
     csrw mtvec, t0;
 
     // Load CLINT.MTIME, it should equal to zero at the very start
-    li t0, PMA_CLINT_START_DEF + O_MTIME;
+    li t0, AR_CLINT_START_DEF + O_MTIME;
     ld t1, 0(t0);
     bnez t1, fail;
 
     // Store and load CLINT.MSIP
-    li t0, PMA_CLINT_START_DEF + O_MSIP;
+    li t0, AR_CLINT_START_DEF + O_MSIP;
     li t1, 0xffffffffff;
     sw t1, 0(t0);
     lw t2, 0(t0); // note that this won't raise an interrupts, because mip should be 0
@@ -65,7 +65,7 @@ _start:
     bne t2, t3, fail; // make sure mie.MSIP is set
 
     // Store and load CLINT.MTIMECMP
-    li t0, PMA_CLINT_START_DEF + O_MTIMECMP;
+    li t0, AR_CLINT_START_DEF + O_MTIMECMP;
     li t1, 0xffffffffffffffff;
     sd t1, 0(t0);
     ld t2, 0(t0);
@@ -77,49 +77,49 @@ _start:
 
     // Attempt to load a non 4-bytes value from CLINT.MSIP
     expect_trap(MCAUSE_LOAD_ACCESS_FAULT,
-        li t0, PMA_CLINT_START_DEF + O_MSIP;
+        li t0, AR_CLINT_START_DEF + O_MSIP;
         ld t1, 0(t0);
     )
 
     // Attempt to load a non 8-bytes value from CLINT.MTIMECMP
     expect_trap(MCAUSE_LOAD_ACCESS_FAULT,
-        li t0, PMA_CLINT_START_DEF + O_MTIMECMP;
+        li t0, AR_CLINT_START_DEF + O_MTIMECMP;
         lw t1, 0(t0);
     )
 
     // Attempt to load a non 8-bytes value from CLINT.MTIME
     expect_trap(MCAUSE_LOAD_ACCESS_FAULT,
-        li t0, PMA_CLINT_START_DEF + O_MTIME;
+        li t0, AR_CLINT_START_DEF + O_MTIME;
         lw t1, 0(t0);
     )
 
     // Attempt to load from an invalid CLINT offset
     expect_trap(MCAUSE_LOAD_ACCESS_FAULT,
-        li t0, PMA_CLINT_START_DEF + 1;
+        li t0, AR_CLINT_START_DEF + 1;
         lb t1, 0(t0);
     )
 
     // Attempt to store a non 4-bytes value in CLINT.MSIP
     expect_trap(MCAUSE_STORE_AMO_ACCESS_FAULT,
-        li t0, PMA_CLINT_START_DEF + O_MSIP;
+        li t0, AR_CLINT_START_DEF + O_MSIP;
         sd zero, 0(t0);
     )
 
     // Attempt to store a non 8-bytes value in CLINT.MTIMECMP
     expect_trap(MCAUSE_STORE_AMO_ACCESS_FAULT,
-        li t0, PMA_CLINT_START_DEF + O_MTIMECMP;
+        li t0, AR_CLINT_START_DEF + O_MTIMECMP;
         sw zero, 0(t0);
     )
 
     // Attempt to write to CLINT.MTIME
     expect_trap(MCAUSE_STORE_AMO_ACCESS_FAULT,
-        li t0, PMA_CLINT_START_DEF + O_MTIME;
+        li t0, AR_CLINT_START_DEF + O_MTIME;
         sd zero, 0(t0);
     )
 
     // Attempt to store in an invalid CLINT offset
     expect_trap(MCAUSE_STORE_AMO_ACCESS_FAULT,
-        li t0, PMA_CLINT_START_DEF + 1;
+        li t0, AR_CLINT_START_DEF + 1;
         sb zero, 0(t0);
     )
 
@@ -143,6 +143,6 @@ exit:
     srli gp, gp, 15;
     ori gp, gp, 1;
 1:
-    li t0, PMA_HTIF_START_DEF
+    li t0, AR_HTIF_START_DEF
     sd gp, 0(t0);
     j 1b;
diff --git a/tests/machine/src/compressed.S b/tests/machine/src/compressed.S
index e612360e3..e164c92d9 100644
--- a/tests/machine/src/compressed.S
+++ b/tests/machine/src/compressed.S
@@ -15,7 +15,7 @@
  */
 
 
-#include <pma-defines.h>
+#include <address-range-defines.h>
 
 // Uses HTIF to exit the emulator with exit code in an immediate
 #define exit_imm(imm) \
@@ -214,7 +214,7 @@ exit:
     srli gp, gp, 15;
     ori gp, gp, 1;
 1:
-    li t0, PMA_HTIF_START_DEF
+    li t0, AR_HTIF_START_DEF
     sd gp, 0(t0);
     j 1b; // Should not be necessary
 
diff --git a/tests/machine/src/csr_counters.S b/tests/machine/src/csr_counters.S
index cfe0ba4d3..bece06355 100644
--- a/tests/machine/src/csr_counters.S
+++ b/tests/machine/src/csr_counters.S
@@ -17,7 +17,7 @@
 
 // This test case tests all hardware counters in different privilege modes
 
-#include <pma-defines.h>
+#include <address-range-defines.h>
 
 #define exit_imm(imm) \
     li gp, imm; \
@@ -361,6 +361,6 @@ exit:
     srli gp, gp, 15;
     ori gp, gp, 1;
 1:
-    li t0, PMA_HTIF_START_DEF
+    li t0, AR_HTIF_START_DEF
     sd gp, 0(t0);
     j 1b; // Should not be necessary
diff --git a/tests/machine/src/csr_semantics.S b/tests/machine/src/csr_semantics.S
index 1a3009d83..4ee1c8e3c 100644
--- a/tests/machine/src/csr_semantics.S
+++ b/tests/machine/src/csr_semantics.S
@@ -17,7 +17,7 @@
 
 // This test case tests many CSR semantics in different privilege modes
 
-#include <pma-defines.h>
+#include <address-range-defines.h>
 
 // Uses HTIF to exit the emulator with exit code in an immediate
 #define exit_imm(imm) \
@@ -320,6 +320,6 @@ exit:
     srli gp, gp, 15;
     ori gp, gp, 1;
 1:
-    li t0, PMA_HTIF_START_DEF
+    li t0, AR_HTIF_START_DEF
     sd gp, 0(t0);
     j 1b; // Should not be necessary
diff --git a/tests/machine/src/dont_write_x0.S b/tests/machine/src/dont_write_x0.S
index 77b3b02f2..63adb8a60 100644
--- a/tests/machine/src/dont_write_x0.S
+++ b/tests/machine/src/dont_write_x0.S
@@ -15,7 +15,7 @@
  */
 
 
-#include <pma-defines.h>
+#include <address-range-defines.h>
 
 #define MSTATUS_FS_MASK     (3<<13)
 
@@ -147,7 +147,7 @@ exit:
 	srli gp, gp, 15;
 	ori gp, gp, 1;
 1:
-	li t0, PMA_HTIF_START_DEF
+	li t0, AR_HTIF_START_DEF
 	sd gp, 0(t0);
 	j 1b; // Should not be necessary
 
diff --git a/tests/machine/src/ebreak.S b/tests/machine/src/ebreak.S
index 9dbf1e9fb..bcf8615ce 100644
--- a/tests/machine/src/ebreak.S
+++ b/tests/machine/src/ebreak.S
@@ -15,7 +15,7 @@
  */
 
 
-#include <pma-defines.h>
+#include <address-range-defines.h>
 
 // Uses HTIF to exit the emulator with exit code in an immediate
 #define exit_imm(imm) \
@@ -57,7 +57,7 @@ exit:
   srli gp, gp, 15;
   ori gp, gp, 1;
 1:
-  li t0, PMA_HTIF_START_DEF
+  li t0, AR_HTIF_START_DEF
   sd gp, 0(t0);
   j 1b; // Should not be necessary
 
diff --git a/tests/machine/src/htif_cmio.S b/tests/machine/src/htif_cmio.S
index c21f08e62..fbd6f60db 100644
--- a/tests/machine/src/htif_cmio.S
+++ b/tests/machine/src/htif_cmio.S
@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+#include <pmas-defines.h>
 #include "htif_util.h"
 
 // This test will fetch the cmio buffers from the PMA entries; check that
@@ -38,7 +39,7 @@
 
 #define PMA_START_DID_CONST(did) ((did) << 8)
 #define PMA_START_DID_MASK    0x0000000000000f00
-#define PMA_START_START_MASK  0xfffffffffffff000
+#define AR_START_START_MASK  0xfffffffffffff000
 
 .global _start
 .align 2;
@@ -61,7 +62,7 @@ _start:
  * a0: a pma_did_const(x)
  * ret: pointer to pma entry */
 find_pma_by_did:
-    li t0, PMA_SHADOW_PMAS_START_DEF;
+    li t0, AR_PMAS_START_DEF;
     li t2, PMA_START_DID_MASK;
     /* is the pma array empty? */
     ld t1, O_LENGTH (t0);
@@ -86,7 +87,7 @@ found:
 fill_pma_with_a2:
     ld a1, O_LENGTH(a0);
     ld a0, O_START (a0);
-    li t0, PMA_START_START_MASK;
+    li t0, AR_START_START_MASK;
     and a0, a0, t0;
     j memset64; // tail call
 
@@ -108,7 +109,7 @@ l2: jr ra;
 check_pma_with_a2:
     ld a1, O_LENGTH(a0);
     ld a0, O_START (a0);
-    li t0, PMA_START_START_MASK;
+    li t0, AR_START_START_MASK;
     and a0, a0, t0;
     j memcheck64;
 
diff --git a/tests/machine/src/htif_console.S b/tests/machine/src/htif_console.S
index da27dead5..66aba2128 100644
--- a/tests/machine/src/htif_console.S
+++ b/tests/machine/src/htif_console.S
@@ -70,7 +70,7 @@ wait:
     ret
 
 is_console_getchar_enabled:
-    li t0, PMA_HTIF_START_DEF; \
+    li t0, AR_HTIF_START_DEF; \
     ld t0, O_ICONSOLE (t0); \
     srli t0, t0, HTIF_CONSOLE_CMD_GETCHAR_DEF; \
     andi a0, t0, 1;
diff --git a/tests/machine/src/htif_invalid_ops.S b/tests/machine/src/htif_invalid_ops.S
index d0a7a6710..ee0f4a659 100644
--- a/tests/machine/src/htif_invalid_ops.S
+++ b/tests/machine/src/htif_invalid_ops.S
@@ -43,7 +43,7 @@ _start:
     csrw mtvec, t0;
 
     // Unknown HTIF devices are silently ignored
-    li t0, PMA_HTIF_START_DEF;
+    li t0, AR_HTIF_START_DEF;
     li t1, htif_const(0xff, 0, 0);
     sd zero, O_FROMHOST(t0);
     sd t1, O_TOHOST(t0);
@@ -51,7 +51,7 @@ _start:
     bnez t2, fail;
 
     // HTIF halt with invalid commands is silently ignored
-    li t0, PMA_HTIF_START_DEF;
+    li t0, AR_HTIF_START_DEF;
     li t1, htif_const(HTIF_DEV_HALT_DEF, 0xff, 3);
     sd zero, O_FROMHOST(t0);
     sd t1, O_TOHOST(t0);
@@ -59,7 +59,7 @@ _start:
     bnez t2, fail;
 
     // HTIF halt with exit least-signed bit unset is silently ignored
-    li t0, PMA_HTIF_START_DEF;
+    li t0, AR_HTIF_START_DEF;
     li t1, htif_const(HTIF_DEV_HALT_DEF, HTIF_HALT_CMD_HALT_DEF, 2);
     sd zero, O_FROMHOST(t0);
     sd t1, O_TOHOST(t0);
@@ -72,39 +72,39 @@ _start:
 
     // Attempt to load a non 8-bytes value from HTIF
     expect_trap(MCAUSE_LOAD_ACCESS_FAULT,
-        li t0, PMA_HTIF_START_DEF;
+        li t0, AR_HTIF_START_DEF;
         lw t1, O_TOHOST(t0);
     )
 
     // Attempt to load from a misaligned HTIF offset
     expect_trap(MCAUSE_LOAD_ACCESS_FAULT,
-        li t0, PMA_HTIF_START_DEF;
+        li t0, AR_HTIF_START_DEF;
         lb t1, 1(t0);
     )
 
     // Attempt to load from an invalid HTIF offset
     expect_trap(MCAUSE_LOAD_ACCESS_FAULT,
-        li t0, PMA_HTIF_START_DEF;
+        li t0, AR_HTIF_START_DEF;
         ld t1, (O_IYIELD+8)(t0);
     )
 
     // Attempt to store a non 8-bytes value in HTIF
     expect_trap(MCAUSE_STORE_AMO_ACCESS_FAULT,
-        li t0, PMA_HTIF_START_DEF;
+        li t0, AR_HTIF_START_DEF;
         li t1, 3;
         sw t1, O_TOHOST(t0);
     )
 
     // Attempt to store in a misaligned HTIF offset
     expect_trap(MCAUSE_STORE_AMO_ACCESS_FAULT,
-        li t0, PMA_HTIF_START_DEF;
+        li t0, AR_HTIF_START_DEF;
         li t1, 3;
         sb t1, 1(t0);
     )
 
     // Attempt to store in an invalid HTIF offset
     expect_trap(MCAUSE_STORE_AMO_ACCESS_FAULT,
-        li t0, PMA_HTIF_START_DEF;
+        li t0, AR_HTIF_START_DEF;
         li t1, 3;
         sd t1, (O_IYIELD+8)(t0);
     )
@@ -129,6 +129,6 @@ exit:
     srli gp, gp, 15;
     ori gp, gp, 1;
 1:
-    li t0, PMA_HTIF_START_DEF
+    li t0, AR_HTIF_START_DEF
     sd gp, 0(t0);
     j 1b;
diff --git a/tests/machine/src/htif_util.h b/tests/machine/src/htif_util.h
index 820de173e..ab2908660 100644
--- a/tests/machine/src/htif_util.h
+++ b/tests/machine/src/htif_util.h
@@ -1,6 +1,6 @@
 #ifndef HTIF_UTIL_H
 #define HTIF_UTIL_H
-#include <pma-defines.h>
+#include <address-range-defines.h>
 #include <htif-defines.h>
 
 /* from: https://www.cartesi.io/en/docs/machine/target/architecture/
@@ -36,7 +36,7 @@
 // Issue a HTIF call with `ireg` as the input, place the output in `oreg`.
 // NOTE: `base` will be used as scratch register
 #define htif_call(base, ireg, oreg) \
-    li base, PMA_HTIF_START_DEF; \
+    li base, AR_HTIF_START_DEF; \
     sd zero, O_FROMHOST (base); \
     sd ireg, O_TOHOST   (base); \
     ld oreg, O_FROMHOST (base)
diff --git a/tests/machine/src/htif_yield.S b/tests/machine/src/htif_yield.S
index 7e5ff7d0b..e06c8a953 100644
--- a/tests/machine/src/htif_yield.S
+++ b/tests/machine/src/htif_yield.S
@@ -28,7 +28,7 @@
 
 // Check HTIF fromhost address for yield command ack
 #define check_htif_ack(dev, cmd, data) \
-    li t0, PMA_HTIF_START_DEF; \
+    li t0, AR_HTIF_START_DEF; \
     ld t3, O_IYIELD (t0); \
     srli t3, t3, cmd; \
     andi t3, t3, 1; \
@@ -46,7 +46,7 @@
     and t0, t0, t2; \
     or t1, t1, t0; \
     and t1, t1, t3; /* if cmd is disabled, expect 0 ack */ \
-    li t0, PMA_HTIF_START_DEF; \
+    li t0, AR_HTIF_START_DEF; \
     ld t2, O_FROMHOST (t0); \
     bne t1, t2, ack_failed;
 
@@ -122,7 +122,7 @@ exit:
     srli gp, gp, 15;
     ori gp, gp, 1;
 1:
-    li t0, PMA_HTIF_START_DEF;
+    li t0, AR_HTIF_START_DEF;
     sd x0, O_FROMHOST (t0);
     sd gp, O_TOHOST   (t0);
     j 1b; // unreachable
diff --git a/tests/machine/src/illegal_insn.S b/tests/machine/src/illegal_insn.S
index 296a51ce8..4e6d36761 100644
--- a/tests/machine/src/illegal_insn.S
+++ b/tests/machine/src/illegal_insn.S
@@ -15,7 +15,7 @@
  */
 
 
-#include <pma-defines.h>
+#include <address-range-defines.h>
 
 // Uses HTIF to exit the emulator with exit code in an immediate
 #define exit_imm(imm) \
@@ -203,7 +203,7 @@ exit:
     srli gp, gp, 15;
     ori gp, gp, 1;
 1:
-    li t0, PMA_HTIF_START_DEF
+    li t0, AR_HTIF_START_DEF
     sd gp, 0(t0);
     j 1b; // Should not be necessary
 
diff --git a/tests/machine/src/interrupts.S b/tests/machine/src/interrupts.S
index e3cb4bbe6..db5612b0f 100644
--- a/tests/machine/src/interrupts.S
+++ b/tests/machine/src/interrupts.S
@@ -17,7 +17,7 @@
 
 // This test case tests software interrupts and interrupt delegation
 
-#include <pma-defines.h>
+#include <address-range-defines.h>
 
 // Uses HTIF to exit the emulator with exit code in an immediate
 #define exit_imm(imm) \
@@ -33,7 +33,7 @@
 #define MCAUSE_SSIP         ((1<<MCAUSE_INT_BIT) | SSI_CODE)
 #define MCAUSE_MTIP         ((1<<MCAUSE_INT_BIT) | MTI_CODE)
 
-#define MTIMECMP_ADDR       (PMA_CLINT_START_DEF + 0x4000)
+#define MTIMECMP_ADDR       (AR_CLINT_START_DEF + 0x4000)
 
 #define MSTATUS_MPP_MASK 0x1800
 #define MSTATUS_SPP_MASK 0x100
@@ -178,6 +178,6 @@ exit:
     srli gp, gp, 15;
     ori gp, gp, 1;
 1:
-    li t0, PMA_HTIF_START_DEF
+    li t0, AR_HTIF_START_DEF
     sd gp, 0(t0);
     j 1b; // Should not be necessary
diff --git a/tests/machine/src/lrsc_semantics.S b/tests/machine/src/lrsc_semantics.S
index 3c07d2adc..38fe99711 100644
--- a/tests/machine/src/lrsc_semantics.S
+++ b/tests/machine/src/lrsc_semantics.S
@@ -15,7 +15,7 @@
  */
 
 
-#include <pma-defines.h>
+#include <address-range-defines.h>
 
 #define exit_imm(imm) \
     li gp, imm; \
@@ -68,10 +68,10 @@ exit:
     srli gp, gp, 15;
     ori gp, gp, 1;
 1:
-    li t0, PMA_HTIF_START_DEF
+    li t0, AR_HTIF_START_DEF
     sd gp, 0(t0);
     j 1b; // Should not be necessary
 
 .data
 .align 3; foo: .dword 0
-.align 3; boo: .dword 0
\ No newline at end of file
+.align 3; boo: .dword 0
diff --git a/tests/machine/src/mcycle_overflow.S b/tests/machine/src/mcycle_overflow.S
index 31fdb51f3..b9a307412 100644
--- a/tests/machine/src/mcycle_overflow.S
+++ b/tests/machine/src/mcycle_overflow.S
@@ -15,7 +15,7 @@
  */
 
 
-#include <pma-defines.h>
+#include <address-range-defines.h>
 
 // Uses HTIF to exit the emulator with exit code in an immediate
 #define exit_imm(imm) \
@@ -58,7 +58,7 @@ exit:
 	srli gp, gp, 15;
 	ori gp, gp, 1;
 1:
-	li t0, PMA_HTIF_START_DEF
+	li t0, AR_HTIF_START_DEF
 	sd gp, 0(t0);
 	j 1b; // Should not be necessary
 
diff --git a/tests/machine/src/mcycle_write.S b/tests/machine/src/mcycle_write.S
index 15a929867..6da637fd5 100644
--- a/tests/machine/src/mcycle_write.S
+++ b/tests/machine/src/mcycle_write.S
@@ -15,7 +15,7 @@
  */
 
 
-#include <pma-defines.h>
+#include <address-range-defines.h>
 
 #define exit_imm(imm) \
     li gp, imm; \
@@ -52,6 +52,6 @@ exit:
     srli gp, gp, 15;
     ori gp, gp, 1;
 1:
-    li t0, PMA_HTIF_START_DEF
+    li t0, AR_HTIF_START_DEF
     sd gp, 0(t0);
     j 1b; // Should not be necessary
diff --git a/tests/machine/src/mtime_interrupt.S b/tests/machine/src/mtime_interrupt.S
index 328a51ec5..841de9270 100644
--- a/tests/machine/src/mtime_interrupt.S
+++ b/tests/machine/src/mtime_interrupt.S
@@ -19,7 +19,7 @@
 // WFI loop for this interrupt to happen. When the interrupt occurs, the test
 // checks whether the cause CSR is set properly.
 
-#include <pma-defines.h>
+#include <address-range-defines.h>
 
 // Uses HTIF to exit the emulator with exit code in an immediate
 #define exit_imm(imm) \
@@ -27,7 +27,7 @@
 	j exit;
 
 // MTIMECMP is a CLINT register that is mapped to RAM
-#define MTIMECMP_ADDR	(PMA_CLINT_START_DEF + 0x4000)
+#define MTIMECMP_ADDR	(AR_CLINT_START_DEF + 0x4000)
 
 #define MTIE_MASK	(1<<7)
 #define MIE_MASK	(1<<3)
@@ -90,6 +90,6 @@ exit:
 	srli gp, gp, 15;
 	ori gp, gp, 1;
 1:
-	li t0, PMA_HTIF_START_DEF
+	li t0, AR_HTIF_START_DEF
 	sd gp, 0(t0);
 	j 1b; // Should not be necessary
diff --git a/tests/machine/src/pte_reserved_exception.S b/tests/machine/src/pte_reserved_exception.S
index 3c9273025..b5974c2db 100644
--- a/tests/machine/src/pte_reserved_exception.S
+++ b/tests/machine/src/pte_reserved_exception.S
@@ -15,7 +15,7 @@
  */
 
 
-#include <pma-defines.h>
+#include <address-range-defines.h>
 
 #define MSTATUS_MPP 0x1800
 #define CAUSE_USER_ECALL 0x8
@@ -79,7 +79,7 @@ exit:
   srli gp, gp, 15;
   ori gp, gp, 1;
 1:
-  li t0, PMA_HTIF_START_DEF
+  li t0, AR_HTIF_START_DEF
   sd gp, 0(t0);
   j 1b; // Should not be necessary
 
diff --git a/tests/machine/src/sd_pma_overflow.S b/tests/machine/src/sd_pma_overflow.S
index 1aded5e2a..072dc275d 100644
--- a/tests/machine/src/sd_pma_overflow.S
+++ b/tests/machine/src/sd_pma_overflow.S
@@ -15,7 +15,7 @@
  */
 
 
-#include <pma-defines.h>
+#include <address-range-defines.h>
 
 // Uses HTIF to exit the emulator with exit code in an immediate
 #define exit_imm(imm) \
@@ -53,6 +53,6 @@ exit:
 	srli gp, gp, 15;
 	ori gp, gp, 1;
 1:
-	li t0, PMA_HTIF_START_DEF
+	li t0, AR_HTIF_START_DEF
 	sd gp, 0(t0);
 	j 1b; // Should not be necessary
diff --git a/tests/machine/src/shadow_ops.S b/tests/machine/src/shadow_ops.S
index 530f36547..1c3336f12 100644
--- a/tests/machine/src/shadow_ops.S
+++ b/tests/machine/src/shadow_ops.S
@@ -17,7 +17,7 @@
 
 // This programs exercise load/writes in the shadow.
 
-#include <pma-defines.h>
+#include <address-range-defines.h>
 
 // Uses HTIF to exit the emulator with exit code in an immediate
 #define exit_imm(imm) \
@@ -32,9 +32,9 @@
 
 #define MCAUSE_STORE_AMO_ACCESS_FAULT 0x7
 #define MCAUSE_LOAD_ACCESS_FAULT 0x5
-#define SHADOWS_PMA_LAST_ENTRY_ISTART (31*16)
-#define SHADOWS_PMA_LAST_ENTRY_ILENGTH (31*16+8)
-#define SHADOWS_PMA_TOTAL_SIZE (32*16)
+#define PMAS_LAST_ENTRY_ISTART (31*16)
+#define PMAS_LAST_ENTRY_ILENGTH (31*16+8)
+#define PMAS_TOTAL_SIZE (32*16)
 #define EMPTY_PMA_ISTART (4)
 #define EMPTY_PMA_ILENGTH (0)
 
@@ -48,11 +48,11 @@ _start:
     csrw mtvec, t0;
 
     // We are allowed to read the shadow PMAs
-    li t0, PMA_SHADOW_PMAS_START_DEF;
-    ld t1, SHADOWS_PMA_LAST_ENTRY_ISTART(t0);
+    li t0, AR_PMAS_START_DEF;
+    ld t1, PMAS_LAST_ENTRY_ISTART(t0);
     li t2, EMPTY_PMA_ISTART
     bne t1, t2, fail;
-    ld t1, SHADOWS_PMA_LAST_ENTRY_ILENGTH(t0);
+    ld t1, PMAS_LAST_ENTRY_ILENGTH(t0);
     li t2, EMPTY_PMA_ILENGTH
     bne t1, t2, fail;
 
@@ -62,31 +62,31 @@ _start:
 
     // Attempt to load a value from the shadow state
     expect_trap(MCAUSE_LOAD_ACCESS_FAULT,
-        li t0, PMA_SHADOW_STATE_START_DEF;
+        li t0, AR_SHADOW_STATE_START_DEF;
         ld t1, 8(t0);
     )
 
     // Attempt to load a value from the shadow TLB
     expect_trap(MCAUSE_LOAD_ACCESS_FAULT,
-        li t0, PMA_SHADOW_TLB_START_DEF;
+        li t0, AR_SHADOW_TLB_START_DEF;
         ld t1, 0(t0);
     )
 
     // Attempt to store a value in the shadow PMAs
     expect_trap(MCAUSE_STORE_AMO_ACCESS_FAULT,
-        li t0, PMA_SHADOW_PMAS_START_DEF;
+        li t0, AR_PMAS_START_DEF;
         sd x0, 0(t0);
     )
 
     // Attempt to store a value in the shadow state
     expect_trap(MCAUSE_STORE_AMO_ACCESS_FAULT,
-        li t0, PMA_SHADOW_STATE_START_DEF;
+        li t0, AR_SHADOW_STATE_START_DEF;
         sd x0, 8(t0);
     )
 
     // Attempt to store a value in the shadow TLB
     expect_trap(MCAUSE_STORE_AMO_ACCESS_FAULT,
-        li t0, PMA_SHADOW_TLB_START_DEF;
+        li t0, AR_SHADOW_TLB_START_DEF;
         sd x0, 0(t0);
     )
 
@@ -110,6 +110,6 @@ exit:
     srli gp, gp, 15;
     ori gp, gp, 1;
 1:
-    li t0, PMA_HTIF_START_DEF
+    li t0, AR_HTIF_START_DEF
     sd gp, 0(t0);
     j 1b;
diff --git a/tests/machine/src/translate_vaddr.S b/tests/machine/src/translate_vaddr.S
index cea1655bf..d628d746d 100644
--- a/tests/machine/src/translate_vaddr.S
+++ b/tests/machine/src/translate_vaddr.S
@@ -15,7 +15,7 @@
  */
 
 
-#include <pma-defines.h>
+#include <address-range-defines.h>
 #include <encoding.h>
 
 #define PTE_FLAGS (PTE_V | PTE_R | PTE_W | PTE_X | PTE_U)
@@ -286,7 +286,7 @@ exit:
     srli gp, gp, 15;
     ori gp, gp, 1;
 1:
-    li t0, PMA_HTIF_START_DEF
+    li t0, AR_HTIF_START_DEF
     sd gp, 0(t0);
     j 1b; // Should not be necessary
 
diff --git a/tests/machine/src/version_check.S b/tests/machine/src/version_check.S
index 564d87443..a642717ca 100644
--- a/tests/machine/src/version_check.S
+++ b/tests/machine/src/version_check.S
@@ -15,7 +15,7 @@
  */
 
 
-#include <pma-defines.h>
+#include <address-range-defines.h>
 
 // Uses HTIF to exit the emulator with exit code in an immediate
 #define exit_imm(imm) \
@@ -67,6 +67,6 @@ exit:
 	srli gp, gp, 15;
 	ori gp, gp, 1;
 1:
-	li t0, PMA_HTIF_START_DEF
+	li t0, AR_HTIF_START_DEF
 	sd gp, 0(t0);
 	j 1b; // Should not be necessary
diff --git a/tests/machine/src/xpie_exceptions.S b/tests/machine/src/xpie_exceptions.S
index d741d8172..efb84ebb4 100644
--- a/tests/machine/src/xpie_exceptions.S
+++ b/tests/machine/src/xpie_exceptions.S
@@ -15,7 +15,7 @@
  */
 
 
-#include <pma-defines.h>
+#include <address-range-defines.h>
 
 // Uses HTIF to exit the emulator with exit code in an immediate
 #define exit_imm(imm) \
@@ -110,6 +110,6 @@ exit:
 	srli gp, gp, 15;
 	ori gp, gp, 1;
 1:
-	li t0, PMA_HTIF_START_DEF
+	li t0, AR_HTIF_START_DEF
 	sd gp, 0(t0);
 	j 1b; // Should not be necessary
diff --git a/tests/misc/test-machine-c-api.cpp b/tests/misc/test-machine-c-api.cpp
index cf806288c..13e63a628 100644
--- a/tests/misc/test-machine-c-api.cpp
+++ b/tests/misc/test-machine-c-api.cpp
@@ -989,7 +989,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(read_write_uarch_x_basic_test, ordinary_machine_f
 
     uint64_t uarch_x2_addr{};
     BOOST_CHECK_EQUAL(cm_get_reg_address(_machine, CM_REG_UARCH_X2, &uarch_x2_addr), CM_ERROR_OK);
-    BOOST_CHECK_EQUAL(static_cast<uint64_t>(cartesi::PMA_SHADOW_UARCH_STATE_START + 40), uarch_x2_addr);
+    BOOST_CHECK_EQUAL(static_cast<uint64_t>(cartesi::AR_SHADOW_UARCH_STATE_START + 40), uarch_x2_addr);
 }
 
 BOOST_AUTO_TEST_CASE_NOLINT(read_reg_null_machine_test) {
@@ -1459,11 +1459,11 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(machine_reset_uarch, ordinary_machine_fixture) {
 
     // change the uarch ram in order to confirm if reset will restore it to the initial value
     std::array<uint8_t, 8> random_bytes{1, 2, 3, 4, 5, 6, 7, 8};
-    error_code = cm_write_memory(_machine, cartesi::PMA_UARCH_RAM_START, random_bytes.data(), random_bytes.size());
+    error_code = cm_write_memory(_machine, cartesi::AR_UARCH_RAM_START, random_bytes.data(), random_bytes.size());
     BOOST_REQUIRE_EQUAL(error_code, CM_ERROR_OK);
 
     // grab the modified ram bytes
-    std::vector<unsigned char> modified_uarch_ram(cartesi::PMA_UARCH_RAM_LENGTH);
+    std::vector<unsigned char> modified_uarch_ram(cartesi::AR_UARCH_RAM_LENGTH);
     error_code = cm_read_memory(_machine, cartesi::UARCH_RAM_START_ADDRESS, modified_uarch_ram.data(),
         modified_uarch_ram.size());
     BOOST_REQUIRE_EQUAL(error_code, CM_ERROR_OK);
diff --git a/third-party/riscv-arch-test b/third-party/riscv-arch-test
index 6f05d8b7e..c05f9b7d3 160000
--- a/third-party/riscv-arch-test
+++ b/third-party/riscv-arch-test
@@ -1 +1 @@
-Subproject commit 6f05d8b7e562b5df5107c657a93e9b8af457ae96
+Subproject commit c05f9b7d3cd8b83a7a9c17ea26e570f080dc95fe
diff --git a/uarch/compute-uarch-pristine-hash.cpp b/uarch/compute-uarch-pristine-hash.cpp
index caf0c09b3..87ed4f92e 100644
--- a/uarch/compute-uarch-pristine-hash.cpp
+++ b/uarch/compute-uarch-pristine-hash.cpp
@@ -35,8 +35,8 @@ using hash_type = tree_type::hash_type;
 using hashertype = tree_type::hasher_type;
 using proof_type = tree_type::proof_type;
 
-static_assert(PMA_PAGE_SIZE == tree_type::get_page_size(), "PMA and machine_merkle_tree page sizes must match");
-static_assert(sizeof(shadow_uarch_state) <= PMA_PAGE_SIZE, "shadow_uarch_state must fit in one page");
+static_assert(AR_PAGE_SIZE == tree_type::get_page_size(), "PMA and machine_merkle_tree page sizes must match");
+static_assert(sizeof(shadow_uarch_state) <= AR_PAGE_SIZE, "shadow_uarch_state must fit in one page");
 
 /// \brief Prints help message
 static void help(const char *name) {
@@ -70,7 +70,7 @@ int main(int argc, char *argv[]) try {
     }
 
     // Allocate scratch page buffer
-    auto scratch = make_unique_calloc<unsigned char>(PMA_PAGE_SIZE, std::nothrow_t{});
+    auto scratch = make_unique_calloc<unsigned char>(AR_PAGE_SIZE, std::nothrow_t{});
     if (!scratch) {
         throw std::runtime_error("Could not allocate scratch memory");
     }
@@ -78,7 +78,7 @@ int main(int argc, char *argv[]) try {
     // Build pristine shadow uarch state
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
     auto *shadow = reinterpret_cast<shadow_uarch_state *>(scratch.get());
-    memset(scratch.get(), 0, PMA_PAGE_SIZE);
+    memset(scratch.get(), 0, AR_PAGE_SIZE);
     shadow->halt_flag = UARCH_HALT_FLAG_INIT;
     shadow->pc = UARCH_PC_INIT;
     shadow->cycle = UARCH_CYCLE_INIT;
@@ -94,10 +94,10 @@ int main(int argc, char *argv[]) try {
         throw std::runtime_error("Could not update uarch shadow tree node hash");
     }
     // Add all pages of uarch ram to merkle tree
-    for (uint32_t p = 0; p < uarch_pristine_ram_len; p += PMA_PAGE_SIZE) {
+    for (uint32_t p = 0; p < uarch_pristine_ram_len; p += AR_PAGE_SIZE) {
         const auto *page_data = uarch_pristine_ram + p;
-        if (p + PMA_PAGE_SIZE > uarch_pristine_ram_len) {
-            memset(scratch.get(), 0, PMA_PAGE_SIZE);
+        if (p + AR_PAGE_SIZE > uarch_pristine_ram_len) {
+            memset(scratch.get(), 0, AR_PAGE_SIZE);
             memcpy(scratch.get(), uarch_pristine_ram + p, uarch_pristine_ram_len - p);
             page_data = scratch.get();
         }
diff --git a/uarch/machine-uarch-bridge-state-access.h b/uarch/machine-uarch-bridge-state-access.h
index bcf842a8d..65230497e 100644
--- a/uarch/machine-uarch-bridge-state-access.h
+++ b/uarch/machine-uarch-bridge-state-access.h
@@ -27,9 +27,8 @@
 #include "i-state-access.h"
 #include "machine-reg.h"
 #include "mock-address-range.h"
-#include "pma-constants.h"
+#include "pmas.h"
 #include "riscv-constants.h"
-#include "shadow-pmas.h"
 #include "shadow-tlb.h"
 #include "uarch-constants.h"
 #include "uarch-defines.h"
@@ -73,11 +72,11 @@ class machine_uarch_bridge_state_access :
     }
 
     static uint64_t bridge_read_pma_istart(int i) {
-        return ua_aliased_aligned_read<uint64_t>(shadow_pmas_get_pma_abs_addr(i, shadow_pmas_what::istart));
+        return ua_aliased_aligned_read<uint64_t>(pmas_get_abs_addr(i, pmas_what::istart));
     }
 
     static uint64_t bridge_read_pma_ilength(int i) {
-        return ua_aliased_aligned_read<uint64_t>(shadow_pmas_get_pma_abs_addr(i, shadow_pmas_what::ilength));
+        return ua_aliased_aligned_read<uint64_t>(pmas_get_abs_addr(i, pmas_what::ilength));
     }
 
     static uint64_t bridge_read_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, shadow_tlb_what what) {
diff --git a/uarch/uarch-ram-entry.S b/uarch/uarch-ram-entry.S
index f8fca7184..0d39dacd9 100644
--- a/uarch/uarch-ram-entry.S
+++ b/uarch/uarch-ram-entry.S
@@ -14,7 +14,7 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#include <pma-defines.h>
+#include <address-range-defines.h>
 #include <uarch-defines.h>
 
 .section .text.init;
@@ -22,8 +22,8 @@
 .global _start;
 _start:
     // Initialize stack
-    li sp, PMA_UARCH_RAM_START_DEF
-    li t0, PMA_UARCH_RAM_LENGTH_DEF
+    li sp, AR_UARCH_RAM_START_DEF
+    li t0, AR_UARCH_RAM_LENGTH_DEF
     add sp, sp, t0 // stack pointer at the end of RAM
     call interpret_next_mcycle_with_uarch
 
diff --git a/uarch/uarch-ram.ld.in b/uarch/uarch-ram.ld.in
index 3a883325d..55874fbaf 100644
--- a/uarch/uarch-ram.ld.in
+++ b/uarch/uarch-ram.ld.in
@@ -1,17 +1,17 @@
 OUTPUT_ARCH( "riscv" )
 ENTRY(_start)
 
-#include "pma-defines.h"
+#include "address-range-defines.h"
 
 SECTIONS
 {
-  . = PMA_UARCH_RAM_START_DEF;
+  . = AR_UARCH_RAM_START_DEF;
   .text.init : { *(.text.init) }
   .text : { *(.text) }
-  .rodata : { *(.rodata) }  
+  .rodata : { *(.rodata) }
   .sdata : { *(.sdata) }
-  .bss : { *(.bss) }  
-  .tdata : { *(.tdata) }  
-     
+  .bss : { *(.bss) }
+  .tdata : { *(.tdata) }
+
   _end = .;
 }

From c2d4a105df21d5079e6e26c7dee299f6b3e24963 Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Mon, 3 Mar 2025 15:58:34 +0000
Subject: [PATCH 25/82] refactor: remove the E flag

This increases the space for DID
Checking for empty address range simply checks its length.
Shadow address ranges are neither device nor memory.
This is because they cannot be read/written with read_device/write_device.
They do not implement get_host_memory() either.
---
 src/Makefile                           |  24 ++--
 src/address-range.h                    |  40 +++---
 src/clint-address-range.h              |  10 +-
 src/find-pmas-entry.h                  |   2 +-
 src/htif-address-range.h               |  10 +-
 src/machine.cpp                        | 170 +++++++++++--------------
 src/machine.h                          |  14 +-
 src/mock-address-range.h               |  24 ++--
 src/plic-address-range.h               |  10 +-
 src/pmas-address-range.h               |  48 -------
 src/pmas-constants.h                   |  34 +++--
 src/pmas.h                             |  10 +-
 src/shadow-state-address-range.h       |  12 +-
 src/shadow-tlb-address-range.h         |  12 +-
 src/shadow-uarch-state-address-range.h |   3 +-
 src/virtio-address-range.h             |   1 -
 tests/lua/cartesi-machine-tests.lua    |   2 +-
 tests/lua/htif-cmio.lua                |   6 +-
 tests/machine/src/htif_cmio.S          |  18 +--
 tests/machine/src/shadow_ops.S         |   8 +-
 tests/misc/test-machine-c-api.cpp      |   6 +-
 21 files changed, 194 insertions(+), 270 deletions(-)
 delete mode 100644 src/pmas-address-range.h

diff --git a/src/Makefile b/src/Makefile
index d170c1660..214326e2d 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -175,19 +175,19 @@ DEFS+=-D_FILE_OFFSET_BITS=64
 DEFS+=-DJSON_HAS_FILESYSTEM=0
 
 ifeq ($(dump),yes)
-#DUMP_DEFS+=-DDUMP_ILLEGAL_INSN_EXCEPTIONS
-#DUMP_DEFS+=-DDUMP_EXCEPTIONS
-#DUMP_DEFS+=-DDUMP_INTERRUPTS
-#DUMP_DEFS+=-DDUMP_MMU_EXCEPTIONS
-#DUMP_DEFS+=-DDUMP_INVALID_CSR
-#DUMP_DEFS+=-DDUMP_REGS
-#DUMP_DEFS+=-DDUMP_INSN_HIST
-#DUMP_DEFS+=-DDUMP_STATS
+DUMP_DEFS+=-DDUMP_ILLEGAL_INSN_EXCEPTIONS
+DUMP_DEFS+=-DDUMP_EXCEPTIONS
+DUMP_DEFS+=-DDUMP_INTERRUPTS
+DUMP_DEFS+=-DDUMP_MMU_EXCEPTIONS
+DUMP_DEFS+=-DDUMP_INVALID_CSR
+DUMP_DEFS+=-DDUMP_REGS
+DUMP_DEFS+=-DDUMP_INSN_HIST
+DUMP_DEFS+=-DDUMP_STATS
 DUMP_DEFS+=-DDUMP_INSN
-#DUMP_DEFS+=-DDUMP_UARCH_INSN
-#DUMP_DEFS+=-DDUMP_SCOPED_NOTE
-#DUMP_DEFS+=-DDUMP_STATE_ACCESS
-#DUMP_DEFS+=-DDUMP_UARCH_STATE_ACCESS
+DUMP_DEFS+=-DDUMP_UARCH_INSN
+DUMP_DEFS+=-DDUMP_SCOPED_NOTE
+DUMP_DEFS+=-DDUMP_STATE_ACCESS
+DUMP_DEFS+=-DDUMP_UARCH_STATE_ACCESS
 endif
 DEFS += $(DUMP_DEFS)
 # Pass down UARCH_DEFS to sub-makefiles
diff --git a/src/address-range.h b/src/address-range.h
index 354e5f80b..be681ccfb 100644
--- a/src/address-range.h
+++ b/src/address-range.h
@@ -56,7 +56,6 @@ class address_range {
         m_length{0},
         m_length_bit_ceil{0},
         m_flags{} {
-        m_flags.E = true;
         for (unsigned i = 0; i < std::min<unsigned>(N, m_description.size() - 1); ++i) {
             m_description[i] = description[i];
         }
@@ -70,7 +69,8 @@ class address_range {
     constexpr virtual ~address_range() {}; // = default; // doesn't work due to bug in gcc
 
     template <typename ABRT, size_t N, typename... ARGS>
-    [[noreturn]] static void ABRTF(ABRT abrt, const char (&fmt)[N], ARGS... args) {
+    [[noreturn]]
+    static void ABRTF(ABRT abrt, const char (&fmt)[N], ARGS... args) {
         char buf[256]{};
         std::ignore = snprintf(buf, std::size(buf), fmt, args...);
         abrt(buf);
@@ -98,36 +98,29 @@ class address_range {
             m_description[i] = description[i];
         }
         // All address ranges must be page-aligned
-        if ((m_length & ~AR_ISTART_START_MASK) != 0) {
-            ABRTF(abrt, "length must be multiple of page size when initializing %s", m_description);
+        if ((m_length & ~PMA_ISTART_START_MASK) != 0) {
+            ABRTF(abrt, "length must be multiple of page size when initializing %s", description);
         }
-        if ((m_start & ~AR_ISTART_START_MASK) != 0) {
-            ABRTF(abrt, "start of %s (0x%" PRIx64 ") must be aligned to page boundary of %d bytes", m_description,
-                start, AR_PAGE_SIZE);
+        if ((m_start & ~PMA_ISTART_START_MASK) != 0) {
+            ABRTF(abrt, "start of %s (0x%" PRIx64 ") must be aligned to page boundary of %" PRId64 " bytes",
+                description, start, AR_PAGE_SIZE);
         }
         // It must be possible to round length up to the next power of two
         if (m_length_bit_ceil == 0) {
-            ABRTF(abrt, "range too long when initializing %s", m_description);
+            ABRTF(abrt, "address range too long when initializing %s", description);
         }
         // Empty range must really be empty
         if (m_length == 0) {
             if (m_start != 0) {
-                ABRTF(abrt, "range with length 0 must start at 0 when initializing %s", m_description);
-            }
-            if (!m_flags.E) {
-                ABRTF(abrt, "range with length 0 must be flagged empty when initializing %s", m_description);
+                ABRTF(abrt, "range with length 0 must start at 0 when initializing %s", description);
             }
             if (m_flags.M) {
-                ABRTF(abrt, "memory range cannot be empty when initializing %s", m_description);
+                ABRTF(abrt, "memory address range cannot have length 0 when initializing %s", description);
             }
             if (m_flags.IO) {
-                ABRTF(abrt, "device range cannot be empty when initializing %s", m_description);
+                ABRTF(abrt, "device address range cannot have length 0 when initializing %s", description);
             }
         }
-        // Non-empty range must either be memory or device
-        if (static_cast<int>(m_flags.M) + static_cast<int>(m_flags.IO) + static_cast<int>(m_flags.E) != 1) {
-            ABRTF(abrt, "range must be one of empty, memory, or device when initializing %s", m_description);
-        }
     }
 
     /// \brief Checks if a range of addresses is entirely contained within this range
@@ -178,36 +171,39 @@ class address_range {
 
     /// \brief Test if address range is occupied by memory
     /// \returns True if and only if range is occupied by memory
+    /// \details In this case, get_host_memory() is guaranteed not to return nullptr.
     bool is_memory() const noexcept {
         return m_flags.M;
     }
 
     /// \brief Test if address range is occupied by a device
     /// \returns True if and only if range is occupied by a device
+    /// \details In this case, read_device() and write_device() are operational.
     bool is_device() const noexcept {
         return m_flags.IO;
     }
 
     /// \brief Test if address range is empty
     /// \returns True if and only if range is empty
+    /// \details Empty ranges should be used only for sentinels.
     bool is_empty() const noexcept {
-        return m_flags.E;
+        return m_length == 0;
     }
 
     /// \brief Tests if range is readable
-    /// \returns True if and only if range is readable
+    /// \returns True if and only if range is readable from within the machine.
     bool is_readable() const noexcept {
         return m_flags.R;
     }
 
     /// \brief Tests if range is writeable
-    /// \returns True if and only if range is writeable
+    /// \returns True if and only if range is writeable from within the machine.
     bool is_writeable() const noexcept {
         return m_flags.W;
     }
 
     /// \brief Tests if range is executable
-    /// \returns True if and only if range is executable
+    /// \returns True if and only if range is executable from within the machine.
     bool is_executable() const noexcept {
         return m_flags.X;
     }
diff --git a/src/clint-address-range.h b/src/clint-address-range.h
index 96b024075..3a785a749 100644
--- a/src/clint-address-range.h
+++ b/src/clint-address-range.h
@@ -19,6 +19,7 @@
 
 #include <cstdint>
 
+#include "address-range-constants.h"
 #include "pristine-address-range.h"
 
 /// \file
@@ -31,7 +32,6 @@ class clint_address_range final : public pristine_address_range {
     static constexpr pmas_flags m_clint_flags{
         .M = false,
         .IO = true,
-        .E = false,
         .R = true,
         .W = true,
         .X = false,
@@ -42,8 +42,8 @@ class clint_address_range final : public pristine_address_range {
 
 public:
     template <typename ABRT>
-    clint_address_range(uint64_t start, uint64_t length, ABRT abrt) :
-        pristine_address_range("CLINT device", start, length, m_clint_flags, abrt) {
+    explicit clint_address_range(ABRT abrt) :
+        pristine_address_range("CLINT device", AR_CLINT_START, AR_CLINT_LENGTH, m_clint_flags, abrt) {
         ;
     }
 
@@ -61,8 +61,8 @@ class clint_address_range final : public pristine_address_range {
 };
 
 template <typename ABRT>
-static inline clint_address_range make_clint_address_range(uint64_t start, uint64_t length, ABRT abrt) {
-    return clint_address_range{start, length, abrt};
+static inline clint_address_range make_clint_address_range(ABRT abrt) {
+    return clint_address_range{abrt};
 }
 
 } // namespace cartesi
diff --git a/src/find-pmas-entry.h b/src/find-pmas-entry.h
index 73cb36503..1ef1f2e64 100644
--- a/src/find-pmas-entry.h
+++ b/src/find-pmas-entry.h
@@ -40,7 +40,7 @@ address_range &find_pma(const STATE_ACCESS a, uint64_t paddr, uint64_t &index) {
         // The pmas array always contain a sentinel.
         // It is an entry with zero length.
         // If we hit it, return it
-        if (unlikely(ar.get_length() == 0)) {
+        if (unlikely(ar.is_empty())) {
             return ar;
         }
         if (ar.contains_absolute(paddr, sizeof(T))) {
diff --git a/src/htif-address-range.h b/src/htif-address-range.h
index c19ec87e5..c48b27c3e 100644
--- a/src/htif-address-range.h
+++ b/src/htif-address-range.h
@@ -19,6 +19,7 @@
 
 #include <cstdint>
 
+#include "address-range-constants.h"
 #include "i-device-state-access.h"
 #include "pmas-constants.h"
 #include "pristine-address-range.h"
@@ -33,7 +34,6 @@ class htif_address_range final : public pristine_address_range {
     static constexpr pmas_flags m_htif_flags{
         .M = false,
         .IO = true,
-        .E = false,
         .R = true,
         .W = true,
         .X = false,
@@ -44,8 +44,8 @@ class htif_address_range final : public pristine_address_range {
 
 public:
     template <typename ABRT>
-    htif_address_range(uint64_t start, uint64_t length, ABRT abrt) :
-        pristine_address_range("HTIF device", start, length, m_htif_flags, abrt) {
+    explicit htif_address_range(ABRT abrt) :
+        pristine_address_range("HTIF device", AR_HTIF_START, AR_HTIF_LENGTH, m_htif_flags, abrt) {
         ;
     }
 
@@ -63,8 +63,8 @@ class htif_address_range final : public pristine_address_range {
 };
 
 template <typename ABRT>
-static inline htif_address_range make_htif_address_range(uint64_t start, uint64_t length, ABRT abrt) {
-    return htif_address_range{start, length, abrt};
+static inline htif_address_range make_htif_address_range(ABRT abrt) {
+    return htif_address_range{abrt};
 }
 
 } // namespace cartesi
diff --git a/src/machine.cpp b/src/machine.cpp
index 5dd705ed7..54d60f59f 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -55,7 +55,6 @@
 #include "machine-runtime-config.h"
 #include "memory-address-range.h"
 #include "plic-address-range.h"
-#include "pmas-address-range.h"
 #include "pmas.h"
 #include "record-send-cmio-state-access.h"
 #include "record-step-state-access.h"
@@ -190,7 +189,6 @@ void machine::init_uarch(const uarch_config &c) {
     static constexpr pmas_flags uram_flags{
         .M = true,
         .IO = false,
-        .E = false,
         .R = true,
         .W = true,
         .X = true,
@@ -287,7 +285,6 @@ void machine::init_ram_ar(const ram_config &ram) {
     static constexpr pmas_flags ram_flags{
         .M = true,
         .IO = false,
-        .E = false,
         .R = true,
         .W = true,
         .X = true,
@@ -308,7 +305,6 @@ void machine::init_flash_drive_ars(flash_drive_configs &flash_drive) {
     static const pmas_flags flash_flags{
         .M = true,
         .IO = false,
-        .E = false,
         .R = true,
         .W = true,
         .X = false,
@@ -412,7 +408,7 @@ void machine::init_virtio_ars(const virtio_configs &cs, uint64_t iunrep) {
 
 void machine::init_htif_ar(const htif_config &h) {
     // Register HTIF device
-    register_address_range(make_htif_address_range(AR_HTIF_START, AR_HTIF_LENGTH, throw_invalid_argument),
+    register_address_range(make_htif_address_range(throw_invalid_argument),
         register_where{.merkle = false, .interpret = true});
     // Copy HTIF state to from config to machine
     write_reg(reg::htif_tohost, h.tohost);
@@ -432,7 +428,6 @@ void machine::init_cmio_ars(const cmio_config &c) {
     static const pmas_flags tx_flags{
         .M = true,
         .IO = false,
-        .E = false,
         .R = true,
         .W = true,
         .X = false,
@@ -443,7 +438,6 @@ void machine::init_cmio_ars(const cmio_config &c) {
     static const pmas_flags rx_flags{
         .M = true,
         .IO = false,
-        .E = false,
         .R = true,
         .W = false,
         .X = false,
@@ -468,8 +462,8 @@ void machine::init_merkle_ars() {
 
 void machine::init_ars_descriptions() {
     // Initialize memory range descriptions returned by get_address_ranges method
-    auto src = m_ars | std::views::filter([](auto &ar) { return ar->get_length() != 0; }) |
-        std::views::transform([](auto &ar) {
+    auto src =
+        m_ars | std::views::filter([](auto &ar) { return !ar->is_empty(); }) | std::views::transform([](auto &ar) {
             return address_range_description{.start = ar->get_start(),
                 .length = ar->get_length(),
                 .description = ar->get_description()};
@@ -480,7 +474,7 @@ void machine::init_ars_descriptions() {
 
 void machine::init_clint_ar(const clint_config &c) {
     // Register CLINT device
-    register_address_range(make_clint_address_range(AR_CLINT_START, AR_CLINT_LENGTH, throw_invalid_argument),
+    register_address_range(make_clint_address_range(throw_invalid_argument),
         register_where{.merkle = false, .interpret = true});
     // Copy CLINT state to from config to machine
     write_reg(reg::clint_mtimecmp, c.mtimecmp);
@@ -488,23 +482,13 @@ void machine::init_clint_ar(const clint_config &c) {
 
 void machine::init_plic_ar(const plic_config &p) {
     // Register PLIC device
-    register_address_range(make_plic_address_range(AR_PLIC_START, AR_PLIC_LENGTH, throw_invalid_argument),
+    register_address_range(make_plic_address_range(throw_invalid_argument),
         register_where{.merkle = false, .interpret = true});
     // Copy PLIC state from config to machine
     write_reg(reg::plic_girqpend, p.girqpend);
     write_reg(reg::plic_girqsrvd, p.girqsrvd);
 }
 
-void machine::init_sentinel_ars() {
-    // Last, add empty sentinels until we reach capacity (need at least one sentinel)
-    // ??D I will remove these sentinels from the list
-    register_address_range(make_empty_address_range("sentinel"), register_where{.merkle = false, .interpret = true});
-    while (m_s.pmas.size() < PMA_MAX) {
-        register_address_range(make_empty_address_range("sentinel"),
-            register_where{.merkle = false, .interpret = true});
-    }
-}
-
 void machine::init_pmas_contents(memory_address_range &pmas) const {
     static_assert(sizeof(pmas_state) == PMA_MAX * 2 * sizeof(uint64_t), "inconsistent PMAs state length");
     static_assert(AR_PMAS_LENGTH >= sizeof(pmas_state), "PMAs address range too short");
@@ -536,13 +520,12 @@ void machine::init_tlb_contents(const std::string &image_filename) {
     }
 }
 
-address_range &machine::init_dtb_ar(const dtb_config &c) {
+static inline auto make_dtb_address_range(const std::string &image_filename) {
     // When we pass a RNG seed in a FDT stored in DTB, Linux will wipe out its contents as a security measure,
-    // therefore we need to make DTB writable, otherwise boot will hang.
+    // theref, ore we need to make DTB writable, otherwise boot will hang.
     static constexpr pmas_flags dtb_flags{
         .M = true,
         .IO = false,
-        .E = false,
         .R = true,
         .W = true,
         .X = true,
@@ -550,9 +533,8 @@ address_range &machine::init_dtb_ar(const dtb_config &c) {
         .IW = true,
         .DID = PMA_ISTART_DID::memory,
     };
-    return register_address_range(make_memory_address_range("DTB"s, AR_DTB_START, AR_DTB_LENGTH, dtb_flags,
-                                      c.image_filename, false /* not shared */),
-        register_where{.merkle = true, .interpret = true});
+    return make_memory_address_range("DTB"s, AR_DTB_START, AR_DTB_LENGTH, dtb_flags, image_filename,
+        false /* not shared */);
 }
 
 void machine::init_dtb_contents(const machine_config &c, address_range &dtb) {
@@ -561,6 +543,20 @@ void machine::init_dtb_contents(const machine_config &c, address_range &dtb) {
     }
 }
 
+static inline auto make_pmas_address_range() {
+    static constexpr pmas_flags m_pmas_flags{
+        .M = true,
+        .IO = false,
+        .R = true,
+        .W = false,
+        .X = false,
+        .IR = true,
+        .IW = false,
+        .DID = PMA_ISTART_DID::memory,
+    };
+    return make_callocd_memory_address_range("PMAs", AR_PMAS_START, AR_PMAS_LENGTH, m_pmas_flags);
+}
+
 // ??D It is best to leave the std::move() on r because it may one day be necessary!
 // NOLINTNEXTLINE(hicpp-move-const-arg,performance-move-const-arg)
 machine::machine(machine_config c, machine_runtime_config r) : m_c{std::move(c)}, m_r{std::move(r)} {
@@ -569,27 +565,24 @@ machine::machine(machine_config c, machine_runtime_config r) : m_c{std::move(c)}
     m_s.soft_yield = m_r.soft_yield;
     init_ram_ar(m_c.ram);
     // Will populate when initialization of PMAs is done
-    auto &dtb = init_dtb_ar(m_c.dtb);
+    auto &dtb = register_address_range(make_dtb_address_range(m_c.dtb.image_filename),
+        register_where{.merkle = true, .interpret = true});
     init_flash_drive_ars(m_c.flash_drive);
     init_cmio_ars(m_c.cmio);
     init_htif_ar(m_c.htif);
     init_clint_ar(m_c.clint);
     init_plic_ar(m_c.plic);
     // Will populate when initialization of PMAs is done
-    register_address_range(
-        make_shadow_tlb_address_range(AR_SHADOW_TLB_START, AR_SHADOW_TLB_LENGTH, throw_invalid_argument),
+    register_address_range(make_shadow_tlb_address_range(throw_invalid_argument),
         register_where{.merkle = true, .interpret = false});
-    register_address_range(
-        make_shadow_state_address_range(AR_SHADOW_STATE_START, AR_SHADOW_STATE_LENGTH, throw_invalid_argument),
+    register_address_range(make_shadow_state_address_range(throw_invalid_argument),
         register_where{.merkle = true, .interpret = false});
     // Will populate when initialization of PMAs is done
-    auto &shpmas = register_address_range(make_pmas_address_range(AR_PMAS_START, AR_PMAS_LENGTH),
-        register_where{.merkle = true, .interpret = true});
+    auto &pmas = register_address_range(make_pmas_address_range(), register_where{.merkle = true, .interpret = true});
     init_virtio_ars(m_c.virtio, m_c.processor.iunrep);
-    init_sentinel_ars();
-    // Populate shadow PMAs contents.
+    // Populate PMAs contents.
     // This must be done after all PMA entries are already registered, so we encode them into the shadow
-    init_pmas_contents(shpmas);
+    init_pmas_contents(pmas);
     // Initialize TLB contents.
     // This must be done after all PMA entries are already registered, so we can lookup page addresses
     init_tlb_contents(m_c.tlb.image_filename);
@@ -778,39 +771,33 @@ machine_config machine::get_serialization_config() const {
     return c;
 }
 
-static void store_device_address_range(const machine &m, const address_range &ar, const std::string &dir) {
-    if (!ar.is_device()) {
-        throw std::runtime_error{"attempt to save non-device address range "s + ar.get_description()};
-    }
-    auto scratch = make_unique_calloc<unsigned char>(AR_PAGE_SIZE); // will throw if it fails
-    auto name = machine_config::get_image_filename(dir, ar.get_start(), ar.get_length());
+void machine::store_address_range(const address_range &ar, const std::string &directory) const {
+    auto name = machine_config::get_image_filename(directory, ar.get_start(), ar.get_length());
     auto fp = make_unique_fopen(name.c_str(), "wb"); // will throw if it fails
-    for (uint64_t offset = 0; offset < ar.get_length(); offset += AR_PAGE_SIZE) {
-        const unsigned char *page_data = nullptr;
-        if (!ar.peek(m, offset, AR_PAGE_SIZE, &page_data, scratch.get())) {
-            throw std::runtime_error{"peek failed"};
-        }
-        if (page_data == nullptr) {
-            memset(scratch.get(), 0, AR_PAGE_SIZE);
-            page_data = scratch.get();
+    // If we have do not have a pointer to the address range memory, use peek
+    if (ar.get_host_memory() == nullptr) {
+        auto scratch = make_unique_calloc<unsigned char>(AR_PAGE_SIZE); // will throw if it fails
+        for (uint64_t offset = 0; offset < ar.get_length(); offset += AR_PAGE_SIZE) {
+            const unsigned char *page_data = nullptr;
+            if (!ar.peek(*this, offset, AR_PAGE_SIZE, &page_data, scratch.get())) {
+                throw std::runtime_error{"peek failed"};
+            }
+            if (page_data == nullptr) {
+                memset(scratch.get(), 0, AR_PAGE_SIZE);
+                page_data = scratch.get();
+            }
+            if (fwrite(page_data, 1, AR_PAGE_SIZE, fp.get()) != AR_PAGE_SIZE) {
+                throw std::system_error{errno, std::generic_category(), "error writing to '" + name + "'"};
+            }
         }
-        if (fwrite(page_data, 1, AR_PAGE_SIZE, fp.get()) != AR_PAGE_SIZE) {
-            throw std::system_error{errno, std::generic_category(), "error writing to '" + name + "'"};
+        // Otherwise, use memory directly
+    } else {
+        if (fwrite(ar.get_host_memory(), 1, ar.get_length(), fp.get()) != ar.get_length()) {
+            throw std::runtime_error{"error writing to '" + name + "'"};
         }
     }
 }
 
-static void store_memory_address_range(const address_range &ar, const std::string &dir) {
-    if (!ar.is_memory()) {
-        throw std::runtime_error{"attempt to save non-memory address-range "s + ar.get_description()};
-    }
-    auto name = machine_config::get_image_filename(dir, ar.get_start(), ar.get_length());
-    auto fp = make_unique_fopen(name.c_str(), "wb");
-    if (fwrite(ar.get_host_memory(), 1, ar.get_length(), fp.get()) != ar.get_length()) {
-        throw std::runtime_error{"error writing to '" + name + "'"};
-    }
-}
-
 uint64_t machine::get_paddr(host_addr haddr, uint64_t pma_index) const {
     return static_cast<uint64_t>(haddr + get_hp_offset(pma_index));
 }
@@ -865,7 +852,7 @@ void machine::check_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, uin
             throw std::domain_error{prefix + "pma_index is out of range"s};
         }
         const auto &ar = read_pma(pma_index);
-        if (ar.get_length() == 0 || !ar.is_memory()) {
+        if (!ar.is_memory()) {
             throw std::invalid_argument{prefix + "pma_index does not point to memory range"s};
         }
         if ((vaddr_page & PAGE_OFFSET_MASK) != 0) {
@@ -912,7 +899,6 @@ host_addr machine::get_hp_offset(uint64_t pma_index) const {
     return paddr - haddr;
 }
 
-//??D now that m_merkle_ars is sorted by start, maybe change this to a binary search?
 const address_range &machine::find_address_range(uint64_t paddr, uint64_t length) const noexcept {
     static constexpr auto sentinel = make_empty_address_range("sentinel");
     for (const auto &ar : m_ars) {
@@ -927,16 +913,16 @@ void machine::store_address_ranges(const machine_config &c, const std::string &d
     if (read_reg(reg::iunrep) != 0) {
         throw std::runtime_error{"cannot store PMAs of unreproducible machines"};
     }
-    store_memory_address_range(find_address_range<uint64_t>(AR_DTB_START), dir);
-    store_memory_address_range(find_address_range<uint64_t>(AR_RAM_START), dir);
-    store_device_address_range(*this, find_address_range<uint64_t>(AR_SHADOW_TLB_START), dir);
+    store_address_range(find_address_range<uint64_t>(AR_DTB_START), dir);
+    store_address_range(find_address_range<uint64_t>(AR_RAM_START), dir);
+    store_address_range(find_address_range<uint64_t>(AR_SHADOW_TLB_START), dir);
     // Could iterate over PMAs checking for those with a drive DID but this is easier
     for (const auto &f : c.flash_drive) {
-        store_memory_address_range(find_address_range<uint64_t>(f.start), dir);
+        store_address_range(find_address_range<uint64_t>(f.start), dir);
     }
-    store_memory_address_range(find_address_range<uint64_t>(AR_CMIO_RX_BUFFER_START), dir);
-    store_memory_address_range(find_address_range<uint64_t>(AR_CMIO_TX_BUFFER_START), dir);
-    store_memory_address_range(find_address_range<uint64_t>(AR_UARCH_RAM_START), dir);
+    store_address_range(find_address_range<uint64_t>(AR_CMIO_RX_BUFFER_START), dir);
+    store_address_range(find_address_range<uint64_t>(AR_CMIO_TX_BUFFER_START), dir);
+    store_address_range(find_address_range<uint64_t>(AR_UARCH_RAM_START), dir);
 }
 
 static void store_hash(const machine::hash_type &h, const std::string &dir) {
@@ -1808,7 +1794,7 @@ void machine::mark_write_tlb_dirty_pages() const {
             const auto &cold_slot = cold_set[slot_index];
             // NOLINTNEXTLINE(cppcoreguidelines-pro-type-const-cast)
             auto &ar = const_cast<address_range &>(read_pma(cold_slot.pma_index));
-            if (ar.get_length() == 0 || !ar.is_memory()) {
+            if (!ar.is_memory()) {
                 throw std::runtime_error{"could not mark dirty page for a TLB entry: TLB is corrupt"};
             }
             auto paddr_page = get_paddr(haddr_page, cold_slot.pma_index);
@@ -2049,32 +2035,28 @@ machine_merkle_tree::proof_type machine::get_proof(uint64_t address, int log2_si
     if ((address & ((~UINT64_C(0)) >> (64 - log2_size))) != 0) {
         throw std::domain_error{"address not aligned to log2_size"};
     }
-    // If proof concerns range smaller than a page, we may need to rebuild part
-    // of the proof from the contents of a page inside some PMA range.
-    // PMA range starts and lengths are multiple of the page size, which is a
-    // power of 2.
-    // The size of the desired range is smaller than the page size, but its
-    // size is a power of 2, and it is aligned to its size.
-    // Therefore, it is is either entirely inside a PMA range,
-    // or entirely outside it.
+    // If proof concerns range smaller than a page, we may need to rebuild part of the proof from
+    // the contents of a page inside some PMA range.
+    // PMA range starts and lengths are multiple of the page size, which is a power of 2.
+    // The size of the desired range is smaller than the page size, but its size is a power of 2,
+    // and it is aligned to its size.
+    // Therefore, it is is either entirely inside a PMA range, or entirely outside it.
     if (log2_size < machine_merkle_tree::get_log2_page_size()) {
         const uint64_t length = UINT64_C(1) << log2_size;
         const auto &ar = find_address_range(address, length);
         auto scratch = make_unique_calloc<unsigned char>(AR_PAGE_SIZE);
         const unsigned char *page_data = nullptr;
-        // If the PMA range is empty, we know the desired range is
-        // entirely outside of any non-pristine PMA.
-        // Therefore, the entire page where it lies is also pristine
+        // If the PMA range is empty, we know the desired range is entirely outside of any non-pristine PMA.
+        // Therefore, the entire page where it lies is also pristine.
         // Otherwise, the entire desired range is inside it.
-        if (ar.get_length() != 0) {
+        if (!ar.is_empty()) {
             const uint64_t page_start_in_range = (address - ar.get_start()) & (~(AR_PAGE_SIZE - 1));
             if (!ar.peek(*this, page_start_in_range, AR_PAGE_SIZE, &page_data, scratch.get())) {
                 throw std::runtime_error{"PMA peek failed"};
             }
         }
         return m_t.get_proof(address, log2_size, page_data);
-        // If proof concerns range bigger than a page, we already have its hash
-        // stored in the tree itself
+        // If proof concerns range bigger than a page, we already have its hash stored in the tree itself
     }
     return m_t.get_proof(address, log2_size, nullptr);
 }
@@ -2160,8 +2142,10 @@ void machine::read_memory(uint64_t paddr, unsigned char *data, uint64_t length)
             data += from_ar;
         }
     }
-    // Finish up with pristine padding after last address range
-    memset(data, 0, length);
+    if (length != 0) {
+        // Finish up with pristine padding after last address range
+        memset(data, 0, length);
+    }
 }
 
 void machine::write_memory(uint64_t paddr, const unsigned char *data, uint64_t length) {
@@ -2175,7 +2159,7 @@ void machine::write_memory(uint64_t paddr, const unsigned char *data, uint64_t l
     if (ar.is_device()) {
         throw std::invalid_argument{"attempted write to device memory range"};
     }
-    if (ar.get_length() == 0 || !ar.is_memory()) {
+    if (!ar.is_memory()) {
         throw std::invalid_argument{"address range to write is not entirely in single memory range"};
     }
     if (is_protected(ar.get_driver_id())) {
@@ -2201,7 +2185,7 @@ void machine::fill_memory(uint64_t paddr, uint8_t val, uint64_t length) {
     if (ar.is_device()) {
         throw std::invalid_argument{"attempted fill to device memory range"};
     }
-    if (ar.get_length() == 0 || !ar.is_memory()) {
+    if (!ar.is_memory()) {
         throw std::invalid_argument{"address range to fill is not entirely in memory PMA"};
     }
     if (is_protected(ar.get_driver_id())) {
@@ -2328,7 +2312,7 @@ void machine::write_word(uint64_t paddr, uint64_t val) {
     }
     // Otherwise, try the slow path
     auto &ar = find_address_range(paddr, sizeof(uint64_t));
-    if (ar.get_length() == 0 || !ar.is_memory() || ar.get_host_memory() == nullptr) {
+    if (!ar.is_memory() || ar.get_host_memory() == nullptr) {
         std::ostringstream err;
         err << "attempted memory write to " << ar.get_description() << " at address 0x" << std::hex << paddr << "("
             << std::dec << paddr << ")";
diff --git a/src/machine.h b/src/machine.h
index 06ca721ea..56a14f0fd 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -129,6 +129,11 @@ class machine final {
     /// \param directory Directory where address ranges will be stored
     void store_address_ranges(const machine_config &config, const std::string &directory) const;
 
+    /// \brief Saves an address ranges into serialization directory
+    /// \param ar Address range to store
+    /// \param directory Directory where address range will be stored
+    void store_address_range(const address_range &ar, const std::string &directory) const;
+
     /// \brief Returns offset that converts between machine host addresses and target physical addresses
     /// \param pma_index Index of the memory PMA for the desired offset
     host_addr get_hp_offset(uint64_t pma_index) const;
@@ -185,9 +190,6 @@ class machine final {
     /// \detail This can only be called after all address ranges have been registered
     void init_ars_descriptions();
 
-    /// \brief Fill up address range list with sentinels
-    void init_sentinel_ars();
-
     /// \brief Initializes contents of the shadow PMAs memory
     /// \param pmas PMA entry for the shadow PMAs
     /// \detail This can only be called after all PMAs have been added
@@ -198,10 +200,6 @@ class machine final {
     /// \detail This can only be called after all PMAs have been added
     void init_tlb_contents(const std::string &image_filename);
 
-    /// \brief Initializes DTB address range
-    /// \param c DTB configuration
-    address_range &init_dtb_ar(const dtb_config &c);
-
     /// \brief Initializes contents of machine DTB, if image was not available
     /// \param c Machine configuration
     /// \param dtb PMA entry for the shadow PMAs
@@ -500,7 +498,7 @@ class machine final {
     /// \returns Desired address range, or an empty sentinel if index is out of bounds
     const address_range &read_pma(uint64_t index) const noexcept {
         if (index >= m_s.pmas.size()) {
-            static constexpr address_range sentinel{"sentinel"};
+            static constexpr auto sentinel = make_empty_address_range("sentinel");
             return sentinel;
         }
         // NOLINTNEXTLINE(bugprone-narrowing-conversions)
diff --git a/src/mock-address-range.h b/src/mock-address-range.h
index 5f51ff520..a7e8609b1 100644
--- a/src/mock-address-range.h
+++ b/src/mock-address-range.h
@@ -37,11 +37,12 @@ using mock_address_range = std::variant<std::monostate, address_range, clint_add
 using mock_address_ranges = std::array<mock_address_range, PMA_MAX>;
 
 template <typename AR, typename ABRT>
-static inline mock_address_range check_mock_flags(AR &&ar, const pmas_flags &flags, ABRT abrt)
+static inline mock_address_range check_mock_address_range(AR &&ar, uint64_t start, uint64_t length,
+    const pmas_flags &flags, ABRT abrt)
     requires std::is_rvalue_reference_v<AR &&> && std::derived_from<AR, address_range>
 {
-    if (ar.get_flags() != flags) {
-        abrt("incompatible flags in mock address range");
+    if (ar.get_flags() != flags || start != ar.get_start() || length != ar.get_length()) {
+        abrt("incompatible mock address range");
         __builtin_trap();
         return std::monostate{};
     }
@@ -53,22 +54,23 @@ static inline mock_address_range make_mock_address_range(uint64_t istart, uint64
     uint64_t start{};
     auto flags = pmas_unpack_istart(istart, start);
     if (flags.M) {
-        return make_address_range(pmas_get_DID_name(flags.DID), start, ilength, flags, abrt);
+        return check_mock_address_range(make_address_range(pmas_get_DID_name(flags.DID), start, ilength, flags, abrt),
+            start, ilength, flags, abrt);
     }
-    if (flags.E) {
-        return make_address_range("empty", start, ilength, flags, abrt);
+    if (ilength == 0) {
+        return check_mock_address_range(make_empty_address_range("empty"), start, ilength, flags, abrt);
     }
     switch (flags.DID) {
         case PMA_ISTART_DID::shadow_state:
-            return check_mock_flags(make_shadow_state_address_range(start, ilength, abrt), flags, abrt);
+            return check_mock_address_range(make_shadow_state_address_range(abrt), start, ilength, flags, abrt);
         case PMA_ISTART_DID::shadow_TLB:
-            return check_mock_flags(make_shadow_tlb_address_range(start, ilength, abrt), flags, abrt);
+            return check_mock_address_range(make_shadow_tlb_address_range(abrt), start, ilength, flags, abrt);
         case PMA_ISTART_DID::CLINT:
-            return check_mock_flags(make_clint_address_range(start, ilength, abrt), flags, abrt);
+            return check_mock_address_range(make_clint_address_range(abrt), start, ilength, flags, abrt);
         case PMA_ISTART_DID::PLIC:
-            return check_mock_flags(make_plic_address_range(start, ilength, abrt), flags, abrt);
+            return check_mock_address_range(make_plic_address_range(abrt), start, ilength, flags, abrt);
         case PMA_ISTART_DID::HTIF:
-            return check_mock_flags(make_htif_address_range(start, ilength, abrt), flags, abrt);
+            return check_mock_address_range(make_htif_address_range(abrt), start, ilength, flags, abrt);
         default:
             abrt("unhandled mock address range");
             __builtin_trap();
diff --git a/src/plic-address-range.h b/src/plic-address-range.h
index 76ab71de8..19b36a9bb 100644
--- a/src/plic-address-range.h
+++ b/src/plic-address-range.h
@@ -19,6 +19,7 @@
 
 #include <cstdint>
 
+#include "address-range-constants.h"
 #include "i-device-state-access.h"
 #include "plic-constants.h"
 #include "pristine-address-range.h"
@@ -41,7 +42,6 @@ class plic_address_range final : public pristine_address_range {
     static constexpr pmas_flags m_plic_flags{
         .M = false,
         .IO = true,
-        .E = false,
         .R = true,
         .W = true,
         .X = false,
@@ -52,8 +52,8 @@ class plic_address_range final : public pristine_address_range {
 
 public:
     template <typename ABRT>
-    plic_address_range(uint64_t start, uint64_t length, ABRT abrt) :
-        pristine_address_range("PLIC device", start, length, m_plic_flags, abrt) {
+    explicit plic_address_range(ABRT abrt) :
+        pristine_address_range("PLIC device", AR_PLIC_START, AR_PLIC_LENGTH, m_plic_flags, abrt) {
         ;
     }
 
@@ -71,8 +71,8 @@ class plic_address_range final : public pristine_address_range {
 };
 
 template <typename ABRT>
-static inline plic_address_range make_plic_address_range(uint64_t start, uint64_t length, ABRT abrt) {
-    return plic_address_range{start, length, abrt};
+static inline plic_address_range make_plic_address_range(ABRT abrt) {
+    return plic_address_range{abrt};
 }
 
 } // namespace cartesi
diff --git a/src/pmas-address-range.h b/src/pmas-address-range.h
deleted file mode 100644
index 960f20e41..000000000
--- a/src/pmas-address-range.h
+++ /dev/null
@@ -1,48 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef PMAS_ADDRESS_RANGE_H
-#define PMAS_ADDRESS_RANGE_H
-
-#include <cstdint>
-#include <stdexcept>
-
-#include "memory-address-range.h"
-#include "pmas.h"
-
-/// \file
-/// \brief Shadow device.
-
-namespace cartesi {
-
-static inline auto make_pmas_address_range(uint64_t start, uint64_t length) {
-    static constexpr pmas_flags m_flags{
-        .M = true,
-        .IO = false,
-        .E = false,
-        .R = true,
-        .W = false,
-        .X = false,
-        .IR = false,
-        .IW = false,
-        .DID = PMA_ISTART_DID::memory,
-    };
-    return make_callocd_memory_address_range("PMAs", start, length, m_flags);
-}
-
-} // namespace cartesi
-
-#endif
diff --git a/src/pmas-constants.h b/src/pmas-constants.h
index fa6aaae09..ff87b0031 100644
--- a/src/pmas-constants.h
+++ b/src/pmas-constants.h
@@ -32,28 +32,26 @@ enum PMA_constants : uint64_t {
 enum PMA_ISTART_shifts {
     PMA_ISTART_M_SHIFT = 0,
     PMA_ISTART_IO_SHIFT = 1,
-    PMA_ISTART_E_SHIFT = 2,
-    PMA_ISTART_R_SHIFT = 3,
-    PMA_ISTART_W_SHIFT = 4,
-    PMA_ISTART_X_SHIFT = 5,
-    PMA_ISTART_IR_SHIFT = 6,
-    PMA_ISTART_IW_SHIFT = 7,
-    PMA_ISTART_DID_SHIFT = 8,
-    AR_ISTART_START_SHIFT = 12
+    PMA_ISTART_R_SHIFT = 2,
+    PMA_ISTART_W_SHIFT = 3,
+    PMA_ISTART_X_SHIFT = 4,
+    PMA_ISTART_IR_SHIFT = 5,
+    PMA_ISTART_IW_SHIFT = 6,
+    PMA_ISTART_DID_SHIFT = 7,
+    PMA_ISTART_START_SHIFT = 12
 };
 
 /// \brief PMA istart masks
 enum PMA_ISTART_masks : uint64_t {
-    PMA_ISTART_M_MASK = UINT64_C(1) << PMA_ISTART_M_SHIFT,       ///< Memory range
-    PMA_ISTART_IO_MASK = UINT64_C(1) << PMA_ISTART_IO_SHIFT,     ///< Device range
-    PMA_ISTART_E_MASK = UINT64_C(1) << PMA_ISTART_E_SHIFT,       ///< Empty range
-    PMA_ISTART_R_MASK = UINT64_C(1) << PMA_ISTART_R_SHIFT,       ///< Readable
-    PMA_ISTART_W_MASK = UINT64_C(1) << PMA_ISTART_W_SHIFT,       ///< Writable
-    PMA_ISTART_X_MASK = UINT64_C(1) << PMA_ISTART_X_SHIFT,       ///< Executable
-    PMA_ISTART_IR_MASK = UINT64_C(1) << PMA_ISTART_IR_SHIFT,     ///< Idempotent reads
-    PMA_ISTART_IW_MASK = UINT64_C(1) << PMA_ISTART_IW_SHIFT,     ///< Idempotent writes
-    PMA_ISTART_DID_MASK = UINT64_C(15) << PMA_ISTART_DID_SHIFT,  ///< Device id
-    AR_ISTART_START_MASK = UINT64_C(-1) << AR_ISTART_START_SHIFT ///< Start of range
+    PMA_ISTART_M_MASK = UINT64_C(1) << PMA_ISTART_M_SHIFT,         ///< Memory range
+    PMA_ISTART_IO_MASK = UINT64_C(1) << PMA_ISTART_IO_SHIFT,       ///< Device range
+    PMA_ISTART_R_MASK = UINT64_C(1) << PMA_ISTART_R_SHIFT,         ///< Readable
+    PMA_ISTART_W_MASK = UINT64_C(1) << PMA_ISTART_W_SHIFT,         ///< Writable
+    PMA_ISTART_X_MASK = UINT64_C(1) << PMA_ISTART_X_SHIFT,         ///< Executable
+    PMA_ISTART_IR_MASK = UINT64_C(1) << PMA_ISTART_IR_SHIFT,       ///< Idempotent reads
+    PMA_ISTART_IW_MASK = UINT64_C(1) << PMA_ISTART_IW_SHIFT,       ///< Idempotent writes
+    PMA_ISTART_DID_MASK = UINT64_C(31) << PMA_ISTART_DID_SHIFT,    ///< Driver ID
+    PMA_ISTART_START_MASK = UINT64_C(-1) << PMA_ISTART_START_SHIFT ///< Start of range
 };
 
 /// \brief PMA device ids
diff --git a/src/pmas.h b/src/pmas.h
index fe178e0e4..819981e40 100644
--- a/src/pmas.h
+++ b/src/pmas.h
@@ -32,6 +32,8 @@ namespace cartesi {
 
 static constexpr const char *pmas_get_DID_name(PMA_ISTART_DID did) {
     switch (did) {
+        case PMA_ISTART_DID::empty:
+            return "DID.empty";
         case PMA_ISTART_DID::memory:
             return "DID.memory";
         case PMA_ISTART_DID::shadow_state:
@@ -54,16 +56,14 @@ static constexpr const char *pmas_get_DID_name(PMA_ISTART_DID did) {
             return "DID.cmio_tx_buffer";
         case PMA_ISTART_DID::shadow_uarch_state:
             return "DID.shadow_uarch";
-        default:
-            return "DID.unknown";
     }
+    return "DID.unknown";
 }
 
 ///< Unpacked attribute flags
 struct pmas_flags {
     bool M;             ///< is memory
     bool IO;            ///< is device
-    bool E;             ///< is empty
     bool R;             ///< is readable
     bool W;             ///< is writeable
     bool X;             ///< is executable
@@ -76,10 +76,9 @@ struct pmas_flags {
 };
 
 static constexpr pmas_flags pmas_unpack_istart(uint64_t istart, uint64_t &start) {
-    start = istart & AR_ISTART_START_MASK;
+    start = istart & PMA_ISTART_START_MASK;
     return pmas_flags{.M = ((istart & PMA_ISTART_M_MASK) >> PMA_ISTART_M_SHIFT) != 0,
         .IO = ((istart & PMA_ISTART_IO_MASK) >> PMA_ISTART_IO_SHIFT) != 0,
-        .E = ((istart & PMA_ISTART_E_MASK) >> PMA_ISTART_E_SHIFT) != 0,
         .R = ((istart & PMA_ISTART_R_MASK) >> PMA_ISTART_R_SHIFT) != 0,
         .W = ((istart & PMA_ISTART_W_MASK) >> PMA_ISTART_W_SHIFT) != 0,
         .X = ((istart & PMA_ISTART_X_MASK) >> PMA_ISTART_X_SHIFT) != 0,
@@ -92,7 +91,6 @@ static constexpr uint64_t pmas_pack_istart(const pmas_flags &flags, uint64_t sta
     uint64_t istart = start;
     istart |= (static_cast<uint64_t>(flags.M) << PMA_ISTART_M_SHIFT);
     istart |= (static_cast<uint64_t>(flags.IO) << PMA_ISTART_IO_SHIFT);
-    istart |= (static_cast<uint64_t>(flags.E) << PMA_ISTART_E_SHIFT);
     istart |= (static_cast<uint64_t>(flags.R) << PMA_ISTART_R_SHIFT);
     istart |= (static_cast<uint64_t>(flags.W) << PMA_ISTART_W_SHIFT);
     istart |= (static_cast<uint64_t>(flags.X) << PMA_ISTART_X_SHIFT);
diff --git a/src/shadow-state-address-range.h b/src/shadow-state-address-range.h
index 45023bb42..d11e7e996 100644
--- a/src/shadow-state-address-range.h
+++ b/src/shadow-state-address-range.h
@@ -20,6 +20,7 @@
 #include <cstddef>
 #include <cstdint>
 
+#include "address-range-constants.h"
 #include "address-range.h"
 #include "shadow-state.h"
 
@@ -32,8 +33,7 @@ class shadow_state_address_range final : public address_range {
 
     static constexpr pmas_flags m_shadow_state_flags{
         .M = false,
-        .IO = true,
-        .E = false,
+        .IO = false,
         .R = false,
         .W = false,
         .X = false,
@@ -44,8 +44,8 @@ class shadow_state_address_range final : public address_range {
 
 public:
     template <typename ABRT>
-    shadow_state_address_range(uint64_t start, uint64_t length, ABRT abrt) :
-        address_range("shadow state", start, length, m_shadow_state_flags, abrt) {
+    explicit shadow_state_address_range(ABRT abrt) :
+        address_range("shadow state", AR_SHADOW_STATE_START, AR_SHADOW_STATE_LENGTH, m_shadow_state_flags, abrt) {
         ;
     }
 
@@ -63,8 +63,8 @@ class shadow_state_address_range final : public address_range {
 };
 
 template <typename ABRT>
-static inline shadow_state_address_range make_shadow_state_address_range(uint64_t start, uint64_t length, ABRT abrt) {
-    return shadow_state_address_range{start, length, abrt};
+static inline shadow_state_address_range make_shadow_state_address_range(ABRT abrt) {
+    return shadow_state_address_range{abrt};
 }
 
 } // namespace cartesi
diff --git a/src/shadow-tlb-address-range.h b/src/shadow-tlb-address-range.h
index 7067e94fe..e82ba76c2 100644
--- a/src/shadow-tlb-address-range.h
+++ b/src/shadow-tlb-address-range.h
@@ -20,6 +20,7 @@
 #include <cstddef>
 #include <cstdint>
 
+#include "address-range-constants.h"
 #include "address-range.h"
 #include "shadow-state.h"
 
@@ -32,8 +33,7 @@ class shadow_tlb_address_range final : public address_range {
 
     static constexpr pmas_flags m_shadow_tlb_flags{
         .M = false,
-        .IO = true,
-        .E = false,
+        .IO = false,
         .R = false,
         .W = false,
         .X = false,
@@ -44,8 +44,8 @@ class shadow_tlb_address_range final : public address_range {
 
 public:
     template <typename ABRT>
-    shadow_tlb_address_range(uint64_t start, uint64_t length, ABRT abrt) :
-        address_range("shadow TLB", start, length, m_shadow_tlb_flags, abrt) {
+    explicit shadow_tlb_address_range(ABRT abrt) :
+        address_range("shadow TLB", AR_SHADOW_TLB_START, AR_SHADOW_TLB_LENGTH, m_shadow_tlb_flags, abrt) {
         ;
     }
 
@@ -63,8 +63,8 @@ class shadow_tlb_address_range final : public address_range {
 };
 
 template <typename ABRT>
-static inline shadow_tlb_address_range make_shadow_tlb_address_range(uint64_t start, uint64_t length, ABRT abrt) {
-    return shadow_tlb_address_range{start, length, abrt};
+static inline shadow_tlb_address_range make_shadow_tlb_address_range(ABRT abrt) {
+    return shadow_tlb_address_range{abrt};
 }
 
 } // namespace cartesi
diff --git a/src/shadow-uarch-state-address-range.h b/src/shadow-uarch-state-address-range.h
index cc2972f5b..025219248 100644
--- a/src/shadow-uarch-state-address-range.h
+++ b/src/shadow-uarch-state-address-range.h
@@ -32,8 +32,7 @@ class shadow_uarch_state_address_range final : public address_range {
 
     static constexpr pmas_flags m_shadow_uarch_state_flags{
         .M = false,
-        .IO = true,
-        .E = false,
+        .IO = false,
         .R = false,
         .W = false,
         .X = false,
diff --git a/src/virtio-address-range.h b/src/virtio-address-range.h
index 337f3b784..1126df5f6 100644
--- a/src/virtio-address-range.h
+++ b/src/virtio-address-range.h
@@ -260,7 +260,6 @@ class virtio_address_range : public pristine_address_range {
     static constexpr pmas_flags m_virtio_flags{
         .M = false,
         .IO = true,
-        .E = false,
         .R = true,
         .W = true,
         .X = false,
diff --git a/tests/lua/cartesi-machine-tests.lua b/tests/lua/cartesi-machine-tests.lua
index dbb7c6fe9..92b09c04e 100755
--- a/tests/lua/cartesi-machine-tests.lua
+++ b/tests/lua/cartesi-machine-tests.lua
@@ -291,7 +291,7 @@ local riscv_tests = {
     { "translate_vaddr.bin", 343 },
     { "htif_invalid_ops.bin", 109 },
     { "clint_ops.bin", 133 },
-    { "shadow_ops.bin", 80 },
+    { "shadow_ops.bin", 78 },
     { "compressed.bin", 410 },
 }
 
diff --git a/tests/lua/htif-cmio.lua b/tests/lua/htif-cmio.lua
index 935732a14..41f73712d 100755
--- a/tests/lua/htif-cmio.lua
+++ b/tests/lua/htif-cmio.lua
@@ -33,7 +33,7 @@ local function stderr(...)
     io.stderr:write(string.format(...))
 end
 
-local final_mcycle = 1835101
+local final_mcycle = 1835100
 local exit_payload = 0
 
 local function test(config)
@@ -48,7 +48,9 @@ local function test(config)
 
     -- check that buffers got filled in with `pattern`
     local tx_length = 1 << cartesi.AR_CMIO_TX_BUFFER_LOG2_SIZE
-    assert(string.rep(pattern, tx_length / 8) == machine:read_memory(cartesi.AR_CMIO_TX_BUFFER_START, tx_length))
+    local expected = string.rep(pattern, tx_length / 8)
+    local got = machine:read_memory(cartesi.AR_CMIO_TX_BUFFER_START, tx_length)
+    assert(expected == got, string.format("expected %q..., (got %q...)", expected:sub(1, 10), got:sub(1, 10)))
 
     assert(machine:read_reg("iflags_H") ~= 0)
 
diff --git a/tests/machine/src/htif_cmio.S b/tests/machine/src/htif_cmio.S
index fbd6f60db..33679ae29 100644
--- a/tests/machine/src/htif_cmio.S
+++ b/tests/machine/src/htif_cmio.S
@@ -26,19 +26,19 @@
  * last entry has length == 0
  *
  * with the following memory layout:
- * +------+--------+--------+------+----+----+---+---+---+---+----+---+
- * |      |        | 63-12  | 11-8 | 7  | 6  | 5 | 4 | 3 | 2 | 1  | 0 |
- * | 0x00 | start  | start  | DID  | IW | IR | X | W | R | E | IO | M |
- * +------+--------+--------+------+----+----+---+---+---+---+----+---+
- * |      |        | 63-11  |                11-0                     |
- * | 0x08 | length | length |             reserved [=0]               |
- * +------+--------+--------+-----------------------------------------+
+ * +------+--------+--------+------+----+----+---+---+---+----+---+
+ * |      |        | 63-12  | 11-7 | 6  | 5  | 4 | 3 | 2 | 1  | 0 |
+ * | 0x00 | start  | start  | DID  | IW | IR | X | W | R | IO | M |
+ * +------+--------+--------+------+----+----+---+---+---+----+---+
+ * |      |        | 63-11  |                11-0                 |
+ * | 0x08 | length | length |             reserved [=0]           |
+ * +------+--------+--------+-------------------------------------+
  */
 #define O_START  0x00
 #define O_LENGTH 0x08
 
-#define PMA_START_DID_CONST(did) ((did) << 8)
-#define PMA_START_DID_MASK    0x0000000000000f00
+#define PMA_START_DID_CONST(did) ((did) << 7)
+#define PMA_START_DID_MASK    0x0000000000000f80
 #define AR_START_START_MASK  0xfffffffffffff000
 
 .global _start
diff --git a/tests/machine/src/shadow_ops.S b/tests/machine/src/shadow_ops.S
index 1c3336f12..f9416554a 100644
--- a/tests/machine/src/shadow_ops.S
+++ b/tests/machine/src/shadow_ops.S
@@ -35,8 +35,6 @@
 #define PMAS_LAST_ENTRY_ISTART (31*16)
 #define PMAS_LAST_ENTRY_ILENGTH (31*16+8)
 #define PMAS_TOTAL_SIZE (32*16)
-#define EMPTY_PMA_ISTART (4)
-#define EMPTY_PMA_ILENGTH (0)
 
 // Section with code
 .section .text.init
@@ -50,11 +48,9 @@ _start:
     // We are allowed to read the shadow PMAs
     li t0, AR_PMAS_START_DEF;
     ld t1, PMAS_LAST_ENTRY_ISTART(t0);
-    li t2, EMPTY_PMA_ISTART
-    bne t1, t2, fail;
+    bnez t1, fail;
     ld t1, PMAS_LAST_ENTRY_ILENGTH(t0);
-    li t2, EMPTY_PMA_ILENGTH
-    bne t1, t2, fail;
+    bnez t1, fail;
 
     // Set the exception handler to skip instructions
     la t0, skip_insn_trap;
diff --git a/tests/misc/test-machine-c-api.cpp b/tests/misc/test-machine-c-api.cpp
index 13e63a628..018173d72 100644
--- a/tests/misc/test-machine-c-api.cpp
+++ b/tests/misc/test-machine-c-api.cpp
@@ -535,7 +535,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(write_memory_invalid_address_range_test, ordinary
     cm_error error_code = cm_write_memory(_machine, address, write_data.data(), write_data.size());
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
     std::string result = cm_get_last_error_message();
-    std::string origin("attempted write to device memory range");
+    std::string origin("address range to write is not entirely in single memory range");
     BOOST_CHECK_EQUAL(origin, result);
 }
 
@@ -628,7 +628,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(write_virtual_memory_invalid_address_range_test,
     cm_error error_code = cm_write_virtual_memory(_machine, address, write_data.data(), write_data.size());
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
     std::string result = cm_get_last_error_message();
-    std::string origin("attempted write to device memory range");
+    std::string origin("address range to write is not entirely in single memory range");
     BOOST_CHECK_EQUAL(origin, result);
 }
 
@@ -825,7 +825,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_null_flash_config_test, ordi
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 
     std::string result = cm_get_last_error_message();
-    std::string origin("attempt to replace a protected range sentinel");
+    std::string origin("attempt to replace inexistent memory range");
     BOOST_CHECK_EQUAL(origin, result);
 }
 

From aadc55278171e2328eca611866376f72f7d638e0 Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Tue, 4 Mar 2025 21:06:53 +0000
Subject: [PATCH 26/82] refactor: rename classes with "virtual" in name

i-virtual-machine        -> i-machine
virtual-machine          -> local-machine
jsonrpc-virtual-machine  -> jsonrpc-machine
clua-i-virtual-machine   -> clua-i-machine
---
 src/Makefile                                  |   9 +-
 src/clua-cartesi-jsonrpc.cpp                  |   4 +-
 src/clua-cartesi.cpp                          |   4 +-
 ...virtual-machine.cpp => clua-i-machine.cpp} |   8 +-
 ...a-i-virtual-machine.h => clua-i-machine.h} |  10 +-
 src/{i-virtual-machine.h => i-machine.h}      |  34 ++---
 src/jsonrpc-machine-c-api.cpp                 |  38 +++---
 ...irtual-machine.cpp => jsonrpc-machine.cpp} | 124 +++++++++---------
 ...pc-virtual-machine.h => jsonrpc-machine.h} |  34 ++---
 ...{virtual-machine.cpp => local-machine.cpp} |  86 ++++++------
 src/{virtual-machine.h => local-machine.h}    |  28 ++--
 src/machine-c-api.cpp                         |  16 +--
 12 files changed, 198 insertions(+), 197 deletions(-)
 rename src/{clua-i-virtual-machine.cpp => clua-i-machine.cpp} (99%)
 rename src/{clua-i-virtual-machine.h => clua-i-machine.h} (96%)
 rename src/{i-virtual-machine.h => i-machine.h} (93%)
 rename src/{jsonrpc-virtual-machine.cpp => jsonrpc-machine.cpp} (85%)
 rename src/{jsonrpc-virtual-machine.h => jsonrpc-machine.h} (87%)
 rename src/{virtual-machine.cpp => local-machine.cpp} (54%)
 rename src/{virtual-machine.h => local-machine.h} (86%)

diff --git a/src/Makefile b/src/Makefile
index 214326e2d..11fc14731 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -375,7 +375,7 @@ LIBCARTESI_OBJS:= \
 	uarch-pristine-state-hash.o \
 	uarch-reset-state.o \
 	uarch-step.o \
-	virtual-machine.o \
+	local-machine.o \
 	uarch-interpret.o \
 	virtio-address-range.o \
 	virtio-console-address-range.o \
@@ -386,7 +386,10 @@ LIBCARTESI_OBJS:= \
 
 CARTESI_CLUA_OBJS:= \
 	clua.o \
-	clua-i-virtual-machine.o
+	clua-i-machine.o \
+	uarch-pristine-ram.o \
+	uarch-pristine-state-hash.o \
+	uarch-pristine-hash.o
 
 LUACARTESI_OBJS:= \
 	clua-cartesi.o \
@@ -404,7 +407,7 @@ CARTESI_MERKLE_TREE_HASH_OBJS:= \
 	merkle-tree-hash.o
 
 LIBCARTESI_JSONRPC_OBJS:= \
-	jsonrpc-virtual-machine.o \
+	jsonrpc-machine.o \
 	os.o \
 	jsonrpc-machine-c-api.o \
 	base64.o \
diff --git a/src/clua-cartesi-jsonrpc.cpp b/src/clua-cartesi-jsonrpc.cpp
index 2f57229bb..326858718 100644
--- a/src/clua-cartesi-jsonrpc.cpp
+++ b/src/clua-cartesi-jsonrpc.cpp
@@ -21,7 +21,7 @@ extern "C" {
 #include <lua.h>
 }
 
-#include "clua-i-virtual-machine.h"
+#include "clua-i-machine.h"
 #include "clua.h"
 #include "jsonrpc-machine-c-api.h"
 #include "machine-c-api.h"
@@ -214,7 +214,7 @@ CM_API int luaopen_cartesi_jsonrpc(lua_State *L) {
     clua_init(L);    // cluactx
     lua_newtable(L); // cluactx jsonrpc
     // Initialize and export jsonrpc machine bind
-    clua_i_virtual_machine_export(L, -2);                                                         // cluactx jsonrpc
+    clua_i_machine_export(L, -2);                                                                 // cluactx jsonrpc
     clua_setmethods<clua_managed_cm_ptr<cm_machine>>(L, jsonrpc_machine_obj_index.data(), 0, -2); // cluactx jsonrpc
     // Set module functions
     lua_pushvalue(L, -2);            // cluactx jsonrpc cluactx
diff --git a/src/clua-cartesi.cpp b/src/clua-cartesi.cpp
index f39ee3250..1326f0806 100644
--- a/src/clua-cartesi.cpp
+++ b/src/clua-cartesi.cpp
@@ -28,7 +28,7 @@ extern "C" {
 }
 
 #include "base64.h"
-#include "clua-i-virtual-machine.h"
+#include "clua-i-machine.h"
 #include "clua.h"
 #include "keccak-256-hasher.h"
 #include "machine-c-api.h"
@@ -181,7 +181,7 @@ CM_API int luaopen_cartesi(lua_State *L) {
     clua_init(L);    // cluactx
     lua_newtable(L); // cluactx cartesi
     // Initialize and export machine bind
-    clua_i_virtual_machine_export(L, -2); // cluactx cartesi
+    clua_i_machine_export(L, -2); // cluactx cartesi
     // Set module functions
     lua_pushvalue(L, -2);                                                    // cluactx cartesi cluactx
     luaL_setfuncs(L, cartesi_mod.data(), 1);                                 // cluactx cartesi
diff --git a/src/clua-i-virtual-machine.cpp b/src/clua-i-machine.cpp
similarity index 99%
rename from src/clua-i-virtual-machine.cpp
rename to src/clua-i-machine.cpp
index 0380f23a7..66c3c3601 100644
--- a/src/clua-i-virtual-machine.cpp
+++ b/src/clua-i-machine.cpp
@@ -14,7 +14,7 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#include "clua-i-virtual-machine.h"
+#include "clua-i-machine.h"
 
 #include <algorithm>
 #include <cassert>
@@ -1120,7 +1120,7 @@ static const auto machine_meta = cartesi::clua_make_luaL_Reg_array({
     {"__call", machine_meta_call},
 });
 
-int clua_i_virtual_machine_init(lua_State *L, int ctxidx) {
+int clua_i_machine_init(lua_State *L, int ctxidx) {
     clua_createnewtype<clua_managed_cm_ptr<unsigned char>>(L, ctxidx);
     clua_createnewtype<clua_managed_cm_ptr<std::string>>(L, ctxidx);
     clua_createnewtype<clua_managed_cm_ptr<nlohmann::json>>(L, ctxidx);
@@ -1132,8 +1132,8 @@ int clua_i_virtual_machine_init(lua_State *L, int ctxidx) {
     return 0;
 }
 
-int clua_i_virtual_machine_export(lua_State *L, int ctxidx) {
-    clua_i_virtual_machine_init(L, ctxidx);
+int clua_i_machine_export(lua_State *L, int ctxidx) {
+    clua_i_machine_init(L, ctxidx);
     return 0;
 }
 
diff --git a/src/clua-i-virtual-machine.h b/src/clua-i-machine.h
similarity index 96%
rename from src/clua-i-virtual-machine.h
rename to src/clua-i-machine.h
index aef3b4217..584ea08ce 100644
--- a/src/clua-i-virtual-machine.h
+++ b/src/clua-i-machine.h
@@ -14,15 +14,15 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#ifndef CLUA_I_VIRTUAL_MACHINE_H
-#define CLUA_I_VIRTUAL_MACHINE_H
+#ifndef CLUA_I_MACHINE_H
+#define CLUA_I_MACHINE_H
 
 #include <memory>
 #include <string>
 #include <utility>
 
 #include "clua.h"
-#include "i-virtual-machine.h"
+#include "i-machine.h"
 #include "json-util.h"
 #include "machine-c-api.h"
 
@@ -34,12 +34,12 @@ namespace cartesi {
 /// \brief Initialize Cartesi machine Lua interface
 /// \param L Lua state
 /// \param ctxidx Index of Clua context
-int clua_i_virtual_machine_init(lua_State *L, int ctxidx);
+int clua_i_machine_init(lua_State *L, int ctxidx);
 
 /// \brief Exports symbols to table on top of Lua stack
 /// \param L Lua state
 /// \param ctxidx Index of Clua context
-int clua_i_virtual_machine_export(lua_State *L, int ctxidx);
+int clua_i_machine_export(lua_State *L, int ctxidx);
 
 /// \brief Deleter for C data buffer
 void clua_delete(unsigned char *ptr);
diff --git a/src/i-virtual-machine.h b/src/i-machine.h
similarity index 93%
rename from src/i-virtual-machine.h
rename to src/i-machine.h
index b307d8d6d..ee82aa6be 100644
--- a/src/i-virtual-machine.h
+++ b/src/i-machine.h
@@ -14,8 +14,8 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#ifndef I_VIRTUAL_MACHINE_H
-#define I_VIRTUAL_MACHINE_H
+#ifndef I_MACHINE_H
+#define I_MACHINE_H
 
 #include <cstdint>
 #include <string>
@@ -30,7 +30,7 @@
 
 namespace cartesi {
 
-/// \class i_virtual_machine
+/// \class i_machine
 /// \brief Interface representing the public API of the Cartesi machine.
 /// \details \{
 /// Allows clients to reference this interface in order to transparently
@@ -42,24 +42,24 @@ namespace cartesi {
 /// Classes implementing this interface are required to provide
 /// implementations for the pure virtual methods.
 /// \}
-class i_virtual_machine {
+class i_machine {
 public:
     using hash_type = machine_merkle_tree::hash_type;
     using reg = machine_reg;
 
     /// \brief Constructor
-    i_virtual_machine() = default;
+    i_machine() = default;
 
     /// \brief Destructor.
-    virtual ~i_virtual_machine() = default;
+    virtual ~i_machine() = default;
 
-    i_virtual_machine(const i_virtual_machine &other) = delete;
-    i_virtual_machine(i_virtual_machine &&other) noexcept = delete;
-    i_virtual_machine &operator=(const i_virtual_machine &other) = delete;
-    i_virtual_machine &operator=(i_virtual_machine &&other) noexcept = delete;
+    i_machine(const i_machine &other) = delete;
+    i_machine(i_machine &&other) noexcept = delete;
+    i_machine &operator=(const i_machine &other) = delete;
+    i_machine &operator=(i_machine &&other) noexcept = delete;
 
     /// \brief Clone an object of same underlying type but without a machine instance
-    i_virtual_machine *clone_empty() const {
+    i_machine *clone_empty() const {
         return do_clone_empty();
     }
 
@@ -249,13 +249,13 @@ class i_virtual_machine {
         do_verify_send_cmio_response(reason, data, length, root_hash_before, log, root_hash_after);
     }
 
-    /// \brief Checks if implementation is jsorpc-virtual-machine
-    bool is_jsonrpc_virtual_machine() const {
-        return do_is_jsonrpc_virtual_machine();
+    /// \brief Checks if implementation is jsorpc-machine
+    bool is_jsonrpc_machine() const {
+        return do_is_jsonrpc_machine();
     }
 
 private:
-    virtual i_virtual_machine *do_clone_empty() const = 0;
+    virtual i_machine *do_clone_empty() const = 0;
     virtual bool do_is_empty() const = 0;
     virtual void do_create(const machine_config &config, const machine_runtime_config &runtime) = 0;
     virtual void do_load(const std::string &directory, const machine_runtime_config &runtime) = 0;
@@ -297,11 +297,11 @@ class i_virtual_machine {
         const hash_type &root_hash_after) const = 0;
     virtual void do_verify_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
         const hash_type &root_hash_before, const access_log &log, const hash_type &root_hash_after) const = 0;
-    virtual bool do_is_jsonrpc_virtual_machine() const {
+    virtual bool do_is_jsonrpc_machine() const {
         return false;
     }
 };
 
 } // namespace cartesi
 
-#endif // I_VIRTUAL_MACHINE_H
+#endif // I_MACHINE_H
diff --git a/src/jsonrpc-machine-c-api.cpp b/src/jsonrpc-machine-c-api.cpp
index 30f4d5a4e..75f9ba296 100644
--- a/src/jsonrpc-machine-c-api.cpp
+++ b/src/jsonrpc-machine-c-api.cpp
@@ -24,60 +24,60 @@
 #include <stdexcept>
 #include <string>
 
-#include "i-virtual-machine.h"
+#include "i-machine.h"
 #include "json-util.h"
 #include "jsonrpc-fork-result.h"
-#include "jsonrpc-virtual-machine.h"
+#include "jsonrpc-machine.h"
 #include "machine-c-api-internal.h"
 #include "machine-c-api.h"
 
 using namespace std::string_literals;
 
-static cartesi::jsonrpc_virtual_machine::cleanup_call convert_from_c(cm_jsonrpc_cleanup_call call) {
+static cartesi::jsonrpc_machine::cleanup_call convert_from_c(cm_jsonrpc_cleanup_call call) {
     switch (call) {
         case CM_JSONRPC_DESTROY:
-            return cartesi::jsonrpc_virtual_machine::cleanup_call::destroy;
+            return cartesi::jsonrpc_machine::cleanup_call::destroy;
         case CM_JSONRPC_SHUTDOWN:
-            return cartesi::jsonrpc_virtual_machine::cleanup_call::shutdown;
+            return cartesi::jsonrpc_machine::cleanup_call::shutdown;
         case CM_JSONRPC_NOTHING:
-            return cartesi::jsonrpc_virtual_machine::cleanup_call::nothing;
+            return cartesi::jsonrpc_machine::cleanup_call::nothing;
         default:
             throw std::invalid_argument("invalid cleanup call");
     }
 }
 
-static cm_jsonrpc_cleanup_call convert_to_c(cartesi::jsonrpc_virtual_machine::cleanup_call call) {
+static cm_jsonrpc_cleanup_call convert_to_c(cartesi::jsonrpc_machine::cleanup_call call) {
     switch (call) {
-        case cartesi::jsonrpc_virtual_machine::cleanup_call::destroy:
+        case cartesi::jsonrpc_machine::cleanup_call::destroy:
             return CM_JSONRPC_DESTROY;
-        case cartesi::jsonrpc_virtual_machine::cleanup_call::shutdown:
+        case cartesi::jsonrpc_machine::cleanup_call::shutdown:
             return CM_JSONRPC_SHUTDOWN;
-        case cartesi::jsonrpc_virtual_machine::cleanup_call::nothing:
+        case cartesi::jsonrpc_machine::cleanup_call::nothing:
             return CM_JSONRPC_NOTHING;
         default:
             throw std::invalid_argument("invalid cleanup call");
     }
 }
 
-static cartesi::jsonrpc_virtual_machine *convert_from_c(cm_machine *m) {
+static cartesi::jsonrpc_machine *convert_from_c(cm_machine *m) {
     if (m == nullptr) {
         throw std::invalid_argument("invalid machine");
     }
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-    auto *cpp_m = reinterpret_cast<cartesi::i_virtual_machine *>(m);
-    if (!cpp_m->is_jsonrpc_virtual_machine()) {
+    auto *cpp_m = reinterpret_cast<cartesi::i_machine *>(m);
+    if (!cpp_m->is_jsonrpc_machine()) {
         throw std::invalid_argument("not a JSONRPC remote machine");
     }
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-    return reinterpret_cast<cartesi::jsonrpc_virtual_machine *>(m);
+    return reinterpret_cast<cartesi::jsonrpc_machine *>(m);
 }
 
-static const cartesi::jsonrpc_virtual_machine *convert_from_c(const cm_machine *m) {
+static const cartesi::jsonrpc_machine *convert_from_c(const cm_machine *m) {
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-const-cast)
     return convert_from_c(const_cast<cm_machine *>(m));
 }
 
-static cm_machine *convert_to_c(cartesi::i_virtual_machine *cpp_m) {
+static cm_machine *convert_to_c(cartesi::i_machine *cpp_m) {
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
     return reinterpret_cast<cm_machine *>(cpp_m);
 }
@@ -90,7 +90,7 @@ cm_error cm_jsonrpc_connect_server(const char *address, int64_t connect_timeout_
     if (new_m == nullptr) {
         throw std::invalid_argument("invalid new machine output");
     }
-    *new_m = convert_to_c(new jsonrpc_virtual_machine(address, connect_timeout_ms));
+    *new_m = convert_to_c(new jsonrpc_machine(address, connect_timeout_ms));
     return cm_result_success();
 } catch (...) {
     if (new_m != nullptr) {
@@ -109,7 +109,7 @@ cm_error cm_jsonrpc_spawn_server(const char *address, int64_t spawn_timeout_ms,
         throw std::invalid_argument("invalid new machine output");
     }
     fork_result spawned;
-    *new_m = convert_to_c(new jsonrpc_virtual_machine(address, spawn_timeout_ms, spawned));
+    *new_m = convert_to_c(new jsonrpc_machine(address, spawn_timeout_ms, spawned));
     if (bound_address != nullptr) {
         *bound_address = cm_set_temp_string(spawned.address);
     }
@@ -144,7 +144,7 @@ cm_error cm_jsonrpc_fork_server(const cm_machine *m, cm_machine **forked_m, cons
     if (pid != nullptr) {
         *pid = forked.pid;
     }
-    auto *cpp_forked_m = new jsonrpc_virtual_machine(forked.address);
+    auto *cpp_forked_m = new jsonrpc_machine(forked.address);
     cpp_forked_m->set_cleanup_call(cpp_m->get_cleanup_call());
     cpp_forked_m->set_timeout(cpp_m->get_timeout());
     *forked_m = convert_to_c(cpp_forked_m);
diff --git a/src/jsonrpc-virtual-machine.cpp b/src/jsonrpc-machine.cpp
similarity index 85%
rename from src/jsonrpc-virtual-machine.cpp
rename to src/jsonrpc-machine.cpp
index c2606d5bb..44ffe334e 100644
--- a/src/jsonrpc-virtual-machine.cpp
+++ b/src/jsonrpc-machine.cpp
@@ -14,7 +14,7 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#include "jsonrpc-virtual-machine.h"
+#include "jsonrpc-machine.h"
 #include "os-features.h"
 
 #include <cassert>
@@ -63,7 +63,7 @@
 #include "access-log.h"
 #include "address-range-description.h"
 #include "base64.h"
-#include "i-virtual-machine.h"
+#include "i-machine.h"
 #include "interpret.h"
 #include "json-util.h"
 #include "jsonrpc-fork-result.h"
@@ -331,7 +331,7 @@ static void jsonrpc_request(std::unique_ptr<boost::asio::io_context> &ioc, std::
 namespace cartesi {
 
 template <typename R, typename... Ts>
-void jsonrpc_virtual_machine::request(const std::string &method, const std::tuple<Ts...> &tp, R &result,
+void jsonrpc_machine::request(const std::string &method, const std::tuple<Ts...> &tp, R &result,
     bool keep_alive) const {
     // Determine request timeout time
     const auto timeout_at = m_timeout >= 0 ? (std::chrono::steady_clock::now() + std::chrono::milliseconds(m_timeout)) :
@@ -341,12 +341,12 @@ void jsonrpc_virtual_machine::request(const std::string &method, const std::tupl
 }
 
 template <typename R, typename... Ts>
-void jsonrpc_virtual_machine::request(const std::string &method, const std::tuple<Ts...> &tp, R &result,
+void jsonrpc_machine::request(const std::string &method, const std::tuple<Ts...> &tp, R &result,
     std::chrono::time_point<std::chrono::steady_clock> timeout_at, bool keep_alive) const {
     jsonrpc_request(m_ioc, m_stream, m_address, method, tp, result, timeout_at, keep_alive);
 }
 
-void jsonrpc_virtual_machine::shutdown_server() {
+void jsonrpc_machine::shutdown_server() {
     bool result = false;
     request("shutdown", std::tie(), result, false);
     // Destroy ASIO context early to release its socket before the destructor,
@@ -356,28 +356,28 @@ void jsonrpc_virtual_machine::shutdown_server() {
     m_ioc.reset();
 }
 
-void jsonrpc_virtual_machine::delay_next_request(uint64_t ms) const {
+void jsonrpc_machine::delay_next_request(uint64_t ms) const {
     bool result = false;
     request("delay_next_request", std::tie(ms), result);
 }
 
-void jsonrpc_virtual_machine::set_timeout(int64_t ms) {
+void jsonrpc_machine::set_timeout(int64_t ms) {
     m_timeout = ms;
 }
 
-int64_t jsonrpc_virtual_machine::get_timeout() const {
+int64_t jsonrpc_machine::get_timeout() const {
     return m_timeout;
 }
 
-void jsonrpc_virtual_machine::set_cleanup_call(cleanup_call call) {
+void jsonrpc_machine::set_cleanup_call(cleanup_call call) {
     m_call = call;
 }
 
-auto jsonrpc_virtual_machine::get_cleanup_call() const -> cleanup_call {
+auto jsonrpc_machine::get_cleanup_call() const -> cleanup_call {
     return m_call;
 }
 
-const std::string &jsonrpc_virtual_machine::get_server_address() const {
+const std::string &jsonrpc_machine::get_server_address() const {
     return m_address;
 }
 
@@ -385,8 +385,7 @@ static inline std::string semver_to_string(uint32_t major, uint32_t minor) {
     return std::to_string(major) + "." + std::to_string(minor);
 }
 
-void jsonrpc_virtual_machine::check_server_version(
-    std::chrono::time_point<std::chrono::steady_clock> timeout_at) const {
+void jsonrpc_machine::check_server_version(std::chrono::time_point<std::chrono::steady_clock> timeout_at) const {
     semantic_version server_version;
     request("get_version", std::tie(), server_version, timeout_at, false);
     if (server_version.major != JSONRPC_VERSION_MAJOR || server_version.minor != JSONRPC_VERSION_MINOR) {
@@ -396,7 +395,7 @@ void jsonrpc_virtual_machine::check_server_version(
     }
 }
 
-jsonrpc_virtual_machine::jsonrpc_virtual_machine(std::string address, int64_t connect_timeout_ms) :
+jsonrpc_machine::jsonrpc_machine(std::string address, int64_t connect_timeout_ms) :
     m_ioc(new boost::asio::io_context{1}),
     m_stream(new boost::beast::tcp_stream(*m_ioc)),
     m_address(std::move(address)) {
@@ -412,7 +411,7 @@ jsonrpc_virtual_machine::jsonrpc_virtual_machine(std::string address, int64_t co
     check_server_version(timeout_at);
 }
 
-jsonrpc_virtual_machine::jsonrpc_virtual_machine(std::string address) :
+jsonrpc_machine::jsonrpc_machine(std::string address) :
     m_ioc(new boost::asio::io_context{1}),
     m_stream(new boost::beast::tcp_stream(*m_ioc)),
     m_address(std::move(address)) {
@@ -442,8 +441,7 @@ static std::string endpoint_to_string(const boost::asio::ip::tcp::endpoint &endp
     return ss.str();
 }
 
-jsonrpc_virtual_machine::jsonrpc_virtual_machine(const std::string &address, int64_t spawn_timeout_ms,
-    fork_result &spawned) :
+jsonrpc_machine::jsonrpc_machine(const std::string &address, int64_t spawn_timeout_ms, fork_result &spawned) :
     m_ioc(new boost::asio::io_context{1}),
     m_stream(new boost::beast::tcp_stream(*m_ioc)),
     m_call(cleanup_call::shutdown) {
@@ -552,26 +550,26 @@ jsonrpc_virtual_machine::jsonrpc_virtual_machine(const std::string &address, int
 
 #else
 
-jsonrpc_virtual_machine::jsonrpc_virtual_machine(const std::string & /*address*/, fork_result & /*spawned*/) {
+jsonrpc_machine::jsonrpc_machine(const std::string & /*address*/, fork_result & /*spawned*/) {
     throw std::runtime_error{"fork() is unsupported in this platform"s};
 }
 
 #endif
 
-void jsonrpc_virtual_machine::do_load(const std::string &directory, const machine_runtime_config &runtime) {
+void jsonrpc_machine::do_load(const std::string &directory, const machine_runtime_config &runtime) {
     bool result = false;
     request("machine.load", std::tie(directory, runtime), result);
 }
 
-bool jsonrpc_virtual_machine::do_is_empty() const {
+bool jsonrpc_machine::do_is_empty() const {
     bool result = false;
     request("machine.is_empty", std::tie(), result);
     return result;
 }
 
-i_virtual_machine *jsonrpc_virtual_machine::do_clone_empty() const {
+i_machine *jsonrpc_machine::do_clone_empty() const {
     auto fork_result = fork_server();
-    auto *clone = new jsonrpc_virtual_machine(fork_result.address);
+    auto *clone = new jsonrpc_machine(fork_result.address);
     try {
         if (!clone->is_empty()) {
             clone->destroy();
@@ -588,12 +586,12 @@ i_virtual_machine *jsonrpc_virtual_machine::do_clone_empty() const {
     return clone;
 };
 
-void jsonrpc_virtual_machine::do_create(const machine_config &config, const machine_runtime_config &runtime) {
+void jsonrpc_machine::do_create(const machine_config &config, const machine_runtime_config &runtime) {
     bool result = false;
     request("machine.create", std::tie(config, runtime), result);
 }
 
-jsonrpc_virtual_machine::~jsonrpc_virtual_machine() {
+jsonrpc_machine::~jsonrpc_machine() {
     // If configured to destroy machine, do it
     if (m_stream && m_call == cleanup_call::destroy) {
         try {
@@ -618,76 +616,76 @@ jsonrpc_virtual_machine::~jsonrpc_virtual_machine() {
     }
 }
 
-machine_config jsonrpc_virtual_machine::do_get_initial_config() const {
+machine_config jsonrpc_machine::do_get_initial_config() const {
     machine_config result;
     request("machine.get_initial_config", std::tie(), result);
     return result;
 }
 
-machine_runtime_config jsonrpc_virtual_machine::do_get_runtime_config() const {
+machine_runtime_config jsonrpc_machine::do_get_runtime_config() const {
     machine_runtime_config result;
     request("machine.get_runtime_config", std::tie(), result);
     return result;
 }
 
-void jsonrpc_virtual_machine::do_set_runtime_config(const machine_runtime_config &r) {
+void jsonrpc_machine::do_set_runtime_config(const machine_runtime_config &r) {
     bool result = false;
     request("machine.set_runtime_config", std::tie(r), result);
 }
 
-semantic_version jsonrpc_virtual_machine::get_server_version() const {
+semantic_version jsonrpc_machine::get_server_version() const {
     semantic_version result;
     request("get_version", std::tie(), result);
     return result;
 }
 
-interpreter_break_reason jsonrpc_virtual_machine::do_run(uint64_t mcycle_end) {
+interpreter_break_reason jsonrpc_machine::do_run(uint64_t mcycle_end) {
     interpreter_break_reason result = interpreter_break_reason::failed;
     request("machine.run", std::tie(mcycle_end), result);
     return result;
 }
 
-interpreter_break_reason jsonrpc_virtual_machine::do_log_step(uint64_t mcycle_count, const std::string &filename) {
+interpreter_break_reason jsonrpc_machine::do_log_step(uint64_t mcycle_count, const std::string &filename) {
     interpreter_break_reason result = interpreter_break_reason::failed;
     request("machine.log_step", std::tie(mcycle_count, filename), result);
     return result;
 }
 
-void jsonrpc_virtual_machine::do_store(const std::string &directory) const {
+void jsonrpc_machine::do_store(const std::string &directory) const {
     bool result = false;
     request("machine.store", std::tie(directory), result);
 }
 
-uint64_t jsonrpc_virtual_machine::do_read_reg(reg r) const {
+uint64_t jsonrpc_machine::do_read_reg(reg r) const {
     uint64_t result = 0;
     request("machine.read_reg", std::tie(r), result);
     return result;
 }
 
-void jsonrpc_virtual_machine::do_write_reg(reg w, uint64_t val) {
+void jsonrpc_machine::do_write_reg(reg w, uint64_t val) {
     bool result = false;
     request("machine.write_reg", std::tie(w, val), result);
 }
 
-auto jsonrpc_virtual_machine::fork_server() const -> fork_result {
+auto jsonrpc_machine::fork_server() const -> fork_result {
     fork_result result{};
     request("fork", std::tie(), result, false);
     return result;
 }
 
-std::string jsonrpc_virtual_machine::rebind_server(const std::string &address) {
+std::string jsonrpc_machine::rebind_server(const std::string &address) {
     std::string result;
     request("rebind", std::tie(address), result, false);
     m_address = result;
     return result;
 }
 
-void jsonrpc_virtual_machine::emancipate_server() const {
+void jsonrpc_machine::emancipate_server() const {
     bool result = false;
     request("emancipate", std::tie(), result);
 }
 
-void jsonrpc_virtual_machine::do_read_memory(uint64_t address, unsigned char *data, uint64_t length) const {
+void jsonrpc_machine::do_read_memory(uint64_t address, unsigned char *data, uint64_t length) const {
     std::string result;
     request("machine.read_memory", std::tie(address, length), result);
     std::string bin = cartesi::decode_base64(result);
@@ -697,13 +695,13 @@ void jsonrpc_virtual_machine::do_read_memory(uint64_t address, unsigned char *da
     std::memcpy(data, bin.data(), length);
 }
 
-void jsonrpc_virtual_machine::do_write_memory(uint64_t address, const unsigned char *data, uint64_t length) {
+void jsonrpc_machine::do_write_memory(uint64_t address, const unsigned char *data, uint64_t length) {
     bool result = false;
     std::string b64 = cartesi::encode_base64(data, length);
     request("machine.write_memory", std::tie(address, b64), result);
 }
 
-void jsonrpc_virtual_machine::do_read_virtual_memory(uint64_t address, unsigned char *data, uint64_t length) {
+void jsonrpc_machine::do_read_virtual_memory(uint64_t address, unsigned char *data, uint64_t length) {
     std::string result;
     request("machine.read_virtual_memory", std::tie(address, length), result);
     std::string bin = cartesi::decode_base64(result);
@@ -713,24 +711,24 @@ void jsonrpc_virtual_machine::do_read_virtual_memory(uint64_t address, unsigned
     std::memcpy(data, bin.data(), length);
 }
 
-void jsonrpc_virtual_machine::do_write_virtual_memory(uint64_t address, const unsigned char *data, uint64_t length) {
+void jsonrpc_machine::do_write_virtual_memory(uint64_t address, const unsigned char *data, uint64_t length) {
     bool result = false;
     std::string b64 = cartesi::encode_base64(data, length);
     request("machine.write_virtual_memory", std::tie(address, b64), result);
 }
 
-uint64_t jsonrpc_virtual_machine::do_translate_virtual_address(uint64_t vaddr) {
+uint64_t jsonrpc_machine::do_translate_virtual_address(uint64_t vaddr) {
     uint64_t result = 0;
     request("machine.translate_virtual_address", std::tie(vaddr), result);
     return result;
 }
 
-void jsonrpc_virtual_machine::do_reset_uarch() {
+void jsonrpc_machine::do_reset_uarch() {
     bool result = false;
     request("machine.reset_uarch", std::tie(), result);
 }
 
-access_log jsonrpc_virtual_machine::do_log_reset_uarch(const access_log::type &log_type) {
+access_log jsonrpc_machine::do_log_reset_uarch(const access_log::type &log_type) {
     not_default_constructible<access_log> result;
     request("machine.log_reset_uarch", std::tie(log_type), result);
     if (!result.has_value()) {
@@ -739,11 +737,11 @@ access_log jsonrpc_virtual_machine::do_log_reset_uarch(const access_log::type &l
     return std::move(result).value();
 }
 
-void jsonrpc_virtual_machine::do_get_root_hash(hash_type &hash) const {
+void jsonrpc_machine::do_get_root_hash(hash_type &hash) const {
     request("machine.get_root_hash", std::tie(), hash);
 }
 
-machine_merkle_tree::proof_type jsonrpc_virtual_machine::do_get_proof(uint64_t address, int log2_size) const {
+machine_merkle_tree::proof_type jsonrpc_machine::do_get_proof(uint64_t address, int log2_size) const {
     not_default_constructible<machine_merkle_tree::proof_type> result;
     request("machine.get_proof", std::tie(address, log2_size), result);
     if (!result.has_value()) {
@@ -752,12 +750,12 @@ machine_merkle_tree::proof_type jsonrpc_virtual_machine::do_get_proof(uint64_t a
     return std::move(result).value();
 }
 
-void jsonrpc_virtual_machine::do_replace_memory_range(const memory_range_config &new_range) {
+void jsonrpc_machine::do_replace_memory_range(const memory_range_config &new_range) {
     bool result = false;
     request("machine.replace_memory_range", std::tie(new_range), result);
 }
 
-access_log jsonrpc_virtual_machine::do_log_step_uarch(const access_log::type &log_type) {
+access_log jsonrpc_machine::do_log_step_uarch(const access_log::type &log_type) {
     not_default_constructible<access_log> result;
     request("machine.log_step_uarch", std::tie(log_type), result);
     if (!result.has_value()) {
@@ -766,49 +764,49 @@ access_log jsonrpc_virtual_machine::do_log_step_uarch(const access_log::type &lo
     return std::move(result).value();
 }
 
-void jsonrpc_virtual_machine::do_destroy() {
+void jsonrpc_machine::do_destroy() {
     bool result = false;
     request("machine.destroy", std::tie(), result);
 }
 
-bool jsonrpc_virtual_machine::do_verify_dirty_page_maps() const {
+bool jsonrpc_machine::do_verify_dirty_page_maps() const {
     bool result = false;
     request("machine.verify_dirty_page_maps", std::tie(), result);
     return result;
 }
 
-uint64_t jsonrpc_virtual_machine::do_read_word(uint64_t address) const {
+uint64_t jsonrpc_machine::do_read_word(uint64_t address) const {
     uint64_t result = 0;
     request("machine.read_word", std::tie(address), result);
     return result;
 }
 
-bool jsonrpc_virtual_machine::do_verify_merkle_tree() const {
+bool jsonrpc_machine::do_verify_merkle_tree() const {
     bool result = false;
     request("machine.verify_merkle_tree", std::tie(), result);
     return result;
 }
 
-uarch_interpreter_break_reason jsonrpc_virtual_machine::do_run_uarch(uint64_t uarch_cycle_end) {
+uarch_interpreter_break_reason jsonrpc_machine::do_run_uarch(uint64_t uarch_cycle_end) {
     uarch_interpreter_break_reason result = uarch_interpreter_break_reason::reached_target_cycle;
     request("machine.run_uarch", std::tie(uarch_cycle_end), result);
     return result;
 }
 
-address_range_descriptions jsonrpc_virtual_machine::do_get_address_ranges() const {
+address_range_descriptions jsonrpc_machine::do_get_address_ranges() const {
     address_range_descriptions result;
     request("machine.get_address_ranges", std::tie(), result);
     return result;
 }
 
-void jsonrpc_virtual_machine::do_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length) {
+void jsonrpc_machine::do_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length) {
     bool result = false;
     std::string b64 = cartesi::encode_base64(data, length);
     request("machine.send_cmio_response", std::tie(reason, b64), result);
 }
 
-access_log jsonrpc_virtual_machine::do_log_send_cmio_response(uint16_t reason, const unsigned char *data,
-    uint64_t length, const access_log::type &log_type) {
+access_log jsonrpc_machine::do_log_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
+    const access_log::type &log_type) {
     not_default_constructible<access_log> result;
     std::string b64 = cartesi::encode_base64(data, length);
     request("machine.log_send_cmio_response", std::tie(reason, b64, log_type), result);
@@ -818,19 +816,19 @@ access_log jsonrpc_virtual_machine::do_log_send_cmio_response(uint16_t reason, c
     return std::move(result).value();
 }
 
-uint64_t jsonrpc_virtual_machine::do_get_reg_address(reg r) const {
+uint64_t jsonrpc_machine::do_get_reg_address(reg r) const {
     uint64_t result = 0;
     request("machine.get_reg_address", std::tie(r), result);
     return result;
 }
 
-machine_config jsonrpc_virtual_machine::do_get_default_config() const {
+machine_config jsonrpc_machine::do_get_default_config() const {
     machine_config result;
     request("machine.get_default_config", std::tie(), result);
     return result;
 }
 
-interpreter_break_reason jsonrpc_virtual_machine::do_verify_step(const hash_type &root_hash_before,
+interpreter_break_reason jsonrpc_machine::do_verify_step(const hash_type &root_hash_before,
     const std::string &log_filename, uint64_t mcycle_count, const hash_type &root_hash_after) const {
     interpreter_break_reason result = interpreter_break_reason::failed;
     auto b64_root_hash_before = encode_base64(root_hash_before);
@@ -840,7 +838,7 @@ interpreter_break_reason jsonrpc_virtual_machine::do_verify_step(const hash_type
     return result;
 }
 
-void jsonrpc_virtual_machine::do_verify_step_uarch(const hash_type &root_hash_before, const access_log &log,
+void jsonrpc_machine::do_verify_step_uarch(const hash_type &root_hash_before, const access_log &log,
     const hash_type &root_hash_after) const {
     bool result = false;
     auto b64_root_hash_before = encode_base64(root_hash_before);
@@ -848,7 +846,7 @@ void jsonrpc_virtual_machine::do_verify_step_uarch(const hash_type &root_hash_be
     request("machine.verify_step_uarch", std::tie(b64_root_hash_before, log, b64_root_hash_after), result);
 }
 
-void jsonrpc_virtual_machine::do_verify_reset_uarch(const hash_type &root_hash_before, const access_log &log,
+void jsonrpc_machine::do_verify_reset_uarch(const hash_type &root_hash_before, const access_log &log,
     const hash_type &root_hash_after) const {
     bool result = false;
     auto b64_root_hash_before = encode_base64(root_hash_before);
@@ -856,7 +854,7 @@ void jsonrpc_virtual_machine::do_verify_reset_uarch(const hash_type &root_hash_b
     request("machine.verify_reset_uarch", std::tie(b64_root_hash_before, log, b64_root_hash_after), result);
 }
 
-void jsonrpc_virtual_machine::do_verify_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
+void jsonrpc_machine::do_verify_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
     const hash_type &root_hash_before, const access_log &log, const hash_type &root_hash_after) const {
     bool result = false;
     std::string b64_data = cartesi::encode_base64(data, length);
@@ -866,7 +864,7 @@ void jsonrpc_virtual_machine::do_verify_send_cmio_response(uint16_t reason, cons
         std::tie(reason, b64_data, b64_root_hash_before, log, b64_root_hash_after), result);
 }
 
-bool jsonrpc_virtual_machine::do_is_jsonrpc_virtual_machine() const {
+bool jsonrpc_machine::do_is_jsonrpc_machine() const {
     return true;
 }
 
diff --git a/src/jsonrpc-virtual-machine.h b/src/jsonrpc-machine.h
similarity index 87%
rename from src/jsonrpc-virtual-machine.h
rename to src/jsonrpc-machine.h
index 3cd564829..5bee677a8 100644
--- a/src/jsonrpc-virtual-machine.h
+++ b/src/jsonrpc-machine.h
@@ -14,8 +14,8 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#ifndef JSONRPC_VIRTUAL_MACHINE_H
-#define JSONRPC_VIRTUAL_MACHINE_H
+#ifndef JSONRPC_MACHINE_H
+#define JSONRPC_MACHINE_H
 
 #include <cstdint>
 #include <memory>
@@ -23,7 +23,7 @@
 
 #include "access-log.h"
 #include "address-range-description.h"
-#include "i-virtual-machine.h"
+#include "i-machine.h"
 #include "interpret.h"
 #include "jsonrpc-fork-result.h"
 #include "machine-config.h"
@@ -41,33 +41,33 @@
 
 namespace cartesi {
 
-/// \class jsonrpc_virtual_machine
-/// \brief JSONRPC implementation of the i_virtual_machine interface
-class jsonrpc_virtual_machine final : public i_virtual_machine {
+/// \class jsonrpc_machine
+/// \brief JSONRPC implementation of the i_machine interface
+class jsonrpc_machine final : public i_machine {
 public:
     enum class cleanup_call { nothing, destroy, shutdown };
 
     /// \brief Constructor that connects to existing JSONRPC server and performs a sanity check on its version
     /// \param address Address of the server in "host:port" format to connect to
     /// \param connect_timeout_ms Timeout in milliseconds for the connection attempt
-    explicit jsonrpc_virtual_machine(std::string address, int64_t connect_timeout_ms);
+    explicit jsonrpc_machine(std::string address, int64_t connect_timeout_ms);
 
     /// \brief Constructor that connects to existing JSONRPC server without version verification
     /// \param address Address of the server in "host:port" format to connect to
-    explicit jsonrpc_virtual_machine(std::string address);
+    explicit jsonrpc_machine(std::string address);
 
     /// \brief Constructor that spawns a new server
     /// \param address The address to bind the server to
     /// \param spawned Output parameter that will contain information about the spawned server
-    jsonrpc_virtual_machine(const std::string &address, int64_t spawn_timeout_ms, fork_result &spawned);
+    jsonrpc_machine(const std::string &address, int64_t spawn_timeout_ms, fork_result &spawned);
 
     // no copies or assignments
-    jsonrpc_virtual_machine(const jsonrpc_virtual_machine &other) = delete;
-    jsonrpc_virtual_machine(jsonrpc_virtual_machine &&other) noexcept = delete;
-    jsonrpc_virtual_machine &operator=(const jsonrpc_virtual_machine &other) = delete;
-    jsonrpc_virtual_machine &operator=(jsonrpc_virtual_machine &&other) noexcept = delete;
+    jsonrpc_machine(const jsonrpc_machine &other) = delete;
+    jsonrpc_machine(jsonrpc_machine &&other) noexcept = delete;
+    jsonrpc_machine &operator=(const jsonrpc_machine &other) = delete;
+    jsonrpc_machine &operator=(jsonrpc_machine &&other) noexcept = delete;
 
-    ~jsonrpc_virtual_machine() override;
+    ~jsonrpc_machine() override;
 
     /// \brief Asks remote server to shutdown
     void shutdown_server();
@@ -104,7 +104,7 @@ class jsonrpc_virtual_machine final : public i_virtual_machine {
 
 private:
     machine_config do_get_initial_config() const override;
-    i_virtual_machine *do_clone_empty() const override;
+    i_machine *do_clone_empty() const override;
     bool do_is_empty() const override;
     void do_create(const machine_config &config, const machine_runtime_config &runtime) override;
     void do_load(const std::string &directory, const machine_runtime_config &runtime) override;
@@ -145,7 +145,7 @@ class jsonrpc_virtual_machine final : public i_virtual_machine {
         const hash_type &root_hash_after) const override;
     void do_verify_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
         const hash_type &root_hash_before, const access_log &log, const hash_type &root_hash_after) const override;
-    bool do_is_jsonrpc_virtual_machine() const override;
+    bool do_is_jsonrpc_machine() const override;
 
     void check_server_version(std::chrono::time_point<std::chrono::steady_clock> timeout_at) const;
     template <typename R, typename... Ts>
@@ -163,4 +163,4 @@ class jsonrpc_virtual_machine final : public i_virtual_machine {
 
 } // namespace cartesi
 
-#endif // JSONRPC_VIRTUAL_MACHINE_H
+#endif // JSONRPC_MACHINE_H
diff --git a/src/virtual-machine.cpp b/src/local-machine.cpp
similarity index 54%
rename from src/virtual-machine.cpp
rename to src/local-machine.cpp
index b2ff88abd..c010460bc 100644
--- a/src/virtual-machine.cpp
+++ b/src/local-machine.cpp
@@ -14,14 +14,14 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#include "virtual-machine.h"
+#include "local-machine.h"
 
 #include <cstdint>
 #include <string>
 
 #include "access-log.h"
 #include "address-range-description.h"
-#include "i-virtual-machine.h"
+#include "i-machine.h"
 #include "interpret.h"
 #include "machine-config.h"
 #include "machine-merkle-tree.h"
@@ -31,175 +31,175 @@
 
 namespace cartesi {
 
-i_virtual_machine *virtual_machine::do_clone_empty() const {
-    return new virtual_machine();
+i_machine *local_machine::do_clone_empty() const {
+    return new local_machine();
 }
 
-bool virtual_machine::do_is_empty() const {
+bool local_machine::do_is_empty() const {
     return m_machine == nullptr;
 }
 
-void virtual_machine::do_create(const machine_config &config, const machine_runtime_config &runtime) {
+void local_machine::do_create(const machine_config &config, const machine_runtime_config &runtime) {
     m_machine = new machine(config, runtime);
 }
 
-void virtual_machine::do_load(const std::string &directory, const machine_runtime_config &runtime) {
+void local_machine::do_load(const std::string &directory, const machine_runtime_config &runtime) {
     m_machine = new machine(directory, runtime);
 }
 
-virtual_machine::~virtual_machine() {
+local_machine::~local_machine() {
     delete m_machine;
     m_machine = nullptr;
 }
 
-machine *virtual_machine::get_machine() {
+machine *local_machine::get_machine() {
     if (m_machine == nullptr) {
         throw std::runtime_error{"no machine"};
     }
     return m_machine;
 }
 
-const machine *virtual_machine::get_machine() const {
+const machine *local_machine::get_machine() const {
     if (m_machine == nullptr) {
         throw std::runtime_error{"no machine"};
     }
     return m_machine;
 }
 
-void virtual_machine::do_store(const std::string &directory) const {
+void local_machine::do_store(const std::string &directory) const {
     get_machine()->store(directory);
 }
 
-interpreter_break_reason virtual_machine::do_run(uint64_t mcycle_end) {
+interpreter_break_reason local_machine::do_run(uint64_t mcycle_end) {
     return get_machine()->run(mcycle_end);
 }
 
-interpreter_break_reason virtual_machine::do_log_step(uint64_t mcycle_count, const std::string &filename) {
+interpreter_break_reason local_machine::do_log_step(uint64_t mcycle_count, const std::string &filename) {
     return m_machine->log_step(mcycle_count, filename);
 }
 
-access_log virtual_machine::do_log_step_uarch(const access_log::type &log_type) {
+access_log local_machine::do_log_step_uarch(const access_log::type &log_type) {
     return get_machine()->log_step_uarch(log_type);
 }
 
-machine_merkle_tree::proof_type virtual_machine::do_get_proof(uint64_t address, int log2_size) const {
+machine_merkle_tree::proof_type local_machine::do_get_proof(uint64_t address, int log2_size) const {
     return get_machine()->get_proof(address, log2_size);
 }
 
-void virtual_machine::do_get_root_hash(hash_type &hash) const {
+void local_machine::do_get_root_hash(hash_type &hash) const {
     get_machine()->get_root_hash(hash);
 }
 
-bool virtual_machine::do_verify_merkle_tree() const {
+bool local_machine::do_verify_merkle_tree() const {
     return get_machine()->verify_merkle_tree();
 }
 
-uint64_t virtual_machine::do_read_reg(reg r) const {
+uint64_t local_machine::do_read_reg(reg r) const {
     return get_machine()->read_reg(r);
 }
 
-void virtual_machine::do_write_reg(reg w, uint64_t val) {
+void local_machine::do_write_reg(reg w, uint64_t val) {
     get_machine()->write_reg(w, val);
 }
 
-void virtual_machine::do_read_memory(uint64_t address, unsigned char *data, uint64_t length) const {
+void local_machine::do_read_memory(uint64_t address, unsigned char *data, uint64_t length) const {
     get_machine()->read_memory(address, data, length);
 }
 
-void virtual_machine::do_write_memory(uint64_t address, const unsigned char *data, uint64_t length) {
+void local_machine::do_write_memory(uint64_t address, const unsigned char *data, uint64_t length) {
     get_machine()->write_memory(address, data, length);
 }
 
-void virtual_machine::do_read_virtual_memory(uint64_t address, unsigned char *data, uint64_t length) {
+void local_machine::do_read_virtual_memory(uint64_t address, unsigned char *data, uint64_t length) {
     get_machine()->read_virtual_memory(address, data, length);
 }
 
-void virtual_machine::do_write_virtual_memory(uint64_t address, const unsigned char *data, uint64_t length) {
+void local_machine::do_write_virtual_memory(uint64_t address, const unsigned char *data, uint64_t length) {
     get_machine()->write_virtual_memory(address, data, length);
 }
 
-uint64_t virtual_machine::do_translate_virtual_address(uint64_t vaddr) {
+uint64_t local_machine::do_translate_virtual_address(uint64_t vaddr) {
     return get_machine()->translate_virtual_address(vaddr);
 }
 
-void virtual_machine::do_replace_memory_range(const memory_range_config &new_range) {
+void local_machine::do_replace_memory_range(const memory_range_config &new_range) {
     get_machine()->replace_memory_range(new_range);
 }
 
-uint64_t virtual_machine::do_read_word(uint64_t address) const {
+uint64_t local_machine::do_read_word(uint64_t address) const {
     return get_machine()->read_word(address);
 }
 
-bool virtual_machine::do_verify_dirty_page_maps() const {
+bool local_machine::do_verify_dirty_page_maps() const {
     return get_machine()->verify_dirty_page_maps();
 }
 
-machine_config virtual_machine::do_get_initial_config() const {
+machine_config local_machine::do_get_initial_config() const {
     return get_machine()->get_initial_config();
 }
 
-machine_runtime_config virtual_machine::do_get_runtime_config() const {
+machine_runtime_config local_machine::do_get_runtime_config() const {
     return get_machine()->get_runtime_config();
 }
 
-void virtual_machine::do_set_runtime_config(const machine_runtime_config &r) {
+void local_machine::do_set_runtime_config(const machine_runtime_config &r) {
     get_machine()->set_runtime_config(r);
 }
 
-void virtual_machine::do_destroy() {
+void local_machine::do_destroy() {
     delete get_machine();
     m_machine = nullptr;
 }
 
-void virtual_machine::do_reset_uarch() {
+void local_machine::do_reset_uarch() {
     get_machine()->reset_uarch();
 }
 
-access_log virtual_machine::do_log_reset_uarch(const access_log::type &log_type) {
+access_log local_machine::do_log_reset_uarch(const access_log::type &log_type) {
     return get_machine()->log_reset_uarch(log_type);
 }
 
-uarch_interpreter_break_reason virtual_machine::do_run_uarch(uint64_t uarch_cycle_end) {
+uarch_interpreter_break_reason local_machine::do_run_uarch(uint64_t uarch_cycle_end) {
     return get_machine()->run_uarch(uarch_cycle_end);
 }
 
-address_range_descriptions virtual_machine::do_get_address_ranges() const {
+address_range_descriptions local_machine::do_get_address_ranges() const {
     return get_machine()->get_address_ranges();
 }
 
-void virtual_machine::do_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length) {
+void local_machine::do_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length) {
     get_machine()->send_cmio_response(reason, data, length);
 }
 
-access_log virtual_machine::do_log_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
+access_log local_machine::do_log_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
     const access_log::type &log_type) {
     return get_machine()->log_send_cmio_response(reason, data, length, log_type);
 }
 
-uint64_t virtual_machine::do_get_reg_address(reg r) const {
+uint64_t local_machine::do_get_reg_address(reg r) const {
     return machine::get_reg_address(r);
 }
 
-machine_config virtual_machine::do_get_default_config() const {
+machine_config local_machine::do_get_default_config() const {
     return machine::get_default_config();
 }
 
-interpreter_break_reason virtual_machine::do_verify_step(const hash_type &root_hash_before,
+interpreter_break_reason local_machine::do_verify_step(const hash_type &root_hash_before,
     const std::string &log_filename, uint64_t mcycle_count, const hash_type &root_hash_after) const {
     return machine::verify_step(root_hash_before, log_filename, mcycle_count, root_hash_after);
 }
 
-void virtual_machine::do_verify_step_uarch(const hash_type &root_hash_before, const access_log &log,
+void local_machine::do_verify_step_uarch(const hash_type &root_hash_before, const access_log &log,
     const hash_type &root_hash_after) const {
     machine::verify_step_uarch(root_hash_before, log, root_hash_after);
 }
 
-void virtual_machine::do_verify_reset_uarch(const hash_type &root_hash_before, const access_log &log,
+void local_machine::do_verify_reset_uarch(const hash_type &root_hash_before, const access_log &log,
     const hash_type &root_hash_after) const {
     machine::verify_reset_uarch(root_hash_before, log, root_hash_after);
 }
 
-void virtual_machine::do_verify_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
+void local_machine::do_verify_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
     const hash_type &root_hash_before, const access_log &log, const hash_type &root_hash_after) const {
     machine::verify_send_cmio_response(reason, data, length, root_hash_before, log, root_hash_after);
 }
diff --git a/src/virtual-machine.h b/src/local-machine.h
similarity index 86%
rename from src/virtual-machine.h
rename to src/local-machine.h
index b3096af03..0f98e064a 100644
--- a/src/virtual-machine.h
+++ b/src/local-machine.h
@@ -14,15 +14,15 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#ifndef VIRTUAL_MACHINE_H
-#define VIRTUAL_MACHINE_H
+#ifndef LOCAL_MACHINE_H
+#define LOCAL_MACHINE_H
 
 #include <cstdint>
 #include <string>
 
 #include "access-log.h"
 #include "address-range-description.h"
-#include "i-virtual-machine.h"
+#include "i-machine.h"
 #include "interpret.h"
 #include "machine-config.h"
 #include "machine-merkle-tree.h"
@@ -32,19 +32,19 @@
 
 namespace cartesi {
 
-/// \class virtual_machine
-/// \brief i_virtual_machine implementation pointing to a local machine instance
-class virtual_machine : public i_virtual_machine {
+/// \class local_machine
+/// \brief i_machine implementation pointing to a local machine instance
+class local_machine : public i_machine {
 public:
-    virtual_machine() = default;
-    virtual_machine(const virtual_machine &other) = delete;
-    virtual_machine(virtual_machine &&other) noexcept = delete;
-    virtual_machine &operator=(const virtual_machine &other) = delete;
-    virtual_machine &operator=(virtual_machine &&other) noexcept = delete;
-    ~virtual_machine() override;
+    local_machine() = default;
+    local_machine(const local_machine &other) = delete;
+    local_machine(local_machine &&other) noexcept = delete;
+    local_machine &operator=(const local_machine &other) = delete;
+    local_machine &operator=(local_machine &&other) noexcept = delete;
+    ~local_machine() override;
 
 private:
-    i_virtual_machine *do_clone_empty() const override;
+    i_machine *do_clone_empty() const override;
     bool do_is_empty() const override;
     void do_create(const machine_config &config, const machine_runtime_config &runtime) override;
     void do_load(const std::string &directory, const machine_runtime_config &runtime) override;
@@ -95,4 +95,4 @@ class virtual_machine : public i_virtual_machine {
 
 } // namespace cartesi
 
-#endif // VIRTUAL_MACHINE_H
+#endif // LOCAL_MACHINE_H
diff --git a/src/machine-c-api.cpp b/src/machine-c-api.cpp
index 1bde476c3..77ddb718a 100644
--- a/src/machine-c-api.cpp
+++ b/src/machine-c-api.cpp
@@ -34,9 +34,10 @@
 #include "access-log.h"
 #include "address-range-description.h"
 #include "htif-constants.h"
-#include "i-virtual-machine.h"
+#include "i-machine.h"
 #include "interpret.h"
 #include "json-util.h"
+#include "local-machine.h"
 #include "machine-c-api-internal.h"
 #include "machine-config.h"
 #include "machine-merkle-tree.h"
@@ -45,7 +46,6 @@
 #include "machine.h"
 #include "os-features.h"
 #include "pmas-defines.h"
-#include "virtual-machine.h"
 
 static std::string &get_last_err_msg_storage() {
     static THREAD_LOCAL std::string last_err_msg;
@@ -452,23 +452,23 @@ static cartesi::machine_reg convert_from_c(cm_reg r) {
     throw std::domain_error{"unknown register"};
 }
 
-static cartesi::i_virtual_machine *convert_from_c(cm_machine *m) {
+static cartesi::i_machine *convert_from_c(cm_machine *m) {
     if (m == nullptr) {
         throw std::invalid_argument("invalid machine");
     }
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-    return reinterpret_cast<cartesi::i_virtual_machine *>(m);
+    return reinterpret_cast<cartesi::i_machine *>(m);
 }
 
-static const cartesi::i_virtual_machine *convert_from_c(const cm_machine *m) {
+static const cartesi::i_machine *convert_from_c(const cm_machine *m) {
     if (m == nullptr) {
         throw std::invalid_argument("invalid machine");
     }
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-    return reinterpret_cast<const cartesi::i_virtual_machine *>(m);
+    return reinterpret_cast<const cartesi::i_machine *>(m);
 }
 
-static cm_machine *convert_to_c(cartesi::i_virtual_machine *cpp_m) {
+static cm_machine *convert_to_c(cartesi::i_machine *cpp_m) {
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
     return reinterpret_cast<cm_machine *>(cpp_m);
 }
@@ -490,7 +490,7 @@ cm_error cm_new(cm_machine **new_m) try {
     if (new_m == nullptr) {
         throw std::invalid_argument("invalid new machine output");
     }
-    *new_m = convert_to_c(new cartesi::virtual_machine());
+    *new_m = convert_to_c(new cartesi::local_machine());
     return cm_result_success();
 } catch (...) {
     if (new_m != nullptr) {

From e4949690ab20475dc74a59900e54c713e52d55a5 Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Tue, 4 Mar 2025 21:10:35 +0000
Subject: [PATCH 27/82] refactor: rename pm-type-name

poor-type-name is more legible
---
 src/{find-pmas-entry.h => find-pma.h}    |  4 ++--
 src/i-state-access.h                     |  6 ++---
 src/interpret.cpp                        |  2 +-
 src/machine.cpp                          |  6 ++---
 src/mock-address-range.h                 |  2 +-
 src/{pm-type-name.h => poor-type-name.h} | 28 ++++++++++++------------
 src/translate-virtual-address.h          |  2 +-
 7 files changed, 25 insertions(+), 25 deletions(-)
 rename src/{find-pmas-entry.h => find-pma.h} (97%)
 rename src/{pm-type-name.h => poor-type-name.h} (75%)

diff --git a/src/find-pmas-entry.h b/src/find-pma.h
similarity index 97%
rename from src/find-pmas-entry.h
rename to src/find-pma.h
index 1ef1f2e64..9a3135d3f 100644
--- a/src/find-pmas-entry.h
+++ b/src/find-pma.h
@@ -14,8 +14,8 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#ifndef FIND_ADDRESS_RANGE_H
-#define FIND_ADDRESS_RANGE_H
+#ifndef FIND_PMA_H
+#define FIND_PMA_H
 
 #include <cstdint>
 
diff --git a/src/i-state-access.h b/src/i-state-access.h
index 9af18c05f..139d24aa2 100644
--- a/src/i-state-access.h
+++ b/src/i-state-access.h
@@ -28,7 +28,7 @@
 #include "dump.h"
 #include "i-prefer-shadow-state.h"
 #include "meta.h"
-#include "pm-type-name.h"
+#include "poor-type-name.h"
 #include "tlb.h"
 
 namespace cartesi {
@@ -332,7 +332,7 @@ class i_state_access { // CRTP
         derived().template do_read_memory_word<T, A>(faddr, pma_index, pval);
         [[maybe_unused]] const auto fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
         DSA_PRINTF("%s::read_memory_word<%s,%s>(%s{0x%" PRIx64 "}, %" PRIu64 ") = %" PRIu64 "(0x%" PRIx64 ")\n",
-            get_name(), pm_type_name_v<T>, pm_type_name_v<A>, fast_addr_name, faddr, pma_index,
+            get_name(), poor_type_name_v<T>, poor_type_name_v<A>, fast_addr_name, faddr, pma_index,
             static_cast<uint64_t>(*pval), static_cast<uint64_t>(*pval));
     }
 
@@ -349,7 +349,7 @@ class i_state_access { // CRTP
         derived().template do_write_memory_word<T, A>(faddr, pma_index, val);
         [[maybe_unused]] const auto fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
         DSA_PRINTF("%s::write_memory_word<%s,%s>(%s{0x%" PRIx64 "}, %" PRIu64 ", %" PRIu64 "(0x%" PRIx64 "))\n",
-            get_name(), pm_type_name_v<T>, pm_type_name_v<A>, fast_addr_name, faddr, pma_index,
+            get_name(), poor_type_name_v<T>, poor_type_name_v<A>, fast_addr_name, faddr, pma_index,
             static_cast<uint64_t>(val), static_cast<uint64_t>(val));
     }
 
diff --git a/src/interpret.cpp b/src/interpret.cpp
index 30507daa7..49094f48d 100644
--- a/src/interpret.cpp
+++ b/src/interpret.cpp
@@ -103,7 +103,7 @@
 #include "compiler-defines.h"
 #include "device-state-access.h"
 #include "dump.h"
-#include "find-pmas-entry.h"
+#include "find-pma.h"
 #include "i-accept-counters.h"
 #include "i-interactive-state-access.h"
 #include "i-state-access.h"
diff --git a/src/machine.cpp b/src/machine.cpp
index 54d60f59f..4bff3b5cb 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -119,9 +119,6 @@ void machine::check_address_range(const address_range &ar, register_where where)
     if (!where.interpret && !where.merkle) {
         throw std::runtime_error{"address range "s + ar.get_description() + " must be registered somwhere"s};
     }
-    if (where.interpret && m_s.pmas.size() >= PMA_MAX) {
-        throw std::runtime_error{"too many address ranges when adding "s + ar.get_description()};
-    }
     const auto start = ar.get_start();
     const auto length = ar.get_length();
     // Checks if new range is machine addressable space (safe unsigned overflows)
@@ -492,6 +489,9 @@ void machine::init_plic_ar(const plic_config &p) {
 void machine::init_pmas_contents(memory_address_range &pmas) const {
     static_assert(sizeof(pmas_state) == PMA_MAX * 2 * sizeof(uint64_t), "inconsistent PMAs state length");
     static_assert(AR_PMAS_LENGTH >= sizeof(pmas_state), "PMAs address range too short");
+    if (m_s.pmas.size() >= PMA_MAX - 1) { // Leave room for a sentinel empty address range after all others
+        throw std::runtime_error{"too many address ranges"};
+    }
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
     auto &dest = *reinterpret_cast<pmas_state *>(pmas.get_host_memory());
     std::ranges::transform(m_s.pmas, dest.begin(),
diff --git a/src/mock-address-range.h b/src/mock-address-range.h
index a7e8609b1..ee73d9c0c 100644
--- a/src/mock-address-range.h
+++ b/src/mock-address-range.h
@@ -80,7 +80,7 @@ static inline mock_address_range make_mock_address_range(uint64_t istart, uint64
 
 template <typename ABRT>
 address_range &get_mock_address_range(mock_address_range &mock, ABRT abrt) {
-    //??D I'm hoping the compiler optimizes this to what amounts to an if and a cast
+    //??D I'm hoping the compiler optimizes this to what amounts to a cast
     static_assert(std::is_same_v<std::variant_alternative_t<0, mock_address_range>, std::monostate>);
     switch (mock.index()) {
         case 1:
diff --git a/src/pm-type-name.h b/src/poor-type-name.h
similarity index 75%
rename from src/pm-type-name.h
rename to src/poor-type-name.h
index 9ecb4241c..4940b7737 100644
--- a/src/pm-type-name.h
+++ b/src/poor-type-name.h
@@ -14,35 +14,35 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#ifndef PM_TYPE_NAME_H
-#define PM_TYPE_NAME_H
+#ifndef POOR_TYPE_NAME_H
+#define POOR_TYPE_NAME_H
 
 namespace cartesi {
 
 //?DD Poor man's rtti that works in microarchitecture
 template <typename T>
-struct pm_type_name {
+struct poor_type_name {
     static constexpr const char *value = "unknown";
 };
 
 template <typename T>
-constexpr const char *pm_type_name_v = pm_type_name<T>::value;
+constexpr const char *poor_type_name_v = poor_type_name<T>::value;
 
 // NOLINTBEGIN(cppcoreguidelines-macro-usage)
-#define PM_TYPE_NAME(type)                                                                                             \
+#define POOR_TYPE_NAME(type)                                                                                           \
     template <>                                                                                                        \
-    struct pm_type_name<type> {                                                                                        \
+    struct poor_type_name<type> {                                                                                      \
         static constexpr const char *value = #type;                                                                    \
     }
 
-PM_TYPE_NAME(uint8_t);
-PM_TYPE_NAME(int8_t);
-PM_TYPE_NAME(uint16_t);
-PM_TYPE_NAME(int16_t);
-PM_TYPE_NAME(uint32_t);
-PM_TYPE_NAME(int32_t);
-PM_TYPE_NAME(uint64_t);
-PM_TYPE_NAME(int64_t);
+POOR_TYPE_NAME(uint8_t);
+POOR_TYPE_NAME(int8_t);
+POOR_TYPE_NAME(uint16_t);
+POOR_TYPE_NAME(int16_t);
+POOR_TYPE_NAME(uint32_t);
+POOR_TYPE_NAME(int32_t);
+POOR_TYPE_NAME(uint64_t);
+POOR_TYPE_NAME(int64_t);
 // NOLINTEND(cppcoreguidelines-macro-usage)
 
 } // namespace cartesi
diff --git a/src/translate-virtual-address.h b/src/translate-virtual-address.h
index 73b11d0bb..58a862a13 100644
--- a/src/translate-virtual-address.h
+++ b/src/translate-virtual-address.h
@@ -46,7 +46,7 @@
 #include <cstdint>
 
 #include "compiler-defines.h"
-#include "find-pmas-entry.h"
+#include "find-pma.h"
 #include "riscv-constants.h"
 
 namespace cartesi {

From 207e9d7e081dcbeea75f0f379b3b3e4181a002f9 Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Wed, 5 Mar 2025 15:24:52 +0000
Subject: [PATCH 28/82] refactor: use std::ranges::lower_bound

---
 src/replay-step-state-access.h | 37 ++++++++++------------------------
 1 file changed, 11 insertions(+), 26 deletions(-)

diff --git a/src/replay-step-state-access.h b/src/replay-step-state-access.h
index 01c5a9ac1..853cccbb0 100644
--- a/src/replay-step-state-access.h
+++ b/src/replay-step-state-access.h
@@ -20,6 +20,7 @@
 #include <cassert>
 #include <cstdlib>
 #include <optional>
+#include <ranges>
 
 #include "compiler-defines.h"
 #include "host-addr.h"
@@ -121,7 +122,6 @@ class replay_step_state_access :
         if (m_context.page_count == 0) {
             interop_throw_runtime_error("page count is zero");
         }
-
         // set page data
         if (!validate_and_advance_offset(log_size, first_page_offset, sizeof(page_type), m_context.page_count,
                 &sibling_count_offset)) {
@@ -200,18 +200,11 @@ class replay_step_state_access :
     /// \return A pointer to the page_type structure if found, nullptr otherwise
     page_type *try_find_page(uint64_t paddr_page) const {
         const auto page_index = paddr_page >> AR_PAGE_SIZE_LOG2;
-        uint64_t min{0};
-        uint64_t max{m_context.page_count};
-        while (min < max) {
-            auto mid = (min + max) >> 1;
-            if (m_context.pages[mid].index == page_index) {
-                return &m_context.pages[mid];
-            }
-            if (m_context.pages[mid].index < page_index) {
-                min = mid + 1;
-            } else {
-                max = mid;
-            }
+        auto pages = std::ranges::views::counted(m_context.pages, static_cast<int64_t>(m_context.page_count));
+        auto it = std::ranges::lower_bound(pages, page_index, std::ranges::less{},
+            [](const auto &page) { return page.index; });
+        if (it != pages.end() && it->index == page_index) {
+            return &(*it);
         }
         return nullptr;
     }
@@ -220,19 +213,11 @@ class replay_step_state_access :
     /// \param haddr Host address of page data
     /// \return A pointer to the page_type structure if found, nullptr otherwise
     page_type *try_find_page(host_addr haddr_page) const {
-        uint64_t min{0};
-        uint64_t max{m_context.page_count};
-        while (min < max) {
-            auto mid = (min + max) >> 1;
-            auto mid_page_data = cast_ptr_to_host_addr(m_context.pages[mid].data);
-            if (mid_page_data == haddr_page) {
-                return &m_context.pages[mid];
-            }
-            if (mid_page_data < haddr_page) {
-                min = mid + 1;
-            } else {
-                max = mid;
-            }
+        auto pages = std::ranges::views::counted(m_context.pages, static_cast<int64_t>(m_context.page_count));
+        auto it = std::ranges::lower_bound(pages, haddr_page, std::ranges::less{},
+            [](const auto &page) { return cast_ptr_to_host_addr(page.data); });
+        if (it != pages.end() && cast_ptr_to_host_addr(it->data) == haddr_page) {
+            return &(*it);
         }
         return nullptr;
     }

From 132aa9751b73ae135d3ca0b4610c43e2231468d7 Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Wed, 5 Mar 2025 15:34:24 +0000
Subject: [PATCH 29/82] refactor: bump boost to 1.87 on mac

---
 src/Makefile        | 4 ++--
 tests/misc/Makefile | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/Makefile b/src/Makefile
index 11fc14731..8b739d904 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -86,8 +86,8 @@ SLIRP_INC=-I$(BREW_PREFIX)/libslirp/include
 # Macports installation
 else ifneq (,$(PORT_PREFIX))
 INSTALL_PREFIX=/opt/local
-BOOST_LIB_DIR=-L$(INSTALL_PREFIX)/libexec/boost/1.81/lib
-BOOST_INC=-I$(INSTALL_PREFIX)/libexec/boost/1.81/include
+BOOST_LIB_DIR=-L$(INSTALL_PREFIX)/libexec/boost/1.87/lib
+BOOST_INC=-I$(INSTALL_PREFIX)/libexec/boost/1.87/include
 SLIRP_LIB=-L$(INSTALL_PREFIX)/lib -lslirp
 SLIRP_INC=-I$(INSTALL_PREFIX)/include
 
diff --git a/tests/misc/Makefile b/tests/misc/Makefile
index 84b6a8f4f..60cc84fa8 100644
--- a/tests/misc/Makefile
+++ b/tests/misc/Makefile
@@ -42,8 +42,8 @@ SLIRP_LIB=-L$(BREW_PREFIX)/lib -lslirp
 # Macports installation
 else ifneq (,$(shell which port))
 PORT_PREFIX = /opt/local
-BOOST_LIB_DIR=-L$(PORT_PREFIX)/libexec/boost/1.81/lib
-BOOST_INC=-I$(PORT_PREFIX)/libexec/boost/1.81/include
+BOOST_LIB_DIR=-L$(PORT_PREFIX)/libexec/boost/1.87/lib
+BOOST_INC=-I$(PORT_PREFIX)/libexec/boost/1.87/include
 SLIRP_LIB=-L$(PORT_PREFIX)/lib -lslirp
 else
 $(error Neither Homebrew nor MacPorts is installed)

From 5ee6fc6966b055c59c477c3b367c33527f70b5bc Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Wed, 5 Mar 2025 16:59:19 +0000
Subject: [PATCH 30/82] refactor: use attribute((format(printf, 1, 2)))

---
 src/assert-printf.h         |  20 ++++++-
 src/dump.h                  |  28 ----------
 src/i-accept-scoped-notes.h |  30 +++++++----
 src/i-state-access.h        |  66 +++++++++++++----------
 src/i-uarch-state-access.h  |  36 ++++++++-----
 src/interpret.cpp           | 104 ++++++++++++++++++------------------
 src/machine.cpp             |  74 ++++++++++++-------------
 src/merkle-tree-hash.cpp    |   2 +-
 src/uarch-solidity-compat.h |   8 +--
 uarch/uarch-runtime.h       |   3 ++
 10 files changed, 198 insertions(+), 173 deletions(-)
 delete mode 100644 src/dump.h

diff --git a/src/assert-printf.h b/src/assert-printf.h
index 1bf16b675..0f0f5b41b 100644
--- a/src/assert-printf.h
+++ b/src/assert-printf.h
@@ -14,8 +14,8 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#ifndef PRINTF_ASSERT_H
-#define PRINTF_ASSERT_H
+#ifndef ASSERT_PRINTF_H
+#define ASSERT_PRINTF_H
 
 /// \file
 /// \brief Microarchitecture-dependent includes for printf and assert
@@ -27,4 +27,20 @@
 #include <cstdio>
 #endif
 
+#include <cstdarg>
+#include <tuple>
+
+static inline void d_vprintf(const char *fmt, va_list ap) {
+    std::ignore = vfprintf(stderr, fmt, ap);
+}
+
+// Better to use C-style variadic function that checks for format!
+// NOLINTNEXTLINE(cert-dcl50-cpp)
+__attribute__((__format__(__printf__, 1, 2))) static inline void d_printf(const char *fmt, ...) {
+    va_list ap;
+    va_start(ap, fmt);
+    d_vprintf(fmt, ap);
+    va_end(ap);
+}
+
 #endif
diff --git a/src/dump.h b/src/dump.h
deleted file mode 100644
index 4cfc8e2c8..000000000
--- a/src/dump.h
+++ /dev/null
@@ -1,28 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-#ifndef DUMP_H
-#define DUMP_H
-
-#include <tuple>
-
-#include "assert-printf.h"
-
-template <size_t N, typename... ARGS>
-static inline auto D_PRINTF(const char (&fmt)[N], ARGS... args) {
-    std::ignore = fprintf(stderr, fmt, args...);
-}
-
-#endif // DUMP_H
diff --git a/src/i-accept-scoped-notes.h b/src/i-accept-scoped-notes.h
index affc19c3e..1c1220269 100644
--- a/src/i-accept-scoped-notes.h
+++ b/src/i-accept-scoped-notes.h
@@ -20,10 +20,11 @@
 /// \file
 /// \brief Accept scoped notes interface
 
+#include <cstdarg>
 #include <cstdint>
 #include <type_traits>
 
-#include "dump.h"
+#include "assert-printf.h"
 #include "i-state-access.h"
 #include "i-uarch-state-access.h"
 #include "meta.h"
@@ -48,32 +49,43 @@ class i_accept_scoped_notes { // CRTP
     }
 
 public:
-    /// \brief Works as printf if we are dumping scoped notes, otherwise does nothing
-    template <size_t N, typename... ARGS>
-    static void DSN_PRINTF([[maybe_unused]] const char (&fmt)[N], [[maybe_unused]] ARGS... args) {
+    /// \brief Works as vprintf if we are dumping scoped notes, otherwise does nothing
+    static void dsn_vprintf([[maybe_unused]] const char *fmt, [[maybe_unused]] va_list ap) {
 #ifdef DUMP_SCOPED_NOTE
         if constexpr (is_an_i_state_access_v<DERIVED>) {
-            DERIVED::DSA_PRINTF(fmt, args...);
+            DERIVED::dsa_vprintf(fmt, ap);
         } else if (is_an_i_uarch_state_access_v<DERIVED>) {
-            DERIVED::DUSA_PRINTF(fmt, args...);
+            DERIVED::dusa_vprintf(fmt, ap);
         } else {
-            D_PRINTF(fmt, args...);
+            d_vprintf(fmt, ap);
         }
 #endif
     }
 
+    /// \brief Works as printf if we are dumping scoped notes, otherwise does nothing
+    // Better to use C-style variadic function that checks for format!
+    // NOLINTNEXTLINE(cert-dcl50-cpp)
+    __attribute__((__format__(__printf__, 1, 2))) static void dsn_printf([[maybe_unused]] const char *fmt, ...) {
+#ifdef DUMP_SCOPED_NOTE
+        va_list ap;
+        va_start(ap, fmt);
+        dsn_vprintf(fmt, ap);
+        va_end(ap);
+#endif
+    }
+
     /// \brief Adds a begin bracket annotation to the log
     /// \param text String with the text for the annotation
     void push_begin_bracket(const char *text) const {
         derived().do_push_begin_bracket(text);
-        DSN_PRINTF("----> begin %s (%s)\n", text, derived().get_name());
+        dsn_printf("----> begin %s (%s)\n", text, derived().get_name());
     }
 
     /// \brief Adds an end bracket annotation to the log
     /// \param text String with the text for the annotation
     void push_end_bracket(const char *text) const {
         derived().do_push_end_bracket(text);
-        DSN_PRINTF("<---- end %s (%s)\n", text, derived().get_name());
+        dsn_printf("<---- end %s (%s)\n", text, derived().get_name());
     }
 
     /// \brief Adds annotations to the state, bracketing a scope
diff --git a/src/i-state-access.h b/src/i-state-access.h
index 139d24aa2..c9cbb1a0d 100644
--- a/src/i-state-access.h
+++ b/src/i-state-access.h
@@ -21,11 +21,12 @@
 /// \brief State access interface
 
 #include <cinttypes>
+#include <cstdarg>
 #include <cstdint>
 #include <type_traits>
 #include <utility>
 
-#include "dump.h"
+#include "assert-printf.h"
 #include "i-prefer-shadow-state.h"
 #include "meta.h"
 #include "poor-type-name.h"
@@ -47,7 +48,7 @@ using i_state_access_fast_addr_t = typename i_state_access_fast_addr<STATE_ACCES
     uint64_t read_##REG() const {                                                                                      \
         if constexpr (!is_an_i_prefer_shadow_state_v<DERIVED>) {                                                       \
             const auto val = derived().do_read_##REG();                                                                \
-            DSA_PRINTF("%s::read_" #REG "() = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), val, val);                    \
+            dsa_printf("%s::read_" #REG "() = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), val, val);                    \
             return val;                                                                                                \
         } else {                                                                                                       \
             return prefer_read_shadow_state(shadow_state_what::REG);                                                   \
@@ -58,7 +59,7 @@ using i_state_access_fast_addr_t = typename i_state_access_fast_addr<STATE_ACCES
     void write_##REG(uint64_t val) const {                                                                             \
         if constexpr (!is_an_i_prefer_shadow_state_v<DERIVED>) {                                                       \
             derived().do_write_##REG(val);                                                                             \
-            DSA_PRINTF("%s::write_" #REG "(%" PRIu64 "(0x%" PRIx64 "))\n", get_name(), val, val);                      \
+            dsa_printf("%s::write_" #REG "(%" PRIu64 "(0x%" PRIx64 "))\n", get_name(), val, val);                      \
         } else {                                                                                                       \
             prefer_write_shadow_state(shadow_state_what::REG, val);                                                    \
         }                                                                                                              \
@@ -104,24 +105,35 @@ class i_state_access { // CRTP
     uint64_t prefer_read_shadow_state(shadow_state_what what) const {
         const auto val = derived().read_shadow_state(what);
         [[maybe_unused]] const auto *const what_name = shadow_state_get_what_name(what);
-        DSA_PRINTF("%s::read_shadow_state(%s) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), what_name, val, val);
+        dsa_printf("%s::read_shadow_state(%s) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), what_name, val, val);
         return val;
     }
 
     void prefer_write_shadow_state(shadow_state_what what, uint64_t val) const {
         derived().write_shadow_state(what, val);
         [[maybe_unused]] const auto *const what_name = shadow_state_get_what_name(what);
-        DSA_PRINTF("%s::write_shadow_state(%s, %" PRIu64 "(0x%" PRIx64 "))\n", get_name(), what_name, val, val);
+        dsa_printf("%s::write_shadow_state(%s, %" PRIu64 "(0x%" PRIx64 "))\n", get_name(), what_name, val, val);
     }
 
 public:
     using fast_addr = i_state_access_fast_addr_t<DERIVED>;
 
+    /// \brief Works as vprintf if we are dumping state accesses, otherwise does nothing
+    static void dsa_vprintf([[maybe_unused]] const char *fmt, [[maybe_unused]] va_list ap) {
+#ifdef DUMP_STATE_ACCESS
+        d_vprintf(fmt, ap);
+#endif
+    }
+
     /// \brief Works as printf if we are dumping state accesses, otherwise does nothing
-    template <size_t N, typename... ARGS>
-    static void DSA_PRINTF([[maybe_unused]] const char (&fmt)[N], [[maybe_unused]] ARGS... args) {
+    // Better to use C-style variadic function that checks for format!
+    // NOLINTNEXTLINE(cert-dcl50-cpp)
+    __attribute__((__format__(__printf__, 1, 2))) static void dsa_printf([[maybe_unused]] const char *fmt, ...) {
 #ifdef DUMP_STATE_ACCESS
-        D_PRINTF(fmt, args...);
+        va_list ap;
+        va_start(ap, fmt);
+        dsa_vprintf(fmt, ap);
+        va_end(ap);
 #endif
     }
 
@@ -131,7 +143,7 @@ class i_state_access { // CRTP
     uint64_t read_x(int i) const {
         if constexpr (!is_an_i_prefer_shadow_state_v<DERIVED>) {
             const auto val = derived().do_read_x(i);
-            DSA_PRINTF("%s::read_x(%d) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), i, val, val);
+            dsa_printf("%s::read_x(%d) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), i, val, val);
             return val;
         } else {
             return prefer_read_shadow_state(shadow_state_get_what(shadow_state_what::x0, i));
@@ -146,7 +158,7 @@ class i_state_access { // CRTP
     void write_x(int i, uint64_t val) const {
         if constexpr (!is_an_i_prefer_shadow_state_v<DERIVED>) {
             derived().do_write_x(i, val);
-            DSA_PRINTF("%s::write_x(%d, %" PRIu64 "(0x%" PRIx64 "))\n", get_name(), i, val, val);
+            dsa_printf("%s::write_x(%d, %" PRIu64 "(0x%" PRIx64 "))\n", get_name(), i, val, val);
         } else {
             prefer_write_shadow_state(shadow_state_get_what(shadow_state_what::x0, i), val);
         }
@@ -158,7 +170,7 @@ class i_state_access { // CRTP
     uint64_t read_f(int i) const {
         if constexpr (!is_an_i_prefer_shadow_state_v<DERIVED>) {
             const auto val = derived().do_read_f(i);
-            DSA_PRINTF("%s::read_f(%d) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), i, val, val);
+            dsa_printf("%s::read_f(%d) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), i, val, val);
             return val;
         } else {
             return prefer_read_shadow_state(shadow_state_get_what(shadow_state_what::f0, i));
@@ -171,7 +183,7 @@ class i_state_access { // CRTP
     void write_f(int i, uint64_t val) const {
         if constexpr (!is_an_i_prefer_shadow_state_v<DERIVED>) {
             derived().do_write_f(i, val);
-            DSA_PRINTF("%s::write_f(%d, %" PRIu64 "(%" PRIx64 "))\n", get_name(), i, val, val);
+            dsa_printf("%s::write_f(%d, %" PRIu64 "(%" PRIx64 "))\n", get_name(), i, val, val);
         } else {
             prefer_write_shadow_state(shadow_state_get_what(shadow_state_what::f0, i), val);
         }
@@ -269,7 +281,7 @@ class i_state_access { // CRTP
     /// \param index Index of PMA
     address_range &read_pma(uint64_t index) const {
         auto &ar = derived().do_read_pma(index);
-        DSA_PRINTF("%s::read_address_range(%" PRIu64 ") = {%s, 0x%" PRIx64 ", 0x%" PRIx64 "}\n", get_name(), index,
+        dsa_printf("%s::read_address_range(%" PRIu64 ") = {%s, 0x%" PRIx64 ", 0x%" PRIx64 "}\n", get_name(), index,
             pmas_get_DID_name(ar.get_driver_id()), ar.get_start(), ar.get_length());
         return ar;
     }
@@ -281,8 +293,8 @@ class i_state_access { // CRTP
     fast_addr get_faddr(uint64_t paddr, uint64_t pma_index) const {
         const auto val = derived().do_get_faddr(paddr, pma_index);
         [[maybe_unused]] const auto fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
-        DSA_PRINTF("%s::get_faddr(%" PRIu64 "(0x%" PRIx64 ")) = %s{%" PRIu64 "(0x%" PRIx64 ")}\n", get_name(), paddr,
-            paddr, fast_addr_name, val, val);
+        dsa_printf("%s::get_faddr(%" PRIu64 "(0x%" PRIx64 ")) = %s{%" PRIu64 "(0x%" PRIx64 ")}\n", get_name(), paddr,
+            paddr, fast_addr_name, static_cast<uint64_t>(val), static_cast<uint64_t>(val));
         return val;
     }
 
@@ -331,9 +343,9 @@ class i_state_access { // CRTP
         static_assert(std::is_integral_v<T> && sizeof(T) <= sizeof(uint64_t), "unsupported type");
         derived().template do_read_memory_word<T, A>(faddr, pma_index, pval);
         [[maybe_unused]] const auto fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
-        DSA_PRINTF("%s::read_memory_word<%s,%s>(%s{0x%" PRIx64 "}, %" PRIu64 ") = %" PRIu64 "(0x%" PRIx64 ")\n",
-            get_name(), poor_type_name_v<T>, poor_type_name_v<A>, fast_addr_name, faddr, pma_index,
-            static_cast<uint64_t>(*pval), static_cast<uint64_t>(*pval));
+        dsa_printf("%s::read_memory_word<%s,%s>(%s{0x%" PRIx64 "}, %" PRIu64 ") = %" PRIu64 "(0x%" PRIx64 ")\n",
+            get_name(), poor_type_name_v<T>, poor_type_name_v<A>, fast_addr_name, static_cast<uint64_t>(faddr),
+            pma_index, static_cast<uint64_t>(*pval), static_cast<uint64_t>(*pval));
     }
 
     /// \brief Writes a word to memory.
@@ -348,9 +360,9 @@ class i_state_access { // CRTP
         static_assert(std::is_integral_v<T> && sizeof(T) <= sizeof(uint64_t), "unsupported type");
         derived().template do_write_memory_word<T, A>(faddr, pma_index, val);
         [[maybe_unused]] const auto fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
-        DSA_PRINTF("%s::write_memory_word<%s,%s>(%s{0x%" PRIx64 "}, %" PRIu64 ", %" PRIu64 "(0x%" PRIx64 "))\n",
-            get_name(), poor_type_name_v<T>, poor_type_name_v<A>, fast_addr_name, faddr, pma_index,
-            static_cast<uint64_t>(val), static_cast<uint64_t>(val));
+        dsa_printf("%s::write_memory_word<%s,%s>(%s{0x%" PRIx64 "}, %" PRIu64 ", %" PRIu64 "(0x%" PRIx64 "))\n",
+            get_name(), poor_type_name_v<T>, poor_type_name_v<A>, fast_addr_name, static_cast<uint64_t>(faddr),
+            pma_index, static_cast<uint64_t>(val), static_cast<uint64_t>(val));
     }
 
     /// \brief Reads TLB's vaddr_page
@@ -360,7 +372,7 @@ class i_state_access { // CRTP
     template <TLB_set_index SET>
     uint64_t read_tlb_vaddr_page(uint64_t slot_index) const {
         const auto val = derived().template do_read_tlb_vaddr_page<SET>(slot_index);
-        DSA_PRINTF("%s::read_tlb_vaddr_page<%" PRIu64 ">(%" PRIu64 ") = 0x%" PRIx64 "\n", get_name(), SET, slot_index,
+        dsa_printf("%s::read_tlb_vaddr_page<%" PRIu64 ">(%" PRIu64 ") = 0x%" PRIx64 "\n", get_name(), SET, slot_index,
             val);
         return val;
     }
@@ -373,8 +385,8 @@ class i_state_access { // CRTP
     fast_addr read_tlb_vp_offset(uint64_t slot_index) const {
         [[maybe_unused]] const auto fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
         const auto val = derived().template do_read_tlb_vp_offset<SET>(slot_index);
-        DSA_PRINTF("%s::read_tlb_vp_offset<%" PRIu64 ">(%" PRIu64 ") = %s{0x%" PRIx64 "}\n", get_name(), SET,
-            slot_index, fast_addr_name, val);
+        dsa_printf("%s::read_tlb_vp_offset<%" PRIu64 ">(%" PRIu64 ") = %s{0x%" PRIx64 "}\n", get_name(), SET,
+            slot_index, fast_addr_name, static_cast<uint64_t>(val));
         return val;
     }
 
@@ -385,7 +397,7 @@ class i_state_access { // CRTP
     template <TLB_set_index SET>
     uint64_t read_tlb_pma_index(uint64_t slot_index) const {
         const auto val = derived().template do_read_tlb_pma_index<SET>(slot_index);
-        DSA_PRINTF("%s::read_tlb_pma_index<%" PRIu64 ">(%" PRIu64 ") = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), SET,
+        dsa_printf("%s::read_tlb_pma_index<%" PRIu64 ">(%" PRIu64 ") = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), SET,
             slot_index, val, val);
         return val;
     }
@@ -402,8 +414,8 @@ class i_state_access { // CRTP
     void write_tlb(uint64_t slot_index, uint64_t vaddr_page, fast_addr vp_offset, uint64_t pma_index) const {
         derived().template do_write_tlb<SET>(slot_index, vaddr_page, vp_offset, pma_index);
         [[maybe_unused]] const auto fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
-        DSA_PRINTF("%s::write_tlb<%" PRIu64 ">(%" PRIu64 ", 0x%" PRIx64 ", %s{0x%" PRIx64 "}, %" PRIu64 ")\n",
-            get_name(), SET, slot_index, vaddr_page, fast_addr_name, vp_offset, pma_index);
+        dsa_printf("%s::write_tlb<%" PRIu64 ">(%" PRIu64 ", 0x%" PRIx64 ", %s{0x%" PRIx64 "}, %" PRIu64 ")\n",
+            get_name(), SET, slot_index, vaddr_page, fast_addr_name, static_cast<uint64_t>(vp_offset), pma_index);
     }
 
     /// \brief Marks a page as dirty
diff --git a/src/i-uarch-state-access.h b/src/i-uarch-state-access.h
index fd58933b7..3e290c768 100644
--- a/src/i-uarch-state-access.h
+++ b/src/i-uarch-state-access.h
@@ -18,9 +18,10 @@
 #define I_UARCH_STATE_ACCESS_H
 
 #include <cinttypes>
+#include <cstdarg>
 #include <cstdint>
 
-#include "dump.h"
+#include "assert-printf.h"
 #include "i-prefer-shadow-uarch-state.h"
 #include "meta.h"
 #include "tlb.h"
@@ -30,7 +31,7 @@
     uint64_t read_##REG() const {                                                                                      \
         if constexpr (!is_an_i_prefer_shadow_uarch_state_v<DERIVED>) {                                                 \
             const auto val = derived().do_read_##REG();                                                                \
-            DUSA_PRINTF("%s::read_" #REG "() = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), val, val);                   \
+            dusa_printf("%s::read_" #REG "() = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), val, val);                   \
             return val;                                                                                                \
         } else {                                                                                                       \
             return prefer_read_shadow_uarch_state(shadow_uarch_state_what::REG);                                       \
@@ -41,7 +42,7 @@
     void write_##REG(uint64_t val) const {                                                                             \
         if constexpr (!is_an_i_prefer_shadow_uarch_state_v<DERIVED>) {                                                 \
             derived().do_write_##REG(val);                                                                             \
-            DUSA_PRINTF("%s::write_" #REG "(%" PRIu64 "(0x%" PRIx64 "))\n", get_name(), val, val);                     \
+            dusa_printf("%s::write_" #REG "(%" PRIu64 "(0x%" PRIx64 "))\n", get_name(), val, val);                     \
         } else {                                                                                                       \
             prefer_write_shadow_uarch_state(shadow_uarch_state_what::REG, val);                                        \
         }                                                                                                              \
@@ -67,29 +68,40 @@ class i_uarch_state_access { // CRTP
     uint64_t prefer_read_shadow_uarch_state(shadow_uarch_state_what what) const {
         const auto val = derived().read_shadow_uarch_state(what);
         [[maybe_unused]] const auto *const what_name = shadow_uarch_state_get_what_name(what);
-        DUSA_PRINTF("%s::read_shadow_uarch_state(%s) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), what_name, val, val);
+        dusa_printf("%s::read_shadow_uarch_state(%s) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), what_name, val, val);
         return val;
     }
 
     void prefer_write_shadow_uarch_state(shadow_uarch_state_what what, uint64_t val) const {
         derived().write_shadow_uarch_state(what, val);
         [[maybe_unused]] const auto *const what_name = shadow_uarch_state_get_what_name(what);
-        DUSA_PRINTF("%s::write_shadow_uarch_state(%s, %" PRIu64 "(0x%" PRIx64 "))\n", get_name(), what_name, val, val);
+        dusa_printf("%s::write_shadow_uarch_state(%s, %" PRIu64 "(0x%" PRIx64 "))\n", get_name(), what_name, val, val);
     }
 
 public:
+    /// \brief Works as vprintf if we are dumping uarch state accesses, otherwise does nothing
+    static void dusa_vprintf([[maybe_unused]] const char *fmt, [[maybe_unused]] va_list ap) {
+#ifdef DUMP_UARCH_STATE_ACCESS
+        d_vprintf(fmt, ap);
+#endif
+    }
+
     /// \brief Works as printf if we are dumping uarch state accesses, otherwise does nothing
-    template <size_t N, typename... ARGS>
-    static void DUSA_PRINTF([[maybe_unused]] const char (&fmt)[N], [[maybe_unused]] ARGS... args) {
+    // Better to use C-style variadic function that checks for format!
+    // NOLINTNEXTLINE(cert-dcl50-cpp)
+    __attribute__((__format__(__printf__, 1, 2))) static void dusa_printf([[maybe_unused]] const char *fmt, ...) {
 #ifdef DUMP_UARCH_STATE_ACCESS
-        D_PRINTF(fmt, args...);
+        va_list ap;
+        va_start(ap, fmt);
+        dusa_vprintf(fmt, ap);
+        va_end(ap);
 #endif
     }
 
     uint64_t read_uarch_x(int i) const {
         if constexpr (!is_an_i_prefer_shadow_uarch_state_v<DERIVED>) {
             const auto val = derived().do_read_uarch_x(i);
-            DUSA_PRINTF("%s::read_uarch_x(%d) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), i, val, val);
+            dusa_printf("%s::read_uarch_x(%d) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), i, val, val);
             return val;
         } else {
             return prefer_read_shadow_uarch_state(shadow_uarch_state_get_what(shadow_uarch_state_what::uarch_x0, i));
@@ -99,7 +111,7 @@ class i_uarch_state_access { // CRTP
     void write_uarch_x(int i, uint64_t val) const {
         if constexpr (!is_an_i_prefer_shadow_uarch_state_v<DERIVED>) {
             derived().do_write_uarch_x(i, val);
-            DUSA_PRINTF("%s::write_uarch_x(%d, %" PRIu64 ")\n", get_name(), i, val);
+            dusa_printf("%s::write_uarch_x(%d, %" PRIu64 ")\n", get_name(), i, val);
         } else {
             prefer_write_shadow_uarch_state(shadow_uarch_state_get_what(shadow_uarch_state_what::uarch_x0, i), val);
         }
@@ -117,14 +129,14 @@ class i_uarch_state_access { // CRTP
 
     uint64_t read_word(uint64_t paddr) const {
         const auto val = derived().do_read_word(paddr);
-        DUSA_PRINTF("%s::read_word(phys_addr{0x%" PRIx64 "}) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), paddr, val,
+        dusa_printf("%s::read_word(phys_addr{0x%" PRIx64 "}) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), paddr, val,
             val);
         return val;
     }
 
     void write_word(uint64_t paddr, uint64_t val) const {
         derived().do_write_word(paddr, val);
-        DUSA_PRINTF("%s::write_word(phys_addr{0x%" PRIx64 "}, %" PRIu64 "(0x%" PRIx64 "))\n", get_name(), paddr, val,
+        dusa_printf("%s::write_word(phys_addr{0x%" PRIx64 "}, %" PRIu64 "(0x%" PRIx64 "))\n", get_name(), paddr, val,
             val);
     }
 
diff --git a/src/interpret.cpp b/src/interpret.cpp
index 49094f48d..11c5a6f31 100644
--- a/src/interpret.cpp
+++ b/src/interpret.cpp
@@ -92,17 +92,15 @@
 
 #ifdef MICROARCHITECTURE
 #include "machine-uarch-bridge-state-access.h"
-#include "uarch-runtime.h"
 #else
 #include "record-step-state-access.h"
 #include "replay-step-state-access.h"
 #include "state-access.h"
-#include <cassert>
 #endif // MICROARCHITECTURE
 
+#include "assert-printf.h"
 #include "compiler-defines.h"
 #include "device-state-access.h"
-#include "dump.h"
 #include "find-pma.h"
 #include "i-accept-counters.h"
 #include "i-interactive-state-access.h"
@@ -182,94 +180,94 @@ static void dump_exception_or_interrupt(uint64_t cause, uint64_t a7) {
     if ((cause & MCAUSE_INTERRUPT_FLAG) != 0) {
         switch (cause & ~MCAUSE_INTERRUPT_FLAG) {
             case 0:
-                D_PRINTF("reserved software interrupt", "");
+                d_printf("reserved software interrupt");
                 break;
             case 1:
-                D_PRINTF("supervisor software interrupt", "");
+                d_printf("supervisor software interrupt");
                 break;
             case 2:
-                D_PRINTF("reserved software interrupt", "");
+                d_printf("reserved software interrupt");
                 break;
             case 3:
-                D_PRINTF("machine software interrupt", "");
+                d_printf("machine software interrupt");
                 break;
             case 4:
-                D_PRINTF("reserved timer interrupt", "");
+                d_printf("reserved timer interrupt");
                 break;
             case 5:
-                D_PRINTF("supervisor timer interrupt", "");
+                d_printf("supervisor timer interrupt");
                 break;
             case 6:
-                D_PRINTF("reserved timer interrupt", "");
+                d_printf("reserved timer interrupt");
                 break;
             case 7:
-                D_PRINTF("machine timer interrupt", "");
+                d_printf("machine timer interrupt");
                 break;
             case 8:
-                D_PRINTF("reserved external interrupt", "");
+                d_printf("reserved external interrupt");
                 break;
             case 9:
-                D_PRINTF("supervisor external interrupt", "");
+                d_printf("supervisor external interrupt");
                 break;
             case 10:
-                D_PRINTF("reserved external interrupt", "");
+                d_printf("reserved external interrupt");
                 break;
             case 11:
-                D_PRINTF("machine external interrupt", "");
+                d_printf("machine external interrupt");
                 break;
             default:
-                D_PRINTF("unknown interrupt", "");
+                d_printf("unknown interrupt");
                 break;
         }
     } else {
         switch (cause) {
             case 0:
-                D_PRINTF("instruction address misaligned", "");
+                d_printf("instruction address misaligned");
                 break;
             case 1:
-                D_PRINTF("instruction access fault", "");
+                d_printf("instruction access fault");
                 break;
             case 2:
-                D_PRINTF("illegal instruction", "");
+                d_printf("illegal instruction");
                 break;
             case 3:
-                D_PRINTF("breakpoint", "");
+                d_printf("breakpoint");
                 break;
             case 4:
-                D_PRINTF("load address misaligned", "");
+                d_printf("load address misaligned");
                 break;
             case 5:
-                D_PRINTF("load access fault", "");
+                d_printf("load access fault");
                 break;
             case 6:
-                D_PRINTF("store/amo address misaligned", "");
+                d_printf("store/amo address misaligned");
                 break;
             case 7:
-                D_PRINTF("store/amo access fault", "");
+                d_printf("store/amo access fault");
                 break;
             case 8:
-                D_PRINTF("ecall %d from u-mode", static_cast<int>(a7));
+                d_printf("ecall %d from u-mode", static_cast<int>(a7));
                 break;
             case 9:
-                D_PRINTF("ecall %s(%d) from s-mode", sbi_ecall_name(a7), static_cast<int>(a7));
+                d_printf("ecall %s(%d) from s-mode", sbi_ecall_name(a7), static_cast<int>(a7));
                 break;
             case 10:
-                D_PRINTF("ecall %d reserved", static_cast<int>(a7));
+                d_printf("ecall %d reserved", static_cast<int>(a7));
                 break;
             case 11:
-                D_PRINTF("ecall %s(%d) from m-mode", sbi_ecall_name(a7), static_cast<int>(a7));
+                d_printf("ecall %s(%d) from m-mode", sbi_ecall_name(a7), static_cast<int>(a7));
                 break;
             case 12:
-                D_PRINTF("instruction page fault", "");
+                d_printf("instruction page fault");
                 break;
             case 13:
-                D_PRINTF("load page fault", "");
+                d_printf("load page fault");
                 break;
             case 15:
-                D_PRINTF("store/amo page fault", "");
+                d_printf("store/amo page fault");
                 break;
             default:
-                D_PRINTF("reserved", "");
+                d_printf("reserved");
                 break;
         }
     }
@@ -319,22 +317,22 @@ static void dump_regs(STATE_ACCESS &a) {
         f[i] = a.read_f(i);
     }
     // Now print them
-    D_PRINTF("pc  = " PRIxREG " ", pc);
+    d_printf("pc  = " PRIxREG " ", pc);
     for (int i = 1; i < X_REG_COUNT; i++) {
         const char sep = ((i & (cols - 1)) == (cols - 1)) ? '\n' : ' ';
-        D_PRINTF("%-4s= " PRIxREG "%c", reg_name[i], x[i], sep);
+        d_printf("%-4s= " PRIxREG "%c", reg_name[i], x[i], sep);
     }
     for (int i = 0; i < F_REG_COUNT; i++) {
         const char sep = ((i & (cols - 1)) == (cols - 1)) ? '\n' : ' ';
-        D_PRINTF("%-4s= " PRIxREG "%c", f_reg_name[i], f[i], sep);
-    }
-    D_PRINTF("prv=%s", prv_get_name(iprv));
-    D_PRINTF(" mstatus=" PRIxREG "\n", mstatus);
-    D_PRINTF(" cycles=" PRIuREG, mcycle);
-    D_PRINTF(" insns=" PRIuREG "\n", mcycle - icycleinstret);
-    D_PRINTF("mideleg=" PRIxREG, mideleg);
-    D_PRINTF(" mie=" PRIxREG, mie);
-    D_PRINTF(" mip=" PRIxREG "\n", mip);
+        d_printf("%-4s= " PRIxREG "%c", f_reg_name[i], f[i], sep);
+    }
+    d_printf("prv=%s", prv_get_name(iprv));
+    d_printf(" mstatus=" PRIxREG "\n", mstatus);
+    d_printf(" cycles=" PRIuREG, mcycle);
+    d_printf(" insns=" PRIuREG "\n", mcycle - icycleinstret);
+    d_printf("mideleg=" PRIxREG, mideleg);
+    d_printf(" mie=" PRIxREG, mie);
+    d_printf(" mip=" PRIxREG "\n", mip);
 #undef PRIxREG
 #undef PRIuREG
 }
@@ -420,10 +418,10 @@ static NO_INLINE uint64_t raise_exception(const STATE_ACCESS a, uint64_t pc, uin
         if (flag) {
             [[maybe_unused]] auto dnote = a.make_scoped_note("dump_exception");
             const auto a7 = a.read_x(17);
-            D_PRINTF("raise_exception: cause=0x%016" PRIx64, cause);
-            D_PRINTF(" tval=0x%016" PRIx64 " (", tval);
+            d_printf("raise_exception: cause=0x%016" PRIx64, cause);
+            d_printf(" tval=0x%016" PRIx64 " (", tval);
             dump_exception_or_interrupt(cause, a7);
-            D_PRINTF(")\n", "");
+            d_printf(")\n");
 #ifdef DUMP_REGS
             dump_regs(a);
 #endif
@@ -1148,11 +1146,11 @@ static auto dump_insn([[maybe_unused]] const STATE_ACCESS a, [[maybe_unused]] ui
     [[maybe_unused]] auto note = a.make_scoped_note("dump_insn");
     uint64_t ppc = pc;
     if (!translate_virtual_address<STATE_ACCESS, false>(a, &ppc, pc, PTE_XWR_X_SHIFT)) {
-        D_PRINTF("v    %08" PRIx64, ppc);
+        d_printf("v    %08" PRIx64, ppc);
     } else {
-        D_PRINTF("p    %08" PRIx64, ppc);
+        d_printf("p    %08" PRIx64, ppc);
     }
-    D_PRINTF(":   %08" PRIx32 "   %s\n", insn, name);
+    d_printf(":   %08" PRIx32 "   %s\n", insn, name);
 #endif
     return a.make_scoped_note(name);
 }
@@ -2089,7 +2087,7 @@ static NO_INLINE uint64_t read_csr(const STATE_ACCESS a, uint64_t mcycle, CSR_ad
         default:
             // Invalid CSRs
 #ifdef DUMP_INVALID_CSR
-            D_PRINTF("csr_read: invalid CSR=0x%x\n", static_cast<int>(csraddr));
+            d_printf("csr_read: invalid CSR=0x%x\n", static_cast<int>(csraddr));
 #endif
             return read_csr_fail(status);
     }
@@ -2437,9 +2435,9 @@ static inline execute_status write_csr_fcsr(const STATE_ACCESS a, uint64_t val)
 template <typename STATE_ACCESS>
 static NO_INLINE execute_status write_csr(const STATE_ACCESS a, uint64_t mcycle, CSR_address csraddr, uint64_t val) {
 #if defined(DUMP_CSR)
-    D_PRINTF("csr_write: csr=0x%03x val=0x", static_cast<int>(csraddr));
+    d_printf("csr_write: csr=0x%03x val=0x", static_cast<int>(csraddr));
     print_uint64_t(val);
-    D_PRINTF("\n");
+    d_printf("\n");
 #endif
     if (unlikely(csr_is_read_only(csraddr))) {
         return execute_status::failure;
@@ -2582,7 +2580,7 @@ static NO_INLINE execute_status write_csr(const STATE_ACCESS a, uint64_t mcycle,
         default:
             // Invalid CSRs
 #ifdef DUMP_INVALID_CSR
-            D_PRINTF("csr_write: invalid CSR=0x%x\n", static_cast<int>(csraddr));
+            d_printf("csr_write: invalid CSR=0x%x\n", static_cast<int>(csraddr));
 #endif
             return execute_status::failure;
     }
diff --git a/src/machine.cpp b/src/machine.cpp
index 4bff3b5cb..1dcb09dac 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -952,10 +952,10 @@ void machine::store(const std::string &dir) const {
 
 void machine::dump_insn_hist() {
 #ifdef DUMP_INSN_HIST
-    D_PRINTF("\nInstruction Histogram:\n", "");
+    d_printf("\nInstruction Histogram:\n");
     for (const auto &[key, val] : m_counters) {
         if (key.starts_with("insn.")) {
-            D_PRINTF("%s: %" PRIu64 "\n", key.c_str(), val);
+            d_printf("%s: %" PRIu64 "\n", key.c_str(), val);
         }
     }
 #endif
@@ -968,41 +968,41 @@ void machine::dump_stats() {
         return static_cast<double>(b) / (a + b);
     };
 
-    D_PRINTF("\nMachine Counters:\n", "");
-    D_PRINTF("inner loops: %" PRIu64 "\n", m_counters["stats.inner_loop"]);
-    D_PRINTF("outers loops: %" PRIu64 "\n", m_counters["stats.outer_loop"]);
-    D_PRINTF("supervisor ints: %" PRIu64 "\n", m_counters["stats.sv_int"]);
-    D_PRINTF("supervisor ex: %" PRIu64 "\n", m_counters["stats.sv_ex"]);
-    D_PRINTF("machine ints: %" PRIu64 "\n", m_counters["stats.m_int"]);
-    D_PRINTF("machine ex: %" PRIu64 "\n", m_counters["stats.m_ex"]);
-    D_PRINTF("atomic mem ops: %" PRIu64 "\n", m_counters["stats.atomic_mop"]);
-    D_PRINTF("fence: %" PRIu64 "\n", m_counters["stats.fence"]);
-    D_PRINTF("fence.i: %" PRIu64 "\n", m_counters["stats.fence_i"]);
-    D_PRINTF("fence.vma: %" PRIu64 "\n", m_counters["stats.fence_vma"]);
-    D_PRINTF("max asid: %" PRIu64 "\n", m_counters["stats.max_asid"]);
-    D_PRINTF("User mode: %" PRIu64 "\n", m_counters["stats.prv.U"]);
-    D_PRINTF("Supervisor mode: %" PRIu64 "\n", m_counters["stats.prv.S"]);
-    D_PRINTF("Machine mode: %" PRIu64 "\n", m_counters["stats.prv.M"]);
-    D_PRINTF("tlb code hit ratio: %.4f\n", hr(m_counters["stats.tlb.cmiss"], m_counters["stats.tlb.chit"]));
-    D_PRINTF("tlb read hit ratio: %.4f\n", hr(m_counters["stats.tlb.rmiss"], m_counters["stats.tlb.rhit"]));
-    D_PRINTF("tlb write hit ratio: %.4f\n", hr(m_counters["stats.tlb.wmiss"], m_counters["stats.tlb.whit"]));
-    D_PRINTF("tlb.chit: %" PRIu64 "\n", m_counters["stats.tlb.chit"]);
-    D_PRINTF("tlb.cmiss: %" PRIu64 "\n", m_counters["stats.tlb.cmiss"]);
-    D_PRINTF("tlb.rhit: %" PRIu64 "\n", m_counters["stats.tlb.rhit"]);
-    D_PRINTF("tlb.rmiss: %" PRIu64 "\n", m_counters["stats.tlb.rmiss"]);
-    D_PRINTF("tlb.whit: %" PRIu64 "\n", m_counters["stats.tlb.whit"]);
-    D_PRINTF("tlb.wmiss: %" PRIu64 "\n", m_counters["stats.tlb.wmiss"]);
-    D_PRINTF("tlb.flush_all: %" PRIu64 "\n", m_counters["stats.tlb.flush_all"]);
-    D_PRINTF("tlb.flush_read: %" PRIu64 "\n", m_counters["stats.tlb.flush_read"]);
-    D_PRINTF("tlb.flush_write: %" PRIu64 "\n", m_counters["stats.tlb.flush_write"]);
-    D_PRINTF("tlb.flush_vaddr: %" PRIu64 "\n", m_counters["stats.tlb.flush_vaddr"]);
-    D_PRINTF("tlb.flush_satp: %" PRIu64 "\n", m_counters["stats.tlb.flush_satp"]);
-    D_PRINTF("tlb.flush_mstatus: %" PRIu64 "\n", m_counters["stats.tlb.flush_mstatus"]);
-    D_PRINTF("tlb.flush_set_prv: %" PRIu64 "\n", m_counters["stats.tlb.flush_set_prv"]);
-    D_PRINTF("tlb.flush_fence_vma_all: %" PRIu64 "\n", m_counters["stats.tlb.flush_fence_vma_all"]);
-    D_PRINTF("tlb.flush_fence_vma_asid: %" PRIu64 "\n", m_counters["stats.tlb.flush_fence_vma_asid"]);
-    D_PRINTF("tlb.flush_fence_vma_vaddr: %" PRIu64 "\n", m_counters["stats.tlb.flush_fence_vma_vaddr"]);
-    D_PRINTF("tlb.flush_fence_vma_asid_vaddr: %" PRIu64 "\n", m_counters["stats.tlb.flush_fence_vma_asid_vaddr"]);
+    d_printf("\nMachine Counters:\n");
+    d_printf("inner loops: %" PRIu64 "\n", m_counters["stats.inner_loop"]);
+    d_printf("outers loops: %" PRIu64 "\n", m_counters["stats.outer_loop"]);
+    d_printf("supervisor ints: %" PRIu64 "\n", m_counters["stats.sv_int"]);
+    d_printf("supervisor ex: %" PRIu64 "\n", m_counters["stats.sv_ex"]);
+    d_printf("machine ints: %" PRIu64 "\n", m_counters["stats.m_int"]);
+    d_printf("machine ex: %" PRIu64 "\n", m_counters["stats.m_ex"]);
+    d_printf("atomic mem ops: %" PRIu64 "\n", m_counters["stats.atomic_mop"]);
+    d_printf("fence: %" PRIu64 "\n", m_counters["stats.fence"]);
+    d_printf("fence.i: %" PRIu64 "\n", m_counters["stats.fence_i"]);
+    d_printf("fence.vma: %" PRIu64 "\n", m_counters["stats.fence_vma"]);
+    d_printf("max asid: %" PRIu64 "\n", m_counters["stats.max_asid"]);
+    d_printf("User mode: %" PRIu64 "\n", m_counters["stats.prv.U"]);
+    d_printf("Supervisor mode: %" PRIu64 "\n", m_counters["stats.prv.S"]);
+    d_printf("Machine mode: %" PRIu64 "\n", m_counters["stats.prv.M"]);
+    d_printf("tlb code hit ratio: %.4f\n", hr(m_counters["stats.tlb.cmiss"], m_counters["stats.tlb.chit"]));
+    d_printf("tlb read hit ratio: %.4f\n", hr(m_counters["stats.tlb.rmiss"], m_counters["stats.tlb.rhit"]));
+    d_printf("tlb write hit ratio: %.4f\n", hr(m_counters["stats.tlb.wmiss"], m_counters["stats.tlb.whit"]));
+    d_printf("tlb.chit: %" PRIu64 "\n", m_counters["stats.tlb.chit"]);
+    d_printf("tlb.cmiss: %" PRIu64 "\n", m_counters["stats.tlb.cmiss"]);
+    d_printf("tlb.rhit: %" PRIu64 "\n", m_counters["stats.tlb.rhit"]);
+    d_printf("tlb.rmiss: %" PRIu64 "\n", m_counters["stats.tlb.rmiss"]);
+    d_printf("tlb.whit: %" PRIu64 "\n", m_counters["stats.tlb.whit"]);
+    d_printf("tlb.wmiss: %" PRIu64 "\n", m_counters["stats.tlb.wmiss"]);
+    d_printf("tlb.flush_all: %" PRIu64 "\n", m_counters["stats.tlb.flush_all"]);
+    d_printf("tlb.flush_read: %" PRIu64 "\n", m_counters["stats.tlb.flush_read"]);
+    d_printf("tlb.flush_write: %" PRIu64 "\n", m_counters["stats.tlb.flush_write"]);
+    d_printf("tlb.flush_vaddr: %" PRIu64 "\n", m_counters["stats.tlb.flush_vaddr"]);
+    d_printf("tlb.flush_satp: %" PRIu64 "\n", m_counters["stats.tlb.flush_satp"]);
+    d_printf("tlb.flush_mstatus: %" PRIu64 "\n", m_counters["stats.tlb.flush_mstatus"]);
+    d_printf("tlb.flush_set_prv: %" PRIu64 "\n", m_counters["stats.tlb.flush_set_prv"]);
+    d_printf("tlb.flush_fence_vma_all: %" PRIu64 "\n", m_counters["stats.tlb.flush_fence_vma_all"]);
+    d_printf("tlb.flush_fence_vma_asid: %" PRIu64 "\n", m_counters["stats.tlb.flush_fence_vma_asid"]);
+    d_printf("tlb.flush_fence_vma_vaddr: %" PRIu64 "\n", m_counters["stats.tlb.flush_fence_vma_vaddr"]);
+    d_printf("tlb.flush_fence_vma_asid_vaddr: %" PRIu64 "\n", m_counters["stats.tlb.flush_fence_vma_asid_vaddr"]);
 #undef TLB_HIT_RATIO
 #endif
 }
diff --git a/src/merkle-tree-hash.cpp b/src/merkle-tree-hash.cpp
index 06f695a14..101235b4c 100644
--- a/src/merkle-tree-hash.cpp
+++ b/src/merkle-tree-hash.cpp
@@ -103,7 +103,7 @@ static std::optional<hash_type> read_hash(FILE *f) {
 /// \param fmt Format string
 /// \param ... Arguments, if any
 // NOLINTNEXTLINE(cert-dcl50-cpp): this vararg is safe because the compiler can check the format
-__attribute__((format(printf, 1, 2))) static void error(const char *fmt, ...) {
+__attribute__((__format__(__printf__, 1, 2))) static void error(const char *fmt, ...) {
     va_list ap{};
     va_start(ap, fmt);
     std::ignore = vfprintf(stderr, fmt, ap);
diff --git a/src/uarch-solidity-compat.h b/src/uarch-solidity-compat.h
index fd1559056..3cd66e0b4 100644
--- a/src/uarch-solidity-compat.h
+++ b/src/uarch-solidity-compat.h
@@ -23,7 +23,7 @@
 #include <stdexcept>
 
 #ifdef DUMP_UARCH_INSN
-#include "dump.h"
+#include "assert-printf.h"
 #include <cinttypes>
 #endif
 
@@ -231,9 +231,9 @@ template <typename UarchState>
 static auto dumpInsn([[maybe_unused]] const UarchState a, [[maybe_unused]] uint64 pc, [[maybe_unused]] uint32 insn,
     [[maybe_unused]] const char *name) {
 #ifdef DUMP_UARCH_INSN
-    D_PRINTF("ua %08" PRIx64, pc);
-    D_PRINTF(":   %08" PRIx32 "   ", insn);
-    D_PRINTF("%s\n", name);
+    d_printf("ua %08" PRIx64, pc);
+    d_printf(":   %08" PRIx32 "   ", insn);
+    d_printf("%s\n", name);
 #endif
     return a.make_scoped_note(name);
 }
diff --git a/uarch/uarch-runtime.h b/uarch/uarch-runtime.h
index 30fc05178..a59b60096 100644
--- a/uarch/uarch-runtime.h
+++ b/uarch/uarch-runtime.h
@@ -40,6 +40,9 @@
 // NOLINTNEXTLINE(cppcoreguidelines-macro-usage)
 #define fprintf(f, ...) printf(__VA_ARGS__)
 
+// NOLINTNEXTLINE(cppcoreguidelines-macro-usage)
+#define vfprintf(f, fmt, ap) vprintf(fmt, ap)
+
 extern "C" NO_RETURN void abort();
 
 namespace cartesi {

From c5cc7b4bca8803df38dbe74719632eeb5d1efb19 Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Mon, 10 Mar 2025 16:29:43 +0000
Subject: [PATCH 31/82] refactor: prepare config for new merkle tree

---
 src/cartesi-machine.lua             | 496 +++++++++++++++++-----------
 src/clua-i-machine.cpp              |   9 +-
 src/json-util.cpp                   | 294 +++++++++--------
 src/json-util.h                     |  86 ++---
 src/jsonrpc-discover.json           | 100 ++++--
 src/machine-c-api.cpp               |  26 +-
 src/machine-c-api.h                 |  32 +-
 src/machine-config.cpp              |  51 ++-
 src/machine-config.h                | 137 +++++---
 src/machine.cpp                     | 225 +++++++------
 src/machine.h                       |  16 +-
 src/uarch-config.h                  |  49 ---
 tests/lua/cartesi-machine-tests.lua |   9 +-
 tests/lua/create-machines.lua       |  16 +-
 tests/lua/htif-cmio.lua             |   4 +-
 tests/lua/htif-console.lua          |   4 +-
 tests/lua/htif-yield.lua            |   7 +-
 tests/lua/machine-bind.lua          | 220 ++++++++----
 tests/lua/machine-test.lua          |   6 +-
 tests/lua/mtime-interrupt.lua       |   2 +-
 tests/lua/run-rv64i-arch-test.lua   |   6 +-
 tests/lua/uarch-riscv-tests.lua     |  10 +-
 tests/misc/test-machine-c-api.cpp   |  96 ++++--
 tests/misc/test-utils.h             |   2 +-
 24 files changed, 1133 insertions(+), 770 deletions(-)
 delete mode 100644 src/uarch-config.h

diff --git a/src/cartesi-machine.lua b/src/cartesi-machine.lua
index ff5cfbc66..ed19f6208 100755
--- a/src/cartesi-machine.lua
+++ b/src/cartesi-machine.lua
@@ -87,10 +87,6 @@ where options are:
   --ram-length=<number>
     set RAM length.
 
-  --dtb-image=<filename>
-    name of file containing DTB image
-    (default: auto generated flattened device tree).
-
   --no-bootargs
     clear default bootargs.
 
@@ -106,9 +102,10 @@ where options are:
 
     <key>:<value> is one of
         label:<label>
-        filename:<filename>
         start:<number>
         length:<number>
+        data_filename:<filename>
+        dht_filename:<filename>
         shared
         mount:<string>
         user:<string>
@@ -116,10 +113,6 @@ where options are:
         label (mandatory)
         identifies the flash drive. init attempts to mount it as /mnt/<label>.
 
-        filename (optional)
-        gives the name of the file containing the image for the flash drive.
-        when omitted or set to the empty, the drive starts filled with 0.
-
         start (optional)
         sets the starting physical memory offset for flash drive in bytes.
         when omitted, drives start at 1 << 55 and are spaced by 1 << 52.
@@ -130,8 +123,18 @@ where options are:
         if omitted, the length is computed from the image in filename.
         if length and filename are set, the image file size must match length.
 
+        data_filename (optional)
+        gives the name of the file containing the data for the flash drive.
+        when omitted or set to the empty, the drive starts filled with 0.
+
+        dht_filename (optional)
+        gives the name of the file containing the dense hash tree for the flash drive.
+        (this is the part of the hash tree that subintends the entire address
+        range for the drive, down to one hash per page.)
+        when omitted or set to the empty, the hash tree will be built from scratch.
+
         shared (optional)
-        target modifications to flash drive modify image file as well.
+        target modifications to flash drive modify the memory and hash tree files.
         by default, image files are not modified and changes are lost.
 
         mount (optional)
@@ -148,33 +151,72 @@ where options are:
         filesystem being mounted.
         in case mount is false, the default ownership is set to the root user.
 
-    (an option "--flash-drive=label:root,filename:rootfs.ext2" is implicit)
+    (an option "--flash-drive=label:root,data_filename:rootfs.ext2" is implicit)
 
   --replace-flash-drive=<key>:<value>[,<key>:<value>[,...]...]
   --replace-memory-range=<key>:<value>[,<key>:<value>[,...]...]
-    replaces an existing flash drive or cmio memory range right after
-    machine instantiation.
+    replaces an existing memory range right after machine instantiation.
     (typically used in conjunction with the --load=<directory> option.)
 
     <key>:<value> is one of
-        filename:<filename>
         start:<number>
         length:<number>
+        data_filename:<filename>
+        dht_filename:<filename>
         shared
 
     semantics are the same as for the --flash-drive option with the following
     difference: start and length are mandatory, and must match those of a
-    previously existing flash drive or cmio memory memory range.
+    previously existing memory range (e.g., flash drive, cmio buffer, etc).
 
+  --ram=<key>:<value>[,<key>:<value>[,...]...]
+  --dtb=<key>:<value>[,<key>:<value>[,...]...]
+  --tlb=<key>:<value>[,<key>:<value>[,...]...]
   --cmio-rx-buffer=<key>:<value>[,<key>:<value>[,...]...]
   --cmio-tx-buffer=<key>:<value>[,<key>:<value>[,...]...]
+  --pmas=<key>:<value>[,<key>:<value>[,...]...]
+  --uarch-ram=<key>:<value>[,<key>:<value>[,...]...]
+    configures file storage for other memory ranges in the machine
 
     <key>:<value> is one of
-        filename:<filename>
+        data_filename:<filename>
+        dht_filename:<filename>
         shared
 
     semantics are the same as for the --flash-drive option.
 
+  --hash-tree=<key>:<value>[,<key>:<value>[,...]...]
+    configures the global hash tree the the machine
+
+    <key>:<value> is one of
+        hasher:<string>
+        sht_filename:<filename>
+        phtc_filename:<filename>
+        phtc_size:<number>
+        shared
+
+        hasher (default: "keccak")
+		hashing algorithm used for the tree
+
+        sht_filename (optional)
+        gives the name of the file containing the sparse hash-tree for the machine.
+		(this is the part of the hash tree from the root down to leaves that subindend
+        entire memory ranges, such as flash-drives or the ram.)
+        when omitted or set to the empty, the hash tree will be built from scratch.
+
+        phtc_filename (optional)
+        gives the name of the file containing the page hash-tree cache for the machine.
+        (this is a cache with the dense hash-trees for a subset of the pages in the
+        machine, all the way down to 256-bit words.)
+        when omitted or set to the empty, the page hash-tree cache will start empty.
+
+        phtc_size (default: 2048)
+        give the maximum number of pages in the cache.
+
+        shared (optional)
+        target modifications to machine state modify the sparse hash tree file.
+        by default, the files is not modified and changes are lost.
+
   --cmio-advance-state=<key>:<value>[,<key>:<value>[,...]...]
     advances the state of the machine through a number of inputs.
 
@@ -568,7 +610,8 @@ local remote_destroy = true
 local perform_rollbacks = true
 local default_config = cartesi.machine:get_default_config()
 local images_path = adjust_images_path(os.getenv("CARTESI_IMAGES_PATH"))
-local flash_image_filename = { root = images_path .. "rootfs.ext2" }
+local flash_data_filename = { root = images_path .. "rootfs.ext2" }
+local flash_dht_filename = {}
 local flash_label_order = { "root" }
 local flash_shared = {}
 local flash_mount = {}
@@ -583,18 +626,37 @@ local has_virtio_console = false
 local has_network = false
 local has_sync_init_date = false
 local memory_range_replace = {}
-local ram_image_filename = images_path .. "linux.bin"
-local ram_length = 128 << 20 -- 128MB
-local dtb_image_filename = nil
-local bootargs = default_config.dtb.bootargs
+local ram = {
+    length = 128 << 20, -- 128MB
+    backing_store = { data_filename = images_path .. "linux.bin" },
+}
 local init_splash = true
 local append_bootargs = ""
 local append_init = ""
 local append_entrypoint = ""
-local uarch
-local cmio
+local dtb = {
+    init = "",
+    entrypoint = "",
+    bootargs = default_config.dtb.bootargs,
+}
+local tlb = {}
+local cmio = {
+    rx_buffer = {},
+    tx_buffer = {},
+}
 local cmio_advance
 local cmio_inspect
+local uarch = {
+    ram = {
+        backing_store = {
+            data_filename = "",
+        },
+    },
+}
+local pmas = {}
+local hash_tree = {
+    hasher = default_config.hash_tree.hasher,
+}
 local concurrency_update_merkle_tree = 0
 local skip_root_hash_check = false
 local skip_root_hash_store = false
@@ -630,34 +692,50 @@ local log_step_filename
 
 local function parse_memory_range(opts, what, all)
     local f = util.parse_options(opts, {
-        filename = true,
+        data_filename = true,
+        dht_filename = true,
         shared = true,
         length = true,
         start = true,
     })
-    f.image_filename = f.filename
-    f.filename = nil
-    if f.image_filename == true then f.image_filename = "" end
-    assert(not f.shared or f.shared == true, "invalid " .. what .. " shared value in " .. all)
+    if f.data_filename == true then f.backing_filename = "" end
+    if f.dense_hashdense_tree_filename == true then f.dht_filename = "" end
+    if f.shared == nil or f.shared == "false" then f.shared = false end
+    if f.shared == "true" then f.shared = true end
+    assert(type(f.shared) == "boolean", "invalid " .. what .. " shared value in " .. all)
+    f.backing_store = {
+        data_filename = f.data_filename,
+        dht_filename = f.dht_filename,
+        shared = f.shared,
+    }
+    f.data_filename = nil
+    f.dht_filename = nil
+    f.shared = nil
     f.start = assert(util.parse_number(f.start), "invalid " .. what .. " start in " .. all)
     f.length = assert(util.parse_number(f.length), "invalid " .. what .. " length in " .. all)
     return f
 end
 
-local function parse_cmio_buffer(opts, what, all)
+local function parse_backing_store(opts, what, all, def)
     local f = util.parse_options(opts, {
-        filename = true,
+        data_filename = true,
+        dht_filename = true,
         shared = true,
     })
-    f.image_filename = f.filename
-    f.filename = nil
-    if f.image_filename == true then f.image_filename = "" end
-    assert(not f.shared or f.shared == true, "invalid " .. what .. " shared value in " .. all)
+    if f.data_filename == true then f.data_filename = "" end
+    if f.dht_filename == true then f.dht_filename = "" end
+    if f.shared == nil or f.shared == "false" then f.shared = false end
+    if f.shared == "true" then f.shared = true end
+    assert(type(f.shared) == "boolean", "invalid " .. what .. " shared value in " .. all)
+    if def then
+        for i, v in pairs(def) do
+            if f[i] == nil then f[i] = v end
+        end
+    end
     return f
 end
 
-local function handle_sync_init_date(all)
-    if not all then return false end
+local function handle_sync_init_date()
     if has_sync_init_date then return true end
     unreproducible = true
     has_sync_init_date = true
@@ -668,14 +746,12 @@ local function handle_sync_init_date(all)
 end
 
 local function handle_virtio_9p(tag, host_directory)
-    if not tag or not host_directory then return false end
     unreproducible = true
     table.insert(virtio, { type = "p9fs", tag = tag, host_directory = host_directory })
     return true
 end
 
 local function handle_volume_option(host_directory, guest_directory)
-    if not host_directory or not guest_directory then return false end
     unreproducible = true
     local tag = "vfs" .. virtio_volume_count
     virtio_volume_count = virtio_volume_count + 1
@@ -683,37 +759,32 @@ local function handle_volume_option(host_directory, guest_directory)
     append_init = append_init .. "busybox mkdir -p " .. guest_directory .. " && "
     append_init = append_init .. "busybox mount -t 9p " .. tag .. " " .. guest_directory .. "\n"
     -- sync guest date with host date, otherwise file system updates will have wrong dates
-    handle_sync_init_date(true)
+    handle_sync_init_date()
     return true
 end
 
-local function handle_htif_console_getchar(all)
-    if not all then return false end
+local function handle_htif_console_getchar()
     htif_console_getchar = true
     unreproducible = true
     return true
 end
 
 local function handle_user(user)
-    if not user then return false end
     append_init = append_init .. "USER=" .. user .. "\n"
     return true
 end
 
 local function handle_env(name, value)
-    if not name or not value then return false end
     append_init = append_init .. "export " .. name .. "=" .. value .. "\n"
     return true
 end
 
 local function handle_workdir(value)
-    if not value then return false end
     append_init = append_init .. "WORKDIR=" .. value .. "\n"
     return true
 end
 
 local function handle_hostname(name)
-    if not name then return false end
     append_init = append_init .. "busybox hostname " .. name .. "\n"
     return true
 end
@@ -792,25 +863,23 @@ busybox ip route add default via 10.0.2.2 dev eth0
 [ -w /etc ] && echo 'nameserver 10.0.2.3' > /etc/resolv.conf
 ]]
     -- sync guest date with host date, otherwise SSL connections may fail to validate certificates
-    handle_sync_init_date(true)
+    handle_sync_init_date()
     return true
 end
 
-local function handle_virtio_console(all)
-    if not all then return false end
+local function handle_virtio_console()
     if has_virtio_console then return true end
     unreproducible = true
     has_virtio_console = true
     -- Switch from HTIF Console (hvc0) to VirtIO console (hvc1)
-    bootargs = bootargs:gsub("console=hvc0", "console=hvc1")
+    dtb.bootargs = dtb.bootargs:gsub("console=hvc0", "console=hvc1")
     table.insert(virtio, 1, { type = "console" })
     return true
 end
 
-local function handle_interactive(all)
-    if not all then return false end
-    handle_virtio_console(true)
-    handle_sync_init_date(true)
+local function handle_interactive()
+    handle_virtio_console()
+    handle_sync_init_date()
     -- Expose current terminal features to the virtual terminal
     local term, lang = os.getenv("TERM"), os.getenv("LANG")
     if term then append_init = append_init .. "export TERM=" .. term .. "\n" end
@@ -828,24 +897,21 @@ end
 local options = {
     {
         "^%-h$",
-        function(all)
-            if not all then return false end
+        function()
             help()
             return true
         end,
     },
     {
         "^%-%-help$",
-        function(all)
-            if not all then return false end
+        function()
             help()
             return true
         end,
     },
     {
         "^%-%-version$",
-        function(all)
-            if not all then return false end
+        function()
             print(string.format("cartesi-machine %s", cartesi.VERSION))
             if cartesi.GIT_COMMIT then print(string.format("git commit: %s", cartesi.GIT_COMMIT)) end
             if cartesi.BUILD_TIME then print(string.format("build time: %s", cartesi.BUILD_TIME)) end
@@ -858,8 +924,7 @@ local options = {
     },
     {
         "^%-%-version%-json$",
-        function(all)
-            if not all then return false end
+        function()
             print("{")
             print(string.format('  "version": "%s",', cartesi.VERSION))
             print(string.format('  "version_major": %d,', cartesi.VERSION_MAJOR))
@@ -888,72 +953,120 @@ local options = {
         end,
     },
     {
-        "^%-%-dtb%-image%=(.*)$",
-        function(o)
-            if not o or #o < 1 then return false end
-            dtb_image_filename = o
+        "^%-%-dtb%-image%=(.+)$",
+        function(opts)
+            dtb.backing_store = dtb.backing_store or {}
+            dtb.backing_store.data_filename = opts
             return true
         end,
     },
     {
         "^%-%-no%-bootargs$",
-        function(all)
-            if not all then return false end
-            bootargs = ""
+        function()
+            dtb.bootargs = ""
             return true
         end,
     },
     {
-        "^%-%-append%-bootargs%=(.*)$",
-        function(o)
-            if not o then return false end
-            if #o == 0 then return true end
+        "^%-%-append%-bootargs%=(.+)$",
+        function(opts)
             if #append_bootargs == 0 then
-                append_bootargs = o
+                append_bootargs = opts
             else
-                append_bootargs = append_bootargs .. " " .. o
+                append_bootargs = append_bootargs .. " " .. opts
             end
             return true
         end,
     },
+    {
+        "^(%-%-dtb%=(.+))$",
+        function(all, opts)
+            dtb.backing_store = parse_backing_store(opts, "dtb", all, dtb.backing_store)
+            return true
+        end,
+    },
     {
         "^%-%-ram%-length%=(.+)$",
         function(n)
-            if not n then return false end
-            ram_length = assert(util.parse_number(n), "invalid RAM length " .. n)
+            ram.length = assert(util.parse_number(n), "invalid RAM length " .. n)
             return true
         end,
     },
     {
-        "^%-%-ram%-image%=(.*)$",
-        function(o)
-            if not o or #o < 1 then return false end
-            ram_image_filename = o
+        "^%-%-ram%-image%=(.+)$",
+        function(opts)
+            ram.backing_store.data_filename = opts
             return true
         end,
     },
     {
         "^%-%-no%-ram%-image$",
-        function(all)
-            if not all then return false end
-            ram_image_filename = ""
+        function()
+            ram.backing_store.data_filename = ""
+            return true
+        end,
+    },
+    {
+        "^(%-%-ram%=(.+))$",
+        function(all, opts)
+            ram.backing_store = parse_backing_store(opts, "ram", all, ram.backing_store)
             return true
         end,
     },
     {
-        "^%-%-uarch%-ram%-image%=(.*)$",
-        function(o)
-            if not o or #o < 1 then return false end
-            uarch = uarch or {}
-            uarch.ram = uarch.ram or {}
-            uarch.ram.image_filename = o
+        "^(%-%-tlb%=(.+))$",
+        function(all, opts)
+            tlb.backing_store = parse_backing_store(opts, "tlb", all, tlb.backing_store)
+            return true
+        end,
+    },
+    {
+        "^(%-%-pmas%=(.+))$",
+        function(all, opts)
+            pmas.backing_store = parse_backing_store(opts, "pmas", all, pmas.backing_store)
+            return true
+        end,
+    },
+    {
+        "^%-%-uarch%-ram%-image%=(.+)$",
+        function(opts)
+            uarch.ram.backing_store.data_filename = opts
+            return true
+        end,
+    },
+    {
+        "^(%-%-uarch%-ram%=(.+))$",
+        function(all, opts)
+            uarch.ram.backing_store = parse_backing_store(opts, "uarch-ram", all, uarch.ram.backing_store)
+            return true
+        end,
+    },
+    {
+        "^(%-%-hash%-tree%=(.+))$",
+        function(all, opts)
+            local h = util.parse_options(opts, {
+                hasher = true,
+                sht_filename = true,
+                phtc_filename = true,
+                phtc_size = true,
+                shared = true,
+            })
+            if h.sht_filename == true then h.sht_filename = "" end
+            if h.phtc_filename == true then h.phtc_filename = "" end
+            if h.hasher == true then h.hasher = "keccak" end
+            if h.shared == nil or h.shared == "false" then h.shared = false end
+            if h.shared == "true" then h.shared = true end
+            h.phtc_size = assert(util.parse_number(h.phtc_size), "invalid page hash cache size in " .. all)
+            assert(type(h.shared) == "boolean", "invalid hash tree shared value in " .. all)
+            for i, v in pairs(h) do
+                hash_tree[i] = v
+            end
             return true
         end,
     },
     {
         "^%-%-unreproducible$",
-        function(all)
-            if not all then return false end
+        function()
             unreproducible = true
             return true
         end,
@@ -1029,10 +1142,10 @@ local options = {
     {
         "^(%-%-flash%-drive%=(.+))$",
         function(all, opts)
-            if not opts then return false end
             local f = util.parse_options(opts, {
                 label = true,
-                filename = true,
+                data_filename = true,
+                dht_filename = true,
                 shared = true,
                 mount = true,
                 user = true,
@@ -1040,13 +1153,12 @@ local options = {
                 start = true,
             })
             assert(f.label, "missing flash drive label in " .. all)
-            f.image_filename = f.filename
-            f.filename = nil
-            if f.image_filename == true then f.image_filename = "" end
+            if f.data_filename == true then f.data_filename = "" end
+            if f.dht_filename == true then f.dht_filename = "" end
             assert(not f.shared or f.shared == true, "invalid flash drive shared value in " .. all)
             if f.mount == nil then
                 -- mount only if there is a file backing
-                if f.image_filename and f.image_filename ~= "" then
+                if f.data_filename and f.data_filename ~= "" then
                     f.mount = "/mnt/" .. f.label
                 else
                     f.mount = false
@@ -1059,11 +1171,12 @@ local options = {
             if f.start then f.start = assert(util.parse_number(f.start), "invalid flash drive start in " .. all) end
             if f.length then f.length = assert(util.parse_number(f.length), "invalid flash drive length in " .. all) end
             local d = f.label
-            if not flash_image_filename[d] then
+            if not flash_data_filename[d] then
                 flash_label_order[#flash_label_order + 1] = d
-                flash_image_filename[d] = ""
+                flash_data_filename[d] = ""
             end
-            flash_image_filename[d] = f.image_filename or flash_image_filename[d]
+            flash_data_filename[d] = f.data_filename or flash_data_filename[d]
+            flash_dht_filename[d] = f.dht_filename or flash_dht_filename[d]
             flash_start[d] = f.start or flash_start[d]
             flash_length[d] = f.length or flash_length[d]
             flash_shared[d] = f.shared or flash_shared[d]
@@ -1075,7 +1188,6 @@ local options = {
     {
         "^(%-%-replace%-flash%-drive%=(.+))$",
         function(all, opts)
-            if not opts then return false end
             memory_range_replace[#memory_range_replace + 1] = parse_memory_range(opts, "flash drive", all)
             return true
         end,
@@ -1083,15 +1195,13 @@ local options = {
     {
         "^(%-%-replace%-memory%-range%=(.+))$",
         function(all, opts)
-            if not opts then return false end
-            memory_range_replace[#memory_range_replace + 1] = parse_memory_range(opts, "flash drive", all)
+            memory_range_replace[#memory_range_replace + 1] = parse_memory_range(opts, "memory range", all)
             return true
         end,
     },
     {
         "^(%-%-cmio%-advance%-state%=(.+))$",
         function(all, opts)
-            if not opts then return false end
             local r = util.parse_options(opts, {
                 input = true,
                 input_index_begin = true,
@@ -1116,9 +1226,8 @@ local options = {
         end,
     },
     {
-        "^(%-%-cmio%-inspect%-state%=(.+))$",
-        function(_, opts)
-            if not opts then return false end
+        "^%-%-cmio%-inspect%-state%=(.+)$",
+        function(opts)
             local r = util.parse_options(opts, {
                 query = true,
                 report = true,
@@ -1144,7 +1253,6 @@ local options = {
     {
         "^(%-%-concurrency%=(.+))$",
         function(all, opts)
-            if not opts then return false end
             local c = util.parse_options(opts, {
                 update_merkle_tree = true,
             })
@@ -1189,7 +1297,6 @@ local options = {
     {
         "^(%-%-initial%-proof%=(.+))$",
         function(all, opts)
-            if not opts then return false end
             local p = util.parse_options(opts, {
                 address = true,
                 log2_size = true,
@@ -1224,13 +1331,13 @@ local options = {
         "^%-%-no%-root%-flash%-drive$",
         function(all)
             if not all then return false end
-            assert(flash_image_filename.root and flash_label_order[1] == "root", "no root flash drive to remove")
-            flash_image_filename.root = nil
+            assert(flash_data_filename.root and flash_label_order[1] == "root", "no root flash drive to remove")
+            flash_data_filename.root = nil
             flash_start.root = nil
             flash_length.root = nil
             flash_shared.root = nil
             table.remove(flash_label_order, 1)
-            bootargs = bootargs:gsub(" root=$", "")
+            dtb.bootargs = dtb.bootargs:gsub(" root=$", "")
             return true
         end,
     },
@@ -1309,41 +1416,41 @@ local options = {
     },
     {
         "^%-%-load%=(.*)$",
-        function(o)
-            if not o or #o < 1 then return false end
-            load_dir = o
+        function(opts)
+            if not opts or #opts < 1 then return false end
+            load_dir = opts
             return true
         end,
     },
     {
         "^%-%-store%=(.*)$",
-        function(o)
-            if not o or #o < 1 then return false end
-            store_dir = o
+        function(opts)
+            if not opts or #opts < 1 then return false end
+            store_dir = opts
             return true
         end,
     },
     {
         "^%-%-remote%-spawn$",
-        function(o)
-            if not o then return false end
+        function(opts)
+            if not opts then return false end
             remote_spawn = true
             return true
         end,
     },
     {
         "^%-%-remote%-address%=(.*)$",
-        function(o)
-            if not o or #o < 1 then return false end
-            remote_address = o
+        function(opts)
+            if not opts or #opts < 1 then return false end
+            remote_address = opts
             return true
         end,
     },
     {
         "^%-%-remote%-fork(%=?)(.*)$",
-        function(o, v)
-            if not o then return false end
-            if o == "=" then
+        function(opts, v)
+            if not opts then return false end
+            if opts == "=" then
                 if not v or #v < 1 then return false end
                 remote_fork = v
             elseif #v ~= 0 then
@@ -1356,40 +1463,40 @@ local options = {
     },
     {
         "^%-%-remote%-health%-check$",
-        function(o)
-            if not o then return false end
+        function(opts)
+            if not opts then return false end
             remote_health_check = true
             return true
         end,
     },
     {
         "^%-%-remote%-shutdown$",
-        function(o)
-            if not o then return false end
+        function(opts)
+            if not opts then return false end
             remote_shutdown = true
             return true
         end,
     },
     {
         "^%-%-no%-remote%-create$",
-        function(o)
-            if not o then return false end
+        function(opts)
+            if not opts then return false end
             remote_create = false
             return true
         end,
     },
     {
         "^%-%-no%-remote%-destroy$",
-        function(o)
-            if not o then return false end
+        function(opts)
+            if not opts then return false end
             remote_destroy = false
             return true
         end,
     },
     {
         "^%-%-no%-rollback$",
-        function(o)
-            if not o then return false end
+        function(opts)
+            if not opts then return false end
             perform_rollbacks = false
             return true
         end,
@@ -1429,9 +1536,9 @@ local options = {
     },
     {
         "^%-%-store%-config(%=?)(%g*)$",
-        function(o, v)
-            if not o then return false end
-            if o == "=" then
+        function(opts, v)
+            if not opts then return false end
+            if opts == "=" then
                 if not v or #v < 1 then return false end
                 store_config = v
             elseif #v ~= 0 then
@@ -1444,9 +1551,9 @@ local options = {
     },
     {
         "^%-%-store%-json%-config(%=?)(%g*)$",
-        function(o, v)
-            if not o then return false end
-            if o == "=" then
+        function(opts, v)
+            if not opts then return false end
+            if opts == "=" then
                 if not v or #v < 1 then return false end
                 store_json_config = v
             elseif #v ~= 0 then
@@ -1459,17 +1566,17 @@ local options = {
     },
     {
         "^%-%-load%-config%=(%g*)$",
-        function(o)
-            if not o or #o < 1 then return false end
-            load_config = o
+        function(opts)
+            if not opts or #opts < 1 then return false end
+            load_config = opts
             return true
         end,
     },
     {
         "^%-%-load%-json%-config%=(%g*)$",
-        function(o)
-            if not o or #o < 1 then return false end
-            load_json_config = o
+        function(opts)
+            if not opts or #opts < 1 then return false end
+            load_json_config = opts
             return true
         end,
     },
@@ -1477,8 +1584,8 @@ local options = {
         "^(%-%-cmio%-rx%-buffer%=(.+))$",
         function(all, opts)
             if not opts then return false end
-            cmio = cmio or {}
-            cmio.rx_buffer = parse_cmio_buffer(opts, "cmio rx buffer", all)
+            cmio.rx_buffer.backing_store =
+                parse_backing_store(opts, "cmio rx buffer", all, cmio.rx_buffer.backing_store)
             return true
         end,
     },
@@ -1486,8 +1593,8 @@ local options = {
         "^(%-%-cmio%-tx%-buffer%=(.+))$",
         function(all, opts)
             if not opts then return false end
-            cmio = cmio or {}
-            cmio.tx_buffer = parse_cmio_buffer(opts, "tx buffer", all)
+            cmio.tx_buffer.backing_store =
+                parse_backing_store(opts, "cmio tx buffer", all, cmio.tx_buffer.backing_store)
             return true
         end,
     },
@@ -1500,51 +1607,48 @@ local options = {
         end,
     },
     {
-        "^%-u%=(.*)$",
+        "^%-u%=(.+)$",
         handle_user,
     },
     {
-        "^%-%-user%=(.*)$",
+        "^%-%-user%=(.+)$",
         handle_user,
     },
     {
-        "^%-e%=([%w_]+)%=(.*)$",
+        "^%-e%=([%w_]+)%=(.+)$",
         handle_env,
     },
     {
-        "^%-%-env%=([%w_]+)%=(.*)$",
+        "^%-%-env%=([%w_]+)%=(.+)$",
         handle_env,
     },
     {
-        "^%-w%=(.*)$",
+        "^%-w%=(.+)$",
         handle_workdir,
     },
     {
-        "^%-%-workdir%=(.*)$",
+        "^%-%-workdir%=(.+)$",
         handle_workdir,
     },
     {
-        "^%-h%=(.*)$",
+        "^%-h%=(.+)$",
         handle_hostname,
     },
     {
-        "^%-%-hostname%=(.*)$",
+        "^%-%-hostname%=(.+)$",
         handle_hostname,
     },
     {
-        "^%-%-append%-init%=(.*)$",
-        function(o)
-            if not o then return false end
-            if #o == 0 then return true end
-            append_init = append_init .. o .. "\n"
+        "^%-%-append%-init%=(.+)$",
+        function(opts)
+            append_init = append_init .. opts .. "\n"
             return true
         end,
     },
     {
-        "^%-%-append%-init%-file%=(.*)$",
-        function(o)
-            if not o or #o < 1 then return false end
-            local f <close> = assert(io.open(o, "rb"))
+        "^%-%-append%-init%-file%=(.+)$",
+        function(opts)
+            local f <close> = assert(io.open(opts, "rb"))
             local contents = assert(f:read("*a"))
             if not contents:find("\n$") then contents = contents .. "\n" end
             append_init = append_init .. contents
@@ -1552,19 +1656,16 @@ local options = {
         end,
     },
     {
-        "^%-%-append%-entrypoint%=(.*)$",
-        function(o)
-            if not o then return false end
-            if #o == 0 then return true end
-            append_entrypoint = append_entrypoint .. o .. "\n"
+        "^%-%-append%-entrypoint%=(.+)$",
+        function(opts)
+            append_entrypoint = append_entrypoint .. opts .. "\n"
             return true
         end,
     },
     {
-        "^%-%-append%-entrypoint%-file%=(.*)$",
-        function(o)
-            if not o or #o < 1 then return false end
-            local f <close> = assert(io.open(o, "rb"))
+        "^%-%-append%-entrypoint%-file%=(.+)$",
+        function(opts)
+            local f <close> = assert(io.open(opts, "rb"))
             local contents = assert(f:read("*a"))
             if not contents:find("\n$") then contents = contents .. "\n" end
             append_entrypoint = append_entrypoint .. contents
@@ -1573,11 +1674,11 @@ local options = {
     },
     {
         "^%-%-gdb(%=?)(.*)$",
-        function(o, address)
-            if o == "=" and #o > 0 then
+        function(eq, address)
+            if eq == "=" and address ~= "" then
                 gdb_address = address
                 return true
-            elseif o == "" then
+            elseif eq == "" and address == "" then
                 gdb_address = "127.0.0.1:1234"
                 return true
             end
@@ -1587,7 +1688,6 @@ local options = {
     {
         ".*",
         function(all)
-            if not all then return false end
             local not_option = all:sub(1, 1) ~= "-"
             if not_option or all == "--" then
                 cmdline_opts_finished = true
@@ -1599,11 +1699,15 @@ local options = {
     },
 }
 
+local function tryoption(handler, ...)
+    if select(1, ...) ~= nil then return handler(...) end
+end
+
 -- Process command line options
 for _, a in ipairs(arg) do
     if not cmdline_opts_finished then
         for _, option in ipairs(options) do
-            if option[2](a:match(option[1])) then break end
+            if tryoption(option[2], a:match(option[1])) then break end
         end
     else
         exec_arguments[#exec_arguments + 1] = a
@@ -1700,25 +1804,20 @@ else
         processor = {
             iunrep = unreproducible and 1 or 0,
         },
-        dtb = {
-            image_filename = dtb_image_filename,
-            bootargs = bootargs,
-            init = "",
-            entrypoint = "",
-        },
-        ram = {
-            image_filename = ram_image_filename,
-            length = ram_length,
-        },
+        ram = ram,
+        dtb = dtb,
+        flash_drive = {},
+        tlb = tlb,
         htif = {
             console_getchar = htif_console_getchar,
             yield_automatic = htif_yield_automatic,
             yield_manual = htif_yield_manual,
         },
+        virtio = virtio,
         cmio = cmio,
+        pmas = pmas,
         uarch = uarch,
-        flash_drive = {},
-        virtio = virtio,
+        hash_tree = hash_tree,
     }
 
     -- show splash on init
@@ -1742,8 +1841,11 @@ echo "
     for _, label in ipairs(flash_label_order) do
         local devname = "pmem" .. #config.flash_drive
         config.flash_drive[#config.flash_drive + 1] = {
-            image_filename = flash_image_filename[label],
-            shared = flash_shared[label],
+            backing_store = {
+                data_filename = flash_data_filename[label],
+                dht_filename = flash_dht_filename[label],
+                shared = flash_shared[label],
+            },
             start = flash_start[label],
             length = flash_length[label] or -1,
         }
diff --git a/src/clua-i-machine.cpp b/src/clua-i-machine.cpp
index 66c3c3601..bc5a1a3f7 100644
--- a/src/clua-i-machine.cpp
+++ b/src/clua-i-machine.cpp
@@ -820,13 +820,10 @@ static int machine_obj_index_translate_virtual_address(lua_State *L) {
 /// \brief Replaces a memory range.
 /// \param L Lua state.
 static int machine_obj_index_replace_memory_range(lua_State *L) {
-    lua_settop(L, 5);
+    lua_settop(L, 2);
     auto &m = clua_check<clua_managed_cm_ptr<cm_machine>>(L, 1);
-    const uint64_t start = luaL_checkinteger(L, 2);
-    const uint64_t length = luaL_checkinteger(L, 3);
-    const bool shared = lua_toboolean(L, 4) != 0;
-    const char *image_filename = luaL_optstring(L, 5, nullptr);
-    if (cm_replace_memory_range(m.get(), start, length, shared, image_filename) != 0) {
+    const char *range_config = clua_check_json_string(L, 2);
+    if (cm_replace_memory_range(m.get(), range_config) != 0) {
         return luaL_error(L, "%s", cm_get_last_error_message());
     }
     return 0;
diff --git a/src/json-util.cpp b/src/json-util.cpp
index e59cf5f6c..719578307 100644
--- a/src/json-util.cpp
+++ b/src/json-util.cpp
@@ -43,7 +43,6 @@
 #include "machine-runtime-config.h"
 #include "machine.h"
 #include "semantic-version.h"
-#include "uarch-config.h"
 #include "uarch-interpret.h"
 
 namespace cartesi {
@@ -586,12 +585,12 @@ static std::string bracket_type_name(bracket_type bt) {
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, std::string &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jk = j[key];
     if (!jk.is_string()) {
-        throw std::invalid_argument("field \""s + path + to_string(key) + "\" not a string");
+        throw std::invalid_argument("\""s + path + to_string(key) + "\" not a string");
     }
     value = jk.template get<std::string>();
 }
@@ -603,12 +602,12 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, bool &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jk = j[key];
     if (!jk.is_boolean()) {
-        throw std::invalid_argument("field \""s + path + to_string(key) + "\" not a Boolean");
+        throw std::invalid_argument("\""s + path + to_string(key) + "\" not a Boolean");
     }
     value = jk.template get<bool>();
 }
@@ -621,18 +620,18 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, uint64_t &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jk = j[key];
     if (!jk.is_number_integer() && !jk.is_number_unsigned() && !jk.is_number_float()) {
-        throw std::invalid_argument("field \""s + path + to_string(key) + "\" not an unsigned integer");
+        throw std::invalid_argument("\""s + path + to_string(key) + "\" not an unsigned integer");
     }
     if (jk.is_number_float()) {
         auto f = jk.template get<nlohmann::json::number_float_t>();
         if (f < 0 || std::fmod(f, static_cast<nlohmann::json::number_float_t>(1.0)) != 0 ||
             f > static_cast<nlohmann::json::number_float_t>(UINT64_MAX)) {
-            throw std::invalid_argument("field \""s + path + to_string(key) + "\" not an unsigned integer");
+            throw std::invalid_argument("\""s + path + to_string(key) + "\" not an unsigned integer");
         }
         value = static_cast<uint64_t>(f);
         return;
@@ -654,26 +653,26 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, uint32_t &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     uint64_t value64 = 0;
     ju_get_field(j, key, value64, path);
     if (value64 > UINT32_MAX) {
-        throw std::invalid_argument("field \""s + path + to_string(key) + "\" out of range");
+        throw std::invalid_argument("\""s + path + to_string(key) + "\" out of range");
     }
     value = static_cast<uint32_t>(value64);
 }
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, uint16_t &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     uint64_t value64 = 0;
     ju_get_field(j, key, value64, path);
     if (value64 > UINT16_MAX) {
-        throw std::invalid_argument("field \""s + path + to_string(key) + "\" out of range");
+        throw std::invalid_argument("\""s + path + to_string(key) + "\" out of range");
     }
     value = static_cast<uint16_t>(value64);
 }
@@ -692,12 +691,12 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, semantic_version &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jk = j[key];
     if (!jk.is_object()) {
-        throw std::invalid_argument("field \""s + path + to_string(key) + "\" not a semantic version");
+        throw std::invalid_argument("\""s + path + to_string(key) + "\" not a semantic version");
     }
     const auto new_path = path + to_string(key) + "/";
     ju_get_field(jk, "major"s, value.major, new_path);
@@ -715,12 +714,12 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, machine::reg &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jk = j[key];
     if (!jk.is_string()) {
-        throw std::invalid_argument("field \""s + path + to_string(key) + "\" not a string");
+        throw std::invalid_argument("\""s + path + to_string(key) + "\" not a string");
     }
     value = reg_from_name(jk.template get<std::string>());
 }
@@ -733,12 +732,12 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, interpreter_break_reason &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jk = j[key];
     if (!jk.is_string()) {
-        throw std::invalid_argument("field \""s + path + to_string(key) + "\" not a string");
+        throw std::invalid_argument("\""s + path + to_string(key) + "\" not a string");
     }
     value = interpreter_break_reason_from_name(jk.template get<std::string>());
 }
@@ -752,12 +751,12 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, uarch_interpreter_break_reason &value,
     const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jk = j[key];
     if (!jk.is_string()) {
-        throw std::invalid_argument("field \""s + path + to_string(key) + "\" not a string");
+        throw std::invalid_argument("\""s + path + to_string(key) + "\" not a string");
     }
     value = uarch_interpreter_break_reason_from_name(jk.template get<std::string>());
 }
@@ -771,7 +770,7 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, concurrency_runtime_config &value,
     const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     ju_get_opt_field(j[key], "update_merkle_tree"s, value.update_merkle_tree, path + to_string(key) + "/");
@@ -785,7 +784,7 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, htif_runtime_config &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     ju_get_opt_field(j[key], "no_console_putchar"s, value.no_console_putchar, path + to_string(key) + "/");
@@ -799,7 +798,7 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, machine_runtime_config &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     ju_get_opt_field(j[key], "concurrency"s, value.concurrency, path + to_string(key) + "/");
@@ -819,16 +818,16 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, machine_merkle_tree::proof_type::hash_type &value,
     const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jk = j[key];
     if (!jk.is_string()) {
-        throw std::invalid_argument("field \""s + path + to_string(key) + "\" not a string");
+        throw std::invalid_argument("\""s + path + to_string(key) + "\" not a string");
     }
     std::string bin = decode_base64(jk.template get<std::string>());
     if (bin.size() != value.size()) {
-        throw std::invalid_argument("field \""s + path + to_string(key) + "\" not a base64-encoded 256-bit hash");
+        throw std::invalid_argument("\""s + path + to_string(key) + "\" not a base64-encoded 256-bit hash");
     }
     std::copy(bin.begin(), bin.end(), value.data());
 }
@@ -837,17 +836,17 @@ template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key,
     std::optional<machine_merkle_tree::proof_type::hash_type> &optional, const std::string &path) {
     optional = {};
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jk = j[key];
     if (!jk.is_string()) {
-        throw std::invalid_argument("field \""s + path + to_string(key) + "\" not a string");
+        throw std::invalid_argument("\""s + path + to_string(key) + "\" not a string");
     }
     std::string bin = decode_base64(jk.template get<std::string>());
     optional.emplace();
     if (bin.size() != optional.value().size()) {
-        throw std::invalid_argument("field \""s + path + to_string(key) + "\" not a base64-encoded 256-bit hash");
+        throw std::invalid_argument("\""s + path + to_string(key) + "\" not a base64-encoded 256-bit hash");
     }
     std::copy(bin.begin(), bin.end(), optional.value().data());
 }
@@ -862,7 +861,7 @@ template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key,
     not_default_constructible<machine_merkle_tree::proof_type> &value, const std::string &path) {
     value = {};
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jk = j[key];
@@ -870,12 +869,12 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key,
     uint64_t log2_root_size = 0;
     ju_get_field(jk, "log2_root_size"s, log2_root_size, new_path);
     if (log2_root_size > INT_MAX) {
-        throw std::domain_error("field \""s + new_path + "log2_root_size\" is out of bounds");
+        throw std::domain_error("\""s + new_path + "log2_root_size\" is out of bounds");
     }
     uint64_t log2_target_size = 0;
     ju_get_field(jk, "log2_target_size"s, log2_target_size, new_path);
     if (log2_root_size > INT_MAX) {
-        throw std::domain_error("field \""s + new_path + "log2_target_size\" is out of bounds");
+        throw std::domain_error("\""s + new_path + "log2_target_size\" is out of bounds");
     }
     value.emplace(static_cast<int>(log2_root_size), static_cast<int>(log2_target_size));
     auto &proof = value.value();
@@ -888,12 +887,12 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key,
     machine_merkle_tree::proof_type::hash_type root_hash;
     ju_get_field(jk, "root_hash"s, root_hash, new_path);
     proof.set_root_hash(root_hash);
-    if (!contains(jk, "sibling_hashes")) {
-        throw std::invalid_argument("missing field \""s + new_path + "sibling_hashes\""s);
+    if (!contains(jk, "sibling_hashes", new_path)) {
+        throw std::invalid_argument("missing \""s + new_path + "sibling_hashes\""s);
     }
     const auto &sh = jk["sibling_hashes"];
     if (!sh.is_array()) {
-        throw std::invalid_argument("field \""s + new_path + "sibling_hashes\" not an array"s);
+        throw std::invalid_argument("\""s + new_path + "sibling_hashes\" not an array"s);
     }
     const auto sibling_hashes_base = path + "sibling_hashes/";
     for (int log2_size = proof.get_log2_target_size(), i = 0; log2_size < proof.get_log2_root_size();
@@ -912,12 +911,12 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, access_type &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jk = j[key];
     if (!jk.is_string()) {
-        throw std::invalid_argument("field \""s + path + to_string(key) + "\" not a string");
+        throw std::invalid_argument("\""s + path + to_string(key) + "\" not a string");
     }
     const auto &v = jk.template get<std::string>();
     if (v == "read") {
@@ -928,7 +927,7 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, access_type &value,
         value = access_type::write;
         return;
     }
-    throw std::invalid_argument("field \""s + path + to_string(key) + "\" not an access type");
+    throw std::invalid_argument("\""s + path + to_string(key) + "\" not an access type");
 }
 
 template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, access_type &value,
@@ -940,12 +939,12 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, access_data &data, const std::string &path) {
     data.clear();
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jk = j[key];
     if (!jk.is_string()) {
-        throw std::invalid_argument("field \""s + path + to_string(key) + "\" not a string");
+        throw std::invalid_argument("\""s + path + to_string(key) + "\" not a string");
     }
     const auto &bin = decode_base64(jk.template get<std::string>());
     std::copy(bin.begin(), bin.end(), std::back_inserter(data));
@@ -955,12 +954,12 @@ template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, std::optional<access_data> &optional,
     const std::string &path) {
     optional = {};
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jk = j[key];
     if (!jk.is_string()) {
-        throw std::invalid_argument("field \""s + path + to_string(key) + "\" not a string");
+        throw std::invalid_argument("\""s + path + to_string(key) + "\" not a string");
     }
     const auto &bin = decode_base64(jk.template get<std::string>());
     optional.emplace();
@@ -975,12 +974,12 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, access &access, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jk = j[key];
     if (!jk.is_object()) {
-        throw std::invalid_argument("field \""s + path + to_string(key) + "\" not an object");
+        throw std::invalid_argument("\""s + path + to_string(key) + "\" not an object");
     }
     const auto new_path = path + to_string(key) + "/";
     access_type type = access_type::read;
@@ -989,7 +988,7 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, access &access, con
     uint64_t log2_size = 0;
     ju_get_field(jk, "log2_size"s, log2_size, new_path);
     if (log2_size >= 64) {
-        throw std::domain_error("field \""s + new_path + "log2_size\" is out of bounds");
+        throw std::domain_error("\""s + new_path + "log2_size\" is out of bounds");
     }
     access.set_log2_size(static_cast<int>(log2_size));
     // Minimum logged data size is merkle tree word size
@@ -1012,7 +1011,7 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, access &access, con
     ju_get_opt_field(jk, "read"s, read, new_path);
     if (read.has_value()) {
         if (read.value().size() != (UINT64_C(1) << data_log2_size)) {
-            throw std::invalid_argument("field \""s + new_path + "written\" has wrong length");
+            throw std::invalid_argument("\""s + new_path + "written\" has wrong length");
         }
         access.set_read(std::move(read.value()));
     }
@@ -1021,19 +1020,19 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, access &access, con
         ju_get_opt_field(jk, "written"s, written, new_path);
         if (written.has_value()) {
             if (written.value().size() != (UINT64_C(1) << data_log2_size)) {
-                throw std::invalid_argument("field \""s + new_path + "written\" has wrong length");
+                throw std::invalid_argument("\""s + new_path + "written\" has wrong length");
             }
             access.set_written(std::move(written.value()));
         }
     }
-    if (contains(jk, "sibling_hashes")) {
+    if (contains(jk, "sibling_hashes", new_path)) {
         access.get_sibling_hashes().emplace();
         // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
         auto &sibling_hashes = access.get_sibling_hashes().value();
         ju_get_vector_like_field(jk, "sibling_hashes"s, sibling_hashes, new_path);
         auto expected_depth = static_cast<size_t>(machine_merkle_tree::get_log2_root_size() - data_log2_size);
         if (sibling_hashes.size() != expected_depth) {
-            throw std::invalid_argument("field \""s + new_path + "sibling_hashes\" has wrong length");
+            throw std::invalid_argument("\""s + new_path + "sibling_hashes\" has wrong length");
         }
     }
 }
@@ -1046,12 +1045,12 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, bracket_type &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jk = j[key];
     if (!jk.is_string()) {
-        throw std::invalid_argument("field \""s + path + to_string(key) + "\" not a string");
+        throw std::invalid_argument("\""s + path + to_string(key) + "\" not a string");
     }
     const auto &v = jk.template get<std::string>();
     if (v == "begin") {
@@ -1062,7 +1061,7 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, bracket_type &value
         value = bracket_type::end;
         return;
     }
-    throw std::invalid_argument("field \""s + path + to_string(key) + "\" not a bracket type");
+    throw std::invalid_argument("\""s + path + to_string(key) + "\" not a bracket type");
 }
 
 template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, bracket_type &value,
@@ -1073,12 +1072,12 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, bracket_note &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jk = j[key];
     if (!jk.is_object()) {
-        throw std::invalid_argument("field \""s + path + to_string(key) + "\" not an object");
+        throw std::invalid_argument("\""s + path + to_string(key) + "\" not an object");
     }
     const auto new_path = path + to_string(key) + "/";
     ju_get_field(jk, "type"s, value.type, new_path);
@@ -1096,7 +1095,7 @@ template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, not_default_constructible<access_log::type> &optional,
     const std::string &path) {
     optional = {};
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jk = j[key];
@@ -1118,7 +1117,7 @@ template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, not_default_constructible<access_log> &optional,
     const std::string &path) {
     optional = {};
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jk = j[key];
@@ -1132,8 +1131,7 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, not_default_constru
     ju_get_vector_like_field(jk, "accesses"s, accesses, new_path);
     for (unsigned i = 0; i < accesses.size(); ++i) {
         if (!accesses[i].get_sibling_hashes().has_value()) {
-            throw std::invalid_argument(
-                "field \""s + new_path + "accesses/" + to_string(i) + "\" missing sibling hashes");
+            throw std::invalid_argument("\""s + new_path + "accesses/" + to_string(i) + "\" missing sibling hashes");
         }
     }
     std::vector<bracket_note> brackets;
@@ -1147,8 +1145,7 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, not_default_constru
         ju_get_vector_like_field(jk, "brackets"s, brackets, new_path);
         for (unsigned i = 0; i < brackets.size(); ++i) {
             if (brackets[i].where > accesses.size()) {
-                throw std::invalid_argument(
-                    "field \""s + new_path + "brackets/" + to_string(i) + "/where\" is out of range");
+                throw std::invalid_argument("\""s + new_path + "brackets/" + to_string(i) + "/where\" is out of range");
             }
         }
     }
@@ -1163,7 +1160,7 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, processor_config &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jconfig = j[key];
@@ -1276,7 +1273,7 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, dtb_config &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jconfig = j[key];
@@ -1284,7 +1281,7 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, dtb_config &value,
     ju_get_opt_field(jconfig, "bootargs"s, value.bootargs, new_path);
     ju_get_opt_field(jconfig, "init"s, value.init, new_path);
     ju_get_opt_field(jconfig, "entrypoint"s, value.entrypoint, new_path);
-    ju_get_opt_field(jconfig, "image_filename"s, value.image_filename, new_path);
+    ju_get_opt_field(jconfig, "backing_store"s, value.backing_store, new_path);
 }
 
 template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, dtb_config &value,
@@ -1295,13 +1292,13 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, ram_config &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jconfig = j[key];
     const auto new_path = path + to_string(key) + "/";
     ju_get_field(jconfig, "length"s, value.length, new_path);
-    ju_get_opt_field(jconfig, "image_filename"s, value.image_filename, new_path);
+    ju_get_opt_field(jconfig, "backing_store"s, value.backing_store, new_path);
 }
 
 template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, ram_config &value,
@@ -1312,15 +1309,15 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, memory_range_config &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jconfig = j[key];
     const auto new_path = path + to_string(key) + "/";
     ju_get_opt_field(jconfig, "start"s, value.start, new_path);
     ju_get_opt_field(jconfig, "length"s, value.length, new_path);
-    ju_get_opt_field(jconfig, "shared"s, value.shared, new_path);
-    ju_get_opt_field(jconfig, "image_filename"s, value.image_filename, new_path);
+    ju_get_opt_field(jconfig, "read_only"s, value.read_only, new_path);
+    ju_get_opt_field(jconfig, "backing_store"s, value.backing_store, new_path);
 }
 
 template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, memory_range_config &value,
@@ -1330,30 +1327,70 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
     const std::string &path);
 
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, cmio_buffer_config &value, const std::string &path) {
-    if (!contains(j, key)) {
+void ju_get_opt_field(const nlohmann::json &j, const K &key, hash_tree_config &value, const std::string &path) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jconfig = j[key];
     const auto new_path = path + to_string(key) + "/";
     ju_get_opt_field(jconfig, "shared"s, value.shared, new_path);
-    ju_get_opt_field(jconfig, "image_filename"s, value.image_filename, new_path);
+    ju_get_opt_field(jconfig, "truncate"s, value.truncate, new_path);
+    ju_get_opt_field(jconfig, "hasher"s, value.hasher, new_path);
+    ju_get_opt_field(jconfig, "sht_filename"s, value.sht_filename, new_path);
+    ju_get_opt_field(jconfig, "phtc_filename"s, value.phtc_filename, new_path);
+    ju_get_opt_field(jconfig, "phtc_size"s, value.phtc_size, new_path);
 }
 
-template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, cmio_buffer_config &value,
+template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, hash_tree_config &value,
     const std::string &path);
 
-template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key, cmio_buffer_config &value,
+template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key, hash_tree_config &value,
+    const std::string &path);
+
+template <typename K>
+void ju_get_opt_field(const nlohmann::json &j, const K &key, backing_store_config &value, const std::string &path) {
+    if (!contains(j, key, path)) {
+        return;
+    }
+    const auto &jconfig = j[key];
+    const auto new_path = path + to_string(key) + "/";
+    ju_get_opt_field(jconfig, "shared"s, value.shared, new_path);
+    ju_get_opt_field(jconfig, "truncate"s, value.truncate, new_path);
+    ju_get_opt_field(jconfig, "data_filename"s, value.data_filename, new_path);
+    ju_get_opt_field(jconfig, "dht_filename"s, value.dht_filename, new_path);
+}
+
+template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, backing_store_config &value,
     const std::string &path);
 
+template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key,
+    backing_store_config &value, const std::string &path);
+
+template <typename K>
+void ju_get_opt_field(const nlohmann::json &j, const K &key, backing_store_config_only &value,
+    const std::string &path) {
+    if (!contains(j, key, path)) {
+        return;
+    }
+    const auto &jconfig = j[key];
+    const auto new_path = path + to_string(key) + "/";
+    ju_get_opt_field(jconfig, "backing_store"s, value.backing_store, new_path);
+}
+
+template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, backing_store_config_only &value,
+    const std::string &path);
+
+template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key,
+    backing_store_config_only &value, const std::string &path);
+
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, flash_drive_configs &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jflash_drive = j[key];
     if (!jflash_drive.is_array()) {
-        throw std::invalid_argument("field \""s + path + to_string(key) + "\" not an array"s);
+        throw std::invalid_argument("\""s + path + to_string(key) + "\" not an array"s);
     }
     const auto new_path = path + to_string(key) + "/";
     value.resize(0);
@@ -1371,7 +1408,7 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, virtio_device_config &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jconfig = j[key];
@@ -1390,7 +1427,7 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, virtio_device_confi
         if (jconfig.contains("hostfwd")) {
             const auto &jhostfwds = jconfig["hostfwd"];
             if (!jhostfwds.is_array()) {
-                throw std::invalid_argument("field \""s + new_path + "hostfwd\" not an array"s);
+                throw std::invalid_argument("\""s + new_path + "hostfwd\" not an array"s);
             }
             for (const auto &el : jhostfwds.items()) {
                 const auto &jhostfwd = el.value();
@@ -1422,17 +1459,17 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, virtio_configs &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jvirtio = j[key];
     if (!jvirtio.is_array()) {
-        throw std::invalid_argument("field \""s + path + to_string(key) + "\" not an array"s);
+        throw std::invalid_argument("\""s + path + to_string(key) + "\" not an array"s);
     }
     const auto new_path = path + to_string(key) + "/";
     value.resize(0);
     for (uint64_t i = 0; i < jvirtio.size(); ++i) {
-        value.push_back({});
+        value.emplace_back();
         ju_get_opt_field(jvirtio, i, value.back(), new_path);
     }
 }
@@ -1443,25 +1480,9 @@ template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t
 template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key, virtio_configs &value,
     const std::string &path);
 
-template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, tlb_config &value, const std::string &path) {
-    if (!contains(j, key)) {
-        return;
-    }
-    const auto &jconfig = j[key];
-    const auto new_path = path + to_string(key) + "/";
-    ju_get_opt_field(jconfig, "image_filename"s, value.image_filename, new_path);
-}
-
-template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, tlb_config &value,
-    const std::string &path);
-
-template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key, tlb_config &value,
-    const std::string &path);
-
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, clint_config &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jconfig = j[key];
@@ -1477,7 +1498,7 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, plic_config &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jconfig = j[key];
@@ -1494,7 +1515,7 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, htif_config &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jconfig = j[key];
@@ -1514,7 +1535,7 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, cmio_config &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jconfig = j[key];
@@ -1531,7 +1552,7 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, uarch_processor_config &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jconfig = j[key];
@@ -1579,25 +1600,9 @@ template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t
 template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key,
     uarch_processor_config &value, const std::string &path);
 
-template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, uarch_ram_config &value, const std::string &path) {
-    if (!contains(j, key)) {
-        return;
-    }
-    const auto &jconfig = j[key];
-    const auto new_path = path + to_string(key) + "/";
-    ju_get_opt_field(jconfig, "image_filename"s, value.image_filename, new_path);
-}
-
-template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, uarch_ram_config &value,
-    const std::string &path);
-
-template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key, uarch_ram_config &value,
-    const std::string &path);
-
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, uarch_config &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &juarch = j[key];
@@ -1614,7 +1619,7 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, machine_config &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &config = j[key];
@@ -1623,13 +1628,15 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, machine_config &val
     ju_get_opt_field(config, "ram"s, value.ram, new_path);
     ju_get_opt_field(config, "dtb"s, value.dtb, new_path);
     ju_get_opt_field(config, "flash_drive"s, value.flash_drive, new_path);
-    ju_get_opt_field(config, "virtio"s, value.virtio, new_path);
     ju_get_opt_field(config, "tlb"s, value.tlb, new_path);
     ju_get_opt_field(config, "clint"s, value.clint, new_path);
     ju_get_opt_field(config, "plic"s, value.plic, new_path);
     ju_get_opt_field(config, "htif"s, value.htif, new_path);
-    ju_get_opt_field(config, "uarch"s, value.uarch, new_path);
+    ju_get_opt_field(config, "virtio"s, value.virtio, new_path);
     ju_get_opt_field(config, "cmio"s, value.cmio, new_path);
+    ju_get_opt_field(config, "pmas"s, value.pmas, new_path);
+    ju_get_opt_field(config, "uarch"s, value.uarch, new_path);
+    ju_get_opt_field(config, "hash_tree"s, value.hash_tree, new_path);
 }
 
 template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, machine_config &value,
@@ -1641,7 +1648,7 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, address_range_description &value,
     const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jconfig = j[key];
@@ -1671,7 +1678,7 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, fork_result &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jconfig = j[key];
@@ -1774,13 +1781,24 @@ void to_json(nlohmann::json &j, const access_log &log) {
     }
 }
 
+void to_json(nlohmann::json &j, const backing_store_config &config) {
+    j = nlohmann::json{{"shared", config.shared}, {"truncate", config.truncate},
+        {"data_filename", config.data_filename}, {"dht_filename", config.dht_filename}};
+}
+
+void to_json(nlohmann::json &j, const backing_store_config_only &config) {
+    j = nlohmann::json{{"backing_store", config.backing_store}};
+}
+
 void to_json(nlohmann::json &j, const memory_range_config &config) {
-    j = nlohmann::json{{"start", config.start}, {"length", config.length}, {"shared", config.shared},
-        {"image_filename", config.image_filename}};
+    j = nlohmann::json{{"start", config.start}, {"length", config.length}, {"read_only", config.read_only},
+        {"backing_store", config.backing_store}};
 }
 
-void to_json(nlohmann::json &j, const cmio_buffer_config &config) {
-    j = nlohmann::json{{"shared", config.shared}, {"image_filename", config.image_filename}};
+void to_json(nlohmann::json &j, const hash_tree_config &config) {
+    j = nlohmann::json{{"hasher", config.hasher}, {"shared", config.shared}, {"truncate", config.truncate},
+        {"sht_filename", config.sht_filename}, {"phtc_filename", config.phtc_filename},
+        {"phtc_size", config.phtc_size}};
 }
 
 void to_json(nlohmann::json &j, const processor_config &config) {
@@ -1856,7 +1874,7 @@ void to_json(nlohmann::json &j, const virtio_configs &vs) {
 void to_json(nlohmann::json &j, const ram_config &config) {
     j = nlohmann::json{
         {"length", config.length},
-        {"image_filename", config.image_filename},
+        {"backing_store", config.backing_store},
     };
 }
 
@@ -1865,13 +1883,7 @@ void to_json(nlohmann::json &j, const dtb_config &config) {
         {"bootargs", config.bootargs},
         {"init", config.init},
         {"entrypoint", config.entrypoint},
-        {"image_filename", config.image_filename},
-    };
-}
-
-void to_json(nlohmann::json &j, const tlb_config &config) {
-    j = nlohmann::json{
-        {"image_filename", config.image_filename},
+        {"backing_store", config.backing_store},
     };
 }
 
@@ -1945,12 +1957,6 @@ void to_json(nlohmann::json &j, const uarch_processor_config &config) {
     };
 }
 
-void to_json(nlohmann::json &j, const uarch_ram_config &config) {
-    j = nlohmann::json{
-        {"image_filename", config.image_filename},
-    };
-}
-
 void to_json(nlohmann::json &j, const uarch_config &config) {
     j = nlohmann::json{
         {"processor", config.processor},
@@ -1964,13 +1970,15 @@ void to_json(nlohmann::json &j, const machine_config &config) {
         {"ram", config.ram},
         {"dtb", config.dtb},
         {"flash_drive", config.flash_drive},
-        {"virtio", config.virtio},
         {"tlb", config.tlb},
         {"clint", config.clint},
         {"plic", config.plic},
         {"htif", config.htif},
-        {"uarch", config.uarch},
+        {"virtio", config.virtio},
         {"cmio", config.cmio},
+        {"pmas", config.pmas},
+        {"uarch", config.uarch},
+        {"hash_tree", config.hash_tree},
     };
 }
 
diff --git a/src/json-util.h b/src/json-util.h
index 5764a3dff..2823e0cb7 100644
--- a/src/json-util.h
+++ b/src/json-util.h
@@ -37,7 +37,6 @@
 #include "machine-runtime-config.h"
 #include "machine.h"
 #include "semantic-version.h"
-#include "uarch-config.h"
 #include "uarch-interpret.h"
 
 namespace cartesi {
@@ -68,18 +67,24 @@ void ju_get_field(const nlohmann::json &j, const K &key, T &value, const std::st
 
 // Allows use contains when the index is an integer and j contains an array
 template <typename T>
-inline bool contains(const nlohmann::json &j, T i)
+inline bool contains(const nlohmann::json &j, T i, const std::string &path)
     requires(std::is_integral_v<T>)
 {
+    if (!j.empty() && !j.is_array()) {
+        throw std::invalid_argument("\""s + path + "\" not an array");
+    }
     if constexpr (std::is_signed_v<T>) {
-        return j.is_array() && i >= 0 && i < static_cast<T>(j.size());
+        return i >= 0 && i < static_cast<T>(j.size());
     } else {
-        return j.is_array() && i < j.size();
+        return i < j.size();
     }
 }
 
 // Overload for case where index is a string and j contains an object
-inline bool contains(const nlohmann::json &j, const std::string &s) {
+inline bool contains(const nlohmann::json &j, const std::string &s, const std::string &path) {
+    if (!j.empty() && !j.is_object()) {
+        throw std::invalid_argument("\""s + path + "\" not an object");
+    }
     return j.contains(s);
 }
 
@@ -340,54 +345,55 @@ template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, memory_range_config &value,
     const std::string &path = "params/");
 
-/// \brief Attempts to load a cmio_buffer_config object from a field in a JSON object
+/// \brief Attempts to load a backing_store_config object from a field in a JSON object
 /// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
 /// \param j JSON object to load from
 /// \param key Key to load value from
 /// \param value Object to store value
 /// \param path Path to j
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, cmio_buffer_config &value,
+void ju_get_opt_field(const nlohmann::json &j, const K &key, backing_store_config &value,
     const std::string &path = "params/");
 
-/// \brief Attempts to load a flash_drive_configs object from a field in a JSON object
+/// \brief Attempts to load a backing_store_config_only object from a field in a JSON object
 /// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
 /// \param j JSON object to load from
 /// \param key Key to load value from
 /// \param value Object to store value
 /// \param path Path to j
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, flash_drive_configs &value,
+void ju_get_opt_field(const nlohmann::json &j, const K &key, backing_store_config_only &value,
     const std::string &path = "params/");
 
-/// \brief Attempts to load a virtio_device_config object from a field in a JSON object
+/// \brief Attempts to load a flash_drive_configs object from a field in a JSON object
 /// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
 /// \param j JSON object to load from
 /// \param key Key to load value from
 /// \param value Object to store value
 /// \param path Path to j
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, virtio_device_config &value,
+void ju_get_opt_field(const nlohmann::json &j, const K &key, flash_drive_configs &value,
     const std::string &path = "params/");
 
-/// \brief Attempts to load an virtio_configs object from a field in a JSON object
+/// \brief Attempts to load a virtio_device_config object from a field in a JSON object
 /// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
 /// \param j JSON object to load from
 /// \param key Key to load value from
 /// \param value Object to store value
 /// \param path Path to j
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, virtio_configs &value,
+void ju_get_opt_field(const nlohmann::json &j, const K &key, virtio_device_config &value,
     const std::string &path = "params/");
 
-/// \brief Attempts to load a tlb_config object from a field in a JSON object
+/// \brief Attempts to load an virtio_configs object from a field in a JSON object
 /// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
 /// \param j JSON object to load from
 /// \param key Key to load value from
 /// \param value Object to store value
 /// \param path Path to j
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, tlb_config &value, const std::string &path = "params/");
+void ju_get_opt_field(const nlohmann::json &j, const K &key, virtio_configs &value,
+    const std::string &path = "params/");
 
 /// \brief Attempts to load a clint_config object from a field in a JSON object
 /// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
@@ -445,24 +451,24 @@ template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, uarch_processor_config &value,
     const std::string &path = "params/");
 
-/// \brief Attempts to load an uarch_ram_config object from a field in a JSON object
+/// \brief Attempts to load an uarch_config object from a field in a JSON object
 /// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
 /// \param j JSON object to load from
 /// \param key Key to load value from
 /// \param value Object to store value
 /// \param path Path to j
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, uarch_ram_config &value,
-    const std::string &path = "params/");
+void ju_get_opt_field(const nlohmann::json &j, const K &key, uarch_config &value, const std::string &path = "params/");
 
-/// \brief Attempts to load an uarch_config object from a field in a JSON object
+/// \brief Attempts to load an hash_tree_config object from a field in a JSON object
 /// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
 /// \param j JSON object to load from
 /// \param key Key to load value from
 /// \param value Object to store value
 /// \param path Path to j
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, uarch_config &value, const std::string &path = "params/");
+void ju_get_opt_field(const nlohmann::json &j, const K &key, hash_tree_config &value,
+    const std::string &path = "params/");
 
 /// \brief Attempts to load a machine_config object from a field in a JSON object
 /// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
@@ -512,7 +518,7 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, fork_result &value,
 template <typename K, typename A>
 void ju_get_opt_vector_like_field(const nlohmann::json &j, const K &key, A &value, const std::string &path) {
     value.clear();
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         return;
     }
     const auto &jk = j[key];
@@ -542,7 +548,7 @@ void ju_get_opt_vector_like_field(const nlohmann::json &j, const K &key, A &valu
 /// \detail Throws error if field is missing
 template <typename K, typename A>
 void ju_get_vector_like_field(const nlohmann::json &j, const K &key, A &value, const std::string &path = "params/") {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         throw std::invalid_argument("missing field \""s + path + to_string(key) + "\""s);
     }
     return ju_get_opt_vector_like_field(j, key, value, path);
@@ -557,7 +563,7 @@ void ju_get_vector_like_field(const nlohmann::json &j, const K &key, A &value, c
 template <typename T, typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, optional_param<T> &value,
     const std::string &path = "params/") {
-    if (contains(j, key)) {
+    if (contains(j, key, path)) {
         value.emplace();
         ju_get_opt_field(j, key, value.value(), path);
     }
@@ -572,7 +578,7 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, optional_param<T> &
 /// \detail Throws error if field is missing
 template <typename T, typename K>
 void ju_get_field(const nlohmann::json &j, const K &key, T &value, const std::string &path) {
-    if (!contains(j, key)) {
+    if (!contains(j, key, path)) {
         throw std::invalid_argument("missing field \""s + path + to_string(key) + "\""s);
     }
     ju_get_opt_field(j, key, value, path);
@@ -604,22 +610,22 @@ void to_json(nlohmann::json &j, const bracket_note &b);
 void to_json(nlohmann::json &j, const std::vector<bracket_note> &bs);
 void to_json(nlohmann::json &j, const std::vector<access> &as);
 void to_json(nlohmann::json &j, const access_log &log);
+void to_json(nlohmann::json &j, const backing_store_config &config);
+void to_json(nlohmann::json &j, const backing_store_config_only &config);
 void to_json(nlohmann::json &j, const memory_range_config &config);
-void to_json(nlohmann::json &j, const cmio_buffer_config &config);
 void to_json(nlohmann::json &j, const processor_config &config);
 void to_json(nlohmann::json &j, const flash_drive_configs &fs);
 void to_json(nlohmann::json &j, const virtio_device_config &config);
 void to_json(nlohmann::json &j, const virtio_configs &vs);
 void to_json(nlohmann::json &j, const ram_config &config);
 void to_json(nlohmann::json &j, const dtb_config &config);
-void to_json(nlohmann::json &j, const tlb_config &config);
 void to_json(nlohmann::json &j, const clint_config &config);
 void to_json(nlohmann::json &j, const plic_config &config);
 void to_json(nlohmann::json &j, const htif_config &config);
 void to_json(nlohmann::json &j, const cmio_config &config);
 void to_json(nlohmann::json &j, const uarch_processor_config &config);
-void to_json(nlohmann::json &j, const uarch_ram_config &config);
 void to_json(nlohmann::json &j, const uarch_config &config);
+void to_json(nlohmann::json &j, const hash_tree_config &config);
 void to_json(nlohmann::json &j, const machine_config &config);
 void to_json(nlohmann::json &j, const concurrency_runtime_config &config);
 void to_json(nlohmann::json &j, const htif_runtime_config &config);
@@ -731,9 +737,13 @@ extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &k
     const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, memory_range_config &value,
     const std::string &base = "params/");
-extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, cmio_buffer_config &value,
+extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, backing_store_config &value,
+    const std::string &base = "params/");
+extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, backing_store_config &value,
     const std::string &base = "params/");
-extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, cmio_buffer_config &value,
+extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, backing_store_config_only &value,
+    const std::string &base = "params/");
+extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, backing_store_config_only &value,
     const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, flash_drive_configs &value,
     const std::string &base = "params/");
@@ -747,10 +757,6 @@ extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &k
     const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, virtio_configs &value,
     const std::string &base = "params/");
-extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, tlb_config &value,
-    const std::string &base = "params/");
-extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, tlb_config &value,
-    const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, clint_config &value,
     const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, clint_config &value,
@@ -775,14 +781,14 @@ extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &k
     const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, uarch_processor_config &value,
     const std::string &base = "params/");
-extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, uarch_ram_config &value,
-    const std::string &base = "params/");
-extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, uarch_ram_config &value,
-    const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, uarch_config &value,
     const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, uarch_config &value,
     const std::string &base = "params/");
+extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, hash_tree_config &value,
+    const std::string &base = "params/");
+extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, hash_tree_config &value,
+    const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, machine_config &value,
     const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, machine_config &value,
@@ -808,11 +814,11 @@ nlohmann::json to_json(const T &v) {
 }
 
 template <typename T>
-T from_json(const char *s) {
+T from_json(const char *s, const char *path) {
     T value{};
     if (s) {
-        const nlohmann::json j = nlohmann::json{{"value", nlohmann::json::parse(s)}};
-        ju_get_field(j, "value"s, value, ""s);
+        const nlohmann::json j = nlohmann::json{{path, nlohmann::json::parse(s)}};
+        ju_get_field(j, std::string{path}, value, ""s);
     }
     return value;
 }
diff --git a/src/jsonrpc-discover.json b/src/jsonrpc-discover.json
index aa613250b..92e710aa1 100644
--- a/src/jsonrpc-discover.json
+++ b/src/jsonrpc-discover.json
@@ -1307,8 +1307,8 @@
           "length": {
             "$ref": "#/components/schemas/UnsignedInteger"
           },
-          "image_filename": {
-            "type": "string"
+          "backing_store": {
+            "$ref": "#/components/schemas/BackingStoreConfig"
           }
         },
         "required": ["length"]
@@ -1326,8 +1326,8 @@
           "entrypoint": {
             "type": "string"
           },
-          "image_filename": {
-            "type": "string"
+          "backing_store": {
+            "$ref": "#/components/schemas/BackingStoreConfig"
           }
         }
       },
@@ -1341,23 +1341,35 @@
           "length": {
             "$ref": "#/components/schemas/UnsignedInteger"
           },
-          "image_filename": {
-            "type": "string"
-          },
-          "shared": {
-            "type": "boolean"
+          "backing_store": {
+            "$ref": "#/components/schemas/BackingStoreConfig"
           }
         }
       },
-      "CmioBufferConfig": {
-        "title": "CmioBufferConfig",
+      "BackingStoreConfig": {
+        "title": "BackingStoreConfig",
         "type": "object",
         "properties": {
-          "image_filename": {
+          "data_filename": {
+            "type": "string"
+          },
+          "dht_filename": {
             "type": "string"
           },
           "shared": {
             "type": "boolean"
+          },
+          "truncate": {
+            "type": "boolean"
+          }
+        }
+      },
+      "CMIOBufferConfig": {
+        "title": "CMIOBufferConfig",
+        "type": "object",
+        "properties": {
+          "backing_store": {
+            "$ref": "#/components/schemas/BackingStoreConfig"
           }
         }
       },
@@ -1426,8 +1438,8 @@
         "title": "TLBConfig",
         "type": "object",
         "properties": {
-          "image_filename": {
-            "type": "string"
+          "backing_store": {
+            "$ref": "#/components/schemas/BackingStoreConfig"
           }
         }
       },
@@ -1580,7 +1592,7 @@
             "$ref": "#/components/schemas/UnsignedInteger"
           },
           "halt_flag": {
-            "type": "boolean"
+            "$ref": "#/components/schemas/UnsignedInteger"
           }
         }
       },
@@ -1591,8 +1603,8 @@
           "length": {
             "$ref": "#/components/schemas/UnsignedInteger"
           },
-          "image_filename": {
-            "type": "string"
+          "backing_store": {
+            "$ref": "#/components/schemas/BackingStoreConfig"
           }
         }
       },
@@ -1608,15 +1620,45 @@
           }
         }
       },
-      "CmioConfig": {
-        "title": "CmioConfig",
+      "CMIOConfig": {
+        "title": "CMIOConfig",
         "type": "object",
         "properties": {
           "rx_buffer": {
-            "$ref": "#/components/schemas/CmioBufferConfig"
+            "$ref": "#/components/schemas/CMIOBufferConfig"
           },
           "tx_buffer": {
-            "$ref": "#/components/schemas/CmioBufferConfig"
+            "$ref": "#/components/schemas/CMIOBufferConfig"
+          }
+        }
+      },
+      "PMAsConfig": {
+        "title": "PMAsConfig",
+        "type": "object",
+        "properties": {
+          "backing_store": {
+            "$ref": "#/components/schemas/BackingStoreConfig"
+          }
+        }
+      },
+      "HashTreeConfig": {
+        "title": "HashTreeConfig",
+        "type": "object",
+        "properties": {
+          "hasher": {
+            "type": "string"
+          },
+          "shared": {
+            "type": "boolean"
+          },
+          "sht_filename": {
+            "type": "string"
+          },
+          "phtc_filename": {
+            "type": "string"
+          },
+          "phtc_size": {
+            "$ref": "#/components/schemas/UnsignedInteger"
           }
         }
       },
@@ -1655,14 +1697,20 @@
           "htif": {
             "$ref": "#/components/schemas/HTIFConfig"
           },
-          "uarch": {
-            "$ref": "#/components/schemas/UarchConfig"
+          "virtio": {
+            "$ref": "#/components/schemas/VirtIOConfigs"
           },
           "cmio": {
-            "$ref": "#/components/schemas/CmioConfig"
+            "$ref": "#/components/schemas/CMIOConfig"
           },
-          "virtio": {
-            "$ref": "#/components/schemas/VirtIOConfigs"
+          "pmas": {
+            "$ref": "#/components/schemas/PMAsConfig"
+          },
+          "uarch": {
+            "$ref": "#/components/schemas/UarchConfig"
+          },
+          "hash_tree": {
+            "$ref": "#/components/schemas/HashTreeConfig"
           }
         },
         "required": ["ram"]
diff --git a/src/machine-c-api.cpp b/src/machine-c-api.cpp
index 77ddb718a..1ba455cb1 100644
--- a/src/machine-c-api.cpp
+++ b/src/machine-c-api.cpp
@@ -529,10 +529,10 @@ cm_error cm_create(cm_machine *m, const char *config, const char *runtime_config
     if (config == nullptr) {
         throw std::invalid_argument("invalid machine configuration");
     }
-    const auto c = cartesi::from_json<cartesi::machine_config>(config);
+    const auto c = cartesi::from_json<cartesi::machine_config>(config, "config");
     cartesi::machine_runtime_config r;
     if (runtime_config != nullptr) {
-        r = cartesi::from_json<cartesi::machine_runtime_config>(runtime_config);
+        r = cartesi::from_json<cartesi::machine_runtime_config>(runtime_config, "runtime_config");
     }
     cpp_m->create(c, r);
     return cm_result_success();
@@ -547,7 +547,7 @@ cm_error cm_load(cm_machine *m, const char *dir, const char *runtime_config) try
     }
     cartesi::machine_runtime_config r;
     if (runtime_config != nullptr) {
-        r = cartesi::from_json<cartesi::machine_runtime_config>(runtime_config);
+        r = cartesi::from_json<cartesi::machine_runtime_config>(runtime_config, "runtime_config");
     }
     cpp_m->load(dir, r);
     return cm_result_success();
@@ -709,7 +709,7 @@ cm_error cm_verify_step_uarch(const cm_machine *m, const cm_hash *root_hash_befo
         throw std::invalid_argument("invalid access log");
     }
     const auto cpp_log = // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
-        cartesi::from_json<cartesi::not_default_constructible<cartesi::access_log>>(log).value();
+        cartesi::from_json<cartesi::not_default_constructible<cartesi::access_log>>(log, "log").value();
     const cartesi::machine::hash_type cpp_root_hash_before = convert_from_c(root_hash_before);
     const cartesi::machine::hash_type cpp_root_hash_after = convert_from_c(root_hash_after);
     if (m != nullptr) {
@@ -729,7 +729,7 @@ cm_error cm_verify_reset_uarch(const cm_machine *m, const cm_hash *root_hash_bef
         throw std::invalid_argument("invalid access log");
     }
     const auto cpp_log = // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
-        cartesi::from_json<cartesi::not_default_constructible<cartesi::access_log>>(log).value();
+        cartesi::from_json<cartesi::not_default_constructible<cartesi::access_log>>(log, "log").value();
     const cartesi::machine::hash_type cpp_root_hash_before = convert_from_c(root_hash_before);
     const cartesi::machine::hash_type cpp_root_hash_after = convert_from_c(root_hash_after);
     if (m != nullptr) {
@@ -933,7 +933,7 @@ cm_error cm_set_runtime_config(cm_machine *m, const char *runtime_config) try {
     if (runtime_config == nullptr) {
         throw std::invalid_argument("invalid machine runtime configuration");
     }
-    auto r = cartesi::from_json<cartesi::machine_runtime_config>(runtime_config);
+    auto r = cartesi::from_json<cartesi::machine_runtime_config>(runtime_config, "runtime_config");
     auto *cpp_m = convert_from_c(m);
     cpp_m->set_runtime_config(r);
     return cm_result_success();
@@ -961,14 +961,12 @@ cm_error cm_get_default_config(const cm_machine *m, const char **config) try {
     return cm_result_failure();
 }
 
-cm_error cm_replace_memory_range(cm_machine *m, uint64_t start, uint64_t length, bool shared,
-    const char *image_filename) try {
+cm_error cm_replace_memory_range(cm_machine *m, const char *range_config) try {
     auto *cpp_m = convert_from_c(m);
-    cartesi::memory_range_config cpp_range;
-    cpp_range.start = start;
-    cpp_range.length = length;
-    cpp_range.shared = shared;
-    cpp_range.image_filename = (image_filename != nullptr) ? image_filename : "";
+    if (range_config == nullptr) {
+        throw std::invalid_argument("invalid memory range configuration");
+    }
+    const auto cpp_range = cartesi::from_json<cartesi::memory_range_config>(range_config, "range_config");
     cpp_m->replace_memory_range(cpp_range);
     return cm_result_success();
 } catch (...) {
@@ -1095,7 +1093,7 @@ cm_error cm_verify_send_cmio_response(const cm_machine *m, uint16_t reason, cons
         throw std::invalid_argument("invalid access log");
     }
     const auto cpp_log = // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
-        cartesi::from_json<cartesi::not_default_constructible<cartesi::access_log>>(log).value();
+        cartesi::from_json<cartesi::not_default_constructible<cartesi::access_log>>(log, "log").value();
     const cartesi::machine::hash_type cpp_root_hash_before = convert_from_c(root_hash_before);
     const cartesi::machine::hash_type cpp_root_hash_after = convert_from_c(root_hash_after);
     if (m != nullptr) {
diff --git a/src/machine-c-api.h b/src/machine-c-api.h
index d4ced6bb8..53399a20c 100644
--- a/src/machine-c-api.h
+++ b/src/machine-c-api.h
@@ -377,10 +377,14 @@ CM_API void cm_delete(cm_machine *m);
 /// {
 ///     "ram": {
 ///         "length": 134217728,
-///         "image_filename": "linux.bin"
+///         "backing_store": {
+///             "data_filename": "linux.bin"
+///         }
 ///     },
 ///     "flash_drive": [{
-///         "image_filename": "rootfs.ext2"
+///         "backing_store": {
+///             "data_filename": "rootfs.ext2"
+///         }
 ///     }],
 ///     "dtb": {
 ///         "entrypoint": "echo Hello world!"
@@ -452,17 +456,25 @@ CM_API cm_error cm_get_runtime_config(const cm_machine *m, const char **runtime_
 
 /// \brief Replaces a memory range.
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
-/// \param start Range start physical address.
-/// \param length Range length in bytes.
-/// \param shared If true, changes to the range from inside the machine will be
-/// written to the associated image file in the host.
-/// \param image_filename Image file name to load into the range. If NULL, entire
-/// range is cleared with zeros.
+/// \param range_config Memory range configuration as a JSON object in a string.
+/// Must have the same start, length, and read-only settings as an existing memory range.
+/// For example:
+/// ```json
+/// {
+///     "start": 0x80000000000000,
+///     "length": 0x100000,
+///     "read_only": false,
+///     "backing_store": {
+///         "data_filename": "linux.bin"
+///         "dht_filename": "linux.dht"
+///         "shared": false
+///     }
+/// }
+/// ```
 /// \returns 0 for success, non zero code for error.
 /// \details The machine must have been initialized with an existing memory range that
 /// has the same start and length specified in the new range.
-CM_API cm_error cm_replace_memory_range(cm_machine *m, uint64_t start, uint64_t length, bool shared,
-    const char *image_filename);
+CM_API cm_error cm_replace_memory_range(cm_machine *m, const char *range_config);
 
 /// \brief Returns a JSON object with the machine config used to initialize the machine.
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
diff --git a/src/machine-config.cpp b/src/machine-config.cpp
index cfd5f28b5..ea11b6f98 100644
--- a/src/machine-config.cpp
+++ b/src/machine-config.cpp
@@ -35,32 +35,55 @@ static constexpr uint32_t archive_version = 5;
 
 namespace cartesi {
 
-std::string machine_config::get_image_filename(const std::string &dir, uint64_t start, uint64_t length) {
+std::string machine_config::get_data_filename(const std::string &dir, uint64_t start, uint64_t length) {
     std::ostringstream sout;
     sout << dir << "/" << std::hex << std::setw(16) << std::setfill('0') << start << "-" << length << ".bin";
     return sout.str();
 }
 
-std::string machine_config::get_image_filename(const std::string &dir, const memory_range_config &c) {
-    return get_image_filename(dir, c.start, c.length);
+std::string machine_config::get_dht_filename(const std::string &dir, uint64_t start, uint64_t length) {
+    std::ostringstream sout;
+    // dense hash tree
+    sout << dir << "/" << std::hex << std::setw(16) << std::setfill('0') << start << "-" << length << ".dht";
+    return sout.str();
+}
+
+std::string machine_config::get_sht_filename(const std::string &dir) {
+    // sparse hash tree
+    return dir + "/global.sht";
+}
+
+std::string machine_config::get_phtc_filename(const std::string &dir) {
+    // sparse hash tree
+    return dir + "/global.phc";
 }
 
 std::string machine_config::get_config_filename(const std::string &dir) {
     return dir + "/config.json";
 }
 
-static void adjust_image_filenames(machine_config &c, const std::string &dir) {
-    c.dtb.image_filename = machine_config::get_image_filename(dir, AR_DTB_START, AR_DTB_LENGTH);
-    c.ram.image_filename = machine_config::get_image_filename(dir, AR_RAM_START, c.ram.length);
-    c.tlb.image_filename = machine_config::get_image_filename(dir, AR_SHADOW_TLB_START, AR_SHADOW_TLB_LENGTH);
+static void adjust_backing_store(uint64_t start, uint64_t length, const std::string &dir, backing_store_config &c) {
+    c.data_filename = machine_config::get_data_filename(dir, start, length);
+    c.dht_filename = machine_config::get_dht_filename(dir, start, length);
+}
+
+static void adjust_hash_tree(const std::string &dir, hash_tree_config &c) {
+    c.sht_filename = machine_config::get_sht_filename(dir);
+    c.phtc_filename = machine_config::get_phtc_filename(dir);
+}
+
+static void adjust_backing_store(machine_config &c, const std::string &dir) {
+    adjust_backing_store(AR_RAM_START, c.ram.length, dir, c.ram.backing_store);
+    adjust_backing_store(AR_DTB_START, AR_DTB_LENGTH, dir, c.dtb.backing_store);
     for (auto &f : c.flash_drive) {
-        f.image_filename = machine_config::get_image_filename(dir, f);
+        adjust_backing_store(f.start, f.length, dir, f.backing_store);
     }
-    c.uarch.ram.image_filename = machine_config::get_image_filename(dir, AR_UARCH_RAM_START, AR_UARCH_RAM_LENGTH);
-    c.cmio.rx_buffer.image_filename =
-        machine_config::get_image_filename(dir, AR_CMIO_RX_BUFFER_START, AR_CMIO_RX_BUFFER_LENGTH);
-    c.cmio.tx_buffer.image_filename =
-        machine_config::get_image_filename(dir, AR_CMIO_TX_BUFFER_START, AR_CMIO_TX_BUFFER_LENGTH);
+    adjust_backing_store(AR_SHADOW_TLB_START, AR_SHADOW_TLB_LENGTH, dir, c.tlb.backing_store);
+    adjust_backing_store(AR_CMIO_RX_BUFFER_START, AR_CMIO_RX_BUFFER_LENGTH, dir, c.cmio.rx_buffer.backing_store);
+    adjust_backing_store(AR_CMIO_TX_BUFFER_START, AR_CMIO_TX_BUFFER_LENGTH, dir, c.cmio.tx_buffer.backing_store);
+    adjust_backing_store(AR_PMAS_START, AR_PMAS_LENGTH, dir, c.pmas.backing_store);
+    adjust_backing_store(AR_UARCH_RAM_START, AR_UARCH_RAM_LENGTH, dir, c.uarch.ram.backing_store);
+    adjust_hash_tree(dir, c.hash_tree);
 }
 
 machine_config machine_config::load(const std::string &dir) {
@@ -84,7 +107,7 @@ machine_config machine_config::load(const std::string &dir) {
                 std::to_string(jv.get<int>()) + ")");
         }
         ju_get_field(j, std::string("config"), c, "");
-        adjust_image_filenames(c, dir);
+        adjust_backing_store(c, dir);
     } catch (std::exception &e) {
         throw std::runtime_error{e.what()};
     }
diff --git a/src/machine-config.h b/src/machine-config.h
index 30beab497..e8b058ca5 100644
--- a/src/machine-config.h
+++ b/src/machine-config.h
@@ -21,11 +21,9 @@
 #include <cstdint>
 #include <string>
 #include <variant>
-
-#include <boost/container/static_vector.hpp>
+#include <vector>
 
 #include "riscv-constants.h"
-#include "uarch-config.h"
 
 namespace cartesi {
 
@@ -36,7 +34,7 @@ enum machine_config_constants {
     VIRTIO_HOSTFWD_MAX = 16, ///< Maximum number of virtio net user host forward ports
 };
 
-/// \brief Processor state configuration
+/// \brief Processor state config
 struct processor_config final {
     std::array<uint64_t, X_REG_COUNT> x{REG_X0, REG_X1, REG_X2, REG_X3, REG_X4, REG_X5, REG_X6, REG_X7, REG_X8, REG_X9,
         REG_X10, REG_X11, REG_X12, REG_X13, REG_X14, REG_X15, REG_X16, REG_X17, REG_X18, REG_X19, REG_X20, REG_X21,
@@ -79,50 +77,61 @@ struct processor_config final {
     uint64_t iunrep{IUNREP_INIT};               ///< Value of iunrep CSR
 };
 
-/// \brief RAM state configuration
+/// \brief Backing store config
+struct backing_store_config final {
+    bool shared{false};        ///< Should changes be reflected in backing store?
+    bool truncate{false};      ///< Should backing store be truncated to correct size?
+    std::string data_filename; ///< Backing store for associated memory address range
+    std::string dht_filename;  ///< Backing store for corresponding dense hash-tree
+};
+
+/// \brief Config with only backing store config field
+struct backing_store_config_only final {
+    backing_store_config backing_store;
+};
+
+/// \brief RAM state config
 struct ram_config final {
-    uint64_t length{0};         ///< RAM length
-    std::string image_filename; ///< RAM image file name
+    uint64_t length{0};                 ///< RAM length
+    backing_store_config backing_store; ///< Backing store
 };
 
-/// \brief DTB state configuration
+/// \brief DTB state config
 struct dtb_config final {
     std::string bootargs{
         "quiet earlycon=sbi console=hvc0 root=/dev/pmem0 rw init=/usr/sbin/cartesi-init"}; ///< Bootargs to pass
                                                                                            ///< to kernel
-    std::string init;           ///< Initialization commands to be executed as root on boot
-    std::string entrypoint;     ///< Commands to execute the main application
-    std::string image_filename; ///< DTB image file
+    std::string init;                   ///< Initialization commands to be executed as root on boot
+    std::string entrypoint;             ///< Commands to execute the main application
+    backing_store_config backing_store; ///< Backing store
 };
 
-/// \brief Memory range configuration
+/// \brief Memory range config
 struct memory_range_config final {
     uint64_t start{0xffffffffffffffffUL};  ///< Memory range start position, default is to auto detect
     uint64_t length{0xffffffffffffffffUL}; ///< Memory range length, default is to auto detect
-    bool shared{false};                    ///< Target changes to memory affect image file?
-    std::string image_filename;            ///< Memory range image file name
+    bool read_only{false};                 ///< Make memory range read-only
+    backing_store_config backing_store;    ///< Backing store
 };
 
 /// \brief List of flash drives
-using flash_drive_configs = boost::container::static_vector<memory_range_config, FLASH_DRIVE_MAX>;
+using flash_drive_configs = std::vector<memory_range_config>;
 
-/// \brief TLB device state configuration
-struct tlb_config final {
-    std::string image_filename; ///< TLB image file name
-};
+/// \brief TLB device state config
+using tlb_config = backing_store_config_only;
 
-/// \brief CLINT device state configuration
+/// \brief CLINT device state config
 struct clint_config final {
     uint64_t mtimecmp{MTIMECMP_INIT}; ///< Value of mtimecmp CSR
 };
 
-/// \brief PLIC device state configuration
+/// \brief PLIC device state config
 struct plic_config final {
     uint64_t girqpend{GIRQPEND_INIT}; ///< Value of girqpend CSR
     uint64_t girqsrvd{GIRQSRVD_INIT}; ///< Value of girqsrvd CSR
 };
 
-/// \brief HTIF device state configuration
+/// \brief HTIF device state config
 struct htif_config final {
     uint64_t fromhost{FROMHOST_INIT}; ///< Value of fromhost CSR
     uint64_t tohost{TOHOST_INIT};     ///< Value of tohost CSR
@@ -150,7 +159,7 @@ struct virtio_hostfwd_config final {
 };
 
 /// \brief List of VirtIO host forwards
-using virtio_hostfwd_configs = boost::container::static_vector<virtio_hostfwd_config, VIRTIO_HOSTFWD_MAX>;
+using virtio_hostfwd_configs = std::vector<virtio_hostfwd_config>;
 
 /// \brief VirtIO user network device state config
 struct virtio_net_user_config final {
@@ -170,40 +179,74 @@ using virtio_device_config = std::variant<virtio_console_config, ///< Console
     >;
 
 /// \brief List of VirtIO devices
-using virtio_configs = boost::container::static_vector<virtio_device_config, VIRTIO_DEVICE_MAX>;
+using virtio_configs = std::vector<virtio_device_config>;
 
-/// \brief cmio buffer configuration
-struct cmio_buffer_config final {
-    bool shared{false};         ///< Target changes to memory affect image file?
-    std::string image_filename; ///< Memory range image file name
+/// \brief CMIO config
+struct cmio_config final {
+    backing_store_config_only rx_buffer{}; ///< RX buffer config
+    backing_store_config_only tx_buffer{}; ///< TX buffer config
 };
 
-/// \brief Cmio configuration
-struct cmio_config final {
-    cmio_buffer_config rx_buffer; ///< RX buffer configuration
-    cmio_buffer_config tx_buffer; ///< TX buffer configuration
+/// \brief PMAS config
+using pmas_config = backing_store_config_only;
+
+/// \brief Uarch RAM config
+using uarch_ram_config = backing_store_config_only;
+
+/// \brief Uarch processor config
+struct uarch_processor_config final {
+    std::array<uint64_t, UARCH_X_REG_COUNT> x{}; ///< Value of general-purpose registers
+    uint64_t pc{UARCH_PC_INIT};                  ///< Value of pc
+    uint64_t cycle{UARCH_CYCLE_INIT};            ///< Value of ucycle counter
+    uint64_t halt_flag{};
+};
+
+/// \brief Uarch config
+struct uarch_config final {
+    uarch_processor_config processor{}; ///< Uarch processor
+    uarch_ram_config ram{};             ///< Uarch RAM
+};
+
+/// \brief Hash tree config
+struct hash_tree_config final {
+    std::string hasher{"keccak"}; ///< What hashing function to use?
+    bool shared{false};           ///< Should changes be reflected in backing store?
+    bool truncate{false};         ///< Should backing store be truncated to correct size?
+    std::string sht_filename;     ///< Backing storage for sparse hash-tree
+    std::string phtc_filename;    ///< Backing storage for page hash-tree cache
+    uint64_t phtc_size{2046};     ///< Max number of pages in page hash-tree cache
 };
 
-/// \brief Machine state configuration
+/// \brief Machine state config
 struct machine_config final {
-    processor_config processor{};    ///< Processor state
-    ram_config ram{};                ///< RAM state
-    dtb_config dtb{};                ///< DTB state
-    flash_drive_configs flash_drive; ///< Flash drives state
-    tlb_config tlb{};                ///< TLB device state
-    clint_config clint{};            ///< CLINT device state
-    plic_config plic{};              ///< PLIC device state
-    htif_config htif{};              ///< HTIF device state
-    virtio_configs virtio;           ///< VirtIO devices state
-    uarch_config uarch{};            ///< microarchitecture configuration
-    cmio_config cmio{};              ///< Cmio state
+    processor_config processor{};    ///< Processor config
+    ram_config ram{};                ///< RAM config
+    dtb_config dtb{};                ///< Device Tree config
+    flash_drive_configs flash_drive; ///< Flash drives config
+    tlb_config tlb{};                ///< Translation Look-aside Buffer config
+    clint_config clint{};            ///< Core-Local Interruptor config
+    plic_config plic{};              ///< Platform-Level Interrupt Controller config
+    htif_config htif{};              ///< Host-Target config InterFace config
+    virtio_configs virtio;           ///< VirtIO devices config
+    cmio_config cmio{};              ///< Cartesi Machine IO config
+    pmas_config pmas{};              ///< Physical Memory Attributes config
+    uarch_config uarch{};            ///< Microarchition config
+    hash_tree_config hash_tree{};    ///< Hash-tree config
 
     /// \brief Get the name where config will be stored in a directory
     static std::string get_config_filename(const std::string &dir);
 
-    /// \brief Get the name where memory range will be stored in a directory
-    static std::string get_image_filename(const std::string &dir, uint64_t start, uint64_t length);
-    static std::string get_image_filename(const std::string &dir, const memory_range_config &c);
+    /// \brief Get the name where the data for an address range will be stored in a directory
+    static std::string get_data_filename(const std::string &dir, uint64_t start, uint64_t length);
+
+    /// \brief Get the name where dense hash-tree for an address range will be stored in a directory
+    static std::string get_dht_filename(const std::string &dir, uint64_t start, uint64_t length);
+
+    /// \brief Get the name where global sparse hash-tree will be stored in a directory
+    static std::string get_sht_filename(const std::string &dir);
+
+    /// \brief Get the name where global page hash-tree cache will be stored in a directory
+    static std::string get_phtc_filename(const std::string &dir);
 
     /// \brief Loads a machine config from a directory
     /// \param dir Directory from whence "config" will be loaded
diff --git a/src/machine.cpp b/src/machine.cpp
index 1dcb09dac..0eee45f13 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -70,7 +70,6 @@
 #include "strict-aliasing.h"
 #include "tlb.h"
 #include "translate-virtual-address.h"
-#include "uarch-config.h"
 #include "uarch-constants.h"
 #include "uarch-interpret.h"
 #include "uarch-pristine-state-hash.h"
@@ -100,19 +99,20 @@ static const auto throw_invalid_argument = [](const char *err) { throw std::inva
 /// \param start Target physical address where range starts.
 /// \param length Length of range, in bytes.
 /// \param f Flags for address range.
-/// \param image_filename Path to backing file.
-/// \param shared If true, changes to memory range reflect in backing file.
+/// \param backing_store Backing store configuration for range.
 /// \returns New address range with flags already set.
-/// \details If \p image_filename is non-empty, return a memory-mapped range, otherwise use calloc.
+/// \details If \p backing_store.data_filename is non-empty and file is large enough to back entire address range,
+/// return a memory-mapped range, otherwise use calloc.
 static inline auto make_memory_address_range(const std::string &d, uint64_t start, uint64_t length, pmas_flags flags,
-    const std::string &image_filename, bool shared) {
-    if (image_filename.empty() && shared) {
-        throw std::invalid_argument{"shared address range requires non-empty image filename when initializing " + d};
+    const backing_store_config &backing_store) {
+    if (backing_store.data_filename.empty() && backing_store.shared) {
+        throw std::invalid_argument{"shared address range requires non-empty memory filename when initializing " + d};
     }
-    if (image_filename.empty() || length > static_cast<uint64_t>(os_get_file_length(image_filename.c_str()))) {
-        return make_callocd_memory_address_range(d, start, length, flags, image_filename);
+    if (backing_store.data_filename.empty() ||
+        length > static_cast<uint64_t>(os_get_file_length(backing_store.data_filename.c_str()))) {
+        return make_callocd_memory_address_range(d, start, length, flags, backing_store.data_filename);
     }
-    return make_mmapd_memory_address_range(d, start, length, flags, image_filename, shared);
+    return make_mmapd_memory_address_range(d, start, length, flags, backing_store.data_filename, backing_store.shared);
 }
 
 void machine::check_address_range(const address_range &ar, register_where where) {
@@ -152,6 +152,7 @@ static bool is_protected(PMA_ISTART_DID DID) {
 
 void machine::replace_memory_range(const memory_range_config &config) {
     for (auto &existing : m_ars) {
+        //??D Need to add check for new read-only property here
         if (existing->get_start() == config.start && existing->get_length() == config.length) {
             if (!existing->is_memory() || is_protected(existing->get_driver_id())) {
                 throw std::invalid_argument{"attempt to replace a protected range "s + existing->get_description()};
@@ -159,7 +160,7 @@ void machine::replace_memory_range(const memory_range_config &config) {
             // Replace range, preserving original flags.
             // This will automatically start with all pages dirty.
             existing = make_moved_unique(make_memory_address_range(existing->get_description(), existing->get_start(),
-                existing->get_length(), existing->get_flags(), config.image_filename, config.shared));
+                existing->get_length(), existing->get_flags(), config.backing_store));
             return;
         }
     }
@@ -194,16 +195,15 @@ void machine::init_uarch(const uarch_config &c) {
         .DID = PMA_ISTART_DID::memory,
     };
     constexpr auto ram_description = "uarch RAM";
-    if (c.ram.image_filename.empty()) {
+    if (c.ram.backing_store.data_filename.empty()) {
         m_us.ram = &register_address_range(
             make_callocd_memory_address_range(ram_description, AR_UARCH_RAM_START, UARCH_RAM_LENGTH, uram_flags),
             register_where{.merkle = true, .interpret = false});
         memcpy(m_us.ram->get_host_memory(), uarch_pristine_ram, uarch_pristine_ram_len);
     } else {
-        m_us.ram =
-            &register_address_range(make_memory_address_range(ram_description, AR_UARCH_RAM_START, UARCH_RAM_LENGTH,
-                                        uram_flags, c.ram.image_filename, false /* not shared */),
-                register_where{.merkle = true, .interpret = false});
+        m_us.ram = &register_address_range(make_memory_address_range(ram_description, AR_UARCH_RAM_START,
+                                               UARCH_RAM_LENGTH, uram_flags, c.ram.backing_store),
+            register_where{.merkle = true, .interpret = false});
     }
 }
 
@@ -292,12 +292,14 @@ void machine::init_ram_ar(const ram_config &ram) {
     if (ram.length == 0) {
         throw std::invalid_argument("RAM length cannot be zero");
     }
-    register_address_range(
-        make_callocd_memory_address_range("RAM"s, AR_RAM_START, ram.length, ram_flags, ram.image_filename),
+    register_address_range(make_memory_address_range("RAM"s, AR_RAM_START, ram.length, ram_flags, ram.backing_store),
         register_where{.merkle = true, .interpret = true});
 }
 
 void machine::init_flash_drive_ars(flash_drive_configs &flash_drive) {
+    if (flash_drive.size() > FLASH_DRIVE_MAX) {
+        throw std::invalid_argument{"too many flash drives"};
+    }
     // Flags for flash drives
     static const pmas_flags flash_flags{
         .M = true,
@@ -318,39 +320,49 @@ void machine::init_flash_drive_ars(flash_drive_configs &flash_drive) {
             f.start = AR_DRIVE_START + AR_DRIVE_OFFSET * i;
         }
         // Auto detect flash drive image length
+        const auto &image_filename = f.backing_store.data_filename;
         if (f.length == UINT64_C(-1)) {
-            auto fp = make_unique_fopen(f.image_filename.c_str(), "rb");
+            if (image_filename.empty()) {
+                throw std::system_error{errno, std::generic_category(),
+                    "unable to auto-detect length of "s.append(flash_description).append(" with empty image file")};
+            }
+            auto fp = make_unique_fopen(image_filename.c_str(), "rb");
             if (fseek(fp.get(), 0, SEEK_END) != 0) {
                 throw std::system_error{errno, std::generic_category(),
-                    "unable to obtain length of image file '"s + f.image_filename + "' when initializing "s +
-                        flash_description};
+                    "unable to obtain length of image file '"s.append(image_filename)
+                        .append("' when initializing ")
+                        .append(flash_description)};
             }
             const auto length = ftell(fp.get());
             if (length < 0) {
                 throw std::system_error{errno, std::generic_category(),
-                    "unable to obtain length of image file '"s + f.image_filename + "' when initializing "s +
-                        flash_description};
+                    "unable to obtain length of image file '"s.append(image_filename)
+                        .append("' when initializing ")
+                        .append(flash_description)};
             }
             f.length = length;
         }
         register_address_range(
-            make_memory_address_range(flash_description, f.start, f.length, flash_flags, f.image_filename, f.shared),
+            make_memory_address_range(flash_description, f.start, f.length, flash_flags, f.backing_store),
             register_where{.merkle = true, .interpret = true});
         i++;
     }
 }
 
-void machine::init_virtio_ars(const virtio_configs &cs, uint64_t iunrep) {
+void machine::init_virtio_ars(const virtio_configs &virtio, uint64_t iunrep) {
     // Initialize VirtIO devices
-    if (cs.empty()) {
+    if (virtio.empty()) {
         return;
     }
+    if (virtio.size() > VIRTIO_DEVICE_MAX) {
+        throw std::invalid_argument{"too many VirtIO devices"};
+    }
     // VirtIO devices are disallowed in unreproducible mode
     if (iunrep == 0) {
         throw std::invalid_argument{"virtio devices are only supported in unreproducible machines"};
     }
     uint32_t virtio_idx = 0;
-    for (const auto &c : cs) {
+    for (const auto &c : virtio) {
         const auto where = register_where{.merkle = false, .interpret = true};
         const auto visitor = overloads{
             [this, virtio_idx, where](const virtio_console_config &) {
@@ -386,6 +398,9 @@ void machine::init_virtio_ars(const virtio_configs &cs, uint64_t iunrep) {
             },
             [this, virtio_idx, where](const virtio_net_user_config &c) {
 #ifdef HAVE_SLIRP
+                if (c.hostfwd.size() > VIRTIO_HOSTFWD_MAX) {
+                    throw std::invalid_argument("too many virtio network user host-forwarding ports");
+                }
                 const auto start = AR_FIRST_VIRTIO_START + (virtio_idx * AR_VIRTIO_LENGTH);
                 register_address_range(make_virtio_net_user_address_range(start, AR_VIRTIO_LENGTH, virtio_idx, c),
                     where);
@@ -443,10 +458,10 @@ void machine::init_cmio_ars(const cmio_config &c) {
         .DID = PMA_ISTART_DID::cmio_rx_buffer,
     };
     register_address_range(make_memory_address_range("CMIO tx buffer memory range"s, AR_CMIO_TX_BUFFER_START,
-                               AR_CMIO_TX_BUFFER_LENGTH, tx_flags, c.tx_buffer.image_filename, c.tx_buffer.shared),
+                               AR_CMIO_TX_BUFFER_LENGTH, tx_flags, c.tx_buffer.backing_store),
         register_where{.merkle = true, .interpret = true});
     register_address_range(make_memory_address_range("CMIO rx buffer memory range"s, AR_CMIO_RX_BUFFER_START,
-                               AR_CMIO_RX_BUFFER_LENGTH, rx_flags, c.rx_buffer.image_filename, c.rx_buffer.shared),
+                               AR_CMIO_RX_BUFFER_LENGTH, rx_flags, c.rx_buffer.backing_store),
         register_where{.merkle = true, .interpret = true});
 }
 
@@ -486,20 +501,23 @@ void machine::init_plic_ar(const plic_config &p) {
     write_reg(reg::plic_girqsrvd, p.girqsrvd);
 }
 
-void machine::init_pmas_contents(memory_address_range &pmas) const {
+void machine::init_pmas_contents(const pmas_config &config, memory_address_range &pmas) const {
     static_assert(sizeof(pmas_state) == PMA_MAX * 2 * sizeof(uint64_t), "inconsistent PMAs state length");
     static_assert(AR_PMAS_LENGTH >= sizeof(pmas_state), "PMAs address range too short");
-    if (m_s.pmas.size() >= PMA_MAX - 1) { // Leave room for a sentinel empty address range after all others
-        throw std::runtime_error{"too many address ranges"};
+    if (config.backing_store.data_filename.empty()) {
+        if (m_s.pmas.size() >= PMA_MAX - 1) { // Leave room for a sentinel empty address range after all others
+            throw std::runtime_error{"too many address ranges"};
+        }
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        auto &dest = *reinterpret_cast<pmas_state *>(pmas.get_host_memory());
+        std::ranges::transform(m_s.pmas, dest.begin(), [this](auto i) {
+            return pmas_entry{.istart = m_ars[i]->get_istart(), .ilength = m_ars[i]->get_ilength()};
+        });
     }
-    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-    auto &dest = *reinterpret_cast<pmas_state *>(pmas.get_host_memory());
-    std::ranges::transform(m_s.pmas, dest.begin(),
-        [this](auto i) { return pmas_entry{.istart = m_ars[i]->get_istart(), .ilength = m_ars[i]->get_ilength()}; });
 }
 
-void machine::init_tlb_contents(const std::string &image_filename) {
-    if (!image_filename.empty()) {
+void machine::init_tlb_contents(const tlb_config &config) {
+    if (const auto &image_filename = config.backing_store.data_filename; !image_filename.empty()) {
         auto shadow_tlb_ptr = make_unique_mmap<shadow_tlb_state>(image_filename.c_str(), 1, false /* not shared */);
         auto &shadow_tlb = *shadow_tlb_ptr;
         for (auto set_index : {TLB_CODE, TLB_READ, TLB_WRITE}) {
@@ -520,7 +538,7 @@ void machine::init_tlb_contents(const std::string &image_filename) {
     }
 }
 
-static inline auto make_dtb_address_range(const std::string &image_filename) {
+static inline auto make_dtb_address_range(const dtb_config &config) {
     // When we pass a RNG seed in a FDT stored in DTB, Linux will wipe out its contents as a security measure,
     // theref, ore we need to make DTB writable, otherwise boot will hang.
     static constexpr pmas_flags dtb_flags{
@@ -533,17 +551,16 @@ static inline auto make_dtb_address_range(const std::string &image_filename) {
         .IW = true,
         .DID = PMA_ISTART_DID::memory,
     };
-    return make_memory_address_range("DTB"s, AR_DTB_START, AR_DTB_LENGTH, dtb_flags, image_filename,
-        false /* not shared */);
+    return make_memory_address_range("DTB"s, AR_DTB_START, AR_DTB_LENGTH, dtb_flags, config.backing_store);
 }
 
-void machine::init_dtb_contents(const machine_config &c, address_range &dtb) {
-    if (c.dtb.image_filename.empty()) {
-        dtb_init(c, dtb.get_host_memory(), AR_DTB_LENGTH);
+void machine::init_dtb_contents(const machine_config &config, memory_address_range &dtb) {
+    if (config.dtb.backing_store.data_filename.empty()) {
+        dtb_init(config, dtb.get_host_memory(), dtb.get_length());
     }
 }
 
-static inline auto make_pmas_address_range() {
+static inline auto make_pmas_address_range(const pmas_config &config) {
     static constexpr pmas_flags m_pmas_flags{
         .M = true,
         .IO = false,
@@ -554,7 +571,7 @@ static inline auto make_pmas_address_range() {
         .IW = false,
         .DID = PMA_ISTART_DID::memory,
     };
-    return make_callocd_memory_address_range("PMAs", AR_PMAS_START, AR_PMAS_LENGTH, m_pmas_flags);
+    return make_memory_address_range("PMAs", AR_PMAS_START, AR_PMAS_LENGTH, m_pmas_flags, config.backing_store);
 }
 
 // ??D It is best to leave the std::move() on r because it may one day be necessary!
@@ -565,8 +582,8 @@ machine::machine(machine_config c, machine_runtime_config r) : m_c{std::move(c)}
     m_s.soft_yield = m_r.soft_yield;
     init_ram_ar(m_c.ram);
     // Will populate when initialization of PMAs is done
-    auto &dtb = register_address_range(make_dtb_address_range(m_c.dtb.image_filename),
-        register_where{.merkle = true, .interpret = true});
+    auto &dtb =
+        register_address_range(make_dtb_address_range(m_c.dtb), register_where{.merkle = true, .interpret = true});
     init_flash_drive_ars(m_c.flash_drive);
     init_cmio_ars(m_c.cmio);
     init_htif_ar(m_c.htif);
@@ -578,14 +595,15 @@ machine::machine(machine_config c, machine_runtime_config r) : m_c{std::move(c)}
     register_address_range(make_shadow_state_address_range(throw_invalid_argument),
         register_where{.merkle = true, .interpret = false});
     // Will populate when initialization of PMAs is done
-    auto &pmas = register_address_range(make_pmas_address_range(), register_where{.merkle = true, .interpret = true});
+    auto &pmas =
+        register_address_range(make_pmas_address_range(m_c.pmas), register_where{.merkle = true, .interpret = true});
     init_virtio_ars(m_c.virtio, m_c.processor.iunrep);
     // Populate PMAs contents.
     // This must be done after all PMA entries are already registered, so we encode them into the shadow
-    init_pmas_contents(pmas);
+    init_pmas_contents(m_c.pmas, pmas);
     // Initialize TLB contents.
     // This must be done after all PMA entries are already registered, so we can lookup page addresses
-    init_tlb_contents(m_c.tlb.image_filename);
+    init_tlb_contents(m_c.tlb);
     // Initialize DTB contents.
     // This must be done after all PMA entries are already registered, so we can lookup flash drive parameters
     init_dtb_contents(m_c, dtb);
@@ -689,6 +707,11 @@ void machine::set_runtime_config(machine_runtime_config r) {
     os_silence_putchar(m_r.htif.no_console_putchar);
 }
 
+static void clear_backing_store_filenames(backing_store_config &config) {
+    config.data_filename.clear();
+    config.dht_filename.clear();
+}
+
 machine_config machine::get_serialization_config() const {
     if (read_reg(reg::iunrep) != 0) {
         throw std::runtime_error{"cannot serialize configuration of unreproducible machines"};
@@ -751,53 +774,30 @@ machine_config machine::get_serialization_config() const {
     // Ensure we don't mess with DTB by writing the original bootargs
     // over the potentially modified memory region we serialize
     c.dtb.bootargs.clear();
-    // Remove image filenames from serialization
-    // (they will be ignored by save and load for security reasons)
-    c.dtb.image_filename.clear();
-    c.ram.image_filename.clear();
-    c.uarch.ram.image_filename.clear();
-    c.tlb.image_filename.clear();
-    for (auto &f : c.flash_drive) {
-        f.image_filename.clear();
-    }
-    c.cmio.rx_buffer.image_filename.clear();
-    c.cmio.tx_buffer.image_filename.clear();
+    // Copy current uarch state to config
     c.uarch.processor.cycle = read_reg(reg::uarch_cycle);
     c.uarch.processor.halt_flag = read_reg(reg::uarch_halt_flag);
     c.uarch.processor.pc = read_reg(reg::uarch_pc);
     for (int i = 1; i < UARCH_X_REG_COUNT; i++) {
         c.uarch.processor.x[i] = read_reg(machine_reg_enum(reg::uarch_x0, i));
     }
+    // Remove backing filenames from serialization
+    // (they will be ignored by save and load for security reasons)
+    clear_backing_store_filenames(c.ram.backing_store);
+    clear_backing_store_filenames(c.dtb.backing_store);
+    for (auto &f : c.flash_drive) {
+        clear_backing_store_filenames(f.backing_store);
+    }
+    clear_backing_store_filenames(c.tlb.backing_store);
+    clear_backing_store_filenames(c.cmio.rx_buffer.backing_store);
+    clear_backing_store_filenames(c.cmio.tx_buffer.backing_store);
+    clear_backing_store_filenames(c.pmas.backing_store);
+    clear_backing_store_filenames(c.uarch.ram.backing_store);
+    c.hash_tree.sht_filename.clear();
+    c.hash_tree.phtc_filename.clear();
     return c;
 }
 
-void machine::store_address_range(const address_range &ar, const std::string &directory) const {
-    auto name = machine_config::get_image_filename(directory, ar.get_start(), ar.get_length());
-    auto fp = make_unique_fopen(name.c_str(), "wb"); // will throw if it fails
-    // If we have do not have a pointer to the address range memory, use peek
-    if (ar.get_host_memory() == nullptr) {
-        auto scratch = make_unique_calloc<unsigned char>(AR_PAGE_SIZE); // will throw if it fails
-        for (uint64_t offset = 0; offset < ar.get_length(); offset += AR_PAGE_SIZE) {
-            const unsigned char *page_data = nullptr;
-            if (!ar.peek(*this, offset, AR_PAGE_SIZE, &page_data, scratch.get())) {
-                throw std::runtime_error{"peek failed"};
-            }
-            if (page_data == nullptr) {
-                memset(scratch.get(), 0, AR_PAGE_SIZE);
-                page_data = scratch.get();
-            }
-            if (fwrite(page_data, 1, AR_PAGE_SIZE, fp.get()) != AR_PAGE_SIZE) {
-                throw std::system_error{errno, std::generic_category(), "error writing to '" + name + "'"};
-            }
-        }
-        // Otherwise, use memory directly
-    } else {
-        if (fwrite(ar.get_host_memory(), 1, ar.get_length(), fp.get()) != ar.get_length()) {
-            throw std::runtime_error{"error writing to '" + name + "'"};
-        }
-    }
-}
-
 uint64_t machine::get_paddr(host_addr haddr, uint64_t pma_index) const {
     return static_cast<uint64_t>(haddr + get_hp_offset(pma_index));
 }
@@ -909,20 +909,49 @@ const address_range &machine::find_address_range(uint64_t paddr, uint64_t length
     return sentinel;
 }
 
-void machine::store_address_ranges(const machine_config &c, const std::string &dir) const {
+void machine::store_address_range(const address_range &ar, const std::string &directory) const {
+    auto name = machine_config::get_data_filename(directory, ar.get_start(), ar.get_length());
+    auto fp = make_unique_fopen(name.c_str(), "wb"); // will throw if it fails
+    // If we have do not have a pointer to the address range memory, use peek
+    // At the moment, this is the case only for the shadow TLB.
+    if (!ar.is_memory() || ar.get_host_memory() == nullptr) {
+        auto scratch = make_unique_calloc<unsigned char>(AR_PAGE_SIZE); // will throw if it fails
+        for (uint64_t offset = 0; offset < ar.get_length(); offset += AR_PAGE_SIZE) {
+            const unsigned char *page_data = nullptr;
+            if (!ar.peek(*this, offset, AR_PAGE_SIZE, &page_data, scratch.get())) {
+                throw std::runtime_error{"peek failed"};
+            }
+            if (page_data == nullptr) {
+                memset(scratch.get(), 0, AR_PAGE_SIZE);
+                page_data = scratch.get();
+            }
+            if (fwrite(page_data, 1, AR_PAGE_SIZE, fp.get()) != AR_PAGE_SIZE) {
+                throw std::system_error{errno, std::generic_category(), "error writing to '" + name + "'"};
+            }
+        }
+        // Otherwise, use memory directly
+    } else {
+        if (fwrite(ar.get_host_memory(), 1, ar.get_length(), fp.get()) != ar.get_length()) {
+            throw std::runtime_error{"error writing to '" + name + "'"};
+        }
+    }
+}
+
+void machine::store_address_ranges(const machine_config &c, const std::string &directory) const {
     if (read_reg(reg::iunrep) != 0) {
-        throw std::runtime_error{"cannot store PMAs of unreproducible machines"};
+        throw std::runtime_error{"cannot store address ranges of unreproducible machines"};
     }
-    store_address_range(find_address_range<uint64_t>(AR_DTB_START), dir);
-    store_address_range(find_address_range<uint64_t>(AR_RAM_START), dir);
-    store_address_range(find_address_range<uint64_t>(AR_SHADOW_TLB_START), dir);
+    store_address_range(find_address_range<uint64_t>(AR_DTB_START), directory);
+    store_address_range(find_address_range<uint64_t>(AR_RAM_START), directory);
+    store_address_range(find_address_range<uint64_t>(AR_SHADOW_TLB_START), directory);
     // Could iterate over PMAs checking for those with a drive DID but this is easier
     for (const auto &f : c.flash_drive) {
-        store_address_range(find_address_range<uint64_t>(f.start), dir);
+        store_address_range(find_address_range<uint64_t>(f.start), directory);
     }
-    store_address_range(find_address_range<uint64_t>(AR_CMIO_RX_BUFFER_START), dir);
-    store_address_range(find_address_range<uint64_t>(AR_CMIO_TX_BUFFER_START), dir);
-    store_address_range(find_address_range<uint64_t>(AR_UARCH_RAM_START), dir);
+    store_address_range(find_address_range<uint64_t>(AR_CMIO_RX_BUFFER_START), directory);
+    store_address_range(find_address_range<uint64_t>(AR_CMIO_TX_BUFFER_START), directory);
+    store_address_range(find_address_range<uint64_t>(AR_UARCH_RAM_START), directory);
+    store_address_range(find_address_range<uint64_t>(AR_PMAS_START), directory);
 }
 
 static void store_hash(const machine::hash_type &h, const std::string &dir) {
diff --git a/src/machine.h b/src/machine.h
index 56a14f0fd..723409b8d 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -129,7 +129,7 @@ class machine final {
     /// \param directory Directory where address ranges will be stored
     void store_address_ranges(const machine_config &config, const std::string &directory) const;
 
-    /// \brief Saves an address ranges into serialization directory
+    /// \brief Saves an address range into serialization directory
     /// \param ar Address range to store
     /// \param directory Directory where address range will be stored
     void store_address_range(const address_range &ar, const std::string &directory) const;
@@ -156,9 +156,9 @@ class machine final {
     void init_flash_drive_ars(flash_drive_configs &flash_drive);
 
     /// \brief Initializes VirtIO device PMAs
-    /// \param cs VirtIO configurations
+    /// \param virtio VirtIO configurations
     /// \param iunrep Initial value of iunrep CSR
-    void init_virtio_ars(const virtio_configs &cs, uint64_t iunrep);
+    void init_virtio_ars(const virtio_configs &virtio, uint64_t iunrep);
 
     /// \brief Initializes HTIF device address range
     /// \param h HTIF configuration
@@ -193,17 +193,17 @@ class machine final {
     /// \brief Initializes contents of the shadow PMAs memory
     /// \param pmas PMA entry for the shadow PMAs
     /// \detail This can only be called after all PMAs have been added
-    void init_pmas_contents(memory_address_range &pmas) const;
+    void init_pmas_contents(const pmas_config &config, memory_address_range &pmas) const;
 
     /// \brief Initializes contents of machine TLB, from image in disk or with default values
-    /// \param image_filename File containing image, or empty for default values
+    /// \param config TLB config
     /// \detail This can only be called after all PMAs have been added
-    void init_tlb_contents(const std::string &image_filename);
+    void init_tlb_contents(const tlb_config &config);
 
     /// \brief Initializes contents of machine DTB, if image was not available
-    /// \param c Machine configuration
+    /// \param config Machine configuration
     /// \param dtb PMA entry for the shadow PMAs
-    static void init_dtb_contents(const machine_config &c, address_range &dtb);
+    static void init_dtb_contents(const machine_config &config, memory_address_range &dtb);
 
     /// \brief Dumps statistics
     void dump_stats();
diff --git a/src/uarch-config.h b/src/uarch-config.h
deleted file mode 100644
index 6e1e29871..000000000
--- a/src/uarch-config.h
+++ /dev/null
@@ -1,49 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef UARCH_CONFIG_H
-#define UARCH_CONFIG_H
-
-#include <array>
-#include <cstdint>
-#include <string>
-
-#include "riscv-constants.h"
-
-namespace cartesi {
-
-/// \brief RAM state configuration for the microarchitecture
-struct uarch_ram_config final {
-    std::string image_filename; ///< RAM image file name
-};
-
-/// \brief Microarchitecture processor configuration
-struct uarch_processor_config final {
-    std::array<uint64_t, UARCH_X_REG_COUNT> x{}; ///< Value of general-purpose registers
-    uint64_t pc{UARCH_PC_INIT};                  ///< Value of pc
-    uint64_t cycle{UARCH_CYCLE_INIT};            ///< Value of ucycle counter
-    uint64_t halt_flag{};
-};
-
-/// \brief Microarchitecture configuration
-struct uarch_config final {
-    uarch_processor_config processor{}; ///< processor configuration
-    uarch_ram_config ram{};             ///< RAM configuration
-};
-
-} // namespace cartesi
-
-#endif
diff --git a/tests/lua/cartesi-machine-tests.lua b/tests/lua/cartesi-machine-tests.lua
index 92b09c04e..ebae54fc0 100755
--- a/tests/lua/cartesi-machine-tests.lua
+++ b/tests/lua/cartesi-machine-tests.lua
@@ -536,7 +536,8 @@ local options = {
             end
             uarch = uarch or {}
             uarch.ram = uarch.ram or {}
-            uarch.ram.image_filename = o
+            uarch.ram.backing_store = uarch.ram.backing_store or {}
+            uarch.ram.backing_store.data_filename = o
             return true
         end,
     },
@@ -603,7 +604,9 @@ local function build_machine(ram_image)
     local config = {
         ram = {
             length = 32 << 20,
-            image_filename = test_path .. "/" .. ram_image,
+            backing_store = {
+                data_filename = test_path .. "/" .. ram_image,
+            },
         },
         flash_drive = { {
             start = 0x80000000000000,
@@ -645,7 +648,7 @@ local function print_machine(test_name, expected_cycles)
  --uarch-ram-image=%s\
  --max-mcycle=%d ",
             test_path .. "/" .. test_name,
-            uarch.ram.image_filename,
+            uarch.ram.backing_store.data_filename,
             2 * expected_cycles
         ))
     end
diff --git a/tests/lua/create-machines.lua b/tests/lua/create-machines.lua
index 37935b58c..b6ff5381b 100755
--- a/tests/lua/create-machines.lua
+++ b/tests/lua/create-machines.lua
@@ -125,18 +125,18 @@ local function create_default_config(images_dir, command)
     return {
         ram = {
             length = 0x4000000,
-            image_filename = images_dir .. "linux.bin",
+            backing_store = {
+                data_filename = images_dir .. "linux.bin",
+            },
         },
         dtb = {
             entrypoint = command,
         },
-        cmio = {
-            rx_buffer = { shared = false },
-            tx_buffer = { shared = false },
-        },
         flash_drive = {
             {
-                image_filename = images_dir .. "rootfs.ext2",
+                backing_store = {
+                    data_filename = images_dir .. "rootfs.ext2",
+                },
             },
         },
     }
@@ -214,10 +214,10 @@ rollup-init sh /home/dapp/s.sh
 
 -- Should not work with shared buffers
 local ret = pcall(create_machine, "shared-rx-buffer-machine", "rollup accept", function(config)
-    config.cmio.rx_buffer.shared = true
+    config.cmio = { rx_buffer = { backing_store = { shared = true } } }
 end)
 assert(not ret, "should have failed")
 ret = pcall(create_machine, "shared-tx-buffer-machine", "rollup accept", function(config)
-    config.cmio.tx_buffer.shared = true
+    config.cmio = { tx_buffer = { backing_store = { shared = true } } }
 end)
 assert(not ret, "should have failed")
diff --git a/tests/lua/htif-cmio.lua b/tests/lua/htif-cmio.lua
index 41f73712d..8dd4b4487 100755
--- a/tests/lua/htif-cmio.lua
+++ b/tests/lua/htif-cmio.lua
@@ -24,7 +24,9 @@ local config_base = {
         -- This test will fetch the cmio buffers from the PMA entries; check
         -- that `rx_buffer` is filled with a byte pattern;
         -- then write a byte pattern into `tx_buffer` to be checked inside.
-        image_filename = test_util.tests_path .. "htif_cmio.bin",
+        backing_store = {
+            data_filename = test_util.tests_path .. "htif_cmio.bin",
+        },
         length = 0x4000000,
     },
 }
diff --git a/tests/lua/htif-console.lua b/tests/lua/htif-console.lua
index 746a0cbbd..17274893c 100755
--- a/tests/lua/htif-console.lua
+++ b/tests/lua/htif-console.lua
@@ -24,7 +24,9 @@ local config_base = {
         iunrep = 1,
     },
     ram = {
-        image_filename = test_util.tests_path .. "htif_console.bin",
+        backing_store = {
+            data_filename = test_util.tests_path .. "htif_console.bin",
+        },
         length = 0x4000000,
     },
 }
diff --git a/tests/lua/htif-yield.lua b/tests/lua/htif-yield.lua
index 1ea0d4a2b..e62272b5d 100755
--- a/tests/lua/htif-yield.lua
+++ b/tests/lua/htif-yield.lua
@@ -83,7 +83,8 @@ local options = {
             end
             uarch = uarch or {}
             uarch.ram = uarch.ram or {}
-            uarch.ram.image_filename = o
+            uarch.ram.backing_store = {}
+            uarch.ram.backing_store.data_filename = o
             return true
         end,
     },
@@ -119,7 +120,9 @@ end
 -- Config yields 5 times with progress
 local config = {
     ram = {
-        image_filename = test_path .. "/htif_yield.bin",
+        backing_store = {
+            data_filename = test_path .. "/htif_yield.bin",
+        },
         length = 0x4000000,
     },
 }
diff --git a/tests/lua/machine-bind.lua b/tests/lua/machine-bind.lua
index dc020adcf..a7af8ddbe 100755
--- a/tests/lua/machine-bind.lua
+++ b/tests/lua/machine-bind.lua
@@ -273,13 +273,16 @@ local function build_machine_config(config_options)
         ram = { length = 1 << 20 },
         htif = config_options.htif or nil,
         cmio = config_options.cmio or nil,
-        uarch = config_options.uarch or {
-            processor = get_uarch_cpu_reg_test_values(),
-            ram = {
-                length = 0x1000,
-                image_filename = test_util.create_test_uarch_program(test_util.uarch_programs.default),
+        uarch = config_options.uarch
+            or {
+                processor = get_uarch_cpu_reg_test_values(),
+                ram = {
+                    length = 0x1000,
+                    backing_store = {
+                        data_filename = test_util.create_test_uarch_program(test_util.uarch_programs.default),
+                    },
+                },
             },
-        },
     }
     local runtime = {
         concurrency = {
@@ -298,8 +301,8 @@ local function build_machine(type, config_options)
     else
         new_machine = assert(cartesi.machine(config, runtime))
     end
-    if config.uarch.ram and config.uarch.ram.image_filename then
-        os.remove(config.uarch.ram.image_filename)
+    if config.uarch.ram and config.uarch.ram.backing_store and config.uarch.ram.backing_store.data_filename then
+        os.remove(config.uarch.ram.backing_store.data_filename)
     end
     return new_machine
 end
@@ -371,61 +374,136 @@ do_test("should return address value for uarch x registers", function(machine)
     end
 end)
 
-local function test_config_memory_range(range, name)
-    assert(type(range.length) == "number", "invalid " .. name .. ".length")
-    assert(type(range.start) == "number", "invalid " .. name .. ".start")
-    assert(range.shared == nil or type(range.shared) == "boolean", "invalid " .. name .. ".shared")
-    assert(
-        range.image_filename == nil or type(range.image_filename) == "string",
-        "invalid " .. name .. ".image_filename"
-    )
+local function getfield(t, i, i_prev)
+    if not t then
+        return nil
+    end
+    for f in (i .. "."):gmatch("([^%.]*)%.") do
+        if type(t) ~= "table" then
+            error(string.format("type of %s is %s (expected table)", i_prev, type(t)))
+        end
+        t = t[f]
+        i_prev = i_prev .. "." .. f
+        if not t then
+            return nil
+        end
+    end
+    return t
 end
 
-local function test_cmio_buffer_config(buffer_config, name)
-    assert(buffer_config.shared == nil or type(buffer_config.shared) == "boolean", "invalid " .. name .. ".shared")
-    assert(
-        buffer_config.image_filename == nil or type(buffer_config.image_filename) == "string",
-        "invalid " .. name .. ".image_filename"
-    )
+local function assertfield(t, i, expected, i_prev, needed)
+    i_prev = i_prev or "config"
+    local what = type(getfield(t, i, i_prev))
+    if what ~= expected and what ~= "nil" or needed and what == "nil" then
+        error(string.format("type of %s.%s is %s (expected %s)", i_prev, i, what, expected))
+    end
+end
+
+local function test_backing_store_config(config, name, i_prev)
+    assertfield(config, name .. ".shared", "boolean", i_prev)
+    assertfield(config, name .. ".truncate", "boolean", i_prev)
+    assertfield(config, name .. ".data_filename", "string", i_prev)
+    assertfield(config, name .. ".dht_filename", "string", i_prev)
+end
+
+local function test_flash_drive_config(config, i_prev)
+    assertfield(config, "length", "number", i_prev, "needed")
+    assertfield(config, "start", "number", i_prev, "needed")
+    test_backing_store_config(config, "backing_store", i_prev)
 end
 
 local function test_config(config)
     assert(type(config) == "table", "config not a table")
-    for _, field in ipairs({ "processor", "htif", "clint", "plic", "flash_drive", "ram", "dtb" }) do
-        assert(config[field] and type(config[field]) == "table", "invalid field " .. field)
+    local config_fields = {
+        "processor",
+        "ram",
+        "dtb",
+        "flash_drive",
+        "tlb",
+        "clint",
+        "plic",
+        "htif",
+        "virtio",
+        "cmio",
+        "pmas",
+        "uarch",
+        "hash_tree",
+    }
+    for _, field in ipairs(config_fields) do
+        assertfield(config, field, "table")
     end
-    for i = 1, 31 do
-        assert(type(config.processor["x" .. i]) == "number", "x" .. i .. " is not a number")
+    for i = 0, 31 do
+        assertfield(config, "processor.x" .. i, "number")
     end
-    local htif = config.htif
-    for _, field in ipairs({ "console_getchar", "yield_manual", "yield_automatic" }) do
-        assert(htif[field] == nil or type(htif[field]) == "boolean", "invalid htif." .. field)
+    for i = 0, 31 do
+        assertfield(config, "processor.f" .. i, "number")
     end
-    assert(type(htif.tohost) == "number", "invalid htif.tohost")
-    assert(type(htif.fromhost) == "number", "invalid htif.fromhost")
-    local clint = config.clint
-    assert(type(clint.mtimecmp) == "number", "invalid clint.mtimecmp")
-    local plic = config.plic
-    assert(type(plic.girqpend) == "number", "invalid plic.girqpend")
-    assert(type(plic.girqsrvd) == "number", "invalid plic.girqsrvd")
-    local ram = config.ram
-    assert(type(ram.length) == "number", "invalid ram.length")
-    assert(ram.image_filename == nil or type(ram.image_filename) == "string", "invalid ram.image_filename")
-    local dtb = config.dtb
-    assert(dtb.image_filename == nil or type(dtb.image_filename) == "string", "invalid dtb.image_filename")
-    assert(dtb.bootargs == nil or type(dtb.bootargs) == "string", "invalid dtb.bootargs")
-    assert(dtb.init == nil or type(dtb.init) == "string", "invalid dtb.init")
-    assert(dtb.entrypoint == nil or type(dtb.entrypoint) == "string", "invalid dtb.entrypoint")
-    local tlb = config.tlb
-    assert(tlb.image_filename == nil or type(tlb.image_filename) == "string", "invalid tlb.image_filename")
-    for i, f in ipairs(config.flash_drive) do
-        test_config_memory_range(f, "drive" .. (i - 1))
+    local csrs = {
+        "pc",
+        "fcsr",
+        "mvendorid",
+        "marchid",
+        "mimpid",
+        "mcycle",
+        "icycleinstret",
+        "mstatus",
+        "mtvec",
+        "mscratch",
+        "mepc",
+        "mcause",
+        "mtval",
+        "misa",
+        "mie",
+        "mip",
+        "medeleg",
+        "mideleg",
+        "mcounteren",
+        "menvcfg",
+        "stvec",
+        "sscratch",
+        "sepc",
+        "scause",
+        "stval",
+        "satp",
+        "scounteren",
+        "senvcfg",
+        "ilrsc",
+        "iprv",
+        "iflags_X",
+        "iflags_Y",
+        "iflags_H",
+        "iunrep",
+    }
+    for _, csr in ipairs(csrs) do
+        assertfield(config, "processor." .. csr, "number")
     end
-    local cmio = config.cmio
-    if config.cmio then
-        test_cmio_buffer_config(cmio.rx_buffer, "cmio.rx_buffer")
-        test_cmio_buffer_config(cmio.tx_buffer, "cmio.tx_buffer")
+    assertfield(config, "htif.console_getchar", "boolean")
+    assertfield(config, "htif.yield_manual", "boolean")
+    assertfield(config, "htif.yield_automatic", "boolean")
+    assertfield(config, "htif.tohost", "number")
+    assertfield(config, "htif.fromhost", "number")
+    assertfield(config, "clint.mtimecmp", "number")
+    assertfield(config, "plic.girqpend", "number")
+    assertfield(config, "plic.girqsrvd", "number")
+    assertfield(config, "ram.length", "number")
+    test_backing_store_config(config, "ram.backing_store")
+    assertfield(config, "dtb.bootargs", "string")
+    assertfield(config, "dtb.init", "string")
+    assertfield(config, "dtb.entrypoint", "string")
+    test_backing_store_config(config, "dtb.backing_store")
+    test_backing_store_config(config, "tlb.backing_store")
+    test_backing_store_config(config, "pmas.backing_store")
+    for i, f in ipairs(config.flash_drive or {}) do
+        test_flash_drive_config(f, "config.flash_drive[" .. i .. "]")
     end
+    test_backing_store_config(config, "cmio.rx_buffer.backing_store")
+    test_backing_store_config(config, "cmio.tx_buffer.backing_store")
+    test_backing_store_config(config, "uarch.ram.backing_store")
+    assertfield(config, "hash_tree.shared", "boolean")
+    assertfield(config, "hash_tree.truncate", "boolean")
+    assertfield(config, "hash_tree.sht_filename", "string")
+    assertfield(config, "hash_tree.phtc_filename", "string")
+    assertfield(config, "hash_tree.phtc_size", "number")
 end
 
 print("\n\ntesting get_default_config function binding")
@@ -739,7 +817,7 @@ local uarch_proof_step_program = {
 
 test_util.make_do_test(build_machine, machine_type, {
     uarch = {
-        ram = { image_filename = test_util.create_test_uarch_program(uarch_proof_step_program) },
+        ram = { backing_store = { data_filename = test_util.create_test_uarch_program(uarch_proof_step_program) } },
     },
 })("merkle tree must be consistent when stepping alternating with and without proofs", function(machine)
     local t0 = 5
@@ -772,7 +850,7 @@ end)
 
 test_util.make_do_test(build_machine, machine_type, {
     uarch = {
-        ram = { image_filename = test_util.create_test_uarch_program(uarch_proof_step_program) },
+        ram = { backing_store = { data_filename = test_util.create_test_uarch_program(uarch_proof_step_program) } },
     },
 })("It should load the uarch ram image from a file", function(machine)
     local expected_ram_image = ""
@@ -1009,11 +1087,11 @@ do_test("Test unhappy paths of verify_reset_uarch", function(machine)
         log.accesses[1].address = 0
     end)
 
-    assert_error('field "value/accesses/0/log2_size" is out of bounds', function(log)
+    assert_error('"log/accesses/0/log2_size" is out of bounds', function(log)
         log.accesses[1].log2_size = 64
     end)
 
-    assert_error('missing field "value/accesses/0/read_hash"', function(log)
+    assert_error('missing field "log/accesses/0/read_hash"', function(log)
         log.accesses[#log.accesses].read_hash = nil
     end)
     assert_error("siblings and read hash do not match root hash before 1st access to uarch.state", function(log)
@@ -1025,7 +1103,7 @@ do_test("Test unhappy paths of verify_reset_uarch", function(machine)
     assert_error("missing written hash of uarch.state in 1st access", function(log)
         log.accesses[#log.accesses].written_hash = nil
     end)
-    assert_error('field "value/accesses/0/written" has wrong length', function(log)
+    assert_error('"log/accesses/0/written" has wrong length', function(log)
         log.accesses[#log.accesses].written = "\0"
     end)
     assert_error("written data for uarch.state does not match written hash in 1st access", function(log)
@@ -1096,7 +1174,7 @@ local uarch_illegal_insn_program = {
 
 test_util.make_do_test(build_machine, machine_type, {
     uarch = {
-        ram = { image_filename = test_util.create_test_uarch_program(uarch_illegal_insn_program) },
+        ram = { backing_store = { data_filename = test_util.create_test_uarch_program(uarch_illegal_insn_program) } },
     },
 })("Detect illegal instruction", function(machine)
     local success, err = pcall(machine.run_uarch, machine)
@@ -1117,11 +1195,11 @@ do_test("uarch ecall putchar should print char to console", function()
                                  }
                                  local uarch_ram_path = test_util.create_test_uarch_program(program)
                                  local machine = cartesi.machine {
-                                 processor = initial_reg_values,
-                                 ram = {length = 1 << 20},
-                                 uarch = {
-                                    ram = { image_filename = uarch_ram_path }
-                                 }
+                                     processor = initial_reg_values,
+                                     ram = {length = 1 << 20},
+                                     uarch = {
+                                        ram = { backing_store = { data_filename = uarch_ram_path } }
+                                     }
                                  }
                                  os.remove(uarch_ram_path)
                                  machine:run_uarch(3) -- run 3 instructions
@@ -1378,8 +1456,8 @@ local function test_cmio_buffers_backed_by_files()
 
     test_util.make_do_test(build_machine, machine_type, {
         cmio = {
-            rx_buffer = { image_filename = rx_filename, shared = false },
-            tx_buffer = { image_filename = tx_filename, shared = false },
+            rx_buffer = { backing_store = { data_filename = rx_filename, shared = false } },
+            tx_buffer = { backing_store = { data_filename = tx_filename, shared = false } },
         },
     })("cmio buffers initialized from backing files", function(machine)
         local rx_data = machine:read_memory(cartesi.AR_CMIO_RX_BUFFER_START, 1 << cartesi.AR_CMIO_RX_BUFFER_LOG2_SIZE)
@@ -1393,8 +1471,8 @@ local function test_cmio_buffers_backed_by_files()
     -- the shared=false from last test should prevent saving the new data to files
     test_util.make_do_test(build_machine, machine_type, {
         cmio = {
-            rx_buffer = { image_filename = rx_filename, shared = true },
-            tx_buffer = { image_filename = tx_filename, shared = true },
+            rx_buffer = { backing_store = { data_filename = rx_filename, shared = true } },
+            tx_buffer = { backing_store = { data_filename = tx_filename, shared = true } },
         },
     })("cmio buffers initialized from backing files should not change", function(machine)
         local rx_data = machine:read_memory(cartesi.AR_CMIO_RX_BUFFER_START, 1 << cartesi.AR_CMIO_RX_BUFFER_LOG2_SIZE)
@@ -1408,8 +1486,8 @@ local function test_cmio_buffers_backed_by_files()
     -- the shared=true from last test should save memory changes to files
     test_util.make_do_test(build_machine, machine_type, {
         cmio = {
-            rx_buffer = { image_filename = rx_filename, shared = false },
-            tx_buffer = { image_filename = tx_filename, shared = false },
+            rx_buffer = { backing_store = { data_filename = rx_filename, shared = false } },
+            tx_buffer = { backing_store = { data_filename = tx_filename, shared = false } },
         },
     })("cmio buffer files should be modified by last write_memory", function(machine)
         local rx_data = machine:read_memory(cartesi.AR_CMIO_RX_BUFFER_START, 1 << cartesi.AR_CMIO_RX_BUFFER_LOG2_SIZE)
@@ -1425,7 +1503,9 @@ local uarch_store_double_in_t0_to_t1 = {
 }
 test_util.make_do_test(build_machine, machine_type, {
     uarch = {
-        ram = { image_filename = test_util.create_test_uarch_program(uarch_store_double_in_t0_to_t1) },
+        ram = {
+            backing_store = { data_filename = test_util.create_test_uarch_program(uarch_store_double_in_t0_to_t1) },
+        },
     },
 })("Log of word access unaligned to merkle tree leaf ", function(machine)
     local leaf_size = 1 << cartesi.TREE_LOG2_WORD_SIZE
diff --git a/tests/lua/machine-test.lua b/tests/lua/machine-test.lua
index 0fe7a0a7e..2e09eb7f3 100755
--- a/tests/lua/machine-test.lua
+++ b/tests/lua/machine-test.lua
@@ -365,7 +365,11 @@ test_util.make_do_test(build_machine, machine_type, {
 
     machine:read_memory(rootfs.start, 20)
 
-    machine:replace_memory_range(rootfs.start, rootfs.length, true, input_path)
+    machine:replace_memory_range({
+        start = rootfs.start,
+        length = rootfs.length,
+        backing_store = { shared = true, data_filename = input_path },
+    })
 
     local read_data = machine:read_memory(rootfs.start, 20)
 
diff --git a/tests/lua/mtime-interrupt.lua b/tests/lua/mtime-interrupt.lua
index 841eaebc1..e69148461 100755
--- a/tests/lua/mtime-interrupt.lua
+++ b/tests/lua/mtime-interrupt.lua
@@ -22,7 +22,7 @@ local test_util = require("cartesi.tests.util")
 local function build_machine()
     local machine_config = {
         ram = {
-            image_filename = test_util.tests_path .. "mtime_interrupt.bin",
+            backing_store = { data_filename = test_util.tests_path .. "mtime_interrupt.bin" },
             length = 32 << 20,
         },
     }
diff --git a/tests/lua/run-rv64i-arch-test.lua b/tests/lua/run-rv64i-arch-test.lua
index 67b792a27..bce7540c6 100755
--- a/tests/lua/run-rv64i-arch-test.lua
+++ b/tests/lua/run-rv64i-arch-test.lua
@@ -37,14 +37,16 @@ where:
     os.exit(1)
 end
 
-local uarch_ram_image_filename = arg[1]
+local uarch_ram_data_filename = arg[1]
 local output_signature_file = arg[2]
 local uarch_ram_start = cartesi.UARCH_RAM_START_ADDRESS
 
 local config = {
     uarch = {
         ram = {
-            image_filename = uarch_ram_image_filename,
+            backing_store = {
+                data_filename = uarch_ram_data_filename,
+            },
         },
     },
     processor = {},
diff --git a/tests/lua/uarch-riscv-tests.lua b/tests/lua/uarch-riscv-tests.lua
index 5a4713844..55accd815 100755
--- a/tests/lua/uarch-riscv-tests.lua
+++ b/tests/lua/uarch-riscv-tests.lua
@@ -242,16 +242,20 @@ local function fatal(fmt, ...)
 end
 
 local function build_machine(test_name)
-    local uarch_ram = {}
+    local data_filename
     if test_name then
-        uarch_ram.image_filename = test_path .. "/" .. test_name
+        data_filename = test_path .. "/" .. test_name
     end
     local config = {
         ram = {
             length = 0x20000,
         },
         uarch = {
-            ram = uarch_ram,
+            ram = {
+                backing_store = {
+                    data_filename = data_filename,
+                },
+            },
         },
     }
     local runtime = {}
diff --git a/tests/misc/test-machine-c-api.cpp b/tests/misc/test-machine-c-api.cpp
index 018173d72..b39268407 100644
--- a/tests/misc/test-machine-c-api.cpp
+++ b/tests/misc/test-machine-c-api.cpp
@@ -136,7 +136,8 @@ class incomplete_machine_fixture : public default_machine_fixture {
 };
 
 BOOST_FIXTURE_TEST_CASE_NOLINT(create_machine_null_machine_test, incomplete_machine_fixture) {
-    cm_error error_code = cm_create_new(_machine_config.dump().c_str(), nullptr, nullptr);
+    const auto dumped_config = _machine_config.dump();
+    cm_error error_code = cm_create_new(dumped_config.c_str(), nullptr, nullptr);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 
     std::string result = cm_get_last_error_message();
@@ -147,7 +148,9 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(create_machine_null_machine_test, incomplete_mach
 BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_pma_overlapping_test, incomplete_machine_fixture) {
     _machine_config["flash_drive"] = nlohmann::json{{{"start", 0x80000000000000}, {"length", 0x3c00000}},
         {{"start", 0x7ffffffffff000}, {"length", 0x2000}}};
-    cm_error error_code = cm_create_new(_machine_config.dump().c_str(), nullptr, &_machine);
+    const auto dumped_config = _machine_config.dump();
+
+    cm_error error_code = cm_create_new(dumped_config.c_str(), nullptr, &_machine);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 
     std::string result = cm_get_last_error_message();
@@ -158,8 +161,8 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_pma_overlapping_test, incomp
 class machine_flash_simple_fixture : public incomplete_machine_fixture {
 public:
     machine_flash_simple_fixture() {
-        _machine_config["flash_drive"] = {
-            {{"start", 0x80000000000000}, {"length", 0x3c00000}, {"shared", false}, {"image_filename", ""}}};
+        _machine_config["flash_drive"] = {{{"start", 0x80000000000000}, {"length", 0x3c00000}, {"read_only", false},
+            {"backing_store", {{"shared", false}, {"truncate", false}, {"data_filename", ""}, {"dht_filename", ""}}}}};
     }
 
     machine_flash_simple_fixture(const machine_flash_simple_fixture &other) = delete;
@@ -170,8 +173,9 @@ class machine_flash_simple_fixture : public incomplete_machine_fixture {
 
 BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_invalid_alignment_test, machine_flash_simple_fixture) {
     _machine_config["flash_drive"][0]["start"] = 0x80000000000000 - 1;
+    const auto dumped_config = _machine_config.dump();
 
-    cm_error error_code = cm_create_new(_machine_config.dump().c_str(), nullptr, &_machine);
+    cm_error error_code = cm_create_new(dumped_config.c_str(), nullptr, &_machine);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 
     std::string result = cm_get_last_error_message();
@@ -182,8 +186,9 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_invalid_alignment_test, mach
 BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_not_addressable_test, machine_flash_simple_fixture) {
     _machine_config["flash_drive"][0]["start"] = 0x100000000000000 - 0x3c00000 + 4096;
     _machine_config["flash_drive"][0]["length"] = 0x3c00000;
+    const auto dumped_config = _machine_config.dump();
 
-    cm_error error_code = cm_create_new(_machine_config.dump().c_str(), nullptr, &_machine);
+    cm_error error_code = cm_create_new(dumped_config.c_str(), nullptr, &_machine);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 
     std::string result = cm_get_last_error_message();
@@ -195,7 +200,8 @@ class ordinary_machine_fixture : public incomplete_machine_fixture {
 public:
     ordinary_machine_fixture() {
         _machine_dir_path = (std::filesystem::temp_directory_path() / "661b6096c377cdc07756df488059f4407c8f4").string();
-        cm_create_new(_machine_config.dump().c_str(), nullptr, &_machine);
+        const auto dumped_config = _machine_config.dump();
+        cm_create_new(dumped_config.c_str(), nullptr, &_machine);
     }
     ~ordinary_machine_fixture() {
         std::filesystem::remove_all(_machine_dir_path);
@@ -433,9 +439,9 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(get_proof_machine_hash_test, ordinary_machine_fix
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_OK);
     BOOST_CHECK_EQUAL(std::string(""), std::string(cm_get_last_error_message()));
 
-    const auto proof =
-        cartesi::from_json<cartesi::not_default_constructible<cartesi::machine_merkle_tree::proof_type>>(proof_str)
-            .value();
+    const auto proof = cartesi::from_json<cartesi::not_default_constructible<cartesi::machine_merkle_tree::proof_type>>(
+        proof_str, "proof")
+                           .value();
     auto proof_root_hash = proof.get_root_hash();
     auto verification = calculate_proof_root_hash(proof);
     BOOST_CHECK_EQUAL_COLLECTIONS(verification.begin(), verification.end(), proof_root_hash.begin(),
@@ -821,7 +827,9 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(verify_dirty_page_maps_success_test, ordinary_mac
 }
 
 BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_null_flash_config_test, ordinary_machine_fixture) {
-    cm_error error_code = cm_replace_memory_range(_machine, 0, 0, false, nullptr);
+    const auto dumped_range =
+        nlohmann::json{{"start", 0}, {"length", 0}, {"backing_store", {{"shared", false}}}}.dump();
+    cm_error error_code = cm_replace_memory_range(_machine, dumped_range.c_str());
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 
     std::string result = cm_get_last_error_message();
@@ -836,7 +844,11 @@ class flash_drive_machine_fixture : public machine_flash_simple_fixture {
         _flash_file{"/tmp/data.bin"},
         _flash_data{"test data 1234567890"} {
         _machine_dir_path = (std::filesystem::temp_directory_path() / "661b6096c377cdc07756df488059f4407c8f4").string();
-        cm_create_new(_machine_config.dump().c_str(), nullptr, &_machine);
+        const auto dumped_config = _machine_config.dump();
+        cm_error error_code = cm_create_new(dumped_config.c_str(), nullptr, &_machine);
+        BOOST_CHECK_EQUAL(error_code, CM_ERROR_OK);
+        BOOST_CHECK_EQUAL(std::string(""), std::string(cm_get_last_error_message()));
+
         std::ofstream flash_stream(_flash_file);
         flash_stream << _flash_data;
         flash_stream.close();
@@ -869,13 +881,34 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(get_initial_config_flash_drive_test, flash_drive_
     BOOST_CHECK_EQUAL(std::string(cfg), _machine_config.dump());
 }
 
+BOOST_FIXTURE_TEST_CASE_NOLINT(replace_null_memory_range_test, flash_drive_machine_fixture) {
+    cm_error error_code = cm_replace_memory_range(_machine, nullptr);
+    BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
+
+    std::string result = cm_get_last_error_message();
+    std::string origin = "invalid memory range configuration";
+    BOOST_CHECK_EQUAL(origin, result);
+}
+
 BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_null_machine_test, flash_drive_machine_fixture) {
-    cm_error error_code = cm_replace_memory_range(nullptr, 0, 0, false, nullptr);
+    const auto dumped_range =
+        nlohmann::json{{{"start", 0}, {"length", 0}, {{"backing_store", {"shared", false}}}}}.dump();
+    cm_error error_code = cm_replace_memory_range(nullptr, dumped_range.c_str());
+    BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
+}
+
+BOOST_FIXTURE_TEST_CASE_NOLINT(replace_empty_memory_range_test, flash_drive_machine_fixture) {
+    const auto dumped_range =
+        nlohmann::json{{{"start", 0}, {"length", 0}, {{"backing_store", {"shared", false}}}}}.dump();
+    cm_error error_code = cm_replace_memory_range(nullptr, dumped_range.c_str());
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 }
 
 BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_invalid_pma_test, flash_drive_machine_fixture) {
-    cm_error error_code = cm_replace_memory_range(_machine, 0x9000000000000, _flash_size, true, _flash_file.c_str());
+    const auto dumped_range = nlohmann::json{{"start", 0x9000000000000}, {"length", _flash_size},
+        {"backing_store", {{"shared", true}, {"data_filename", _flash_file}}}}
+                                  .dump();
+    cm_error error_code = cm_replace_memory_range(_machine, dumped_range.c_str());
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 
     std::string result = cm_get_last_error_message();
@@ -886,8 +919,11 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_invalid_pma_test, flash_driv
 BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_invalid_length_test, flash_drive_machine_fixture) {
     _flash_size = 0x3c00;
     std::filesystem::resize_file(_flash_file, _flash_size);
+    const auto dumped_range = nlohmann::json{{"start", 0x80000000000000}, {"length", _flash_size},
+        {"backing_store", {{"shared", true}, {"data_filename", _flash_file}}}}
+                                  .dump();
 
-    cm_error error_code = cm_replace_memory_range(_machine, 0x80000000000000, _flash_size, true, _flash_file.c_str());
+    cm_error error_code = cm_replace_memory_range(_machine, dumped_range.c_str());
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 
     std::string result = cm_get_last_error_message();
@@ -897,8 +933,10 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_invalid_length_test, flash_d
 
 BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_file_length_mismatch_test, flash_drive_machine_fixture) {
     _flash_size = 0x3c00;
-
-    cm_error error_code = cm_replace_memory_range(_machine, 0x80000000000000, _flash_size, true, _flash_file.c_str());
+    const auto dumped_range = nlohmann::json{{"start", 0x80000000000000}, {"length", _flash_size},
+        {"backing_store", {{"shared", true}, {"data_filename", _flash_file}}}}
+                                  .dump();
+    cm_error error_code = cm_replace_memory_range(_machine, dumped_range.c_str());
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 
     std::string result = cm_get_last_error_message();
@@ -908,8 +946,11 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_file_length_mismatch_test, f
 
 BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_zero_length_test, flash_drive_machine_fixture) {
     _flash_size = 0x0;
+    const auto dumped_range = nlohmann::json{{"start", 0x80000000000000}, {"length", _flash_size},
+        {"backing_store", {{"shared", true}, {"data_filename", _flash_file}}}}
+                                  .dump();
 
-    cm_error error_code = cm_replace_memory_range(_machine, 0x80000000000000, _flash_size, true, _flash_file.c_str());
+    cm_error error_code = cm_replace_memory_range(_machine, dumped_range.c_str());
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 
     std::string result = cm_get_last_error_message();
@@ -918,7 +959,10 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_zero_length_test, flash_driv
 }
 
 BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_basic_test, flash_drive_machine_fixture) {
-    cm_error error_code = cm_replace_memory_range(_machine, 0x80000000000000, _flash_size, true, _flash_file.c_str());
+    const auto dumped_range = nlohmann::json{{"start", 0x80000000000000}, {"length", _flash_size},
+        {"backing_store", {{"shared", true}, {"data_filename", _flash_file}}}}
+                                  .dump();
+    cm_error error_code = cm_replace_memory_range(_machine, dumped_range.c_str());
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_OK);
     BOOST_CHECK_EQUAL(std::string(""), std::string(cm_get_last_error_message()));
 
@@ -1068,9 +1112,10 @@ class access_log_machine_fixture : public incomplete_machine_fixture {
         std::ofstream of(_uarch_ram_path, std::ios::binary);
         of.write(static_cast<char *>(static_cast<void *>(&test_uarch_ram)), sizeof(test_uarch_ram));
         of.close();
-        _machine_config["uarch"]["ram"]["image_filename"] = _uarch_ram_path;
+        _machine_config["uarch"]["ram"] = {{"backing_store", {{"data_filename", _uarch_ram_path}}}};
+        const auto dumped_config = _machine_config.dump();
 
-        cm_create_new(_machine_config.dump().c_str(), nullptr, &_machine);
+        cm_create_new(dumped_config.c_str(), nullptr, &_machine);
     }
     ~access_log_machine_fixture() {
         cm_delete(_machine);
@@ -1519,9 +1564,9 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(machine_verify_merkle_tree_proof_updates_test, or
     cm_error error_code = cm_get_proof(_machine, 0, 12, &proof_str);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_OK);
     BOOST_CHECK_EQUAL(std::string(""), std::string(cm_get_last_error_message()));
-    auto proof =
-        cartesi::from_json<cartesi::not_default_constructible<cartesi::machine_merkle_tree::proof_type>>(proof_str)
-            .value();
+    auto proof = cartesi::from_json<cartesi::not_default_constructible<cartesi::machine_merkle_tree::proof_type>>(
+        proof_str, "proof")
+                     .value();
     auto proof_root_hash = proof.get_root_hash();
     auto verification = calculate_proof_root_hash(proof);
     BOOST_CHECK_EQUAL_COLLECTIONS(verification.begin(), verification.end(), proof_root_hash.begin(),
@@ -1537,7 +1582,8 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(machine_verify_merkle_tree_proof_updates_test, or
     error_code = cm_get_proof(_machine, 0, 12, &proof_str);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_OK);
     BOOST_CHECK_EQUAL(std::string(""), std::string(cm_get_last_error_message()));
-    proof = cartesi::from_json<cartesi::not_default_constructible<cartesi::machine_merkle_tree::proof_type>>(proof_str)
+    proof = cartesi::from_json<cartesi::not_default_constructible<cartesi::machine_merkle_tree::proof_type>>(proof_str,
+        "proof")
                 .value();
     proof_root_hash = proof.get_root_hash();
     verification = calculate_proof_root_hash(proof);
diff --git a/tests/misc/test-utils.h b/tests/misc/test-utils.h
index 9934c0fd4..4d72cb1fd 100644
--- a/tests/misc/test-utils.h
+++ b/tests/misc/test-utils.h
@@ -95,7 +95,7 @@ static hash_type calculate_emulator_hash(cm_machine *machine) {
     if (cm_get_address_ranges(machine, &ranges_jsonstr) != 0) {
         throw std::runtime_error{cm_get_last_error_message()};
     }
-    const auto mrds = cartesi::from_json<cartesi::address_range_descriptions>(ranges_jsonstr);
+    const auto mrds = cartesi::from_json<cartesi::address_range_descriptions>(ranges_jsonstr, "memory_ranges");
     uint64_t last = 0;
     for (auto m : mrds) {
         tree.pad_back((m.start - last) >> detail::MERKLE_PAGE_LOG2_SIZE);

From ef7f5bc1ffc69ebbaa515313d3c0d7135f2e4d53 Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Wed, 12 Mar 2025 14:34:46 +0000
Subject: [PATCH 32/82] refactor: store end of address range, not length

---
 src/address-range.h               | 56 ++++++++++++++-----------------
 src/machine.cpp                   | 46 ++++++++++++-------------
 tests/misc/test-machine-c-api.cpp |  2 +-
 3 files changed, 48 insertions(+), 56 deletions(-)

diff --git a/src/address-range.h b/src/address-range.h
index be681ccfb..95ea1df9d 100644
--- a/src/address-range.h
+++ b/src/address-range.h
@@ -42,8 +42,7 @@ class address_range {
 
     std::array<char, 32> m_description; ///< Description of address range for use in error messages.
     uint64_t m_start;                   ///< Target physical address where range starts.
-    uint64_t m_length;                  ///< Length of range, in bytes.
-    uint64_t m_length_bit_ceil;         ///< Smallest power of 2 that is not smaller than length, in bytes.
+    uint64_t m_end;                     ///< Target physical address where range ends.
     pmas_flags m_flags;                 ///< Physical memory attribute flags for range.
 
 public:
@@ -53,8 +52,7 @@ class address_range {
     explicit constexpr address_range(const char (&description)[N]) noexcept :
         m_description{},
         m_start{0},
-        m_length{0},
-        m_length_bit_ceil{0},
+        m_end{0},
         m_flags{} {
         for (unsigned i = 0; i < std::min<unsigned>(N, m_description.size() - 1); ++i) {
             m_description[i] = description[i];
@@ -87,38 +85,36 @@ class address_range {
     address_range(const char *description, uint64_t start, uint64_t length, const pmas_flags &flags, ABRT abrt) :
         m_description{},
         m_start{start},
-        m_length{length},
-        m_length_bit_ceil{(length >> 63) == 0 ? std::bit_ceil(length) : 0},
+        m_end{start + length},
         m_flags{flags} {
         // Non-empty description is mandatory
         if (description == nullptr || *description == '\0') {
-            ABRTF(abrt, "address range 0x%" PRIx64 ":0x%" PRIx64 " has empty description", m_start, m_length);
+            ABRTF(abrt, "address range 0x%" PRIx64 ":0x%" PRIx64 " has empty description", start, length);
         }
         for (unsigned i = 0; i < m_description.size() - 1 && description[i] != '\0'; ++i) {
             m_description[i] = description[i];
         }
-        // All address ranges must be page-aligned
-        if ((m_length & ~PMA_ISTART_START_MASK) != 0) {
-            ABRTF(abrt, "length must be multiple of page size when initializing %s", description);
+        // End = start + length cannot overflow
+        if (start >= UINT64_MAX - length) {
+            ABRTF(abrt, "0x%" PRIx64 ":0x%" PRIx64 " is out of bounds when initializing %s", start, length,
+                description);
         }
+        // All address ranges must be page-aligned
         if ((m_start & ~PMA_ISTART_START_MASK) != 0) {
-            ABRTF(abrt, "start of %s (0x%" PRIx64 ") must be aligned to page boundary of %" PRId64 " bytes",
+            ABRTF(abrt, "start of %s (0x%" PRIx64 ") must be aligned to page boundary (every %" PRId64 " bytes)",
                 description, start, AR_PAGE_SIZE);
         }
-        // It must be possible to round length up to the next power of two
-        if (m_length_bit_ceil == 0) {
-            ABRTF(abrt, "address range too long when initializing %s", description);
+        if ((m_end & ~PMA_ISTART_START_MASK) != 0) {
+            ABRTF(abrt, "length of %s (0x% " PRIx64 ") must be multiple of page length (%" PRId64 " bytes)",
+                description, length, AR_PAGE_SIZE);
         }
         // Empty range must really be empty
-        if (m_length == 0) {
-            if (m_start != 0) {
-                ABRTF(abrt, "range with length 0 must start at 0 when initializing %s", description);
+        if (length == 0) {
+            if (start != 0) {
+                ABRTF(abrt, "empty range with length 0 must start at 0 when initializing %s", description);
             }
-            if (m_flags.M) {
-                ABRTF(abrt, "memory address range cannot have length 0 when initializing %s", description);
-            }
-            if (m_flags.IO) {
-                ABRTF(abrt, "device address range cannot have length 0 when initializing %s", description);
+            if (get_istart() != 0) {
+                ABRTF(abrt, "empty range must have clear flags when initializing %s", description);
             }
         }
     }
@@ -157,16 +153,16 @@ class address_range {
         return m_start;
     }
 
+    /// \brief Returns target physical address right past end of range.
+    /// \returns End of range
+    uint64_t get_end() const noexcept {
+        return m_end;
+    }
+
     /// \brief Returns length of range, in bytes.
     /// \returns Length of range
     uint64_t get_length() const noexcept {
-        return m_length;
-    }
-
-    /// \brief Returns smallest power of 2 that is not smaller than range length, in bytes
-    /// \returns Bit-ceil of length of range
-    uint64_t get_length_bit_ceil() const noexcept {
-        return m_length_bit_ceil;
+        return m_end - m_start;
     }
 
     /// \brief Test if address range is occupied by memory
@@ -187,7 +183,7 @@ class address_range {
     /// \returns True if and only if range is empty
     /// \details Empty ranges should be used only for sentinels.
     bool is_empty() const noexcept {
-        return m_length == 0;
+        return m_end == 0;
     }
 
     /// \brief Tests if range is readable
diff --git a/src/machine.cpp b/src/machine.cpp
index 0eee45f13..2f4eef447 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -115,25 +115,22 @@ static inline auto make_memory_address_range(const std::string &d, uint64_t star
     return make_mmapd_memory_address_range(d, start, length, flags, backing_store.data_filename, backing_store.shared);
 }
 
-void machine::check_address_range(const address_range &ar, register_where where) {
+void machine::check_address_range(const address_range &new_ar, register_where where) {
     if (!where.interpret && !where.merkle) {
-        throw std::runtime_error{"address range "s + ar.get_description() + " must be registered somwhere"s};
+        throw std::runtime_error{"address range "s + new_ar.get_description() + " must be registered somewhere"s};
     }
-    const auto start = ar.get_start();
-    const auto length = ar.get_length();
+    const auto start = new_ar.get_start();
+    const auto end = new_ar.get_end();
     // Checks if new range is machine addressable space (safe unsigned overflows)
-    if (start > AR_ADDRESSABLE_MASK || (length > 0 && (length - 1) > (AR_ADDRESSABLE_MASK - start))) {
+    if (start > AR_ADDRESSABLE_MASK || end > AR_ADDRESSABLE_MASK) {
         throw std::invalid_argument{
-            "address range of "s + ar.get_description() + " must use at most 56 bits to be addressable"s};
+            "address range of "s + new_ar.get_description() + " must use at most 56 bits to be addressable"s};
     }
-    const auto length_bit_ceil = ar.get_length_bit_ceil();
     // Range A overlaps with B if A starts before B ends and A ends after B starts
-    for (const auto &existing : m_ars) {
-        const auto existing_start = existing->get_start();
-        const auto existing_length_bit_ceil = existing->get_length_bit_ceil();
-        if (start < existing_start + existing_length_bit_ceil && start + length_bit_ceil > existing_start) {
-            throw std::invalid_argument{"address range of "s + ar.get_description() +
-                " overlaps with address range of existing "s + existing->get_description()};
+    for (const auto &ar : m_ars) {
+        if (start < ar->get_end() && end > ar->get_start()) {
+            throw std::invalid_argument{"address range of "s + new_ar.get_description() +
+                " overlaps with address range of existing "s + ar->get_description()};
         }
     }
 }
@@ -151,16 +148,16 @@ static bool is_protected(PMA_ISTART_DID DID) {
 }
 
 void machine::replace_memory_range(const memory_range_config &config) {
-    for (auto &existing : m_ars) {
+    for (auto &ar : m_ars) {
         //??D Need to add check for new read-only property here
-        if (existing->get_start() == config.start && existing->get_length() == config.length) {
-            if (!existing->is_memory() || is_protected(existing->get_driver_id())) {
-                throw std::invalid_argument{"attempt to replace a protected range "s + existing->get_description()};
+        if (ar->get_start() == config.start && ar->get_length() == config.length) {
+            if (!ar->is_memory() || is_protected(ar->get_driver_id())) {
+                throw std::invalid_argument{"attempt to replace a protected range "s + ar->get_description()};
             }
             // Replace range, preserving original flags.
             // This will automatically start with all pages dirty.
-            existing = make_moved_unique(make_memory_address_range(existing->get_description(), existing->get_start(),
-                existing->get_length(), existing->get_flags(), config.backing_store));
+            ar = make_moved_unique(make_memory_address_range(ar->get_description(), ar->get_start(), ar->get_length(),
+                ar->get_flags(), config.backing_store));
             return;
         }
     }
@@ -862,8 +859,7 @@ void machine::check_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, uin
         if ((paddr_page & PAGE_OFFSET_MASK) != 0) {
             throw std::invalid_argument{prefix + "vp_offset is not aligned"s};
         }
-        const auto pmas_end = ar.get_start() + (ar.get_length() - AR_PAGE_SIZE);
-        if (paddr_page < ar.get_start() || paddr_page > pmas_end) {
+        if (paddr_page < ar.get_start() || paddr_page >= ar.get_end()) {
             throw std::invalid_argument{prefix + "vp_offset is inconsistent with pma_index"s};
         }
     } else if (pma_index != TLB_INVALID_PMA_INDEX || vp_offset != 0) {
@@ -1848,8 +1844,8 @@ bool machine::verify_dirty_page_maps() const {
     mark_write_tlb_dirty_pages();
     // Now go over all memory PMAs verifying that all dirty pages are marked
     for (const auto &ar : m_ars) {
-        for (uint64_t offset = 0; offset < ar->get_length(); offset += AR_PAGE_SIZE) {
-            const uint64_t page_address = ar->get_start() + offset;
+        for (uint64_t page_address = ar->get_start(); page_address < ar->get_end(); page_address += AR_PAGE_SIZE) {
+            const auto offset = page_address - ar->get_start();
             if (ar->is_memory()) {
                 const unsigned char *page_data = nullptr;
                 ar->peek(*this, offset, AR_PAGE_SIZE, &page_data, scratch.get());
@@ -2130,7 +2126,7 @@ void machine::read_memory(uint64_t paddr, unsigned char *data, uint64_t length)
         std::views::transform(
             [this](auto i) -> address_range & { return *m_ars[i]; }) |        // Now address ranges themselves
         std::views::drop_while([paddr, &gap_start](const address_range &ar) { // Only those that end after paddr
-            const auto ar_end = ar.get_start() + ar.get_length();
+            const auto ar_end = ar.get_end();
             if (paddr >= ar_end) {
                 gap_start = ar_end;
                 return true;
@@ -2147,7 +2143,7 @@ void machine::read_memory(uint64_t paddr, unsigned char *data, uint64_t length)
             paddr += from_gap;
             data += from_gap;
         }
-        gap_start = ar_start + ar.get_length();
+        gap_start = ar.get_end();
         // Write as much as possible from current address range
         if (paddr >= ar_start && paddr < gap_start) {
             const auto from_ar = std::min(gap_start - paddr, length);
diff --git a/tests/misc/test-machine-c-api.cpp b/tests/misc/test-machine-c-api.cpp
index b39268407..8ab7904bf 100644
--- a/tests/misc/test-machine-c-api.cpp
+++ b/tests/misc/test-machine-c-api.cpp
@@ -179,7 +179,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_invalid_alignment_test, mach
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 
     std::string result = cm_get_last_error_message();
-    std::string origin("start of flash drive 0 (0x7fffffffffffff) must be aligned to page boundary of 4096 bytes");
+    std::string origin("start of flash drive 0 (0x7fffffffffffff) must be aligned to page boundary (every 4096 bytes)");
     BOOST_CHECK_EQUAL(origin, result);
 }
 

From a13405d5dcced5aa02585c37d33b0b0ef39eb03d Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Fri, 28 Mar 2025 22:28:18 +0000
Subject: [PATCH 33/82] refactor: improve initialization

Factor out a machine_address_ranges object to manage all address ranges.
This can be constructed in the initializer list of the machine constructor.
---
 src/Makefile                           |   5 +-
 src/assert-printf.h                    |   2 +-
 src/clint-address-range.cpp            |   2 +-
 src/dtb.cpp                            |   1 -
 src/machine-address-ranges.cpp         | 409 +++++++++++++++++++
 src/machine-address-ranges.h           | 190 +++++++++
 src/machine-c-api.cpp                  |   2 +-
 src/machine-config.cpp                 |   3 +-
 src/machine-state.h                    |   2 -
 src/machine.cpp                        | 534 ++++---------------------
 src/machine.h                          | 252 ++++--------
 src/memory-address-range.cpp           |   9 +
 src/pmas.h                             |  12 +
 src/record-send-cmio-state-access.h    |   2 +-
 src/shadow-uarch-state-address-range.h |  10 +-
 src/uarch-state-access.h               |  14 +-
 src/uarch-state.h                      |   2 -
 17 files changed, 792 insertions(+), 659 deletions(-)
 create mode 100644 src/machine-address-ranges.cpp
 create mode 100644 src/machine-address-ranges.h

diff --git a/src/Makefile b/src/Makefile
index 8b739d904..8eee948ad 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -137,8 +137,8 @@ LIBCARTESI_JSONRPC=libcartesi_jsonrpc-$(EMULATOR_VERSION_MAJOR).$(EMULATOR_VERSI
 
 ifeq ($(slirp),yes)
 # Workaround for building with macports lua-luarocks installation
-machine.o: INCS+=$(SLIRP_INC)
-machine.clang-tidy: INCS+=$(SLIRP_INC)
+machine-address-ranges.o: INCS+=$(SLIRP_INC)
+machine-address-ranges.clang-tidy: INCS+=$(SLIRP_INC)
 virtio-net-user-address-range.o: INCS+=$(SLIRP_INC)
 virtio-net-user-address-range.clang-tidy: INCS+=$(SLIRP_INC)
 #INCS+=$(SLIRP_INC)
@@ -360,6 +360,7 @@ LIBCARTESI_OBJS:= \
 	machine-config.o \
 	machine-merkle-tree.o \
 	machine.o \
+	machine-address-ranges.o \
 	memory-address-range.o \
 	os.o \
 	plic-address-range.o \
diff --git a/src/assert-printf.h b/src/assert-printf.h
index 0f0f5b41b..015e17997 100644
--- a/src/assert-printf.h
+++ b/src/assert-printf.h
@@ -37,7 +37,7 @@ static inline void d_vprintf(const char *fmt, va_list ap) {
 // Better to use C-style variadic function that checks for format!
 // NOLINTNEXTLINE(cert-dcl50-cpp)
 __attribute__((__format__(__printf__, 1, 2))) static inline void d_printf(const char *fmt, ...) {
-    va_list ap;
+    va_list ap{};
     va_start(ap, fmt);
     d_vprintf(fmt, ap);
     va_end(ap);
diff --git a/src/clint-address-range.cpp b/src/clint-address-range.cpp
index 9ffeb0416..b8992f5c2 100644
--- a/src/clint-address-range.cpp
+++ b/src/clint-address-range.cpp
@@ -18,9 +18,9 @@
 
 #include <cstdint>
 
+#include "address-range-constants.h"
 #include "i-device-state-access.h"
 #include "interpret.h"
-#include "pmas-constants.h"
 #include "riscv-constants.h"
 #include "rtc.h"
 
diff --git a/src/dtb.cpp b/src/dtb.cpp
index 7024fd3ad..e42422642 100644
--- a/src/dtb.cpp
+++ b/src/dtb.cpp
@@ -29,7 +29,6 @@
 #include "machine-c-version.h"
 #include "machine-config.h"
 #include "plic-constants.h"
-#include "pmas-constants.h"
 #include "riscv-constants.h"
 #include "rng-seed.h"
 #include "rtc.h"
diff --git a/src/machine-address-ranges.cpp b/src/machine-address-ranges.cpp
new file mode 100644
index 000000000..43cd29212
--- /dev/null
+++ b/src/machine-address-ranges.cpp
@@ -0,0 +1,409 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+/// \file
+/// \brief Cartesi machine address ranges.
+
+#include "machine-address-ranges.h"
+
+#include <algorithm>
+#include <cerrno>
+#include <concepts>
+#include <cstdint>
+#include <cstdio>
+#include <cstring>
+#include <iterator>
+#include <ranges>
+#include <stdexcept>
+#include <string>
+#include <variant>
+
+#include "address-range-constants.h"
+#include "address-range-description.h"
+#include "address-range.h"
+#include "clint-address-range.h"
+#include "htif-address-range.h"
+#include "machine-config.h"
+#include "memory-address-range.h"
+#include "os.h"
+#include "plic-address-range.h"
+#include "pmas-constants.h"
+#include "pmas.h"
+#include "shadow-state-address-range.h"
+#include "shadow-tlb-address-range.h"
+#include "shadow-uarch-state-address-range.h"
+#include "uarch-pristine.h"
+#include "unique-c-ptr.h"
+#include "virtio-address-range.h"
+#include "virtio-console-address-range.h"
+#include "virtio-net-tuntap-address-range.h"
+#include "virtio-net-user-address-range.h"
+#include "virtio-p9fs-address-range.h"
+
+namespace cartesi {
+
+using namespace std::string_literals;
+
+static const auto throw_invalid_argument = [](const char *err) { throw std::invalid_argument{err}; };
+
+/// \brief Creates a memory address range.
+/// \param d Description of address range for use in error messages.
+/// \param start Target physical address where range starts.
+/// \param length Length of range, in bytes.
+/// \param f Flags for address range.
+/// \param backing_store Backing store configuration for range.
+/// \returns New address range with flags already set.
+/// \details If \p backing_store.data_filename is non-empty and file is large enough to back entire address range,
+/// return a memory-mapped range, otherwise use calloc.
+static inline auto make_memory_address_range(const std::string &d, uint64_t start, uint64_t length, pmas_flags flags,
+    const backing_store_config &backing_store) {
+    if (backing_store.data_filename.empty() && backing_store.shared) {
+        throw std::invalid_argument{"shared address range requires non-empty memory filename when initializing " + d};
+    }
+    if (backing_store.data_filename.empty() ||
+        length > static_cast<uint64_t>(os_get_file_length(backing_store.data_filename.c_str()))) {
+        return make_callocd_memory_address_range(d, start, length, flags, backing_store.data_filename);
+    }
+    return make_mmapd_memory_address_range(d, start, length, flags, backing_store.data_filename, backing_store.shared);
+}
+
+static inline auto make_pmas_address_range(const pmas_config &config) {
+    static constexpr pmas_flags m_pmas_flags{
+        .M = true,
+        .IO = false,
+        .R = true,
+        .W = false,
+        .X = false,
+        .IR = true,
+        .IW = false,
+        .DID = PMA_ISTART_DID::memory,
+    };
+    return make_memory_address_range("PMAs", AR_PMAS_START, AR_PMAS_LENGTH, m_pmas_flags, config.backing_store);
+}
+
+static inline auto make_dtb_address_range(const dtb_config &config) {
+    // When we pass a RNG seed in a FDT stored in DTB, Linux will wipe out its contents as a security measure,
+    // theref, ore we need to make DTB writable, otherwise boot will hang.
+    static constexpr pmas_flags dtb_flags{
+        .M = true,
+        .IO = false,
+        .R = true,
+        .W = true,
+        .X = true,
+        .IR = true,
+        .IW = true,
+        .DID = PMA_ISTART_DID::memory,
+    };
+    return make_memory_address_range("DTB"s, AR_DTB_START, AR_DTB_LENGTH, dtb_flags, config.backing_store);
+}
+
+template <typename AR>
+    requires std::is_rvalue_reference_v<AR &&> && std::derived_from<AR, address_range>
+AR &machine_address_ranges::push_back(AR &&ar, register_where where) {
+    check(ar, where);                                   // Check if we can register it
+    auto ptr = make_moved_unique(std::forward<AR>(ar)); // Move object to heap, now owned by ptr
+    AR &ar_ref = *ptr;                                  // Get reference to object, already in heap, to return later
+    const auto index = m_all.size();                    // Get index the new address range will occupy
+    m_all.push_back(std::move(ptr));                    // Move ptr to list of address ranges
+    if (where.interpret) {                              // Register with interpreter
+        m_interpret.push_back(index);
+    }
+    if (where.merkle) { // Register with Merkle tree
+        m_merkle.push_back(index);
+    }
+    if constexpr (std::is_convertible_v<AR *, virtio_address_range *>) { // Register with VirtIO
+        m_virtio.push_back(&ar_ref);
+    }
+    return ar_ref; // Return reference to object in heap
+}
+
+machine_address_ranges::machine_address_ranges(machine_config &c) {
+    // Add all address ranges to m_all, and potentially to interpret and merkle
+    push_back_uarch_ram(c.uarch.ram);
+    push_back(make_shadow_uarch_state_address_range(throw_invalid_argument),
+        register_where{.merkle = true, .interpret = false});
+    push_back_ram(c.ram);
+    push_back(make_dtb_address_range(c.dtb), register_where{.merkle = true, .interpret = true});
+    push_back_flash_drives(c.flash_drive);
+    push_back_cmio(c.cmio);
+    push_back(make_htif_address_range(throw_invalid_argument), register_where{.merkle = false, .interpret = true});
+    push_back(make_clint_address_range(throw_invalid_argument), register_where{.merkle = false, .interpret = true});
+    push_back(make_plic_address_range(throw_invalid_argument), register_where{.merkle = false, .interpret = true});
+    push_back(make_shadow_tlb_address_range(throw_invalid_argument),
+        register_where{.merkle = true, .interpret = false});
+    push_back(make_shadow_state_address_range(throw_invalid_argument),
+        register_where{.merkle = true, .interpret = false});
+    push_back(make_pmas_address_range(c.pmas), register_where{.merkle = true, .interpret = true});
+    push_back_virtio(c.virtio, c.processor.iunrep);
+
+    // Sort indices visible to Merkle tree by the start of corresponding address range
+    std::ranges::sort(
+        m_merkle, [](const auto &a, const auto &b) { return a.get_start() < b.get_start(); },
+        [this](const auto i) { return *m_all[i]; });
+
+    // Create descriptions and sort by start address
+    auto src =
+        m_all | std::views::filter([](auto &ar) { return !ar->is_empty(); }) | std::views::transform([](auto &ar) {
+            return address_range_description{.start = ar->get_start(),
+                .length = ar->get_length(),
+                .description = ar->get_description()};
+        });
+    std::ranges::copy(src, std::back_inserter(m_descrs));
+    std::ranges::sort(m_descrs, [](auto &a, auto &b) { return a.start < b.start; });
+}
+
+void machine_address_ranges::push_back_uarch_ram(const uarch_ram_config &uram) {
+    // Register RAM
+    if (uarch_pristine_ram_len > AR_UARCH_RAM_LENGTH) {
+        throw std::runtime_error("embedded uarch RAM image does not fit in uarch memory");
+    }
+    static constexpr pmas_flags uram_flags{
+        .M = true,
+        .IO = false,
+        .R = true,
+        .W = true,
+        .X = true,
+        .IR = true,
+        .IW = true,
+        .DID = PMA_ISTART_DID::memory,
+    };
+    constexpr auto ram_description = "uarch RAM";
+    if (uram.backing_store.data_filename.empty()) {
+        auto &ar = push_back(
+            make_callocd_memory_address_range(ram_description, AR_UARCH_RAM_START, AR_UARCH_RAM_LENGTH, uram_flags),
+            register_where{.merkle = true, .interpret = false});
+        memcpy(ar.get_host_memory(), uarch_pristine_ram, uarch_pristine_ram_len);
+    } else {
+        push_back(make_memory_address_range(ram_description, AR_UARCH_RAM_START, AR_UARCH_RAM_LENGTH, uram_flags,
+                      uram.backing_store),
+            register_where{.merkle = true, .interpret = false});
+    }
+}
+
+void machine_address_ranges::check(const address_range &new_ar, register_where where) {
+    if (!where.interpret && !where.merkle) {
+        throw std::runtime_error{"address range "s + new_ar.get_description() + " must be registered somewhere"s};
+    }
+    const auto start = new_ar.get_start();
+    const auto end = new_ar.get_end();
+    // Checks if new range is machine addressable space (safe unsigned overflows)
+    if (start > AR_ADDRESSABLE_MASK || end > AR_ADDRESSABLE_MASK) {
+        throw std::invalid_argument{
+            "address range of "s + new_ar.get_description() + " must use at most 56 bits to be addressable"s};
+    }
+    // Range A overlaps with B if A starts before B ends and A ends after B starts
+    for (const auto &ar : m_all) {
+        if (start < ar->get_end() && end > ar->get_start()) {
+            throw std::invalid_argument{"address range of "s + new_ar.get_description() +
+                " overlaps with address range of existing "s + ar->get_description()};
+        }
+    }
+}
+
+void machine_address_ranges::push_back_ram(const ram_config &ram) {
+    // Flags for RAM
+    static constexpr pmas_flags ram_flags{
+        .M = true,
+        .IO = false,
+        .R = true,
+        .W = true,
+        .X = true,
+        .IR = true,
+        .IW = true,
+        .DID = PMA_ISTART_DID::memory,
+    };
+    if (ram.length == 0) {
+        throw std::invalid_argument("RAM length cannot be zero");
+    }
+    push_back(make_memory_address_range("RAM"s, AR_RAM_START, ram.length, ram_flags, ram.backing_store),
+        register_where{.merkle = true, .interpret = true});
+}
+
+void machine_address_ranges::push_back_flash_drives(flash_drive_configs &flash_drive) {
+    if (flash_drive.size() > FLASH_DRIVE_MAX) {
+        throw std::invalid_argument{"too many flash drives"};
+    }
+    // Flags for flash drives
+    static const pmas_flags flash_flags{
+        .M = true,
+        .IO = false,
+        .R = true,
+        .W = true,
+        .X = false,
+        .IR = true,
+        .IW = true,
+        .DID = PMA_ISTART_DID::flash_drive,
+    };
+    // Register all flash drives
+    int i = 0; // NOLINT(misc-const-correctness)
+    for (auto &f : flash_drive) {
+        const std::string flash_description = "flash drive "s + std::to_string(i);
+        // Auto detect flash drive start address
+        if (f.start == UINT64_C(-1)) {
+            f.start = AR_DRIVE_START + AR_DRIVE_OFFSET * i;
+        }
+        // Auto detect flash drive image length
+        const auto &image_filename = f.backing_store.data_filename;
+        if (f.length == UINT64_C(-1)) {
+            if (image_filename.empty()) {
+                throw std::system_error{errno, std::generic_category(),
+                    "unable to auto-detect length of "s.append(flash_description).append(" with empty image file")};
+            }
+            auto fp = make_unique_fopen(image_filename.c_str(), "rb");
+            if (fseek(fp.get(), 0, SEEK_END) != 0) {
+                throw std::system_error{errno, std::generic_category(),
+                    "unable to obtain length of image file '"s.append(image_filename)
+                        .append("' when initializing ")
+                        .append(flash_description)};
+            }
+            const auto length = ftell(fp.get());
+            if (length < 0) {
+                throw std::system_error{errno, std::generic_category(),
+                    "unable to obtain length of image file '"s.append(image_filename)
+                        .append("' when initializing ")
+                        .append(flash_description)};
+            }
+            f.length = length;
+        }
+        push_back(make_memory_address_range(flash_description, f.start, f.length, flash_flags, f.backing_store),
+            register_where{.merkle = true, .interpret = true});
+        i++;
+    }
+}
+
+void machine_address_ranges::push_back_virtio(const virtio_configs &virtio, uint64_t iunrep) {
+    if (virtio.empty()) {
+        return;
+    }
+    if (virtio.size() > VIRTIO_DEVICE_MAX) {
+        throw std::invalid_argument{"too many VirtIO devices"};
+    }
+    // VirtIO devices are disallowed in unreproducible mode
+    if (iunrep == 0) {
+        throw std::invalid_argument{"virtio devices are only supported in unreproducible machines"};
+    }
+    uint32_t virtio_idx = 0;
+    for (const auto &c : virtio) {
+        const auto where = register_where{.merkle = false, .interpret = true};
+        const auto visitor = overloads{
+            [this, virtio_idx, where](const virtio_console_config &) {
+                const auto start = AR_FIRST_VIRTIO_START + (virtio_idx * AR_VIRTIO_LENGTH);
+                push_back(make_virtio_console_address_range(start, AR_VIRTIO_LENGTH, virtio_idx), where);
+            },
+            [this, virtio_idx, where](const virtio_p9fs_config &c) {
+#ifdef HAVE_POSIX_FS
+                const auto start = AR_FIRST_VIRTIO_START + (virtio_idx * AR_VIRTIO_LENGTH);
+                push_back(make_virtio_p9fs_address_range(start, AR_VIRTIO_LENGTH, virtio_idx, c.tag, c.host_directory),
+                    where);
+#else
+                (void) c;
+                (void) this;
+                (void) virtio_idx;
+                (void) where;
+                throw std::invalid_argument{"virtio 9p device is unsupported in this platform"};
+#endif
+            },
+            [this, virtio_idx, where](const virtio_net_tuntap_config &c) {
+#ifdef HAVE_TUNTAP
+                const auto start = AR_FIRST_VIRTIO_START + (virtio_idx * AR_VIRTIO_LENGTH);
+                push_back(make_virtio_net_tuntap_address_range(start, AR_VIRTIO_LENGTH, virtio_idx, c.iface), where);
+#else
+                (void) c;
+                (void) this;
+                (void) virtio_idx;
+                (void) where;
+                throw std::invalid_argument("virtio network TUN/TAP device is unsupported in this platform");
+#endif
+            },
+            [this, virtio_idx, where](const virtio_net_user_config &c) {
+#ifdef HAVE_SLIRP
+                if (c.hostfwd.size() > VIRTIO_HOSTFWD_MAX) {
+                    throw std::invalid_argument("too many virtio network user host-forwarding ports");
+                }
+                const auto start = AR_FIRST_VIRTIO_START + (virtio_idx * AR_VIRTIO_LENGTH);
+                push_back(make_virtio_net_user_address_range(start, AR_VIRTIO_LENGTH, virtio_idx, c), where);
+#else
+                (void) c;
+                (void) this;
+                (void) virtio_idx;
+                (void) where;
+                throw std::invalid_argument("virtio network user device is unsupported in this platform");
+#endif
+            },
+            [](const auto &) { throw std::invalid_argument("invalid virtio device configuration"); }};
+        std::visit(visitor, c);
+        ++virtio_idx;
+    }
+}
+
+void machine_address_ranges::push_back_cmio(const cmio_config &c) {
+    static const pmas_flags tx_flags{
+        .M = true,
+        .IO = false,
+        .R = true,
+        .W = true,
+        .X = false,
+        .IR = true,
+        .IW = true,
+        .DID = PMA_ISTART_DID::cmio_tx_buffer,
+    };
+    static const pmas_flags rx_flags{
+        .M = true,
+        .IO = false,
+        .R = true,
+        .W = false,
+        .X = false,
+        .IR = true,
+        .IW = true,
+        .DID = PMA_ISTART_DID::cmio_rx_buffer,
+    };
+    push_back(make_memory_address_range("CMIO tx buffer memory range"s, AR_CMIO_TX_BUFFER_START,
+                  AR_CMIO_TX_BUFFER_LENGTH, tx_flags, c.tx_buffer.backing_store),
+        register_where{.merkle = true, .interpret = true});
+    push_back(make_memory_address_range("CMIO rx buffer memory range"s, AR_CMIO_RX_BUFFER_START,
+                  AR_CMIO_RX_BUFFER_LENGTH, rx_flags, c.rx_buffer.backing_store),
+        register_where{.merkle = true, .interpret = true});
+}
+
+void machine_address_ranges::replace(const memory_range_config &config) {
+    for (auto &ar : m_all) {
+        //??D Need to add check for new read-only property here
+        if (ar->get_start() == config.start && ar->get_length() == config.length) {
+            if (!ar->is_memory() || pmas_is_protected(ar->get_driver_id())) {
+                throw std::invalid_argument{
+                    std::string{"attempt to replace a protected range "}.append(ar->get_description())};
+            }
+            // Replace range, preserving original flags.
+            // This will automatically start with all pages dirty.
+            ar = make_moved_unique(make_memory_address_range(ar->get_description(), ar->get_start(), ar->get_length(),
+                ar->get_flags(), config.backing_store));
+            return;
+        }
+    }
+    throw std::invalid_argument{"attempt to replace inexistent memory range"};
+}
+
+const address_range &machine_address_ranges::find(uint64_t paddr, uint64_t length) const noexcept {
+    static constexpr auto sentinel = make_empty_address_range("sentinel");
+    for (const auto &ar : m_all) {
+        if (ar->contains_absolute(paddr, length)) {
+            return *ar;
+        }
+    }
+    return sentinel;
+}
+
+} // namespace cartesi
diff --git a/src/machine-address-ranges.h b/src/machine-address-ranges.h
new file mode 100644
index 000000000..bfba63c89
--- /dev/null
+++ b/src/machine-address-ranges.h
@@ -0,0 +1,190 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef MACHINE_ADDRESS_RANGES_H
+#define MACHINE_ADDRESS_RANGES_H
+
+#include <cstdint>
+#include <memory>
+#include <ranges>
+#include <utility>
+#include <vector>
+
+/// \file
+/// \brief Cartesi machine address ranges.
+
+#include "address-range-description.h"
+#include "address-range.h"
+#include "machine-config.h"
+#include "machine-runtime-config.h"
+#include "meta.h"
+#include "virtio-address-range.h"
+
+namespace cartesi {
+
+/// \brief Machine address ranges.
+/// \details Class holding all address ranges in the machine
+class machine_address_ranges {
+    std::vector<std::unique_ptr<address_range>> m_all; ///< Owner of all address ranges
+    std::vector<uint64_t> m_merkle;                    ///< Indices of address ranges registered with Merkle tree
+    std::vector<uint64_t> m_interpret;                 ///< Indices of address ranges registered with interpret (PMAs)
+    std::vector<virtio_address_range *> m_virtio;      ///< Pointers to all VirtIO address ranges
+    address_range_descriptions m_descrs;               ///< Address range descriptions for users
+
+public:
+    /// \brief Constructor
+    /// \param c Machine configuration
+    explicit machine_address_ranges(machine_config &c);
+
+    /// \brief Const view of all address ranges
+    auto all() const {
+        return std::views::transform(m_all, [](const auto &p) -> const address_range & { return *p; });
+    }
+
+    /// \brief Const view of address ranges registered with Merkle tree
+    auto merkle() const {
+        return std::views::transform(m_merkle, [this](auto i) -> const address_range & { return *m_all[i]; });
+    }
+
+    /// \brief View of address ranges registered with Merkle tree
+    auto merkle() {
+        return std::views::transform(m_merkle, [this](auto i) -> address_range & { return *m_all[i]; });
+    }
+
+    /// \brief View of address ranges registered with interpret (PMAs)
+    auto interpret() const {
+        return std::views::transform(m_interpret, [this](auto i) -> address_range & { return *m_all[i]; });
+    }
+
+    /// \brief View of all VirtIO address ranges
+    auto virtio() {
+        return std::views::transform(m_virtio, [](auto *p) -> virtio_address_range & { return *p; });
+    }
+
+    /// \brief Returns the ith address range registed with interpret
+    const address_range &read_pma(uint64_t index) const noexcept {
+        if (index >= m_interpret.size()) {
+            static constexpr auto sentinel = make_empty_address_range("sentinel");
+            return sentinel;
+        }
+        // NOLINTNEXTLINE(bugprone-narrowing-conversions)
+        return *m_all[static_cast<int>(m_interpret[static_cast<int>(index)])];
+    }
+
+    /// \brief Returns const address range that covers a given physical memory region
+    /// \param paddr Target physical address of start of region.
+    /// \param length Length of region, in bytes.
+    /// \returns Corresponding address range if found, or an empty sentinel otherwise.
+    const address_range &find(uint64_t paddr, uint64_t length) const noexcept;
+
+    /// \brief Returns address range that covers a given physical memory region
+    /// \param paddr Target physical address of start of region.
+    /// \param length Length of region, in bytes.
+    /// \returns Corresponding address range if found, or an empty sentinel otherwise.
+    address_range &find(uint64_t paddr, uint64_t length) noexcept {
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-const-cast)
+        return const_cast<address_range &>(std::as_const(*this).find(paddr, length));
+    }
+
+    /// \brief Returns a const address range that covers a given word in physical memory
+    /// \tparam T Type of word.
+    /// \param paddr Target physical address of start of region.
+    /// \returns Corresponding address range if found, or an empty sentinel otherwise.
+    template <typename T>
+    const address_range &find(uint64_t paddr) const {
+        return find(paddr, sizeof(T));
+    }
+
+    /// \brief Returns a const address range that covers a given word in physical memory
+    /// \tparam T Type of word.
+    /// \param paddr Target physical address of start of region.
+    /// \returns Corresponding address range if found, or an empty sentinel otherwise.
+    template <typename T>
+    address_range &find(uint64_t paddr) {
+        return find(paddr, sizeof(T));
+    }
+
+    /// \brief Replaces a memory address range.
+    /// \param config Configuration of the new memory address range.
+    /// \details A memory address range matching the start and length specified in the config must exist.
+    void replace(const memory_range_config &config);
+
+    /// \brief Returns descriptions of all address ranges.
+    const address_range_descriptions &descriptions() const {
+        return m_descrs;
+    }
+
+private:
+    ///< Where to register an address range
+    struct register_where {
+        bool merkle;    //< Register with Merkle tree, so it appears in the root hash
+        bool interpret; //< Register so interpret can see (and it also appears as a PMA entries in memory)
+    };
+
+    /// \brief Checks if address range can be registered.
+    /// \param ar Address range object to register.
+    /// \param where Where to register the address range.
+    void check(const address_range &ar, register_where where);
+
+    /// \brief Registers a new address range.
+    /// \tparam AR An address range or derived type.
+    /// \param ar The address range object to register (as an r-value).
+    /// \param where Where to register the address range.
+    /// \returns Reference to address range object after it is moved inside the machine.
+    /// \details The r-value address range is moved to the heap, and a smart pointer holding it is added to a container.
+    /// Once the address range is moved to the heap, its address will remain valid until it is replaced by
+    /// a call to replace(), or until this object is destroyed.
+    /// This means pointers to address ranges remain valid even after subsequent calls to push_back(),
+    /// but may be invalidated by calls to replace().
+    /// For a stronger guarantee, when an address range is replaced, the smart pointer holding the new address range
+    /// overwrites the smart pointer holding the old address range at the same index in the container.
+    /// This means the index into the container that owns all address ranges will always refer to same address range
+    /// after subsequent calls to register() and  calls to replace() as well.
+    /// \details Besides the container that stores the address ranges, the machine maintains three subsets.
+    /// The "merkle" subset lists the indices of the address ranges taht will be considered by the Merkle
+    /// tree during the computation of the state hash.
+    /// The "interpret" subset lists the indices of the address ranges visible from within the interpreter (PMAs).
+    /// When registering an address range with the machine, one must specify \p where to register it.
+    /// The "virtio" subset lists every VirtIO address range that has been registered.
+    template <typename AR>
+        requires std::is_rvalue_reference_v<AR &&> && std::derived_from<AR, address_range>
+    AR &push_back(AR &&ar, register_where where);
+
+    /// \param c uarch RAM configuration
+    void push_back_uarch_ram(const uarch_ram_config &uram);
+
+    /// \brief Adds RAM address range
+    /// \param ram RAM configuration
+    void push_back_ram(const ram_config &ram);
+
+    /// \brief Adds flash drive address ranges
+    /// \param flash_drive Flash drive configurations
+    /// \detail This modifies the flash drive configuration with automatic start/length from backing storage, if needed
+    void push_back_flash_drives(flash_drive_configs &flash_drive);
+
+    /// \brief Adds virtio address ranges
+    /// \param virtio VirtIO configurations
+    /// \param iunrep Initial value of iunrep CSR
+    void push_back_virtio(const virtio_configs &virtio, uint64_t iunrep);
+
+    /// \brief Adds CMIO address ranges
+    /// \param c CMIO configuration
+    void push_back_cmio(const cmio_config &c);
+};
+
+} // namespace cartesi
+
+#endif
diff --git a/src/machine-c-api.cpp b/src/machine-c-api.cpp
index 1ba455cb1..2b32586c4 100644
--- a/src/machine-c-api.cpp
+++ b/src/machine-c-api.cpp
@@ -32,6 +32,7 @@
 #include <variant>
 
 #include "access-log.h"
+#include "address-range-defines.h"
 #include "address-range-description.h"
 #include "htif-constants.h"
 #include "i-machine.h"
@@ -45,7 +46,6 @@
 #include "machine-runtime-config.h"
 #include "machine.h"
 #include "os-features.h"
-#include "pmas-defines.h"
 
 static std::string &get_last_err_msg_storage() {
     static THREAD_LOCAL std::string last_err_msg;
diff --git a/src/machine-config.cpp b/src/machine-config.cpp
index ea11b6f98..12c007438 100644
--- a/src/machine-config.cpp
+++ b/src/machine-config.cpp
@@ -21,6 +21,7 @@
 #include <exception>
 #include <fstream>
 #include <iomanip>
+#include <ios>
 #include <sstream>
 #include <stdexcept>
 #include <string>
@@ -28,8 +29,8 @@
 
 #include <json.hpp>
 
+#include "address-range-constants.h"
 #include "json-util.h"
-#include "pmas-constants.h"
 
 static constexpr uint32_t archive_version = 5;
 
diff --git a/src/machine-state.h b/src/machine-state.h
index 8fcfa1c6e..707e96988 100644
--- a/src/machine-state.h
+++ b/src/machine-state.h
@@ -113,8 +113,6 @@ struct machine_state {
 
     /// Soft yield
     bool soft_yield{};
-
-    std::vector<uint64_t> pmas; ///< Indices of address ranges that interpret can find
 };
 
 } // namespace cartesi
diff --git a/src/machine.cpp b/src/machine.cpp
index 2f4eef447..bb2900593 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -31,20 +31,15 @@
 #include <stdexcept>
 #include <string>
 #include <system_error>
-#include <type_traits>
 #include <utility>
-#include <variant>
-#include <vector>
 
 #include "access-log.h"
-#include "address-range-description.h"
+#include "address-range-constants.h"
 #include "address-range.h"
-#include "clint-address-range.h"
 #include "compiler-defines.h"
 #include "device-state-access.h"
 #include "dtb.h"
 #include "host-addr.h"
-#include "htif-address-range.h"
 #include "htif-constants.h"
 #include "i-device-state-access.h"
 #include "i-hasher.h"
@@ -53,8 +48,8 @@
 #include "machine-config.h"
 #include "machine-reg.h"
 #include "machine-runtime-config.h"
-#include "memory-address-range.h"
-#include "plic-address-range.h"
+#include "os.h"
+#include "pmas-constants.h"
 #include "pmas.h"
 #include "record-send-cmio-state-access.h"
 #include "record-step-state-access.h"
@@ -63,9 +58,7 @@
 #include "riscv-constants.h"
 #include "rtc.h"
 #include "send-cmio-response.h"
-#include "shadow-state-address-range.h"
-#include "shadow-tlb-address-range.h"
-#include "shadow-uarch-state-address-range.h"
+#include "shadow-tlb.h"
 #include "state-access.h"
 #include "strict-aliasing.h"
 #include "tlb.h"
@@ -73,17 +66,13 @@
 #include "uarch-constants.h"
 #include "uarch-interpret.h"
 #include "uarch-pristine-state-hash.h"
-#include "uarch-pristine.h"
 #include "uarch-record-state-access.h"
 #include "uarch-replay-state-access.h"
 #include "uarch-reset-state.h"
 #include "uarch-state-access.h"
 #include "uarch-step.h"
 #include "unique-c-ptr.h"
-#include "virtio-console-address-range.h"
-#include "virtio-net-tuntap-address-range.h"
-#include "virtio-net-user-address-range.h"
-#include "virtio-p9fs-address-range.h"
+#include "virtio-address-range.h"
 
 /// \file
 /// \brief Cartesi machine implementation
@@ -92,79 +81,7 @@ namespace cartesi {
 
 using namespace std::string_literals;
 
-static const auto throw_invalid_argument = [](const char *err) { throw std::invalid_argument{err}; };
-
-/// \brief Creates a memory address range.
-/// \param d Description of address range for use in error messages.
-/// \param start Target physical address where range starts.
-/// \param length Length of range, in bytes.
-/// \param f Flags for address range.
-/// \param backing_store Backing store configuration for range.
-/// \returns New address range with flags already set.
-/// \details If \p backing_store.data_filename is non-empty and file is large enough to back entire address range,
-/// return a memory-mapped range, otherwise use calloc.
-static inline auto make_memory_address_range(const std::string &d, uint64_t start, uint64_t length, pmas_flags flags,
-    const backing_store_config &backing_store) {
-    if (backing_store.data_filename.empty() && backing_store.shared) {
-        throw std::invalid_argument{"shared address range requires non-empty memory filename when initializing " + d};
-    }
-    if (backing_store.data_filename.empty() ||
-        length > static_cast<uint64_t>(os_get_file_length(backing_store.data_filename.c_str()))) {
-        return make_callocd_memory_address_range(d, start, length, flags, backing_store.data_filename);
-    }
-    return make_mmapd_memory_address_range(d, start, length, flags, backing_store.data_filename, backing_store.shared);
-}
-
-void machine::check_address_range(const address_range &new_ar, register_where where) {
-    if (!where.interpret && !where.merkle) {
-        throw std::runtime_error{"address range "s + new_ar.get_description() + " must be registered somewhere"s};
-    }
-    const auto start = new_ar.get_start();
-    const auto end = new_ar.get_end();
-    // Checks if new range is machine addressable space (safe unsigned overflows)
-    if (start > AR_ADDRESSABLE_MASK || end > AR_ADDRESSABLE_MASK) {
-        throw std::invalid_argument{
-            "address range of "s + new_ar.get_description() + " must use at most 56 bits to be addressable"s};
-    }
-    // Range A overlaps with B if A starts before B ends and A ends after B starts
-    for (const auto &ar : m_ars) {
-        if (start < ar->get_end() && end > ar->get_start()) {
-            throw std::invalid_argument{"address range of "s + new_ar.get_description() +
-                " overlaps with address range of existing "s + ar->get_description()};
-        }
-    }
-}
-
-static bool is_protected(PMA_ISTART_DID DID) {
-    switch (DID) {
-        case PMA_ISTART_DID::memory:
-        case PMA_ISTART_DID::flash_drive:
-        case PMA_ISTART_DID::cmio_rx_buffer:
-        case PMA_ISTART_DID::cmio_tx_buffer:
-            return false;
-        default:
-            return true;
-    }
-}
-
-void machine::replace_memory_range(const memory_range_config &config) {
-    for (auto &ar : m_ars) {
-        //??D Need to add check for new read-only property here
-        if (ar->get_start() == config.start && ar->get_length() == config.length) {
-            if (!ar->is_memory() || is_protected(ar->get_driver_id())) {
-                throw std::invalid_argument{"attempt to replace a protected range "s + ar->get_description()};
-            }
-            // Replace range, preserving original flags.
-            // This will automatically start with all pages dirty.
-            ar = make_moved_unique(make_memory_address_range(ar->get_description(), ar->get_start(), ar->get_length(),
-                ar->get_flags(), config.backing_store));
-            return;
-        }
-    }
-    throw std::invalid_argument{"attempt to replace inexistent memory range"};
-}
-
-void machine::init_uarch(const uarch_config &c) {
+void machine::init_uarch_processor(const uarch_config &c) {
     using reg = machine_reg;
     write_reg(reg::uarch_pc, c.processor.pc);
     write_reg(reg::uarch_cycle, c.processor.cycle);
@@ -173,35 +90,6 @@ void machine::init_uarch(const uarch_config &c) {
     for (int i = 1; i < UARCH_X_REG_COUNT; i++) {
         write_reg(machine_reg_enum(reg::uarch_x0, i), c.processor.x[i]);
     }
-    // Register shadow state
-    m_us.shadow_state = &register_address_range(make_shadow_uarch_state_address_range(AR_SHADOW_UARCH_STATE_START,
-                                                    AR_SHADOW_UARCH_STATE_LENGTH, throw_invalid_argument),
-        register_where{.merkle = true, .interpret = false});
-    // Register RAM
-    if (uarch_pristine_ram_len > AR_UARCH_RAM_LENGTH) {
-        throw std::runtime_error("embedded uarch RAM image does not fit in uarch memory");
-    }
-    static constexpr pmas_flags uram_flags{
-        .M = true,
-        .IO = false,
-        .R = true,
-        .W = true,
-        .X = true,
-        .IR = true,
-        .IW = true,
-        .DID = PMA_ISTART_DID::memory,
-    };
-    constexpr auto ram_description = "uarch RAM";
-    if (c.ram.backing_store.data_filename.empty()) {
-        m_us.ram = &register_address_range(
-            make_callocd_memory_address_range(ram_description, AR_UARCH_RAM_START, UARCH_RAM_LENGTH, uram_flags),
-            register_where{.merkle = true, .interpret = false});
-        memcpy(m_us.ram->get_host_memory(), uarch_pristine_ram, uarch_pristine_ram_len);
-    } else {
-        m_us.ram = &register_address_range(make_memory_address_range(ram_description, AR_UARCH_RAM_START,
-                                               UARCH_RAM_LENGTH, uram_flags, c.ram.backing_store),
-            register_where{.merkle = true, .interpret = false});
-    }
 }
 
 void machine::init_processor(processor_config &p, const machine_runtime_config &r) {
@@ -274,151 +162,7 @@ void machine::init_processor(processor_config &p, const machine_runtime_config &
     write_reg(reg::iunrep, p.iunrep);
 }
 
-void machine::init_ram_ar(const ram_config &ram) {
-    // Flags for RAM
-    static constexpr pmas_flags ram_flags{
-        .M = true,
-        .IO = false,
-        .R = true,
-        .W = true,
-        .X = true,
-        .IR = true,
-        .IW = true,
-        .DID = PMA_ISTART_DID::memory,
-    };
-    if (ram.length == 0) {
-        throw std::invalid_argument("RAM length cannot be zero");
-    }
-    register_address_range(make_memory_address_range("RAM"s, AR_RAM_START, ram.length, ram_flags, ram.backing_store),
-        register_where{.merkle = true, .interpret = true});
-}
-
-void machine::init_flash_drive_ars(flash_drive_configs &flash_drive) {
-    if (flash_drive.size() > FLASH_DRIVE_MAX) {
-        throw std::invalid_argument{"too many flash drives"};
-    }
-    // Flags for flash drives
-    static const pmas_flags flash_flags{
-        .M = true,
-        .IO = false,
-        .R = true,
-        .W = true,
-        .X = false,
-        .IR = true,
-        .IW = true,
-        .DID = PMA_ISTART_DID::flash_drive,
-    };
-    // Register all flash drives
-    int i = 0; // NOLINT(misc-const-correctness)
-    for (auto &f : flash_drive) {
-        const std::string flash_description = "flash drive "s + std::to_string(i);
-        // Auto detect flash drive start address
-        if (f.start == UINT64_C(-1)) {
-            f.start = AR_DRIVE_START + AR_DRIVE_OFFSET * i;
-        }
-        // Auto detect flash drive image length
-        const auto &image_filename = f.backing_store.data_filename;
-        if (f.length == UINT64_C(-1)) {
-            if (image_filename.empty()) {
-                throw std::system_error{errno, std::generic_category(),
-                    "unable to auto-detect length of "s.append(flash_description).append(" with empty image file")};
-            }
-            auto fp = make_unique_fopen(image_filename.c_str(), "rb");
-            if (fseek(fp.get(), 0, SEEK_END) != 0) {
-                throw std::system_error{errno, std::generic_category(),
-                    "unable to obtain length of image file '"s.append(image_filename)
-                        .append("' when initializing ")
-                        .append(flash_description)};
-            }
-            const auto length = ftell(fp.get());
-            if (length < 0) {
-                throw std::system_error{errno, std::generic_category(),
-                    "unable to obtain length of image file '"s.append(image_filename)
-                        .append("' when initializing ")
-                        .append(flash_description)};
-            }
-            f.length = length;
-        }
-        register_address_range(
-            make_memory_address_range(flash_description, f.start, f.length, flash_flags, f.backing_store),
-            register_where{.merkle = true, .interpret = true});
-        i++;
-    }
-}
-
-void machine::init_virtio_ars(const virtio_configs &virtio, uint64_t iunrep) {
-    // Initialize VirtIO devices
-    if (virtio.empty()) {
-        return;
-    }
-    if (virtio.size() > VIRTIO_DEVICE_MAX) {
-        throw std::invalid_argument{"too many VirtIO devices"};
-    }
-    // VirtIO devices are disallowed in unreproducible mode
-    if (iunrep == 0) {
-        throw std::invalid_argument{"virtio devices are only supported in unreproducible machines"};
-    }
-    uint32_t virtio_idx = 0;
-    for (const auto &c : virtio) {
-        const auto where = register_where{.merkle = false, .interpret = true};
-        const auto visitor = overloads{
-            [this, virtio_idx, where](const virtio_console_config &) {
-                const auto start = AR_FIRST_VIRTIO_START + (virtio_idx * AR_VIRTIO_LENGTH);
-                register_address_range(make_virtio_console_address_range(start, AR_VIRTIO_LENGTH, virtio_idx), where);
-            },
-            [this, virtio_idx, where](const virtio_p9fs_config &c) {
-#ifdef HAVE_POSIX_FS
-                const auto start = AR_FIRST_VIRTIO_START + (virtio_idx * AR_VIRTIO_LENGTH);
-                register_address_range(
-                    make_virtio_p9fs_address_range(start, AR_VIRTIO_LENGTH, virtio_idx, c.tag, c.host_directory),
-                    where);
-#else
-                (void) c;
-                (void) this;
-                (void) virtio_idx;
-                (void) where;
-                throw std::invalid_argument{"virtio 9p device is unsupported in this platform"};
-#endif
-            },
-            [this, virtio_idx, where](const virtio_net_tuntap_config &c) {
-#ifdef HAVE_TUNTAP
-                const auto start = AR_FIRST_VIRTIO_START + (virtio_idx * AR_VIRTIO_LENGTH);
-                register_address_range(
-                    make_virtio_net_tuntap_address_range(start, AR_VIRTIO_LENGTH, virtio_idx, c.iface), where);
-#else
-                (void) c;
-                (void) this;
-                (void) virtio_idx;
-                (void) where;
-                throw std::invalid_argument("virtio network TUN/TAP device is unsupported in this platform");
-#endif
-            },
-            [this, virtio_idx, where](const virtio_net_user_config &c) {
-#ifdef HAVE_SLIRP
-                if (c.hostfwd.size() > VIRTIO_HOSTFWD_MAX) {
-                    throw std::invalid_argument("too many virtio network user host-forwarding ports");
-                }
-                const auto start = AR_FIRST_VIRTIO_START + (virtio_idx * AR_VIRTIO_LENGTH);
-                register_address_range(make_virtio_net_user_address_range(start, AR_VIRTIO_LENGTH, virtio_idx, c),
-                    where);
-#else
-                (void) c;
-                (void) this;
-                (void) virtio_idx;
-                (void) where;
-                throw std::invalid_argument("virtio network user device is unsupported in this platform");
-#endif
-            },
-            [](const auto &) { throw std::invalid_argument("invalid virtio device configuration"); }};
-        std::visit(visitor, c);
-        ++virtio_idx;
-    }
-}
-
-void machine::init_htif_ar(const htif_config &h) {
-    // Register HTIF device
-    register_address_range(make_htif_address_range(throw_invalid_argument),
-        register_where{.merkle = false, .interpret = true});
+void machine::init_htif_registers(const htif_config &h) {
     // Copy HTIF state to from config to machine
     write_reg(reg::htif_tohost, h.tohost);
     write_reg(reg::htif_fromhost, h.fromhost);
@@ -433,83 +177,27 @@ void machine::init_htif_ar(const htif_config &h) {
     write_reg(reg::htif_iyield, htif_iyield);
 }
 
-void machine::init_cmio_ars(const cmio_config &c) {
-    static const pmas_flags tx_flags{
-        .M = true,
-        .IO = false,
-        .R = true,
-        .W = true,
-        .X = false,
-        .IR = true,
-        .IW = true,
-        .DID = PMA_ISTART_DID::cmio_tx_buffer,
-    };
-    static const pmas_flags rx_flags{
-        .M = true,
-        .IO = false,
-        .R = true,
-        .W = false,
-        .X = false,
-        .IR = true,
-        .IW = true,
-        .DID = PMA_ISTART_DID::cmio_rx_buffer,
-    };
-    register_address_range(make_memory_address_range("CMIO tx buffer memory range"s, AR_CMIO_TX_BUFFER_START,
-                               AR_CMIO_TX_BUFFER_LENGTH, tx_flags, c.tx_buffer.backing_store),
-        register_where{.merkle = true, .interpret = true});
-    register_address_range(make_memory_address_range("CMIO rx buffer memory range"s, AR_CMIO_RX_BUFFER_START,
-                               AR_CMIO_RX_BUFFER_LENGTH, rx_flags, c.rx_buffer.backing_store),
-        register_where{.merkle = true, .interpret = true});
-}
-
-void machine::init_merkle_ars() {
-    // Sort indices by the starting address of the range they point to in the m_ars array
-    std::ranges::sort(
-        m_merkle_ars, [](const auto &a, const auto &b) { return a.get_start() < b.get_start(); },
-        [this](const auto i) { return *m_ars[i]; });
-}
-
-void machine::init_ars_descriptions() {
-    // Initialize memory range descriptions returned by get_address_ranges method
-    auto src =
-        m_ars | std::views::filter([](auto &ar) { return !ar->is_empty(); }) | std::views::transform([](auto &ar) {
-            return address_range_description{.start = ar->get_start(),
-                .length = ar->get_length(),
-                .description = ar->get_description()};
-        });
-    std::ranges::copy(src, std::back_inserter(m_ards));
-    std::ranges::sort(m_ards, [](auto &a, auto &b) { return a.start < b.start; });
-}
-
-void machine::init_clint_ar(const clint_config &c) {
-    // Register CLINT device
-    register_address_range(make_clint_address_range(throw_invalid_argument),
-        register_where{.merkle = false, .interpret = true});
-    // Copy CLINT state to from config to machine
+void machine::init_clint_registers(const clint_config &c) {
     write_reg(reg::clint_mtimecmp, c.mtimecmp);
 }
 
-void machine::init_plic_ar(const plic_config &p) {
-    // Register PLIC device
-    register_address_range(make_plic_address_range(throw_invalid_argument),
-        register_where{.merkle = false, .interpret = true});
-    // Copy PLIC state from config to machine
+void machine::init_plic_registers(const plic_config &p) {
     write_reg(reg::plic_girqpend, p.girqpend);
     write_reg(reg::plic_girqsrvd, p.girqsrvd);
 }
 
-void machine::init_pmas_contents(const pmas_config &config, memory_address_range &pmas) const {
+void machine::init_pmas_contents(const pmas_config &config) {
     static_assert(sizeof(pmas_state) == PMA_MAX * 2 * sizeof(uint64_t), "inconsistent PMAs state length");
     static_assert(AR_PMAS_LENGTH >= sizeof(pmas_state), "PMAs address range too short");
     if (config.backing_store.data_filename.empty()) {
-        if (m_s.pmas.size() >= PMA_MAX - 1) { // Leave room for a sentinel empty address range after all others
-            throw std::runtime_error{"too many address ranges"};
+        auto &pmas = m_ars.find(AR_PMAS_START, AR_PMAS_LENGTH);
+        if (!pmas.is_memory()) {
+            throw std::runtime_error{"initialization error: PMAs memory address range not found"};
         }
         // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
         auto &dest = *reinterpret_cast<pmas_state *>(pmas.get_host_memory());
-        std::ranges::transform(m_s.pmas, dest.begin(), [this](auto i) {
-            return pmas_entry{.istart = m_ars[i]->get_istart(), .ilength = m_ars[i]->get_ilength()};
-        });
+        std::ranges::transform(m_ars.interpret(), dest.begin(),
+            [](const auto &ar) { return pmas_entry{.istart = ar.get_istart(), .ilength = ar.get_ilength()}; });
     }
 }
 
@@ -535,77 +223,28 @@ void machine::init_tlb_contents(const tlb_config &config) {
     }
 }
 
-static inline auto make_dtb_address_range(const dtb_config &config) {
-    // When we pass a RNG seed in a FDT stored in DTB, Linux will wipe out its contents as a security measure,
-    // theref, ore we need to make DTB writable, otherwise boot will hang.
-    static constexpr pmas_flags dtb_flags{
-        .M = true,
-        .IO = false,
-        .R = true,
-        .W = true,
-        .X = true,
-        .IR = true,
-        .IW = true,
-        .DID = PMA_ISTART_DID::memory,
-    };
-    return make_memory_address_range("DTB"s, AR_DTB_START, AR_DTB_LENGTH, dtb_flags, config.backing_store);
-}
-
-void machine::init_dtb_contents(const machine_config &config, memory_address_range &dtb) {
+void machine::init_dtb_contents(const machine_config &config) {
     if (config.dtb.backing_store.data_filename.empty()) {
+        auto &dtb = m_ars.find(AR_DTB_START, AR_DTB_LENGTH);
+        if (!dtb.is_memory()) {
+            throw std::runtime_error{"initialization error: DTB memory address range not found"};
+        }
         dtb_init(config, dtb.get_host_memory(), dtb.get_length());
     }
 }
 
-static inline auto make_pmas_address_range(const pmas_config &config) {
-    static constexpr pmas_flags m_pmas_flags{
-        .M = true,
-        .IO = false,
-        .R = true,
-        .W = false,
-        .X = false,
-        .IR = true,
-        .IW = false,
-        .DID = PMA_ISTART_DID::memory,
-    };
-    return make_memory_address_range("PMAs", AR_PMAS_START, AR_PMAS_LENGTH, m_pmas_flags, config.backing_store);
-}
-
 // ??D It is best to leave the std::move() on r because it may one day be necessary!
 // NOLINTNEXTLINE(hicpp-move-const-arg,performance-move-const-arg)
-machine::machine(machine_config c, machine_runtime_config r) : m_c{std::move(c)}, m_r{std::move(r)} {
-    init_uarch(m_c.uarch);
+machine::machine(machine_config c, machine_runtime_config r) : m_c{std::move(c)}, m_r{std::move(r)}, m_ars{m_c} {
+    init_uarch_processor(m_c.uarch);
     init_processor(m_c.processor, m_r);
+    init_htif_registers(m_c.htif);
+    init_clint_registers(m_c.clint);
+    init_plic_registers(m_c.plic);
     m_s.soft_yield = m_r.soft_yield;
-    init_ram_ar(m_c.ram);
-    // Will populate when initialization of PMAs is done
-    auto &dtb =
-        register_address_range(make_dtb_address_range(m_c.dtb), register_where{.merkle = true, .interpret = true});
-    init_flash_drive_ars(m_c.flash_drive);
-    init_cmio_ars(m_c.cmio);
-    init_htif_ar(m_c.htif);
-    init_clint_ar(m_c.clint);
-    init_plic_ar(m_c.plic);
-    // Will populate when initialization of PMAs is done
-    register_address_range(make_shadow_tlb_address_range(throw_invalid_argument),
-        register_where{.merkle = true, .interpret = false});
-    register_address_range(make_shadow_state_address_range(throw_invalid_argument),
-        register_where{.merkle = true, .interpret = false});
-    // Will populate when initialization of PMAs is done
-    auto &pmas =
-        register_address_range(make_pmas_address_range(m_c.pmas), register_where{.merkle = true, .interpret = true});
-    init_virtio_ars(m_c.virtio, m_c.processor.iunrep);
-    // Populate PMAs contents.
-    // This must be done after all PMA entries are already registered, so we encode them into the shadow
-    init_pmas_contents(m_c.pmas, pmas);
-    // Initialize TLB contents.
-    // This must be done after all PMA entries are already registered, so we can lookup page addresses
+    init_pmas_contents(m_c.pmas);
     init_tlb_contents(m_c.tlb);
-    // Initialize DTB contents.
-    // This must be done after all PMA entries are already registered, so we can lookup flash drive parameters
-    init_dtb_contents(m_c, dtb);
-    init_merkle_ars();
-    init_ars_descriptions();
+    init_dtb_contents(m_c);
     init_tty(m_c.htif, m_r.htif, m_c.processor.iunrep);
     // Disable SIGPIPE handler, because this signal can be raised and terminate the emulator process
     // when calling write() on closed file descriptors.
@@ -651,16 +290,16 @@ machine::machine(const std::string &dir, machine_runtime_config r) : machine{mac
 }
 
 void machine::prepare_virtio_devices_select(select_fd_sets *fds, uint64_t *timeout_us) {
-    for (auto *v : m_virtio_ars) {
-        v->prepare_select(fds, timeout_us);
+    for (auto &v : m_ars.virtio()) {
+        v.prepare_select(fds, timeout_us);
     }
 }
 
 // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
 bool machine::poll_selected_virtio_devices(int select_ret, select_fd_sets *fds, i_device_state_access *da) {
     bool interrupt_requested = false; // NOLINT(misc-const-correctness)
-    for (auto *v : m_virtio_ars) {
-        interrupt_requested |= v->poll_selected(select_ret, fds, da);
+    for (auto &v : m_ars.virtio()) {
+        interrupt_requested |= v.poll_selected(select_ret, fds, da);
     }
     return interrupt_requested;
 }
@@ -674,13 +313,13 @@ bool machine::poll_virtio_devices(uint64_t *timeout_us, i_device_state_access *d
 }
 
 bool machine::has_virtio_devices() const {
-    return !m_virtio_ars.empty();
+    return !m_ars.virtio().empty();
 }
 
 bool machine::has_virtio_console() const {
     // When present, the console device is guaranteed to be the first VirtIO device,
     // therefore we only need to check the first device.
-    return has_virtio_devices() && m_virtio_ars[0]->get_device_id() == VIRTIO_DEVICE_CONSOLE;
+    return has_virtio_devices() && m_ars.virtio().front().get_device_id() == VIRTIO_DEVICE_CONSOLE;
 }
 
 bool machine::has_htif_console() const {
@@ -845,10 +484,10 @@ void machine::check_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, uin
         throw std::domain_error{prefix + "TLB slot index is out of range"s};
     }
     if (vaddr_page != TLB_INVALID_PAGE) {
-        if (pma_index >= m_s.pmas.size()) {
+        const auto &ar = read_pma(pma_index);
+        if (ar.is_empty()) {
             throw std::domain_error{prefix + "pma_index is out of range"s};
         }
-        const auto &ar = read_pma(pma_index);
         if (!ar.is_memory()) {
             throw std::invalid_argument{prefix + "pma_index does not point to memory range"s};
         }
@@ -895,18 +534,32 @@ host_addr machine::get_hp_offset(uint64_t pma_index) const {
     return paddr - haddr;
 }
 
-const address_range &machine::find_address_range(uint64_t paddr, uint64_t length) const noexcept {
-    static constexpr auto sentinel = make_empty_address_range("sentinel");
-    for (const auto &ar : m_ars) {
-        if (ar->contains_absolute(paddr, length)) {
-            return *ar;
-        }
+static void store_hash(const machine::hash_type &h, const std::string &dir) {
+    auto name = dir + "/hash";
+    auto fp = make_unique_fopen(name.c_str(), "wb");
+    if (fwrite(h.data(), 1, h.size(), fp.get()) != h.size()) {
+        throw std::runtime_error{"error writing to '" + name + "'"};
     }
-    return sentinel;
 }
 
-void machine::store_address_range(const address_range &ar, const std::string &directory) const {
-    auto name = machine_config::get_data_filename(directory, ar.get_start(), ar.get_length());
+void machine::store_address_ranges(const machine_config &c, const std::string &dir) const {
+    store_address_range(m_ars.find<uint64_t>(AR_DTB_START), dir);
+    store_address_range(m_ars.find<uint64_t>(AR_RAM_START), dir);
+    store_address_range(m_ars.find<uint64_t>(AR_SHADOW_TLB_START), dir);
+    for (const auto &f : c.flash_drive) {
+        store_address_range(m_ars.find<uint64_t>(f.start), dir);
+    }
+    store_address_range(m_ars.find<uint64_t>(AR_CMIO_RX_BUFFER_START), dir);
+    store_address_range(m_ars.find<uint64_t>(AR_CMIO_TX_BUFFER_START), dir);
+    store_address_range(m_ars.find<uint64_t>(AR_UARCH_RAM_START), dir);
+    store_address_range(m_ars.find<uint64_t>(AR_PMAS_START), dir);
+}
+
+void machine::store_address_range(const address_range &ar, const std::string &dir) const {
+    if (ar.is_empty()) {
+        throw std::runtime_error{"attempt to store empty address range "s.append(ar.get_description())};
+    }
+    auto name = machine_config::get_data_filename(dir, ar.get_start(), ar.get_length());
     auto fp = make_unique_fopen(name.c_str(), "wb"); // will throw if it fails
     // If we have do not have a pointer to the address range memory, use peek
     // At the moment, this is the case only for the shadow TLB.
@@ -933,32 +586,10 @@ void machine::store_address_range(const address_range &ar, const std::string &di
     }
 }
 
-void machine::store_address_ranges(const machine_config &c, const std::string &directory) const {
+void machine::store(const std::string &dir) const {
     if (read_reg(reg::iunrep) != 0) {
-        throw std::runtime_error{"cannot store address ranges of unreproducible machines"};
-    }
-    store_address_range(find_address_range<uint64_t>(AR_DTB_START), directory);
-    store_address_range(find_address_range<uint64_t>(AR_RAM_START), directory);
-    store_address_range(find_address_range<uint64_t>(AR_SHADOW_TLB_START), directory);
-    // Could iterate over PMAs checking for those with a drive DID but this is easier
-    for (const auto &f : c.flash_drive) {
-        store_address_range(find_address_range<uint64_t>(f.start), directory);
+        throw std::runtime_error{"cannot store unreproducible machines"};
     }
-    store_address_range(find_address_range<uint64_t>(AR_CMIO_RX_BUFFER_START), directory);
-    store_address_range(find_address_range<uint64_t>(AR_CMIO_TX_BUFFER_START), directory);
-    store_address_range(find_address_range<uint64_t>(AR_UARCH_RAM_START), directory);
-    store_address_range(find_address_range<uint64_t>(AR_PMAS_START), directory);
-}
-
-static void store_hash(const machine::hash_type &h, const std::string &dir) {
-    auto name = dir + "/hash";
-    auto fp = make_unique_fopen(name.c_str(), "wb");
-    if (fwrite(h.data(), 1, h.size(), fp.get()) != h.size()) {
-        throw std::runtime_error{"error writing to '" + name + "'"};
-    }
-}
-
-void machine::store(const std::string &dir) const {
     if (os_mkdir(dir.c_str(), 0700) != 0) {
         throw std::system_error{errno, std::generic_category(), "error creating directory '"s + dir + "'"s};
     }
@@ -1843,17 +1474,17 @@ bool machine::verify_dirty_page_maps() const {
     // Go over the write TLB and mark as dirty all pages currently there
     mark_write_tlb_dirty_pages();
     // Now go over all memory PMAs verifying that all dirty pages are marked
-    for (const auto &ar : m_ars) {
-        for (uint64_t page_address = ar->get_start(); page_address < ar->get_end(); page_address += AR_PAGE_SIZE) {
-            const auto offset = page_address - ar->get_start();
-            if (ar->is_memory()) {
+    for (const auto &ar : m_ars.all()) {
+        for (uint64_t page_address = ar.get_start(); page_address < ar.get_end(); page_address += AR_PAGE_SIZE) {
+            const auto offset = page_address - ar.get_start();
+            if (ar.is_memory()) {
                 const unsigned char *page_data = nullptr;
-                ar->peek(*this, offset, AR_PAGE_SIZE, &page_data, scratch.get());
+                ar.peek(*this, offset, AR_PAGE_SIZE, &page_data, scratch.get());
                 hash_type stored;
                 hash_type real;
                 m_t.get_page_node_hash(page_address, stored);
                 m_t.get_page_node_hash(h, page_data, real);
-                const bool marked_dirty = ar->is_page_marked_dirty(offset);
+                const bool marked_dirty = ar.is_page_marked_dirty(offset);
                 const bool is_dirty = (real != stored);
                 if (is_dirty && !marked_dirty) {
                     broken = true;
@@ -1863,8 +1494,8 @@ bool machine::verify_dirty_page_maps() const {
                     std::cerr << "  got " << real << '\n';
                     break;
                 }
-            } else if (ar->is_device()) {
-                if (!ar->is_page_marked_dirty(offset)) {
+            } else if (ar.is_device()) {
+                if (!ar.is_page_marked_dirty(offset)) {
                     broken = true;
                     std::cerr << std::setfill('0') << std::setw(8) << std::hex << page_address
                               << " should have been dirty\n";
@@ -1890,7 +1521,7 @@ bool machine::update_merkle_tree() const {
     mark_write_tlb_dirty_pages();
     // Now go over all PMAs and updating the Merkle tree
     m_t.begin_update();
-    for (auto &ar : m_merkle_ars | std::views::transform([this](auto i) -> address_range & { return *m_ars[i]; })) {
+    for (auto &ar : m_ars.merkle()) {
         // Each PMA has a number of pages
         auto pages_in_range = (ar.get_length() + AR_PAGE_SIZE - 1) / AR_PAGE_SIZE;
         // For each PMA, we launch as many threads (n) as defined on concurrency
@@ -1958,7 +1589,7 @@ bool machine::update_merkle_tree_page(uint64_t address) {
         "PMA and machine_merkle_tree page sizes must match");
     // Align address to beginning of page
     address &= ~(AR_PAGE_SIZE - 1);
-    auto &ar = find_address_range<uint8_t>(address);
+    auto &ar = m_ars.find<uint8_t>(address);
     const uint64_t page_start_in_range = address - ar.get_start();
     machine_merkle_tree::hasher_type h;
     auto scratch = make_unique_calloc<unsigned char>(AR_PAGE_SIZE, std::nothrow_t{});
@@ -2068,7 +1699,7 @@ machine_merkle_tree::proof_type machine::get_proof(uint64_t address, int log2_si
     // Therefore, it is is either entirely inside a PMA range, or entirely outside it.
     if (log2_size < machine_merkle_tree::get_log2_page_size()) {
         const uint64_t length = UINT64_C(1) << log2_size;
-        const auto &ar = find_address_range(address, length);
+        const auto &ar = m_ars.find(address, length);
         auto scratch = make_unique_calloc<unsigned char>(AR_PAGE_SIZE);
         const unsigned char *page_data = nullptr;
         // If the PMA range is empty, we know the desired range is entirely outside of any non-pristine PMA.
@@ -2122,9 +1753,7 @@ void machine::read_memory(uint64_t paddr, unsigned char *data, uint64_t length)
         throw std::invalid_argument{"invalid data buffer"};
     }
     uint64_t gap_start = 0;
-    auto view = m_merkle_ars | // Indices of Mekrle tree address ranges
-        std::views::transform(
-            [this](auto i) -> address_range & { return *m_ars[i]; }) |        // Now address ranges themselves
+    auto view = m_ars.merkle() |
         std::views::drop_while([paddr, &gap_start](const address_range &ar) { // Only those that end after paddr
             const auto ar_end = ar.get_end();
             if (paddr >= ar_end) {
@@ -2180,14 +1809,14 @@ void machine::write_memory(uint64_t paddr, const unsigned char *data, uint64_t l
     if (data == nullptr) {
         throw std::invalid_argument{"invalid data buffer"};
     }
-    auto &ar = find_address_range(paddr, length);
+    auto &ar = m_ars.find(paddr, length);
     if (ar.is_device()) {
         throw std::invalid_argument{"attempted write to device memory range"};
     }
     if (!ar.is_memory()) {
         throw std::invalid_argument{"address range to write is not entirely in single memory range"};
     }
-    if (is_protected(ar.get_driver_id())) {
+    if (pmas_is_protected(ar.get_driver_id())) {
         throw std::invalid_argument{"attempt to write to protected memory range"};
     }
     foreach_aligned_chunk(paddr, length, AR_PAGE_SIZE, [&ar, paddr, data](auto chunk_start, auto chunk_length) {
@@ -2206,14 +1835,14 @@ void machine::fill_memory(uint64_t paddr, uint8_t val, uint64_t length) {
     if (length == 0) {
         return;
     }
-    auto &ar = find_address_range(paddr, length);
+    auto &ar = m_ars.find(paddr, length);
     if (ar.is_device()) {
         throw std::invalid_argument{"attempted fill to device memory range"};
     }
     if (!ar.is_memory()) {
         throw std::invalid_argument{"address range to fill is not entirely in memory PMA"};
     }
-    if (is_protected(ar.get_driver_id())) {
+    if (pmas_is_protected(ar.get_driver_id())) {
         throw std::invalid_argument{"attempt fill to protected memory range"};
     }
     // The case of filling a range with zeros is special and optimized for uarch reset
@@ -2336,7 +1965,7 @@ void machine::write_word(uint64_t paddr, uint64_t val) {
         return;
     }
     // Otherwise, try the slow path
-    auto &ar = find_address_range(paddr, sizeof(uint64_t));
+    auto &ar = m_ars.find(paddr, sizeof(uint64_t));
     if (!ar.is_memory() || ar.get_host_memory() == nullptr) {
         std::ostringstream err;
         err << "attempted memory write to " << ar.get_description() << " at address 0x" << std::hex << paddr << "("
@@ -2402,13 +2031,10 @@ void machine::reset_uarch() {
     for (int i = 1; i < UARCH_X_REG_COUNT; i++) {
         write_reg(machine_reg_enum(reg::uarch_x0, i), UARCH_X_INIT);
     }
-    // Load embedded pristine RAM image
-    const auto uram_length = m_us.ram->get_length();
-    const auto uram_start = m_us.ram->get_start();
     // Reset RAM to initial state
-    write_memory(uram_start, uarch_pristine_ram, uarch_pristine_ram_len);
-    if (uram_length > uarch_pristine_ram_len) {
-        fill_memory(uram_start + uarch_pristine_ram_len, 0, uram_length - uarch_pristine_ram_len);
+    write_memory(AR_UARCH_RAM_START, uarch_pristine_ram, uarch_pristine_ram_len);
+    if (AR_UARCH_RAM_LENGTH > uarch_pristine_ram_len) {
+        fill_memory(AR_UARCH_RAM_START + uarch_pristine_ram_len, 0, AR_UARCH_RAM_LENGTH - uarch_pristine_ram_len);
     }
 }
 
diff --git a/src/machine.h b/src/machine.h
index 723409b8d..de79f6f0a 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -34,6 +34,7 @@
 #include "host-addr.h"
 #include "i-device-state-access.h"
 #include "interpret.h"
+#include "machine-address-ranges.h"
 #include "machine-config.h"
 #include "machine-merkle-tree.h"
 #include "machine-reg.h"
@@ -60,140 +61,38 @@ constexpr skip_merkle_tree_update_t skip_merkle_tree_update;
 /// \brief Cartesi Machine implementation
 class machine final {
 private:
-    mutable machine_state m_s;                                 ///< Big machine state
-    mutable uarch_state m_us;                                  ///< Microarchitecture state
-    mutable std::vector<std::unique_ptr<address_range>> m_ars; ///< All address ranges
-    mutable machine_merkle_tree m_t;                           ///< Merkle tree of state
-    machine_config m_c;                                        ///< Copy of initialization config
-    machine_runtime_config m_r;                                ///< Copy of initialization runtime config
-    std::vector<uint64_t> m_merkle_ars;                   ///< Indices of address ranges that the Mekrle tree can find
-    std::vector<virtio_address_range *> m_virtio_ars;     ///< VirtIO address ranges
-    address_range_descriptions m_ards;                    ///< Address range descriptions listed by get_address_ranges()
-    std::unordered_map<std::string, uint64_t> m_counters; ///< Counters used for statistics collection
-
-    ///< Where to register an address range
-    struct register_where {
-        bool merkle;    //< Register with Merkle tree, so it appears in the root hash
-        bool interpret; //< Register so interpret can see (and it also appears as a PMA entries in memory)
-    };
-
-    /// \brief Checks if address range can be registered.
-    /// \param ar Address range object to register.
-    /// \param where Where to register the address range.
-    void check_address_range(const address_range &ar, register_where where);
-
-    /// \brief Registers a new address range.
-    /// \tparam AR An address range or derived type.
-    /// \param ar The address range object to register (as an r-value).
-    /// \param where Where to register the address range.
-    /// \returns Reference to address range object after it is moved inside the machine.
-    /// \details The r-value address range is moved to the heap, and the pointer holding it is added to a container.
-    /// Once the address range is moved to the heap, its address will remain valid until it is replaced by
-    /// a call to replace_memory_range(), or until the machine is destroyed.
-    /// This means pointers to address ranges remain valid even after subsequent calls to register_address_range(),
-    /// but may be invalidated by calls to replace_address_range().
-    /// For a stronger guarantee, when an address range is replaced, the pointer to the new address range
-    /// overwrites the pointer to the old address range at the same index in the container.
-    /// This means the an index into the container that owns all address ranges will always refers to same address range
-    /// after subsequent calls to register_address_range() and  calls to replace_address_range() as well.
-    /// \details Besides the container that stores the address ranges, the machine maintains subsets of address ranges.
-    /// The "merkle" address range container lists the indices of the address ranges taht will be considered by
-    /// the Merkle tree during the computation of the state hash.
-    /// The "interpret" address range container lists the indices of the address ranges that will be visible from within
-    /// the interpreter.
-    /// When registering an address range with the machine, one must specify \p where else to register it.
-    /// The "virtio" address range container holds pointers to every virtio address range that has been registered.
-    template <typename AR>
-    AR &register_address_range(AR &&ar, register_where where)
-        requires std::is_rvalue_reference_v<AR &&> && std::derived_from<AR, address_range>
-    {
-        check_address_range(ar, where);                     // Check if we can register it
-        auto ptr = make_moved_unique(std::forward<AR>(ar)); // Move object to heap, now owned by ptr
-        AR &ar_ref = *ptr;                                  // Get reference to object, already in heap, to return later
-        const auto index = m_ars.size();                    // Get index new address range will occupy
-        m_ars.push_back(std::move(ptr));                    // Move ptr to list of address ranges
-        if (where.interpret) {                              // Register with interpreter
-            m_s.pmas.push_back(index);
-        }
-        if (where.merkle) { // Register with Merkle tree
-            m_merkle_ars.push_back(index);
-        }
-        if constexpr (std::is_convertible_v<AR *, virtio_address_range *>) { // Register with VirtIO
-            m_virtio_ars.push_back(&ar_ref);
-        }
-        return ar_ref; // Return reference to object in heap
-    }
+    machine_config m_c;                   ///< Copy of initialization config
+    machine_runtime_config m_r;           ///< Copy of initialization runtime config
+    mutable machine_address_ranges m_ars; ///< Address ranges
+    mutable uarch_state m_us;             ///< Uarch state
+    mutable machine_state m_s;            ///< Big machine state
+    mutable machine_merkle_tree m_t;      ///< Merkle tree of state
 
-    /// \brief Saves address ranges into files for serialization
-    /// \param config Machine config to be stored
-    /// \param directory Directory where address ranges will be stored
-    void store_address_ranges(const machine_config &config, const std::string &directory) const;
-
-    /// \brief Saves an address range into serialization directory
-    /// \param ar Address range to store
-    /// \param directory Directory where address range will be stored
-    void store_address_range(const address_range &ar, const std::string &directory) const;
+    std::unordered_map<std::string, uint64_t> m_counters; ///< Counters used for statistics collection
 
     /// \brief Returns offset that converts between machine host addresses and target physical addresses
     /// \param pma_index Index of the memory PMA for the desired offset
     host_addr get_hp_offset(uint64_t pma_index) const;
 
-    /// \brief Initializes microarchitecture
-    /// \param c Microarchitecture configuration
-    void init_uarch(const uarch_config &c);
+    /// \brief Initializes uarch processor
+    /// \param c Uarch configuration
+    void init_uarch_processor(const uarch_config &c);
 
     /// \brief Initializes registers
     /// \param p Processor configuration
     /// \param r Machine runtime configuration
     void init_processor(processor_config &p, const machine_runtime_config &r);
 
-    /// \brief Initializes RAM address range
-    /// \param ram RAM configuration
-    void init_ram_ar(const ram_config &ram);
-
-    /// \brief Initializes flash drive PMAs
-    /// \param flash_drive Flash drive configurations
-    void init_flash_drive_ars(flash_drive_configs &flash_drive);
-
-    /// \brief Initializes VirtIO device PMAs
-    /// \param virtio VirtIO configurations
-    /// \param iunrep Initial value of iunrep CSR
-    void init_virtio_ars(const virtio_configs &virtio, uint64_t iunrep);
-
-    /// \brief Initializes HTIF device address range
-    /// \param h HTIF configuration
-    void init_htif_ar(const htif_config &h);
-
     /// \brief Initializes TTY if needed
     /// \param h HTIF configuration
     /// \param r HTIF runtime configuration
     /// \param iunrep Initial value of iunrep CSR
     void init_tty(const htif_config &h, const htif_runtime_config &r, uint64_t iunrep) const;
 
-    /// \brief Initializes CLINT device address range
-    /// \param c CLINT configuration
-    void init_clint_ar(const clint_config &c);
-
-    /// \brief Initializes PLIC device address range
-    /// \param p PLIC configuration
-    void init_plic_ar(const plic_config &p);
-
-    /// \brief Initializes CMIO address ranges
-    /// \param c CMIO configuration
-    void init_cmio_ars(const cmio_config &c);
-
-    /// \brief Initializes the address ranges involced in the Merkle tree
-    /// \detail This can only be called after all address ranges have been registerd
-    void init_merkle_ars();
-
-    /// \brief Initializes the address range descriptions returned by get_address_ranges()
-    /// \detail This can only be called after all address ranges have been registered
-    void init_ars_descriptions();
-
     /// \brief Initializes contents of the shadow PMAs memory
-    /// \param pmas PMA entry for the shadow PMAs
+    /// \param pmas_config PMAs configuration
     /// \detail This can only be called after all PMAs have been added
-    void init_pmas_contents(const pmas_config &config, memory_address_range &pmas) const;
+    void init_pmas_contents(const pmas_config &config);
 
     /// \brief Initializes contents of machine TLB, from image in disk or with default values
     /// \param config TLB config
@@ -202,8 +101,19 @@ class machine final {
 
     /// \brief Initializes contents of machine DTB, if image was not available
     /// \param config Machine configuration
-    /// \param dtb PMA entry for the shadow PMAs
-    static void init_dtb_contents(const machine_config &config, memory_address_range &dtb);
+    void init_dtb_contents(const machine_config &config);
+
+    /// \brief Initializes HTIF registers
+    /// \param h HTIF configuration
+    void init_htif_registers(const htif_config &h);
+
+    /// \brief Initializes CLINT registers
+    /// \param c CLINT configuration
+    void init_clint_registers(const clint_config &c);
+
+    /// \brief Initializes PLIC registers
+    /// \param p PLIC configuration
+    void init_plic_registers(const plic_config &p);
 
     /// \brief Dumps statistics
     void dump_stats();
@@ -217,6 +127,32 @@ class machine final {
     /// \details The counter is key is the concatenation of \p domain with \p name.
     static std::string get_counter_key(const char *name, const char *domain = nullptr);
 
+    /// \brief Stores address ranges into files for serialization
+    /// \param c Serialization machine config
+    /// \param dir Directory where address ranges will be stored
+    void store_address_ranges(const machine_config &c, const std::string &dir) const;
+
+    /// \brief Stores address range into files for serialization
+    /// \param ar Address range to store
+    /// \param dir Directory where address ranges will be stored
+    void store_address_range(const address_range &ar, const std::string &dir) const;
+
+    /// \brief Checks if the machine has VirtIO devices.
+    /// \returns True if at least one VirtIO device is present.
+    bool has_virtio_devices() const;
+
+    /// \brief Checks if the machine has VirtIO console device.
+    /// \returns True if at least one VirtIO console is present.
+    bool has_virtio_console() const;
+
+    /// \brief Checks if the machine has HTIF console device.
+    /// \returns True if HTIF console is present.
+    bool has_htif_console() const;
+
+    /// \brief Copies the current state into a configuration for serialization
+    /// \returns The configuration
+    machine_config get_serialization_config() const;
+
 public:
     /// \brief Type of hash
     using hash_type = machine_merkle_tree::hash_type;
@@ -237,6 +173,14 @@ class machine final {
     /// \param directory Directory to store machine into
     void store(const std::string &directory) const;
 
+    /// \brief Returns address range that covers a given physical memory region
+    /// \param paddr Target physical address of start of region.
+    /// \param length Length of region, in bytes.
+    /// \returns Corresponding address range if found, or an empty sentinel otherwise.
+    const address_range &find_address_range(uint64_t paddr, uint64_t length) const noexcept {
+        return m_ars.find(paddr, length);
+    }
+
     /// \brief No default constructor
     machine() = delete;
     /// \brief No copy constructor
@@ -248,6 +192,9 @@ class machine final {
     /// \brief No move assignment
     machine &operator=(machine &&other) = delete;
 
+    /// \brief Destructor.
+    ~machine();
+
     /// \brief Runs the machine until mcycle reaches mcycle_end, the machine halts or yields.
     /// \param mcycle_end Maximum value of mcycle before function returns.
     /// \returns The reason the machine was interrupted.
@@ -306,6 +253,11 @@ class machine final {
     /// \brief Returns copy of default machine config
     static machine_config get_default_config();
 
+    /// \brief Returns a list of descriptions for all PMA entries registered in the machine, sorted by start
+    const address_range_descriptions &get_address_ranges() const {
+        return m_ars.descriptions();
+    }
+
     /// \brief Returns machine state for direct access.
     machine_state &get_state() {
         return m_s;
@@ -326,11 +278,6 @@ class machine final {
         return m_us;
     }
 
-    /// \brief Returns a list of descriptions for all PMA entries registered in the machine, sorted by start
-    address_range_descriptions get_address_ranges() const {
-        return m_ards;
-    }
-
     /// \brief Wait for external interrupts requests.
     /// \param mcycle Current value of mcycle.
     /// \param mcycle_max Maximum mcycle after wait.
@@ -341,9 +288,6 @@ class machine final {
     /// is triggered or until the amount of time estimated for mcycle to reach mcycle_max has elapsed.
     std::pair<uint64_t, execute_status> poll_external_interrupts(uint64_t mcycle, uint64_t mcycle_max);
 
-    /// \brief Destructor.
-    ~machine();
-
     /// \brief Fill file descriptors to be polled by select() for all VirtIO devices.
     /// \param fds Pointer to sets of read, write and except file descriptors to be updated.
     /// \param timeout_us Maximum amount of time to wait in microseconds, this may be updated (always to lower
@@ -364,18 +308,6 @@ class machine final {
     /// \returns True if an interrupt was requested, false otherwise.
     bool poll_virtio_devices(uint64_t *timeout_us, i_device_state_access *da);
 
-    /// \brief Checks if the machine has VirtIO devices.
-    /// \returns True if at least one VirtIO device is present.
-    bool has_virtio_devices() const;
-
-    /// \brief Checks if the machine has VirtIO console device.
-    /// \returns True if at least one VirtIO console is present.
-    bool has_virtio_console() const;
-
-    /// \brief Checks if the machine has HTIF console device.
-    /// \returns True if HTIF console is present.
-    bool has_htif_console() const;
-
     /// \brief Update the Merkle tree so it matches the contents of the machine state.
     /// \returns true if succeeded, false otherwise.
     bool update_merkle_tree() const;
@@ -497,12 +429,7 @@ class machine final {
     /// \param index Index of desired address range
     /// \returns Desired address range, or an empty sentinel if index is out of bounds
     const address_range &read_pma(uint64_t index) const noexcept {
-        if (index >= m_s.pmas.size()) {
-            static constexpr auto sentinel = make_empty_address_range("sentinel");
-            return sentinel;
-        }
-        // NOLINTNEXTLINE(bugprone-narrowing-conversions)
-        return *m_ars[static_cast<int>(m_s.pmas[static_cast<int>(index)])];
+        return m_ars.read_pma(index);
     }
 
     /// \brief Returns the address range associated to the PMA at a given index
@@ -513,33 +440,6 @@ class machine final {
         return const_cast<address_range &>(std::as_const(*this).read_pma(index));
     }
 
-    /// \brief Obtain address range from the machine state that covers a given physical memory region
-    /// \param paddr Target physical address of start of region.
-    /// \param length Length of region, in bytes.
-    /// \returns Corresponding address range if found, or an empty sentinel otherwise.
-    /// \warning Microarchitecture address ranges are not considered in the search.
-    const address_range &find_address_range(uint64_t paddr, uint64_t length) const noexcept;
-
-    address_range &find_address_range(uint64_t paddr, uint64_t length) noexcept {
-        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-const-cast)
-        return const_cast<address_range &>(std::as_const(*this).find_address_range(paddr, length));
-    }
-
-    /// \brief Obtain address range from the machine state that covers a given word in physical memory
-    /// \tparam T Type of word.
-    /// \param paddr Target physical address of word.
-    /// \returns Corresponding address range if found, or an empty sentinel otherwise.
-    /// \warning Microarchitecture address ranges are not considered in the search.
-    template <typename T>
-    const address_range &find_address_range(uint64_t paddr) const {
-        return find_address_range(paddr, sizeof(T));
-    }
-
-    template <typename T>
-    address_range &find_address_range(uint64_t paddr) {
-        return find_address_range(paddr, sizeof(T));
-    }
-
     /// \brief Go over the write TLB and mark as dirty all pages currently there.
     void mark_write_tlb_dirty_pages() const;
 
@@ -547,10 +447,6 @@ class machine final {
     /// \returns true if they are, false if there is an error.
     bool verify_dirty_page_maps() const;
 
-    /// \brief Copies the current state into a configuration for serialization
-    /// \returns The configuration
-    machine_config get_serialization_config() const;
-
     /// \brief Returns copy of initialization config.
     const machine_config &get_initial_config() const;
 
@@ -562,10 +458,12 @@ class machine final {
     /// \details Some runtime options cannot be changed.
     void set_runtime_config(machine_runtime_config r);
 
-    /// \brief Replaces a memory range.
-    /// \param config Configuration of the new memory range.
-    /// \details The machine must contain an existing memory range matching the start and length specified in range.
-    void replace_memory_range(const memory_range_config &config);
+    /// \brief Replaces a memory address range.
+    /// \param config Configuration of the new memory address range.
+    /// \details A memory address range matching the start and length specified in the config must exist.
+    void replace_memory_range(const memory_range_config &config) {
+        m_ars.replace(config);
+    }
 
     /// \brief Sends cmio response
     /// \param reason Reason for sending response.
diff --git a/src/memory-address-range.cpp b/src/memory-address-range.cpp
index da61d5d12..1a7e38811 100644
--- a/src/memory-address-range.cpp
+++ b/src/memory-address-range.cpp
@@ -16,6 +16,15 @@
 
 #include "memory-address-range.h"
 
+#include <cerrno>
+#include <cstdio>
+#include <exception>
+#include <stdexcept>
+#include <system_error>
+
+#include "address-range-constants.h"
+#include "unique-c-ptr.h"
+
 namespace cartesi {
 
 using namespace std::string_literals;
diff --git a/src/pmas.h b/src/pmas.h
index 819981e40..6244ee1b6 100644
--- a/src/pmas.h
+++ b/src/pmas.h
@@ -60,6 +60,18 @@ static constexpr const char *pmas_get_DID_name(PMA_ISTART_DID did) {
     return "DID.unknown";
 }
 
+static constexpr bool pmas_is_protected(PMA_ISTART_DID DID) {
+    switch (DID) {
+        case PMA_ISTART_DID::memory:
+        case PMA_ISTART_DID::flash_drive:
+        case PMA_ISTART_DID::cmio_rx_buffer:
+        case PMA_ISTART_DID::cmio_tx_buffer:
+            return false;
+        default:
+            return true;
+    }
+}
+
 ///< Unpacked attribute flags
 struct pmas_flags {
     bool M;             ///< is memory
diff --git a/src/record-send-cmio-state-access.h b/src/record-send-cmio-state-access.h
index 8fdedeb6a..e2eb87d30 100644
--- a/src/record-send-cmio-state-access.h
+++ b/src/record-send-cmio-state-access.h
@@ -213,7 +213,7 @@ class record_send_cmio_state_access :
         }
         // We need to compute the hash of the existing data before writing
         // Find the target address range
-        auto &ar = m_m.find_address_range(paddr, write_length);
+        const auto &ar = m_m.find_address_range(paddr, write_length);
         if (!ar.is_memory()) {
             throw std::invalid_argument("address range not entirely in memory PMA");
         }
diff --git a/src/shadow-uarch-state-address-range.h b/src/shadow-uarch-state-address-range.h
index 025219248..9ddd4a4df 100644
--- a/src/shadow-uarch-state-address-range.h
+++ b/src/shadow-uarch-state-address-range.h
@@ -43,8 +43,9 @@ class shadow_uarch_state_address_range final : public address_range {
 
 public:
     template <typename ABRT>
-    shadow_uarch_state_address_range(uint64_t start, uint64_t length, ABRT abrt) :
-        address_range("shadow uarch state", start, length, m_shadow_uarch_state_flags, abrt) {
+    explicit shadow_uarch_state_address_range(ABRT abrt) :
+        address_range("shadow uarch state", AR_SHADOW_UARCH_STATE_START, AR_SHADOW_UARCH_STATE_LENGTH,
+            m_shadow_uarch_state_flags, abrt) {
         ;
     }
 
@@ -63,9 +64,8 @@ class shadow_uarch_state_address_range final : public address_range {
 };
 
 template <typename ABRT>
-static inline shadow_uarch_state_address_range make_shadow_uarch_state_address_range(uint64_t start, uint64_t length,
-    ABRT abrt) {
-    return shadow_uarch_state_address_range{start, length, abrt};
+static inline shadow_uarch_state_address_range make_shadow_uarch_state_address_range(ABRT abrt) {
+    return shadow_uarch_state_address_range{abrt};
 }
 
 } // namespace cartesi
diff --git a/src/uarch-state-access.h b/src/uarch-state-access.h
index fc1b7ef45..b62410112 100644
--- a/src/uarch-state-access.h
+++ b/src/uarch-state-access.h
@@ -38,19 +38,11 @@ class uarch_state_access :
     // NOLINTBEGIN(cppcoreguidelines-avoid-const-or-ref-data-members)
     machine &m_m;
     // NOLINTEND(cppcoreguidelines-avoid-const-or-ref-data-members)
-    host_addr m_uram_ph_offset;
 
 public:
-    /// \brief Constructor from machine and uarch states.
-    /// \param um Reference to uarch state.
-    /// \param m Reference to machine state.
-    explicit uarch_state_access(machine &m) : m_m(m) {
-        const auto &uram = m_m.get_uarch_state().ram;
-        const auto haddr = cast_ptr_to_host_addr(uram->get_host_memory());
-        const auto paddr = uram->get_start();
-        // initialize translation cache from paddr in uarch RAM to host address
-        m_uram_ph_offset = haddr - paddr;
-    }
+    /// \brief Constructor from machine.
+    /// \param m Reference to machine.
+    explicit uarch_state_access(machine &m) : m_m(m) {}
 
 private:
     // -----
diff --git a/src/uarch-state.h b/src/uarch-state.h
index 51c0db901..ffd2a2420 100644
--- a/src/uarch-state.h
+++ b/src/uarch-state.h
@@ -43,8 +43,6 @@ struct uarch_state {
     std::array<uint64_t, UARCH_X_REG_COUNT> x{}; ///< Register file.
     uint64_t cycle{};                            ///< Cycles counter
     uint64_t halt_flag{};
-    address_range *shadow_state{}; ///< Shadow uarch state
-    memory_address_range *ram{};   ///< Memory range for uarch RAM
 };
 
 } // namespace cartesi

From 0d20122a3d03b80b9880d065bc4416a1e886992d Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Thu, 27 Mar 2025 10:56:04 -0300
Subject: [PATCH 34/82] refactor!: support backing files for processor config

---
 src/address-range.h                     |   8 +-
 src/cartesi-machine.lua                 |  46 +-
 src/clua-cartesi.cpp                    |   7 +
 src/dtb.cpp                             |   8 +-
 src/htif-constants.h                    |   9 +
 src/json-util.cpp                       | 129 ++--
 src/json-util.h                         |  74 ++-
 src/jsonrpc-discover.json               |  24 +
 src/machine-address-ranges.cpp          |   2 +-
 src/machine-c-api.h                     |   6 +-
 src/machine-config.h                    |  82 +--
 src/machine-reg.h                       |   1 -
 src/machine-state.h                     |  78 +--
 src/machine.cpp                         | 746 ++++++++++++------------
 src/machine.h                           |  18 +-
 src/pristine-address-range.h            |   2 +-
 src/record-send-cmio-state-access.h     |   8 +-
 src/replay-step-state-access.h          |   4 +-
 src/riscv-constants.h                   |  56 +-
 src/shadow-state.h                      | 152 +++--
 src/shadow-uarch-state.h                |  19 +-
 src/state-access.h                      | 158 ++---
 src/uarch-state-access.h                |  16 +-
 src/uarch-state.h                       |   9 +-
 tests/lua/htif-console.lua              |   4 +-
 tests/lua/htif-yield.lua                |  10 +-
 tests/lua/log-with-mtime-transition.lua |   4 +-
 tests/lua/machine-bind.lua              | 164 ++----
 tests/lua/machine-test.lua              |   7 +-
 tests/lua/run-rv64i-arch-test.lua       |   1 -
 tests/lua/test-jsonrpc-fork.lua         |   2 +-
 tests/misc/test-machine-c-api.cpp       |   4 +-
 32 files changed, 937 insertions(+), 921 deletions(-)

diff --git a/src/address-range.h b/src/address-range.h
index 95ea1df9d..17f4c5a20 100644
--- a/src/address-range.h
+++ b/src/address-range.h
@@ -80,7 +80,7 @@ class address_range {
     /// \param description Description of address range for use in error messages (will be copied)
     /// \param start Target physical address where range starts
     /// \param length Length of range, in bytes
-    /// \param f Phyical memory attribute flags for range
+    /// \param f Physical memory attribute flags for range
     template <typename ABRT>
     address_range(const char *description, uint64_t start, uint64_t length, const pmas_flags &flags, ABRT abrt) :
         m_description{},
@@ -217,7 +217,7 @@ class address_range {
     }
 
     /// \brief Returns driver ID associated to range
-    /// \returns Teh driver ID
+    /// \returns The driver ID
     PMA_ISTART_DID get_driver_id() const noexcept {
         return m_flags.DID;
     }
@@ -228,7 +228,7 @@ class address_range {
         return pmas_pack_istart(m_flags, m_start);
     }
 
-    /// \brief Returns encoded addres range ilength field as per whitepaper
+    /// \brief Returns encoded address range ilength field as per whitepaper
     /// \returns Packed address range ilength
     /// \details This currently contains only the length itself
     uint64_t get_ilength() const noexcept {
@@ -351,7 +351,7 @@ class address_range {
         return nullptr;
     }
 
-    // Defaul implemenation always assumes every page is always dirty
+    // Default implementation always assumes every page is always dirty
     virtual void do_mark_dirty_page(uint64_t /*offset*/) noexcept {
         ;
     }
diff --git a/src/cartesi-machine.lua b/src/cartesi-machine.lua
index ed19f6208..2663917e5 100755
--- a/src/cartesi-machine.lua
+++ b/src/cartesi-machine.lua
@@ -1720,7 +1720,7 @@ end
 
 local function dump_value_proofs(machine, desired_proofs, config)
     if #desired_proofs > 0 then
-        assert(config.processor.iunrep == 0, "proofs are meaningless in unreproducible mode")
+        assert(config.processor.registers.iunrep == 0, "proofs are meaningless in unreproducible mode")
     end
     for _, desired in ipairs(desired_proofs) do
         local proof = machine:get_proof(desired.address, desired.log2_size)
@@ -1802,17 +1802,20 @@ else
     -- Build machine config
     local config = {
         processor = {
-            iunrep = unreproducible and 1 or 0,
+            registers = {
+                iunrep = unreproducible and 1 or 0,
+                htif = {
+                    iconsole = (htif_console_getchar and cartesi.HTIF_CONSOLE_CMD_GETCHAR_MASK or 0)
+                        | cartesi.HTIF_CONSOLE_CMD_PUTCHAR_MASK,
+                    iyield = (htif_yield_automatic and cartesi.HTIF_YIELD_CMD_AUTOMATIC_MASK or 0)
+                        | (htif_yield_manual and cartesi.HTIF_YIELD_CMD_MANUAL_MASK or 0),
+                },
+            },
         },
         ram = ram,
         dtb = dtb,
         flash_drive = {},
         tlb = tlb,
-        htif = {
-            console_getchar = htif_console_getchar,
-            yield_automatic = htif_yield_automatic,
-            yield_manual = htif_yield_manual,
-        },
         virtio = virtio,
         cmio = cmio,
         pmas = pmas,
@@ -1992,15 +1995,20 @@ local cmio_yield_command = {
 }
 
 local function check_cmio_htif_config(htif)
-    assert(not htif.console_getchar, "console getchar must be disabled for cmio")
-    assert(htif.yield_manual, "yield manual must be enabled for cmio")
-    assert(htif.yield_automatic, "yield automatic must be enabled for cmio")
+    assert((htif.iconsole & cartesi.HTIF_CONSOLE_CMD_GETCHAR_MASK) == 0, "console getchar must be disabled for cmio")
+    assert(
+        htif.iyield == (cartesi.HTIF_YIELD_CMD_MANUAL_MASK | cartesi.HTIF_YIELD_CMD_AUTOMATIC_MASK),
+        "yield manual must be enabled for cmio"
+    )
 end
 
 local function get_and_print_yield(machine, htif)
     local cmd, reason, data = machine:receive_cmio_request()
     if cmd == cartesi.CMIO_YIELD_COMMAND_AUTOMATIC and reason == cartesi.CMIO_YIELD_AUTOMATIC_REASON_PROGRESS then
-        stderr("Progress: %6.2f" .. (htif.console_getchar and "\n" or "\r"), string.unpack("I4", data) / 10)
+        stderr(
+            "Progress: %6.2f" .. ((htif.iconsole & cartesi.HTIF_CONSOLE_CMD_GETCHAR_MASK) ~= 0 and "\n" or "\r"),
+            string.unpack("I4", data) / 10
+        )
         return cmd, reason, data
     end
     local cmd_str = cmio_yield_command[cmd] or "Unknown"
@@ -2070,7 +2078,7 @@ local function save_cmio_inspect_state_report(inspect, data)
 end
 
 local function store_machine(machine, config, dir)
-    assert(config.processor.iunrep == 0, "hashes are meaningless in unreproducible mode")
+    assert(config.processor.registers.iunrep == 0, "hashes are meaningless in unreproducible mode")
     stderr("Storing machine: please wait\n")
     local values = {}
     if dir:find("%%h") then values.h = util.hexhash(machine:get_root_hash()) end
@@ -2099,13 +2107,13 @@ if gdb_address then
     assert(address and port, "invalid address for GDB")
     gdb_stub:listen_and_wait_gdb(address, tonumber(port))
 end
-if config.processor.iunrep ~= 0 then stderr("Running in unreproducible mode!\n") end
+if config.processor.registers.iunrep ~= 0 then stderr("Running in unreproducible mode!\n") end
 if cmio_advance or cmio_inspect then
-    check_cmio_htif_config(config.htif)
+    check_cmio_htif_config(config.processor.registers.htif)
     assert(remote_address or not perform_rollbacks, "cmio requires --remote-address for snapshot/commit/rollback")
 end
 if initial_hash then
-    assert(config.processor.iunrep == 0, "hashes are meaningless in unreproducible mode")
+    assert(config.processor.registers.iunrep == 0, "hashes are meaningless in unreproducible mode")
     print_root_hash(machine, stderr_unsilenceable)
 end
 dump_value_proofs(machine, initial_proof, config)
@@ -2192,7 +2200,7 @@ while math.ult(machine:read_reg("mcycle"), max_mcycle) do
         break
     -- deal with yield manual
     elseif machine:read_reg("iflags_Y") ~= 0 then
-        local _, reason, data = get_and_print_yield(machine, config.htif)
+        local _, reason, data = get_and_print_yield(machine, config.processor.registers.htif)
         -- there was an exception
         if reason == cartesi.CMIO_YIELD_MANUAL_REASON_TX_EXCEPTION then
             stderr("cmio exception with payload: %q\n", data)
@@ -2256,7 +2264,7 @@ while math.ult(machine:read_reg("mcycle"), max_mcycle) do
         end
     -- deal with yield automatic
     elseif machine:read_reg("iflags_X") ~= 0 then
-        local _, reason, data = get_and_print_yield(machine, config.htif)
+        local _, reason, data = get_and_print_yield(machine, config.processor.registers.htif)
         -- we have fed an advance state input
         if cmio_advance and cmio_advance.next_input_index > cmio_advance.input_index_begin then
             if reason == cartesi.CMIO_YIELD_AUTOMATIC_REASON_TX_OUTPUT then
@@ -2312,7 +2320,7 @@ if max_uarch_cycle > 0 then
 end
 if gdb_stub then gdb_stub:close() end
 if log_step_uarch then
-    assert(config.processor.iunrep == 0, "micro step proof is meaningless in unreproducible mode")
+    assert(config.processor.registers.iunrep == 0, "micro step proof is meaningless in unreproducible mode")
     stderr("Gathering micro step log: please wait\n")
     util.dump_log(machine:log_step_uarch(cartesi.ACCESS_LOG_TYPE_ANNOTATIONS), io.stderr)
 end
@@ -2322,7 +2330,7 @@ if log_reset_uarch then
 end
 if dump_memory_ranges then dump_pmas(machine) end
 if final_hash then
-    assert(config.processor.iunrep == 0, "hashes are meaningless in unreproducible mode")
+    assert(config.processor.registers.iunrep == 0, "hashes are meaningless in unreproducible mode")
     print_root_hash(machine, stderr_unsilenceable)
 end
 dump_value_proofs(machine, final_proof, config)
diff --git a/src/clua-cartesi.cpp b/src/clua-cartesi.cpp
index 1326f0806..5a196b45c 100644
--- a/src/clua-cartesi.cpp
+++ b/src/clua-cartesi.cpp
@@ -30,6 +30,7 @@ extern "C" {
 #include "base64.h"
 #include "clua-i-machine.h"
 #include "clua.h"
+#include "htif-constants.h"
 #include "keccak-256-hasher.h"
 #include "machine-c-api.h"
 #include "machine-c-version.h"
@@ -225,6 +226,12 @@ CM_API int luaopen_cartesi(lua_State *L) {
     clua_setintegerfield(L, CM_AR_CMIO_TX_BUFFER_START, "AR_CMIO_TX_BUFFER_START", -1);
     clua_setintegerfield(L, CM_AR_CMIO_TX_BUFFER_LOG2_SIZE, "AR_CMIO_TX_BUFFER_LOG2_SIZE", -1);
     clua_setintegerfield(L, CM_AR_RAM_START, "AR_RAM_START", -1);
+    // HTIF masks
+    clua_setintegerfield(L, HTIF_HALT_CMD_HALT_MASK, "HTIF_HALT_CMD_HALT_MASK", -1);
+    clua_setintegerfield(L, HTIF_CONSOLE_CMD_GETCHAR_MASK, "HTIF_CONSOLE_CMD_GETCHAR_MASK", -1);
+    clua_setintegerfield(L, HTIF_CONSOLE_CMD_PUTCHAR_MASK, "HTIF_CONSOLE_CMD_PUTCHAR_MASK", -1);
+    clua_setintegerfield(L, HTIF_YIELD_CMD_MANUAL_MASK, "HTIF_YIELD_CMD_MANUAL_MASK", -1);
+    clua_setintegerfield(L, HTIF_YIELD_CMD_AUTOMATIC_MASK, "HTIF_YIELD_CMD_AUTOMATIC_MASK", -1);
     // Set other constants used by internal tests
     clua_setintegerfield(L, UARCH_STATE_START_ADDRESS, "UARCH_STATE_START_ADDRESS", -1);
     clua_setintegerfield(L, UARCH_STATE_LOG2_SIZE, "UARCH_STATE_LOG2_SIZE", -1);
diff --git a/src/dtb.cpp b/src/dtb.cpp
index e42422642..b7e2983b9 100644
--- a/src/dtb.cpp
+++ b/src/dtb.cpp
@@ -97,7 +97,7 @@ void dtb_init(const machine_config &c, unsigned char *dtb_start, uint64_t dtb_le
                 fdt.prop_u32("reg", 0);
                 fdt.prop_string("status", "okay");
                 fdt.prop_string("compatible", "riscv");
-                fdt.prop_string("riscv,isa", misa_to_isa_string(c.processor.misa));
+                fdt.prop_string("riscv,isa", misa_to_isa_string(c.processor.registers.misa));
                 fdt.prop_string("mmu-type", "riscv,sv39");
                 fdt.prop_u32("clock-frequency", RTC_CLOCK_FREQ);
                 { // interrupt-controller
@@ -206,13 +206,13 @@ void dtb_init(const machine_config &c, unsigned char *dtb_start, uint64_t dtb_le
         fdt.end_node();
 
         // yield
-        if (c.htif.yield_manual || c.htif.yield_automatic) {
+        if (c.processor.registers.htif.iyield != 0) {
             fdt.begin_node("yield");
             fdt.prop_string("compatible", "ctsi-yield");
-            if (c.htif.yield_manual) {
+            if ((c.processor.registers.htif.iyield & HTIF_YIELD_CMD_MANUAL_MASK) != 0) {
                 fdt.prop_empty("manual");
             }
-            if (c.htif.yield_automatic) {
+            if ((c.processor.registers.htif.iyield & HTIF_YIELD_CMD_AUTOMATIC_MASK) != 0) {
                 fdt.prop_empty("automatic");
             }
             fdt.end_node();
diff --git a/src/htif-constants.h b/src/htif-constants.h
index 1a57a13f6..744f69bba 100644
--- a/src/htif-constants.h
+++ b/src/htif-constants.h
@@ -102,6 +102,15 @@ enum HTIF_commands : uint64_t {
     HTIF_YIELD_CMD_AUTOMATIC = HTIF_YIELD_CMD_AUTOMATIC_DEF,
 };
 
+/// \brief HTIF commands masks
+enum HTIF_commands_masks : uint64_t {
+    HTIF_HALT_CMD_HALT_MASK = UINT64_C(1) << HTIF_HALT_CMD_HALT,
+    HTIF_CONSOLE_CMD_GETCHAR_MASK = UINT64_C(1) << HTIF_CONSOLE_CMD_GETCHAR,
+    HTIF_CONSOLE_CMD_PUTCHAR_MASK = UINT64_C(1) << HTIF_CONSOLE_CMD_PUTCHAR,
+    HTIF_YIELD_CMD_MANUAL_MASK = UINT64_C(1) << HTIF_YIELD_CMD_MANUAL,
+    HTIF_YIELD_CMD_AUTOMATIC_MASK = UINT64_C(1) << HTIF_YIELD_CMD_AUTOMATIC,
+};
+
 /// \brief HTIF yield reasons
 enum HTIF_yield_reason : uint64_t {
     HTIF_YIELD_AUTOMATIC_REASON_PROGRESS = HTIF_YIELD_AUTOMATIC_REASON_PROGRESS_DEF,
diff --git a/src/json-util.cpp b/src/json-util.cpp
index 719578307..5341216c7 100644
--- a/src/json-util.cpp
+++ b/src/json-util.cpp
@@ -1159,7 +1159,7 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
     not_default_constructible<access_log> &value, const std::string &path);
 
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, processor_config &value, const std::string &path) {
+void ju_get_opt_field(const nlohmann::json &j, const K &key, registers_state &value, const std::string &path) {
     if (!contains(j, key, path)) {
         return;
     }
@@ -1259,10 +1259,28 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, processor_config &v
     ju_get_opt_field(jconfig, "senvcfg"s, value.senvcfg, new_path);
     ju_get_opt_field(jconfig, "ilrsc"s, value.ilrsc, new_path);
     ju_get_opt_field(jconfig, "iprv"s, value.iprv, new_path);
-    ju_get_opt_field(jconfig, "iflags_X"s, value.iflags_X, new_path);
-    ju_get_opt_field(jconfig, "iflags_Y"s, value.iflags_Y, new_path);
-    ju_get_opt_field(jconfig, "iflags_H"s, value.iflags_H, new_path);
+    ju_get_opt_field(jconfig, "iflags"s, value.iflags, new_path);
     ju_get_opt_field(jconfig, "iunrep"s, value.iunrep, new_path);
+    ju_get_opt_field(jconfig, "clint"s, value.clint, new_path);
+    ju_get_opt_field(jconfig, "plic"s, value.plic, new_path);
+    ju_get_opt_field(jconfig, "htif"s, value.htif, new_path);
+}
+
+template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, registers_state &value,
+    const std::string &path);
+
+template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key, registers_state &value,
+    const std::string &path);
+
+template <typename K>
+void ju_get_opt_field(const nlohmann::json &j, const K &key, processor_config &value, const std::string &path) {
+    if (!contains(j, key, path)) {
+        return;
+    }
+    const auto &jconfig = j[key];
+    const auto new_path = path + to_string(key) + "/";
+    ju_get_opt_field(jconfig, "registers"s, value.registers, new_path);
+    ju_get_opt_field(jconfig, "backing_store"s, value.backing_store, new_path);
 }
 
 template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, processor_config &value,
@@ -1481,7 +1499,25 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
     const std::string &path);
 
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, clint_config &value, const std::string &path) {
+void ju_get_opt_field(const nlohmann::json &j, const K &key, iflags_state &value, const std::string &path) {
+    if (!contains(j, key, path)) {
+        return;
+    }
+    const auto &jconfig = j[key];
+    const auto new_path = path + to_string(key) + "/";
+    ju_get_opt_field(jconfig, "X"s, value.X, new_path);
+    ju_get_opt_field(jconfig, "Y"s, value.Y, new_path);
+    ju_get_opt_field(jconfig, "H"s, value.H, new_path);
+}
+
+template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, iflags_state &value,
+    const std::string &path);
+
+template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key, iflags_state &value,
+    const std::string &path);
+
+template <typename K>
+void ju_get_opt_field(const nlohmann::json &j, const K &key, clint_state &value, const std::string &path) {
     if (!contains(j, key, path)) {
         return;
     }
@@ -1490,14 +1526,14 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, clint_config &value
     ju_get_opt_field(jconfig, "mtimecmp"s, value.mtimecmp, new_path);
 }
 
-template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, clint_config &value,
+template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, clint_state &value,
     const std::string &path);
 
-template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key, clint_config &value,
+template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key, clint_state &value,
     const std::string &path);
 
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, plic_config &value, const std::string &path) {
+void ju_get_opt_field(const nlohmann::json &j, const K &key, plic_state &value, const std::string &path) {
     if (!contains(j, key, path)) {
         return;
     }
@@ -1507,14 +1543,14 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, plic_config &value,
     ju_get_opt_field(jconfig, "girqsrvd"s, value.girqsrvd, new_path);
 }
 
-template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, plic_config &value,
+template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, plic_state &value,
     const std::string &path);
 
-template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key, plic_config &value,
+template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key, plic_state &value,
     const std::string &path);
 
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, htif_config &value, const std::string &path) {
+void ju_get_opt_field(const nlohmann::json &j, const K &key, htif_state &value, const std::string &path) {
     if (!contains(j, key, path)) {
         return;
     }
@@ -1522,15 +1558,15 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, htif_config &value,
     const auto new_path = path + to_string(key) + "/";
     ju_get_opt_field(jconfig, "fromhost"s, value.fromhost, new_path);
     ju_get_opt_field(jconfig, "tohost"s, value.tohost, new_path);
-    ju_get_opt_field(jconfig, "console_getchar"s, value.console_getchar, new_path);
-    ju_get_opt_field(jconfig, "yield_manual"s, value.yield_manual, new_path);
-    ju_get_opt_field(jconfig, "yield_automatic"s, value.yield_automatic, new_path);
+    ju_get_opt_field(jconfig, "ihalt"s, value.ihalt, new_path);
+    ju_get_opt_field(jconfig, "iconsole"s, value.iconsole, new_path);
+    ju_get_opt_field(jconfig, "iyield"s, value.iyield, new_path);
 }
 
-template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, htif_config &value,
+template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, htif_state &value,
     const std::string &path);
 
-template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key, htif_config &value,
+template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key, htif_state &value,
     const std::string &path);
 
 template <typename K>
@@ -1551,7 +1587,7 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
     const std::string &path);
 
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, uarch_processor_config &value, const std::string &path) {
+void ju_get_opt_field(const nlohmann::json &j, const K &key, uarch_registers_state &value, const std::string &path) {
     if (!contains(j, key, path)) {
         return;
     }
@@ -1594,6 +1630,23 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, uarch_processor_con
     ju_get_opt_field(jconfig, "halt_flag"s, value.halt_flag, new_path);
 }
 
+template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, uarch_registers_state &value,
+    const std::string &path);
+
+template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key,
+    uarch_registers_state &value, const std::string &path);
+
+template <typename K>
+void ju_get_opt_field(const nlohmann::json &j, const K &key, uarch_processor_config &value, const std::string &path) {
+    if (!contains(j, key, path)) {
+        return;
+    }
+    const auto &jconfig = j[key];
+    const auto new_path = path + to_string(key) + "/";
+    ju_get_opt_field(jconfig, "registers"s, value.registers, new_path);
+    ju_get_opt_field(jconfig, "backing_store"s, value.backing_store, new_path);
+}
+
 template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, uarch_processor_config &value,
     const std::string &path);
 
@@ -1629,9 +1682,6 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, machine_config &val
     ju_get_opt_field(config, "dtb"s, value.dtb, new_path);
     ju_get_opt_field(config, "flash_drive"s, value.flash_drive, new_path);
     ju_get_opt_field(config, "tlb"s, value.tlb, new_path);
-    ju_get_opt_field(config, "clint"s, value.clint, new_path);
-    ju_get_opt_field(config, "plic"s, value.plic, new_path);
-    ju_get_opt_field(config, "htif"s, value.htif, new_path);
     ju_get_opt_field(config, "virtio"s, value.virtio, new_path);
     ju_get_opt_field(config, "cmio"s, value.cmio, new_path);
     ju_get_opt_field(config, "pmas"s, value.pmas, new_path);
@@ -1801,7 +1851,7 @@ void to_json(nlohmann::json &j, const hash_tree_config &config) {
         {"phtc_size", config.phtc_size}};
 }
 
-void to_json(nlohmann::json &j, const processor_config &config) {
+void to_json(nlohmann::json &j, const registers_state &config) {
     j = nlohmann::json{{"x0", config.x[0]}, {"x1", config.x[1]}, {"x2", config.x[2]}, {"x3", config.x[3]},
         {"x4", config.x[4]}, {"x5", config.x[5]}, {"x6", config.x[6]}, {"x7", config.x[7]}, {"x8", config.x[8]},
         {"x9", config.x[9]}, {"x10", config.x[10]}, {"x11", config.x[11]}, {"x12", config.x[12]}, {"x13", config.x[13]},
@@ -1824,8 +1874,12 @@ void to_json(nlohmann::json &j, const processor_config &config) {
         {"medeleg", config.medeleg}, {"mideleg", config.mideleg}, {"mcounteren", config.mcounteren},
         {"menvcfg", config.menvcfg}, {"stvec", config.stvec}, {"sscratch", config.sscratch}, {"sepc", config.sepc},
         {"scause", config.scause}, {"stval", config.stval}, {"satp", config.satp}, {"scounteren", config.scounteren},
-        {"senvcfg", config.senvcfg}, {"ilrsc", config.ilrsc}, {"iprv", config.iprv}, {"iflags_X", config.iflags_X},
-        {"iflags_Y", config.iflags_Y}, {"iflags_H", config.iflags_H}, {"iunrep", config.iunrep}};
+        {"senvcfg", config.senvcfg}, {"ilrsc", config.ilrsc}, {"iprv", config.iprv}, {"iflags", config.iflags},
+        {"iunrep", config.iunrep}, {"clint", config.clint}, {"plic", config.plic}, {"htif", config.htif}};
+}
+
+void to_json(nlohmann::json &j, const processor_config &config) {
+    j = nlohmann::json{{"registers", config.registers}, {"backing_store", config.backing_store}};
 }
 
 void to_json(nlohmann::json &j, const flash_drive_configs &fs) {
@@ -1887,26 +1941,34 @@ void to_json(nlohmann::json &j, const dtb_config &config) {
     };
 }
 
-void to_json(nlohmann::json &j, const clint_config &config) {
+void to_json(nlohmann::json &j, const iflags_state &config) {
+    j = nlohmann::json{
+        {"X", config.X},
+        {"Y", config.Y},
+        {"H", config.H},
+    };
+}
+
+void to_json(nlohmann::json &j, const clint_state &config) {
     j = nlohmann::json{
         {"mtimecmp", config.mtimecmp},
     };
 }
 
-void to_json(nlohmann::json &j, const plic_config &config) {
+void to_json(nlohmann::json &j, const plic_state &config) {
     j = nlohmann::json{
         {"girqpend", config.girqpend},
         {"girqsrvd", config.girqsrvd},
     };
 }
 
-void to_json(nlohmann::json &j, const htif_config &config) {
+void to_json(nlohmann::json &j, const htif_state &config) {
     j = nlohmann::json{
         {"fromhost", config.fromhost},
         {"tohost", config.tohost},
-        {"console_getchar", config.console_getchar},
-        {"yield_manual", config.yield_manual},
-        {"yield_automatic", config.yield_automatic},
+        {"ihalt", config.ihalt},
+        {"iconsole", config.iconsole},
+        {"iyield", config.iyield},
     };
 }
 
@@ -1917,7 +1979,7 @@ void to_json(nlohmann::json &j, const cmio_config &config) {
     };
 }
 
-void to_json(nlohmann::json &j, const uarch_processor_config &config) {
+void to_json(nlohmann::json &j, const uarch_registers_state &config) {
     j = nlohmann::json{
         {"x0", config.x[0]},
         {"x1", config.x[1]},
@@ -1957,6 +2019,10 @@ void to_json(nlohmann::json &j, const uarch_processor_config &config) {
     };
 }
 
+void to_json(nlohmann::json &j, const uarch_processor_config &config) {
+    j = nlohmann::json{{"registers", config.registers}, {"backing_store", config.backing_store}};
+}
+
 void to_json(nlohmann::json &j, const uarch_config &config) {
     j = nlohmann::json{
         {"processor", config.processor},
@@ -1971,9 +2037,6 @@ void to_json(nlohmann::json &j, const machine_config &config) {
         {"dtb", config.dtb},
         {"flash_drive", config.flash_drive},
         {"tlb", config.tlb},
-        {"clint", config.clint},
-        {"plic", config.plic},
-        {"htif", config.htif},
         {"virtio", config.virtio},
         {"cmio", config.cmio},
         {"pmas", config.pmas},
diff --git a/src/json-util.h b/src/json-util.h
index 2823e0cb7..4f6e9d186 100644
--- a/src/json-util.h
+++ b/src/json-util.h
@@ -307,6 +307,16 @@ template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, not_default_constructible<access_log> &optional,
     const std::string &path = "params/");
 
+/// \brief Attempts to load a registers_state object from a field in a JSON object
+/// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
+/// \param j JSON object to load from
+/// \param key Key to load value from
+/// \param value Object to store value
+/// \param path Path to j
+template <typename K>
+void ju_get_opt_field(const nlohmann::json &j, const K &key, registers_state &value,
+    const std::string &path = "params/");
+
 /// \brief Attempts to load a processor_config object from a field in a JSON object
 /// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
 /// \param j JSON object to load from
@@ -395,32 +405,41 @@ template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, virtio_configs &value,
     const std::string &path = "params/");
 
-/// \brief Attempts to load a clint_config object from a field in a JSON object
+/// \brief Attempts to load a iflags_state object from a field in a JSON object
+/// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
+/// \param j JSON object to load from
+/// \param key Key to load value from
+/// \param value Object to store value
+/// \param path Path to j
+template <typename K>
+void ju_get_opt_field(const nlohmann::json &j, const K &key, iflags_state &value, const std::string &path = "params/");
+
+/// \brief Attempts to load a clint_state object from a field in a JSON object
 /// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
 /// \param j JSON object to load from
 /// \param key Key to load value from
 /// \param value Object to store value
 /// \param path Path to j
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, clint_config &value, const std::string &path = "params/");
+void ju_get_opt_field(const nlohmann::json &j, const K &key, clint_state &value, const std::string &path = "params/");
 
-/// \brief Attempts to load a plic_config object from a field in a JSON object
+/// \brief Attempts to load a plic_state object from a field in a JSON object
 /// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
 /// \param j JSON object to load from
 /// \param key Key to load value from
 /// \param value Object to store value
 /// \param path Path to j
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, plic_config &value, const std::string &path = "params/");
+void ju_get_opt_field(const nlohmann::json &j, const K &key, plic_state &value, const std::string &path = "params/");
 
-/// \brief Attempts to load an htif_config object from a field in a JSON object
+/// \brief Attempts to load an htif_state object from a field in a JSON object
 /// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
 /// \param j JSON object to load from
 /// \param key Key to load value from
 /// \param value Object to store value
 /// \param path Path to j
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, htif_config &value, const std::string &path = "params/");
+void ju_get_opt_field(const nlohmann::json &j, const K &key, htif_state &value, const std::string &path = "params/");
 
 /// \brief Attempts to load a cmio_config object from a field in a JSON object
 /// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
@@ -441,6 +460,16 @@ template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, std::optional<cmio_config> &optional,
     const std::string &path = "params/");
 
+/// \brief Attempts to load an uarch_registers_state object from a field in a JSON object
+/// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
+/// \param j JSON object to load from
+/// \param key Key to load value from
+/// \param value Object to store value
+/// \param path Path to j
+template <typename K>
+void ju_get_opt_field(const nlohmann::json &j, const K &key, uarch_registers_state &value,
+    const std::string &path = "params/");
+
 /// \brief Attempts to load an uarch_processor_config object from a field in a JSON object
 /// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
 /// \param j JSON object to load from
@@ -613,16 +642,19 @@ void to_json(nlohmann::json &j, const access_log &log);
 void to_json(nlohmann::json &j, const backing_store_config &config);
 void to_json(nlohmann::json &j, const backing_store_config_only &config);
 void to_json(nlohmann::json &j, const memory_range_config &config);
+void to_json(nlohmann::json &j, const registers_state &config);
 void to_json(nlohmann::json &j, const processor_config &config);
 void to_json(nlohmann::json &j, const flash_drive_configs &fs);
 void to_json(nlohmann::json &j, const virtio_device_config &config);
 void to_json(nlohmann::json &j, const virtio_configs &vs);
 void to_json(nlohmann::json &j, const ram_config &config);
 void to_json(nlohmann::json &j, const dtb_config &config);
-void to_json(nlohmann::json &j, const clint_config &config);
-void to_json(nlohmann::json &j, const plic_config &config);
-void to_json(nlohmann::json &j, const htif_config &config);
+void to_json(nlohmann::json &j, const iflags_state &config);
+void to_json(nlohmann::json &j, const clint_state &config);
+void to_json(nlohmann::json &j, const plic_state &config);
+void to_json(nlohmann::json &j, const htif_state &config);
 void to_json(nlohmann::json &j, const cmio_config &config);
+void to_json(nlohmann::json &j, const uarch_registers_state &config);
 void to_json(nlohmann::json &j, const uarch_processor_config &config);
 void to_json(nlohmann::json &j, const uarch_config &config);
 void to_json(nlohmann::json &j, const hash_tree_config &config);
@@ -721,6 +753,10 @@ extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &k
     not_default_constructible<access_log> &value, const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key,
     not_default_constructible<access_log> &value, const std::string &base = "params/");
+extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, registers_state &value,
+    const std::string &base = "params/");
+extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, registers_state &value,
+    const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, processor_config &value,
     const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, processor_config &value,
@@ -757,17 +793,21 @@ extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &k
     const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, virtio_configs &value,
     const std::string &base = "params/");
-extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, clint_config &value,
+extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, iflags_state &value,
+    const std::string &base = "params/");
+extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, iflags_state &value,
     const std::string &base = "params/");
-extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, clint_config &value,
+extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, clint_state &value,
     const std::string &base = "params/");
-extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, plic_config &value,
+extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, clint_state &value,
     const std::string &base = "params/");
-extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, plic_config &value,
+extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, plic_state &value,
     const std::string &base = "params/");
-extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, htif_config &value,
+extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, plic_state &value,
     const std::string &base = "params/");
-extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, htif_config &value,
+extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, htif_state &value,
+    const std::string &base = "params/");
+extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, htif_state &value,
     const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, cmio_config &value,
     const std::string &base = "params/");
@@ -777,6 +817,10 @@ extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &k
     const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key,
     std::optional<cmio_config> &value, const std::string &base = "params/");
+extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, uarch_registers_state &value,
+    const std::string &base = "params/");
+extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, uarch_registers_state &value,
+    const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, uarch_processor_config &value,
     const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, uarch_processor_config &value,
diff --git a/src/jsonrpc-discover.json b/src/jsonrpc-discover.json
index 92e710aa1..439f3d98a 100644
--- a/src/jsonrpc-discover.json
+++ b/src/jsonrpc-discover.json
@@ -1003,6 +1003,18 @@
       "ProcessorConfig": {
         "title": "ProcessorConfig",
         "type": "object",
+        "properties": {
+          "registers": {
+            "$ref": "#/components/schemas/RegistersConfig"
+          },
+          "backing_store": {
+            "$ref": "#/components/schemas/BackingStoreConfig"
+          }
+        }
+      },
+      "RegistersConfig": {
+        "title": "RegistersConfig",
+        "type": "object",
         "properties": {
           "x0": {
             "$ref": "#/components/schemas/UnsignedInteger"
@@ -1488,6 +1500,18 @@
       "UarchProcessorConfig": {
         "title": "UarchProcessorConfig",
         "type": "object",
+        "properties": {
+          "registers": {
+            "$ref": "#/components/schemas/UarchRegistersConfig"
+          },
+          "backing_store": {
+            "$ref": "#/components/schemas/BackingStoreConfig"
+          }
+        }
+      },
+      "UarchRegistersConfig": {
+        "title": "UarchRegistersConfig",
+        "type": "object",
         "properties": {
           "x0": {
             "$ref": "#/components/schemas/UnsignedInteger"
diff --git a/src/machine-address-ranges.cpp b/src/machine-address-ranges.cpp
index 43cd29212..d44833c61 100644
--- a/src/machine-address-ranges.cpp
+++ b/src/machine-address-ranges.cpp
@@ -147,7 +147,7 @@ machine_address_ranges::machine_address_ranges(machine_config &c) {
     push_back(make_shadow_state_address_range(throw_invalid_argument),
         register_where{.merkle = true, .interpret = false});
     push_back(make_pmas_address_range(c.pmas), register_where{.merkle = true, .interpret = true});
-    push_back_virtio(c.virtio, c.processor.iunrep);
+    push_back_virtio(c.virtio, c.processor.registers.iunrep);
 
     // Sort indices visible to Merkle tree by the start of corresponding address range
     std::ranges::sort(
diff --git a/src/machine-c-api.h b/src/machine-c-api.h
index 53399a20c..7c46dc703 100644
--- a/src/machine-c-api.h
+++ b/src/machine-c-api.h
@@ -130,7 +130,7 @@ typedef enum cm_cmio_yield_reason {
 
 /// \brief Machine x, f, and control and status registers.
 typedef enum cm_reg {
-    // Processor x registers
+    // Machine x registers
     CM_REG_X0,
     CM_REG_X1,
     CM_REG_X2,
@@ -163,7 +163,7 @@ typedef enum cm_reg {
     CM_REG_X29,
     CM_REG_X30,
     CM_REG_X31,
-    // Processor f registers
+    // Machine f registers
     CM_REG_F0,
     CM_REG_F1,
     CM_REG_F2,
@@ -196,7 +196,7 @@ typedef enum cm_reg {
     CM_REG_F29,
     CM_REG_F30,
     CM_REG_F31,
-    // Processor CSRs
+    // Machine CSRs
     CM_REG_PC,
     CM_REG_FCSR,
     CM_REG_MVENDORID,
diff --git a/src/machine-config.h b/src/machine-config.h
index e8b058ca5..3b8e967b5 100644
--- a/src/machine-config.h
+++ b/src/machine-config.h
@@ -24,6 +24,8 @@
 #include <vector>
 
 #include "riscv-constants.h"
+#include "shadow-state.h"
+#include "shadow-uarch-state.h"
 
 namespace cartesi {
 
@@ -34,49 +36,6 @@ enum machine_config_constants {
     VIRTIO_HOSTFWD_MAX = 16, ///< Maximum number of virtio net user host forward ports
 };
 
-/// \brief Processor state config
-struct processor_config final {
-    std::array<uint64_t, X_REG_COUNT> x{REG_X0, REG_X1, REG_X2, REG_X3, REG_X4, REG_X5, REG_X6, REG_X7, REG_X8, REG_X9,
-        REG_X10, REG_X11, REG_X12, REG_X13, REG_X14, REG_X15, REG_X16, REG_X17, REG_X18, REG_X19, REG_X20, REG_X21,
-        REG_X22, REG_X23, REG_X24, REG_X25, REG_X26, REG_X27, REG_X28, REG_X29, REG_X30,
-        REG_X31};                               ///< Value of general-purpose registers
-    std::array<uint64_t, F_REG_COUNT> f{};      ///< Value of floating-point registers
-    uint64_t pc{PC_INIT};                       ///< Value of pc
-    uint64_t fcsr{FCSR_INIT};                   ///< Value of fcsr CSR
-    uint64_t mvendorid{MVENDORID_INIT};         ///< Value of mvendorid CSR
-    uint64_t marchid{MARCHID_INIT};             ///< Value of marchid CSR
-    uint64_t mimpid{MIMPID_INIT};               ///< Value of mimpid CSR
-    uint64_t mcycle{MCYCLE_INIT};               ///< Value of mcycle CSR
-    uint64_t icycleinstret{ICYCLEINSTRET_INIT}; ///< Value of icycleinstret CSR
-    uint64_t mstatus{MSTATUS_INIT};             ///< Value of mstatus CSR
-    uint64_t mtvec{MTVEC_INIT};                 ///< Value of mtvec CSR
-    uint64_t mscratch{MSCRATCH_INIT};           ///< Value of mscratch CSR
-    uint64_t mepc{MEPC_INIT};                   ///< Value of mepc CSR
-    uint64_t mcause{MCAUSE_INIT};               ///< Value of mcause CSR
-    uint64_t mtval{MTVAL_INIT};                 ///< Value of mtval CSR
-    uint64_t misa{MISA_INIT};                   ///< Value of misa CSR
-    uint64_t mie{MIE_INIT};                     ///< Value of mie CSR
-    uint64_t mip{MIP_INIT};                     ///< Value of mip CSR
-    uint64_t medeleg{MEDELEG_INIT};             ///< Value of medeleg CSR
-    uint64_t mideleg{MIDELEG_INIT};             ///< Value of mideleg CSR
-    uint64_t mcounteren{MCOUNTEREN_INIT};       ///< Value of mcounteren CSR
-    uint64_t menvcfg{MENVCFG_INIT};             ///< Value of menvcfg CSR
-    uint64_t stvec{STVEC_INIT};                 ///< Value of stvec CSR
-    uint64_t sscratch{SSCRATCH_INIT};           ///< Value of sscratch CSR
-    uint64_t sepc{SEPC_INIT};                   ///< Value of sepc CSR
-    uint64_t scause{SCAUSE_INIT};               ///< Value of scause CSR
-    uint64_t stval{STVAL_INIT};                 ///< Value of stval CSR
-    uint64_t satp{SATP_INIT};                   ///< Value of satp CSR
-    uint64_t scounteren{SCOUNTEREN_INIT};       ///< Value of scounteren CSR
-    uint64_t senvcfg{SENVCFG_INIT};             ///< Value of senvcfg CSR
-    uint64_t ilrsc{ILRSC_INIT};                 ///< Value of ilrsc CSR
-    uint64_t iprv{IPRV_INIT};                   ///< Value of iprv CSR
-    uint64_t iflags_X{IFLAGS_X_INIT};           ///< Value of iflags_X CSR
-    uint64_t iflags_Y{IFLAGS_Y_INIT};           ///< Value of iflags_Y CSR
-    uint64_t iflags_H{IFLAGS_H_INIT};           ///< Value of iflags_H CSR
-    uint64_t iunrep{IUNREP_INIT};               ///< Value of iunrep CSR
-};
-
 /// \brief Backing store config
 struct backing_store_config final {
     bool shared{false};        ///< Should changes be reflected in backing store?
@@ -85,6 +44,12 @@ struct backing_store_config final {
     std::string dht_filename;  ///< Backing store for corresponding dense hash-tree
 };
 
+/// \brief Processor state config
+struct processor_config final {
+    registers_state registers;
+    backing_store_config backing_store;
+};
+
 /// \brief Config with only backing store config field
 struct backing_store_config_only final {
     backing_store_config backing_store;
@@ -120,26 +85,6 @@ using flash_drive_configs = std::vector<memory_range_config>;
 /// \brief TLB device state config
 using tlb_config = backing_store_config_only;
 
-/// \brief CLINT device state config
-struct clint_config final {
-    uint64_t mtimecmp{MTIMECMP_INIT}; ///< Value of mtimecmp CSR
-};
-
-/// \brief PLIC device state config
-struct plic_config final {
-    uint64_t girqpend{GIRQPEND_INIT}; ///< Value of girqpend CSR
-    uint64_t girqsrvd{GIRQSRVD_INIT}; ///< Value of girqsrvd CSR
-};
-
-/// \brief HTIF device state config
-struct htif_config final {
-    uint64_t fromhost{FROMHOST_INIT}; ///< Value of fromhost CSR
-    uint64_t tohost{TOHOST_INIT};     ///< Value of tohost CSR
-    bool console_getchar{false};      ///< Make console getchar available?
-    bool yield_manual{true};          ///< Make yield manual available?
-    bool yield_automatic{true};       ///< Make yield automatic available?
-};
-
 /// \brief VirtIO console device state config
 struct virtio_console_config final {};
 
@@ -193,12 +138,10 @@ using pmas_config = backing_store_config_only;
 /// \brief Uarch RAM config
 using uarch_ram_config = backing_store_config_only;
 
-/// \brief Uarch processor config
+/// \brief Uarch processor state config
 struct uarch_processor_config final {
-    std::array<uint64_t, UARCH_X_REG_COUNT> x{}; ///< Value of general-purpose registers
-    uint64_t pc{UARCH_PC_INIT};                  ///< Value of pc
-    uint64_t cycle{UARCH_CYCLE_INIT};            ///< Value of ucycle counter
-    uint64_t halt_flag{};
+    uarch_registers_state registers; ///< Uarch registers
+    backing_store_config backing_store;
 };
 
 /// \brief Uarch config
@@ -224,9 +167,6 @@ struct machine_config final {
     dtb_config dtb{};                ///< Device Tree config
     flash_drive_configs flash_drive; ///< Flash drives config
     tlb_config tlb{};                ///< Translation Look-aside Buffer config
-    clint_config clint{};            ///< Core-Local Interruptor config
-    plic_config plic{};              ///< Platform-Level Interrupt Controller config
-    htif_config htif{};              ///< Host-Target config InterFace config
     virtio_configs virtio;           ///< VirtIO devices config
     cmio_config cmio{};              ///< Cartesi Machine IO config
     pmas_config pmas{};              ///< Physical Memory Attributes config
diff --git a/src/machine-reg.h b/src/machine-reg.h
index d8865c4a9..736f9f98e 100644
--- a/src/machine-reg.h
+++ b/src/machine-reg.h
@@ -27,7 +27,6 @@ namespace cartesi {
 
 /// \brief List of machine registers
 enum class machine_reg : uint64_t {
-    // Processor x registers
     x0 = static_cast<uint64_t>(shadow_state_what::x0),
     x1 = static_cast<uint64_t>(shadow_state_what::x1),
     x2 = static_cast<uint64_t>(shadow_state_what::x2),
diff --git a/src/machine-state.h b/src/machine-state.h
index 707e96988..4c77c4649 100644
--- a/src/machine-state.h
+++ b/src/machine-state.h
@@ -26,6 +26,7 @@
 
 #include "address-range.h"
 #include "riscv-constants.h"
+#include "shadow-state.h"
 #include "tlb.h"
 
 namespace cartesi {
@@ -33,7 +34,7 @@ namespace cartesi {
 /// \brief Machine state.
 /// \details The machine_state structure contains the entire
 /// state of a Cartesi machine.
-struct machine_state {
+struct machine_state final {
     machine_state() = default;
     ~machine_state() = default;
 
@@ -43,76 +44,13 @@ struct machine_state {
     machine_state &operator=(const machine_state &other) = delete;
     machine_state &operator=(machine_state &&other) = delete;
 
-    // The following state fields are very hot,
-    // and are carefully ordered to have better data locality in the interpreter loop.
-    // The X registers are the very first to optimize access of registers in the interpreter.
-    std::array<uint64_t, X_REG_COUNT> x{}; ///< Register file
-    uint64_t mcycle{};                     ///< CSR mcycle.
-    uint64_t pc{};                         ///< Program counter.
-    uint64_t fcsr{};                       ///< CSR fcsr.
-    std::array<uint64_t, F_REG_COUNT> f{}; ///< Floating-point register file.
+    // Shadow region.
+    registers_state registers; ///< Registers
 
-    uint64_t iprv{}; ///< Privilege level (Cartesi-specific).
-
-    uint64_t mstatus{};  ///< CSR mstatus.
-    uint64_t mtvec{};    ///< CSR mtvec.
-    uint64_t mscratch{}; ///< CSR mscratch.
-    uint64_t mepc{};     ///< CSR mepc.
-    uint64_t mcause{};   ///< CSR mcause.
-    uint64_t mtval{};    ///< CSR mtval.
-    uint64_t misa{};     ///< CSR misa.
-
-    uint64_t mie{};        ///< CSR mie.
-    uint64_t mip{};        ///< CSR mip.
-    uint64_t medeleg{};    ///< CSR medeleg.
-    uint64_t mideleg{};    ///< CSR mideleg.
-    uint64_t mcounteren{}; ///< CSR mcounteren.
-    uint64_t menvcfg{};    ///< CSR menvcfg.
-
-    uint64_t stvec{};      ///< CSR stvec.
-    uint64_t sscratch{};   ///< CSR sscratch.
-    uint64_t sepc{};       ///< CSR sepc.
-    uint64_t scause{};     ///< CSR scause.
-    uint64_t stval{};      ///< CSR stval.
-    uint64_t satp{};       ///< CSR satp.
-    uint64_t scounteren{}; ///< CSR scounteren.
-    uint64_t senvcfg{};    ///< CSR senvcfg.
-
-    // Cartesi-specific state
-    uint64_t ilrsc{};         ///< For LR/SC instructions (Cartesi-specific).
-    uint64_t icycleinstret{}; ///< CSR icycleinstret (Cartesi-specific).
-    struct {
-        uint64_t X{}; ///< CPU has yielded with automatic reset (Cartesi-specific).
-        uint64_t Y{}; ///< CPU has yielded with manual reset (Cartesi-specific).
-        uint64_t H{}; ///< CPU has been permanently halted (Cartesi-specific).
-    } iflags;
-    uint64_t iunrep{}; ///< Unreproducible mode (Cartesi-specific).
-
-    /// \brief CLINT state
-    struct {
-        uint64_t mtimecmp{}; ///< CSR mtimecmp.
-    } clint;
-
-    /// \brief PLIC state
-    struct {
-        uint64_t girqpend{}; ///< CSR girqpend (global interrupts pending).
-        uint64_t girqsrvd{}; ///< CSR girqsrvd (global interrupts served).
-    } plic;
-
-    /// \brief TLB state
-    tlb_state tlb{};
-
-    /// \brief HTIF state
-    struct {
-        uint64_t tohost{};   ///< CSR tohost.
-        uint64_t fromhost{}; ///< CSR fromhost.
-        uint64_t ihalt{};    ///< CSR ihalt.
-        uint64_t iconsole{}; ///< CSR iconsole.
-        uint64_t iyield{};   ///< CSR iyield.
-    } htif;
-
-    /// Soft yield
-    bool soft_yield{};
+    // Penumbra region, the fields below are not stored in the backing file,
+    // it's only visible in host resident memory during runtime.
+    tlb_state tlb{};   ///< TLB state
+    bool soft_yield{}; ///< Whether soft yield is enabled
 };
 
 } // namespace cartesi
diff --git a/src/machine.cpp b/src/machine.cpp
index bb2900593..2b5546cda 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -83,16 +83,16 @@ using namespace std::string_literals;
 
 void machine::init_uarch_processor(const uarch_config &c) {
     using reg = machine_reg;
-    write_reg(reg::uarch_pc, c.processor.pc);
-    write_reg(reg::uarch_cycle, c.processor.cycle);
-    write_reg(reg::uarch_halt_flag, c.processor.halt_flag);
+    write_reg(reg::uarch_pc, c.processor.registers.pc);
+    write_reg(reg::uarch_cycle, c.processor.registers.cycle);
+    write_reg(reg::uarch_halt_flag, c.processor.registers.halt_flag);
     // General purpose registers
     for (int i = 1; i < UARCH_X_REG_COUNT; i++) {
-        write_reg(machine_reg_enum(reg::uarch_x0, i), c.processor.x[i]);
+        write_reg(machine_reg_enum(reg::uarch_x0, i), c.processor.registers.x[i]);
     }
 }
 
-void machine::init_processor(processor_config &p, const machine_runtime_config &r) {
+void machine::init_registers(registers_state &p, const machine_runtime_config &r) {
 
     if (p.marchid == UINT64_C(-1)) {
         p.marchid = MARCHID_INIT;
@@ -156,34 +156,24 @@ void machine::init_processor(processor_config &p, const machine_runtime_config &
     write_reg(reg::senvcfg, p.senvcfg);
     write_reg(reg::ilrsc, p.ilrsc);
     write_reg(reg::iprv, p.iprv);
-    write_reg(reg::iflags_X, p.iflags_X);
-    write_reg(reg::iflags_Y, p.iflags_Y);
-    write_reg(reg::iflags_H, p.iflags_H);
+    write_reg(reg::iflags_X, p.iflags.X);
+    write_reg(reg::iflags_Y, p.iflags.Y);
+    write_reg(reg::iflags_H, p.iflags.H);
     write_reg(reg::iunrep, p.iunrep);
-}
 
-void machine::init_htif_registers(const htif_config &h) {
-    // Copy HTIF state to from config to machine
-    write_reg(reg::htif_tohost, h.tohost);
-    write_reg(reg::htif_fromhost, h.fromhost);
-    // Only command in halt device is command 0 and it is always available
-    const uint64_t htif_ihalt = static_cast<uint64_t>(true) << HTIF_HALT_CMD_HALT;
-    write_reg(reg::htif_ihalt, htif_ihalt);
-    const uint64_t htif_iconsole = static_cast<uint64_t>(h.console_getchar) << HTIF_CONSOLE_CMD_GETCHAR |
-        static_cast<uint64_t>(true) << HTIF_CONSOLE_CMD_PUTCHAR;
-    write_reg(reg::htif_iconsole, htif_iconsole);
-    const uint64_t htif_iyield = static_cast<uint64_t>(h.yield_manual) << HTIF_YIELD_CMD_MANUAL |
-        static_cast<uint64_t>(h.yield_automatic) << HTIF_YIELD_CMD_AUTOMATIC;
-    write_reg(reg::htif_iyield, htif_iyield);
-}
+    // HTIF
+    write_reg(reg::htif_tohost, p.htif.tohost);
+    write_reg(reg::htif_fromhost, p.htif.fromhost);
+    write_reg(reg::htif_ihalt, p.htif.ihalt);
+    write_reg(reg::htif_iconsole, p.htif.iconsole);
+    write_reg(reg::htif_iyield, p.htif.iyield);
 
-void machine::init_clint_registers(const clint_config &c) {
-    write_reg(reg::clint_mtimecmp, c.mtimecmp);
-}
+    // CLINT
+    write_reg(reg::clint_mtimecmp, p.clint.mtimecmp);
 
-void machine::init_plic_registers(const plic_config &p) {
-    write_reg(reg::plic_girqpend, p.girqpend);
-    write_reg(reg::plic_girqsrvd, p.girqsrvd);
+    // PLIC
+    write_reg(reg::plic_girqpend, p.plic.girqpend);
+    write_reg(reg::plic_girqsrvd, p.plic.girqsrvd);
 }
 
 void machine::init_pmas_contents(const pmas_config &config) {
@@ -237,24 +227,21 @@ void machine::init_dtb_contents(const machine_config &config) {
 // NOLINTNEXTLINE(hicpp-move-const-arg,performance-move-const-arg)
 machine::machine(machine_config c, machine_runtime_config r) : m_c{std::move(c)}, m_r{std::move(r)}, m_ars{m_c} {
     init_uarch_processor(m_c.uarch);
-    init_processor(m_c.processor, m_r);
-    init_htif_registers(m_c.htif);
-    init_clint_registers(m_c.clint);
-    init_plic_registers(m_c.plic);
+    init_registers(m_c.processor.registers, m_r);
     m_s.soft_yield = m_r.soft_yield;
     init_pmas_contents(m_c.pmas);
     init_tlb_contents(m_c.tlb);
     init_dtb_contents(m_c);
-    init_tty(m_c.htif, m_r.htif, m_c.processor.iunrep);
+    init_tty(m_c.processor.registers.htif, m_r.htif, m_c.processor.registers.iunrep);
     // Disable SIGPIPE handler, because this signal can be raised and terminate the emulator process
     // when calling write() on closed file descriptors.
     // This can happen with the stdout console file descriptors or network file descriptors.
     os_disable_sigpipe();
 }
 
-void machine::init_tty(const htif_config &h, const htif_runtime_config &r, uint64_t iunrep) const {
+void machine::init_tty(const htif_state &h, const htif_runtime_config &r, uint64_t iunrep) const {
     // Initialize TTY if console input is enabled
-    if (h.console_getchar || has_virtio_console()) {
+    if ((h.iconsole & HTIF_CONSOLE_CMD_GETCHAR_MASK) != 0 || has_virtio_console()) {
         if (iunrep == 0) {
             throw std::invalid_argument{"TTY stdin is only supported in unreproducible machines"};
         }
@@ -323,7 +310,7 @@ bool machine::has_virtio_console() const {
 }
 
 bool machine::has_htif_console() const {
-    return static_cast<bool>(read_reg(reg::htif_iconsole) & (1 << HTIF_CONSOLE_CMD_GETCHAR));
+    return static_cast<bool>(read_reg(reg::htif_iconsole) & HTIF_CONSOLE_CMD_GETCHAR);
 }
 
 /// \brief Returns copy of initialization config.
@@ -354,68 +341,67 @@ machine_config machine::get_serialization_config() const {
     }
     // Initialize with copy of original config
     machine_config c = m_c;
-    // Copy current processor state to config
+    // Copy current registers state to config
     for (int i = 1; i < X_REG_COUNT; ++i) {
-        c.processor.x[i] = read_reg(machine_reg_enum(reg::x0, i));
+        c.processor.registers.x[i] = read_reg(machine_reg_enum(reg::x0, i));
     }
     for (int i = 0; i < F_REG_COUNT; ++i) {
-        c.processor.f[i] = read_reg(machine_reg_enum(reg::f0, i));
-    }
-    c.processor.pc = read_reg(reg::pc);
-    c.processor.fcsr = read_reg(reg::fcsr);
-    c.processor.mvendorid = read_reg(reg::mvendorid);
-    c.processor.marchid = read_reg(reg::marchid);
-    c.processor.mimpid = read_reg(reg::mimpid);
-    c.processor.mcycle = read_reg(reg::mcycle);
-    c.processor.icycleinstret = read_reg(reg::icycleinstret);
-    c.processor.mstatus = read_reg(reg::mstatus);
-    c.processor.mtvec = read_reg(reg::mtvec);
-    c.processor.mscratch = read_reg(reg::mscratch);
-    c.processor.mepc = read_reg(reg::mepc);
-    c.processor.mcause = read_reg(reg::mcause);
-    c.processor.mtval = read_reg(reg::mtval);
-    c.processor.misa = read_reg(reg::misa);
-    c.processor.mie = read_reg(reg::mie);
-    c.processor.mip = read_reg(reg::mip);
-    c.processor.medeleg = read_reg(reg::medeleg);
-    c.processor.mideleg = read_reg(reg::mideleg);
-    c.processor.mcounteren = read_reg(reg::mcounteren);
-    c.processor.menvcfg = read_reg(reg::menvcfg);
-    c.processor.stvec = read_reg(reg::stvec);
-    c.processor.sscratch = read_reg(reg::sscratch);
-    c.processor.sepc = read_reg(reg::sepc);
-    c.processor.scause = read_reg(reg::scause);
-    c.processor.stval = read_reg(reg::stval);
-    c.processor.satp = read_reg(reg::satp);
-    c.processor.scounteren = read_reg(reg::scounteren);
-    c.processor.senvcfg = read_reg(reg::senvcfg);
-    c.processor.ilrsc = read_reg(reg::ilrsc);
-    c.processor.iprv = read_reg(reg::iprv);
-    c.processor.iflags_X = read_reg(reg::iflags_X);
-    c.processor.iflags_Y = read_reg(reg::iflags_Y);
-    c.processor.iflags_H = read_reg(reg::iflags_H);
-    c.processor.iunrep = read_reg(reg::iunrep);
+        c.processor.registers.f[i] = read_reg(machine_reg_enum(reg::f0, i));
+    }
+    c.processor.registers.pc = read_reg(reg::pc);
+    c.processor.registers.fcsr = read_reg(reg::fcsr);
+    c.processor.registers.mvendorid = read_reg(reg::mvendorid);
+    c.processor.registers.marchid = read_reg(reg::marchid);
+    c.processor.registers.mimpid = read_reg(reg::mimpid);
+    c.processor.registers.mcycle = read_reg(reg::mcycle);
+    c.processor.registers.icycleinstret = read_reg(reg::icycleinstret);
+    c.processor.registers.mstatus = read_reg(reg::mstatus);
+    c.processor.registers.mtvec = read_reg(reg::mtvec);
+    c.processor.registers.mscratch = read_reg(reg::mscratch);
+    c.processor.registers.mepc = read_reg(reg::mepc);
+    c.processor.registers.mcause = read_reg(reg::mcause);
+    c.processor.registers.mtval = read_reg(reg::mtval);
+    c.processor.registers.misa = read_reg(reg::misa);
+    c.processor.registers.mie = read_reg(reg::mie);
+    c.processor.registers.mip = read_reg(reg::mip);
+    c.processor.registers.medeleg = read_reg(reg::medeleg);
+    c.processor.registers.mideleg = read_reg(reg::mideleg);
+    c.processor.registers.mcounteren = read_reg(reg::mcounteren);
+    c.processor.registers.menvcfg = read_reg(reg::menvcfg);
+    c.processor.registers.stvec = read_reg(reg::stvec);
+    c.processor.registers.sscratch = read_reg(reg::sscratch);
+    c.processor.registers.sepc = read_reg(reg::sepc);
+    c.processor.registers.scause = read_reg(reg::scause);
+    c.processor.registers.stval = read_reg(reg::stval);
+    c.processor.registers.satp = read_reg(reg::satp);
+    c.processor.registers.scounteren = read_reg(reg::scounteren);
+    c.processor.registers.senvcfg = read_reg(reg::senvcfg);
+    c.processor.registers.ilrsc = read_reg(reg::ilrsc);
+    c.processor.registers.iprv = read_reg(reg::iprv);
+    c.processor.registers.iflags.X = read_reg(reg::iflags_X);
+    c.processor.registers.iflags.Y = read_reg(reg::iflags_Y);
+    c.processor.registers.iflags.H = read_reg(reg::iflags_H);
+    c.processor.registers.iunrep = read_reg(reg::iunrep);
     // Copy current CLINT state to config
-    c.clint.mtimecmp = read_reg(reg::clint_mtimecmp);
+    c.processor.registers.clint.mtimecmp = read_reg(reg::clint_mtimecmp);
     // Copy current PLIC state to config
-    c.plic.girqpend = read_reg(reg::plic_girqpend);
-    c.plic.girqsrvd = read_reg(reg::plic_girqsrvd);
+    c.processor.registers.plic.girqpend = read_reg(reg::plic_girqpend);
+    c.processor.registers.plic.girqsrvd = read_reg(reg::plic_girqsrvd);
     // Copy current HTIF state to config
-    c.htif.tohost = read_reg(reg::htif_tohost);
-    c.htif.fromhost = read_reg(reg::htif_fromhost);
-    // c.htif.halt = read_reg(reg::htif_ihalt); // hard-coded to true
-    c.htif.console_getchar = static_cast<bool>(read_reg(reg::htif_iconsole) & (1 << HTIF_CONSOLE_CMD_GETCHAR));
-    c.htif.yield_manual = static_cast<bool>(read_reg(reg::htif_iyield) & (1 << HTIF_YIELD_CMD_MANUAL));
-    c.htif.yield_automatic = static_cast<bool>(read_reg(reg::htif_iyield) & (1 << HTIF_YIELD_CMD_AUTOMATIC));
+    c.processor.registers.htif.tohost = read_reg(reg::htif_tohost);
+    c.processor.registers.htif.fromhost = read_reg(reg::htif_fromhost);
+    c.processor.registers.htif.ihalt = read_reg(reg::htif_ihalt);
+    c.processor.registers.htif.iconsole = read_reg(reg::htif_iconsole);
+    c.processor.registers.htif.iyield = read_reg(reg::htif_iyield);
     // Ensure we don't mess with DTB by writing the original bootargs
     // over the potentially modified memory region we serialize
     c.dtb.bootargs.clear();
     // Copy current uarch state to config
-    c.uarch.processor.cycle = read_reg(reg::uarch_cycle);
-    c.uarch.processor.halt_flag = read_reg(reg::uarch_halt_flag);
-    c.uarch.processor.pc = read_reg(reg::uarch_pc);
+    c.uarch.processor.registers.cycle = read_reg(reg::uarch_cycle);
+    c.uarch.processor.registers.halt_flag = read_reg(reg::uarch_halt_flag);
+    c.uarch.processor.registers.pc = read_reg(reg::uarch_pc);
     for (int i = 1; i < UARCH_X_REG_COUNT; i++) {
-        c.uarch.processor.x[i] = read_reg(machine_reg_enum(reg::uarch_x0, i));
+        c.uarch.processor.registers.x[i] = read_reg(machine_reg_enum(reg::uarch_x0, i));
     }
     // Remove backing filenames from serialization
     // (they will be ignored by save and load for security reasons)
@@ -665,7 +651,7 @@ void machine::dump_stats() {
 
 machine::~machine() {
     // Cleanup TTY if console input was enabled
-    if (m_c.htif.console_getchar || has_virtio_console()) {
+    if ((m_c.processor.registers.htif.iconsole & HTIF_CONSOLE_CMD_GETCHAR_MASK) != 0 || has_virtio_console()) {
         os_close_tty();
     }
     dump_insn_hist();
@@ -676,137 +662,137 @@ uint64_t machine::read_reg(reg r) const {
     using reg = machine_reg;
     switch (r) {
         case reg::x0:
-            return m_s.x[0];
+            return m_s.registers.x[0];
         case reg::x1:
-            return m_s.x[1];
+            return m_s.registers.x[1];
         case reg::x2:
-            return m_s.x[2];
+            return m_s.registers.x[2];
         case reg::x3:
-            return m_s.x[3];
+            return m_s.registers.x[3];
         case reg::x4:
-            return m_s.x[4];
+            return m_s.registers.x[4];
         case reg::x5:
-            return m_s.x[5];
+            return m_s.registers.x[5];
         case reg::x6:
-            return m_s.x[6];
+            return m_s.registers.x[6];
         case reg::x7:
-            return m_s.x[7];
+            return m_s.registers.x[7];
         case reg::x8:
-            return m_s.x[8];
+            return m_s.registers.x[8];
         case reg::x9:
-            return m_s.x[9];
+            return m_s.registers.x[9];
         case reg::x10:
-            return m_s.x[10];
+            return m_s.registers.x[10];
         case reg::x11:
-            return m_s.x[11];
+            return m_s.registers.x[11];
         case reg::x12:
-            return m_s.x[12];
+            return m_s.registers.x[12];
         case reg::x13:
-            return m_s.x[13];
+            return m_s.registers.x[13];
         case reg::x14:
-            return m_s.x[14];
+            return m_s.registers.x[14];
         case reg::x15:
-            return m_s.x[15];
+            return m_s.registers.x[15];
         case reg::x16:
-            return m_s.x[16];
+            return m_s.registers.x[16];
         case reg::x17:
-            return m_s.x[17];
+            return m_s.registers.x[17];
         case reg::x18:
-            return m_s.x[18];
+            return m_s.registers.x[18];
         case reg::x19:
-            return m_s.x[19];
+            return m_s.registers.x[19];
         case reg::x20:
-            return m_s.x[20];
+            return m_s.registers.x[20];
         case reg::x21:
-            return m_s.x[21];
+            return m_s.registers.x[21];
         case reg::x22:
-            return m_s.x[22];
+            return m_s.registers.x[22];
         case reg::x23:
-            return m_s.x[23];
+            return m_s.registers.x[23];
         case reg::x24:
-            return m_s.x[24];
+            return m_s.registers.x[24];
         case reg::x25:
-            return m_s.x[25];
+            return m_s.registers.x[25];
         case reg::x26:
-            return m_s.x[26];
+            return m_s.registers.x[26];
         case reg::x27:
-            return m_s.x[27];
+            return m_s.registers.x[27];
         case reg::x28:
-            return m_s.x[28];
+            return m_s.registers.x[28];
         case reg::x29:
-            return m_s.x[29];
+            return m_s.registers.x[29];
         case reg::x30:
-            return m_s.x[30];
+            return m_s.registers.x[30];
         case reg::x31:
-            return m_s.x[31];
+            return m_s.registers.x[31];
         case reg::f0:
-            return m_s.f[0];
+            return m_s.registers.f[0];
         case reg::f1:
-            return m_s.f[1];
+            return m_s.registers.f[1];
         case reg::f2:
-            return m_s.f[2];
+            return m_s.registers.f[2];
         case reg::f3:
-            return m_s.f[3];
+            return m_s.registers.f[3];
         case reg::f4:
-            return m_s.f[4];
+            return m_s.registers.f[4];
         case reg::f5:
-            return m_s.f[5];
+            return m_s.registers.f[5];
         case reg::f6:
-            return m_s.f[6];
+            return m_s.registers.f[6];
         case reg::f7:
-            return m_s.f[7];
+            return m_s.registers.f[7];
         case reg::f8:
-            return m_s.f[8];
+            return m_s.registers.f[8];
         case reg::f9:
-            return m_s.f[9];
+            return m_s.registers.f[9];
         case reg::f10:
-            return m_s.f[10];
+            return m_s.registers.f[10];
         case reg::f11:
-            return m_s.f[11];
+            return m_s.registers.f[11];
         case reg::f12:
-            return m_s.f[12];
+            return m_s.registers.f[12];
         case reg::f13:
-            return m_s.f[13];
+            return m_s.registers.f[13];
         case reg::f14:
-            return m_s.f[14];
+            return m_s.registers.f[14];
         case reg::f15:
-            return m_s.f[15];
+            return m_s.registers.f[15];
         case reg::f16:
-            return m_s.f[16];
+            return m_s.registers.f[16];
         case reg::f17:
-            return m_s.f[17];
+            return m_s.registers.f[17];
         case reg::f18:
-            return m_s.f[18];
+            return m_s.registers.f[18];
         case reg::f19:
-            return m_s.f[19];
+            return m_s.registers.f[19];
         case reg::f20:
-            return m_s.f[20];
+            return m_s.registers.f[20];
         case reg::f21:
-            return m_s.f[21];
+            return m_s.registers.f[21];
         case reg::f22:
-            return m_s.f[22];
+            return m_s.registers.f[22];
         case reg::f23:
-            return m_s.f[23];
+            return m_s.registers.f[23];
         case reg::f24:
-            return m_s.f[24];
+            return m_s.registers.f[24];
         case reg::f25:
-            return m_s.f[25];
+            return m_s.registers.f[25];
         case reg::f26:
-            return m_s.f[26];
+            return m_s.registers.f[26];
         case reg::f27:
-            return m_s.f[27];
+            return m_s.registers.f[27];
         case reg::f28:
-            return m_s.f[28];
+            return m_s.registers.f[28];
         case reg::f29:
-            return m_s.f[29];
+            return m_s.registers.f[29];
         case reg::f30:
-            return m_s.f[30];
+            return m_s.registers.f[30];
         case reg::f31:
-            return m_s.f[31];
+            return m_s.registers.f[31];
         case reg::pc:
-            return m_s.pc;
+            return m_s.registers.pc;
         case reg::fcsr:
-            return m_s.fcsr;
+            return m_s.registers.fcsr;
         case reg::mvendorid:
             return MVENDORID_INIT;
         case reg::marchid:
@@ -814,165 +800,165 @@ uint64_t machine::read_reg(reg r) const {
         case reg::mimpid:
             return MIMPID_INIT;
         case reg::mcycle:
-            return m_s.mcycle;
+            return m_s.registers.mcycle;
         case reg::icycleinstret:
-            return m_s.icycleinstret;
+            return m_s.registers.icycleinstret;
         case reg::mstatus:
-            return m_s.mstatus;
+            return m_s.registers.mstatus;
         case reg::mtvec:
-            return m_s.mtvec;
+            return m_s.registers.mtvec;
         case reg::mscratch:
-            return m_s.mscratch;
+            return m_s.registers.mscratch;
         case reg::mepc:
-            return m_s.mepc;
+            return m_s.registers.mepc;
         case reg::mcause:
-            return m_s.mcause;
+            return m_s.registers.mcause;
         case reg::mtval:
-            return m_s.mtval;
+            return m_s.registers.mtval;
         case reg::misa:
-            return m_s.misa;
+            return m_s.registers.misa;
         case reg::mie:
-            return m_s.mie;
+            return m_s.registers.mie;
         case reg::mip:
-            return m_s.mip;
+            return m_s.registers.mip;
         case reg::medeleg:
-            return m_s.medeleg;
+            return m_s.registers.medeleg;
         case reg::mideleg:
-            return m_s.mideleg;
+            return m_s.registers.mideleg;
         case reg::mcounteren:
-            return m_s.mcounteren;
+            return m_s.registers.mcounteren;
         case reg::menvcfg:
-            return m_s.menvcfg;
+            return m_s.registers.menvcfg;
         case reg::stvec:
-            return m_s.stvec;
+            return m_s.registers.stvec;
         case reg::sscratch:
-            return m_s.sscratch;
+            return m_s.registers.sscratch;
         case reg::sepc:
-            return m_s.sepc;
+            return m_s.registers.sepc;
         case reg::scause:
-            return m_s.scause;
+            return m_s.registers.scause;
         case reg::stval:
-            return m_s.stval;
+            return m_s.registers.stval;
         case reg::satp:
-            return m_s.satp;
+            return m_s.registers.satp;
         case reg::scounteren:
-            return m_s.scounteren;
+            return m_s.registers.scounteren;
         case reg::senvcfg:
-            return m_s.senvcfg;
+            return m_s.registers.senvcfg;
         case reg::ilrsc:
-            return m_s.ilrsc;
+            return m_s.registers.ilrsc;
         case reg::iprv:
-            return m_s.iprv;
+            return m_s.registers.iprv;
         case reg::iflags_X:
-            return m_s.iflags.X;
+            return m_s.registers.iflags.X;
         case reg::iflags_Y:
-            return m_s.iflags.Y;
+            return m_s.registers.iflags.Y;
         case reg::iflags_H:
-            return m_s.iflags.H;
+            return m_s.registers.iflags.H;
         case reg::iunrep:
-            return m_s.iunrep;
+            return m_s.registers.iunrep;
         case reg::clint_mtimecmp:
-            return m_s.clint.mtimecmp;
+            return m_s.registers.clint.mtimecmp;
         case reg::plic_girqpend:
-            return m_s.plic.girqpend;
+            return m_s.registers.plic.girqpend;
         case reg::plic_girqsrvd:
-            return m_s.plic.girqsrvd;
+            return m_s.registers.plic.girqsrvd;
         case reg::htif_tohost:
-            return m_s.htif.tohost;
+            return m_s.registers.htif.tohost;
         case reg::htif_fromhost:
-            return m_s.htif.fromhost;
+            return m_s.registers.htif.fromhost;
         case reg::htif_ihalt:
-            return m_s.htif.ihalt;
+            return m_s.registers.htif.ihalt;
         case reg::htif_iconsole:
-            return m_s.htif.iconsole;
+            return m_s.registers.htif.iconsole;
         case reg::htif_iyield:
-            return m_s.htif.iyield;
+            return m_s.registers.htif.iyield;
         case reg::uarch_x0:
-            return m_us.x[0];
+            return m_us.registers.x[0];
         case reg::uarch_x1:
-            return m_us.x[1];
+            return m_us.registers.x[1];
         case reg::uarch_x2:
-            return m_us.x[2];
+            return m_us.registers.x[2];
         case reg::uarch_x3:
-            return m_us.x[3];
+            return m_us.registers.x[3];
         case reg::uarch_x4:
-            return m_us.x[4];
+            return m_us.registers.x[4];
         case reg::uarch_x5:
-            return m_us.x[5];
+            return m_us.registers.x[5];
         case reg::uarch_x6:
-            return m_us.x[6];
+            return m_us.registers.x[6];
         case reg::uarch_x7:
-            return m_us.x[7];
+            return m_us.registers.x[7];
         case reg::uarch_x8:
-            return m_us.x[8];
+            return m_us.registers.x[8];
         case reg::uarch_x9:
-            return m_us.x[9];
+            return m_us.registers.x[9];
         case reg::uarch_x10:
-            return m_us.x[10];
+            return m_us.registers.x[10];
         case reg::uarch_x11:
-            return m_us.x[11];
+            return m_us.registers.x[11];
         case reg::uarch_x12:
-            return m_us.x[12];
+            return m_us.registers.x[12];
         case reg::uarch_x13:
-            return m_us.x[13];
+            return m_us.registers.x[13];
         case reg::uarch_x14:
-            return m_us.x[14];
+            return m_us.registers.x[14];
         case reg::uarch_x15:
-            return m_us.x[15];
+            return m_us.registers.x[15];
         case reg::uarch_x16:
-            return m_us.x[16];
+            return m_us.registers.x[16];
         case reg::uarch_x17:
-            return m_us.x[17];
+            return m_us.registers.x[17];
         case reg::uarch_x18:
-            return m_us.x[18];
+            return m_us.registers.x[18];
         case reg::uarch_x19:
-            return m_us.x[19];
+            return m_us.registers.x[19];
         case reg::uarch_x20:
-            return m_us.x[20];
+            return m_us.registers.x[20];
         case reg::uarch_x21:
-            return m_us.x[21];
+            return m_us.registers.x[21];
         case reg::uarch_x22:
-            return m_us.x[22];
+            return m_us.registers.x[22];
         case reg::uarch_x23:
-            return m_us.x[23];
+            return m_us.registers.x[23];
         case reg::uarch_x24:
-            return m_us.x[24];
+            return m_us.registers.x[24];
         case reg::uarch_x25:
-            return m_us.x[25];
+            return m_us.registers.x[25];
         case reg::uarch_x26:
-            return m_us.x[26];
+            return m_us.registers.x[26];
         case reg::uarch_x27:
-            return m_us.x[27];
+            return m_us.registers.x[27];
         case reg::uarch_x28:
-            return m_us.x[28];
+            return m_us.registers.x[28];
         case reg::uarch_x29:
-            return m_us.x[29];
+            return m_us.registers.x[29];
         case reg::uarch_x30:
-            return m_us.x[30];
+            return m_us.registers.x[30];
         case reg::uarch_x31:
-            return m_us.x[31];
+            return m_us.registers.x[31];
         case reg::uarch_pc:
-            return m_us.pc;
+            return m_us.registers.pc;
         case reg::uarch_cycle:
-            return m_us.cycle;
+            return m_us.registers.cycle;
         case reg::uarch_halt_flag:
-            return m_us.halt_flag;
+            return m_us.registers.halt_flag;
         case reg::htif_tohost_dev:
-            return HTIF_DEV_FIELD(m_s.htif.tohost);
+            return HTIF_DEV_FIELD(m_s.registers.htif.tohost);
         case reg::htif_tohost_cmd:
-            return HTIF_CMD_FIELD(m_s.htif.tohost);
+            return HTIF_CMD_FIELD(m_s.registers.htif.tohost);
         case reg::htif_tohost_reason:
-            return HTIF_REASON_FIELD(m_s.htif.tohost);
+            return HTIF_REASON_FIELD(m_s.registers.htif.tohost);
         case reg::htif_tohost_data:
-            return HTIF_DATA_FIELD(m_s.htif.tohost);
+            return HTIF_DATA_FIELD(m_s.registers.htif.tohost);
         case reg::htif_fromhost_dev:
-            return HTIF_DEV_FIELD(m_s.htif.fromhost);
+            return HTIF_DEV_FIELD(m_s.registers.htif.fromhost);
         case reg::htif_fromhost_cmd:
-            return HTIF_CMD_FIELD(m_s.htif.fromhost);
+            return HTIF_CMD_FIELD(m_s.registers.htif.fromhost);
         case reg::htif_fromhost_reason:
-            return HTIF_REASON_FIELD(m_s.htif.fromhost);
+            return HTIF_REASON_FIELD(m_s.registers.htif.fromhost);
         case reg::htif_fromhost_data:
-            return HTIF_DATA_FIELD(m_s.htif.fromhost);
+            return HTIF_DATA_FIELD(m_s.registers.htif.fromhost);
         default:
             throw std::invalid_argument{"unknown register"};
             return 0; // never reached
@@ -984,199 +970,199 @@ void machine::write_reg(reg w, uint64_t value) {
         case reg::x0:
             throw std::invalid_argument{"register is read-only"};
         case reg::x1:
-            m_s.x[1] = value;
+            m_s.registers.x[1] = value;
             break;
         case reg::x2:
-            m_s.x[2] = value;
+            m_s.registers.x[2] = value;
             break;
         case reg::x3:
-            m_s.x[3] = value;
+            m_s.registers.x[3] = value;
             break;
         case reg::x4:
-            m_s.x[4] = value;
+            m_s.registers.x[4] = value;
             break;
         case reg::x5:
-            m_s.x[5] = value;
+            m_s.registers.x[5] = value;
             break;
         case reg::x6:
-            m_s.x[6] = value;
+            m_s.registers.x[6] = value;
             break;
         case reg::x7:
-            m_s.x[7] = value;
+            m_s.registers.x[7] = value;
             break;
         case reg::x8:
-            m_s.x[8] = value;
+            m_s.registers.x[8] = value;
             break;
         case reg::x9:
-            m_s.x[9] = value;
+            m_s.registers.x[9] = value;
             break;
         case reg::x10:
-            m_s.x[10] = value;
+            m_s.registers.x[10] = value;
             break;
         case reg::x11:
-            m_s.x[11] = value;
+            m_s.registers.x[11] = value;
             break;
         case reg::x12:
-            m_s.x[12] = value;
+            m_s.registers.x[12] = value;
             break;
         case reg::x13:
-            m_s.x[13] = value;
+            m_s.registers.x[13] = value;
             break;
         case reg::x14:
-            m_s.x[14] = value;
+            m_s.registers.x[14] = value;
             break;
         case reg::x15:
-            m_s.x[15] = value;
+            m_s.registers.x[15] = value;
             break;
         case reg::x16:
-            m_s.x[16] = value;
+            m_s.registers.x[16] = value;
             break;
         case reg::x17:
-            m_s.x[17] = value;
+            m_s.registers.x[17] = value;
             break;
         case reg::x18:
-            m_s.x[18] = value;
+            m_s.registers.x[18] = value;
             break;
         case reg::x19:
-            m_s.x[19] = value;
+            m_s.registers.x[19] = value;
             break;
         case reg::x20:
-            m_s.x[20] = value;
+            m_s.registers.x[20] = value;
             break;
         case reg::x21:
-            m_s.x[21] = value;
+            m_s.registers.x[21] = value;
             break;
         case reg::x22:
-            m_s.x[22] = value;
+            m_s.registers.x[22] = value;
             break;
         case reg::x23:
-            m_s.x[23] = value;
+            m_s.registers.x[23] = value;
             break;
         case reg::x24:
-            m_s.x[24] = value;
+            m_s.registers.x[24] = value;
             break;
         case reg::x25:
-            m_s.x[25] = value;
+            m_s.registers.x[25] = value;
             break;
         case reg::x26:
-            m_s.x[26] = value;
+            m_s.registers.x[26] = value;
             break;
         case reg::x27:
-            m_s.x[27] = value;
+            m_s.registers.x[27] = value;
             break;
         case reg::x28:
-            m_s.x[28] = value;
+            m_s.registers.x[28] = value;
             break;
         case reg::x29:
-            m_s.x[29] = value;
+            m_s.registers.x[29] = value;
             break;
         case reg::x30:
-            m_s.x[30] = value;
+            m_s.registers.x[30] = value;
             break;
         case reg::x31:
-            m_s.x[31] = value;
+            m_s.registers.x[31] = value;
             break;
         case reg::f0:
-            m_s.f[0] = value;
+            m_s.registers.f[0] = value;
             break;
         case reg::f1:
-            m_s.f[1] = value;
+            m_s.registers.f[1] = value;
             break;
         case reg::f2:
-            m_s.f[2] = value;
+            m_s.registers.f[2] = value;
             break;
         case reg::f3:
-            m_s.f[3] = value;
+            m_s.registers.f[3] = value;
             break;
         case reg::f4:
-            m_s.f[4] = value;
+            m_s.registers.f[4] = value;
             break;
         case reg::f5:
-            m_s.f[5] = value;
+            m_s.registers.f[5] = value;
             break;
         case reg::f6:
-            m_s.f[6] = value;
+            m_s.registers.f[6] = value;
             break;
         case reg::f7:
-            m_s.f[7] = value;
+            m_s.registers.f[7] = value;
             break;
         case reg::f8:
-            m_s.f[8] = value;
+            m_s.registers.f[8] = value;
             break;
         case reg::f9:
-            m_s.f[9] = value;
+            m_s.registers.f[9] = value;
             break;
         case reg::f10:
-            m_s.f[10] = value;
+            m_s.registers.f[10] = value;
             break;
         case reg::f11:
-            m_s.f[11] = value;
+            m_s.registers.f[11] = value;
             break;
         case reg::f12:
-            m_s.f[12] = value;
+            m_s.registers.f[12] = value;
             break;
         case reg::f13:
-            m_s.f[13] = value;
+            m_s.registers.f[13] = value;
             break;
         case reg::f14:
-            m_s.f[14] = value;
+            m_s.registers.f[14] = value;
             break;
         case reg::f15:
-            m_s.f[15] = value;
+            m_s.registers.f[15] = value;
             break;
         case reg::f16:
-            m_s.f[16] = value;
+            m_s.registers.f[16] = value;
             break;
         case reg::f17:
-            m_s.f[17] = value;
+            m_s.registers.f[17] = value;
             break;
         case reg::f18:
-            m_s.f[18] = value;
+            m_s.registers.f[18] = value;
             break;
         case reg::f19:
-            m_s.f[19] = value;
+            m_s.registers.f[19] = value;
             break;
         case reg::f20:
-            m_s.f[20] = value;
+            m_s.registers.f[20] = value;
             break;
         case reg::f21:
-            m_s.f[21] = value;
+            m_s.registers.f[21] = value;
             break;
         case reg::f22:
-            m_s.f[22] = value;
+            m_s.registers.f[22] = value;
             break;
         case reg::f23:
-            m_s.f[23] = value;
+            m_s.registers.f[23] = value;
             break;
         case reg::f24:
-            m_s.f[24] = value;
+            m_s.registers.f[24] = value;
             break;
         case reg::f25:
-            m_s.f[25] = value;
+            m_s.registers.f[25] = value;
             break;
         case reg::f26:
-            m_s.f[26] = value;
+            m_s.registers.f[26] = value;
             break;
         case reg::f27:
-            m_s.f[27] = value;
+            m_s.registers.f[27] = value;
             break;
         case reg::f28:
-            m_s.f[28] = value;
+            m_s.registers.f[28] = value;
             break;
         case reg::f29:
-            m_s.f[29] = value;
+            m_s.registers.f[29] = value;
             break;
         case reg::f30:
-            m_s.f[30] = value;
+            m_s.registers.f[30] = value;
             break;
         case reg::f31:
-            m_s.f[31] = value;
+            m_s.registers.f[31] = value;
             break;
         case reg::pc:
-            m_s.pc = value;
+            m_s.registers.pc = value;
             break;
         case reg::fcsr:
-            m_s.fcsr = value;
+            m_s.registers.fcsr = value;
             break;
         case reg::mvendorid:
             throw std::invalid_argument{"register is read-only"};
@@ -1185,243 +1171,243 @@ void machine::write_reg(reg w, uint64_t value) {
         case reg::mimpid:
             throw std::invalid_argument{"register is read-only"};
         case reg::mcycle:
-            m_s.mcycle = value;
+            m_s.registers.mcycle = value;
             break;
         case reg::icycleinstret:
-            m_s.icycleinstret = value;
+            m_s.registers.icycleinstret = value;
             break;
         case reg::mstatus:
-            m_s.mstatus = value;
+            m_s.registers.mstatus = value;
             break;
         case reg::mtvec:
-            m_s.mtvec = value;
+            m_s.registers.mtvec = value;
             break;
         case reg::mscratch:
-            m_s.mscratch = value;
+            m_s.registers.mscratch = value;
             break;
         case reg::mepc:
-            m_s.mepc = value;
+            m_s.registers.mepc = value;
             break;
         case reg::mcause:
-            m_s.mcause = value;
+            m_s.registers.mcause = value;
             break;
         case reg::mtval:
-            m_s.mtval = value;
+            m_s.registers.mtval = value;
             break;
         case reg::misa:
-            m_s.misa = value;
+            m_s.registers.misa = value;
             break;
         case reg::mie:
-            m_s.mie = value;
+            m_s.registers.mie = value;
             break;
         case reg::mip:
-            m_s.mip = value;
+            m_s.registers.mip = value;
             break;
         case reg::medeleg:
-            m_s.medeleg = value;
+            m_s.registers.medeleg = value;
             break;
         case reg::mideleg:
-            m_s.mideleg = value;
+            m_s.registers.mideleg = value;
             break;
         case reg::mcounteren:
-            m_s.mcounteren = value;
+            m_s.registers.mcounteren = value;
             break;
         case reg::menvcfg:
-            m_s.menvcfg = value;
+            m_s.registers.menvcfg = value;
             break;
         case reg::stvec:
-            m_s.stvec = value;
+            m_s.registers.stvec = value;
             break;
         case reg::sscratch:
-            m_s.sscratch = value;
+            m_s.registers.sscratch = value;
             break;
         case reg::sepc:
-            m_s.sepc = value;
+            m_s.registers.sepc = value;
             break;
         case reg::scause:
-            m_s.scause = value;
+            m_s.registers.scause = value;
             break;
         case reg::stval:
-            m_s.stval = value;
+            m_s.registers.stval = value;
             break;
         case reg::satp:
-            m_s.satp = value;
+            m_s.registers.satp = value;
             break;
         case reg::scounteren:
-            m_s.scounteren = value;
+            m_s.registers.scounteren = value;
             break;
         case reg::senvcfg:
-            m_s.senvcfg = value;
+            m_s.registers.senvcfg = value;
             break;
         case reg::ilrsc:
-            m_s.ilrsc = value;
+            m_s.registers.ilrsc = value;
             break;
         case reg::iprv:
-            m_s.iprv = value;
+            m_s.registers.iprv = value;
             break;
         case reg::iflags_X:
-            m_s.iflags.X = value;
+            m_s.registers.iflags.X = value;
             break;
         case reg::iflags_Y:
-            m_s.iflags.Y = value;
+            m_s.registers.iflags.Y = value;
             break;
         case reg::iflags_H:
-            m_s.iflags.H = value;
+            m_s.registers.iflags.H = value;
             break;
         case reg::iunrep:
-            m_s.iunrep = value;
+            m_s.registers.iunrep = value;
             break;
         case reg::clint_mtimecmp:
-            m_s.clint.mtimecmp = value;
+            m_s.registers.clint.mtimecmp = value;
             break;
         case reg::plic_girqpend:
-            m_s.plic.girqpend = value;
+            m_s.registers.plic.girqpend = value;
             break;
         case reg::plic_girqsrvd:
-            m_s.plic.girqsrvd = value;
+            m_s.registers.plic.girqsrvd = value;
             break;
         case reg::htif_tohost:
-            m_s.htif.tohost = value;
+            m_s.registers.htif.tohost = value;
             break;
         case reg::htif_fromhost:
-            m_s.htif.fromhost = value;
+            m_s.registers.htif.fromhost = value;
             break;
         case reg::htif_ihalt:
-            m_s.htif.ihalt = value;
+            m_s.registers.htif.ihalt = value;
             break;
         case reg::htif_iconsole:
-            m_s.htif.iconsole = value;
+            m_s.registers.htif.iconsole = value;
             break;
         case reg::htif_iyield:
-            m_s.htif.iyield = value;
+            m_s.registers.htif.iyield = value;
             break;
         case reg::uarch_x0:
             throw std::invalid_argument{"register is read-only"};
         case reg::uarch_x1:
-            m_us.x[1] = value;
+            m_us.registers.x[1] = value;
             break;
         case reg::uarch_x2:
-            m_us.x[2] = value;
+            m_us.registers.x[2] = value;
             break;
         case reg::uarch_x3:
-            m_us.x[3] = value;
+            m_us.registers.x[3] = value;
             break;
         case reg::uarch_x4:
-            m_us.x[4] = value;
+            m_us.registers.x[4] = value;
             break;
         case reg::uarch_x5:
-            m_us.x[5] = value;
+            m_us.registers.x[5] = value;
             break;
         case reg::uarch_x6:
-            m_us.x[6] = value;
+            m_us.registers.x[6] = value;
             break;
         case reg::uarch_x7:
-            m_us.x[7] = value;
+            m_us.registers.x[7] = value;
             break;
         case reg::uarch_x8:
-            m_us.x[8] = value;
+            m_us.registers.x[8] = value;
             break;
         case reg::uarch_x9:
-            m_us.x[9] = value;
+            m_us.registers.x[9] = value;
             break;
         case reg::uarch_x10:
-            m_us.x[10] = value;
+            m_us.registers.x[10] = value;
             break;
         case reg::uarch_x11:
-            m_us.x[11] = value;
+            m_us.registers.x[11] = value;
             break;
         case reg::uarch_x12:
-            m_us.x[12] = value;
+            m_us.registers.x[12] = value;
             break;
         case reg::uarch_x13:
-            m_us.x[13] = value;
+            m_us.registers.x[13] = value;
             break;
         case reg::uarch_x14:
-            m_us.x[14] = value;
+            m_us.registers.x[14] = value;
             break;
         case reg::uarch_x15:
-            m_us.x[15] = value;
+            m_us.registers.x[15] = value;
             break;
         case reg::uarch_x16:
-            m_us.x[16] = value;
+            m_us.registers.x[16] = value;
             break;
         case reg::uarch_x17:
-            m_us.x[17] = value;
+            m_us.registers.x[17] = value;
             break;
         case reg::uarch_x18:
-            m_us.x[18] = value;
+            m_us.registers.x[18] = value;
             break;
         case reg::uarch_x19:
-            m_us.x[19] = value;
+            m_us.registers.x[19] = value;
             break;
         case reg::uarch_x20:
-            m_us.x[20] = value;
+            m_us.registers.x[20] = value;
             break;
         case reg::uarch_x21:
-            m_us.x[21] = value;
+            m_us.registers.x[21] = value;
             break;
         case reg::uarch_x22:
-            m_us.x[22] = value;
+            m_us.registers.x[22] = value;
             break;
         case reg::uarch_x23:
-            m_us.x[23] = value;
+            m_us.registers.x[23] = value;
             break;
         case reg::uarch_x24:
-            m_us.x[24] = value;
+            m_us.registers.x[24] = value;
             break;
         case reg::uarch_x25:
-            m_us.x[25] = value;
+            m_us.registers.x[25] = value;
             break;
         case reg::uarch_x26:
-            m_us.x[26] = value;
+            m_us.registers.x[26] = value;
             break;
         case reg::uarch_x27:
-            m_us.x[27] = value;
+            m_us.registers.x[27] = value;
             break;
         case reg::uarch_x28:
-            m_us.x[28] = value;
+            m_us.registers.x[28] = value;
             break;
         case reg::uarch_x29:
-            m_us.x[29] = value;
+            m_us.registers.x[29] = value;
             break;
         case reg::uarch_x30:
-            m_us.x[30] = value;
+            m_us.registers.x[30] = value;
             break;
         case reg::uarch_x31:
-            m_us.x[31] = value;
+            m_us.registers.x[31] = value;
             break;
         case reg::uarch_pc:
-            m_us.pc = value;
+            m_us.registers.pc = value;
             break;
         case reg::uarch_cycle:
-            m_us.cycle = value;
+            m_us.registers.cycle = value;
             break;
         case reg::uarch_halt_flag:
-            m_us.halt_flag = value;
+            m_us.registers.halt_flag = value;
             break;
         case reg::htif_tohost_dev:
-            m_s.htif.tohost = HTIF_REPLACE_DEV(m_s.htif.tohost, value);
+            m_s.registers.htif.tohost = HTIF_REPLACE_DEV(m_s.registers.htif.tohost, value);
             break;
         case reg::htif_tohost_cmd:
-            m_s.htif.tohost = HTIF_REPLACE_CMD(m_s.htif.tohost, value);
+            m_s.registers.htif.tohost = HTIF_REPLACE_CMD(m_s.registers.htif.tohost, value);
             break;
         case reg::htif_tohost_reason:
-            m_s.htif.tohost = HTIF_REPLACE_REASON(m_s.htif.tohost, value);
+            m_s.registers.htif.tohost = HTIF_REPLACE_REASON(m_s.registers.htif.tohost, value);
             break;
         case reg::htif_tohost_data:
-            m_s.htif.tohost = HTIF_REPLACE_DATA(m_s.htif.tohost, value);
+            m_s.registers.htif.tohost = HTIF_REPLACE_DATA(m_s.registers.htif.tohost, value);
             break;
         case reg::htif_fromhost_dev:
-            m_s.htif.fromhost = HTIF_REPLACE_DEV(m_s.htif.fromhost, value);
+            m_s.registers.htif.fromhost = HTIF_REPLACE_DEV(m_s.registers.htif.fromhost, value);
             break;
         case reg::htif_fromhost_cmd:
-            m_s.htif.fromhost = HTIF_REPLACE_CMD(m_s.htif.fromhost, value);
+            m_s.registers.htif.fromhost = HTIF_REPLACE_CMD(m_s.registers.htif.fromhost, value);
             break;
         case reg::htif_fromhost_reason:
-            m_s.htif.fromhost = HTIF_REPLACE_REASON(m_s.htif.fromhost, value);
+            m_s.registers.htif.fromhost = HTIF_REPLACE_REASON(m_s.registers.htif.fromhost, value);
             break;
         case reg::htif_fromhost_data:
-            m_s.htif.fromhost = HTIF_REPLACE_DATA(m_s.htif.fromhost, value);
+            m_s.registers.htif.fromhost = HTIF_REPLACE_DATA(m_s.registers.htif.fromhost, value);
             break;
         default:
             throw std::invalid_argument{"unknown register"};
@@ -2180,7 +2166,7 @@ interpreter_break_reason machine::run(uint64_t mcycle_end) {
 std::pair<uint64_t, execute_status> machine::poll_external_interrupts(uint64_t mcycle, uint64_t mcycle_max) {
     const auto status = execute_status::success;
     // Only poll external interrupts if we are in unreproducible mode
-    if (unlikely(m_s.iunrep)) {
+    if (unlikely(m_s.registers.iunrep)) {
         // Convert the relative interval of cycles we can wait to the interval of host time we can wait
         uint64_t timeout_us = (mcycle_max - mcycle) / RTC_CYCLES_PER_US;
         int64_t start_us = 0;
diff --git a/src/machine.h b/src/machine.h
index de79f6f0a..471589b1d 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -79,15 +79,15 @@ class machine final {
     void init_uarch_processor(const uarch_config &c);
 
     /// \brief Initializes registers
-    /// \param p Processor configuration
+    /// \param p Registers configuration
     /// \param r Machine runtime configuration
-    void init_processor(processor_config &p, const machine_runtime_config &r);
+    void init_registers(registers_state &p, const machine_runtime_config &r);
 
     /// \brief Initializes TTY if needed
     /// \param h HTIF configuration
     /// \param r HTIF runtime configuration
     /// \param iunrep Initial value of iunrep CSR
-    void init_tty(const htif_config &h, const htif_runtime_config &r, uint64_t iunrep) const;
+    void init_tty(const htif_state &h, const htif_runtime_config &r, uint64_t iunrep) const;
 
     /// \brief Initializes contents of the shadow PMAs memory
     /// \param pmas_config PMAs configuration
@@ -103,18 +103,6 @@ class machine final {
     /// \param config Machine configuration
     void init_dtb_contents(const machine_config &config);
 
-    /// \brief Initializes HTIF registers
-    /// \param h HTIF configuration
-    void init_htif_registers(const htif_config &h);
-
-    /// \brief Initializes CLINT registers
-    /// \param c CLINT configuration
-    void init_clint_registers(const clint_config &c);
-
-    /// \brief Initializes PLIC registers
-    /// \param p PLIC configuration
-    void init_plic_registers(const plic_config &p);
-
     /// \brief Dumps statistics
     void dump_stats();
 
diff --git a/src/pristine-address-range.h b/src/pristine-address-range.h
index 9324e6e71..cd763f8c3 100644
--- a/src/pristine-address-range.h
+++ b/src/pristine-address-range.h
@@ -33,7 +33,7 @@ class pristine_address_range : public address_range {
     /// \param description Description of address range for use in error messages
     /// \param start Target physical address where range starts
     /// \param length Length of range, in bytes
-    /// \param f Phyical memory attribute flags for range
+    /// \param f Physical memory attribute flags for range
     template <typename ABRT>
     pristine_address_range(const char *description, uint64_t start, uint64_t length, pmas_flags f, ABRT abrt) :
         address_range{description, start, length, f, abrt} {
diff --git a/src/record-send-cmio-state-access.h b/src/record-send-cmio-state-access.h
index e2eb87d30..b031c1015 100644
--- a/src/record-send-cmio-state-access.h
+++ b/src/record-send-cmio-state-access.h
@@ -185,18 +185,18 @@ class record_send_cmio_state_access :
     friend i_state_access<record_send_cmio_state_access>;
 
     void do_write_iflags_Y(uint64_t val) const {
-        log_before_write_write_and_update(machine_reg_address(machine_reg::iflags_Y), m_m.get_state().iflags.Y, val,
-            "iflags.Y");
+        log_before_write_write_and_update(machine_reg_address(machine_reg::iflags_Y),
+            m_m.get_state().registers.iflags.Y, val, "iflags.Y");
     }
 
     uint64_t do_read_iflags_Y() const {
         log_read(machine_reg_address(machine_reg::iflags_Y), "iflags.Y");
-        return m_m.get_state().iflags.Y;
+        return m_m.get_state().registers.iflags.Y;
     }
 
     void do_write_htif_fromhost(uint64_t val) const {
         log_before_write_write_and_update(machine_reg_address(machine_reg::htif_fromhost),
-            m_m.get_state().htif.fromhost, val, "htif.fromhost");
+            m_m.get_state().registers.htif.fromhost, val, "htif.fromhost");
     }
 
     void do_write_memory_with_padding(uint64_t paddr, const unsigned char *data, uint64_t data_length,
diff --git a/src/replay-step-state-access.h b/src/replay-step-state-access.h
index 853cccbb0..b56476553 100644
--- a/src/replay-step-state-access.h
+++ b/src/replay-step-state-access.h
@@ -372,7 +372,7 @@ class replay_step_state_access :
     }
 
     //??D we should probably optimize access to the shadow so it doesn't perform a translation every time
-    // We can do this by caching the vh_offset trasnslation of the processor shadow page. This is easy if
+    // We can do this by caching the vh_offset translation of the registers shadow page. This is easy if
     // static_assert(sizeof(shadow_state) <= AR_PAGE_SIZE, "shadow state must fit in single page");
     uint64_t check_read_reg(machine_reg reg) const {
         const auto haddr = do_get_faddr(machine_reg_address(reg));
@@ -380,7 +380,7 @@ class replay_step_state_access :
     }
 
     //??D we should probably optimize access to the shadow so it doesn't perform a translation every time
-    // We can do this by caching the vh_offset trasnslation of the processor shadow page. This is easy if
+    // We can do this by caching the vh_offset translation of the registers shadow page. This is easy if
     // static_assert(sizeof(shadow_state) <= AR_PAGE_SIZE, "shadow state must fit in single page");
     void check_write_reg(machine_reg reg, uint64_t val) const {
         const auto haddr = do_get_faddr(machine_reg_address(reg));
diff --git a/src/riscv-constants.h b/src/riscv-constants.h
index 91853ba30..1c7644585 100644
--- a/src/riscv-constants.h
+++ b/src/riscv-constants.h
@@ -20,6 +20,7 @@
 #include <cstdint>
 
 #include "address-range-constants.h"
+#include "htif-constants.h"
 #include "machine-c-version.h"
 #include "pmas-constants.h"
 
@@ -441,32 +442,35 @@ enum CARTESI_init : uint64_t {
     MTVAL_INIT = UINT64_C(0),                                                          ///< Initial value for mtval
     MISA_INIT = (MISA_MXL_VALUE << MISA_MXL_SHIFT) | MISA_EXT_S_MASK | MISA_EXT_U_MASK | MISA_EXT_I_MASK |
         MISA_EXT_M_MASK | MISA_EXT_A_MASK | MISA_EXT_F_MASK | MISA_EXT_D_MASK |
-        MISA_EXT_C_MASK,                ///< Initial value for misa
-    MIE_INIT = UINT64_C(0),             ///< Initial value for mie
-    MIP_INIT = UINT64_C(0),             ///< Initial value for mip
-    MEDELEG_INIT = UINT64_C(0),         ///< Initial value for medeleg
-    MIDELEG_INIT = UINT64_C(0),         ///< Initial value for mideleg
-    MCOUNTEREN_INIT = UINT64_C(0),      ///< Initial value for mcounteren
-    STVEC_INIT = UINT64_C(0),           ///< Initial value for stvec
-    SSCRATCH_INIT = UINT64_C(0),        ///< Initial value for sscratch
-    SEPC_INIT = UINT64_C(0),            ///< Initial value for sepc
-    SCAUSE_INIT = UINT64_C(0),          ///< Initial value for scause
-    STVAL_INIT = UINT64_C(0),           ///< Initial value for stval
-    SATP_INIT = UINT64_C(0),            ///< Initial value for satp
-    SCOUNTEREN_INIT = UINT64_C(0),      ///< Initial value for scounteren
-    ILRSC_INIT = UINT64_C(-1),          ///< Initial value for ilrsc
-    IPRV_INIT = PRV_M,                  ///< Initial value for iprv
-    IFLAGS_X_INIT = UINT64_C(0),        ///< Initial value for iflags_X
-    IFLAGS_Y_INIT = UINT64_C(0),        ///< Initial value for iflags_Y
-    IFLAGS_H_INIT = UINT64_C(0),        ///< Initial value for iflags_H
-    IUNREP_INIT = UINT64_C(0),          ///< Initial value for iunrep
-    MTIMECMP_INIT = UINT64_C(0),        ///< Initial value for mtimecmp
-    GIRQPEND_INIT = UINT64_C(0),        ///< Initial value for girqpend
-    GIRQSRVD_INIT = UINT64_C(0),        ///< Initial value for girqsrvd
-    FROMHOST_INIT = UINT64_C(0),        ///< Initial value for fromhost
-    TOHOST_INIT = UINT64_C(0),          ///< Initial value for tohost
-    MENVCFG_INIT = UINT64_C(0),         ///< Initial value for menvcfg
-    SENVCFG_INIT = UINT64_C(0),         ///< Initial value for senvcfg
+        MISA_EXT_C_MASK,                                                      ///< Initial value for misa
+    MIE_INIT = UINT64_C(0),                                                   ///< Initial value for mie
+    MIP_INIT = UINT64_C(0),                                                   ///< Initial value for mip
+    MEDELEG_INIT = UINT64_C(0),                                               ///< Initial value for medeleg
+    MIDELEG_INIT = UINT64_C(0),                                               ///< Initial value for mideleg
+    MCOUNTEREN_INIT = UINT64_C(0),                                            ///< Initial value for mcounteren
+    STVEC_INIT = UINT64_C(0),                                                 ///< Initial value for stvec
+    SSCRATCH_INIT = UINT64_C(0),                                              ///< Initial value for sscratch
+    SEPC_INIT = UINT64_C(0),                                                  ///< Initial value for sepc
+    SCAUSE_INIT = UINT64_C(0),                                                ///< Initial value for scause
+    STVAL_INIT = UINT64_C(0),                                                 ///< Initial value for stval
+    SATP_INIT = UINT64_C(0),                                                  ///< Initial value for satp
+    SCOUNTEREN_INIT = UINT64_C(0),                                            ///< Initial value for scounteren
+    ILRSC_INIT = UINT64_C(-1),                                                ///< Initial value for ilrsc
+    IPRV_INIT = PRV_M,                                                        ///< Initial value for iprv
+    IFLAGS_X_INIT = UINT64_C(0),                                              ///< Initial value for iflags_X
+    IFLAGS_Y_INIT = UINT64_C(0),                                              ///< Initial value for iflags_Y
+    IFLAGS_H_INIT = UINT64_C(0),                                              ///< Initial value for iflags_H
+    IUNREP_INIT = UINT64_C(0),                                                ///< Initial value for iunrep
+    MTIMECMP_INIT = UINT64_C(0),                                              ///< Initial value for mtimecmp
+    GIRQPEND_INIT = UINT64_C(0),                                              ///< Initial value for girqpend
+    GIRQSRVD_INIT = UINT64_C(0),                                              ///< Initial value for girqsrvd
+    FROMHOST_INIT = UINT64_C(0),                                              ///< Initial value for fromhost
+    TOHOST_INIT = UINT64_C(0),                                                ///< Initial value for tohost
+    MENVCFG_INIT = UINT64_C(0),                                               ///< Initial value for menvcfg
+    SENVCFG_INIT = UINT64_C(0),                                               ///< Initial value for senvcfg
+    IHALT_INIT = HTIF_HALT_CMD_HALT_MASK,                                     ///< Initial value for ihalt
+    ICONSOLE_INIT = HTIF_CONSOLE_CMD_PUTCHAR_MASK,                            ///< Initial value for iconsole
+    IYIELD_INIT = HTIF_YIELD_CMD_MANUAL_MASK | HTIF_YIELD_CMD_AUTOMATIC_MASK, ///< Initial value for iyield
     UARCH_HALT_FLAG_INIT = UINT64_C(0), ///< Initial value for microarchitecture halt flag
     UARCH_X_INIT = UINT64_C(0),         ///< Initial value for microarchitecture general purpose register x
     UARCH_PC_INIT = AR_UARCH_RAM_START, ///< Initial value for microarchitecture pc
diff --git a/src/shadow-state.h b/src/shadow-state.h
index 57ebad79c..f0742acfb 100644
--- a/src/shadow-state.h
+++ b/src/shadow-state.h
@@ -30,54 +30,92 @@
 
 namespace cartesi {
 
-/// \brief Shadow memory layout
-struct PACKED shadow_state {
-    uint64_t x[X_REG_COUNT]; ///< Register file.
-    uint64_t f[F_REG_COUNT]; ///< Floating-point register file.
-    uint64_t pc;
-    uint64_t fcsr;
-    uint64_t mvendorid;
-    uint64_t marchid;
-    uint64_t mimpid;
-    uint64_t mcycle;
-    uint64_t icycleinstret;
-    uint64_t mstatus;
-    uint64_t mtvec;
-    uint64_t mscratch;
-    uint64_t mepc;
-    uint64_t mcause;
-    uint64_t mtval;
-    uint64_t misa;
-    uint64_t mie;
-    uint64_t mip;
-    uint64_t medeleg;
-    uint64_t mideleg;
-    uint64_t mcounteren;
-    uint64_t menvcfg;
-    uint64_t stvec;
-    uint64_t sscratch;
-    uint64_t sepc;
-    uint64_t scause;
-    uint64_t stval;
-    uint64_t satp;
-    uint64_t scounteren;
-    uint64_t senvcfg;
-    uint64_t ilrsc;
-    uint64_t iprv;
-    uint64_t iflags_X;
-    uint64_t iflags_Y;
-    uint64_t iflags_H;
-    uint64_t iunrep;
-    uint64_t clint_mtimecmp;
-    uint64_t plic_girqpend;
-    uint64_t plic_girqsrvd;
-    uint64_t htif_tohost;
-    uint64_t htif_fromhost;
-    uint64_t htif_ihalt;
-    uint64_t htif_iconsole;
-    uint64_t htif_iyield;
+/// \brief Internal flags state (Cartesi specific).
+struct iflags_state final {
+    uint64_t X{IFLAGS_X_INIT}; ///< CPU has yielded with automatic reset.
+    uint64_t Y{IFLAGS_Y_INIT}; ///< CPU has yielded with manual reset.
+    uint64_t H{IFLAGS_H_INIT}; ///< CPU has been permanently halted.
+};
+
+/// \brief CLINT (Core-Local Interruptor) state
+struct clint_state final {
+    uint64_t mtimecmp{MTIMECMP_INIT}; ///< CSR mtimecmp.
+};
+
+/// \brief PLIC (Platform-Level Interrupt Controller) state
+struct plic_state final {
+    uint64_t girqpend{GIRQPEND_INIT}; ///< CSR girqpend (global interrupts pending).
+    uint64_t girqsrvd{GIRQSRVD_INIT}; ///< CSR girqsrvd (global interrupts served).
+};
+
+/// HTIF (Host-Target config InterFace) state
+struct htif_state final {
+    uint64_t tohost{TOHOST_INIT};     ///< CSR tohost.
+    uint64_t fromhost{FROMHOST_INIT}; ///< CSR fromhost.
+    uint64_t ihalt{IHALT_INIT};       ///< CSR ihalt (Cartesi-specific).
+    uint64_t iconsole{ICONSOLE_INIT}; ///< CSR iconsole (Cartesi-specific).
+    uint64_t iyield{IYIELD_INIT};     ///< CSR iyield (Cartesi-specific).
+};
+
+/// \brief Machine registers state
+struct registers_state final {
+    // The X registers are the very first to optimize access of registers in the interpreter.
+    uint64_t x[X_REG_COUNT]{REG_X0, REG_X1, REG_X2, REG_X3, REG_X4, REG_X5, REG_X6, REG_X7, REG_X8, REG_X9, REG_X10,
+        REG_X11, REG_X12, REG_X13, REG_X14, REG_X15, REG_X16, REG_X17, REG_X18, REG_X19, REG_X20, REG_X21, REG_X22,
+        REG_X23, REG_X24, REG_X25, REG_X26, REG_X27, REG_X28, REG_X29, REG_X30, REG_X31}; ///< Register file.
+    // The following registers are carefully ordered to have better data locality in the interpreter loop.
+    uint64_t mcycle{MCYCLE_INIT}; ///< CSR mcycle.
+    uint64_t pc{PC_INIT};         ///< Program counter.
+    uint64_t fcsr{FCSR_INIT};     ///< CSR fcsr.
+    uint64_t f[F_REG_COUNT]{};    ///< Floating-point register file.
+    uint64_t iprv{IPRV_INIT};     ///< Privilege level (Cartesi-specific).
+
+    // RISC-V machine CSRs
+    uint64_t mstatus{MSTATUS_INIT};       ///< CSR mstatus.
+    uint64_t mtvec{MTVEC_INIT};           ///< CSR mtvec.
+    uint64_t mscratch{MSCRATCH_INIT};     ///< CSR mscratch.
+    uint64_t mepc{MEPC_INIT};             ///< CSR mepc.
+    uint64_t mcause{MCAUSE_INIT};         ///< CSR mcause.
+    uint64_t mtval{MTVAL_INIT};           ///< CSR mtval.
+    uint64_t misa{MISA_INIT};             ///< CSR misa.
+    uint64_t mie{MIE_INIT};               ///< CSR mie.
+    uint64_t mip{MIP_INIT};               ///< CSR mip.
+    uint64_t medeleg{MEDELEG_INIT};       ///< CSR medeleg.
+    uint64_t mideleg{MIDELEG_INIT};       ///< CSR mideleg.
+    uint64_t mcounteren{MCOUNTEREN_INIT}; ///< CSR mcounteren.
+    uint64_t menvcfg{MENVCFG_INIT};       ///< CSR menvcfg.
+    uint64_t mvendorid{MVENDORID_INIT};   ///< CSR mvendorid.
+    uint64_t marchid{MARCHID_INIT};       ///< CSR marchid.
+    uint64_t mimpid{MIMPID_INIT};         ///< CSR mimpid.
+
+    // RISC-V supervisor CSRs
+    uint64_t stvec{STVEC_INIT};           ///< CSR stvec.
+    uint64_t sscratch{SSCRATCH_INIT};     ///< CSR sscratch.
+    uint64_t sepc{SEPC_INIT};             ///< CSR sepc.
+    uint64_t scause{SCAUSE_INIT};         ///< CSR scause.
+    uint64_t stval{STVAL_INIT};           ///< CSR stval.
+    uint64_t satp{SATP_INIT};             ///< CSR satp.
+    uint64_t scounteren{SCOUNTEREN_INIT}; ///< CSR scounteren.
+    uint64_t senvcfg{SENVCFG_INIT};       ///< CSR senvcfg.
+
+    // Cartesi-specific state
+    uint64_t ilrsc{ILRSC_INIT};                 ///< For LR/SC instructions.
+    uint64_t icycleinstret{ICYCLEINSTRET_INIT}; ///< Difference between mcycle and minstret.
+    uint64_t iunrep{IUNREP_INIT};               ///< Unreproducible mode.
+
+    iflags_state iflags; ///< Internal flags (Cartesi specific).
+    clint_state clint;   ///< CLINT registers.
+    plic_state plic;     ///< PLIC registers.
+    htif_state htif;     ///< HTIF registers.
 };
 
+/// \brief Shadow memory layout
+using shadow_state = registers_state;
+
+// We need strong guarantees that shadow_state has fixed size and alignment across platforms.
+static_assert(sizeof(shadow_state) == 106 * sizeof(uint64_t), "unexpected registers state size");
+static_assert(alignof(shadow_state) == sizeof(uint64_t), "unexpected registers state alignment");
+
 enum class shadow_state_what : uint64_t {
     x0 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[0]),
     x1 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[1]),
@@ -173,18 +211,18 @@ enum class shadow_state_what : uint64_t {
     senvcfg = AR_SHADOW_STATE_START + offsetof(shadow_state, senvcfg),
     ilrsc = AR_SHADOW_STATE_START + offsetof(shadow_state, ilrsc),
     iprv = AR_SHADOW_STATE_START + offsetof(shadow_state, iprv),
-    iflags_X = AR_SHADOW_STATE_START + offsetof(shadow_state, iflags_X),
-    iflags_Y = AR_SHADOW_STATE_START + offsetof(shadow_state, iflags_Y),
-    iflags_H = AR_SHADOW_STATE_START + offsetof(shadow_state, iflags_H),
+    iflags_X = AR_SHADOW_STATE_START + offsetof(shadow_state, iflags.X),
+    iflags_Y = AR_SHADOW_STATE_START + offsetof(shadow_state, iflags.Y),
+    iflags_H = AR_SHADOW_STATE_START + offsetof(shadow_state, iflags.H),
     iunrep = AR_SHADOW_STATE_START + offsetof(shadow_state, iunrep),
-    clint_mtimecmp = AR_SHADOW_STATE_START + offsetof(shadow_state, clint_mtimecmp),
-    plic_girqpend = AR_SHADOW_STATE_START + offsetof(shadow_state, plic_girqpend),
-    plic_girqsrvd = AR_SHADOW_STATE_START + offsetof(shadow_state, plic_girqsrvd),
-    htif_tohost = AR_SHADOW_STATE_START + offsetof(shadow_state, htif_tohost),
-    htif_fromhost = AR_SHADOW_STATE_START + offsetof(shadow_state, htif_fromhost),
-    htif_ihalt = AR_SHADOW_STATE_START + offsetof(shadow_state, htif_ihalt),
-    htif_iconsole = AR_SHADOW_STATE_START + offsetof(shadow_state, htif_iconsole),
-    htif_iyield = AR_SHADOW_STATE_START + offsetof(shadow_state, htif_iyield),
+    clint_mtimecmp = AR_SHADOW_STATE_START + offsetof(shadow_state, clint.mtimecmp),
+    plic_girqpend = AR_SHADOW_STATE_START + offsetof(shadow_state, plic.girqpend),
+    plic_girqsrvd = AR_SHADOW_STATE_START + offsetof(shadow_state, plic.girqsrvd),
+    htif_tohost = AR_SHADOW_STATE_START + offsetof(shadow_state, htif.tohost),
+    htif_fromhost = AR_SHADOW_STATE_START + offsetof(shadow_state, htif.fromhost),
+    htif_ihalt = AR_SHADOW_STATE_START + offsetof(shadow_state, htif.ihalt),
+    htif_iconsole = AR_SHADOW_STATE_START + offsetof(shadow_state, htif.iconsole),
+    htif_iyield = AR_SHADOW_STATE_START + offsetof(shadow_state, htif.iyield),
     unknown_ = UINT64_C(1) << 63, // Outside of RISC-V address space
 };
 
diff --git a/src/shadow-uarch-state.h b/src/shadow-uarch-state.h
index ded6e0201..868100379 100644
--- a/src/shadow-uarch-state.h
+++ b/src/shadow-uarch-state.h
@@ -28,14 +28,21 @@
 
 namespace cartesi {
 
-/// \brief Shadow uarch memory layout
-struct PACKED shadow_uarch_state {
-    uint64_t halt_flag;
-    uint64_t cycle;
-    uint64_t pc;
-    uint64_t x[UARCH_X_REG_COUNT];
+/// \brief Uarch registers state
+struct uarch_registers_state final {
+    uint64_t halt_flag{UARCH_HALT_FLAG_INIT};
+    uint64_t cycle{UARCH_CYCLE_INIT};
+    uint64_t pc{UARCH_PC_INIT};
+    uint64_t x[UARCH_X_REG_COUNT]{};
 };
 
+/// \brief Shadow uarch memory layout
+using shadow_uarch_state = uarch_registers_state;
+
+// We need strong guarantees that shadow_uarch_state has fixed size and alignment across platforms.
+static_assert(sizeof(shadow_uarch_state) == 35 * sizeof(uint64_t), "unexpected uarch registers state size");
+static_assert(alignof(shadow_uarch_state) == sizeof(uint64_t), "unexpected uarch registers state alignment");
+
 enum class shadow_uarch_state_what : uint64_t {
     uarch_halt_flag = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, halt_flag),
     uarch_cycle = AR_SHADOW_UARCH_STATE_START + offsetof(shadow_uarch_state, cycle),
diff --git a/src/state-access.h b/src/state-access.h
index 6f079853a..1665cfea0 100644
--- a/src/state-access.h
+++ b/src/state-access.h
@@ -77,44 +77,44 @@ class state_access :
     friend i_state_access<state_access>;
 
     uint64_t do_read_x(int i) const {
-        return m_m.get_state().x[i];
+        return m_m.get_state().registers.x[i];
     }
 
     void do_write_x(int i, uint64_t val) const {
         assert(i != 0);
-        m_m.get_state().x[i] = val;
+        m_m.get_state().registers.x[i] = val;
     }
 
     uint64_t do_read_f(int i) const {
-        return m_m.get_state().f[i];
+        return m_m.get_state().registers.f[i];
     }
 
     void do_write_f(int i, uint64_t val) const {
-        m_m.get_state().f[i] = val;
+        m_m.get_state().registers.f[i] = val;
     }
 
     uint64_t do_read_pc() const {
-        return m_m.get_state().pc;
+        return m_m.get_state().registers.pc;
     }
 
     void do_write_pc(uint64_t val) const {
-        m_m.get_state().pc = val;
+        m_m.get_state().registers.pc = val;
     }
 
     uint64_t do_read_fcsr() const {
-        return m_m.get_state().fcsr;
+        return m_m.get_state().registers.fcsr;
     }
 
     void do_write_fcsr(uint64_t val) const {
-        m_m.get_state().fcsr = val;
+        m_m.get_state().registers.fcsr = val;
     }
 
     uint64_t do_read_icycleinstret() const {
-        return m_m.get_state().icycleinstret;
+        return m_m.get_state().registers.icycleinstret;
     }
 
     void do_write_icycleinstret(uint64_t val) const {
-        m_m.get_state().icycleinstret = val;
+        m_m.get_state().registers.icycleinstret = val;
     }
 
     uint64_t do_read_mvendorid() const { // NOLINT(readability-convert-member-functions-to-static)
@@ -130,279 +130,279 @@ class state_access :
     }
 
     uint64_t do_read_mcycle() const {
-        return m_m.get_state().mcycle;
+        return m_m.get_state().registers.mcycle;
     }
 
     void do_write_mcycle(uint64_t val) const {
-        m_m.get_state().mcycle = val;
+        m_m.get_state().registers.mcycle = val;
     }
 
     uint64_t do_read_mstatus() const {
-        return m_m.get_state().mstatus;
+        return m_m.get_state().registers.mstatus;
     }
 
     void do_write_mstatus(uint64_t val) const {
-        m_m.get_state().mstatus = val;
+        m_m.get_state().registers.mstatus = val;
     }
 
     uint64_t do_read_menvcfg() const {
-        return m_m.get_state().menvcfg;
+        return m_m.get_state().registers.menvcfg;
     }
 
     void do_write_menvcfg(uint64_t val) const {
-        m_m.get_state().menvcfg = val;
+        m_m.get_state().registers.menvcfg = val;
     }
 
     uint64_t do_read_mtvec() const {
-        return m_m.get_state().mtvec;
+        return m_m.get_state().registers.mtvec;
     }
 
     void do_write_mtvec(uint64_t val) const {
-        m_m.get_state().mtvec = val;
+        m_m.get_state().registers.mtvec = val;
     }
 
     uint64_t do_read_mscratch() const {
-        return m_m.get_state().mscratch;
+        return m_m.get_state().registers.mscratch;
     }
 
     void do_write_mscratch(uint64_t val) const {
-        m_m.get_state().mscratch = val;
+        m_m.get_state().registers.mscratch = val;
     }
 
     uint64_t do_read_mepc() const {
-        return m_m.get_state().mepc;
+        return m_m.get_state().registers.mepc;
     }
 
     void do_write_mepc(uint64_t val) const {
-        m_m.get_state().mepc = val;
+        m_m.get_state().registers.mepc = val;
     }
 
     uint64_t do_read_mcause() const {
-        return m_m.get_state().mcause;
+        return m_m.get_state().registers.mcause;
     }
 
     void do_write_mcause(uint64_t val) const {
-        m_m.get_state().mcause = val;
+        m_m.get_state().registers.mcause = val;
     }
 
     uint64_t do_read_mtval() const {
-        return m_m.get_state().mtval;
+        return m_m.get_state().registers.mtval;
     }
 
     void do_write_mtval(uint64_t val) const {
-        m_m.get_state().mtval = val;
+        m_m.get_state().registers.mtval = val;
     }
 
     uint64_t do_read_misa() const {
-        return m_m.get_state().misa;
+        return m_m.get_state().registers.misa;
     }
 
     void do_write_misa(uint64_t val) const {
-        m_m.get_state().misa = val;
+        m_m.get_state().registers.misa = val;
     }
 
     uint64_t do_read_mie() const {
-        return m_m.get_state().mie;
+        return m_m.get_state().registers.mie;
     }
 
     void do_write_mie(uint64_t val) const {
-        m_m.get_state().mie = val;
+        m_m.get_state().registers.mie = val;
     }
 
     uint64_t do_read_mip() const {
-        return m_m.get_state().mip;
+        return m_m.get_state().registers.mip;
     }
 
     void do_write_mip(uint64_t val) const {
-        m_m.get_state().mip = val;
+        m_m.get_state().registers.mip = val;
     }
 
     uint64_t do_read_medeleg() const {
-        return m_m.get_state().medeleg;
+        return m_m.get_state().registers.medeleg;
     }
 
     void do_write_medeleg(uint64_t val) const {
-        m_m.get_state().medeleg = val;
+        m_m.get_state().registers.medeleg = val;
     }
 
     uint64_t do_read_mideleg() const {
-        return m_m.get_state().mideleg;
+        return m_m.get_state().registers.mideleg;
     }
 
     void do_write_mideleg(uint64_t val) const {
-        m_m.get_state().mideleg = val;
+        m_m.get_state().registers.mideleg = val;
     }
 
     uint64_t do_read_mcounteren() const {
-        return m_m.get_state().mcounteren;
+        return m_m.get_state().registers.mcounteren;
     }
 
     void do_write_mcounteren(uint64_t val) const {
-        m_m.get_state().mcounteren = val;
+        m_m.get_state().registers.mcounteren = val;
     }
 
     uint64_t do_read_senvcfg() const {
-        return m_m.get_state().senvcfg;
+        return m_m.get_state().registers.senvcfg;
     }
 
     void do_write_senvcfg(uint64_t val) const {
-        m_m.get_state().senvcfg = val;
+        m_m.get_state().registers.senvcfg = val;
     }
 
     uint64_t do_read_stvec() const {
-        return m_m.get_state().stvec;
+        return m_m.get_state().registers.stvec;
     }
 
     void do_write_stvec(uint64_t val) const {
-        m_m.get_state().stvec = val;
+        m_m.get_state().registers.stvec = val;
     }
 
     uint64_t do_read_sscratch() const {
-        return m_m.get_state().sscratch;
+        return m_m.get_state().registers.sscratch;
     }
 
     void do_write_sscratch(uint64_t val) const {
-        m_m.get_state().sscratch = val;
+        m_m.get_state().registers.sscratch = val;
     }
 
     uint64_t do_read_sepc() const {
-        return m_m.get_state().sepc;
+        return m_m.get_state().registers.sepc;
     }
 
     void do_write_sepc(uint64_t val) const {
-        m_m.get_state().sepc = val;
+        m_m.get_state().registers.sepc = val;
     }
 
     uint64_t do_read_scause() const {
-        return m_m.get_state().scause;
+        return m_m.get_state().registers.scause;
     }
 
     void do_write_scause(uint64_t val) const {
-        m_m.get_state().scause = val;
+        m_m.get_state().registers.scause = val;
     }
 
     uint64_t do_read_stval() const {
-        return m_m.get_state().stval;
+        return m_m.get_state().registers.stval;
     }
 
     void do_write_stval(uint64_t val) const {
-        m_m.get_state().stval = val;
+        m_m.get_state().registers.stval = val;
     }
 
     uint64_t do_read_satp() const {
-        return m_m.get_state().satp;
+        return m_m.get_state().registers.satp;
     }
 
     void do_write_satp(uint64_t val) const {
-        m_m.get_state().satp = val;
+        m_m.get_state().registers.satp = val;
     }
 
     uint64_t do_read_scounteren() const {
-        return m_m.get_state().scounteren;
+        return m_m.get_state().registers.scounteren;
     }
 
     void do_write_scounteren(uint64_t val) const {
-        m_m.get_state().scounteren = val;
+        m_m.get_state().registers.scounteren = val;
     }
 
     uint64_t do_read_ilrsc() const {
-        return m_m.get_state().ilrsc;
+        return m_m.get_state().registers.ilrsc;
     }
 
     void do_write_ilrsc(uint64_t val) const {
-        m_m.get_state().ilrsc = val;
+        m_m.get_state().registers.ilrsc = val;
     }
 
     uint64_t do_read_iprv() const {
-        return m_m.get_state().iprv;
+        return m_m.get_state().registers.iprv;
     }
 
     void do_write_iprv(uint64_t val) const {
-        m_m.get_state().iprv = val;
+        m_m.get_state().registers.iprv = val;
     }
 
     uint64_t do_read_iflags_X() const {
-        return m_m.get_state().iflags.X;
+        return m_m.get_state().registers.iflags.X;
     }
 
     void do_write_iflags_X(uint64_t val) const {
-        m_m.get_state().iflags.X = val;
+        m_m.get_state().registers.iflags.X = val;
     }
 
     uint64_t do_read_iflags_Y() const {
-        return m_m.get_state().iflags.Y;
+        return m_m.get_state().registers.iflags.Y;
     }
 
     void do_write_iflags_Y(uint64_t val) const {
-        m_m.get_state().iflags.Y = val;
+        m_m.get_state().registers.iflags.Y = val;
     }
 
     uint64_t do_read_iflags_H() const {
-        return m_m.get_state().iflags.H;
+        return m_m.get_state().registers.iflags.H;
     }
 
     void do_write_iflags_H(uint64_t val) const {
-        m_m.get_state().iflags.H = val;
+        m_m.get_state().registers.iflags.H = val;
     }
 
     uint64_t do_read_iunrep() const {
-        return m_m.get_state().iunrep;
+        return m_m.get_state().registers.iunrep;
     }
 
     void do_write_iunrep(uint64_t val) const {
-        m_m.get_state().iunrep = val;
+        m_m.get_state().registers.iunrep = val;
     }
 
     uint64_t do_read_clint_mtimecmp() const {
-        return m_m.get_state().clint.mtimecmp;
+        return m_m.get_state().registers.clint.mtimecmp;
     }
 
     void do_write_clint_mtimecmp(uint64_t val) const {
-        m_m.get_state().clint.mtimecmp = val;
+        m_m.get_state().registers.clint.mtimecmp = val;
     }
 
     uint64_t do_read_plic_girqpend() const {
-        return m_m.get_state().plic.girqpend;
+        return m_m.get_state().registers.plic.girqpend;
     }
 
     void do_write_plic_girqpend(uint64_t val) const {
-        m_m.get_state().plic.girqpend = val;
+        m_m.get_state().registers.plic.girqpend = val;
     }
 
     uint64_t do_read_plic_girqsrvd() const {
-        return m_m.get_state().plic.girqsrvd;
+        return m_m.get_state().registers.plic.girqsrvd;
     }
 
     void do_write_plic_girqsrvd(uint64_t val) const {
-        m_m.get_state().plic.girqsrvd = val;
+        m_m.get_state().registers.plic.girqsrvd = val;
     }
 
     uint64_t do_read_htif_fromhost() const {
-        return m_m.get_state().htif.fromhost;
+        return m_m.get_state().registers.htif.fromhost;
     }
 
     void do_write_htif_fromhost(uint64_t val) const {
-        m_m.get_state().htif.fromhost = val;
+        m_m.get_state().registers.htif.fromhost = val;
     }
 
     uint64_t do_read_htif_tohost() const {
-        return m_m.get_state().htif.tohost;
+        return m_m.get_state().registers.htif.tohost;
     }
 
     void do_write_htif_tohost(uint64_t val) const {
-        m_m.get_state().htif.tohost = val;
+        m_m.get_state().registers.htif.tohost = val;
     }
 
     uint64_t do_read_htif_ihalt() const {
-        return m_m.get_state().htif.ihalt;
+        return m_m.get_state().registers.htif.ihalt;
     }
 
     uint64_t do_read_htif_iconsole() const {
-        return m_m.get_state().htif.iconsole;
+        return m_m.get_state().registers.htif.iconsole;
     }
 
     uint64_t do_read_htif_iyield() const {
-        return m_m.get_state().htif.iyield;
+        return m_m.get_state().registers.htif.iyield;
     }
 
     bool do_read_memory(uint64_t paddr, unsigned char *data, uint64_t length) const {
diff --git a/src/uarch-state-access.h b/src/uarch-state-access.h
index b62410112..5d60593b6 100644
--- a/src/uarch-state-access.h
+++ b/src/uarch-state-access.h
@@ -51,36 +51,36 @@ class uarch_state_access :
     friend i_uarch_state_access<uarch_state_access>;
 
     uint64_t do_read_uarch_x(int i) const {
-        return m_m.get_uarch_state().x[i];
+        return m_m.get_uarch_state().registers.x[i];
     }
 
     void do_write_uarch_x(int i, uint64_t val) const {
         assert(i != 0);
-        m_m.get_uarch_state().x[i] = val;
+        m_m.get_uarch_state().registers.x[i] = val;
     }
 
     uint64_t do_read_uarch_pc() const {
-        return m_m.get_uarch_state().pc;
+        return m_m.get_uarch_state().registers.pc;
     }
 
     void do_write_uarch_pc(uint64_t val) const {
-        m_m.get_uarch_state().pc = val;
+        m_m.get_uarch_state().registers.pc = val;
     }
 
     uint64_t do_read_uarch_cycle() const {
-        return m_m.get_uarch_state().cycle;
+        return m_m.get_uarch_state().registers.cycle;
     }
 
     void do_write_uarch_cycle(uint64_t val) const {
-        m_m.get_uarch_state().cycle = val;
+        m_m.get_uarch_state().registers.cycle = val;
     }
 
     uint64_t do_read_uarch_halt_flag() const {
-        return m_m.get_uarch_state().halt_flag;
+        return m_m.get_uarch_state().registers.halt_flag;
     }
 
     void do_write_uarch_halt_flag(uint64_t v) const {
-        m_m.get_uarch_state().halt_flag = v;
+        m_m.get_uarch_state().registers.halt_flag = v;
     }
 
     uint64_t do_read_word(uint64_t paddr) const {
diff --git a/src/uarch-state.h b/src/uarch-state.h
index ffd2a2420..51bff79af 100644
--- a/src/uarch-state.h
+++ b/src/uarch-state.h
@@ -26,10 +26,11 @@
 
 #include "memory-address-range.h"
 #include "riscv-constants.h"
+#include "shadow-uarch-state.h"
 
 namespace cartesi {
 
-struct uarch_state {
+struct uarch_state final {
     uarch_state() = default;
     ~uarch_state() = default;
 
@@ -39,10 +40,8 @@ struct uarch_state {
     uarch_state &operator=(const uarch_state &other) = delete;
     uarch_state &operator=(uarch_state &&other) = delete;
 
-    uint64_t pc{};                               ///< Program counter.
-    std::array<uint64_t, UARCH_X_REG_COUNT> x{}; ///< Register file.
-    uint64_t cycle{};                            ///< Cycles counter
-    uint64_t halt_flag{};
+    // Shadow region.
+    uarch_registers_state registers; ///< Uarch registers
 };
 
 } // namespace cartesi
diff --git a/tests/lua/htif-console.lua b/tests/lua/htif-console.lua
index 17274893c..ee8a60ce0 100755
--- a/tests/lua/htif-console.lua
+++ b/tests/lua/htif-console.lua
@@ -21,7 +21,9 @@ local test_util = require("cartesi.tests.util")
 
 local config_base = {
     processor = {
-        iunrep = 1,
+        registers = {
+            iunrep = 1,
+        },
     },
     ram = {
         backing_store = {
diff --git a/tests/lua/htif-yield.lua b/tests/lua/htif-yield.lua
index e62272b5d..6c62d3610 100755
--- a/tests/lua/htif-yield.lua
+++ b/tests/lua/htif-yield.lua
@@ -203,9 +203,13 @@ local function test(machine_config, yield_automatic_enable, yield_manual_enable)
         yield_automatic_enable and "on" or "off",
         yield_manual_enable and "on" or "off"
     )
-    machine_config.htif = {
-        yield_automatic = yield_automatic_enable,
-        yield_manual = yield_manual_enable,
+    machine_config.processor = {
+        registers = {
+            htif = {
+                iyield = (yield_automatic_enable and cartesi.HTIF_YIELD_CMD_AUTOMATIC_MASK or 0)
+                    | (yield_manual_enable and cartesi.HTIF_YIELD_CMD_MANUAL_MASK or 0),
+            },
+        },
     }
     local machine <close> = cartesi.machine(machine_config)
     for _, v in ipairs(yields) do
diff --git a/tests/lua/log-with-mtime-transition.lua b/tests/lua/log-with-mtime-transition.lua
index 4d3298952..f8f2461d0 100755
--- a/tests/lua/log-with-mtime-transition.lua
+++ b/tests/lua/log-with-mtime-transition.lua
@@ -4,7 +4,9 @@ local cartesi = require("cartesi")
 
 local config = {
     processor = {
-        mcycle = 99,
+        registers = {
+            mcycle = 99,
+        },
     },
     ram = {
         length = 1 << 12,
diff --git a/tests/lua/machine-bind.lua b/tests/lua/machine-bind.lua
index a7af8ddbe..2f4870d2c 100755
--- a/tests/lua/machine-bind.lua
+++ b/tests/lua/machine-bind.lua
@@ -147,60 +147,12 @@ end
 
 local SHADOW_BASE = 0x0
 
-local cpu_reg_addr = {
-    pc = 512,
-    fcsr = 520,
-    mvendorid = 528,
-    marchid = 536,
-    mimpid = 544,
-    mcycle = 552,
-    icycleinstret = 560,
-    mstatus = 568,
-    mtvec = 576,
-    mscratch = 584,
-    mepc = 592,
-    mcause = 600,
-    mtval = 608,
-    misa = 616,
-    mie = 624,
-    mip = 632,
-    medeleg = 640,
-    mideleg = 648,
-    mcounteren = 656,
-    menvcfg = 664,
-    stvec = 672,
-    sscratch = 680,
-    sepc = 688,
-    scause = 696,
-    stval = 704,
-    satp = 712,
-    scounteren = 720,
-    senvcfg = 728,
-    ilrsc = 736,
-    iprv = 744,
-    iflags_X = 752,
-    iflags_Y = 760,
-    iflags_H = 768,
-    iunrep = 776,
-    clint_mtimecmp = 784,
-    plic_girqpend = 792,
-    plic_girqsrvd = 800,
-    htif_tohost = 808,
-    htif_fromhost = 816,
-    htif_ihalt = 824,
-    htif_iconsole = 832,
-    htif_iyield = 840,
-}
-for i = 0, 31 do
-    cpu_reg_addr["x" .. i] = i * 8
-end
-
 local function get_uarch_cpu_reg_test_values()
-    local processor = {}
+    local registers = {}
     for i = 0, 31 do
-        processor["x" .. i] = 0x10000 + (i * 8)
+        registers["x" .. i] = 0x10000 + (i * 8)
     end
-    return processor
+    return registers
 end
 
 local function get_cpu_reg_test_values()
@@ -269,13 +221,16 @@ local function build_machine_config(config_options)
     -- Create new machine
     local initial_reg_values = get_cpu_reg_test_values()
     local config = {
-        processor = config_options.processor or initial_reg_values,
+        processor = config_options.processor or {
+            registers = initial_reg_values,
+        },
         ram = { length = 1 << 20 },
-        htif = config_options.htif or nil,
         cmio = config_options.cmio or nil,
         uarch = config_options.uarch
             or {
-                processor = get_uarch_cpu_reg_test_values(),
+                processor = {
+                    registers = get_uarch_cpu_reg_test_values(),
+                },
                 ram = {
                     length = 0x1000,
                     backing_store = {
@@ -327,8 +282,7 @@ do_test("machine should have default config shadow register values", function(ma
     initial_reg_values.mimpid = nil
     -- Check initialization and shadow reads
     for k, v in pairs(initial_reg_values) do
-        local r = machine:read_word(cpu_reg_addr[k])
-        assert(v == r)
+        assert(v == machine:read_word(machine:get_reg_address(k)))
     end
 end)
 
@@ -351,9 +305,9 @@ end)
 print("\n\ntesting get_reg_address function binding")
 do_test("should return address value for registers", function(machine)
     -- Check register address
-    for k, v in pairs(cpu_reg_addr) do
-        local u = machine:get_reg_address(k)
-        assert(u == v, "invalid return for " .. v)
+    local initial_reg_values = get_cpu_reg_test_values()
+    for k, v in pairs(initial_reg_values) do
+        assert(machine:read_reg(k) == machine:read_word(machine:get_reg_address(k)), "invalid return for " .. v)
     end
 end)
 
@@ -420,9 +374,6 @@ local function test_config(config)
         "dtb",
         "flash_drive",
         "tlb",
-        "clint",
-        "plic",
-        "htif",
         "virtio",
         "cmio",
         "pmas",
@@ -430,13 +381,13 @@ local function test_config(config)
         "hash_tree",
     }
     for _, field in ipairs(config_fields) do
-        assertfield(config, field, "table")
+        assertfield(config, field, "table", "config", "needed")
     end
     for i = 0, 31 do
-        assertfield(config, "processor.x" .. i, "number")
+        assertfield(config.processor, "registers.x" .. i, "number", "processor", "needed")
     end
     for i = 0, 31 do
-        assertfield(config, "processor.f" .. i, "number")
+        assertfield(config.processor, "registers.f" .. i, "number", "processor", "needed")
     end
     local csrs = {
         "pc",
@@ -469,22 +420,22 @@ local function test_config(config)
         "senvcfg",
         "ilrsc",
         "iprv",
-        "iflags_X",
-        "iflags_Y",
-        "iflags_H",
+        "iflags.X",
+        "iflags.Y",
+        "iflags.H",
         "iunrep",
+        "htif.ihalt",
+        "htif.iconsole",
+        "htif.iyield",
+        "htif.tohost",
+        "htif.fromhost",
+        "clint.mtimecmp",
+        "plic.girqpend",
+        "plic.girqsrvd",
     }
     for _, csr in ipairs(csrs) do
-        assertfield(config, "processor." .. csr, "number")
+        assertfield(config.processor, "registers." .. csr, "number", "processor", "needed")
     end
-    assertfield(config, "htif.console_getchar", "boolean")
-    assertfield(config, "htif.yield_manual", "boolean")
-    assertfield(config, "htif.yield_automatic", "boolean")
-    assertfield(config, "htif.tohost", "number")
-    assertfield(config, "htif.fromhost", "number")
-    assertfield(config, "clint.mtimecmp", "number")
-    assertfield(config, "plic.girqpend", "number")
-    assertfield(config, "plic.girqsrvd", "number")
     assertfield(config, "ram.length", "number")
     test_backing_store_config(config, "ram.backing_store")
     assertfield(config, "dtb.bootargs", "string")
@@ -533,16 +484,19 @@ do_test("should have expected values", function(machine)
     -- Check initial config
     local initial_config = machine:get_initial_config()
     test_config(initial_config)
-    assert(initial_config.processor.pc == 0x200, "wrong pc reg initial config value")
-    assert(initial_config.processor.ilrsc == 0x2e0, "wrong ilrsc reg initial config value")
-    assert(initial_config.processor.mstatus == 0x230, "wrong mstatus reg initial config value")
-    assert(initial_config.clint.mtimecmp == 0, "wrong clint mtimecmp initial config value")
-    assert(initial_config.plic.girqpend == 0, "wrong plic girqpend initial config value")
-    assert(initial_config.plic.girqsrvd == 0, "wrong plic girqsrvd initial config value")
-    assert(initial_config.htif.fromhost == 0, "wrong htif fromhost initial config value")
-    assert(initial_config.htif.tohost == 0, "wrong htif tohost initial config value")
-    assert(initial_config.htif.yield_automatic == true, "wrong htif yield automatic initial config value")
-    assert(initial_config.htif.yield_manual == true, "wrong htif yield manual initial config value")
+    assert(initial_config.processor.registers.pc == 0x200, "wrong pc reg initial config value")
+    assert(initial_config.processor.registers.ilrsc == 0x2e0, "wrong ilrsc reg initial config value")
+    assert(initial_config.processor.registers.mstatus == 0x230, "wrong mstatus reg initial config value")
+    assert(initial_config.processor.registers.clint.mtimecmp == 0, "wrong clint mtimecmp initial config value")
+    assert(initial_config.processor.registers.plic.girqpend == 0, "wrong plic girqpend initial config value")
+    assert(initial_config.processor.registers.plic.girqsrvd == 0, "wrong plic girqsrvd initial config value")
+    assert(initial_config.processor.registers.htif.fromhost == 0, "wrong htif fromhost initial config value")
+    assert(initial_config.processor.registers.htif.tohost == 0, "wrong htif tohost initial config value")
+    assert(
+        initial_config.processor.registers.htif.iyield
+            == cartesi.HTIF_YIELD_CMD_MANUAL_MASK | cartesi.HTIF_YIELD_CMD_AUTOMATIC_MASK,
+        "wrong htif yield automatic initial config value"
+    )
 end)
 
 print("\n\n test read_reg")
@@ -555,7 +509,7 @@ do_test("should return expected values", function(machine)
     initial_reg_values.htif_fromhost = 0x0
     initial_reg_values.htif_ihalt = 0x0
     initial_reg_values.htif_iconsole = 0x0
-    initial_reg_values.htif_iyield = 3
+    initial_reg_values.htif_iyield = cartesi.HTIF_YIELD_CMD_MANUAL_MASK | cartesi.HTIF_YIELD_CMD_AUTOMATIC_MASK
 
     -- Check register read
     local to_ignore = {
@@ -569,7 +523,7 @@ do_test("should return expected values", function(machine)
         htif_ihalt = true,
         htif_iconsole = true,
     }
-    for k in pairs(cpu_reg_addr) do
+    for k in pairs(initial_reg_values) do
         if not to_ignore[k] then
             assert(machine:read_reg(k) == initial_reg_values[k], "wrong " .. k .. " value")
         end
@@ -864,7 +818,7 @@ test_util.make_do_test(build_machine, machine_type, {
     assert(ram_image == expected_ram_image)
 end)
 
-test_util.make_do_test(build_machine, machine_type, { processor = { mcycle = 1 }, uarch = {} })(
+test_util.make_do_test(build_machine, machine_type, { processor = { registers = { mcycle = 1 } }, uarch = {} })(
     "It should use the embedded uarch-ram.bin when the uarch config is not provided",
     function(machine)
         assert(machine:read_reg("mcycle") == 1)
@@ -909,13 +863,15 @@ test_util.make_do_test(build_machine, machine_type, { uarch = {} })(
 
 local test_reset_uarch_config = {
     processor = {
-        halt_flag = 1,
-        cycle = 1,
-        pc = 0,
+        registers = {
+            halt_flag = 1,
+            cycle = 1,
+            pc = 0,
+        },
     },
 }
 for i = 0, 31 do
-    test_reset_uarch_config.processor["x" .. i] = 0x10000 + (i * 8)
+    test_reset_uarch_config.processor.registers["x" .. i] = 0x10000 + (i * 8)
 end
 
 local function test_reset_uarch(machine, with_log, with_annotations)
@@ -924,7 +880,7 @@ local function test_reset_uarch(machine, with_log, with_annotations)
     assert(machine:read_reg("uarch_cycle") == 1)
     assert(machine:read_reg("uarch_pc") == 0)
     for i = 1, 31 do
-        assert(machine:read_reg("uarch_x" .. i) == test_reset_uarch_config.processor["x" .. i])
+        assert(machine:read_reg("uarch_x" .. i) == test_reset_uarch_config.processor.registers["x" .. i])
     end
     -- modify uarch ram
     local gibberish = "mydataol12345678"
@@ -1195,7 +1151,7 @@ do_test("uarch ecall putchar should print char to console", function()
                                  }
                                  local uarch_ram_path = test_util.create_test_uarch_program(program)
                                  local machine = cartesi.machine {
-                                     processor = initial_reg_values,
+                                     registers = initial_reg_values,
                                      ram = {length = 1 << 20},
                                      uarch = {
                                         ram = { backing_store = { data_filename = uarch_ram_path } }
@@ -1336,14 +1292,14 @@ do_test("Dump of log produced by send_cmio_response should match", function(mach
     local data = "0123456789"
     local reason = 7
     local log = machine:log_send_cmio_response(reason, data, cartesi.ACCESS_LOG_TYPE_ANNOTATIONS)
-    -- luacheck: push no max line length
-    local expected_dump = "begin send_cmio_response\n"
-        .. "  1: read iflags.Y@0x2f8(760): 0x1(1)\n"
-        .. '  2: write cmio rx buffer@0x60000000(1610612736): hash:"290decd9"(2^5 bytes) -> hash:"555b1f6d"(2^5 bytes)\n'
-        .. "  3: write htif.fromhost@0x330(816): 0x0(0) -> 0x70000000a(30064771082)\n"
-        .. "  4: write iflags.Y@0x2f8(760): 0x1(1) -> 0x0(0)\n"
-        .. "end send_cmio_response\n"
-    -- luacheck: pop
+    local expected_dump = [[
+begin send_cmio_response
+  1: read iflags.Y@0x300(768): 0x1(1)
+  2: write cmio rx buffer@0x60000000(1610612736): hash:"290decd9"(2^5 bytes) -> hash:"555b1f6d"(2^5 bytes)
+  3: write htif.fromhost@0x330(816): 0x0(0) -> 0x70000000a(30064771082)
+  4: write iflags.Y@0x300(768): 0x1(1) -> 0x0(0)
+end send_cmio_response
+]]
     local temp_file <close> = test_util.new_temp_file()
     util.dump_log(log, temp_file)
     local actual_dump = temp_file:read_all()
diff --git a/tests/lua/machine-test.lua b/tests/lua/machine-test.lua
index 2e09eb7f3..a39490169 100755
--- a/tests/lua/machine-test.lua
+++ b/tests/lua/machine-test.lua
@@ -154,9 +154,9 @@ do_test("machine halt and yield flags and config matches", function(machine)
     -- Get machine default config  and test for known fields
     local initial_config = machine:get_initial_config()
     -- test_util.print_table(initial_config)
-    assert(initial_config["processor"]["marchid"] == cartesi.MARCHID, "marchid value does not match")
-    assert(initial_config["processor"]["pc"] == cartesi.AR_RAM_START, "pc value does not match")
-    assert(initial_config["ram"]["length"] == 1048576, "ram length value does not match")
+    assert(initial_config.processor.registers.marchid == cartesi.MARCHID, "marchid value does not match")
+    assert(initial_config.processor.registers.pc == cartesi.AR_RAM_START, "pc value does not match")
+    assert(initial_config.ram.length == 1048576, "ram length value does not match")
     -- Check machine is not halted
     assert(machine:read_reg("iflags_H") == 0, "machine shouldn't be halted")
     -- Check machine is not yielded
@@ -340,7 +340,6 @@ end)
 
 print("\n\n check replace flash drives")
 test_util.make_do_test(build_machine, machine_type, {
-    processor = {},
     ram = { length = 1 << 20 },
     flash_drive = {
         {
diff --git a/tests/lua/run-rv64i-arch-test.lua b/tests/lua/run-rv64i-arch-test.lua
index bce7540c6..bbed08695 100755
--- a/tests/lua/run-rv64i-arch-test.lua
+++ b/tests/lua/run-rv64i-arch-test.lua
@@ -49,7 +49,6 @@ local config = {
             },
         },
     },
-    processor = {},
     ram = { length = 0x1000 },
 }
 
diff --git a/tests/lua/test-jsonrpc-fork.lua b/tests/lua/test-jsonrpc-fork.lua
index 97ffcb7b1..8c7ea6146 100755
--- a/tests/lua/test-jsonrpc-fork.lua
+++ b/tests/lua/test-jsonrpc-fork.lua
@@ -117,7 +117,7 @@ local function fork_tree(address, x, depth)
     if depth == 0 then
         local config = machine:get_default_config()
         x = {}
-        for k, v in pairs(config.processor) do
+        for k, v in pairs(config.processor.registers) do
             if k:sub(1, 1) == "x" then
                 x[tonumber(k:sub(2))] = v
             end
diff --git a/tests/misc/test-machine-c-api.cpp b/tests/misc/test-machine-c-api.cpp
index 8ab7904bf..6e92c4efe 100644
--- a/tests/misc/test-machine-c-api.cpp
+++ b/tests/misc/test-machine-c-api.cpp
@@ -1016,7 +1016,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(read_write_f_basic_test, ordinary_machine_fixture
 
     uint64_t f2_addr{};
     BOOST_CHECK_EQUAL(cm_get_reg_address(_machine, CM_REG_F2, &f2_addr), CM_ERROR_OK);
-    BOOST_CHECK_EQUAL(static_cast<uint64_t>(0x110), f2_addr);
+    BOOST_CHECK_EQUAL(static_cast<uint64_t>(0x128), f2_addr);
 }
 
 BOOST_FIXTURE_TEST_CASE_NOLINT(read_write_uarch_x_basic_test, ordinary_machine_fixture) {
@@ -1067,7 +1067,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(read_write_reg_basic_test, ordinary_machine_fixtu
 
     uint64_t pc_addr{};
     BOOST_CHECK_EQUAL(cm_get_reg_address(_machine, CM_REG_PC, &pc_addr), CM_ERROR_OK);
-    BOOST_CHECK_EQUAL(static_cast<uint64_t>(0x200), pc_addr);
+    BOOST_CHECK_EQUAL(static_cast<uint64_t>(0x108), pc_addr);
 }
 
 BOOST_AUTO_TEST_CASE_NOLINT(verify_merkle_tree_null_machine_test) {

From 25b839aaca6dc28d05a2bf52b89cc17183c2922c Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Thu, 27 Mar 2025 11:36:17 -0300
Subject: [PATCH 35/82] refactor: remove unneeded fields from states

---
 .gitignore                                    |    1 +
 src/Makefile                                  |   11 +-
 src/address-range-constants.h                 |   22 +-
 src/address-range-defines.h                   |    8 +-
 src/address-range.h                           |   20 +
 src/cartesi-machine.lua                       |   46 +-
 src/hot-tlb.h                                 |   53 +
 src/i-prefer-shadow-state.h                   |   12 +-
 src/i-prefer-shadow-uarch-state.h             |    2 +-
 src/i-state-access.h                          |   46 +-
 src/i-uarch-state-access.h                    |    2 +-
 src/interpret.cpp                             |   68 +-
 src/json-util.cpp                             |   10 +-
 src/jsonrpc-discover.json                     |   24 +-
 src/machine-address-ranges.cpp                |  153 +--
 src/machine-address-ranges.h                  |    5 +-
 src/machine-config.cpp                        |   36 +-
 src/machine-config.h                          |   23 +-
 src/machine-reg.h                             |  219 ++--
 src/machine-state.h                           |   58 -
 src/machine.cpp                               | 1101 ++++++++---------
 src/machine.h                                 |   71 +-
 src/memory-address-range.cpp                  |   61 +-
 src/memory-address-range.h                    |   70 +-
 src/mock-address-range.h                      |   16 +-
 src/os-features.h                             |    4 +
 src/os-mmap.cpp                               |  650 ++++++++++
 src/os-mmap.h                                 |  123 ++
 src/os.cpp                                    |  164 +--
 src/os.h                                      |    6 -
 src/pmas-constants.h                          |    1 -
 src/pmas-defines.h                            |   23 +-
 src/pmas.h                                    |   10 +-
 src/processor-state.h                         |   73 ++
 src/record-send-cmio-state-access.h           |   10 +-
 src/record-step-state-access.h                |   21 +-
 src/replay-send-cmio-state-access.h           |    2 +-
 src/replay-step-state-access.h                |   12 +-
 src/shadow-peek.h                             |   67 -
 src/{shadow-state.h => shadow-registers.h}    |  242 ++--
 src/shadow-state-address-range.cpp            |   47 -
 src/shadow-state-address-range.h              |   72 --
 src/shadow-tlb-address-range.cpp              |   48 -
 src/shadow-tlb-address-range.h                |   72 --
 src/shadow-tlb-factory.h                      |   35 -
 src/shadow-tlb.h                              |   48 +-
 src/shadow-uarch-state-address-range.cpp      |   50 -
 src/shadow-uarch-state-address-range.h        |   73 --
 src/state-access.h                            |  170 +--
 src/tlb.h                                     |  101 --
 ...{uarch-state.h => uarch-processor-state.h} |   23 +-
 src/uarch-record-state-access.h               |    2 +-
 src/unique-c-ptr.h                            |   19 -
 tests/lua/machine-bind.lua                    |    4 +-
 tests/misc/test-machine-c-api.cpp             |   14 +-
 uarch/compute-uarch-pristine-hash.cpp         |    2 +-
 uarch/machine-uarch-bridge-state-access.h     |    6 +-
 57 files changed, 2194 insertions(+), 2138 deletions(-)
 create mode 100644 src/hot-tlb.h
 delete mode 100644 src/machine-state.h
 create mode 100644 src/os-mmap.cpp
 create mode 100644 src/os-mmap.h
 create mode 100644 src/processor-state.h
 delete mode 100644 src/shadow-peek.h
 rename src/{shadow-state.h => shadow-registers.h} (53%)
 delete mode 100644 src/shadow-state-address-range.cpp
 delete mode 100644 src/shadow-state-address-range.h
 delete mode 100644 src/shadow-tlb-address-range.cpp
 delete mode 100644 src/shadow-tlb-address-range.h
 delete mode 100644 src/shadow-tlb-factory.h
 delete mode 100644 src/shadow-uarch-state-address-range.cpp
 delete mode 100644 src/shadow-uarch-state-address-range.h
 delete mode 100644 src/tlb.h
 rename src/{uarch-state.h => uarch-processor-state.h} (64%)

diff --git a/.gitignore b/.gitignore
index 0772c58de..80b58149a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,6 +6,7 @@
 *.a
 *.lib
 *.wasm
+*.TODO
 
 build
 pkg
diff --git a/src/Makefile b/src/Makefile
index 8eee948ad..03761c571 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -157,7 +157,8 @@ CARTESI_MERKLE_TREE_HASH_LIBS=
 
 #DEFS+= -DMT_ALL_DIRTY
 
-WARNS=-Wall -Wextra -Wpedantic
+C_WARNS=-Wall -Wextra -Wpedantic
+CXX_WARNS=$(C_WARNS) -Wno-missing-field-initializers
 CLANG_TIDY_WARNS=-Wthread-safety -Wglobal-constructors
 
 # Place our include directories before the system's
@@ -310,8 +311,8 @@ else
 DEFS+=-DNO_THREADS
 endif
 
-CXXFLAGS+=$(OPTFLAGS) -std=gnu++20 -fvisibility=hidden -MMD $(PICCFLAGS) $(CC_MARCH) $(INCS) $(GCFLAGS) $(UBCFLAGS) $(DEFS) $(WARNS)
-CFLAGS+=$(OPTFLAGS) -std=gnu99 -fvisibility=hidden -MMD $(PICCFLAGS) $(CC_MARCH) $(INCS) $(GCFLAGS) $(UBCFLAGS) $(DEFS) $(WARNS)
+CXXFLAGS+=$(OPTFLAGS) -std=gnu++20 -fvisibility=hidden -MMD $(PICCFLAGS) $(CC_MARCH) $(INCS) $(GCFLAGS) $(UBCFLAGS) $(DEFS) $(CXX_WARNS)
+CFLAGS+=$(OPTFLAGS) -std=gnu99 -fvisibility=hidden -MMD $(PICCFLAGS) $(CC_MARCH) $(INCS) $(GCFLAGS) $(UBCFLAGS) $(DEFS) $(C_WARNS)
 LDFLAGS+=$(UBLDFLAGS)
 
 ifeq ($(coverage),yes)
@@ -363,14 +364,12 @@ LIBCARTESI_OBJS:= \
 	machine-address-ranges.o \
 	memory-address-range.o \
 	os.o \
+	os-mmap.o \
 	plic-address-range.o \
 	pristine-merkle-tree.o \
 	replay-step-state-access-interop.o \
 	send-cmio-response.o \
 	sha3.o \
-	shadow-state-address-range.o \
-	shadow-tlb-address-range.o \
-	shadow-uarch-state-address-range.o \
 	uarch-pristine-hash.o \
 	uarch-pristine-ram.o \
 	uarch-pristine-state-hash.o \
diff --git a/src/address-range-constants.h b/src/address-range-constants.h
index 1c4fdb65f..77f07e279 100644
--- a/src/address-range-constants.h
+++ b/src/address-range-constants.h
@@ -25,14 +25,16 @@ namespace cartesi {
 
 /// \brief Fixed address ranges.
 enum AR_ranges : uint64_t {
-    AR_SHADOW_STATE_START = EXPAND_UINT64_C(AR_SHADOW_STATE_START_DEF),   ///< Start of shadow state range
-    AR_SHADOW_STATE_LENGTH = EXPAND_UINT64_C(AR_SHADOW_STATE_LENGTH_DEF), ///< Length of shadow state range
-    AR_PMAS_START = EXPAND_UINT64_C(AR_PMAS_START_DEF),                   ///< Start of PMAS list range
-    AR_PMAS_LENGTH = EXPAND_UINT64_C(AR_PMAS_LENGTH_DEF),                 ///< Length of PMAS list range
-    AR_DTB_START = EXPAND_UINT64_C(AR_DTB_START_DEF),                     ///< Start of DTB range
-    AR_DTB_LENGTH = EXPAND_UINT64_C(AR_DTB_LENGTH_DEF),                   ///< Length of DTB range
-    AR_SHADOW_TLB_START = EXPAND_UINT64_C(AR_SHADOW_TLB_START_DEF),       ///< Start of shadow TLB range
-    AR_SHADOW_TLB_LENGTH = EXPAND_UINT64_C(AR_SHADOW_TLB_LENGTH_DEF),     ///< Length of shadow TLB range
+    AR_SHADOW_STATE_START = EXPAND_UINT64_C(AR_SHADOW_STATE_START_DEF),           ///< Start of shadow state range
+    AR_SHADOW_STATE_LENGTH = EXPAND_UINT64_C(AR_SHADOW_STATE_LENGTH_DEF),         ///< Length of shadow state range
+    AR_SHADOW_REGISTERS_START = EXPAND_UINT64_C(AR_SHADOW_REGISTERS_START_DEF),   ///< Start of shadow registers range
+    AR_SHADOW_REGISTERS_LENGTH = EXPAND_UINT64_C(AR_SHADOW_REGISTERS_LENGTH_DEF), ///< Length of shadow registers range
+    AR_SHADOW_TLB_START = EXPAND_UINT64_C(AR_SHADOW_TLB_START_DEF),               ///< Start of shadow TLB range
+    AR_SHADOW_TLB_LENGTH = EXPAND_UINT64_C(AR_SHADOW_TLB_LENGTH_DEF),             ///< Length of shadow TLB range
+    AR_PMAS_START = EXPAND_UINT64_C(AR_PMAS_START_DEF),                           ///< Start of PMAS list range
+    AR_PMAS_LENGTH = EXPAND_UINT64_C(AR_PMAS_LENGTH_DEF),                         ///< Length of PMAS list range
+    AR_DTB_START = EXPAND_UINT64_C(AR_DTB_START_DEF),                             ///< Start of DTB range
+    AR_DTB_LENGTH = EXPAND_UINT64_C(AR_DTB_LENGTH_DEF),                           ///< Length of DTB range
     AR_SHADOW_UARCH_STATE_START =
         EXPAND_UINT64_C(AR_SHADOW_UARCH_STATE_START_DEF), ///< Start of uarch shadow state range
     AR_SHADOW_UARCH_STATE_LENGTH =
@@ -61,6 +63,10 @@ enum AR_ranges : uint64_t {
     AR_RAM_START = EXPAND_UINT64_C(AR_RAM_START_DEF), ///< Start of RAM range
 };
 
+static_assert(AR_SHADOW_STATE_LENGTH >= AR_SHADOW_REGISTERS_LENGTH + AR_SHADOW_TLB_LENGTH);
+static_assert(AR_SHADOW_TLB_START == AR_SHADOW_REGISTERS_START + AR_SHADOW_REGISTERS_LENGTH);
+static_assert(AR_SHADOW_STATE_START == AR_SHADOW_REGISTERS_START);
+
 /// \brief PMA constants.
 enum AR_constants : uint64_t {
     AR_PAGE_SIZE_LOG2 = EXPAND_UINT64_C(AR_PAGE_SIZE_LOG2_DEF), ///< Log<sub>2</sub> of physical memory page size.
diff --git a/src/address-range-defines.h b/src/address-range-defines.h
index 4f49e9141..dd89cc9a9 100644
--- a/src/address-range-defines.h
+++ b/src/address-range-defines.h
@@ -19,11 +19,13 @@
 
 // NOLINTBEGIN(cppcoreguidelines-macro-usage,cppcoreguidelines-macro-to-enum,modernize-macro-to-enum)
 #define AR_SHADOW_STATE_START_DEF 0x0            ///< Shadow start address
-#define AR_SHADOW_STATE_LENGTH_DEF 0x1000        ///< Shadow length in bytes
+#define AR_SHADOW_STATE_LENGTH_DEF 0x8000        ///< Shadow length in bytes
+#define AR_SHADOW_REGISTERS_START_DEF 0x0        ///< Shadow registers start address
+#define AR_SHADOW_REGISTERS_LENGTH_DEF 0x1000    ///< Shadow registers length in bytes
+#define AR_SHADOW_TLB_START_DEF 0x1000           ///< Shadow TLB start address
+#define AR_SHADOW_TLB_LENGTH_DEF 0x6000          ///< Shadow TLB length in bytes
 #define AR_PMAS_START_DEF 0x10000                ///< PMA Array start address
 #define AR_PMAS_LENGTH_DEF 0x1000                ///< PMA Array length in bytes
-#define AR_SHADOW_TLB_START_DEF 0x20000          ///< TLB start address
-#define AR_SHADOW_TLB_LENGTH_DEF 0x6000          ///< TLB length in bytes
 #define AR_SHADOW_UARCH_STATE_START_DEF 0x400000 ///< microarchitecture shadow state start address
 #define AR_SHADOW_UARCH_STATE_LENGTH_DEF 0x1000  ///< microarchitecture shadow state length
 #define AR_UARCH_RAM_START_DEF 0x600000          ///< microarchitecture RAM start address
diff --git a/src/address-range.h b/src/address-range.h
index 17f4c5a20..fc53811d1 100644
--- a/src/address-range.h
+++ b/src/address-range.h
@@ -323,6 +323,18 @@ class address_range {
         return do_is_page_marked_dirty(offset);
     }
 
+    /// \brief Returns true if the mapped memory is read-only on the host
+    /// \returns True if the memory is read-only in the host
+    bool is_host_read_only() const noexcept {
+        return do_is_host_read_only();
+    }
+
+    /// \brief Returns true if pages marked as dirty once are uncleanable
+    /// \returns True if and only if dirty pages are uncleanable
+    bool is_page_uncleanable() const noexcept {
+        return do_is_page_uncleanable();
+    }
+
 private:
     // Default implementation of peek() always fails
     virtual bool do_peek(const machine & /*m*/, uint64_t /*offset*/, uint64_t /*length*/,
@@ -367,6 +379,14 @@ class address_range {
     virtual bool do_is_page_marked_dirty(uint64_t /*offset*/) const noexcept {
         return true;
     }
+
+    virtual bool do_is_host_read_only() const noexcept {
+        return false;
+    }
+
+    virtual bool do_is_page_uncleanable() const noexcept {
+        return false;
+    }
 };
 
 template <size_t N>
diff --git a/src/cartesi-machine.lua b/src/cartesi-machine.lua
index 2663917e5..80c36b181 100755
--- a/src/cartesi-machine.lua
+++ b/src/cartesi-machine.lua
@@ -107,6 +107,9 @@ where options are:
         data_filename:<filename>
         dht_filename:<filename>
         shared
+        create
+        truncate
+        read_only
         mount:<string>
         user:<string>
 
@@ -137,6 +140,18 @@ where options are:
         target modifications to flash drive modify the memory and hash tree files.
         by default, image files are not modified and changes are lost.
 
+        create (optional)
+        create the backing storage file, shared must also be true.
+
+        truncate (optional)
+        truncate the memory length to match memory lengths different from the backing storage,
+        in case of shared flash drive, then it also truncates the underlying backing file.
+        by default, when a length is present it must also match the backing storage length.
+
+        read_only (optional)
+        mark flash drive as read-only, disallowing write attempts from the host or the guest.
+        by default, flash drives are not read-only, thus writable.
+
         mount (optional)
         whether the flash drive should be mounted automatically in init.
         by default, the drive is mounted if there is an image file backing it,
@@ -171,11 +186,12 @@ where options are:
 
   --ram=<key>:<value>[,<key>:<value>[,...]...]
   --dtb=<key>:<value>[,<key>:<value>[,...]...]
-  --tlb=<key>:<value>[,<key>:<value>[,...]...]
+  --processor=<key>:<value>[,<key>:<value>[,...]...]
   --cmio-rx-buffer=<key>:<value>[,<key>:<value>[,...]...]
   --cmio-tx-buffer=<key>:<value>[,<key>:<value>[,...]...]
   --pmas=<key>:<value>[,<key>:<value>[,...]...]
   --uarch-ram=<key>:<value>[,<key>:<value>[,...]...]
+  --uarch-processor=<key>:<value>[,<key>:<value>[,...]...]
     configures file storage for other memory ranges in the machine
 
     <key>:<value> is one of
@@ -614,6 +630,9 @@ local flash_data_filename = { root = images_path .. "rootfs.ext2" }
 local flash_dht_filename = {}
 local flash_label_order = { "root" }
 local flash_shared = {}
+local flash_create = {}
+local flash_truncate = {}
+local flash_read_only = {}
 local flash_mount = {}
 local flash_user = {}
 local flash_start = {}
@@ -1013,13 +1032,6 @@ local options = {
             return true
         end,
     },
-    {
-        "^(%-%-tlb%=(.+))$",
-        function(all, opts)
-            tlb.backing_store = parse_backing_store(opts, "tlb", all, tlb.backing_store)
-            return true
-        end,
-    },
     {
         "^(%-%-pmas%=(.+))$",
         function(all, opts)
@@ -1147,6 +1159,9 @@ local options = {
                 data_filename = true,
                 dht_filename = true,
                 shared = true,
+                create = true,
+                truncate = true,
+                read_only = true,
                 mount = true,
                 user = true,
                 length = true,
@@ -1156,6 +1171,9 @@ local options = {
             if f.data_filename == true then f.data_filename = "" end
             if f.dht_filename == true then f.dht_filename = "" end
             assert(not f.shared or f.shared == true, "invalid flash drive shared value in " .. all)
+            assert(not f.create or f.create == true, "invalid flash drive create value in " .. all)
+            assert(not f.truncate or f.truncate == true, "invalid flash drive read_only value in " .. all)
+            assert(not f.read_only or f.read_only == true, "invalid flash drive truncate value in " .. all)
             if f.mount == nil then
                 -- mount only if there is a file backing
                 if f.data_filename and f.data_filename ~= "" then
@@ -1180,8 +1198,14 @@ local options = {
             flash_start[d] = f.start or flash_start[d]
             flash_length[d] = f.length or flash_length[d]
             flash_shared[d] = f.shared or flash_shared[d]
+            flash_create[d] = f.create or flash_create[d]
+            flash_truncate[d] = f.truncate or flash_truncate[d]
+            flash_read_only[d] = f.read_only or flash_read_only[d]
             flash_mount[d] = f.mount or flash_mount[d]
             flash_user[d] = f.user or flash_user[d]
+            if d == "root" and f.read_only then -- Mount root filesystem as read-only
+                dtb.bootargs = dtb.bootargs:gsub("rw", "ro")
+            end
             return true
         end,
     },
@@ -1336,6 +1360,9 @@ local options = {
             flash_start.root = nil
             flash_length.root = nil
             flash_shared.root = nil
+            flash_create.root = nil
+            flash_truncate.root = nil
+            flash_read_only.root = nil
             table.remove(flash_label_order, 1)
             dtb.bootargs = dtb.bootargs:gsub(" root=$", "")
             return true
@@ -1848,7 +1875,10 @@ echo "
                 data_filename = flash_data_filename[label],
                 dht_filename = flash_dht_filename[label],
                 shared = flash_shared[label],
+                create = flash_create[label],
+                truncate = flash_truncate[label],
             },
+            read_only = flash_read_only[label],
             start = flash_start[label],
             length = flash_length[label] or -1,
         }
diff --git a/src/hot-tlb.h b/src/hot-tlb.h
new file mode 100644
index 000000000..471d461c3
--- /dev/null
+++ b/src/hot-tlb.h
@@ -0,0 +1,53 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef HOT_TLB_H
+#define HOT_TLB_H
+
+/// \file
+/// \brief TLB definitions
+/// \details The Translation Lookaside Buffer is a small cache used to speed up translation between address spaces.
+
+#include <array>
+#include <cstddef>
+#include <cstdint>
+
+#include "host-addr.h"
+#include "shadow-tlb.h"
+
+namespace cartesi {
+
+/// \brief Hot TLB slot.
+/// \details
+/// Given a target virtual address vaddr within a page matching vaddr_page in TLB slot, the corresponding host address
+/// haddr = vaddr + vh_offset.
+struct hot_tlb_slot final {
+    uint64_t vaddr_page{TLB_INVALID_PAGE}; ///< Target virtual address of start of page
+    host_addr vh_offset{0};                ///< Offset from target virtual address in the same page to host address
+};
+
+using hot_tlb_set = std::array<hot_tlb_slot, TLB_SET_SIZE>;
+using hot_tlb_state = std::array<hot_tlb_set, TLB_NUM_SETS_>;
+
+static_assert(sizeof(uint64_t) >= sizeof(uintptr_t), "TLB expects host pointer fit in 64 bits");
+
+// We need to ensure TLB state sizes are fixed across different platforms
+static_assert(sizeof(hot_tlb_state) == 3 * TLB_SET_SIZE * 2 * sizeof(uint64_t), "unexpected hot TLB state size");
+static_assert(alignof(hot_tlb_state) == sizeof(uint64_t), "unexpected hot TLB state alignment");
+
+} // namespace cartesi
+
+#endif
diff --git a/src/i-prefer-shadow-state.h b/src/i-prefer-shadow-state.h
index 4d4f83213..dd75b9f56 100644
--- a/src/i-prefer-shadow-state.h
+++ b/src/i-prefer-shadow-state.h
@@ -25,8 +25,8 @@
 #include <type_traits>
 
 #include "meta.h"
-#include "shadow-state.h"
-#include "tlb.h"
+#include "shadow-registers.h"
+#include "shadow-tlb.h"
 
 namespace cartesi {
 
@@ -48,12 +48,12 @@ class i_prefer_shadow_state { // CRTP
     }
 
 public:
-    uint64_t read_shadow_state(shadow_state_what what) const {
-        return derived().do_read_shadow_state(what);
+    uint64_t read_shadow_register(shadow_registers_what what) const {
+        return derived().do_read_shadow_register(what);
     }
 
-    void write_shadow_state(shadow_state_what what, uint64_t val) const {
-        derived().do_write_shadow_state(what, val);
+    void write_shadow_register(shadow_registers_what what, uint64_t val) const {
+        derived().do_write_shadow_register(what, val);
     }
 };
 
diff --git a/src/i-prefer-shadow-uarch-state.h b/src/i-prefer-shadow-uarch-state.h
index f540cff75..af9319cf1 100644
--- a/src/i-prefer-shadow-uarch-state.h
+++ b/src/i-prefer-shadow-uarch-state.h
@@ -25,8 +25,8 @@
 #include <type_traits>
 
 #include "meta.h"
+#include "shadow-tlb.h"
 #include "shadow-uarch-state.h"
-#include "tlb.h"
 
 namespace cartesi {
 
diff --git a/src/i-state-access.h b/src/i-state-access.h
index c9cbb1a0d..e216b3d4e 100644
--- a/src/i-state-access.h
+++ b/src/i-state-access.h
@@ -30,7 +30,7 @@
 #include "i-prefer-shadow-state.h"
 #include "meta.h"
 #include "poor-type-name.h"
-#include "tlb.h"
+#include "shadow-tlb.h"
 
 namespace cartesi {
 
@@ -51,7 +51,7 @@ using i_state_access_fast_addr_t = typename i_state_access_fast_addr<STATE_ACCES
             dsa_printf("%s::read_" #REG "() = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), val, val);                    \
             return val;                                                                                                \
         } else {                                                                                                       \
-            return prefer_read_shadow_state(shadow_state_what::REG);                                                   \
+            return prefer_read_shadow_register(shadow_registers_what::REG);                                            \
         }                                                                                                              \
     }
 
@@ -61,7 +61,7 @@ using i_state_access_fast_addr_t = typename i_state_access_fast_addr<STATE_ACCES
             derived().do_write_##REG(val);                                                                             \
             dsa_printf("%s::write_" #REG "(%" PRIu64 "(0x%" PRIx64 "))\n", get_name(), val, val);                      \
         } else {                                                                                                       \
-            prefer_write_shadow_state(shadow_state_what::REG, val);                                                    \
+            prefer_write_shadow_register(shadow_registers_what::REG, val);                                             \
         }                                                                                                              \
     }
 // NOLINTEND(cppcoreguidelines-macro-usage)
@@ -102,17 +102,17 @@ class i_state_access { // CRTP
         return *static_cast<const DERIVED *>(this);
     }
 
-    uint64_t prefer_read_shadow_state(shadow_state_what what) const {
-        const auto val = derived().read_shadow_state(what);
-        [[maybe_unused]] const auto *const what_name = shadow_state_get_what_name(what);
-        dsa_printf("%s::read_shadow_state(%s) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), what_name, val, val);
+    uint64_t prefer_read_shadow_register(shadow_registers_what what) const {
+        const auto val = derived().read_shadow_register(what);
+        [[maybe_unused]] const auto *const what_name = shadow_registers_get_what_name(what);
+        dsa_printf("%s::read_shadow_register(%s) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), what_name, val, val);
         return val;
     }
 
-    void prefer_write_shadow_state(shadow_state_what what, uint64_t val) const {
-        derived().write_shadow_state(what, val);
-        [[maybe_unused]] const auto *const what_name = shadow_state_get_what_name(what);
-        dsa_printf("%s::write_shadow_state(%s, %" PRIu64 "(0x%" PRIx64 "))\n", get_name(), what_name, val, val);
+    void prefer_write_shadow_register(shadow_registers_what what, uint64_t val) const {
+        derived().write_shadow_register(what, val);
+        [[maybe_unused]] const auto *const what_name = shadow_registers_get_what_name(what);
+        dsa_printf("%s::write_shadow_register(%s, %" PRIu64 "(0x%" PRIx64 "))\n", get_name(), what_name, val, val);
     }
 
 public:
@@ -146,7 +146,7 @@ class i_state_access { // CRTP
             dsa_printf("%s::read_x(%d) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), i, val, val);
             return val;
         } else {
-            return prefer_read_shadow_state(shadow_state_get_what(shadow_state_what::x0, i));
+            return prefer_read_shadow_register(shadow_registers_get_what(shadow_registers_what::x0, i));
         }
     }
 
@@ -160,7 +160,7 @@ class i_state_access { // CRTP
             derived().do_write_x(i, val);
             dsa_printf("%s::write_x(%d, %" PRIu64 "(0x%" PRIx64 "))\n", get_name(), i, val, val);
         } else {
-            prefer_write_shadow_state(shadow_state_get_what(shadow_state_what::x0, i), val);
+            prefer_write_shadow_register(shadow_registers_get_what(shadow_registers_what::x0, i), val);
         }
     }
 
@@ -173,7 +173,7 @@ class i_state_access { // CRTP
             dsa_printf("%s::read_f(%d) = %" PRIu64 "(0x%" PRIx64 ")\n", get_name(), i, val, val);
             return val;
         } else {
-            return prefer_read_shadow_state(shadow_state_get_what(shadow_state_what::f0, i));
+            return prefer_read_shadow_register(shadow_registers_get_what(shadow_registers_what::f0, i));
         }
     }
 
@@ -185,7 +185,7 @@ class i_state_access { // CRTP
             derived().do_write_f(i, val);
             dsa_printf("%s::write_f(%d, %" PRIu64 "(%" PRIx64 "))\n", get_name(), i, val, val);
         } else {
-            prefer_write_shadow_state(shadow_state_get_what(shadow_state_what::f0, i), val);
+            prefer_write_shadow_register(shadow_registers_get_what(shadow_registers_what::f0, i), val);
         }
     }
 
@@ -377,15 +377,15 @@ class i_state_access { // CRTP
         return val;
     }
 
-    /// \brief Reads TLB's vp_offset
+    /// \brief Reads TLB's vf_offset
     /// \tparam USE TLB set
     /// \param slot_index Slot index
     /// \returns Value in slot.
     template <TLB_set_index SET>
-    fast_addr read_tlb_vp_offset(uint64_t slot_index) const {
+    fast_addr read_tlb_vf_offset(uint64_t slot_index) const {
         [[maybe_unused]] const auto fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
-        const auto val = derived().template do_read_tlb_vp_offset<SET>(slot_index);
-        dsa_printf("%s::read_tlb_vp_offset<%" PRIu64 ">(%" PRIu64 ") = %s{0x%" PRIx64 "}\n", get_name(), SET,
+        const auto val = derived().template do_read_tlb_vf_offset<SET>(slot_index);
+        dsa_printf("%s::read_tlb_vf_offset<%" PRIu64 ">(%" PRIu64 ") = %s{0x%" PRIx64 "}\n", get_name(), SET,
             slot_index, fast_addr_name, static_cast<uint64_t>(val));
         return val;
     }
@@ -406,16 +406,16 @@ class i_state_access { // CRTP
     /// \tparam USE TLB set
     /// \param slot_index Slot index
     /// \param vaddr_page Value to write
-    /// \param vp_offset Value to write
+    /// \param vf_offset Value to write
     /// \param pma_index Value to write
     /// \detail Writes to the TLB must be modify all fields atomically to prevent an inconsistent state.
     /// This simplifies all state access implementations.
     template <TLB_set_index SET>
-    void write_tlb(uint64_t slot_index, uint64_t vaddr_page, fast_addr vp_offset, uint64_t pma_index) const {
-        derived().template do_write_tlb<SET>(slot_index, vaddr_page, vp_offset, pma_index);
+    void write_tlb(uint64_t slot_index, uint64_t vaddr_page, fast_addr vf_offset, uint64_t pma_index) const {
+        derived().template do_write_tlb<SET>(slot_index, vaddr_page, vf_offset, pma_index);
         [[maybe_unused]] const auto fast_addr_name = std::is_same_v<fast_addr, uint64_t> ? "phys_addr" : "fast_addr";
         dsa_printf("%s::write_tlb<%" PRIu64 ">(%" PRIu64 ", 0x%" PRIx64 ", %s{0x%" PRIx64 "}, %" PRIu64 ")\n",
-            get_name(), SET, slot_index, vaddr_page, fast_addr_name, static_cast<uint64_t>(vp_offset), pma_index);
+            get_name(), SET, slot_index, vaddr_page, fast_addr_name, static_cast<uint64_t>(vf_offset), pma_index);
     }
 
     /// \brief Marks a page as dirty
diff --git a/src/i-uarch-state-access.h b/src/i-uarch-state-access.h
index 3e290c768..d697eb153 100644
--- a/src/i-uarch-state-access.h
+++ b/src/i-uarch-state-access.h
@@ -24,7 +24,7 @@
 #include "assert-printf.h"
 #include "i-prefer-shadow-uarch-state.h"
 #include "meta.h"
-#include "tlb.h"
+#include "shadow-tlb.h"
 
 // NOLINTBEGIN(cppcoreguidelines-macro-usage)
 #define DEFINE_USA_READ(REG)                                                                                           \
diff --git a/src/interpret.cpp b/src/interpret.cpp
index 11c5a6f31..d3ebc3c44 100644
--- a/src/interpret.cpp
+++ b/src/interpret.cpp
@@ -102,6 +102,7 @@
 #include "compiler-defines.h"
 #include "device-state-access.h"
 #include "find-pma.h"
+#include "hot-tlb.h"
 #include "i-accept-counters.h"
 #include "i-interactive-state-access.h"
 #include "i-state-access.h"
@@ -109,7 +110,6 @@
 #include "riscv-constants.h"
 #include "rtc.h"
 #include "soft-float.h"
-#include "tlb.h"
 #include "translate-virtual-address.h"
 #include "uint128.h"
 
@@ -876,16 +876,16 @@ static void flush_tlb_slot(const STATE_ACCESS a, uint64_t slot_index) {
         const auto old_vaddr_page = a.template read_tlb_vaddr_page<TLB_WRITE>(slot_index);
         if (old_vaddr_page != TLB_INVALID_PAGE) {
             auto old_pma_index = a.template read_tlb_pma_index<TLB_WRITE>(slot_index);
-            const auto old_faddr_page = old_vaddr_page + a.template read_tlb_vp_offset<TLB_WRITE>(slot_index);
+            const auto old_faddr_page = old_vaddr_page + a.template read_tlb_vf_offset<TLB_WRITE>(slot_index);
             a.mark_dirty_page(old_faddr_page, old_pma_index);
         }
     }
     // We do not leave garbage behind in empty slots
     // (It would make state access classes trickier to implement)
     const auto vaddr_page = TLB_INVALID_PAGE;
-    const auto vp_offset = i_state_access_fast_addr_t<STATE_ACCESS>{};
+    const auto vf_offset = i_state_access_fast_addr_t<STATE_ACCESS>{};
     const auto pma_index = TLB_INVALID_PMA_INDEX;
-    a.template write_tlb<SET>(slot_index, vaddr_page, vp_offset, pma_index);
+    a.template write_tlb<SET>(slot_index, vaddr_page, vf_offset, pma_index);
 }
 
 /// \brief Flushes out an entire TLB set
@@ -930,18 +930,18 @@ static void flush_tlb_vaddr(const STATE_ACCESS a, uint64_t /* vaddr */) {
 /// \param vaddr Virtual address of new mapping
 /// \param paddr Corresponding physical address
 /// \param paddr Index of PMA where paddr falls
-/// \param vp_offset Receives the new vp_offset that will be stored in the slot
+/// \param vf_offset Receives the new vf_offset that will be stored in the slot
 /// \returns The implementation-defined fast address corresponding to paddr
 template <TLB_set_index SET, typename STATE_ACCESS>
 static i_state_access_fast_addr_t<STATE_ACCESS> replace_tlb_entry(const STATE_ACCESS a, uint64_t vaddr, uint64_t paddr,
-    uint64_t pma_index, i_state_access_fast_addr_t<STATE_ACCESS> &vp_offset) {
+    uint64_t pma_index, i_state_access_fast_addr_t<STATE_ACCESS> &vf_offset) {
     [[maybe_unused]] auto note = a.make_scoped_note("replace_tlb_entry");
     const auto slot_index = tlb_slot_index(vaddr);
     flush_tlb_slot<SET>(a, slot_index);
     const auto vaddr_page = tlb_addr_page(vaddr);
     const auto faddr = a.get_faddr(paddr, pma_index);
-    vp_offset = faddr - vaddr;
-    a.template write_tlb<SET>(slot_index, vaddr_page, vp_offset, pma_index);
+    vf_offset = faddr - vaddr;
+    a.template write_tlb<SET>(slot_index, vaddr_page, vf_offset, pma_index);
     return faddr;
 }
 
@@ -955,8 +955,8 @@ static i_state_access_fast_addr_t<STATE_ACCESS> replace_tlb_entry(const STATE_AC
 /// \returns The implementation-defined fast address corresponding to paddr
 template <TLB_set_index SET, typename STATE_ACCESS>
 static FORCE_INLINE auto replace_tlb_entry(const STATE_ACCESS a, uint64_t vaddr, uint64_t paddr, uint64_t pma_index) {
-    i_state_access_fast_addr_t<STATE_ACCESS> vp_offset{0};
-    return replace_tlb_entry<SET>(a, vaddr, paddr, pma_index, vp_offset);
+    i_state_access_fast_addr_t<STATE_ACCESS> vf_offset{0};
+    return replace_tlb_entry<SET>(a, vaddr, paddr, pma_index, vf_offset);
 }
 
 /// \brief Read an aligned word from virtual memory (slow path that goes through virtual address translation).
@@ -1046,8 +1046,8 @@ static FORCE_INLINE bool read_virtual_memory(const STATE_ACCESS a, uint64_t &pc,
         return status;
     }
     const auto pma_index = a.template read_tlb_pma_index<TLB_READ>(slot_index);
-    const auto vp_offset = a.template read_tlb_vp_offset<TLB_READ>(slot_index);
-    const auto faddr = vaddr + vp_offset;
+    const auto vf_offset = a.template read_tlb_vf_offset<TLB_READ>(slot_index);
+    const auto faddr = vaddr + vf_offset;
     a.template read_memory_word<T>(faddr, pma_index, pval);
     DUMP_STATS_INCR(a, "tlb.rhit");
     return true;
@@ -1128,8 +1128,8 @@ static FORCE_INLINE execute_status write_virtual_memory(const STATE_ACCESS a, ui
         return status;
     }
     const auto pma_index = a.template read_tlb_pma_index<TLB_WRITE>(slot_index);
-    const auto vp_offset = a.template read_tlb_vp_offset<TLB_WRITE>(slot_index);
-    const auto faddr = vaddr + vp_offset;
+    const auto vf_offset = a.template read_tlb_vf_offset<TLB_WRITE>(slot_index);
+    const auto faddr = vaddr + vf_offset;
     a.template write_memory_word<T>(faddr, pma_index, static_cast<T>(val64));
     DUMP_STATS_INCR(a, "tlb.whit");
     return execute_status::success;
@@ -5378,13 +5378,13 @@ enum class fetch_status : int {
 /// \param a Machine state accessor object.
 /// \param pc Virtual address for the current instruction being executed.
 /// \param vaddr Virtual address to be fetched.
-/// \param vp_offset Receives vp_offset in the TLB slot
+/// \param vf_offset Receives vf_offset in the TLB slot
 /// \param pma_index Receives the index of PMA where vaddr falls
 /// \return Returns fetch_status::success if load succeeded, fetch_status::exception if it caused an exception.
 //          In that case, raise the exception.
 template <typename STATE_ACCESS>
 static FORCE_INLINE fetch_status fetch_translate_pc_slow(const STATE_ACCESS a, uint64_t &pc, uint64_t vaddr,
-    i_state_access_fast_addr_t<STATE_ACCESS> &vp_offset, uint64_t &pma_index) {
+    i_state_access_fast_addr_t<STATE_ACCESS> &vf_offset, uint64_t &pma_index) {
     uint64_t paddr{};
     // Walk page table and obtain the physical address
     if (unlikely(!translate_virtual_address(a, &paddr, vaddr, PTE_XWR_X_SHIFT))) {
@@ -5399,7 +5399,7 @@ static FORCE_INLINE fetch_status fetch_translate_pc_slow(const STATE_ACCESS a, u
         pc = raise_exception(a, pc, MCAUSE_INSN_ACCESS_FAULT, vaddr);
         return fetch_status::exception;
     }
-    replace_tlb_entry<TLB_CODE>(a, vaddr, paddr, pma_index, vp_offset);
+    replace_tlb_entry<TLB_CODE>(a, vaddr, paddr, pma_index, vf_offset);
     return fetch_status::success;
 }
 
@@ -5408,22 +5408,22 @@ static FORCE_INLINE fetch_status fetch_translate_pc_slow(const STATE_ACCESS a, u
 /// \param a Machine state accessor object.
 /// \param pc Virtual address for the current instruction being executed.
 /// \param vaddr Virtual address to be fetched.
-/// \param vp_offset Receives vp_offset in the TLB slot
+/// \param vf_offset Receives vf_offset in the TLB slot
 /// \param pma_index Receives the index of PMA where vaddr falls
 /// \return Returns fetch_status::success if load succeeded, fetch_status::exception if it caused an exception.
 //          In that case, raise the exception.
 template <typename STATE_ACCESS>
 static FORCE_INLINE fetch_status fetch_translate_pc(const STATE_ACCESS a, uint64_t &pc, uint64_t vaddr,
-    i_state_access_fast_addr_t<STATE_ACCESS> &vp_offset, uint64_t &pma_index) {
+    i_state_access_fast_addr_t<STATE_ACCESS> &vf_offset, uint64_t &pma_index) {
     // Try to perform the address translation via TLB first
     const uint64_t slot_index = tlb_slot_index(vaddr);
     const uint64_t slot_vaddr_page = a.template read_tlb_vaddr_page<TLB_CODE>(slot_index);
     if (unlikely(!tlb_is_hit<uint16_t>(slot_vaddr_page, vaddr))) {
         DUMP_STATS_INCR(a, "tlb.cmiss");
         // Outline the slow path into a function call to minimize host CPU code cache pressure
-        return fetch_translate_pc_slow(a, pc, vaddr, vp_offset, pma_index);
+        return fetch_translate_pc_slow(a, pc, vaddr, vf_offset, pma_index);
     }
-    vp_offset = a.template read_tlb_vp_offset<TLB_CODE>(slot_index);
+    vf_offset = a.template read_tlb_vf_offset<TLB_CODE>(slot_index);
     pma_index = a.template read_tlb_pma_index<TLB_CODE>(slot_index);
     DUMP_STATS_INCR(a, "tlb.chit");
     return fetch_status::success;
@@ -5435,32 +5435,32 @@ static FORCE_INLINE fetch_status fetch_translate_pc(const STATE_ACCESS a, uint64
 /// \param pc Virtual address for the current instruction being executed.
 /// \param insn Receives the instruction.
 /// \param last_vaddr_page Receives and updates vaddr_page for cache.
-/// \param last_vp_offset Receives and updates vp_offset for cache.
+/// \param last_vf_offset Receives and updates vf_offset for cache.
 /// \param last_pma_index Receives and updates pma_index for cache.
 /// \return Returns fetch_status::success if load succeeded, fetch_status::exception if it caused an exception.
 //          In that case, raise the exception.
 template <typename STATE_ACCESS>
 static FORCE_INLINE fetch_status fetch_insn(const STATE_ACCESS a, uint64_t &pc, uint32_t &insn,
-    uint64_t &last_vaddr_page, i_state_access_fast_addr_t<STATE_ACCESS> &last_vp_offset, uint64_t &last_pma_index) {
+    uint64_t &last_vaddr_page, i_state_access_fast_addr_t<STATE_ACCESS> &last_vf_offset, uint64_t &last_pma_index) {
     [[maybe_unused]] auto note = a.make_scoped_note("fetch_insn");
     i_state_access_fast_addr_t<STATE_ACCESS> faddr{0};
     const uint64_t pc_vaddr_page = tlb_addr_page(pc);
     // If pc is in the same page as the last pc fetch,
     // we can just reuse last fetch translation, skipping TLB or slow address translation altogether.
     if (likely(pc_vaddr_page == last_vaddr_page)) {
-        faddr = pc + last_vp_offset;
+        faddr = pc + last_vf_offset;
     } else {
         // Not in the same page as last the fetch, we need to perform address translation
-        i_state_access_fast_addr_t<STATE_ACCESS> pc_vp_offset{};
+        i_state_access_fast_addr_t<STATE_ACCESS> pc_vf_offset{};
         uint64_t pc_pma_index{};
-        if (unlikely(fetch_translate_pc(a, pc, pc, pc_vp_offset, pc_pma_index) == fetch_status::exception)) {
+        if (unlikely(fetch_translate_pc(a, pc, pc, pc_vf_offset, pc_pma_index) == fetch_status::exception)) {
             return fetch_status::exception;
         }
         // Update fetch address translation cache
         last_vaddr_page = pc_vaddr_page;
-        last_vp_offset = pc_vp_offset;
+        last_vf_offset = pc_vf_offset;
         last_pma_index = pc_pma_index;
-        faddr = pc + pc_vp_offset;
+        faddr = pc + pc_vf_offset;
     }
     // The following code assumes pc is always 2-byte aligned, this is guaranteed by RISC-V spec.
     // If pc is pointing to the very last 2 bytes of a page, it's crossing a page boundary.
@@ -5473,15 +5473,15 @@ static FORCE_INLINE fetch_status fetch_insn(const STATE_ACCESS a, uint64_t &pc,
         if (unlikely(insn_is_uncompressed(insn))) {
             // We have to perform a new address translation to read the next 2 bytes since we changed pages.
             const uint64_t pc2 = pc + 2;
-            i_state_access_fast_addr_t<STATE_ACCESS> pc2_vp_offset{};
+            i_state_access_fast_addr_t<STATE_ACCESS> pc2_vf_offset{};
             uint64_t pc2_pma_index{};
-            if (unlikely(fetch_translate_pc(a, pc, pc2, pc2_vp_offset, pc2_pma_index) == fetch_status::exception)) {
+            if (unlikely(fetch_translate_pc(a, pc, pc2, pc2_vf_offset, pc2_pma_index) == fetch_status::exception)) {
                 return fetch_status::exception;
             }
             last_vaddr_page = tlb_addr_page(pc2);
-            last_vp_offset = pc2_vp_offset;
+            last_vf_offset = pc2_vf_offset;
             last_pma_index = pc2_pma_index;
-            faddr = pc2 + last_vp_offset;
+            faddr = pc2 + last_vf_offset;
             a.template read_memory_word<uint16_t>(faddr, last_pma_index, &insn16);
             insn |= insn16 << 16;
         }
@@ -5524,7 +5524,7 @@ static NO_INLINE execute_status interpret_loop(const STATE_ACCESS a, uint64_t mc
     // Initialize fetch address translation cache invalidated
     uint64_t fetch_vaddr_page = TLB_INVALID_PAGE;
     uint64_t fetch_pma_index = TLB_INVALID_PMA_INDEX;
-    i_state_access_fast_addr_t<STATE_ACCESS> fetch_vp_offset{};
+    i_state_access_fast_addr_t<STATE_ACCESS> fetch_vf_offset{};
 
     // The outer loop continues until there is an interruption that should be handled
     // externally, or mcycle reaches mcycle_end
@@ -5563,7 +5563,7 @@ static NO_INLINE execute_status interpret_loop(const STATE_ACCESS a, uint64_t mc
             uint32_t insn = 0;
 
             // Try to fetch the next instruction
-            if (likely(fetch_insn(a, pc, insn, fetch_vaddr_page, fetch_vp_offset, fetch_pma_index) ==
+            if (likely(fetch_insn(a, pc, insn, fetch_vaddr_page, fetch_vf_offset, fetch_pma_index) ==
                     fetch_status::success)) {
                 // clang-format off
                 // NOLINTBEGIN
diff --git a/src/json-util.cpp b/src/json-util.cpp
index 5341216c7..2349bd54c 100644
--- a/src/json-util.cpp
+++ b/src/json-util.cpp
@@ -1352,6 +1352,7 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, hash_tree_config &v
     const auto &jconfig = j[key];
     const auto new_path = path + to_string(key) + "/";
     ju_get_opt_field(jconfig, "shared"s, value.shared, new_path);
+    ju_get_opt_field(jconfig, "create"s, value.create, new_path);
     ju_get_opt_field(jconfig, "truncate"s, value.truncate, new_path);
     ju_get_opt_field(jconfig, "hasher"s, value.hasher, new_path);
     ju_get_opt_field(jconfig, "sht_filename"s, value.sht_filename, new_path);
@@ -1373,6 +1374,7 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, backing_store_confi
     const auto &jconfig = j[key];
     const auto new_path = path + to_string(key) + "/";
     ju_get_opt_field(jconfig, "shared"s, value.shared, new_path);
+    ju_get_opt_field(jconfig, "create"s, value.create, new_path);
     ju_get_opt_field(jconfig, "truncate"s, value.truncate, new_path);
     ju_get_opt_field(jconfig, "data_filename"s, value.data_filename, new_path);
     ju_get_opt_field(jconfig, "dht_filename"s, value.dht_filename, new_path);
@@ -1681,7 +1683,6 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, machine_config &val
     ju_get_opt_field(config, "ram"s, value.ram, new_path);
     ju_get_opt_field(config, "dtb"s, value.dtb, new_path);
     ju_get_opt_field(config, "flash_drive"s, value.flash_drive, new_path);
-    ju_get_opt_field(config, "tlb"s, value.tlb, new_path);
     ju_get_opt_field(config, "virtio"s, value.virtio, new_path);
     ju_get_opt_field(config, "cmio"s, value.cmio, new_path);
     ju_get_opt_field(config, "pmas"s, value.pmas, new_path);
@@ -1832,7 +1833,7 @@ void to_json(nlohmann::json &j, const access_log &log) {
 }
 
 void to_json(nlohmann::json &j, const backing_store_config &config) {
-    j = nlohmann::json{{"shared", config.shared}, {"truncate", config.truncate},
+    j = nlohmann::json{{"shared", config.shared}, {"create", config.create}, {"truncate", config.truncate},
         {"data_filename", config.data_filename}, {"dht_filename", config.dht_filename}};
 }
 
@@ -1846,8 +1847,8 @@ void to_json(nlohmann::json &j, const memory_range_config &config) {
 }
 
 void to_json(nlohmann::json &j, const hash_tree_config &config) {
-    j = nlohmann::json{{"hasher", config.hasher}, {"shared", config.shared}, {"truncate", config.truncate},
-        {"sht_filename", config.sht_filename}, {"phtc_filename", config.phtc_filename},
+    j = nlohmann::json{{"hasher", config.hasher}, {"shared", config.shared}, {"create", config.create},
+        {"truncate", config.truncate}, {"sht_filename", config.sht_filename}, {"phtc_filename", config.phtc_filename},
         {"phtc_size", config.phtc_size}};
 }
 
@@ -2036,7 +2037,6 @@ void to_json(nlohmann::json &j, const machine_config &config) {
         {"ram", config.ram},
         {"dtb", config.dtb},
         {"flash_drive", config.flash_drive},
-        {"tlb", config.tlb},
         {"virtio", config.virtio},
         {"cmio", config.cmio},
         {"pmas", config.pmas},
diff --git a/src/jsonrpc-discover.json b/src/jsonrpc-discover.json
index 439f3d98a..07775c656 100644
--- a/src/jsonrpc-discover.json
+++ b/src/jsonrpc-discover.json
@@ -1353,6 +1353,9 @@
           "length": {
             "$ref": "#/components/schemas/UnsignedInteger"
           },
+          "read_only": {
+            "type": "boolean"
+          },
           "backing_store": {
             "$ref": "#/components/schemas/BackingStoreConfig"
           }
@@ -1371,6 +1374,9 @@
           "shared": {
             "type": "boolean"
           },
+          "create": {
+            "type": "boolean"
+          },
           "truncate": {
             "type": "boolean"
           }
@@ -1446,15 +1452,6 @@
           "$ref": "#/components/schemas/MemoryRangeConfig"
         }
       },
-      "TLBConfig": {
-        "title": "TLBConfig",
-        "type": "object",
-        "properties": {
-          "backing_store": {
-            "$ref": "#/components/schemas/BackingStoreConfig"
-          }
-        }
-      },
       "CLINTConfig": {
         "title": "CLINTConfig",
         "type": "object",
@@ -1675,6 +1672,12 @@
           "shared": {
             "type": "boolean"
           },
+          "create": {
+            "type": "boolean"
+          },
+          "truncate": {
+            "type": "boolean"
+          },
           "sht_filename": {
             "type": "string"
           },
@@ -1709,9 +1712,6 @@
           "flash_drive": {
             "$ref": "#/components/schemas/FlashDriveConfigs"
           },
-          "tlb": {
-            "$ref": "#/components/schemas/TLBConfig"
-          },
           "clint": {
             "$ref": "#/components/schemas/CLINTConfig"
           },
diff --git a/src/machine-address-ranges.cpp b/src/machine-address-ranges.cpp
index d44833c61..7afee20d8 100644
--- a/src/machine-address-ranges.cpp
+++ b/src/machine-address-ranges.cpp
@@ -42,10 +42,9 @@
 #include "plic-address-range.h"
 #include "pmas-constants.h"
 #include "pmas.h"
-#include "shadow-state-address-range.h"
-#include "shadow-tlb-address-range.h"
-#include "shadow-uarch-state-address-range.h"
+#include "processor-state.h"
 #include "uarch-pristine.h"
+#include "uarch-processor-state.h"
 #include "unique-c-ptr.h"
 #include "virtio-address-range.h"
 #include "virtio-console-address-range.h"
@@ -59,29 +58,8 @@ using namespace std::string_literals;
 
 static const auto throw_invalid_argument = [](const char *err) { throw std::invalid_argument{err}; };
 
-/// \brief Creates a memory address range.
-/// \param d Description of address range for use in error messages.
-/// \param start Target physical address where range starts.
-/// \param length Length of range, in bytes.
-/// \param f Flags for address range.
-/// \param backing_store Backing store configuration for range.
-/// \returns New address range with flags already set.
-/// \details If \p backing_store.data_filename is non-empty and file is large enough to back entire address range,
-/// return a memory-mapped range, otherwise use calloc.
-static inline auto make_memory_address_range(const std::string &d, uint64_t start, uint64_t length, pmas_flags flags,
-    const backing_store_config &backing_store) {
-    if (backing_store.data_filename.empty() && backing_store.shared) {
-        throw std::invalid_argument{"shared address range requires non-empty memory filename when initializing " + d};
-    }
-    if (backing_store.data_filename.empty() ||
-        length > static_cast<uint64_t>(os_get_file_length(backing_store.data_filename.c_str()))) {
-        return make_callocd_memory_address_range(d, start, length, flags, backing_store.data_filename);
-    }
-    return make_mmapd_memory_address_range(d, start, length, flags, backing_store.data_filename, backing_store.shared);
-}
-
 static inline auto make_pmas_address_range(const pmas_config &config) {
-    static constexpr pmas_flags m_pmas_flags{
+    static constexpr pmas_flags pmas_flags{
         .M = true,
         .IO = false,
         .R = true,
@@ -91,12 +69,12 @@ static inline auto make_pmas_address_range(const pmas_config &config) {
         .IW = false,
         .DID = PMA_ISTART_DID::memory,
     };
-    return make_memory_address_range("PMAs", AR_PMAS_START, AR_PMAS_LENGTH, m_pmas_flags, config.backing_store);
+    return memory_address_range{"PMAs", AR_PMAS_START, AR_PMAS_LENGTH, pmas_flags, config.backing_store};
 }
 
 static inline auto make_dtb_address_range(const dtb_config &config) {
     // When we pass a RNG seed in a FDT stored in DTB, Linux will wipe out its contents as a security measure,
-    // theref, ore we need to make DTB writable, otherwise boot will hang.
+    // therefore, we need to make DTB writable, otherwise boot will hang.
     static constexpr pmas_flags dtb_flags{
         .M = true,
         .IO = false,
@@ -107,7 +85,45 @@ static inline auto make_dtb_address_range(const dtb_config &config) {
         .IW = true,
         .DID = PMA_ISTART_DID::memory,
     };
-    return make_memory_address_range("DTB"s, AR_DTB_START, AR_DTB_LENGTH, dtb_flags, config.backing_store);
+    return memory_address_range{"DTB"s, AR_DTB_START, AR_DTB_LENGTH, dtb_flags, config.backing_store};
+}
+
+static inline auto make_shadow_state_address_range(const processor_config &config) {
+    static constexpr pmas_flags shadow_state_flags{
+        .M = true,
+        .IO = false,
+        .R = false,
+        .W = false,
+        .X = false,
+        .IR = false,
+        .IW = false,
+        .DID = PMA_ISTART_DID::shadow_state,
+    };
+    auto ar = memory_address_range{"shadow state", AR_SHADOW_STATE_START, AR_SHADOW_STATE_LENGTH, shadow_state_flags,
+        config.backing_store, memory_address_range_flags{.page_uncleanable = true}, sizeof(processor_state)};
+    // Mark pages that are permanently dirty in the shadow
+    ar.mark_dirty_pages(AR_SHADOW_REGISTERS_START - AR_SHADOW_STATE_START, AR_SHADOW_REGISTERS_LENGTH);
+    ar.mark_dirty_pages(AR_SHADOW_TLB_START - AR_SHADOW_STATE_START, AR_SHADOW_TLB_LENGTH);
+    return ar;
+}
+
+static inline auto make_shadow_uarch_state_address_range(const uarch_processor_config &config) {
+    static constexpr pmas_flags shadow_uarch_state_flags{
+        .M = true,
+        .IO = false,
+        .R = false,
+        .W = false,
+        .X = false,
+        .IR = false,
+        .IW = false,
+        .DID = PMA_ISTART_DID::shadow_uarch_state,
+    };
+    auto ar = memory_address_range{"shadow uarch state", AR_SHADOW_UARCH_STATE_START, AR_SHADOW_UARCH_STATE_LENGTH,
+        shadow_uarch_state_flags, config.backing_store, memory_address_range_flags{.page_uncleanable = true},
+        sizeof(uarch_processor_state)};
+    // Mark pages that are permanently dirty in the shadow
+    ar.mark_dirty_pages(0, AR_SHADOW_UARCH_STATE_LENGTH);
+    return ar;
 }
 
 template <typename AR>
@@ -132,9 +148,10 @@ AR &machine_address_ranges::push_back(AR &&ar, register_where where) {
 
 machine_address_ranges::machine_address_ranges(machine_config &c) {
     // Add all address ranges to m_all, and potentially to interpret and merkle
-    push_back_uarch_ram(c.uarch.ram);
-    push_back(make_shadow_uarch_state_address_range(throw_invalid_argument),
+    push_back(make_shadow_state_address_range(c.processor), register_where{.merkle = true, .interpret = false});
+    push_back(make_shadow_uarch_state_address_range(c.uarch.processor),
         register_where{.merkle = true, .interpret = false});
+    push_back_uarch_ram(c.uarch.ram);
     push_back_ram(c.ram);
     push_back(make_dtb_address_range(c.dtb), register_where{.merkle = true, .interpret = true});
     push_back_flash_drives(c.flash_drive);
@@ -142,10 +159,6 @@ machine_address_ranges::machine_address_ranges(machine_config &c) {
     push_back(make_htif_address_range(throw_invalid_argument), register_where{.merkle = false, .interpret = true});
     push_back(make_clint_address_range(throw_invalid_argument), register_where{.merkle = false, .interpret = true});
     push_back(make_plic_address_range(throw_invalid_argument), register_where{.merkle = false, .interpret = true});
-    push_back(make_shadow_tlb_address_range(throw_invalid_argument),
-        register_where{.merkle = true, .interpret = false});
-    push_back(make_shadow_state_address_range(throw_invalid_argument),
-        register_where{.merkle = true, .interpret = false});
     push_back(make_pmas_address_range(c.pmas), register_where{.merkle = true, .interpret = true});
     push_back_virtio(c.virtio, c.processor.registers.iunrep);
 
@@ -166,10 +179,7 @@ machine_address_ranges::machine_address_ranges(machine_config &c) {
 }
 
 void machine_address_ranges::push_back_uarch_ram(const uarch_ram_config &uram) {
-    // Register RAM
-    if (uarch_pristine_ram_len > AR_UARCH_RAM_LENGTH) {
-        throw std::runtime_error("embedded uarch RAM image does not fit in uarch memory");
-    }
+    // Register uarch RAM
     static constexpr pmas_flags uram_flags{
         .M = true,
         .IO = false,
@@ -181,15 +191,16 @@ void machine_address_ranges::push_back_uarch_ram(const uarch_ram_config &uram) {
         .DID = PMA_ISTART_DID::memory,
     };
     constexpr auto ram_description = "uarch RAM";
-    if (uram.backing_store.data_filename.empty()) {
-        auto &ar = push_back(
-            make_callocd_memory_address_range(ram_description, AR_UARCH_RAM_START, AR_UARCH_RAM_LENGTH, uram_flags),
-            register_where{.merkle = true, .interpret = false});
+    auto &ar = push_back(
+        memory_address_range{ram_description, AR_UARCH_RAM_START, AR_UARCH_RAM_LENGTH, uram_flags, uram.backing_store},
+        register_where{.merkle = true, .interpret = false});
+
+    // Initialize uarch RAM
+    if (uram.backing_store.data_filename.empty() || uram.backing_store.create) {
+        if (uarch_pristine_ram_len > AR_UARCH_RAM_LENGTH) {
+            throw std::runtime_error("embedded uarch RAM image does not fit in uarch memory");
+        }
         memcpy(ar.get_host_memory(), uarch_pristine_ram, uarch_pristine_ram_len);
-    } else {
-        push_back(make_memory_address_range(ram_description, AR_UARCH_RAM_START, AR_UARCH_RAM_LENGTH, uram_flags,
-                      uram.backing_store),
-            register_where{.merkle = true, .interpret = false});
     }
 }
 
@@ -228,7 +239,7 @@ void machine_address_ranges::push_back_ram(const ram_config &ram) {
     if (ram.length == 0) {
         throw std::invalid_argument("RAM length cannot be zero");
     }
-    push_back(make_memory_address_range("RAM"s, AR_RAM_START, ram.length, ram_flags, ram.backing_store),
+    push_back(memory_address_range{"RAM"s, AR_RAM_START, ram.length, ram_flags, ram.backing_store},
         register_where{.merkle = true, .interpret = true});
 }
 
@@ -236,17 +247,6 @@ void machine_address_ranges::push_back_flash_drives(flash_drive_configs &flash_d
     if (flash_drive.size() > FLASH_DRIVE_MAX) {
         throw std::invalid_argument{"too many flash drives"};
     }
-    // Flags for flash drives
-    static const pmas_flags flash_flags{
-        .M = true,
-        .IO = false,
-        .R = true,
-        .W = true,
-        .X = false,
-        .IR = true,
-        .IW = true,
-        .DID = PMA_ISTART_DID::flash_drive,
-    };
     // Register all flash drives
     int i = 0; // NOLINT(misc-const-correctness)
     for (auto &f : flash_drive) {
@@ -259,7 +259,7 @@ void machine_address_ranges::push_back_flash_drives(flash_drive_configs &flash_d
         const auto &image_filename = f.backing_store.data_filename;
         if (f.length == UINT64_C(-1)) {
             if (image_filename.empty()) {
-                throw std::system_error{errno, std::generic_category(),
+                throw std::runtime_error{
                     "unable to auto-detect length of "s.append(flash_description).append(" with empty image file")};
             }
             auto fp = make_unique_fopen(image_filename.c_str(), "rb");
@@ -278,7 +278,19 @@ void machine_address_ranges::push_back_flash_drives(flash_drive_configs &flash_d
             }
             f.length = length;
         }
-        push_back(make_memory_address_range(flash_description, f.start, f.length, flash_flags, f.backing_store),
+        // Flags for the flash drive
+        const pmas_flags flash_flags{
+            .M = true,
+            .IO = false,
+            .R = true,
+            .W = !f.read_only,
+            .X = false,
+            .IR = true,
+            .IW = !f.read_only,
+            .DID = PMA_ISTART_DID::flash_drive,
+        };
+        push_back(memory_address_range{flash_description, f.start, f.length, flash_flags, f.backing_store,
+                      memory_address_range_flags{.read_only = f.read_only}},
             register_where{.merkle = true, .interpret = true});
         i++;
     }
@@ -350,7 +362,7 @@ void machine_address_ranges::push_back_virtio(const virtio_configs &virtio, uint
 }
 
 void machine_address_ranges::push_back_cmio(const cmio_config &c) {
-    static const pmas_flags tx_flags{
+    const pmas_flags tx_flags{
         .M = true,
         .IO = false,
         .R = true,
@@ -360,7 +372,7 @@ void machine_address_ranges::push_back_cmio(const cmio_config &c) {
         .IW = true,
         .DID = PMA_ISTART_DID::cmio_tx_buffer,
     };
-    static const pmas_flags rx_flags{
+    const pmas_flags rx_flags{
         .M = true,
         .IO = false,
         .R = true,
@@ -370,26 +382,29 @@ void machine_address_ranges::push_back_cmio(const cmio_config &c) {
         .IW = true,
         .DID = PMA_ISTART_DID::cmio_rx_buffer,
     };
-    push_back(make_memory_address_range("CMIO tx buffer memory range"s, AR_CMIO_TX_BUFFER_START,
-                  AR_CMIO_TX_BUFFER_LENGTH, tx_flags, c.tx_buffer.backing_store),
+    push_back(memory_address_range{"CMIO tx buffer memory range"s, AR_CMIO_TX_BUFFER_START, AR_CMIO_TX_BUFFER_LENGTH,
+                  tx_flags, c.tx_buffer.backing_store},
         register_where{.merkle = true, .interpret = true});
-    push_back(make_memory_address_range("CMIO rx buffer memory range"s, AR_CMIO_RX_BUFFER_START,
-                  AR_CMIO_RX_BUFFER_LENGTH, rx_flags, c.rx_buffer.backing_store),
+    push_back(memory_address_range{"CMIO rx buffer memory range"s, AR_CMIO_RX_BUFFER_START, AR_CMIO_RX_BUFFER_LENGTH,
+                  rx_flags, c.rx_buffer.backing_store},
         register_where{.merkle = true, .interpret = true});
 }
 
 void machine_address_ranges::replace(const memory_range_config &config) {
     for (auto &ar : m_all) {
-        //??D Need to add check for new read-only property here
         if (ar->get_start() == config.start && ar->get_length() == config.length) {
             if (!ar->is_memory() || pmas_is_protected(ar->get_driver_id())) {
                 throw std::invalid_argument{
                     std::string{"attempt to replace a protected range "}.append(ar->get_description())};
             }
+            if (ar->is_host_read_only()) {
+                throw std::invalid_argument{
+                    std::string{"attempt to replace a read-only range "}.append(ar->get_description())};
+            }
             // Replace range, preserving original flags.
             // This will automatically start with all pages dirty.
-            ar = make_moved_unique(make_memory_address_range(ar->get_description(), ar->get_start(), ar->get_length(),
-                ar->get_flags(), config.backing_store));
+            ar = make_moved_unique(memory_address_range{ar->get_description(), ar->get_start(), ar->get_length(),
+                ar->get_flags(), config.backing_store, memory_address_range_flags{.read_only = config.read_only}});
             return;
         }
     }
diff --git a/src/machine-address-ranges.h b/src/machine-address-ranges.h
index bfba63c89..3b63e6de0 100644
--- a/src/machine-address-ranges.h
+++ b/src/machine-address-ranges.h
@@ -74,7 +74,7 @@ class machine_address_ranges {
         return std::views::transform(m_virtio, [](auto *p) -> virtio_address_range & { return *p; });
     }
 
-    /// \brief Returns the ith address range registed with interpret
+    /// \brief Returns the ith address range registered with interpret
     const address_range &read_pma(uint64_t index) const noexcept {
         if (index >= m_interpret.size()) {
             static constexpr auto sentinel = make_empty_address_range("sentinel");
@@ -154,7 +154,7 @@ class machine_address_ranges {
     /// This means the index into the container that owns all address ranges will always refer to same address range
     /// after subsequent calls to register() and  calls to replace() as well.
     /// \details Besides the container that stores the address ranges, the machine maintains three subsets.
-    /// The "merkle" subset lists the indices of the address ranges taht will be considered by the Merkle
+    /// The "merkle" subset lists the indices of the address ranges that will be considered by the Merkle
     /// tree during the computation of the state hash.
     /// The "interpret" subset lists the indices of the address ranges visible from within the interpreter (PMAs).
     /// When registering an address range with the machine, one must specify \p where to register it.
@@ -163,6 +163,7 @@ class machine_address_ranges {
         requires std::is_rvalue_reference_v<AR &&> && std::derived_from<AR, address_range>
     AR &push_back(AR &&ar, register_where where);
 
+    /// \brief Adds uarch RAM address range
     /// \param c uarch RAM configuration
     void push_back_uarch_ram(const uarch_ram_config &uram);
 
diff --git a/src/machine-config.cpp b/src/machine-config.cpp
index 12c007438..486ed8c9d 100644
--- a/src/machine-config.cpp
+++ b/src/machine-config.cpp
@@ -32,7 +32,7 @@
 #include "address-range-constants.h"
 #include "json-util.h"
 
-static constexpr uint32_t archive_version = 5;
+static constexpr uint32_t archive_version = 6;
 
 namespace cartesi {
 
@@ -63,28 +63,34 @@ std::string machine_config::get_config_filename(const std::string &dir) {
     return dir + "/config.json";
 }
 
-static void adjust_backing_store(uint64_t start, uint64_t length, const std::string &dir, backing_store_config &c) {
+void machine_config::adjust_backing_store_config(uint64_t start, uint64_t length, const std::string &dir,
+    backing_store_config &c) {
+    c.shared = false;
+    c.create = false;
+    c.truncate = false;
     c.data_filename = machine_config::get_data_filename(dir, start, length);
     c.dht_filename = machine_config::get_dht_filename(dir, start, length);
 }
 
-static void adjust_hash_tree(const std::string &dir, hash_tree_config &c) {
+void machine_config::adjust_hash_tree_config(const std::string &dir, hash_tree_config &c) {
     c.sht_filename = machine_config::get_sht_filename(dir);
     c.phtc_filename = machine_config::get_phtc_filename(dir);
 }
 
-static void adjust_backing_store(machine_config &c, const std::string &dir) {
-    adjust_backing_store(AR_RAM_START, c.ram.length, dir, c.ram.backing_store);
-    adjust_backing_store(AR_DTB_START, AR_DTB_LENGTH, dir, c.dtb.backing_store);
-    for (auto &f : c.flash_drive) {
-        adjust_backing_store(f.start, f.length, dir, f.backing_store);
+void machine_config::adjust_backing_stores(const std::string &dir) {
+    adjust_backing_store_config(AR_RAM_START, ram.length, dir, ram.backing_store);
+    adjust_backing_store_config(AR_DTB_START, AR_DTB_LENGTH, dir, dtb.backing_store);
+    for (auto &f : flash_drive) {
+        adjust_backing_store_config(f.start, f.length, dir, f.backing_store);
     }
-    adjust_backing_store(AR_SHADOW_TLB_START, AR_SHADOW_TLB_LENGTH, dir, c.tlb.backing_store);
-    adjust_backing_store(AR_CMIO_RX_BUFFER_START, AR_CMIO_RX_BUFFER_LENGTH, dir, c.cmio.rx_buffer.backing_store);
-    adjust_backing_store(AR_CMIO_TX_BUFFER_START, AR_CMIO_TX_BUFFER_LENGTH, dir, c.cmio.tx_buffer.backing_store);
-    adjust_backing_store(AR_PMAS_START, AR_PMAS_LENGTH, dir, c.pmas.backing_store);
-    adjust_backing_store(AR_UARCH_RAM_START, AR_UARCH_RAM_LENGTH, dir, c.uarch.ram.backing_store);
-    adjust_hash_tree(dir, c.hash_tree);
+    adjust_backing_store_config(AR_SHADOW_STATE_START, AR_SHADOW_STATE_LENGTH, dir, processor.backing_store);
+    adjust_backing_store_config(AR_CMIO_RX_BUFFER_START, AR_CMIO_RX_BUFFER_LENGTH, dir, cmio.rx_buffer.backing_store);
+    adjust_backing_store_config(AR_CMIO_TX_BUFFER_START, AR_CMIO_TX_BUFFER_LENGTH, dir, cmio.tx_buffer.backing_store);
+    adjust_backing_store_config(AR_PMAS_START, AR_PMAS_LENGTH, dir, pmas.backing_store);
+    adjust_backing_store_config(AR_SHADOW_UARCH_STATE_START, AR_SHADOW_UARCH_STATE_LENGTH, dir,
+        uarch.processor.backing_store);
+    adjust_backing_store_config(AR_UARCH_RAM_START, AR_UARCH_RAM_LENGTH, dir, uarch.ram.backing_store);
+    adjust_hash_tree_config(dir, hash_tree);
 }
 
 machine_config machine_config::load(const std::string &dir) {
@@ -108,7 +114,7 @@ machine_config machine_config::load(const std::string &dir) {
                 std::to_string(jv.get<int>()) + ")");
         }
         ju_get_field(j, std::string("config"), c, "");
-        adjust_backing_store(c, dir);
+        c.adjust_backing_stores(dir);
     } catch (std::exception &e) {
         throw std::runtime_error{e.what()};
     }
diff --git a/src/machine-config.h b/src/machine-config.h
index 3b8e967b5..687171ca6 100644
--- a/src/machine-config.h
+++ b/src/machine-config.h
@@ -24,7 +24,7 @@
 #include <vector>
 
 #include "riscv-constants.h"
-#include "shadow-state.h"
+#include "shadow-registers.h"
 #include "shadow-uarch-state.h"
 
 namespace cartesi {
@@ -39,6 +39,7 @@ enum machine_config_constants {
 /// \brief Backing store config
 struct backing_store_config final {
     bool shared{false};        ///< Should changes be reflected in backing store?
+    bool create{false};        ///< Should backing store be created?
     bool truncate{false};      ///< Should backing store be truncated to correct size?
     std::string data_filename; ///< Backing store for associated memory address range
     std::string dht_filename;  ///< Backing store for corresponding dense hash-tree
@@ -57,8 +58,8 @@ struct backing_store_config_only final {
 
 /// \brief RAM state config
 struct ram_config final {
-    uint64_t length{0};                 ///< RAM length
-    backing_store_config backing_store; ///< Backing store
+    uint64_t length{0};                                   ///< RAM length
+    backing_store_config backing_store{.truncate = true}; ///< Backing store
 };
 
 /// \brief DTB state config
@@ -82,9 +83,6 @@ struct memory_range_config final {
 /// \brief List of flash drives
 using flash_drive_configs = std::vector<memory_range_config>;
 
-/// \brief TLB device state config
-using tlb_config = backing_store_config_only;
-
 /// \brief VirtIO console device state config
 struct virtio_console_config final {};
 
@@ -146,14 +144,15 @@ struct uarch_processor_config final {
 
 /// \brief Uarch config
 struct uarch_config final {
-    uarch_processor_config processor{}; ///< Uarch processor
-    uarch_ram_config ram{};             ///< Uarch RAM
+    uarch_processor_config processor{};                        ///< Uarch processor
+    uarch_ram_config ram{.backing_store = {.truncate = true}}; ///< Uarch RAM
 };
 
 /// \brief Hash tree config
 struct hash_tree_config final {
     std::string hasher{"keccak"}; ///< What hashing function to use?
     bool shared{false};           ///< Should changes be reflected in backing store?
+    bool create{false};           ///< Should backing store be created to correct size?
     bool truncate{false};         ///< Should backing store be truncated to correct size?
     std::string sht_filename;     ///< Backing storage for sparse hash-tree
     std::string phtc_filename;    ///< Backing storage for page hash-tree cache
@@ -166,7 +165,6 @@ struct machine_config final {
     ram_config ram{};                ///< RAM config
     dtb_config dtb{};                ///< Device Tree config
     flash_drive_configs flash_drive; ///< Flash drives config
-    tlb_config tlb{};                ///< Translation Look-aside Buffer config
     virtio_configs virtio;           ///< VirtIO devices config
     cmio_config cmio{};              ///< Cartesi Machine IO config
     pmas_config pmas{};              ///< Physical Memory Attributes config
@@ -188,6 +186,13 @@ struct machine_config final {
     /// \brief Get the name where global page hash-tree cache will be stored in a directory
     static std::string get_phtc_filename(const std::string &dir);
 
+    static void adjust_backing_store_config(uint64_t start, uint64_t length, const std::string &dir,
+        backing_store_config &c);
+
+    static void adjust_hash_tree_config(const std::string &dir, hash_tree_config &c);
+
+    void adjust_backing_stores(const std::string &dir);
+
     /// \brief Loads a machine config from a directory
     /// \param dir Directory from whence "config" will be loaded
     /// \returns The config loaded
diff --git a/src/machine-reg.h b/src/machine-reg.h
index 736f9f98e..277b69bac 100644
--- a/src/machine-reg.h
+++ b/src/machine-reg.h
@@ -17,8 +17,7 @@
 #ifndef MACHINE_REG_H
 #define MACHINE_REG_H
 
-#include "shadow-state-address-range.h"
-#include "shadow-uarch-state-address-range.h"
+#include "shadow-uarch-state.h"
 
 /// \file
 /// \brief Cartesi machine registers
@@ -27,112 +26,112 @@ namespace cartesi {
 
 /// \brief List of machine registers
 enum class machine_reg : uint64_t {
-    x0 = static_cast<uint64_t>(shadow_state_what::x0),
-    x1 = static_cast<uint64_t>(shadow_state_what::x1),
-    x2 = static_cast<uint64_t>(shadow_state_what::x2),
-    x3 = static_cast<uint64_t>(shadow_state_what::x3),
-    x4 = static_cast<uint64_t>(shadow_state_what::x4),
-    x5 = static_cast<uint64_t>(shadow_state_what::x5),
-    x6 = static_cast<uint64_t>(shadow_state_what::x6),
-    x7 = static_cast<uint64_t>(shadow_state_what::x7),
-    x8 = static_cast<uint64_t>(shadow_state_what::x8),
-    x9 = static_cast<uint64_t>(shadow_state_what::x9),
-    x10 = static_cast<uint64_t>(shadow_state_what::x10),
-    x11 = static_cast<uint64_t>(shadow_state_what::x11),
-    x12 = static_cast<uint64_t>(shadow_state_what::x12),
-    x13 = static_cast<uint64_t>(shadow_state_what::x13),
-    x14 = static_cast<uint64_t>(shadow_state_what::x14),
-    x15 = static_cast<uint64_t>(shadow_state_what::x15),
-    x16 = static_cast<uint64_t>(shadow_state_what::x16),
-    x17 = static_cast<uint64_t>(shadow_state_what::x17),
-    x18 = static_cast<uint64_t>(shadow_state_what::x18),
-    x19 = static_cast<uint64_t>(shadow_state_what::x19),
-    x20 = static_cast<uint64_t>(shadow_state_what::x20),
-    x21 = static_cast<uint64_t>(shadow_state_what::x21),
-    x22 = static_cast<uint64_t>(shadow_state_what::x22),
-    x23 = static_cast<uint64_t>(shadow_state_what::x23),
-    x24 = static_cast<uint64_t>(shadow_state_what::x24),
-    x25 = static_cast<uint64_t>(shadow_state_what::x25),
-    x26 = static_cast<uint64_t>(shadow_state_what::x26),
-    x27 = static_cast<uint64_t>(shadow_state_what::x27),
-    x28 = static_cast<uint64_t>(shadow_state_what::x28),
-    x29 = static_cast<uint64_t>(shadow_state_what::x29),
-    x30 = static_cast<uint64_t>(shadow_state_what::x30),
-    x31 = static_cast<uint64_t>(shadow_state_what::x31),
-    f0 = static_cast<uint64_t>(shadow_state_what::f0),
-    f1 = static_cast<uint64_t>(shadow_state_what::f1),
-    f2 = static_cast<uint64_t>(shadow_state_what::f2),
-    f3 = static_cast<uint64_t>(shadow_state_what::f3),
-    f4 = static_cast<uint64_t>(shadow_state_what::f4),
-    f5 = static_cast<uint64_t>(shadow_state_what::f5),
-    f6 = static_cast<uint64_t>(shadow_state_what::f6),
-    f7 = static_cast<uint64_t>(shadow_state_what::f7),
-    f8 = static_cast<uint64_t>(shadow_state_what::f8),
-    f9 = static_cast<uint64_t>(shadow_state_what::f9),
-    f10 = static_cast<uint64_t>(shadow_state_what::f10),
-    f11 = static_cast<uint64_t>(shadow_state_what::f11),
-    f12 = static_cast<uint64_t>(shadow_state_what::f12),
-    f13 = static_cast<uint64_t>(shadow_state_what::f13),
-    f14 = static_cast<uint64_t>(shadow_state_what::f14),
-    f15 = static_cast<uint64_t>(shadow_state_what::f15),
-    f16 = static_cast<uint64_t>(shadow_state_what::f16),
-    f17 = static_cast<uint64_t>(shadow_state_what::f17),
-    f18 = static_cast<uint64_t>(shadow_state_what::f18),
-    f19 = static_cast<uint64_t>(shadow_state_what::f19),
-    f20 = static_cast<uint64_t>(shadow_state_what::f20),
-    f21 = static_cast<uint64_t>(shadow_state_what::f21),
-    f22 = static_cast<uint64_t>(shadow_state_what::f22),
-    f23 = static_cast<uint64_t>(shadow_state_what::f23),
-    f24 = static_cast<uint64_t>(shadow_state_what::f24),
-    f25 = static_cast<uint64_t>(shadow_state_what::f25),
-    f26 = static_cast<uint64_t>(shadow_state_what::f26),
-    f27 = static_cast<uint64_t>(shadow_state_what::f27),
-    f28 = static_cast<uint64_t>(shadow_state_what::f28),
-    f29 = static_cast<uint64_t>(shadow_state_what::f29),
-    f30 = static_cast<uint64_t>(shadow_state_what::f30),
-    f31 = static_cast<uint64_t>(shadow_state_what::f31),
-    pc = static_cast<uint64_t>(shadow_state_what::pc),
-    fcsr = static_cast<uint64_t>(shadow_state_what::fcsr),
-    mvendorid = static_cast<uint64_t>(shadow_state_what::mvendorid),
-    marchid = static_cast<uint64_t>(shadow_state_what::marchid),
-    mimpid = static_cast<uint64_t>(shadow_state_what::mimpid),
-    mcycle = static_cast<uint64_t>(shadow_state_what::mcycle),
-    icycleinstret = static_cast<uint64_t>(shadow_state_what::icycleinstret),
-    mstatus = static_cast<uint64_t>(shadow_state_what::mstatus),
-    mtvec = static_cast<uint64_t>(shadow_state_what::mtvec),
-    mscratch = static_cast<uint64_t>(shadow_state_what::mscratch),
-    mepc = static_cast<uint64_t>(shadow_state_what::mepc),
-    mcause = static_cast<uint64_t>(shadow_state_what::mcause),
-    mtval = static_cast<uint64_t>(shadow_state_what::mtval),
-    misa = static_cast<uint64_t>(shadow_state_what::misa),
-    mie = static_cast<uint64_t>(shadow_state_what::mie),
-    mip = static_cast<uint64_t>(shadow_state_what::mip),
-    medeleg = static_cast<uint64_t>(shadow_state_what::medeleg),
-    mideleg = static_cast<uint64_t>(shadow_state_what::mideleg),
-    mcounteren = static_cast<uint64_t>(shadow_state_what::mcounteren),
-    menvcfg = static_cast<uint64_t>(shadow_state_what::menvcfg),
-    stvec = static_cast<uint64_t>(shadow_state_what::stvec),
-    sscratch = static_cast<uint64_t>(shadow_state_what::sscratch),
-    sepc = static_cast<uint64_t>(shadow_state_what::sepc),
-    scause = static_cast<uint64_t>(shadow_state_what::scause),
-    stval = static_cast<uint64_t>(shadow_state_what::stval),
-    satp = static_cast<uint64_t>(shadow_state_what::satp),
-    scounteren = static_cast<uint64_t>(shadow_state_what::scounteren),
-    senvcfg = static_cast<uint64_t>(shadow_state_what::senvcfg),
-    ilrsc = static_cast<uint64_t>(shadow_state_what::ilrsc),
-    iprv = static_cast<uint64_t>(shadow_state_what::iprv),
-    iflags_X = static_cast<uint64_t>(shadow_state_what::iflags_X),
-    iflags_Y = static_cast<uint64_t>(shadow_state_what::iflags_Y),
-    iflags_H = static_cast<uint64_t>(shadow_state_what::iflags_H),
-    iunrep = static_cast<uint64_t>(shadow_state_what::iunrep),
-    clint_mtimecmp = static_cast<uint64_t>(shadow_state_what::clint_mtimecmp),
-    plic_girqpend = static_cast<uint64_t>(shadow_state_what::plic_girqpend),
-    plic_girqsrvd = static_cast<uint64_t>(shadow_state_what::plic_girqsrvd),
-    htif_tohost = static_cast<uint64_t>(shadow_state_what::htif_tohost),
-    htif_fromhost = static_cast<uint64_t>(shadow_state_what::htif_fromhost),
-    htif_ihalt = static_cast<uint64_t>(shadow_state_what::htif_ihalt),
-    htif_iconsole = static_cast<uint64_t>(shadow_state_what::htif_iconsole),
-    htif_iyield = static_cast<uint64_t>(shadow_state_what::htif_iyield),
+    x0 = static_cast<uint64_t>(shadow_registers_what::x0),
+    x1 = static_cast<uint64_t>(shadow_registers_what::x1),
+    x2 = static_cast<uint64_t>(shadow_registers_what::x2),
+    x3 = static_cast<uint64_t>(shadow_registers_what::x3),
+    x4 = static_cast<uint64_t>(shadow_registers_what::x4),
+    x5 = static_cast<uint64_t>(shadow_registers_what::x5),
+    x6 = static_cast<uint64_t>(shadow_registers_what::x6),
+    x7 = static_cast<uint64_t>(shadow_registers_what::x7),
+    x8 = static_cast<uint64_t>(shadow_registers_what::x8),
+    x9 = static_cast<uint64_t>(shadow_registers_what::x9),
+    x10 = static_cast<uint64_t>(shadow_registers_what::x10),
+    x11 = static_cast<uint64_t>(shadow_registers_what::x11),
+    x12 = static_cast<uint64_t>(shadow_registers_what::x12),
+    x13 = static_cast<uint64_t>(shadow_registers_what::x13),
+    x14 = static_cast<uint64_t>(shadow_registers_what::x14),
+    x15 = static_cast<uint64_t>(shadow_registers_what::x15),
+    x16 = static_cast<uint64_t>(shadow_registers_what::x16),
+    x17 = static_cast<uint64_t>(shadow_registers_what::x17),
+    x18 = static_cast<uint64_t>(shadow_registers_what::x18),
+    x19 = static_cast<uint64_t>(shadow_registers_what::x19),
+    x20 = static_cast<uint64_t>(shadow_registers_what::x20),
+    x21 = static_cast<uint64_t>(shadow_registers_what::x21),
+    x22 = static_cast<uint64_t>(shadow_registers_what::x22),
+    x23 = static_cast<uint64_t>(shadow_registers_what::x23),
+    x24 = static_cast<uint64_t>(shadow_registers_what::x24),
+    x25 = static_cast<uint64_t>(shadow_registers_what::x25),
+    x26 = static_cast<uint64_t>(shadow_registers_what::x26),
+    x27 = static_cast<uint64_t>(shadow_registers_what::x27),
+    x28 = static_cast<uint64_t>(shadow_registers_what::x28),
+    x29 = static_cast<uint64_t>(shadow_registers_what::x29),
+    x30 = static_cast<uint64_t>(shadow_registers_what::x30),
+    x31 = static_cast<uint64_t>(shadow_registers_what::x31),
+    f0 = static_cast<uint64_t>(shadow_registers_what::f0),
+    f1 = static_cast<uint64_t>(shadow_registers_what::f1),
+    f2 = static_cast<uint64_t>(shadow_registers_what::f2),
+    f3 = static_cast<uint64_t>(shadow_registers_what::f3),
+    f4 = static_cast<uint64_t>(shadow_registers_what::f4),
+    f5 = static_cast<uint64_t>(shadow_registers_what::f5),
+    f6 = static_cast<uint64_t>(shadow_registers_what::f6),
+    f7 = static_cast<uint64_t>(shadow_registers_what::f7),
+    f8 = static_cast<uint64_t>(shadow_registers_what::f8),
+    f9 = static_cast<uint64_t>(shadow_registers_what::f9),
+    f10 = static_cast<uint64_t>(shadow_registers_what::f10),
+    f11 = static_cast<uint64_t>(shadow_registers_what::f11),
+    f12 = static_cast<uint64_t>(shadow_registers_what::f12),
+    f13 = static_cast<uint64_t>(shadow_registers_what::f13),
+    f14 = static_cast<uint64_t>(shadow_registers_what::f14),
+    f15 = static_cast<uint64_t>(shadow_registers_what::f15),
+    f16 = static_cast<uint64_t>(shadow_registers_what::f16),
+    f17 = static_cast<uint64_t>(shadow_registers_what::f17),
+    f18 = static_cast<uint64_t>(shadow_registers_what::f18),
+    f19 = static_cast<uint64_t>(shadow_registers_what::f19),
+    f20 = static_cast<uint64_t>(shadow_registers_what::f20),
+    f21 = static_cast<uint64_t>(shadow_registers_what::f21),
+    f22 = static_cast<uint64_t>(shadow_registers_what::f22),
+    f23 = static_cast<uint64_t>(shadow_registers_what::f23),
+    f24 = static_cast<uint64_t>(shadow_registers_what::f24),
+    f25 = static_cast<uint64_t>(shadow_registers_what::f25),
+    f26 = static_cast<uint64_t>(shadow_registers_what::f26),
+    f27 = static_cast<uint64_t>(shadow_registers_what::f27),
+    f28 = static_cast<uint64_t>(shadow_registers_what::f28),
+    f29 = static_cast<uint64_t>(shadow_registers_what::f29),
+    f30 = static_cast<uint64_t>(shadow_registers_what::f30),
+    f31 = static_cast<uint64_t>(shadow_registers_what::f31),
+    pc = static_cast<uint64_t>(shadow_registers_what::pc),
+    fcsr = static_cast<uint64_t>(shadow_registers_what::fcsr),
+    mvendorid = static_cast<uint64_t>(shadow_registers_what::mvendorid),
+    marchid = static_cast<uint64_t>(shadow_registers_what::marchid),
+    mimpid = static_cast<uint64_t>(shadow_registers_what::mimpid),
+    mcycle = static_cast<uint64_t>(shadow_registers_what::mcycle),
+    icycleinstret = static_cast<uint64_t>(shadow_registers_what::icycleinstret),
+    mstatus = static_cast<uint64_t>(shadow_registers_what::mstatus),
+    mtvec = static_cast<uint64_t>(shadow_registers_what::mtvec),
+    mscratch = static_cast<uint64_t>(shadow_registers_what::mscratch),
+    mepc = static_cast<uint64_t>(shadow_registers_what::mepc),
+    mcause = static_cast<uint64_t>(shadow_registers_what::mcause),
+    mtval = static_cast<uint64_t>(shadow_registers_what::mtval),
+    misa = static_cast<uint64_t>(shadow_registers_what::misa),
+    mie = static_cast<uint64_t>(shadow_registers_what::mie),
+    mip = static_cast<uint64_t>(shadow_registers_what::mip),
+    medeleg = static_cast<uint64_t>(shadow_registers_what::medeleg),
+    mideleg = static_cast<uint64_t>(shadow_registers_what::mideleg),
+    mcounteren = static_cast<uint64_t>(shadow_registers_what::mcounteren),
+    menvcfg = static_cast<uint64_t>(shadow_registers_what::menvcfg),
+    stvec = static_cast<uint64_t>(shadow_registers_what::stvec),
+    sscratch = static_cast<uint64_t>(shadow_registers_what::sscratch),
+    sepc = static_cast<uint64_t>(shadow_registers_what::sepc),
+    scause = static_cast<uint64_t>(shadow_registers_what::scause),
+    stval = static_cast<uint64_t>(shadow_registers_what::stval),
+    satp = static_cast<uint64_t>(shadow_registers_what::satp),
+    scounteren = static_cast<uint64_t>(shadow_registers_what::scounteren),
+    senvcfg = static_cast<uint64_t>(shadow_registers_what::senvcfg),
+    ilrsc = static_cast<uint64_t>(shadow_registers_what::ilrsc),
+    iprv = static_cast<uint64_t>(shadow_registers_what::iprv),
+    iflags_X = static_cast<uint64_t>(shadow_registers_what::iflags_X),
+    iflags_Y = static_cast<uint64_t>(shadow_registers_what::iflags_Y),
+    iflags_H = static_cast<uint64_t>(shadow_registers_what::iflags_H),
+    iunrep = static_cast<uint64_t>(shadow_registers_what::iunrep),
+    clint_mtimecmp = static_cast<uint64_t>(shadow_registers_what::clint_mtimecmp),
+    plic_girqpend = static_cast<uint64_t>(shadow_registers_what::plic_girqpend),
+    plic_girqsrvd = static_cast<uint64_t>(shadow_registers_what::plic_girqsrvd),
+    htif_tohost = static_cast<uint64_t>(shadow_registers_what::htif_tohost),
+    htif_fromhost = static_cast<uint64_t>(shadow_registers_what::htif_fromhost),
+    htif_ihalt = static_cast<uint64_t>(shadow_registers_what::htif_ihalt),
+    htif_iconsole = static_cast<uint64_t>(shadow_registers_what::htif_iconsole),
+    htif_iyield = static_cast<uint64_t>(shadow_registers_what::htif_iyield),
     first_ = x0,
     last_ = htif_iyield,
 
@@ -199,7 +198,7 @@ static constexpr machine_reg machine_reg_enum(machine_reg reg, int i) {
     return static_cast<machine_reg>(static_cast<uint64_t>(reg) + (i * sizeof(uint64_t)));
 }
 
-static constexpr machine_reg machine_reg_enum(shadow_state_what reg) {
+static constexpr machine_reg machine_reg_enum(shadow_registers_what reg) {
     return static_cast<machine_reg>(reg);
 }
 
@@ -210,7 +209,7 @@ static constexpr machine_reg machine_reg_enum(shadow_uarch_state_what reg) {
 static constexpr const char *machine_reg_get_name(machine_reg reg) {
     const auto ureg = static_cast<uint64_t>(reg);
     if (ureg >= static_cast<uint64_t>(machine_reg::first_) && ureg <= static_cast<uint64_t>(machine_reg::last_)) {
-        return shadow_state_get_what_name(static_cast<shadow_state_what>(reg));
+        return shadow_registers_get_what_name(static_cast<shadow_registers_what>(reg));
     }
     if (ureg >= static_cast<uint64_t>(machine_reg::uarch_first_) &&
         ureg <= static_cast<uint64_t>(machine_reg::uarch_last_)) {
diff --git a/src/machine-state.h b/src/machine-state.h
deleted file mode 100644
index 4c77c4649..000000000
--- a/src/machine-state.h
+++ /dev/null
@@ -1,58 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef MACHINE_STATE_H
-#define MACHINE_STATE_H
-
-/// \file
-/// \brief Cartesi machine state structure definition.
-
-#include <array>
-#include <cstdint>
-#include <vector>
-
-#include "address-range.h"
-#include "riscv-constants.h"
-#include "shadow-state.h"
-#include "tlb.h"
-
-namespace cartesi {
-
-/// \brief Machine state.
-/// \details The machine_state structure contains the entire
-/// state of a Cartesi machine.
-struct machine_state final {
-    machine_state() = default;
-    ~machine_state() = default;
-
-    /// \brief No copy or move constructor or assignment
-    machine_state(const machine_state &other) = delete;
-    machine_state(machine_state &&other) = delete;
-    machine_state &operator=(const machine_state &other) = delete;
-    machine_state &operator=(machine_state &&other) = delete;
-
-    // Shadow region.
-    registers_state registers; ///< Registers
-
-    // Penumbra region, the fields below are not stored in the backing file,
-    // it's only visible in host resident memory during runtime.
-    tlb_state tlb{};   ///< TLB state
-    bool soft_yield{}; ///< Whether soft yield is enabled
-};
-
-} // namespace cartesi
-
-#endif
diff --git a/src/machine.cpp b/src/machine.cpp
index 2b5546cda..8110594fe 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -19,6 +19,7 @@
 
 #include <algorithm>
 #include <array>
+#include <bit>
 #include <cerrno>
 #include <cstdint>
 #include <cstdio>
@@ -40,6 +41,7 @@
 #include "device-state-access.h"
 #include "dtb.h"
 #include "host-addr.h"
+#include "hot-tlb.h"
 #include "htif-constants.h"
 #include "i-device-state-access.h"
 #include "i-hasher.h"
@@ -51,6 +53,7 @@
 #include "os.h"
 #include "pmas-constants.h"
 #include "pmas.h"
+#include "processor-state.h"
 #include "record-send-cmio-state-access.h"
 #include "record-step-state-access.h"
 #include "replay-send-cmio-state-access.h"
@@ -61,7 +64,6 @@
 #include "shadow-tlb.h"
 #include "state-access.h"
 #include "strict-aliasing.h"
-#include "tlb.h"
 #include "translate-virtual-address.h"
 #include "uarch-constants.h"
 #include "uarch-interpret.h"
@@ -81,105 +83,115 @@ namespace cartesi {
 
 using namespace std::string_literals;
 
-void machine::init_uarch_processor(const uarch_config &c) {
-    using reg = machine_reg;
-    write_reg(reg::uarch_pc, c.processor.registers.pc);
-    write_reg(reg::uarch_cycle, c.processor.registers.cycle);
-    write_reg(reg::uarch_halt_flag, c.processor.registers.halt_flag);
-    // General purpose registers
-    for (int i = 1; i < UARCH_X_REG_COUNT; i++) {
-        write_reg(machine_reg_enum(reg::uarch_x0, i), c.processor.registers.x[i]);
+void machine::init_uarch_processor(const uarch_processor_config &p) {
+    if (p.backing_store.data_filename.empty() || p.backing_store.create) {
+        // Initialize to default values first
+        *m_us = uarch_processor_state{};
+
+        // Initialize registers
+        write_reg(reg::uarch_pc, p.registers.pc);
+        write_reg(reg::uarch_cycle, p.registers.cycle);
+        write_reg(reg::uarch_halt_flag, p.registers.halt_flag);
+        // General purpose registers
+        for (int i = 1; i < UARCH_X_REG_COUNT; i++) {
+            write_reg(machine_reg_enum(reg::uarch_x0, i), p.registers.x[i]);
+        }
     }
 }
 
-void machine::init_registers(registers_state &p, const machine_runtime_config &r) {
+void machine::init_processor(processor_config &p, const machine_runtime_config &r) {
+    if (p.backing_store.data_filename.empty() || p.backing_store.create) {
+        // Initialize to default values first
+        *m_s = processor_state{};
 
-    if (p.marchid == UINT64_C(-1)) {
-        p.marchid = MARCHID_INIT;
-    }
+        // Initialize registers
+        if (p.registers.marchid == UINT64_C(-1)) {
+            p.registers.marchid = MARCHID_INIT;
+        }
 
-    if (p.marchid != MARCHID_INIT && !r.skip_version_check) {
-        throw std::invalid_argument{"marchid mismatch, emulator version is incompatible"};
-    }
+        if (p.registers.marchid != MARCHID_INIT && !r.skip_version_check) {
+            throw std::invalid_argument{"marchid mismatch, emulator version is incompatible"};
+        }
 
-    if (p.mvendorid == UINT64_C(-1)) {
-        p.mvendorid = MVENDORID_INIT;
-    }
+        if (p.registers.mvendorid == UINT64_C(-1)) {
+            p.registers.mvendorid = MVENDORID_INIT;
+        }
 
-    if (p.mvendorid != MVENDORID_INIT && !r.skip_version_check) {
-        throw std::invalid_argument{"mvendorid mismatch, emulator version is incompatible"};
-    }
+        if (p.registers.mvendorid != MVENDORID_INIT && !r.skip_version_check) {
+            throw std::invalid_argument{"mvendorid mismatch, emulator version is incompatible"};
+        }
 
-    if (p.mimpid == UINT64_C(-1)) {
-        p.mimpid = MIMPID_INIT;
-    }
+        if (p.registers.mimpid == UINT64_C(-1)) {
+            p.registers.mimpid = MIMPID_INIT;
+        }
 
-    if (p.mimpid != MIMPID_INIT && !r.skip_version_check) {
-        throw std::invalid_argument{"mimpid mismatch, emulator version is incompatible"};
-    }
+        if (p.registers.mimpid != MIMPID_INIT && !r.skip_version_check) {
+            throw std::invalid_argument{"mimpid mismatch, emulator version is incompatible"};
+        }
 
-    // General purpose registers
-    for (int i = 1; i < X_REG_COUNT; i++) {
-        write_reg(machine_reg_enum(reg::x0, i), p.x[i]);
-    }
-
-    // Floating-point registers
-    for (int i = 0; i < F_REG_COUNT; i++) {
-        write_reg(machine_reg_enum(reg::f0, i), p.f[i]);
-    }
-
-    // Named registers
-    write_reg(reg::pc, p.pc);
-    write_reg(reg::fcsr, p.fcsr);
-    write_reg(reg::mcycle, p.mcycle);
-    write_reg(reg::icycleinstret, p.icycleinstret);
-    write_reg(reg::mstatus, p.mstatus);
-    write_reg(reg::mtvec, p.mtvec);
-    write_reg(reg::mscratch, p.mscratch);
-    write_reg(reg::mepc, p.mepc);
-    write_reg(reg::mcause, p.mcause);
-    write_reg(reg::mtval, p.mtval);
-    write_reg(reg::misa, p.misa);
-    write_reg(reg::mie, p.mie);
-    write_reg(reg::mip, p.mip);
-    write_reg(reg::medeleg, p.medeleg);
-    write_reg(reg::mideleg, p.mideleg);
-    write_reg(reg::mcounteren, p.mcounteren);
-    write_reg(reg::menvcfg, p.menvcfg);
-    write_reg(reg::stvec, p.stvec);
-    write_reg(reg::sscratch, p.sscratch);
-    write_reg(reg::sepc, p.sepc);
-    write_reg(reg::scause, p.scause);
-    write_reg(reg::stval, p.stval);
-    write_reg(reg::satp, p.satp);
-    write_reg(reg::scounteren, p.scounteren);
-    write_reg(reg::senvcfg, p.senvcfg);
-    write_reg(reg::ilrsc, p.ilrsc);
-    write_reg(reg::iprv, p.iprv);
-    write_reg(reg::iflags_X, p.iflags.X);
-    write_reg(reg::iflags_Y, p.iflags.Y);
-    write_reg(reg::iflags_H, p.iflags.H);
-    write_reg(reg::iunrep, p.iunrep);
-
-    // HTIF
-    write_reg(reg::htif_tohost, p.htif.tohost);
-    write_reg(reg::htif_fromhost, p.htif.fromhost);
-    write_reg(reg::htif_ihalt, p.htif.ihalt);
-    write_reg(reg::htif_iconsole, p.htif.iconsole);
-    write_reg(reg::htif_iyield, p.htif.iyield);
-
-    // CLINT
-    write_reg(reg::clint_mtimecmp, p.clint.mtimecmp);
-
-    // PLIC
-    write_reg(reg::plic_girqpend, p.plic.girqpend);
-    write_reg(reg::plic_girqsrvd, p.plic.girqsrvd);
+        // General purpose registers
+        for (int i = 1; i < X_REG_COUNT; i++) {
+            write_reg(machine_reg_enum(reg::x0, i), p.registers.x[i]);
+        }
+
+        // Floating-point registers
+        for (int i = 0; i < F_REG_COUNT; i++) {
+            write_reg(machine_reg_enum(reg::f0, i), p.registers.f[i]);
+        }
+
+        // Named registers
+        write_reg(reg::pc, p.registers.pc);
+        write_reg(reg::fcsr, p.registers.fcsr);
+        write_reg(reg::mcycle, p.registers.mcycle);
+        write_reg(reg::icycleinstret, p.registers.icycleinstret);
+        write_reg(reg::mstatus, p.registers.mstatus);
+        write_reg(reg::mtvec, p.registers.mtvec);
+        write_reg(reg::mscratch, p.registers.mscratch);
+        write_reg(reg::mepc, p.registers.mepc);
+        write_reg(reg::mcause, p.registers.mcause);
+        write_reg(reg::mtval, p.registers.mtval);
+        write_reg(reg::misa, p.registers.misa);
+        write_reg(reg::mie, p.registers.mie);
+        write_reg(reg::mip, p.registers.mip);
+        write_reg(reg::medeleg, p.registers.medeleg);
+        write_reg(reg::mideleg, p.registers.mideleg);
+        write_reg(reg::mcounteren, p.registers.mcounteren);
+        write_reg(reg::menvcfg, p.registers.menvcfg);
+        write_reg(reg::stvec, p.registers.stvec);
+        write_reg(reg::sscratch, p.registers.sscratch);
+        write_reg(reg::sepc, p.registers.sepc);
+        write_reg(reg::scause, p.registers.scause);
+        write_reg(reg::stval, p.registers.stval);
+        write_reg(reg::satp, p.registers.satp);
+        write_reg(reg::scounteren, p.registers.scounteren);
+        write_reg(reg::senvcfg, p.registers.senvcfg);
+        write_reg(reg::ilrsc, p.registers.ilrsc);
+        write_reg(reg::iprv, p.registers.iprv);
+        write_reg(reg::iflags_X, p.registers.iflags.X);
+        write_reg(reg::iflags_Y, p.registers.iflags.Y);
+        write_reg(reg::iflags_H, p.registers.iflags.H);
+        write_reg(reg::iunrep, p.registers.iunrep);
+
+        // HTIF registers
+        write_reg(reg::htif_tohost, p.registers.htif.tohost);
+        write_reg(reg::htif_fromhost, p.registers.htif.fromhost);
+        write_reg(reg::htif_ihalt, p.registers.htif.ihalt);
+        write_reg(reg::htif_iconsole, p.registers.htif.iconsole);
+        write_reg(reg::htif_iyield, p.registers.htif.iyield);
+
+        // CLINT registers
+        write_reg(reg::clint_mtimecmp, p.registers.clint.mtimecmp);
+
+        // PLIC registers
+        write_reg(reg::plic_girqpend, p.registers.plic.girqpend);
+        write_reg(reg::plic_girqsrvd, p.registers.plic.girqsrvd);
+    }
 }
 
 void machine::init_pmas_contents(const pmas_config &config) {
     static_assert(sizeof(pmas_state) == PMA_MAX * 2 * sizeof(uint64_t), "inconsistent PMAs state length");
     static_assert(AR_PMAS_LENGTH >= sizeof(pmas_state), "PMAs address range too short");
-    if (config.backing_store.data_filename.empty()) {
+    if (config.backing_store.data_filename.empty() || config.backing_store.create) {
         auto &pmas = m_ars.find(AR_PMAS_START, AR_PMAS_LENGTH);
         if (!pmas.is_memory()) {
             throw std::runtime_error{"initialization error: PMAs memory address range not found"};
@@ -191,30 +203,47 @@ void machine::init_pmas_contents(const pmas_config &config) {
     }
 }
 
-void machine::init_tlb_contents(const tlb_config &config) {
-    if (const auto &image_filename = config.backing_store.data_filename; !image_filename.empty()) {
-        auto shadow_tlb_ptr = make_unique_mmap<shadow_tlb_state>(image_filename.c_str(), 1, false /* not shared */);
-        auto &shadow_tlb = *shadow_tlb_ptr;
-        for (auto set_index : {TLB_CODE, TLB_READ, TLB_WRITE}) {
-            for (uint64_t slot_index = 0; slot_index < TLB_SET_SIZE; ++slot_index) {
-                const auto vaddr_page = shadow_tlb[set_index][slot_index].vaddr_page;
-                const auto vp_offset = shadow_tlb[set_index][slot_index].vp_offset;
-                const auto pma_index = shadow_tlb[set_index][slot_index].pma_index;
-                check_shadow_tlb(set_index, slot_index, vaddr_page, vp_offset, pma_index, "stored TLB is corrupt: "s);
-                write_shadow_tlb(set_index, slot_index, vaddr_page, vp_offset, pma_index);
+void machine::init_hot_tlb_contents() {
+    for (auto set_index : {TLB_CODE, TLB_READ, TLB_WRITE}) {
+        for (uint64_t slot_index = 0; slot_index < TLB_SET_SIZE; ++slot_index) {
+            const auto &shadow_slot = m_s->shadow.tlb[set_index][slot_index];
+            const auto vaddr_page = shadow_slot.vaddr_page;
+            const auto vp_offset = shadow_slot.vp_offset;
+            const auto pma_index = shadow_slot.pma_index;
+            const auto zero_padding_ = shadow_slot.zero_padding_;
+            host_addr vh_offset{};
+            if (zero_padding_ != 0) {
+                throw std::domain_error{"stored TLB is corrupt: inconsistent padding"};
             }
-        }
-    } else {
-        for (auto set_index : {TLB_CODE, TLB_READ, TLB_WRITE}) {
-            for (uint64_t slot_index = 0; slot_index < TLB_SET_SIZE; ++slot_index) {
-                write_tlb(set_index, slot_index, TLB_INVALID_PAGE, host_addr{}, TLB_INVALID_PMA_INDEX);
+            if (vaddr_page != TLB_INVALID_PAGE) {
+                const auto &ar = read_pma(pma_index);
+                if (!ar.is_memory()) {
+                    throw std::invalid_argument{"stored TLB is corrupt: pma_index does not point to memory range"s};
+                }
+                if ((vaddr_page & PAGE_OFFSET_MASK) != 0) {
+                    throw std::invalid_argument{"stored TLB is corrupt: vaddr_page is not aligned"s};
+                }
+                const auto paddr_page = vaddr_page + vp_offset;
+                if ((paddr_page & PAGE_OFFSET_MASK) != 0) {
+                    throw std::invalid_argument{"stored TLB is corrupt: vp_offset is not aligned"s};
+                }
+                const auto pmas_end = ar.get_start() + (ar.get_length() - AR_PAGE_SIZE);
+                if (paddr_page < ar.get_start() || paddr_page > pmas_end) {
+                    throw std::invalid_argument{"stored TLB is corrupt: vp_offset is inconsistent with pma_index"s};
+                }
+                vh_offset = get_host_addr(paddr_page, pma_index) - vaddr_page;
+            } else if (pma_index != TLB_INVALID_PMA_INDEX || vp_offset != 0) {
+                throw std::domain_error{"stored TLB is corrupt: inconsistent empty slot"};
             }
+            auto &hot_slot = m_s->penumbra.tlb[set_index][slot_index];
+            hot_slot.vaddr_page = vaddr_page;
+            hot_slot.vh_offset = vh_offset;
         }
     }
 }
 
 void machine::init_dtb_contents(const machine_config &config) {
-    if (config.dtb.backing_store.data_filename.empty()) {
+    if (config.dtb.backing_store.data_filename.empty() || config.dtb.backing_store.create) {
         auto &dtb = m_ars.find(AR_DTB_START, AR_DTB_LENGTH);
         if (!dtb.is_memory()) {
             throw std::runtime_error{"initialization error: DTB memory address range not found"};
@@ -224,30 +253,34 @@ void machine::init_dtb_contents(const machine_config &config) {
 }
 
 // ??D It is best to leave the std::move() on r because it may one day be necessary!
-// NOLINTNEXTLINE(hicpp-move-const-arg,performance-move-const-arg)
-machine::machine(machine_config c, machine_runtime_config r) : m_c{std::move(c)}, m_r{std::move(r)}, m_ars{m_c} {
-    init_uarch_processor(m_c.uarch);
-    init_registers(m_c.processor.registers, m_r);
-    m_s.soft_yield = m_r.soft_yield;
+machine::machine(machine_config c, machine_runtime_config r) :
+    m_c{std::move(c)}, // NOLINT(hicpp-move-const-arg,performance-move-const-arg)
+    m_r{std::move(r)}, // NOLINT(hicpp-move-const-arg,performance-move-const-arg)
+    m_ars{m_c},
+    m_s{std::bit_cast<processor_state *>(m_ars.find(AR_SHADOW_STATE_START, AR_SHADOW_STATE_LENGTH).get_host_memory())},
+    m_us{std::bit_cast<uarch_processor_state *>(
+        m_ars.find(AR_SHADOW_UARCH_STATE_START, AR_SHADOW_UARCH_STATE_LENGTH).get_host_memory())} {
+    init_processor(m_c.processor, m_r);
+    init_uarch_processor(m_c.uarch.processor);
     init_pmas_contents(m_c.pmas);
-    init_tlb_contents(m_c.tlb);
+    init_hot_tlb_contents();
     init_dtb_contents(m_c);
-    init_tty(m_c.processor.registers.htif, m_r.htif, m_c.processor.registers.iunrep);
+    init_tty();
     // Disable SIGPIPE handler, because this signal can be raised and terminate the emulator process
     // when calling write() on closed file descriptors.
     // This can happen with the stdout console file descriptors or network file descriptors.
     os_disable_sigpipe();
 }
 
-void machine::init_tty(const htif_state &h, const htif_runtime_config &r, uint64_t iunrep) const {
+void machine::init_tty() {
     // Initialize TTY if console input is enabled
-    if ((h.iconsole & HTIF_CONSOLE_CMD_GETCHAR_MASK) != 0 || has_virtio_console()) {
-        if (iunrep == 0) {
+    if (has_htif_console() || has_virtio_console()) {
+        if (read_reg(reg::iunrep) == 0) {
             throw std::invalid_argument{"TTY stdin is only supported in unreproducible machines"};
         }
         os_open_tty();
+        m_tty_opened = true;
     }
-    os_silence_putchar(r.no_console_putchar);
 }
 
 static void load_hash(const std::string &dir, machine::hash_type &h) {
@@ -310,7 +343,7 @@ bool machine::has_virtio_console() const {
 }
 
 bool machine::has_htif_console() const {
-    return static_cast<bool>(read_reg(reg::htif_iconsole) & HTIF_CONSOLE_CMD_GETCHAR);
+    return static_cast<bool>(read_reg(reg::htif_iconsole) & HTIF_CONSOLE_CMD_GETCHAR_MASK);
 }
 
 /// \brief Returns copy of initialization config.
@@ -326,98 +359,6 @@ const machine_runtime_config &machine::get_runtime_config() const {
 /// \brief Changes the machine runtime config.
 void machine::set_runtime_config(machine_runtime_config r) {
     m_r = std::move(r); // NOLINT(hicpp-move-const-arg,performance-move-const-arg)
-    m_s.soft_yield = m_r.soft_yield;
-    os_silence_putchar(m_r.htif.no_console_putchar);
-}
-
-static void clear_backing_store_filenames(backing_store_config &config) {
-    config.data_filename.clear();
-    config.dht_filename.clear();
-}
-
-machine_config machine::get_serialization_config() const {
-    if (read_reg(reg::iunrep) != 0) {
-        throw std::runtime_error{"cannot serialize configuration of unreproducible machines"};
-    }
-    // Initialize with copy of original config
-    machine_config c = m_c;
-    // Copy current registers state to config
-    for (int i = 1; i < X_REG_COUNT; ++i) {
-        c.processor.registers.x[i] = read_reg(machine_reg_enum(reg::x0, i));
-    }
-    for (int i = 0; i < F_REG_COUNT; ++i) {
-        c.processor.registers.f[i] = read_reg(machine_reg_enum(reg::f0, i));
-    }
-    c.processor.registers.pc = read_reg(reg::pc);
-    c.processor.registers.fcsr = read_reg(reg::fcsr);
-    c.processor.registers.mvendorid = read_reg(reg::mvendorid);
-    c.processor.registers.marchid = read_reg(reg::marchid);
-    c.processor.registers.mimpid = read_reg(reg::mimpid);
-    c.processor.registers.mcycle = read_reg(reg::mcycle);
-    c.processor.registers.icycleinstret = read_reg(reg::icycleinstret);
-    c.processor.registers.mstatus = read_reg(reg::mstatus);
-    c.processor.registers.mtvec = read_reg(reg::mtvec);
-    c.processor.registers.mscratch = read_reg(reg::mscratch);
-    c.processor.registers.mepc = read_reg(reg::mepc);
-    c.processor.registers.mcause = read_reg(reg::mcause);
-    c.processor.registers.mtval = read_reg(reg::mtval);
-    c.processor.registers.misa = read_reg(reg::misa);
-    c.processor.registers.mie = read_reg(reg::mie);
-    c.processor.registers.mip = read_reg(reg::mip);
-    c.processor.registers.medeleg = read_reg(reg::medeleg);
-    c.processor.registers.mideleg = read_reg(reg::mideleg);
-    c.processor.registers.mcounteren = read_reg(reg::mcounteren);
-    c.processor.registers.menvcfg = read_reg(reg::menvcfg);
-    c.processor.registers.stvec = read_reg(reg::stvec);
-    c.processor.registers.sscratch = read_reg(reg::sscratch);
-    c.processor.registers.sepc = read_reg(reg::sepc);
-    c.processor.registers.scause = read_reg(reg::scause);
-    c.processor.registers.stval = read_reg(reg::stval);
-    c.processor.registers.satp = read_reg(reg::satp);
-    c.processor.registers.scounteren = read_reg(reg::scounteren);
-    c.processor.registers.senvcfg = read_reg(reg::senvcfg);
-    c.processor.registers.ilrsc = read_reg(reg::ilrsc);
-    c.processor.registers.iprv = read_reg(reg::iprv);
-    c.processor.registers.iflags.X = read_reg(reg::iflags_X);
-    c.processor.registers.iflags.Y = read_reg(reg::iflags_Y);
-    c.processor.registers.iflags.H = read_reg(reg::iflags_H);
-    c.processor.registers.iunrep = read_reg(reg::iunrep);
-    // Copy current CLINT state to config
-    c.processor.registers.clint.mtimecmp = read_reg(reg::clint_mtimecmp);
-    // Copy current PLIC state to config
-    c.processor.registers.plic.girqpend = read_reg(reg::plic_girqpend);
-    c.processor.registers.plic.girqsrvd = read_reg(reg::plic_girqsrvd);
-    // Copy current HTIF state to config
-    c.processor.registers.htif.tohost = read_reg(reg::htif_tohost);
-    c.processor.registers.htif.fromhost = read_reg(reg::htif_fromhost);
-    c.processor.registers.htif.ihalt = read_reg(reg::htif_ihalt);
-    c.processor.registers.htif.iconsole = read_reg(reg::htif_iconsole);
-    c.processor.registers.htif.iyield = read_reg(reg::htif_iyield);
-    // Ensure we don't mess with DTB by writing the original bootargs
-    // over the potentially modified memory region we serialize
-    c.dtb.bootargs.clear();
-    // Copy current uarch state to config
-    c.uarch.processor.registers.cycle = read_reg(reg::uarch_cycle);
-    c.uarch.processor.registers.halt_flag = read_reg(reg::uarch_halt_flag);
-    c.uarch.processor.registers.pc = read_reg(reg::uarch_pc);
-    for (int i = 1; i < UARCH_X_REG_COUNT; i++) {
-        c.uarch.processor.registers.x[i] = read_reg(machine_reg_enum(reg::uarch_x0, i));
-    }
-    // Remove backing filenames from serialization
-    // (they will be ignored by save and load for security reasons)
-    clear_backing_store_filenames(c.ram.backing_store);
-    clear_backing_store_filenames(c.dtb.backing_store);
-    for (auto &f : c.flash_drive) {
-        clear_backing_store_filenames(f.backing_store);
-    }
-    clear_backing_store_filenames(c.tlb.backing_store);
-    clear_backing_store_filenames(c.cmio.rx_buffer.backing_store);
-    clear_backing_store_filenames(c.cmio.tx_buffer.backing_store);
-    clear_backing_store_filenames(c.pmas.backing_store);
-    clear_backing_store_filenames(c.uarch.ram.backing_store);
-    c.hash_tree.sht_filename.clear();
-    c.hash_tree.phtc_filename.clear();
-    return c;
 }
 
 uint64_t machine::get_paddr(host_addr haddr, uint64_t pma_index) const {
@@ -441,62 +382,30 @@ void machine::mark_dirty_page(host_addr haddr, uint64_t pma_index) {
 uint64_t machine::read_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, shadow_tlb_what reg) const {
     switch (reg) {
         case shadow_tlb_what::vaddr_page:
-            return m_s.tlb.hot[set_index][slot_index].vaddr_page;
-        case shadow_tlb_what::vp_offset: {
-            const auto vaddr_page = m_s.tlb.hot[set_index][slot_index].vaddr_page;
-            if (vaddr_page != TLB_INVALID_PAGE) {
-                const auto vh_offset = m_s.tlb.hot[set_index][slot_index].vh_offset;
-                const auto haddr_page = vaddr_page + vh_offset;
-                const auto pma_index = m_s.tlb.cold[set_index][slot_index].pma_index;
-                return get_paddr(haddr_page, pma_index) - vaddr_page;
-            }
-            return 0;
-        }
+            return m_s->shadow.tlb[set_index][slot_index].vaddr_page;
+        case shadow_tlb_what::vp_offset:
+            return m_s->shadow.tlb[set_index][slot_index].vp_offset;
         case shadow_tlb_what::pma_index:
-            return m_s.tlb.cold[set_index][slot_index].pma_index;
+            return m_s->shadow.tlb[set_index][slot_index].pma_index;
         case shadow_tlb_what::zero_padding_:
-            return 0;
+            return m_s->shadow.tlb[set_index][slot_index].zero_padding_;
         default:
             throw std::domain_error{"unknown shadow TLB register"};
     }
 }
 
-void machine::check_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset,
-    uint64_t pma_index, const std::string &prefix) const {
-    if (set_index > TLB_LAST_) {
-        throw std::domain_error{prefix + "TLB set index is out of range"s};
-    }
-    if (slot_index >= TLB_SET_SIZE) {
-        throw std::domain_error{prefix + "TLB slot index is out of range"s};
-    }
-    if (vaddr_page != TLB_INVALID_PAGE) {
-        const auto &ar = read_pma(pma_index);
-        if (ar.is_empty()) {
-            throw std::domain_error{prefix + "pma_index is out of range"s};
-        }
-        if (!ar.is_memory()) {
-            throw std::invalid_argument{prefix + "pma_index does not point to memory range"s};
-        }
-        if ((vaddr_page & PAGE_OFFSET_MASK) != 0) {
-            throw std::invalid_argument{prefix + "vaddr_page is not aligned"s};
-        }
-        const auto paddr_page = vaddr_page + vp_offset;
-        if ((paddr_page & PAGE_OFFSET_MASK) != 0) {
-            throw std::invalid_argument{prefix + "vp_offset is not aligned"s};
-        }
-        if (paddr_page < ar.get_start() || paddr_page >= ar.get_end()) {
-            throw std::invalid_argument{prefix + "vp_offset is inconsistent with pma_index"s};
-        }
-    } else if (pma_index != TLB_INVALID_PMA_INDEX || vp_offset != 0) {
-        throw std::domain_error{prefix + "inconsistent empty TLB slot"};
-    }
-}
-
 void machine::write_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, host_addr vh_offset,
     uint64_t pma_index) {
-    m_s.tlb.hot[set_index][slot_index].vaddr_page = vaddr_page;
-    m_s.tlb.hot[set_index][slot_index].vh_offset = vh_offset;
-    m_s.tlb.cold[set_index][slot_index].pma_index = pma_index;
+    uint64_t vp_offset = 0;
+    if (vaddr_page != TLB_INVALID_PAGE) {
+        vp_offset = get_paddr(vh_offset, pma_index);
+    }
+    m_s->penumbra.tlb[set_index][slot_index].vaddr_page = vaddr_page;
+    m_s->penumbra.tlb[set_index][slot_index].vh_offset = vh_offset;
+    m_s->shadow.tlb[set_index][slot_index].vaddr_page = vaddr_page;
+    m_s->shadow.tlb[set_index][slot_index].vp_offset = vp_offset;
+    m_s->shadow.tlb[set_index][slot_index].pma_index = pma_index;
+    m_s->shadow.tlb[set_index][slot_index].zero_padding_ = 0;
 }
 
 void machine::write_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset,
@@ -531,44 +440,28 @@ static void store_hash(const machine::hash_type &h, const std::string &dir) {
 void machine::store_address_ranges(const machine_config &c, const std::string &dir) const {
     store_address_range(m_ars.find<uint64_t>(AR_DTB_START), dir);
     store_address_range(m_ars.find<uint64_t>(AR_RAM_START), dir);
-    store_address_range(m_ars.find<uint64_t>(AR_SHADOW_TLB_START), dir);
+    store_address_range(m_ars.find<uint64_t>(AR_SHADOW_STATE_START), dir);
     for (const auto &f : c.flash_drive) {
         store_address_range(m_ars.find<uint64_t>(f.start), dir);
     }
     store_address_range(m_ars.find<uint64_t>(AR_CMIO_RX_BUFFER_START), dir);
     store_address_range(m_ars.find<uint64_t>(AR_CMIO_TX_BUFFER_START), dir);
+    store_address_range(m_ars.find<uint64_t>(AR_SHADOW_UARCH_STATE_START), dir);
     store_address_range(m_ars.find<uint64_t>(AR_UARCH_RAM_START), dir);
     store_address_range(m_ars.find<uint64_t>(AR_PMAS_START), dir);
 }
 
-void machine::store_address_range(const address_range &ar, const std::string &dir) const {
+void machine::store_address_range(const address_range &ar, const std::string &dir) {
     if (ar.is_empty()) {
         throw std::runtime_error{"attempt to store empty address range "s.append(ar.get_description())};
     }
     auto name = machine_config::get_data_filename(dir, ar.get_start(), ar.get_length());
     auto fp = make_unique_fopen(name.c_str(), "wb"); // will throw if it fails
-    // If we have do not have a pointer to the address range memory, use peek
-    // At the moment, this is the case only for the shadow TLB.
     if (!ar.is_memory() || ar.get_host_memory() == nullptr) {
-        auto scratch = make_unique_calloc<unsigned char>(AR_PAGE_SIZE); // will throw if it fails
-        for (uint64_t offset = 0; offset < ar.get_length(); offset += AR_PAGE_SIZE) {
-            const unsigned char *page_data = nullptr;
-            if (!ar.peek(*this, offset, AR_PAGE_SIZE, &page_data, scratch.get())) {
-                throw std::runtime_error{"peek failed"};
-            }
-            if (page_data == nullptr) {
-                memset(scratch.get(), 0, AR_PAGE_SIZE);
-                page_data = scratch.get();
-            }
-            if (fwrite(page_data, 1, AR_PAGE_SIZE, fp.get()) != AR_PAGE_SIZE) {
-                throw std::system_error{errno, std::generic_category(), "error writing to '" + name + "'"};
-            }
-        }
-        // Otherwise, use memory directly
-    } else {
-        if (fwrite(ar.get_host_memory(), 1, ar.get_length(), fp.get()) != ar.get_length()) {
-            throw std::runtime_error{"error writing to '" + name + "'"};
-        }
+        throw std::runtime_error{"attempt to store non memory address range "s.append(ar.get_description())};
+    }
+    if (fwrite(ar.get_host_memory(), 1, ar.get_length(), fp.get()) != ar.get_length()) {
+        throw std::runtime_error{"error writing to '" + name + "'"};
     }
 }
 
@@ -587,7 +480,8 @@ void machine::store(const std::string &dir) const {
         m_t.get_root_hash(h);
         store_hash(h, dir);
     }
-    auto c = get_serialization_config();
+    machine_config c = m_c;
+    c.adjust_backing_stores(".");
     c.store(dir);
     store_address_ranges(c, dir);
 }
@@ -650,8 +544,7 @@ void machine::dump_stats() {
 }
 
 machine::~machine() {
-    // Cleanup TTY if console input was enabled
-    if ((m_c.processor.registers.htif.iconsole & HTIF_CONSOLE_CMD_GETCHAR_MASK) != 0 || has_virtio_console()) {
+    if (m_tty_opened) {
         os_close_tty();
     }
     dump_insn_hist();
@@ -659,140 +552,139 @@ machine::~machine() {
 }
 
 uint64_t machine::read_reg(reg r) const {
-    using reg = machine_reg;
     switch (r) {
         case reg::x0:
-            return m_s.registers.x[0];
+            return m_s->shadow.registers.x[0];
         case reg::x1:
-            return m_s.registers.x[1];
+            return m_s->shadow.registers.x[1];
         case reg::x2:
-            return m_s.registers.x[2];
+            return m_s->shadow.registers.x[2];
         case reg::x3:
-            return m_s.registers.x[3];
+            return m_s->shadow.registers.x[3];
         case reg::x4:
-            return m_s.registers.x[4];
+            return m_s->shadow.registers.x[4];
         case reg::x5:
-            return m_s.registers.x[5];
+            return m_s->shadow.registers.x[5];
         case reg::x6:
-            return m_s.registers.x[6];
+            return m_s->shadow.registers.x[6];
         case reg::x7:
-            return m_s.registers.x[7];
+            return m_s->shadow.registers.x[7];
         case reg::x8:
-            return m_s.registers.x[8];
+            return m_s->shadow.registers.x[8];
         case reg::x9:
-            return m_s.registers.x[9];
+            return m_s->shadow.registers.x[9];
         case reg::x10:
-            return m_s.registers.x[10];
+            return m_s->shadow.registers.x[10];
         case reg::x11:
-            return m_s.registers.x[11];
+            return m_s->shadow.registers.x[11];
         case reg::x12:
-            return m_s.registers.x[12];
+            return m_s->shadow.registers.x[12];
         case reg::x13:
-            return m_s.registers.x[13];
+            return m_s->shadow.registers.x[13];
         case reg::x14:
-            return m_s.registers.x[14];
+            return m_s->shadow.registers.x[14];
         case reg::x15:
-            return m_s.registers.x[15];
+            return m_s->shadow.registers.x[15];
         case reg::x16:
-            return m_s.registers.x[16];
+            return m_s->shadow.registers.x[16];
         case reg::x17:
-            return m_s.registers.x[17];
+            return m_s->shadow.registers.x[17];
         case reg::x18:
-            return m_s.registers.x[18];
+            return m_s->shadow.registers.x[18];
         case reg::x19:
-            return m_s.registers.x[19];
+            return m_s->shadow.registers.x[19];
         case reg::x20:
-            return m_s.registers.x[20];
+            return m_s->shadow.registers.x[20];
         case reg::x21:
-            return m_s.registers.x[21];
+            return m_s->shadow.registers.x[21];
         case reg::x22:
-            return m_s.registers.x[22];
+            return m_s->shadow.registers.x[22];
         case reg::x23:
-            return m_s.registers.x[23];
+            return m_s->shadow.registers.x[23];
         case reg::x24:
-            return m_s.registers.x[24];
+            return m_s->shadow.registers.x[24];
         case reg::x25:
-            return m_s.registers.x[25];
+            return m_s->shadow.registers.x[25];
         case reg::x26:
-            return m_s.registers.x[26];
+            return m_s->shadow.registers.x[26];
         case reg::x27:
-            return m_s.registers.x[27];
+            return m_s->shadow.registers.x[27];
         case reg::x28:
-            return m_s.registers.x[28];
+            return m_s->shadow.registers.x[28];
         case reg::x29:
-            return m_s.registers.x[29];
+            return m_s->shadow.registers.x[29];
         case reg::x30:
-            return m_s.registers.x[30];
+            return m_s->shadow.registers.x[30];
         case reg::x31:
-            return m_s.registers.x[31];
+            return m_s->shadow.registers.x[31];
         case reg::f0:
-            return m_s.registers.f[0];
+            return m_s->shadow.registers.f[0];
         case reg::f1:
-            return m_s.registers.f[1];
+            return m_s->shadow.registers.f[1];
         case reg::f2:
-            return m_s.registers.f[2];
+            return m_s->shadow.registers.f[2];
         case reg::f3:
-            return m_s.registers.f[3];
+            return m_s->shadow.registers.f[3];
         case reg::f4:
-            return m_s.registers.f[4];
+            return m_s->shadow.registers.f[4];
         case reg::f5:
-            return m_s.registers.f[5];
+            return m_s->shadow.registers.f[5];
         case reg::f6:
-            return m_s.registers.f[6];
+            return m_s->shadow.registers.f[6];
         case reg::f7:
-            return m_s.registers.f[7];
+            return m_s->shadow.registers.f[7];
         case reg::f8:
-            return m_s.registers.f[8];
+            return m_s->shadow.registers.f[8];
         case reg::f9:
-            return m_s.registers.f[9];
+            return m_s->shadow.registers.f[9];
         case reg::f10:
-            return m_s.registers.f[10];
+            return m_s->shadow.registers.f[10];
         case reg::f11:
-            return m_s.registers.f[11];
+            return m_s->shadow.registers.f[11];
         case reg::f12:
-            return m_s.registers.f[12];
+            return m_s->shadow.registers.f[12];
         case reg::f13:
-            return m_s.registers.f[13];
+            return m_s->shadow.registers.f[13];
         case reg::f14:
-            return m_s.registers.f[14];
+            return m_s->shadow.registers.f[14];
         case reg::f15:
-            return m_s.registers.f[15];
+            return m_s->shadow.registers.f[15];
         case reg::f16:
-            return m_s.registers.f[16];
+            return m_s->shadow.registers.f[16];
         case reg::f17:
-            return m_s.registers.f[17];
+            return m_s->shadow.registers.f[17];
         case reg::f18:
-            return m_s.registers.f[18];
+            return m_s->shadow.registers.f[18];
         case reg::f19:
-            return m_s.registers.f[19];
+            return m_s->shadow.registers.f[19];
         case reg::f20:
-            return m_s.registers.f[20];
+            return m_s->shadow.registers.f[20];
         case reg::f21:
-            return m_s.registers.f[21];
+            return m_s->shadow.registers.f[21];
         case reg::f22:
-            return m_s.registers.f[22];
+            return m_s->shadow.registers.f[22];
         case reg::f23:
-            return m_s.registers.f[23];
+            return m_s->shadow.registers.f[23];
         case reg::f24:
-            return m_s.registers.f[24];
+            return m_s->shadow.registers.f[24];
         case reg::f25:
-            return m_s.registers.f[25];
+            return m_s->shadow.registers.f[25];
         case reg::f26:
-            return m_s.registers.f[26];
+            return m_s->shadow.registers.f[26];
         case reg::f27:
-            return m_s.registers.f[27];
+            return m_s->shadow.registers.f[27];
         case reg::f28:
-            return m_s.registers.f[28];
+            return m_s->shadow.registers.f[28];
         case reg::f29:
-            return m_s.registers.f[29];
+            return m_s->shadow.registers.f[29];
         case reg::f30:
-            return m_s.registers.f[30];
+            return m_s->shadow.registers.f[30];
         case reg::f31:
-            return m_s.registers.f[31];
+            return m_s->shadow.registers.f[31];
         case reg::pc:
-            return m_s.registers.pc;
+            return m_s->shadow.registers.pc;
         case reg::fcsr:
-            return m_s.registers.fcsr;
+            return m_s->shadow.registers.fcsr;
         case reg::mvendorid:
             return MVENDORID_INIT;
         case reg::marchid:
@@ -800,165 +692,165 @@ uint64_t machine::read_reg(reg r) const {
         case reg::mimpid:
             return MIMPID_INIT;
         case reg::mcycle:
-            return m_s.registers.mcycle;
+            return m_s->shadow.registers.mcycle;
         case reg::icycleinstret:
-            return m_s.registers.icycleinstret;
+            return m_s->shadow.registers.icycleinstret;
         case reg::mstatus:
-            return m_s.registers.mstatus;
+            return m_s->shadow.registers.mstatus;
         case reg::mtvec:
-            return m_s.registers.mtvec;
+            return m_s->shadow.registers.mtvec;
         case reg::mscratch:
-            return m_s.registers.mscratch;
+            return m_s->shadow.registers.mscratch;
         case reg::mepc:
-            return m_s.registers.mepc;
+            return m_s->shadow.registers.mepc;
         case reg::mcause:
-            return m_s.registers.mcause;
+            return m_s->shadow.registers.mcause;
         case reg::mtval:
-            return m_s.registers.mtval;
+            return m_s->shadow.registers.mtval;
         case reg::misa:
-            return m_s.registers.misa;
+            return m_s->shadow.registers.misa;
         case reg::mie:
-            return m_s.registers.mie;
+            return m_s->shadow.registers.mie;
         case reg::mip:
-            return m_s.registers.mip;
+            return m_s->shadow.registers.mip;
         case reg::medeleg:
-            return m_s.registers.medeleg;
+            return m_s->shadow.registers.medeleg;
         case reg::mideleg:
-            return m_s.registers.mideleg;
+            return m_s->shadow.registers.mideleg;
         case reg::mcounteren:
-            return m_s.registers.mcounteren;
+            return m_s->shadow.registers.mcounteren;
         case reg::menvcfg:
-            return m_s.registers.menvcfg;
+            return m_s->shadow.registers.menvcfg;
         case reg::stvec:
-            return m_s.registers.stvec;
+            return m_s->shadow.registers.stvec;
         case reg::sscratch:
-            return m_s.registers.sscratch;
+            return m_s->shadow.registers.sscratch;
         case reg::sepc:
-            return m_s.registers.sepc;
+            return m_s->shadow.registers.sepc;
         case reg::scause:
-            return m_s.registers.scause;
+            return m_s->shadow.registers.scause;
         case reg::stval:
-            return m_s.registers.stval;
+            return m_s->shadow.registers.stval;
         case reg::satp:
-            return m_s.registers.satp;
+            return m_s->shadow.registers.satp;
         case reg::scounteren:
-            return m_s.registers.scounteren;
+            return m_s->shadow.registers.scounteren;
         case reg::senvcfg:
-            return m_s.registers.senvcfg;
+            return m_s->shadow.registers.senvcfg;
         case reg::ilrsc:
-            return m_s.registers.ilrsc;
+            return m_s->shadow.registers.ilrsc;
         case reg::iprv:
-            return m_s.registers.iprv;
+            return m_s->shadow.registers.iprv;
         case reg::iflags_X:
-            return m_s.registers.iflags.X;
+            return m_s->shadow.registers.iflags.X;
         case reg::iflags_Y:
-            return m_s.registers.iflags.Y;
+            return m_s->shadow.registers.iflags.Y;
         case reg::iflags_H:
-            return m_s.registers.iflags.H;
+            return m_s->shadow.registers.iflags.H;
         case reg::iunrep:
-            return m_s.registers.iunrep;
+            return m_s->shadow.registers.iunrep;
         case reg::clint_mtimecmp:
-            return m_s.registers.clint.mtimecmp;
+            return m_s->shadow.registers.clint.mtimecmp;
         case reg::plic_girqpend:
-            return m_s.registers.plic.girqpend;
+            return m_s->shadow.registers.plic.girqpend;
         case reg::plic_girqsrvd:
-            return m_s.registers.plic.girqsrvd;
+            return m_s->shadow.registers.plic.girqsrvd;
         case reg::htif_tohost:
-            return m_s.registers.htif.tohost;
+            return m_s->shadow.registers.htif.tohost;
         case reg::htif_fromhost:
-            return m_s.registers.htif.fromhost;
+            return m_s->shadow.registers.htif.fromhost;
         case reg::htif_ihalt:
-            return m_s.registers.htif.ihalt;
+            return m_s->shadow.registers.htif.ihalt;
         case reg::htif_iconsole:
-            return m_s.registers.htif.iconsole;
+            return m_s->shadow.registers.htif.iconsole;
         case reg::htif_iyield:
-            return m_s.registers.htif.iyield;
+            return m_s->shadow.registers.htif.iyield;
         case reg::uarch_x0:
-            return m_us.registers.x[0];
+            return m_us->registers.x[0];
         case reg::uarch_x1:
-            return m_us.registers.x[1];
+            return m_us->registers.x[1];
         case reg::uarch_x2:
-            return m_us.registers.x[2];
+            return m_us->registers.x[2];
         case reg::uarch_x3:
-            return m_us.registers.x[3];
+            return m_us->registers.x[3];
         case reg::uarch_x4:
-            return m_us.registers.x[4];
+            return m_us->registers.x[4];
         case reg::uarch_x5:
-            return m_us.registers.x[5];
+            return m_us->registers.x[5];
         case reg::uarch_x6:
-            return m_us.registers.x[6];
+            return m_us->registers.x[6];
         case reg::uarch_x7:
-            return m_us.registers.x[7];
+            return m_us->registers.x[7];
         case reg::uarch_x8:
-            return m_us.registers.x[8];
+            return m_us->registers.x[8];
         case reg::uarch_x9:
-            return m_us.registers.x[9];
+            return m_us->registers.x[9];
         case reg::uarch_x10:
-            return m_us.registers.x[10];
+            return m_us->registers.x[10];
         case reg::uarch_x11:
-            return m_us.registers.x[11];
+            return m_us->registers.x[11];
         case reg::uarch_x12:
-            return m_us.registers.x[12];
+            return m_us->registers.x[12];
         case reg::uarch_x13:
-            return m_us.registers.x[13];
+            return m_us->registers.x[13];
         case reg::uarch_x14:
-            return m_us.registers.x[14];
+            return m_us->registers.x[14];
         case reg::uarch_x15:
-            return m_us.registers.x[15];
+            return m_us->registers.x[15];
         case reg::uarch_x16:
-            return m_us.registers.x[16];
+            return m_us->registers.x[16];
         case reg::uarch_x17:
-            return m_us.registers.x[17];
+            return m_us->registers.x[17];
         case reg::uarch_x18:
-            return m_us.registers.x[18];
+            return m_us->registers.x[18];
         case reg::uarch_x19:
-            return m_us.registers.x[19];
+            return m_us->registers.x[19];
         case reg::uarch_x20:
-            return m_us.registers.x[20];
+            return m_us->registers.x[20];
         case reg::uarch_x21:
-            return m_us.registers.x[21];
+            return m_us->registers.x[21];
         case reg::uarch_x22:
-            return m_us.registers.x[22];
+            return m_us->registers.x[22];
         case reg::uarch_x23:
-            return m_us.registers.x[23];
+            return m_us->registers.x[23];
         case reg::uarch_x24:
-            return m_us.registers.x[24];
+            return m_us->registers.x[24];
         case reg::uarch_x25:
-            return m_us.registers.x[25];
+            return m_us->registers.x[25];
         case reg::uarch_x26:
-            return m_us.registers.x[26];
+            return m_us->registers.x[26];
         case reg::uarch_x27:
-            return m_us.registers.x[27];
+            return m_us->registers.x[27];
         case reg::uarch_x28:
-            return m_us.registers.x[28];
+            return m_us->registers.x[28];
         case reg::uarch_x29:
-            return m_us.registers.x[29];
+            return m_us->registers.x[29];
         case reg::uarch_x30:
-            return m_us.registers.x[30];
+            return m_us->registers.x[30];
         case reg::uarch_x31:
-            return m_us.registers.x[31];
+            return m_us->registers.x[31];
         case reg::uarch_pc:
-            return m_us.registers.pc;
+            return m_us->registers.pc;
         case reg::uarch_cycle:
-            return m_us.registers.cycle;
+            return m_us->registers.cycle;
         case reg::uarch_halt_flag:
-            return m_us.registers.halt_flag;
+            return m_us->registers.halt_flag;
         case reg::htif_tohost_dev:
-            return HTIF_DEV_FIELD(m_s.registers.htif.tohost);
+            return HTIF_DEV_FIELD(m_s->shadow.registers.htif.tohost);
         case reg::htif_tohost_cmd:
-            return HTIF_CMD_FIELD(m_s.registers.htif.tohost);
+            return HTIF_CMD_FIELD(m_s->shadow.registers.htif.tohost);
         case reg::htif_tohost_reason:
-            return HTIF_REASON_FIELD(m_s.registers.htif.tohost);
+            return HTIF_REASON_FIELD(m_s->shadow.registers.htif.tohost);
         case reg::htif_tohost_data:
-            return HTIF_DATA_FIELD(m_s.registers.htif.tohost);
+            return HTIF_DATA_FIELD(m_s->shadow.registers.htif.tohost);
         case reg::htif_fromhost_dev:
-            return HTIF_DEV_FIELD(m_s.registers.htif.fromhost);
+            return HTIF_DEV_FIELD(m_s->shadow.registers.htif.fromhost);
         case reg::htif_fromhost_cmd:
-            return HTIF_CMD_FIELD(m_s.registers.htif.fromhost);
+            return HTIF_CMD_FIELD(m_s->shadow.registers.htif.fromhost);
         case reg::htif_fromhost_reason:
-            return HTIF_REASON_FIELD(m_s.registers.htif.fromhost);
+            return HTIF_REASON_FIELD(m_s->shadow.registers.htif.fromhost);
         case reg::htif_fromhost_data:
-            return HTIF_DATA_FIELD(m_s.registers.htif.fromhost);
+            return HTIF_DATA_FIELD(m_s->shadow.registers.htif.fromhost);
         default:
             throw std::invalid_argument{"unknown register"};
             return 0; // never reached
@@ -970,199 +862,199 @@ void machine::write_reg(reg w, uint64_t value) {
         case reg::x0:
             throw std::invalid_argument{"register is read-only"};
         case reg::x1:
-            m_s.registers.x[1] = value;
+            m_s->shadow.registers.x[1] = value;
             break;
         case reg::x2:
-            m_s.registers.x[2] = value;
+            m_s->shadow.registers.x[2] = value;
             break;
         case reg::x3:
-            m_s.registers.x[3] = value;
+            m_s->shadow.registers.x[3] = value;
             break;
         case reg::x4:
-            m_s.registers.x[4] = value;
+            m_s->shadow.registers.x[4] = value;
             break;
         case reg::x5:
-            m_s.registers.x[5] = value;
+            m_s->shadow.registers.x[5] = value;
             break;
         case reg::x6:
-            m_s.registers.x[6] = value;
+            m_s->shadow.registers.x[6] = value;
             break;
         case reg::x7:
-            m_s.registers.x[7] = value;
+            m_s->shadow.registers.x[7] = value;
             break;
         case reg::x8:
-            m_s.registers.x[8] = value;
+            m_s->shadow.registers.x[8] = value;
             break;
         case reg::x9:
-            m_s.registers.x[9] = value;
+            m_s->shadow.registers.x[9] = value;
             break;
         case reg::x10:
-            m_s.registers.x[10] = value;
+            m_s->shadow.registers.x[10] = value;
             break;
         case reg::x11:
-            m_s.registers.x[11] = value;
+            m_s->shadow.registers.x[11] = value;
             break;
         case reg::x12:
-            m_s.registers.x[12] = value;
+            m_s->shadow.registers.x[12] = value;
             break;
         case reg::x13:
-            m_s.registers.x[13] = value;
+            m_s->shadow.registers.x[13] = value;
             break;
         case reg::x14:
-            m_s.registers.x[14] = value;
+            m_s->shadow.registers.x[14] = value;
             break;
         case reg::x15:
-            m_s.registers.x[15] = value;
+            m_s->shadow.registers.x[15] = value;
             break;
         case reg::x16:
-            m_s.registers.x[16] = value;
+            m_s->shadow.registers.x[16] = value;
             break;
         case reg::x17:
-            m_s.registers.x[17] = value;
+            m_s->shadow.registers.x[17] = value;
             break;
         case reg::x18:
-            m_s.registers.x[18] = value;
+            m_s->shadow.registers.x[18] = value;
             break;
         case reg::x19:
-            m_s.registers.x[19] = value;
+            m_s->shadow.registers.x[19] = value;
             break;
         case reg::x20:
-            m_s.registers.x[20] = value;
+            m_s->shadow.registers.x[20] = value;
             break;
         case reg::x21:
-            m_s.registers.x[21] = value;
+            m_s->shadow.registers.x[21] = value;
             break;
         case reg::x22:
-            m_s.registers.x[22] = value;
+            m_s->shadow.registers.x[22] = value;
             break;
         case reg::x23:
-            m_s.registers.x[23] = value;
+            m_s->shadow.registers.x[23] = value;
             break;
         case reg::x24:
-            m_s.registers.x[24] = value;
+            m_s->shadow.registers.x[24] = value;
             break;
         case reg::x25:
-            m_s.registers.x[25] = value;
+            m_s->shadow.registers.x[25] = value;
             break;
         case reg::x26:
-            m_s.registers.x[26] = value;
+            m_s->shadow.registers.x[26] = value;
             break;
         case reg::x27:
-            m_s.registers.x[27] = value;
+            m_s->shadow.registers.x[27] = value;
             break;
         case reg::x28:
-            m_s.registers.x[28] = value;
+            m_s->shadow.registers.x[28] = value;
             break;
         case reg::x29:
-            m_s.registers.x[29] = value;
+            m_s->shadow.registers.x[29] = value;
             break;
         case reg::x30:
-            m_s.registers.x[30] = value;
+            m_s->shadow.registers.x[30] = value;
             break;
         case reg::x31:
-            m_s.registers.x[31] = value;
+            m_s->shadow.registers.x[31] = value;
             break;
         case reg::f0:
-            m_s.registers.f[0] = value;
+            m_s->shadow.registers.f[0] = value;
             break;
         case reg::f1:
-            m_s.registers.f[1] = value;
+            m_s->shadow.registers.f[1] = value;
             break;
         case reg::f2:
-            m_s.registers.f[2] = value;
+            m_s->shadow.registers.f[2] = value;
             break;
         case reg::f3:
-            m_s.registers.f[3] = value;
+            m_s->shadow.registers.f[3] = value;
             break;
         case reg::f4:
-            m_s.registers.f[4] = value;
+            m_s->shadow.registers.f[4] = value;
             break;
         case reg::f5:
-            m_s.registers.f[5] = value;
+            m_s->shadow.registers.f[5] = value;
             break;
         case reg::f6:
-            m_s.registers.f[6] = value;
+            m_s->shadow.registers.f[6] = value;
             break;
         case reg::f7:
-            m_s.registers.f[7] = value;
+            m_s->shadow.registers.f[7] = value;
             break;
         case reg::f8:
-            m_s.registers.f[8] = value;
+            m_s->shadow.registers.f[8] = value;
             break;
         case reg::f9:
-            m_s.registers.f[9] = value;
+            m_s->shadow.registers.f[9] = value;
             break;
         case reg::f10:
-            m_s.registers.f[10] = value;
+            m_s->shadow.registers.f[10] = value;
             break;
         case reg::f11:
-            m_s.registers.f[11] = value;
+            m_s->shadow.registers.f[11] = value;
             break;
         case reg::f12:
-            m_s.registers.f[12] = value;
+            m_s->shadow.registers.f[12] = value;
             break;
         case reg::f13:
-            m_s.registers.f[13] = value;
+            m_s->shadow.registers.f[13] = value;
             break;
         case reg::f14:
-            m_s.registers.f[14] = value;
+            m_s->shadow.registers.f[14] = value;
             break;
         case reg::f15:
-            m_s.registers.f[15] = value;
+            m_s->shadow.registers.f[15] = value;
             break;
         case reg::f16:
-            m_s.registers.f[16] = value;
+            m_s->shadow.registers.f[16] = value;
             break;
         case reg::f17:
-            m_s.registers.f[17] = value;
+            m_s->shadow.registers.f[17] = value;
             break;
         case reg::f18:
-            m_s.registers.f[18] = value;
+            m_s->shadow.registers.f[18] = value;
             break;
         case reg::f19:
-            m_s.registers.f[19] = value;
+            m_s->shadow.registers.f[19] = value;
             break;
         case reg::f20:
-            m_s.registers.f[20] = value;
+            m_s->shadow.registers.f[20] = value;
             break;
         case reg::f21:
-            m_s.registers.f[21] = value;
+            m_s->shadow.registers.f[21] = value;
             break;
         case reg::f22:
-            m_s.registers.f[22] = value;
+            m_s->shadow.registers.f[22] = value;
             break;
         case reg::f23:
-            m_s.registers.f[23] = value;
+            m_s->shadow.registers.f[23] = value;
             break;
         case reg::f24:
-            m_s.registers.f[24] = value;
+            m_s->shadow.registers.f[24] = value;
             break;
         case reg::f25:
-            m_s.registers.f[25] = value;
+            m_s->shadow.registers.f[25] = value;
             break;
         case reg::f26:
-            m_s.registers.f[26] = value;
+            m_s->shadow.registers.f[26] = value;
             break;
         case reg::f27:
-            m_s.registers.f[27] = value;
+            m_s->shadow.registers.f[27] = value;
             break;
         case reg::f28:
-            m_s.registers.f[28] = value;
+            m_s->shadow.registers.f[28] = value;
             break;
         case reg::f29:
-            m_s.registers.f[29] = value;
+            m_s->shadow.registers.f[29] = value;
             break;
         case reg::f30:
-            m_s.registers.f[30] = value;
+            m_s->shadow.registers.f[30] = value;
             break;
         case reg::f31:
-            m_s.registers.f[31] = value;
+            m_s->shadow.registers.f[31] = value;
             break;
         case reg::pc:
-            m_s.registers.pc = value;
+            m_s->shadow.registers.pc = value;
             break;
         case reg::fcsr:
-            m_s.registers.fcsr = value;
+            m_s->shadow.registers.fcsr = value;
             break;
         case reg::mvendorid:
             throw std::invalid_argument{"register is read-only"};
@@ -1171,243 +1063,243 @@ void machine::write_reg(reg w, uint64_t value) {
         case reg::mimpid:
             throw std::invalid_argument{"register is read-only"};
         case reg::mcycle:
-            m_s.registers.mcycle = value;
+            m_s->shadow.registers.mcycle = value;
             break;
         case reg::icycleinstret:
-            m_s.registers.icycleinstret = value;
+            m_s->shadow.registers.icycleinstret = value;
             break;
         case reg::mstatus:
-            m_s.registers.mstatus = value;
+            m_s->shadow.registers.mstatus = value;
             break;
         case reg::mtvec:
-            m_s.registers.mtvec = value;
+            m_s->shadow.registers.mtvec = value;
             break;
         case reg::mscratch:
-            m_s.registers.mscratch = value;
+            m_s->shadow.registers.mscratch = value;
             break;
         case reg::mepc:
-            m_s.registers.mepc = value;
+            m_s->shadow.registers.mepc = value;
             break;
         case reg::mcause:
-            m_s.registers.mcause = value;
+            m_s->shadow.registers.mcause = value;
             break;
         case reg::mtval:
-            m_s.registers.mtval = value;
+            m_s->shadow.registers.mtval = value;
             break;
         case reg::misa:
-            m_s.registers.misa = value;
+            m_s->shadow.registers.misa = value;
             break;
         case reg::mie:
-            m_s.registers.mie = value;
+            m_s->shadow.registers.mie = value;
             break;
         case reg::mip:
-            m_s.registers.mip = value;
+            m_s->shadow.registers.mip = value;
             break;
         case reg::medeleg:
-            m_s.registers.medeleg = value;
+            m_s->shadow.registers.medeleg = value;
             break;
         case reg::mideleg:
-            m_s.registers.mideleg = value;
+            m_s->shadow.registers.mideleg = value;
             break;
         case reg::mcounteren:
-            m_s.registers.mcounteren = value;
+            m_s->shadow.registers.mcounteren = value;
             break;
         case reg::menvcfg:
-            m_s.registers.menvcfg = value;
+            m_s->shadow.registers.menvcfg = value;
             break;
         case reg::stvec:
-            m_s.registers.stvec = value;
+            m_s->shadow.registers.stvec = value;
             break;
         case reg::sscratch:
-            m_s.registers.sscratch = value;
+            m_s->shadow.registers.sscratch = value;
             break;
         case reg::sepc:
-            m_s.registers.sepc = value;
+            m_s->shadow.registers.sepc = value;
             break;
         case reg::scause:
-            m_s.registers.scause = value;
+            m_s->shadow.registers.scause = value;
             break;
         case reg::stval:
-            m_s.registers.stval = value;
+            m_s->shadow.registers.stval = value;
             break;
         case reg::satp:
-            m_s.registers.satp = value;
+            m_s->shadow.registers.satp = value;
             break;
         case reg::scounteren:
-            m_s.registers.scounteren = value;
+            m_s->shadow.registers.scounteren = value;
             break;
         case reg::senvcfg:
-            m_s.registers.senvcfg = value;
+            m_s->shadow.registers.senvcfg = value;
             break;
         case reg::ilrsc:
-            m_s.registers.ilrsc = value;
+            m_s->shadow.registers.ilrsc = value;
             break;
         case reg::iprv:
-            m_s.registers.iprv = value;
+            m_s->shadow.registers.iprv = value;
             break;
         case reg::iflags_X:
-            m_s.registers.iflags.X = value;
+            m_s->shadow.registers.iflags.X = value;
             break;
         case reg::iflags_Y:
-            m_s.registers.iflags.Y = value;
+            m_s->shadow.registers.iflags.Y = value;
             break;
         case reg::iflags_H:
-            m_s.registers.iflags.H = value;
+            m_s->shadow.registers.iflags.H = value;
             break;
         case reg::iunrep:
-            m_s.registers.iunrep = value;
+            m_s->shadow.registers.iunrep = value;
             break;
         case reg::clint_mtimecmp:
-            m_s.registers.clint.mtimecmp = value;
+            m_s->shadow.registers.clint.mtimecmp = value;
             break;
         case reg::plic_girqpend:
-            m_s.registers.plic.girqpend = value;
+            m_s->shadow.registers.plic.girqpend = value;
             break;
         case reg::plic_girqsrvd:
-            m_s.registers.plic.girqsrvd = value;
+            m_s->shadow.registers.plic.girqsrvd = value;
             break;
         case reg::htif_tohost:
-            m_s.registers.htif.tohost = value;
+            m_s->shadow.registers.htif.tohost = value;
             break;
         case reg::htif_fromhost:
-            m_s.registers.htif.fromhost = value;
+            m_s->shadow.registers.htif.fromhost = value;
             break;
         case reg::htif_ihalt:
-            m_s.registers.htif.ihalt = value;
+            m_s->shadow.registers.htif.ihalt = value;
             break;
         case reg::htif_iconsole:
-            m_s.registers.htif.iconsole = value;
+            m_s->shadow.registers.htif.iconsole = value;
             break;
         case reg::htif_iyield:
-            m_s.registers.htif.iyield = value;
+            m_s->shadow.registers.htif.iyield = value;
             break;
         case reg::uarch_x0:
             throw std::invalid_argument{"register is read-only"};
         case reg::uarch_x1:
-            m_us.registers.x[1] = value;
+            m_us->registers.x[1] = value;
             break;
         case reg::uarch_x2:
-            m_us.registers.x[2] = value;
+            m_us->registers.x[2] = value;
             break;
         case reg::uarch_x3:
-            m_us.registers.x[3] = value;
+            m_us->registers.x[3] = value;
             break;
         case reg::uarch_x4:
-            m_us.registers.x[4] = value;
+            m_us->registers.x[4] = value;
             break;
         case reg::uarch_x5:
-            m_us.registers.x[5] = value;
+            m_us->registers.x[5] = value;
             break;
         case reg::uarch_x6:
-            m_us.registers.x[6] = value;
+            m_us->registers.x[6] = value;
             break;
         case reg::uarch_x7:
-            m_us.registers.x[7] = value;
+            m_us->registers.x[7] = value;
             break;
         case reg::uarch_x8:
-            m_us.registers.x[8] = value;
+            m_us->registers.x[8] = value;
             break;
         case reg::uarch_x9:
-            m_us.registers.x[9] = value;
+            m_us->registers.x[9] = value;
             break;
         case reg::uarch_x10:
-            m_us.registers.x[10] = value;
+            m_us->registers.x[10] = value;
             break;
         case reg::uarch_x11:
-            m_us.registers.x[11] = value;
+            m_us->registers.x[11] = value;
             break;
         case reg::uarch_x12:
-            m_us.registers.x[12] = value;
+            m_us->registers.x[12] = value;
             break;
         case reg::uarch_x13:
-            m_us.registers.x[13] = value;
+            m_us->registers.x[13] = value;
             break;
         case reg::uarch_x14:
-            m_us.registers.x[14] = value;
+            m_us->registers.x[14] = value;
             break;
         case reg::uarch_x15:
-            m_us.registers.x[15] = value;
+            m_us->registers.x[15] = value;
             break;
         case reg::uarch_x16:
-            m_us.registers.x[16] = value;
+            m_us->registers.x[16] = value;
             break;
         case reg::uarch_x17:
-            m_us.registers.x[17] = value;
+            m_us->registers.x[17] = value;
             break;
         case reg::uarch_x18:
-            m_us.registers.x[18] = value;
+            m_us->registers.x[18] = value;
             break;
         case reg::uarch_x19:
-            m_us.registers.x[19] = value;
+            m_us->registers.x[19] = value;
             break;
         case reg::uarch_x20:
-            m_us.registers.x[20] = value;
+            m_us->registers.x[20] = value;
             break;
         case reg::uarch_x21:
-            m_us.registers.x[21] = value;
+            m_us->registers.x[21] = value;
             break;
         case reg::uarch_x22:
-            m_us.registers.x[22] = value;
+            m_us->registers.x[22] = value;
             break;
         case reg::uarch_x23:
-            m_us.registers.x[23] = value;
+            m_us->registers.x[23] = value;
             break;
         case reg::uarch_x24:
-            m_us.registers.x[24] = value;
+            m_us->registers.x[24] = value;
             break;
         case reg::uarch_x25:
-            m_us.registers.x[25] = value;
+            m_us->registers.x[25] = value;
             break;
         case reg::uarch_x26:
-            m_us.registers.x[26] = value;
+            m_us->registers.x[26] = value;
             break;
         case reg::uarch_x27:
-            m_us.registers.x[27] = value;
+            m_us->registers.x[27] = value;
             break;
         case reg::uarch_x28:
-            m_us.registers.x[28] = value;
+            m_us->registers.x[28] = value;
             break;
         case reg::uarch_x29:
-            m_us.registers.x[29] = value;
+            m_us->registers.x[29] = value;
             break;
         case reg::uarch_x30:
-            m_us.registers.x[30] = value;
+            m_us->registers.x[30] = value;
             break;
         case reg::uarch_x31:
-            m_us.registers.x[31] = value;
+            m_us->registers.x[31] = value;
             break;
         case reg::uarch_pc:
-            m_us.registers.pc = value;
+            m_us->registers.pc = value;
             break;
         case reg::uarch_cycle:
-            m_us.registers.cycle = value;
+            m_us->registers.cycle = value;
             break;
         case reg::uarch_halt_flag:
-            m_us.registers.halt_flag = value;
+            m_us->registers.halt_flag = value;
             break;
         case reg::htif_tohost_dev:
-            m_s.registers.htif.tohost = HTIF_REPLACE_DEV(m_s.registers.htif.tohost, value);
+            m_s->shadow.registers.htif.tohost = HTIF_REPLACE_DEV(m_s->shadow.registers.htif.tohost, value);
             break;
         case reg::htif_tohost_cmd:
-            m_s.registers.htif.tohost = HTIF_REPLACE_CMD(m_s.registers.htif.tohost, value);
+            m_s->shadow.registers.htif.tohost = HTIF_REPLACE_CMD(m_s->shadow.registers.htif.tohost, value);
             break;
         case reg::htif_tohost_reason:
-            m_s.registers.htif.tohost = HTIF_REPLACE_REASON(m_s.registers.htif.tohost, value);
+            m_s->shadow.registers.htif.tohost = HTIF_REPLACE_REASON(m_s->shadow.registers.htif.tohost, value);
             break;
         case reg::htif_tohost_data:
-            m_s.registers.htif.tohost = HTIF_REPLACE_DATA(m_s.registers.htif.tohost, value);
+            m_s->shadow.registers.htif.tohost = HTIF_REPLACE_DATA(m_s->shadow.registers.htif.tohost, value);
             break;
         case reg::htif_fromhost_dev:
-            m_s.registers.htif.fromhost = HTIF_REPLACE_DEV(m_s.registers.htif.fromhost, value);
+            m_s->shadow.registers.htif.fromhost = HTIF_REPLACE_DEV(m_s->shadow.registers.htif.fromhost, value);
             break;
         case reg::htif_fromhost_cmd:
-            m_s.registers.htif.fromhost = HTIF_REPLACE_CMD(m_s.registers.htif.fromhost, value);
+            m_s->shadow.registers.htif.fromhost = HTIF_REPLACE_CMD(m_s->shadow.registers.htif.fromhost, value);
             break;
         case reg::htif_fromhost_reason:
-            m_s.registers.htif.fromhost = HTIF_REPLACE_REASON(m_s.registers.htif.fromhost, value);
+            m_s->shadow.registers.htif.fromhost = HTIF_REPLACE_REASON(m_s->shadow.registers.htif.fromhost, value);
             break;
         case reg::htif_fromhost_data:
-            m_s.registers.htif.fromhost = HTIF_REPLACE_DATA(m_s.registers.htif.fromhost, value);
+            m_s->shadow.registers.htif.fromhost = HTIF_REPLACE_DATA(m_s->shadow.registers.htif.fromhost, value);
             break;
         default:
             throw std::invalid_argument{"unknown register"};
@@ -1427,19 +1319,18 @@ uint64_t machine::get_reg_address(reg r) {
 }
 
 void machine::mark_write_tlb_dirty_pages() const {
-    auto &hot_set = m_s.tlb.hot[TLB_WRITE];
-    auto &cold_set = m_s.tlb.cold[TLB_WRITE];
+    auto &hot_set = m_s->penumbra.tlb[TLB_WRITE];
+    auto &shadow_set = m_s->shadow.tlb[TLB_WRITE];
     for (uint64_t slot_index = 0; slot_index < TLB_SET_SIZE; ++slot_index) {
         const auto &hot_slot = hot_set[slot_index];
         if (hot_slot.vaddr_page != TLB_INVALID_PAGE) {
-            auto haddr_page = hot_slot.vaddr_page + hot_slot.vh_offset;
-            const auto &cold_slot = cold_set[slot_index];
+            const auto &shadow_slot = shadow_set[slot_index];
             // NOLINTNEXTLINE(cppcoreguidelines-pro-type-const-cast)
-            auto &ar = const_cast<address_range &>(read_pma(cold_slot.pma_index));
+            auto &ar = const_cast<address_range &>(read_pma(shadow_slot.pma_index));
             if (!ar.is_memory()) {
                 throw std::runtime_error{"could not mark dirty page for a TLB entry: TLB is corrupt"};
             }
-            auto paddr_page = get_paddr(haddr_page, cold_slot.pma_index);
+            auto paddr_page = hot_slot.vaddr_page + shadow_slot.vp_offset;
             if (!ar.contains_absolute(paddr_page, AR_PAGE_SIZE)) {
                 throw std::runtime_error{"could not mark dirty page for a TLB entry: TLB is corrupt"};
             }
@@ -1636,14 +1527,14 @@ const char *machine::get_what_name(uint64_t paddr) {
         return "uarch.ram";
     }
     // If in shadow, return refined name
+    if (paddr >= AR_SHADOW_REGISTERS_START && paddr - AR_SHADOW_REGISTERS_START < AR_SHADOW_REGISTERS_LENGTH) {
+        return shadow_registers_get_what_name(shadow_registers_get_what(paddr));
+    }
     if (paddr >= AR_SHADOW_TLB_START && paddr - AR_SHADOW_TLB_START < AR_SHADOW_TLB_LENGTH) {
         [[maybe_unused]] TLB_set_index set_index{};
         [[maybe_unused]] uint64_t slot_index{};
         return shadow_tlb_get_what_name(shadow_tlb_get_what(paddr, set_index, slot_index));
     }
-    if (paddr >= AR_SHADOW_STATE_START && paddr - AR_SHADOW_STATE_START < AR_SHADOW_STATE_LENGTH) {
-        return shadow_state_get_what_name(shadow_state_get_what(paddr));
-    }
     if (paddr >= AR_PMAS_START && paddr - AR_PMAS_START < AR_PMAS_LENGTH) {
         return pmas_get_what_name(pmas_get_what(paddr));
     }
@@ -1802,8 +1693,8 @@ void machine::write_memory(uint64_t paddr, const unsigned char *data, uint64_t l
     if (!ar.is_memory()) {
         throw std::invalid_argument{"address range to write is not entirely in single memory range"};
     }
-    if (pmas_is_protected(ar.get_driver_id())) {
-        throw std::invalid_argument{"attempt to write to protected memory range"};
+    if (ar.is_host_read_only()) {
+        throw std::invalid_argument{"address range to write is read-only in the host"};
     }
     foreach_aligned_chunk(paddr, length, AR_PAGE_SIZE, [&ar, paddr, data](auto chunk_start, auto chunk_length) {
         const auto *src = data + (chunk_start - paddr);
@@ -1815,6 +1706,10 @@ void machine::write_memory(uint64_t paddr, const unsigned char *data, uint64_t l
             ar.mark_dirty_page(offset);
         }
     });
+    if (pmas_range_overlaps(paddr, length, AR_SHADOW_TLB_START, AR_SHADOW_TLB_LENGTH)) {
+        // Must reinitialize hot TLB again to reflect changes in the shadow TLB
+        init_hot_tlb_contents();
+    }
 }
 
 void machine::fill_memory(uint64_t paddr, uint8_t val, uint64_t length) {
@@ -1828,8 +1723,13 @@ void machine::fill_memory(uint64_t paddr, uint8_t val, uint64_t length) {
     if (!ar.is_memory()) {
         throw std::invalid_argument{"address range to fill is not entirely in memory PMA"};
     }
-    if (pmas_is_protected(ar.get_driver_id())) {
-        throw std::invalid_argument{"attempt fill to protected memory range"};
+    if (ar.is_host_read_only()) {
+        throw std::invalid_argument{"address range is read-only in the host"};
+    }
+    if (pmas_range_overlaps(paddr, length, AR_SHADOW_TLB_START, AR_SHADOW_TLB_LENGTH)) {
+        // Filling shadow TLB memory doesn't make sense because it would leave
+        // its state corrupted in most situations.
+        throw std::invalid_argument{"attempted fill to shadow TLB memory range"};
     }
     // The case of filling a range with zeros is special and optimized for uarch reset
     foreach_aligned_chunk(paddr, length, AR_PAGE_SIZE, [&ar, val](auto chunk_start, auto chunk_length) {
@@ -1932,25 +1832,6 @@ void machine::write_word(uint64_t paddr, uint64_t val) {
     if ((paddr & (sizeof(uint64_t) - 1)) != 0) {
         throw std::domain_error{"attempted misaligned write to word"};
     }
-    // If in shadow, forward to write_reg
-    if (paddr >= AR_SHADOW_STATE_START && paddr - AR_SHADOW_STATE_START < AR_SHADOW_STATE_LENGTH) {
-        auto reg = shadow_state_get_what(paddr);
-        if (reg == shadow_state_what::unknown_) {
-            throw std::runtime_error("unhandled write to shadow state");
-        }
-        write_reg(machine_reg_enum(reg), val);
-        return;
-    }
-    // If in uarch shadow, forward to write_reg
-    if (paddr >= AR_SHADOW_UARCH_STATE_START && paddr - AR_SHADOW_UARCH_STATE_START < AR_SHADOW_UARCH_STATE_LENGTH) {
-        auto reg = shadow_uarch_state_get_what(paddr);
-        if (reg == shadow_uarch_state_what::unknown_) {
-            throw std::runtime_error("unhandled write to shadow uarch state");
-        }
-        write_reg(machine_reg_enum(reg), val);
-        return;
-    }
-    // Otherwise, try the slow path
     auto &ar = m_ars.find(paddr, sizeof(uint64_t));
     if (!ar.is_memory() || ar.get_host_memory() == nullptr) {
         std::ostringstream err;
@@ -1958,12 +1839,17 @@ void machine::write_word(uint64_t paddr, uint64_t val) {
             << std::dec << paddr << ")";
         throw std::runtime_error{err.str()};
     }
-    if (!ar.is_writeable()) {
+    if (ar.is_host_read_only()) {
         std::ostringstream err;
         err << "attempted memory write to read-only " << ar.get_description() << " at address 0x" << std::hex << paddr
             << "(" << std::dec << paddr << ")";
         throw std::runtime_error{err.str()};
     }
+    if (pmas_range_overlaps(paddr, sizeof(uint64_t), AR_SHADOW_TLB_START, AR_SHADOW_TLB_LENGTH)) {
+        // Writing a single word to shadow TLB memory is not supported,
+        // it would leave corrupt its state in most situations.
+        throw std::invalid_argument{"attempted memory word write to shadow TLB memory range"};
+    }
     const auto offset = paddr - ar.get_start();
     aliased_aligned_write<uint64_t>(ar.get_host_memory() + offset, val);
     ar.mark_dirty_page(offset);
@@ -2009,7 +1895,6 @@ void machine::verify_send_cmio_response(uint16_t reason, const unsigned char *da
 }
 
 void machine::reset_uarch() {
-    using reg = machine_reg;
     write_reg(reg::uarch_halt_flag, UARCH_HALT_FLAG_INIT);
     write_reg(reg::uarch_pc, UARCH_PC_INIT);
     write_reg(reg::uarch_cycle, UARCH_CYCLE_INIT);
@@ -2076,6 +1961,7 @@ access_log machine::log_step_uarch(const access_log::type &log_type) {
     // Verify access log before returning
     hash_type root_hash_after;
     get_root_hash(root_hash_after);
+    os_silence_putchar(m_r.htif.no_console_putchar);
     verify_step_uarch(root_hash_before, log, root_hash_after);
     return log;
 }
@@ -2108,6 +1994,7 @@ uarch_interpreter_break_reason machine::run_uarch(uint64_t uarch_cycle_end) {
         throw std::runtime_error("microarchitecture cannot be used with unreproducible machines");
     }
     const uarch_state_access a(*this);
+    os_silence_putchar(m_r.htif.no_console_putchar);
     return uarch_interpret(a, uarch_cycle_end);
 }
 
@@ -2134,6 +2021,7 @@ interpreter_break_reason machine::log_step(uint64_t mcycle_count, const std::str
     a.finish();
     hash_type root_hash_after;
     get_root_hash(root_hash_after);
+    os_silence_putchar(m_r.htif.no_console_putchar);
     verify_step(root_hash_before, filename, mcycle_count, root_hash_after);
     return break_reason;
 }
@@ -2141,7 +2029,7 @@ interpreter_break_reason machine::log_step(uint64_t mcycle_count, const std::str
 interpreter_break_reason machine::verify_step(const hash_type &root_hash_before, const std::string &filename,
     uint64_t mcycle_count, const hash_type &root_hash_after) {
     auto data_length = os_get_file_length(filename.c_str(), "step log file");
-    auto data = make_unique_mmap<unsigned char>(filename.c_str(), data_length, false /* not shared */);
+    auto data = make_unique_mmap<unsigned char>(data_length, os_mmap_flags{}, filename, data_length);
     replay_step_state_access::context context;
     replay_step_state_access a(context, data.get(), data_length, root_hash_before);
     uint64_t mcycle_end{};
@@ -2159,6 +2047,7 @@ interpreter_break_reason machine::run(uint64_t mcycle_end) {
         throw std::invalid_argument{"mcycle is past"};
     }
     const state_access a(*this);
+    os_silence_putchar(m_r.htif.no_console_putchar);
     return interpret(a, mcycle_end);
 }
 
@@ -2166,7 +2055,7 @@ interpreter_break_reason machine::run(uint64_t mcycle_end) {
 std::pair<uint64_t, execute_status> machine::poll_external_interrupts(uint64_t mcycle, uint64_t mcycle_max) {
     const auto status = execute_status::success;
     // Only poll external interrupts if we are in unreproducible mode
-    if (unlikely(m_s.registers.iunrep)) {
+    if (unlikely(m_s->shadow.registers.iunrep)) {
         // Convert the relative interval of cycles we can wait to the interval of host time we can wait
         uint64_t timeout_us = (mcycle_max - mcycle) / RTC_CYCLES_PER_US;
         int64_t start_us = 0;
diff --git a/src/machine.h b/src/machine.h
index 471589b1d..0b67a6b0d 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -39,12 +39,12 @@
 #include "machine-merkle-tree.h"
 #include "machine-reg.h"
 #include "machine-runtime-config.h"
-#include "machine-state.h"
 #include "os.h"
 #include "pmas-constants.h"
+#include "processor-state.h"
 #include "shadow-tlb.h"
 #include "uarch-interpret.h"
-#include "uarch-state.h"
+#include "uarch-processor-state.h"
 #include "virtio-address-range.h"
 
 namespace cartesi {
@@ -64,40 +64,37 @@ class machine final {
     machine_config m_c;                   ///< Copy of initialization config
     machine_runtime_config m_r;           ///< Copy of initialization runtime config
     mutable machine_address_ranges m_ars; ///< Address ranges
-    mutable uarch_state m_us;             ///< Uarch state
-    mutable machine_state m_s;            ///< Big machine state
     mutable machine_merkle_tree m_t;      ///< Merkle tree of state
+    processor_state *m_s;                 ///< Big machine processor state
+    uarch_processor_state *m_us;          ///< Microarchitecture processor state
 
     std::unordered_map<std::string, uint64_t> m_counters; ///< Counters used for statistics collection
+    bool m_tty_opened{false};                             ///< Whether tty was opened
 
     /// \brief Returns offset that converts between machine host addresses and target physical addresses
     /// \param pma_index Index of the memory PMA for the desired offset
     host_addr get_hp_offset(uint64_t pma_index) const;
 
-    /// \brief Initializes uarch processor
-    /// \param c Uarch configuration
-    void init_uarch_processor(const uarch_config &c);
-
-    /// \brief Initializes registers
-    /// \param p Registers configuration
+    /// \brief Initializes processor
+    /// \param p Processor configuration
     /// \param r Machine runtime configuration
-    void init_registers(registers_state &p, const machine_runtime_config &r);
+    void init_processor(processor_config &p, const machine_runtime_config &r);
+
+    /// \brief Initializes microarchitecture processor
+    /// \param c Microarchitecture processor configuration
+    void init_uarch_processor(const uarch_processor_config &p);
 
     /// \brief Initializes TTY if needed
-    /// \param h HTIF configuration
-    /// \param r HTIF runtime configuration
-    /// \param iunrep Initial value of iunrep CSR
-    void init_tty(const htif_state &h, const htif_runtime_config &r, uint64_t iunrep) const;
+    void init_tty();
 
     /// \brief Initializes contents of the shadow PMAs memory
     /// \param pmas_config PMAs configuration
     /// \detail This can only be called after all PMAs have been added
     void init_pmas_contents(const pmas_config &config);
 
-    /// \brief Initializes contents of machine TLB, from image in disk or with default values
-    /// \param config TLB config
+    /// \brief Initialize hot TLB contents
     /// \detail This can only be called after all PMAs have been added
-    void init_tlb_contents(const tlb_config &config);
+    void init_hot_tlb_contents();
 
     /// \brief Initializes contents of machine DTB, if image was not available
     /// \param config Machine configuration
@@ -123,7 +120,7 @@ class machine final {
     /// \brief Stores address range into files for serialization
     /// \param ar Address range to store
     /// \param dir Directory where address ranges will be stored
-    void store_address_range(const address_range &ar, const std::string &dir) const;
+    static void store_address_range(const address_range &ar, const std::string &dir);
 
     /// \brief Checks if the machine has VirtIO devices.
     /// \returns True if at least one VirtIO device is present.
@@ -137,10 +134,6 @@ class machine final {
     /// \returns True if HTIF console is present.
     bool has_htif_console() const;
 
-    /// \brief Copies the current state into a configuration for serialization
-    /// \returns The configuration
-    machine_config get_serialization_config() const;
-
 public:
     /// \brief Type of hash
     using hash_type = machine_merkle_tree::hash_type;
@@ -247,23 +240,23 @@ class machine final {
     }
 
     /// \brief Returns machine state for direct access.
-    machine_state &get_state() {
-        return m_s;
+    processor_state &get_state() {
+        return *m_s;
     }
 
     /// \brief Returns machine state for direct read-only access.
-    const machine_state &get_state() const {
-        return m_s;
+    const processor_state &get_state() const {
+        return *m_s;
     }
 
     /// \brief Returns uarch state for direct access.
-    uarch_state &get_uarch_state() {
-        return m_us;
+    uarch_processor_state &get_uarch_state() {
+        return *m_us;
     }
 
     /// \brief Returns uarch state for direct read-only access.
-    const uarch_state &get_uarch_state() const {
-        return m_us;
+    const uarch_processor_state &get_uarch_state() const {
+        return *m_us;
     }
 
     /// \brief Wait for external interrupts requests.
@@ -370,7 +363,7 @@ class machine final {
     /// \param paddr Word address (aligned to 64-bit boundary).
     /// \details The word can be in a writeable area of the address space.
     /// This includes the shadow state and the shadow uarch state.
-    /// (But does NOT include memory-mapped devices, the shadow tlb, shadow PMAs, or unnocupied memory regions.)
+    /// (But does NOT include memory-mapped devices, shadow PMAs, or unnocupied memory regions.)
     void write_word(uint64_t paddr, uint64_t val);
 
     /// \brief Reads a chunk of data, by its target physical address and length.
@@ -501,15 +494,6 @@ class machine final {
     void write_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset,
         uint64_t pma_index);
 
-    /// \brief Check consistency of TLB slot
-    /// \param set_index TLB_CODE, TLB_READ, or TLB_WRITE
-    /// \param slot_index Index of slot to update
-    /// \param vaddr_page Virtual address of page to map
-    /// \param vp_offset Offset from target virtual addresses to target physical addresses within page
-    /// \param pma_index Index of PMA where address falls
-    void check_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset,
-        uint64_t pma_index, const std::string &prefix = "") const;
-
     /// \brief Reads a TLB register
     /// \param set_index TLB_CODE, TLB_READ, or TLB_WRITE
     /// \param slot_index Index of slot to read
@@ -564,6 +548,11 @@ class machine final {
     const auto &get_counters() {
         return m_counters;
     }
+
+    /// \brief Returns whether runtime soft yields are enabled
+    bool is_soft_yield() const {
+        return m_r.soft_yield;
+    }
 };
 
 } // namespace cartesi
diff --git a/src/memory-address-range.cpp b/src/memory-address-range.cpp
index 1a7e38811..e63236727 100644
--- a/src/memory-address-range.cpp
+++ b/src/memory-address-range.cpp
@@ -37,12 +37,22 @@ class base_error : public std::invalid_argument {
 };
 
 memory_address_range::memory_address_range(const std::string &description, uint64_t start, uint64_t length,
-    const pmas_flags &flags, const std::string &image_filename, const mmapd &m) try :
+    const pmas_flags &flags, const backing_store_config &backing_store, const memory_address_range_flags &ar_flags,
+    uint64_t host_length) try :
     address_range(description.c_str(), start, length, flags, [](const char *err) { throw base_error{err}; }),
-    m_ptr{make_unique_mmap<unsigned char>(image_filename.c_str(), length, m.shared)},
-    m_host_memory{std::get<mmapd_ptr>(m_ptr).get()} {
+    m_ptr{make_unique_mmap<unsigned char>(host_length != 0 ? host_length : length,
+        os_mmap_flags{
+            .read_only = ar_flags.read_only && !backing_store.create,
+            .shared = backing_store.shared,
+            .create = backing_store.create,
+            .truncate = backing_store.truncate,
+            .lock = !backing_store.data_filename.empty(),
+        },
+        backing_store.data_filename, length)},
+    m_host_memory{m_ptr.get()},
+    m_ar_flags{ar_flags} {
     if (!is_memory()) {
-        throw std::invalid_argument{"memory range must be flagged memory when initializing "s + description};
+        throw std::invalid_argument{"memory range must be flagged memory"s};
     }
     m_dirty_page_map.resize((get_length() / (8 * AR_PAGE_SIZE)) + 1, 0xff);
 } catch (base_error &b) {
@@ -53,47 +63,4 @@ memory_address_range::memory_address_range(const std::string &description, uint6
     throw std::invalid_argument{"unknown exception when initializing "s + description};
 }
 
-memory_address_range::memory_address_range(const std::string &description, uint64_t start, uint64_t length,
-    const pmas_flags &flags, const std::string &image_filename, const callocd & /*c*/) try :
-    address_range(description.c_str(), start, length, flags, [](const char *err) { throw base_error{err}; }),
-    m_ptr{make_unique_calloc<unsigned char>(length)},
-    m_host_memory{std::get<callocd_ptr>(m_ptr).get()} {
-    if (!is_memory()) {
-        throw std::invalid_argument{"memory range must be flagged memory when initializing "s + description};
-    }
-    m_dirty_page_map.resize((length / (8 * AR_PAGE_SIZE)) + 1, 0xff);
-    // Try to load image file, if any
-    if (!image_filename.empty()) {
-        auto fp = make_unique_fopen(image_filename.c_str(), "rb", std::nothrow_t{});
-        if (!fp) {
-            throw std::system_error{errno, std::generic_category(), "error opening image file '"s + image_filename};
-        }
-        // Get file size
-        if (fseek(fp.get(), 0, SEEK_END) != 0) {
-            throw std::system_error{errno, std::generic_category(),
-                "error obtaining length of image file '"s + image_filename};
-        }
-        const auto file_length = static_cast<uint64_t>(ftello(fp.get()));
-        if (fseek(fp.get(), 0, SEEK_SET) != 0) {
-            throw std::system_error{errno, std::generic_category(),
-                "error obtaining length of image file '"s + image_filename};
-        }
-        // Check against PMA range size
-        if (file_length > length) {
-            throw std::runtime_error{"image file '"s + image_filename + "' is too large for range"s};
-        }
-        // Read to host memory
-        const auto read_length = static_cast<uint64_t>(fread(m_host_memory, 1, file_length, fp.get()));
-        if (read_length != file_length) {
-            throw std::runtime_error{"error reading from image file '"s + image_filename};
-        }
-    }
-} catch (base_error &b) {
-    throw; // already contains the description
-} catch (std::exception &e) {
-    throw std::invalid_argument{e.what() + " when initializing "s + description};
-} catch (...) {
-    throw std::invalid_argument{"unknown exception when initializing "s + description};
-}
-
 } // namespace cartesi
diff --git a/src/memory-address-range.h b/src/memory-address-range.h
index e7b828147..bf2f12868 100644
--- a/src/memory-address-range.h
+++ b/src/memory-address-range.h
@@ -21,6 +21,8 @@
 #include <variant>
 
 #include "address-range.h"
+#include "machine-config.h"
+#include "os-mmap.h"
 #include "unique-c-ptr.h"
 
 namespace cartesi {
@@ -31,50 +33,32 @@ class machine;
 /// \file
 /// \brief An address range occupied by memory
 
-class memory_address_range : public address_range {
-
-    using callocd_ptr = unique_calloc_ptr<unsigned char>;
-    using mmapd_ptr = unique_mmap_ptr<unsigned char>;
-
-    std::variant<std::monostate, ///< Before initialization
-        callocd_ptr,             ///< Automatic pointer for calloced memory
-        mmapd_ptr                ///< Automatic pointer for mmapped memory
-        >
-        m_ptr;
+struct memory_address_range_flags final {
+    bool read_only{false};        ///< Whether the memory is read-only on the host
+    bool page_uncleanable{false}; //< Whether the memory page dirty state can be cleaned
+};
 
+class memory_address_range : public address_range {
+    unique_mmap_ptr<unsigned char> m_ptr;  ///< Pointer to mapped memory
     unsigned char *m_host_memory;          ///< Start of associated memory region in host.
+    memory_address_range_flags m_ar_flags; ///< Memory address range specific flags.
     std::vector<uint8_t> m_dirty_page_map; ///< Map of dirty pages.
 
 public:
     using ptr_type = std::unique_ptr<memory_address_range>;
 
-    /// \brief Mmap'd range data (shared or not).
-    struct mmapd {
-        bool shared;
-    };
-
     /// \brief Constructor for mmap'd ranges.
     /// \param description Description of address range for use in error messages
     /// \param start Start of address range
     /// \param length Length of address range
     /// \param flags Range flags
     /// \param image_filename Path to backing file.
-    /// \param m Mmap'd range data (shared or not).
-    memory_address_range(const std::string &description, uint64_t start, uint64_t length, const pmas_flags &flags,
-        const std::string &image_filename, const mmapd &m);
-
-    /// \brief Calloc'd range data (just a tag).
-    struct callocd {};
-
-    /// \brief Constructor for calloc'd ranges.
-    /// \param description Description of address range for use in error messages
-    /// \param start Start of address range
-    /// \param length Length of address range
-    /// \param flags Range flags
-    /// \param image_filename Path to backing file.
-    /// \param c Calloc'd range data (just a tag).
+    /// \param host_length Length of host memory to be mapped.
+    /// This value can exceed the specified length, effectively creating an additional region
+    /// of memory that is not associated with the backing files.
     memory_address_range(const std::string &description, uint64_t start, uint64_t length, const pmas_flags &flags,
-        const std::string &image_filename, const callocd & /*c*/);
+        const backing_store_config &backing_store = {}, const memory_address_range_flags &ar_flags = {},
+        uint64_t host_length = 0);
 
     memory_address_range(const memory_address_range &) = delete;
     memory_address_range &operator=(const memory_address_range &) = delete;
@@ -100,6 +84,10 @@ class memory_address_range : public address_range {
     }
 
     void do_mark_clean_page(uint64_t offset) noexcept override {
+        if (m_ar_flags.page_uncleanable) {
+            // Dirty pages on this address range are permanently dirty and cannot be cleaned.
+            return;
+        }
         auto page_index = offset >> AR_constants::AR_PAGE_SIZE_LOG2;
         auto map_index = page_index >> 3;
         assert(map_index < m_dirty_page_map.size());
@@ -107,6 +95,10 @@ class memory_address_range : public address_range {
     }
 
     void do_mark_pages_clean() noexcept override {
+        if (m_ar_flags.page_uncleanable) {
+            // Dirty pages on this address range are permanently dirty and cannot be cleaned.
+            return;
+        }
         std::fill(m_dirty_page_map.begin(), m_dirty_page_map.end(), 0);
     }
 
@@ -117,6 +109,14 @@ class memory_address_range : public address_range {
         return (m_dirty_page_map[map_index] & (1 << (page_index & 7))) != 0;
     }
 
+    bool do_is_host_read_only() const noexcept override {
+        return m_ar_flags.read_only;
+    }
+
+    bool do_is_page_uncleanable() const noexcept override {
+        return m_ar_flags.page_uncleanable;
+    }
+
     bool do_peek(const machine & /*m*/, uint64_t offset, uint64_t length, const unsigned char **data,
         unsigned char * /*scratch*/) const noexcept override {
         if (contains_relative(offset, length)) {
@@ -128,16 +128,6 @@ class memory_address_range : public address_range {
     }
 };
 
-static inline auto make_callocd_memory_address_range(const std::string &description, uint64_t start, uint64_t length,
-    pmas_flags flags, const std::string &image_filename = {}) {
-    return memory_address_range{description, start, length, flags, image_filename, memory_address_range::callocd{}};
-}
-
-static inline auto make_mmapd_memory_address_range(const std::string &description, uint64_t start, uint64_t length,
-    pmas_flags flags, const std::string &image_filename, bool shared) {
-    return memory_address_range{description, start, length, flags, image_filename, memory_address_range::mmapd{shared}};
-}
-
 } // namespace cartesi
 
 #endif
diff --git a/src/mock-address-range.h b/src/mock-address-range.h
index ee73d9c0c..dd7b18714 100644
--- a/src/mock-address-range.h
+++ b/src/mock-address-range.h
@@ -26,13 +26,11 @@
 #include "htif-address-range.h"
 #include "plic-address-range.h"
 #include "pmas.h"
-#include "shadow-state-address-range.h"
-#include "shadow-tlb-address-range.h"
 
 namespace cartesi {
 
-using mock_address_range = std::variant<std::monostate, address_range, clint_address_range, htif_address_range,
-    plic_address_range, shadow_state_address_range, shadow_tlb_address_range>;
+using mock_address_range =
+    std::variant<std::monostate, address_range, clint_address_range, htif_address_range, plic_address_range>;
 
 using mock_address_ranges = std::array<mock_address_range, PMA_MAX>;
 
@@ -61,10 +59,6 @@ static inline mock_address_range make_mock_address_range(uint64_t istart, uint64
         return check_mock_address_range(make_empty_address_range("empty"), start, ilength, flags, abrt);
     }
     switch (flags.DID) {
-        case PMA_ISTART_DID::shadow_state:
-            return check_mock_address_range(make_shadow_state_address_range(abrt), start, ilength, flags, abrt);
-        case PMA_ISTART_DID::shadow_TLB:
-            return check_mock_address_range(make_shadow_tlb_address_range(abrt), start, ilength, flags, abrt);
         case PMA_ISTART_DID::CLINT:
             return check_mock_address_range(make_clint_address_range(abrt), start, ilength, flags, abrt);
         case PMA_ISTART_DID::PLIC:
@@ -91,10 +85,6 @@ address_range &get_mock_address_range(mock_address_range &mock, ABRT abrt) {
             return std::get<3>(mock);
         case 4:
             return std::get<4>(mock);
-        case 5:
-            return std::get<5>(mock);
-        case 6:
-            return std::get<6>(mock);
         default: {
             static auto unhandled = make_empty_address_range("unhandled mock address range");
             abrt("unhandled mock address range");
@@ -102,7 +92,7 @@ address_range &get_mock_address_range(mock_address_range &mock, ABRT abrt) {
             return unhandled;
         }
     }
-    static_assert(std::variant_size_v<mock_address_range> == 7);
+    static_assert(std::variant_size_v<mock_address_range> == 5);
 }
 
 } // namespace cartesi
diff --git a/src/os-features.h b/src/os-features.h
index f853fd256..0060fca7f 100644
--- a/src/os-features.h
+++ b/src/os-features.h
@@ -72,4 +72,8 @@
 #define HAVE_FORK
 #endif
 
+#if !defined(NO_FLOCK) && (defined(__linux__) || defined(__unix__) || defined(__APPLE__)) && !defined(__wasi__)
+#define HAVE_FLOCK
+#endif
+
 #endif
diff --git a/src/os-mmap.cpp b/src/os-mmap.cpp
new file mode 100644
index 000000000..a49ec013e
--- /dev/null
+++ b/src/os-mmap.cpp
@@ -0,0 +1,650 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifdef _WIN32
+#ifndef WIN32_LEAN_AND_MEAN
+#define WIN32_LEAN_AND_MEAN
+#endif
+#ifndef _CRT_SECURE_NO_WARNINGS
+#define _CRT_SECURE_NO_WARNINGS
+#endif
+#include <windows.h>
+#endif // _WIN32
+
+#include <cstring>
+#include <stdexcept>
+#include <system_error>
+
+#include "os-features.h"
+#include "os-mmap.h"
+#include "scope-exit.h"
+
+//------------------------------------------------------------------------------
+
+#if defined(HAVE_MMAP)
+#include <fcntl.h>    // open
+#include <sys/mman.h> // mmap/munmap
+#include <sys/stat.h> // fstat
+#include <unistd.h>   // write/read/close
+#else
+#include <cstdio>  // fopen/fclose/fread/fwrite/fflush
+#include <cstdlib> // calloc/free
+#endif
+
+#if defined(HAVE_FLOCK)
+#include <sys/file.h> // flock
+#endif
+
+namespace cartesi {
+
+using namespace std::string_literals;
+
+constexpr uint64_t DEFAULT_MMAP_PAGE_SIZE = 4096;
+
+uint64_t os_get_mmap_page_size() {
+#ifdef HAVE_MMAP
+    const auto page_size = sysconf(_SC_PAGESIZE);
+    if (page_size < 0) {
+        throw std::system_error{errno, std::generic_category(), "unable to retrieve system page size"s};
+    }
+    return static_cast<uint64_t>(page_size);
+
+#elif defined(_WIN32)
+    SYSTEM_INFO si;
+    GetSystemInfo(&si);
+    return static_cast<uint64_t>(si.dwPageSize);
+
+#else
+    return DEFAULT_MMAP_PAGE_SIZE;
+
+#endif // HAVE_MMAP
+}
+
+os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string &backing_filename,
+    uint64_t backing_length) {
+    // Check some preconditions
+    if (backing_filename.empty() && (flags.lock || flags.shared || flags.create)) {
+        throw std::invalid_argument{"backing filename must be specified"s};
+    }
+    if (flags.create && !flags.shared) {
+        throw std::invalid_argument{"created backing files must be shared"s};
+    }
+    if (flags.read_only && flags.shared && (flags.create || flags.truncate)) {
+        throw std::invalid_argument{"cannot create or truncate backing files that are shared read-only"s};
+    }
+    if (length == 0) {
+        throw std::invalid_argument{"memory map length cannot be zero"s};
+    }
+    if (length < backing_length) {
+        throw std::invalid_argument{"length must be greater or equal than max backing length"s};
+    }
+    const bool shared_write = flags.shared && !flags.read_only;
+
+    // Ensure mapped pages are 4096-byte aligned for compatibility with
+    // routines using efficient SIMD operations on memory pages.
+    const uint64_t page_size = os_get_mmap_page_size();
+    if (page_size < DEFAULT_MMAP_PAGE_SIZE) {
+        throw std::runtime_error{"system memory page size is less than "s + std::to_string(DEFAULT_MMAP_PAGE_SIZE)};
+    }
+
+#ifdef HAVE_MMAP
+    int backing_fd = -1;
+    uint64_t backing_file_length = 0;
+
+    // Auto close backing file on failure
+    auto backing_closer = scope_fail([&] {
+        if (backing_fd >= 0) {
+            // Close backing file
+            close(backing_fd);
+            // Remove backing file in case it was created
+            if (flags.create) {
+                unlink(backing_filename.c_str());
+            }
+        }
+    });
+
+    // Handle backing file if specified
+    if (!backing_filename.empty()) {
+        // Determine backing file open flags
+        int oflags = (shared_write ? O_RDWR : O_RDONLY);
+        oflags |= O_CLOEXEC; // to remove file locks on fork + exec
+        mode_t omode = 0;
+        if (flags.create) {
+            oflags |= O_CREAT | O_EXCL;
+            omode = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH;
+        }
+
+        // Open backing file
+        backing_fd = open(backing_filename.c_str(), oflags, omode);
+        if (backing_fd < 0) {
+            throw std::system_error{errno, std::generic_category(),
+                "unable to open backing file '"s + backing_filename + "'"s};
+        }
+
+#ifdef HAVE_FLOCK
+        // Lock backing file immediately after opening it
+        if (flags.lock) {
+            const int flockop = (shared_write ? LOCK_EX : LOCK_SH) | LOCK_NB;
+            if (flock(backing_fd, flockop) < 0) {
+                throw std::system_error{errno, std::generic_category(),
+                    "unable to lock backing file '"s + backing_filename + "'"s};
+            }
+        }
+#endif // HAVE_FLOCK
+
+        // Get backing file size
+        struct stat statbuf{};
+        if (fstat(backing_fd, &statbuf) < 0) {
+            throw std::system_error{errno, std::generic_category(),
+                "unable to obtain length of backing file '"s + backing_filename + "'"s};
+        }
+        backing_file_length = static_cast<uint64_t>(statbuf.st_size);
+
+        // When backing file length mismatch the desired backing length we may need to truncate
+        if (backing_file_length != backing_length) {
+            if (!(flags.truncate || flags.create)) { // Can we truncate?
+                throw std::runtime_error{"backing file '"s + backing_filename + "' length ("s +
+                    std::to_string(backing_file_length) + ") does not match desired backing length ("s +
+                    std::to_string(backing_length) + ")"s};
+            }
+            if (flags.shared) { // Truncate backing file to match the desired length
+                if (ftruncate(backing_fd, static_cast<off_t>(backing_length)) < 0) {
+                    throw std::runtime_error{"unable to truncate backing file '"s + backing_filename + "' length ("s +
+                        std::to_string(backing_file_length) + ") to desired backing length ("s +
+                        std::to_string(backing_length) + ")"s};
+                }
+                backing_file_length = backing_length;
+            } else {
+                // Backing file length may be less than desired backing length,
+                // but this is fine, as we are not sharing the file.
+                // The gap between the file length and the memory length will be allocated as anonymous memory.
+            }
+        }
+    }
+
+    // Determine map memory flags
+    int mflags = flags.shared ? MAP_SHARED : MAP_PRIVATE;
+    if (backing_fd < 0) { // The mapping is not backed by any file
+        mflags |= MAP_ANONYMOUS;
+    }
+
+    // Determine map protection flags
+    int mprot = PROT_READ;
+    if (!flags.read_only) {
+        mprot |= PROT_WRITE;
+    }
+
+    // Unmap memory in case memory mapping fails
+    void *host_memory = nullptr;
+    auto memory_closer = scope_fail([&] {
+        if (host_memory != nullptr) {
+            munmap(host_memory, length);
+        }
+    });
+
+    // Map memory
+    if (backing_fd >= 0 && length != backing_file_length) {
+        // Here we need to split the mapping into two parts:
+        // 1. Map the entire memory range with anonymous memory first
+        // 2. Replace memory map related to backing file portion
+        // This will leave a contiguous memory region where the first portion is backed by a file,
+        // and the second portion is backed by anonymous memory.
+
+        // Map entire memory range, this is required to use the subsequent MAP_FIXED safely.
+        host_memory = mmap(nullptr, length, mprot, MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
+        if (host_memory == MAP_FAILED) {
+            throw std::system_error{errno, std::generic_category(), "unable to map memory"s};
+        }
+
+        // Replace memory map related to backing file portion
+        void *backing_host_memory = mmap(host_memory, backing_file_length, mprot, mflags | MAP_FIXED, backing_fd, 0);
+        if (backing_host_memory != host_memory) {
+            throw std::system_error{errno, std::generic_category(),
+                "unable to map backing file '"s + backing_filename + "' to memory"s};
+        }
+
+        // POSIX ensures that any partial page at the end of a file is zero-filled,
+        // and modifications beyond the file's end are never written to disk.
+        // However on Linux, writing beyond such a partial page updates the page cache but not the file,
+        // and subsequent mappings may see the cached modifications even after the file is closed and unmapped,
+        // so we have to zero fill the last partial page just to be safe.
+        // See more about this on BUGS section in mmap() Linux man pages.
+        const uint64_t partial_page_size = backing_file_length % page_size;
+        const uint64_t partial_page_remaining = std::min(page_size - partial_page_size, length - backing_file_length);
+        if (partial_page_remaining > 0) {
+            if (flags.read_only) {
+                // We can't write on read-only mappings.
+                // This kind of mapping is unlikely to happen, so there is no need to support it.
+                throw std::system_error{errno, std::generic_category(),
+                    "possible non zero partial page when mapping backing file '"s + backing_filename + "' to memory"s};
+            }
+            std::memset(std::bit_cast<uint8_t *>(backing_host_memory) + backing_file_length, 0, partial_page_remaining);
+        }
+    } else { // Can perform a single mmap()
+        host_memory = mmap(nullptr, length, mprot, mflags, backing_fd, 0);
+        if (host_memory == MAP_FAILED) {
+            if (backing_fd < 0) {
+                throw std::system_error{errno, std::generic_category(), "unable to map memory"s};
+            }
+            throw std::system_error{errno, std::generic_category(),
+                "unable to map backing file '"s + backing_filename + "' to memory"s};
+        }
+    }
+
+    return os_mmapd{.host_memory = host_memory,
+        .length = length,
+        .backing_sync_length = shared_write ? backing_length : 0,
+        .backing_fd = backing_fd};
+
+#elif defined(_WIN32)
+    HANDLE backing_fh = INVALID_HANDLE_VALUE;
+    HANDLE backing_mapping = nullptr;
+    HANDLE memory_mapping = nullptr;
+    void *backing_host_memory = nullptr;
+    void *host_memory = nullptr;
+    uint64_t backing_file_length = 0;
+
+    // Auto cleanup on failure
+    auto failure_cleaner = scope_fail([&] {
+        if (backing_host_memory != nullptr) {
+            std::ignore = UnmapViewOfFile(backing_host_memory);
+        }
+        if (host_memory != nullptr) {
+            std::ignore = UnmapViewOfFile(host_memory);
+        }
+        if (backing_mapping != nullptr) {
+            std::ignore = CloseHandle(backing_mapping);
+        }
+        if (memory_mapping != nullptr) {
+            std::ignore = CloseHandle(memory_mapping);
+        }
+        if (backing_fh != INVALID_HANDLE_VALUE) {
+            if (flags.lock) {
+                OVERLAPPED overlapped{};
+                std::ignore = UnlockFileEx(backing_fh, 0, MAXDWORD, MAXDWORD, &overlapped);
+            }
+            // Close backing file
+            std::ignore = CloseHandle(backing_fh);
+            // Remove backing file in case it was created
+            if (flags.create) {
+                std::ignore = DeleteFileA(backing_filename.c_str());
+            }
+        }
+    });
+
+    // Handle backing file if specified
+    if (!backing_filename.empty()) {
+        // Determine backing file open flags
+        const DWORD open_access = GENERIC_READ | (!flags.read_only ? GENERIC_WRITE : 0);
+        const DWORD share_mode = FILE_SHARE_READ | (!flags.read_only ? FILE_SHARE_WRITE : 0);
+        const DWORD creation = flags.create ? CREATE_NEW : OPEN_EXISTING;
+
+        // Open backing file
+        backing_fh = CreateFileA(backing_filename.c_str(), open_access, share_mode, nullptr, creation,
+            FILE_ATTRIBUTE_NORMAL, nullptr);
+        if (backing_fh == INVALID_HANDLE_VALUE) {
+            throw std::system_error{static_cast<int>(GetLastError()), std::system_category(),
+                "unable to open backing file '"s + backing_filename + "'"s};
+        }
+
+        // Lock backing file immediately after opening it
+        if (flags.lock) {
+            DWORD lock_flags = LOCKFILE_FAIL_IMMEDIATELY; // Non-blocking lock
+            if (shared_write) {
+                lock_flags |= LOCKFILE_EXCLUSIVE_LOCK; // Exclusive lock for writing
+            }
+            OVERLAPPED overlapped{};
+            if (!LockFileEx(backing_fh, lock_flags, 0, MAXDWORD, MAXDWORD, &overlapped)) {
+                throw std::system_error{static_cast<int>(GetLastError()), std::system_category(),
+                    "unable to lock backing file '" + backing_filename + "'"};
+            }
+        }
+
+        // Get backing file size
+        LARGE_INTEGER size{};
+        if (!GetFileSizeEx(backing_fh, &size)) {
+            throw std::system_error{static_cast<int>(GetLastError()), std::system_category(),
+                "unable to obtain length of backing file '"s + backing_filename + "'"s};
+        }
+        backing_file_length = static_cast<uint64_t>(size.QuadPart);
+
+        // When backing file length mismatch the desired backing length we may need to truncate
+        if (backing_file_length != backing_length) {
+            if (!(flags.truncate || flags.create)) { // Can we truncate?
+                throw std::runtime_error{"backing file '"s + backing_filename + "' length ("s +
+                    std::to_string(backing_file_length) + ") does not match desired backing length ("s +
+                    std::to_string(backing_length) + ")"s};
+            }
+            if (flags.shared) { // Truncate backing file to match the desired length
+                // Set file pointer to the new size position
+                LARGE_INTEGER new_size{.QuadPart = static_cast<LONGLONG>(backing_length)};
+                if (!SetFilePointerEx(backing_fh, new_size, nullptr, FILE_BEGIN)) {
+                    throw std::system_error{static_cast<int>(GetLastError()), std::system_category(),
+                        "unable to seek backing file '"s + backing_filename + "'"s};
+                }
+
+                // Set the end of file at the current position
+                if (!SetEndOfFile(backing_fh)) {
+                    throw std::system_error{static_cast<int>(GetLastError()), std::system_category(),
+                        "unable to truncate backing file '"s + backing_filename + "'"s};
+                }
+
+                // Initialize truncated bytes to zeros
+                if (backing_length > backing_file_length) {
+                    // Set file pointer to truncate position
+                    LARGE_INTEGER truncate_pos{.QuadPart = static_cast<LONGLONG>(backing_file_length)};
+                    if (!SetFilePointerEx(backing_fh, truncate_pos, nullptr, FILE_BEGIN)) {
+                        throw std::system_error{static_cast<int>(GetLastError()), std::system_category(),
+                            "unable to seek backing file '"s + backing_filename + "'"s};
+                    }
+
+                    // Write zeros in chunks
+                    static uint8_t zero_buffer[65536]{};
+                    uint64_t remaining = backing_length - backing_file_length;
+                    while (remaining > 0) {
+                        const auto write_size = static_cast<DWORD>(std::min<uint64_t>(remaining, sizeof(zero_buffer)));
+                        DWORD bytes_written = 0;
+                        if (!WriteFile(backing_fh, zero_buffer, write_size, &bytes_written, nullptr) ||
+                            bytes_written != write_size) {
+                            throw std::system_error{static_cast<int>(GetLastError()), std::system_category(),
+                                "unable to write backing file '"s + backing_filename + "'"s};
+                        }
+                        remaining -= bytes_written;
+                    }
+                }
+
+                // Flush file changes
+                if (!FlushFileBuffers(backing_fh)) {
+                    throw std::system_error{static_cast<int>(GetLastError()), std::system_category(),
+                        "unable to flush backing file '"s + backing_filename + "'"s};
+                }
+
+                backing_file_length = backing_length;
+            } else {
+                // Backing file length may be less than desired backing length,
+                // but this is fine, as we are not sharing the file.
+                // The gap between the file length and the memory length will be allocated as anonymous memory.
+            }
+        }
+    }
+
+    HANDLE memory_handle = INVALID_HANDLE_VALUE;
+    if (backing_file_length > 0 && backing_file_length == length) {
+        // When backing file length matches memory length, we can map it directly
+        memory_handle = backing_fh;
+    } else if (backing_file_length > 0) {
+        // Unfortunately Windows does not easily support creating a contiguous memory region with
+        // mixed file-backed and anonymous memory mappings. Instead, we create an auxiliary
+        // mapping for the backing file and handle data transfers explicitly:
+        // 1) Copy data from backing file to host memory during mapping
+        // 2) Copy modified data back to the backing file during unmapping in case of shared write access
+
+        // Determine backing file mapping flags
+        const DWORD backing_access = shared_write ? FILE_MAP_WRITE : FILE_MAP_READ;
+        const DWORD backing_protect = shared_write ? PAGE_READWRITE : PAGE_READONLY;
+
+        // Create backing file mapping
+        backing_mapping =
+            CreateFileMappingA(backing_fh, nullptr, backing_protect, static_cast<DWORD>(backing_file_length >> 32),
+                static_cast<DWORD>(backing_file_length & 0xffffffff), nullptr);
+        if (backing_mapping == nullptr) {
+            throw std::system_error{static_cast<int>(GetLastError()), std::system_category(),
+                "unable to create memory mapping of backing file '"s + backing_filename + "'"s};
+        }
+
+        // Map backing file
+        backing_host_memory = MapViewOfFile(backing_mapping, backing_access, 0, 0, backing_file_length);
+        if (backing_host_memory == nullptr) {
+            throw std::system_error{static_cast<int>(GetLastError()), std::system_category(),
+                "unable to map memory of backing file '"s + backing_filename + "'"s};
+        }
+    }
+
+    // Determine memory mapping flags
+    const DWORD protect = flags.read_only ? PAGE_READONLY : PAGE_READWRITE;
+    DWORD access = FILE_MAP_READ;
+    if (!flags.read_only) {
+        access |= FILE_MAP_WRITE;
+        if (!flags.shared) {
+            access |= FILE_MAP_COPY;
+        }
+    }
+
+    // Create memory mapping
+    memory_mapping = CreateFileMappingA(memory_handle, nullptr, protect, static_cast<DWORD>(length >> 32),
+        static_cast<DWORD>(length & 0xffffffff), nullptr);
+    if (memory_mapping == nullptr) {
+        throw std::system_error{static_cast<int>(GetLastError()), std::system_category(),
+            "unable to create memory mapping"s};
+    }
+
+    // Map memory
+    host_memory = MapViewOfFile(memory_mapping, access, 0, 0, length);
+    if (host_memory == nullptr) {
+        throw std::system_error{static_cast<int>(GetLastError()), std::system_category(), "unable to map memory"s};
+    }
+
+    // Copy contents from the backing file if needed
+    if (backing_host_memory != nullptr && backing_file_length > 0) {
+        std::memcpy(host_memory, backing_host_memory, backing_file_length);
+    }
+
+    return os_mmapd{.host_memory = host_memory,
+        .length = length,
+        .backing_sync_length = shared_write ? backing_length : 0,
+        .memory_mapping = static_cast<void *>(memory_mapping),
+        .backing_host_memory = backing_host_memory,
+        .backing_mapping = backing_mapping,
+        .backing_fh = static_cast<void *>(backing_fh),
+        .backing_lock = flags.lock};
+
+#else  // Fallback implementation using standard C APIs
+    // Over-allocate to ensure we can align the pointer and store the original pointer.
+    // Use calloc() instead of aligned_alloc() to initialize memory to zeros.
+    std::size_t space = length + DEFAULT_MMAP_PAGE_SIZE - 1;
+    void *unaligned_host_memory = std::calloc(1, space); // NOLINT(cppcoreguidelines-no-malloc,hicpp-no-malloc)
+    if (unaligned_host_memory == nullptr) {
+        throw std::bad_alloc{};
+    }
+
+    // Automatically deallocate memory on failure
+    auto memory_closer = scope_fail([&] {
+        std::free(unaligned_host_memory); // NOLINT(cppcoreguidelines-no-malloc,hicpp-no-malloc)
+    });
+
+    // Align allocated memory
+    void *host_memory = unaligned_host_memory;
+    if (std::align(DEFAULT_MMAP_PAGE_SIZE, length, host_memory, space) == nullptr) {
+        throw std::runtime_error{"unable to align allocated memory"};
+    }
+
+    FILE *backing_fp = nullptr;
+
+    // Automatically close backing file on failure
+    auto backing_closer = scope_fail([&] {
+        if (backing_fp != nullptr) {
+            // Close backing file
+            std::ignore = std::fclose(backing_fp);
+            // Remove backing file in case it was created
+            if (flags.create) {
+                std::ignore = std::remove(backing_filename.c_str());
+            }
+        }
+    });
+
+    // Handle backing file if specified
+    if (!backing_filename.empty()) {
+        // Determine backing file open flags
+        const char *mode{};
+        if (flags.create) {
+            // Check if file already exists first
+            auto *fp = std::fopen(backing_filename.c_str(), "rb");
+            if (fp != nullptr) {
+                std::ignore = std::fclose(fp);
+                throw std::system_error{errno, std::generic_category(),
+                    "unable to create backing file '"s + backing_filename + "': file already exists"s};
+            }
+            mode = "w+b";
+        } else if (shared_write) {
+            mode = "r+b";
+        } else {
+            mode = "rb";
+        }
+
+        // Open backing file
+        backing_fp = std::fopen(backing_filename.c_str(), mode);
+        if (backing_fp == nullptr) {
+            throw std::system_error{errno, std::generic_category(),
+                "unable to open backing file '"s + backing_filename + "'"s};
+        }
+
+        // Get backing file size
+        if (std::fseek(backing_fp, 0, SEEK_END) < 0) {
+            throw std::system_error{errno, std::generic_category(),
+                "unable to obtain length of backing file '"s + backing_filename + "'"s};
+        }
+        const auto file_size = std::ftell(backing_fp);
+        if (file_size < 0) {
+            throw std::system_error{errno, std::generic_category(),
+                "unable to obtain length of backing file '"s + backing_filename + "'"s};
+        }
+        const auto backing_file_length = static_cast<uint64_t>(file_size);
+
+        // Copy backing file contents
+        if (std::fseek(backing_fp, 0, SEEK_SET) < 0) {
+            throw std::system_error{errno, std::generic_category(),
+                "unable to seek to beginning of backing file '"s + backing_filename + "'"s};
+        }
+        const auto copy_length = std::min(backing_file_length, backing_length);
+        if (static_cast<uint64_t>(std::fread(host_memory, 1, copy_length, backing_fp)) != copy_length) {
+            throw std::system_error{errno, std::generic_category(),
+                "unable to read from backing file '"s + backing_filename + "'"s};
+        }
+
+        // When backing file length mismatch the desired backing length we may need to truncate
+        if (backing_file_length != backing_length) {
+            if (!(flags.truncate || flags.create)) { // Can we truncate?
+                throw std::runtime_error{"backing file '"s + backing_filename + "' length ("s +
+                    std::to_string(backing_file_length) + ") does not match desired backing length ("s +
+                    std::to_string(backing_length) + ")"s};
+            }
+            if (flags.shared) { // Truncate backing file to match the desired length
+                // In order to truncate the file using standard C API,
+                // we need recreate from scratch and copy over the existing content.
+                if (std::fclose(backing_fp) != 0) {
+                    throw std::system_error{errno, std::generic_category(),
+                        "unable to truncate backing file '"s + backing_filename + "': fclose() failed"s};
+                }
+                backing_fp = std::fopen(backing_filename.c_str(), "w+b");
+                if (backing_fp == nullptr) {
+                    throw std::system_error{errno, std::generic_category(),
+                        "unable to truncate backing file '"s + backing_filename + "': fopen() failed"s};
+                }
+                if (static_cast<uint64_t>(std::fwrite(host_memory, 1, backing_length, backing_fp)) != backing_length) {
+                    throw std::system_error{errno, std::generic_category(),
+                        "unable to truncate backing file '"s + backing_filename + "': fwrite() failed"s};
+                }
+                if (std::fflush(backing_fp) != 0) {
+                    throw std::system_error{errno, std::generic_category(),
+                        "unable to truncate backing file '"s + backing_filename + "': fflush() failed"s};
+                }
+            } else {
+                // Backing file length may be less than desired backing length,
+                // but this is fine, as we are not sharing the file.
+                // The gap between the file length and the memory length will be allocated as anonymous memory.
+            }
+        }
+
+        // Rewind the backing file to the beginning
+        if (std::fseek(backing_fp, 0, SEEK_SET) < 0) {
+            throw std::system_error{errno, std::generic_category(),
+                "unable to rewind backing file '"s + backing_filename + "'"s};
+        }
+    }
+
+    return os_mmapd{.host_memory = host_memory,
+        .length = length,
+        .backing_sync_length = shared_write ? backing_length : 0,
+        .backing_fp = backing_fp,
+        .unaligned_host_memory = unaligned_host_memory};
+#endif // HAVE_MMAP
+}
+
+void os_munmap(const os_mmapd &mmapd) noexcept {
+#ifdef HAVE_MMAP
+    if (mmapd.host_memory != nullptr && mmapd.length > 0) {
+        if (mmapd.backing_sync_length > 0) {
+            // Request the kernel to flush the mapped file to disk asynchronously.
+            // This may reduce the risk of file corruption in the event of unexpected host power loss.
+            std::ignore = msync(mmapd.host_memory, mmapd.backing_sync_length, MS_ASYNC);
+        }
+        std::ignore = munmap(mmapd.host_memory, mmapd.length);
+    }
+    if (mmapd.backing_fd != -1) {
+        // Closing a file will also release file locks
+        std::ignore = close(mmapd.backing_fd);
+    }
+
+#elif defined(_WIN32) // Windows implementation
+    // Flush changes to disk if necessary
+    if (mmapd.backing_sync_length > 0 && mmapd.host_memory != nullptr) {
+        if (mmapd.backing_host_memory != nullptr) { // Copy contents to the backing file
+            std::memcpy(mmapd.backing_host_memory, mmapd.host_memory, mmapd.backing_sync_length);
+            std::ignore = FlushViewOfFile(mmapd.backing_host_memory, mmapd.backing_sync_length);
+        } else {
+            std::ignore = FlushViewOfFile(mmapd.host_memory, mmapd.backing_sync_length);
+        }
+        if (mmapd.backing_fh != nullptr && mmapd.backing_fh != INVALID_HANDLE_VALUE) {
+            std::ignore = FlushFileBuffers(mmapd.backing_fh);
+        }
+    }
+    if (mmapd.host_memory != nullptr) {
+        std::ignore = UnmapViewOfFile(mmapd.host_memory);
+    }
+    if (mmapd.backing_host_memory != nullptr) {
+        std::ignore = UnmapViewOfFile(mmapd.backing_host_memory);
+    }
+    if (mmapd.memory_mapping != nullptr) {
+        std::ignore = CloseHandle(static_cast<HANDLE>(mmapd.memory_mapping));
+    }
+    if (mmapd.backing_mapping != nullptr) {
+        std::ignore = CloseHandle(static_cast<HANDLE>(mmapd.backing_mapping));
+    }
+    if (mmapd.backing_fh != nullptr && mmapd.backing_fh != INVALID_HANDLE_VALUE) {
+        if (mmapd.backing_lock) {
+            OVERLAPPED overlapped{};
+            std::ignore = UnlockFileEx(static_cast<HANDLE>(mmapd.backing_fh), 0, MAXDWORD, MAXDWORD, &overlapped);
+        }
+        std::ignore = CloseHandle(static_cast<HANDLE>(mmapd.backing_fh));
+    }
+
+#else // Fallback implementation using standard C APIs
+    if (mmapd.backing_sync_length > 0 && mmapd.host_memory != nullptr && mmapd.backing_fp != nullptr) {
+        // Write back changes to backing file
+        std::ignore = std::fwrite(mmapd.host_memory, 1, mmapd.backing_sync_length, mmapd.backing_fp);
+        std::ignore = std::fflush(mmapd.backing_fp);
+    }
+    if (mmapd.unaligned_host_memory != nullptr) {
+        std::free(mmapd.unaligned_host_memory); // NOLINT(cppcoreguidelines-no-malloc,hicpp-no-malloc)
+    }
+    if (mmapd.backing_fp != nullptr) {
+        std::ignore = std::fclose(mmapd.backing_fp);
+    }
+
+#endif // HAVE_MMAP
+}
+
+} // namespace cartesi
diff --git a/src/os-mmap.h b/src/os-mmap.h
new file mode 100644
index 000000000..0f9f4542d
--- /dev/null
+++ b/src/os-mmap.h
@@ -0,0 +1,123 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef OS_MMAP_H
+#define OS_MMAP_H
+
+/// \file
+/// \brief Operating system memory mapping operations.
+/// \details \{
+/// This header file defines the interface for memory mapping operations for the emulator.
+/// It provides a cross-platform abstraction for memory-mapped regions, supporting both anonymous
+/// and file-backed mappings. The implementation ensures compatibility with various operating
+/// systems, including Linux, Windows, and fallback environments without native `mmap` support.
+///
+/// Key Features:
+/// - Memory mapping with optional file backing.
+/// - Support for read-only, shared, and exclusive access modes.
+/// - Automatic alignment to system page size for efficient memory access.
+/// - Cross-platform compatibility with platform-specific optimizations.
+///
+/// This module is designed to handle complex memory mapping scenarios, such as partial file
+/// mappings, file truncation, and synchronization of file-backed memory regions.
+/// \}
+
+#include <cstdint>
+#include <memory>
+#include <string>
+
+#include "os-features.h"
+
+#ifndef HAVE_MMAP
+#include <cstdio>
+#endif
+
+namespace cartesi {
+
+/// \brief Flags for memory mapping operations.
+struct os_mmap_flags {
+    bool read_only{false}; ///< Mark mapped memory as read-only
+    bool shared{false};    ///< Share mapped memory with the backing file
+    bool create{false};    ///< Create the backing file (requires shared to be true)
+    bool truncate{false};  ///< Truncate backing file to match the specified backing file length
+    bool lock{false};      ///< Lock the backing file for exclusive writing when shared, otherwise for shared reading
+};
+
+/// \brief Structure representing a memory-mapped region.
+struct os_mmapd {
+    void *host_memory{nullptr};      ///< Pointer to the mapped memory region
+    uint64_t length{0};              ///< The total size of the mapped memory
+    uint64_t backing_sync_length{0}; ///< Length of file-backed portion for which memory sync is needed
+#ifdef HAVE_MMAP
+    int backing_fd{-1}; ///< File descriptor of the backing file
+#elif defined(_WIN32)
+    void *memory_mapping{nullptr};      ///< Handle of the memory mapping
+    void *backing_host_memory{nullptr}; ///< Pointer to the backing file mapped memory region
+    void *backing_mapping{nullptr};     ///< Handle of the backing file mapping
+    void *backing_fh{nullptr};          ///< Handle of the backing file
+    bool backing_lock{false};           ///< Whether the backing file was locked
+#else
+    FILE *backing_fp{nullptr};            ///< Pointer of the backing file
+    void *unaligned_host_memory{nullptr}; ///< Pointer to the memory that we can deallocate with std::free()
+#endif
+};
+
+/// \brief Retrieves the system's memory page size.
+/// \details Typically 4KB, but may vary (e.g., 8KB on Solaris, 16KB on macOS arm64).
+uint64_t os_get_mmap_page_size();
+
+/// \brief Maps a memory region, optionally backed by a file.
+/// \param length Total memory length to map.
+/// \param flags Flags for the mapping.
+/// \param backing_filename Path to the file to back the memory mapping (if empty, creates anonymous mapping).
+/// \param backing_length The expected or intended size of the backing file in bytes (must be <= length).
+/// \returns Structure containing the memory mapping information.
+/// \details The memory is guaranteed to be aligned to 4096-byte boundaries.
+/// Memory above backing file length are zereod, and modifications to that region are not written out to the file.
+os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags = {}, const std::string &backing_filename = {},
+    uint64_t backing_length = 0);
+
+/// \brief Unmaps a previously mapped memory region.
+void os_munmap(const os_mmapd &mmapd) noexcept;
+
+namespace detail {
+
+struct mmap_deleter {
+    os_mmapd m_mmapd;
+    explicit mmap_deleter(os_mmapd mmapd) : m_mmapd(mmapd) {};
+    template <typename T>
+    void operator()(T * /*ptr*/) const noexcept {
+        os_munmap(m_mmapd);
+    }
+};
+
+} // namespace detail
+
+template <typename T>
+using unique_mmap_ptr = std::unique_ptr<T, detail::mmap_deleter>;
+
+template <typename T>
+static inline auto make_unique_mmap(size_t nmemb, const os_mmap_flags &flags = {},
+    const std::string &backing_filename = {}, uint64_t backing_length = 0) {
+    const size_t size = nmemb * sizeof(T);
+    const os_mmapd mmapd = os_mmap(size, flags, backing_filename, backing_length); // os_map throws on error
+    T *ptr = static_cast<T *>(mmapd.host_memory);
+    return unique_mmap_ptr<T>(ptr, detail::mmap_deleter{mmapd});
+}
+
+} // namespace cartesi
+
+#endif
diff --git a/src/os.cpp b/src/os.cpp
index 3db6d7dbc..5f509978b 100644
--- a/src/os.cpp
+++ b/src/os.cpp
@@ -43,7 +43,7 @@
 #include <thread>
 #endif
 
-#if defined(HAVE_TTY) || defined(HAVE_MMAP) || defined(HAVE_TERMIOS) || defined(_WIN32)
+#if defined(HAVE_TTY) || defined(HAVE_TERMIOS) || defined(_WIN32)
 #include <fcntl.h> // open
 #endif
 
@@ -54,11 +54,7 @@
 #endif
 #endif
 
-#ifdef HAVE_MMAP
-#include <sys/mman.h> // mmap/munmap
-#endif
-
-#if defined(HAVE_MMAP) || defined(HAVE_MKDIR) || defined(_WIN32)
+#if defined(HAVE_MKDIR) || defined(_WIN32)
 #include <sys/stat.h> // fstat/mkdir
 #endif
 
@@ -89,7 +85,7 @@
 
 #else // not _WIN32
 
-#if defined(HAVE_TTY) || defined(HAVE_MMAP) || defined(HAVE_TERMIOS) || defined(HAVE_USLEEP)
+#if defined(HAVE_TTY) || defined(HAVE_TERMIOS) || defined(HAVE_USLEEP)
 #include <unistd.h> // write/read/close/usleep/fork
 #endif
 
@@ -118,6 +114,7 @@ struct tty_state {
     bool initialized{false};
     bool resize_pending{false};
     bool silence_putchar{false};
+    uint64_t use_count{0};
     std::array<char, TTY_BUF_SIZE> buf{}; // Characters in console input buffer
     intptr_t buf_pos{};
     intptr_t buf_len{};
@@ -236,11 +233,13 @@ void os_open_tty() {
 #ifdef HAVE_TTY
     auto *s = get_tty_state();
     if (s->initialized) {
+        s->use_count++;
         // Already initialized
         return;
     }
 
     s->initialized = true;
+    s->use_count = 1;
 
 #ifdef HAVE_TERMIOS
     if (s->ttyfd >= 0) { // Already open
@@ -342,10 +341,17 @@ void os_close_tty() {
 #ifdef HAVE_TTY
 #ifdef HAVE_TERMIOS
     auto *s = get_tty_state();
+    if (!s->initialized) {
+        return;
+    }
+    if (--s->use_count > 0) {
+        // Still in use by some other machine
+        return;
+    }
     if (s->ttyfd >= 0) { // Restore old mode
         tcsetattr(s->ttyfd, TCSANOW, &s->oldtty);
         close(s->ttyfd);
-        s->ttyfd = 1;
+        s->ttyfd = -1;
     }
 
 #elif defined(_WIN32)
@@ -553,148 +559,6 @@ int os_mkdir(const char *path, [[maybe_unused]] int mode) {
 #endif // HAVE_MKDIR
 }
 
-void *os_map_file(const char *path, uint64_t length, bool shared) {
-    if ((path == nullptr) || *path == '\0') {
-        throw std::runtime_error{"image file path must be specified"s};
-    }
-
-#ifdef HAVE_MMAP
-    const int oflag = shared ? O_RDWR : O_RDONLY;
-
-    // Try to open image file
-    const int backing_file = open(path, oflag);
-    if (backing_file < 0) {
-        throw std::system_error{errno, std::generic_category(), "could not open image file '"s + path + "'"s};
-    }
-
-    // Try to get file size
-    struct stat statbuf{};
-    if (fstat(backing_file, &statbuf) < 0) {
-        close(backing_file);
-        throw std::system_error{errno, std::generic_category(),
-            "unable to obtain length of image file '"s + path + "'"s};
-    }
-
-    // Check that it matches range length
-    if (static_cast<uint64_t>(statbuf.st_size) != length) {
-        close(backing_file);
-        throw std::invalid_argument{"image file '"s + path + "' size ("s +
-            std::to_string(static_cast<uint64_t>(statbuf.st_size)) + ") does not match range length ("s +
-            std::to_string(length) + ")"s};
-    }
-
-    // Try to map image file to host memory
-    const int mflag = shared ? MAP_SHARED : MAP_PRIVATE;
-    void *host_memory = mmap(nullptr, length, PROT_READ | PROT_WRITE, mflag, backing_file, 0);
-    if (host_memory == MAP_FAILED) { // NOLINT(cppcoreguidelines-pro-type-cstyle-cast,performance-no-int-to-ptr)
-        close(backing_file);
-        throw std::system_error{errno, std::generic_category(), "could not map image file '"s + path + "' to memory"s};
-    }
-
-    // We can close the file after mapping it, because the OS will retain a reference of the file on its own
-    close(backing_file);
-    return host_memory;
-
-#elif defined(_WIN32)
-    const int oflag = (shared ? _O_RDWR : _O_RDONLY) | _O_BINARY;
-
-    // Try to open image file
-    const int backing_file = _open(path, oflag);
-    if (backing_file < 0) {
-        throw std::system_error{errno, std::generic_category(), "could not open image file '"s + path + "'"s};
-    }
-
-    // Try to get file size
-    struct __stat64 statbuf{};
-    if (_fstat64(backing_file, &statbuf) < 0) {
-        _close(backing_file);
-        throw std::system_error{errno, std::generic_category(),
-            "unable to obtain length of image file '"s + path + "'"s};
-    }
-
-    // Check that it matches range length
-    if (static_cast<uint64_t>(statbuf.st_size) != length) {
-        _close(backing_file);
-        throw std::invalid_argument{"image file '"s + path + "' size ("s +
-            std::to_string(static_cast<uint64_t>(statbuf.st_size)) + ") does not match range length ("s +
-            std::to_string(length) + ")"s};
-    }
-
-    // Try to map image file to host memory
-    DWORD flProtect = shared ? PAGE_READWRITE : PAGE_READONLY;
-    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-    HANDLE hFile = reinterpret_cast<HANDLE>(_get_osfhandle(backing_file));
-    HANDLE hFileMappingObject = CreateFileMapping(hFile, NULL, flProtect, length >> 32, length & 0xffffffff, NULL);
-    if (!hFileMappingObject) {
-        _close(backing_file);
-        throw std::system_error{errno, std::generic_category(), "could not map image file '"s + path + "' to memory"s};
-    }
-
-    DWORD dwDesiredAccess = shared ? FILE_MAP_WRITE : FILE_MAP_COPY;
-    void *host_memory = MapViewOfFile(hFileMappingObject, dwDesiredAccess, 0, 0, length);
-    if (!host_memory) {
-        _close(backing_file);
-        throw std::system_error{errno, std::generic_category(), "could not map image file '"s + path + "' to memory"s};
-    }
-
-    // We can close the file after mapping it, because the OS will retain a reference of the file on its own
-    _close(backing_file);
-    return host_memory;
-
-#else
-    if (shared) {
-        throw std::runtime_error{"shared image file mapping is unsupported"s};
-    }
-
-    auto fp = unique_fopen(path, "rb", std::nothrow_t{});
-    if (!fp) {
-        throw std::system_error{errno, std::generic_category(), "error opening image file '"s + path + "'"s};
-    }
-    // Get file size
-    if (fseek(fp.get(), 0, SEEK_END)) {
-        throw std::system_error{errno, std::generic_category(),
-            "error obtaining length of image file '"s + path + "'"s};
-    }
-    auto file_length = ftell(fp.get());
-    if (fseek(fp.get(), 0, SEEK_SET)) {
-        throw std::system_error{errno, std::generic_category(),
-            "error obtaining length of image file '"s + path + "'"s};
-    }
-    // Check against PMA range size
-    if (static_cast<uint64_t>(file_length) > length) {
-        throw std::runtime_error{"image file '"s + path + "' of "s + " is too large for range"s};
-    }
-
-    // use calloc to improve performance
-    // NOLINTNEXTLINE(cppcoreguidelines-no-malloc,hicpp-no-malloc)
-    auto host_memory = static_cast<unsigned char *>(std::calloc(1, length));
-    if (!host_memory) {
-        throw std::runtime_error{"error allocating memory"s};
-    }
-
-    // Read to host memory
-    std::ignore = fread(host_memory, 1, length, fp.get());
-    if (ferror(fp.get())) {
-        throw std::system_error{errno, std::generic_category(), "error reading from image file '"s + path + "'"s};
-    }
-    return host_memory;
-
-#endif // HAVE_MMAP
-}
-
-void os_unmap_file(void *host_memory, [[maybe_unused]] uint64_t length) {
-#ifdef HAVE_MMAP
-    munmap(host_memory, length);
-
-#elif defined(_WIN32)
-    UnmapViewOfFile(host_memory);
-
-#else
-    std::free(host_memory);
-
-#endif // HAVE_MMAP
-}
-
 int64_t os_now_us() {
     static const std::chrono::time_point<std::chrono::high_resolution_clock> start{
         std::chrono::high_resolution_clock::now()};
diff --git a/src/os.h b/src/os.h
index 36d58195d..d271f609d 100644
--- a/src/os.h
+++ b/src/os.h
@@ -93,12 +93,6 @@ void os_silence_putchar(bool yes);
 /// \brief Creates a new directory
 int os_mkdir(const char *path, int mode);
 
-/// \brief Maps a file to memory
-void *os_map_file(const char *path, uint64_t length, bool shared);
-
-/// \brief Unmaps a file from memory
-void os_unmap_file(void *host_memory, uint64_t length);
-
 /// \brief Get time elapsed since its first call with microsecond precision
 int64_t os_now_us();
 
diff --git a/src/pmas-constants.h b/src/pmas-constants.h
index ff87b0031..4744f56ad 100644
--- a/src/pmas-constants.h
+++ b/src/pmas-constants.h
@@ -59,7 +59,6 @@ enum class PMA_ISTART_DID : uint8_t {
     empty = PMA_EMPTY_DID_DEF,                           ///< DID for empty range
     memory = PMA_MEMORY_DID_DEF,                         ///< DID for memory
     shadow_state = PMA_SHADOW_STATE_DID_DEF,             ///< DID for shadow state
-    shadow_TLB = PMA_SHADOW_TLB_DID_DEF,                 ///< DID for shadow TLB
     flash_drive = PMA_FLASH_DRIVE_DID_DEF,               ///< DID for flash drives
     CLINT = PMA_CLINT_DID_DEF,                           ///< DID for CLINT device
     PLIC = PMA_PLIC_DID_DEF,                             ///< DID for PLIC device
diff --git a/src/pmas-defines.h b/src/pmas-defines.h
index 38008e7c7..42561cd27 100644
--- a/src/pmas-defines.h
+++ b/src/pmas-defines.h
@@ -20,18 +20,17 @@
 
 #define PMA_MAX_DEF 32 ///< Maximum number of PMAs
 
-#define PMA_EMPTY_DID_DEF 0               ///< Device ID for empty range
-#define PMA_MEMORY_DID_DEF 1              ///< Device ID for memory
-#define PMA_SHADOW_STATE_DID_DEF 2        ///< Device ID for shadow state device
-#define PMA_FLASH_DRIVE_DID_DEF 3         ///< Device ID for flash drive device
-#define PMA_CLINT_DID_DEF 4               ///< Device ID for CLINT device
-#define PMA_HTIF_DID_DEF 5                ///< Device ID for HTIF device
-#define PMA_SHADOW_TLB_DID_DEF 6          ///< Device ID for shadow TLB device
-#define PMA_CMIO_RX_BUFFER_DID_DEF 7      ///< Device ID for cmio RX buffer
-#define PMA_CMIO_TX_BUFFER_DID_DEF 8      ///< Device ID for cmio TX buffer
-#define PMA_PLIC_DID_DEF 10               ///< Device ID for PLIC device
-#define PMA_VIRTIO_DID_DEF 11             ///< Device ID for VirtIO devices
-#define PMA_SHADOW_UARCH_STATE_DID_DEF 12 ///< Device ID for uarch shadow state device
+#define PMA_EMPTY_DID_DEF 0              ///< Device ID for empty range
+#define PMA_MEMORY_DID_DEF 1             ///< Device ID for memory
+#define PMA_SHADOW_STATE_DID_DEF 2       ///< Device ID for shadow state device
+#define PMA_FLASH_DRIVE_DID_DEF 3        ///< Device ID for flash drive device
+#define PMA_CLINT_DID_DEF 4              ///< Device ID for CLINT device
+#define PMA_HTIF_DID_DEF 5               ///< Device ID for HTIF device
+#define PMA_PLIC_DID_DEF 6               ///< Device ID for PLIC device
+#define PMA_CMIO_RX_BUFFER_DID_DEF 7     ///< Device ID for cmio RX buffer
+#define PMA_CMIO_TX_BUFFER_DID_DEF 8     ///< Device ID for cmio TX buffer
+#define PMA_SHADOW_UARCH_STATE_DID_DEF 9 ///< Device ID for uarch shadow state device
+#define PMA_VIRTIO_DID_DEF 10            ///< Device ID for VirtIO devices
 
 // helper for using UINT64_C with defines
 #ifndef EXPAND_UINT64_C
diff --git a/src/pmas.h b/src/pmas.h
index 6244ee1b6..cea24d9c9 100644
--- a/src/pmas.h
+++ b/src/pmas.h
@@ -38,8 +38,6 @@ static constexpr const char *pmas_get_DID_name(PMA_ISTART_DID did) {
             return "DID.memory";
         case PMA_ISTART_DID::shadow_state:
             return "DID.shadow_state";
-        case PMA_ISTART_DID::shadow_TLB:
-            return "DID.shadow_TLB";
         case PMA_ISTART_DID::flash_drive:
             return "DID.flash_drive";
         case PMA_ISTART_DID::CLINT:
@@ -55,7 +53,7 @@ static constexpr const char *pmas_get_DID_name(PMA_ISTART_DID did) {
         case PMA_ISTART_DID::cmio_tx_buffer:
             return "DID.cmio_tx_buffer";
         case PMA_ISTART_DID::shadow_uarch_state:
-            return "DID.shadow_uarch";
+            return "DID.shadow_uarch_state";
     }
     return "DID.unknown";
 }
@@ -72,6 +70,12 @@ static constexpr bool pmas_is_protected(PMA_ISTART_DID DID) {
     }
 }
 
+static constexpr bool pmas_range_overlaps(uint64_t a_start, uint64_t a_length, uint64_t b_start, uint64_t b_length) {
+    const uint64_t a_end = a_start + a_length - 1;
+    const uint64_t b_end = b_start + b_length - 1;
+    return (a_start <= b_end && a_end >= b_start);
+}
+
 ///< Unpacked attribute flags
 struct pmas_flags {
     bool M;             ///< is memory
diff --git a/src/processor-state.h b/src/processor-state.h
new file mode 100644
index 000000000..bd4b0ba70
--- /dev/null
+++ b/src/processor-state.h
@@ -0,0 +1,73 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef PROCESSOR_STATE_H
+#define PROCESSOR_STATE_H
+
+/// \file
+/// \brief Cartesi machine processor state structure definition.
+
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <vector>
+
+#include "address-range.h"
+#include "hot-tlb.h"
+#include "riscv-constants.h"
+#include "shadow-registers.h"
+#include "shadow-tlb.h"
+
+namespace cartesi {
+
+/// brief Shadow state.
+/// \details It's stored in the processor backing file.
+struct shadow_state final {
+    registers_state registers;          ///< Registers state
+    uint64_t registers_padding_[406]{}; ///< Padding to align next field to a page boundary
+    shadow_tlb_state tlb;               ///< Shadow TLB state
+    uint64_t shadow_tlb_padding[512]{}; ///< Padding to align next field to a page boundary
+};
+
+/// \brief Penumbra state.
+/// \details It's not stored in the processor backing file, it's only visible in host memory during runtime.
+struct penumbra_state final {
+    hot_tlb_state tlb; ///< Hot TLB state
+};
+
+/// \brief Machine processor state.
+/// \details Contains the registers and TLB state of a machine.
+struct processor_state final {
+    shadow_state shadow;     ///< Shadow state
+    penumbra_state penumbra; ///< Penumbra state
+};
+
+static_assert(offsetof(shadow_state, tlb) % AR_PAGE_SIZE == 0, "shadow tlb state must be aligned to a page boundary");
+static_assert(offsetof(processor_state, penumbra) % AR_PAGE_SIZE == 0,
+    "penumbra state must be aligned to a page boundary");
+
+static_assert(sizeof(processor_state) % AR_PAGE_SIZE == 0, "processor state size must be multiple of a page size");
+static_assert(sizeof(shadow_state) == AR_SHADOW_STATE_LENGTH, "unexpected shadow state size");
+
+// The size of the shadow state should align with the largest page size used by the supported operating systems.
+// For instance, macOS on arm64 currently utilizes a page size of 16KB.
+// Doing this ensures that memory allocations made with os_mmap()
+// result in the backing shadow file occupying whole pages, avoiding partial page mappings.
+static_assert(sizeof(shadow_state) % 16384 == 0, "shadow state size must be multiple of a 16KB");
+
+} // namespace cartesi
+
+#endif
diff --git a/src/record-send-cmio-state-access.h b/src/record-send-cmio-state-access.h
index b031c1015..ef732603c 100644
--- a/src/record-send-cmio-state-access.h
+++ b/src/record-send-cmio-state-access.h
@@ -32,10 +32,10 @@
 #include "i-hasher.h"
 #include "i-state-access.h"
 #include "machine-merkle-tree.h"
-#include "machine-state.h"
 #include "machine.h"
 #include "meta.h"
-#include "shadow-state.h"
+#include "processor-state.h"
+#include "shadow-registers.h"
 
 namespace cartesi {
 
@@ -186,17 +186,17 @@ class record_send_cmio_state_access :
 
     void do_write_iflags_Y(uint64_t val) const {
         log_before_write_write_and_update(machine_reg_address(machine_reg::iflags_Y),
-            m_m.get_state().registers.iflags.Y, val, "iflags.Y");
+            m_m.get_state().shadow.registers.iflags.Y, val, "iflags.Y");
     }
 
     uint64_t do_read_iflags_Y() const {
         log_read(machine_reg_address(machine_reg::iflags_Y), "iflags.Y");
-        return m_m.get_state().registers.iflags.Y;
+        return m_m.get_state().shadow.registers.iflags.Y;
     }
 
     void do_write_htif_fromhost(uint64_t val) const {
         log_before_write_write_and_update(machine_reg_address(machine_reg::htif_fromhost),
-            m_m.get_state().registers.htif.fromhost, val, "htif.fromhost");
+            m_m.get_state().shadow.registers.htif.fromhost, val, "htif.fromhost");
     }
 
     void do_write_memory_with_padding(uint64_t paddr, const unsigned char *data, uint64_t data_length,
diff --git a/src/record-step-state-access.h b/src/record-step-state-access.h
index e1cc987a5..e0c4395fc 100644
--- a/src/record-step-state-access.h
+++ b/src/record-step-state-access.h
@@ -201,11 +201,11 @@ class record_step_state_access :
     // -----
     friend i_prefer_shadow_state<record_step_state_access>;
 
-    uint64_t do_read_shadow_state(shadow_state_what what) const {
+    uint64_t do_read_shadow_register(shadow_registers_what what) const {
         return log_read_reg(machine_reg_enum(what));
     }
 
-    void do_write_shadow_state(shadow_state_what what, uint64_t val) const {
+    void do_write_shadow_register(shadow_registers_what what, uint64_t val) const {
         log_write_reg(machine_reg_enum(what), val);
     }
 
@@ -264,7 +264,7 @@ class record_step_state_access :
 
     //??D This is still a bit too complicated for my taste
     template <TLB_set_index SET>
-    host_addr do_read_tlb_vp_offset(uint64_t slot_index) const {
+    host_addr do_read_tlb_vf_offset(uint64_t slot_index) const {
         // During initialization, replay_step_state_access translates all vp_offset to corresponding vh_offset
         // At deinitialization, it translates them back
         // To do that, it needs the corresponding paddr_page = vaddr_page + vp_offset, and page data itself
@@ -275,12 +275,11 @@ class record_step_state_access :
         // We still need to touch the page data
         // Writes to the TLB slot are atomic, so we know the values in a slot are ALWAYS internally consistent.
         // This means we can safely use all other fields to find paddr_page.
-        const auto vaddr_page = m_m.get_state().tlb.hot[SET][slot_index].vaddr_page;
-        const auto vh_offset = m_m.get_state().tlb.hot[SET][slot_index].vh_offset;
+        const auto vaddr_page = m_m.get_state().penumbra.tlb[SET][slot_index].vaddr_page;
+        const auto vh_offset = m_m.get_state().penumbra.tlb[SET][slot_index].vh_offset;
         if (vaddr_page != TLB_INVALID_PAGE) {
-            const auto pma_index = m_m.get_state().tlb.cold[SET][slot_index].pma_index;
-            const auto haddr_page = vaddr_page + vh_offset;
-            auto paddr_page = m_m.get_paddr(haddr_page, pma_index);
+            const auto vp_offset = m_m.get_state().shadow.tlb[SET][slot_index].vp_offset;
+            const auto paddr_page = vaddr_page + vp_offset;
             touch_page(paddr_page);
         }
         return vh_offset;
@@ -299,12 +298,10 @@ class record_step_state_access :
         // We still need to touch the page data
         if (vaddr_page != TLB_INVALID_PAGE) {
             const auto haddr_page = vaddr_page + vh_offset;
-            auto paddr_page = m_m.get_paddr(haddr_page, pma_index);
+            const auto paddr_page = m_m.get_paddr(haddr_page, pma_index);
             touch_page(paddr_page);
         }
-        m_m.get_state().tlb.hot[SET][slot_index].vaddr_page = vaddr_page;
-        m_m.get_state().tlb.hot[SET][slot_index].vh_offset = vh_offset;
-        m_m.get_state().tlb.cold[SET][slot_index].pma_index = pma_index;
+        m_m.write_tlb(SET, slot_index, vaddr_page, vh_offset, pma_index);
     }
 
     fast_addr do_get_faddr(uint64_t paddr, uint64_t pma_index) const {
diff --git a/src/replay-send-cmio-state-access.h b/src/replay-send-cmio-state-access.h
index f22449b05..42688f143 100644
--- a/src/replay-send-cmio-state-access.h
+++ b/src/replay-send-cmio-state-access.h
@@ -34,7 +34,7 @@
 #include "machine-merkle-tree.h"
 #include "meta.h"
 #include "riscv-constants.h"
-#include "shadow-state.h"
+#include "shadow-registers.h"
 #include "unique-c-ptr.h"
 
 namespace cartesi {
diff --git a/src/replay-step-state-access.h b/src/replay-step-state-access.h
index b56476553..f7986d8a2 100644
--- a/src/replay-step-state-access.h
+++ b/src/replay-step-state-access.h
@@ -31,7 +31,7 @@
 #include "pmas.h"
 #include "replay-step-state-access-interop.h"
 #include "riscv-constants.h"
-#include "shadow-state.h"
+#include "shadow-registers.h"
 #include "shadow-tlb.h"
 #include "shadow-uarch-state.h"
 #include "strict-aliasing.h"
@@ -231,7 +231,7 @@ class replay_step_state_access :
             auto *vp_offset_log = try_find_page(vp_offset_field_addr & ~PAGE_OFFSET_MASK);
             const auto vaddr_page_field_addr = shadow_tlb_get_abs_addr(SET, slot_index, shadow_tlb_what::vaddr_page);
             auto *vaddr_page_log = try_find_page(vaddr_page_field_addr & ~PAGE_OFFSET_MASK);
-            // If vp_offset was accessed during record, both it and vaddr_apge will appear in the log
+            // If vp_offset was accessed during record, both it and vaddr_page will appear in the log
             // (record_step_state_access makes sure of it)
             // Otherwise, we do not need to translate
             if (vp_offset_log == nullptr || vaddr_page_log == nullptr) {
@@ -268,7 +268,7 @@ class replay_step_state_access :
             auto *vp_offset_log = try_find_page(vp_offset_field_addr & ~PAGE_OFFSET_MASK);
             const auto vaddr_page_field_addr = shadow_tlb_get_abs_addr(SET, slot_index, shadow_tlb_what::vaddr_page);
             auto *vaddr_page_log = try_find_page(vaddr_page_field_addr & ~PAGE_OFFSET_MASK);
-            // If vp_offset was accessed during record, both it and vaddr_apge will appear in the log
+            // If vp_offset was accessed during record, both it and vaddr_page will appear in the log
             // (record_step_state_access makes sure of it)
             // Otherwise, we do not need to translate
             if (vp_offset_log == nullptr || vaddr_page_log == nullptr) {
@@ -402,11 +402,11 @@ class replay_step_state_access :
     // -----
     friend i_prefer_shadow_state<replay_step_state_access>;
 
-    uint64_t do_read_shadow_state(shadow_state_what what) const {
+    uint64_t do_read_shadow_register(shadow_registers_what what) const {
         return check_read_reg(machine_reg_enum(what));
     }
 
-    void do_write_shadow_state(shadow_state_what what, uint64_t val) const {
+    void do_write_shadow_register(shadow_registers_what what, uint64_t val) const {
         check_write_reg(machine_reg_enum(what), val);
     }
 
@@ -481,7 +481,7 @@ class replay_step_state_access :
     }
 
     template <TLB_set_index SET>
-    host_addr do_read_tlb_vp_offset(uint64_t slot_index) const {
+    host_addr do_read_tlb_vf_offset(uint64_t slot_index) const {
         return check_read_tlb<host_addr>(SET, slot_index, shadow_tlb_what::vp_offset);
     }
 
diff --git a/src/shadow-peek.h b/src/shadow-peek.h
deleted file mode 100644
index 8d094bc80..000000000
--- a/src/shadow-peek.h
+++ /dev/null
@@ -1,67 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef SHADOW_PEEK_H
-#define SHADOW_PEEK_H
-
-#include <cstdint>
-
-namespace cartesi {
-
-// Forward declarations
-class machine;
-class address_range;
-
-/// \file
-/// \brief Peeks part of a shadow
-template <typename READ_REG_F>
-static bool shadow_peek(READ_REG_F read_reg, const address_range &ar, const machine &m, uint64_t offset,
-    uint64_t length, const unsigned char **data, unsigned char *scratch) {
-    // Must be inside range
-    if (!ar.contains_relative(offset, length)) {
-        *data = nullptr;
-        return false;
-    }
-    // Initial, potentially partial register read
-    const uint64_t offset_aligned = offset & ~(sizeof(uint64_t) - 1);
-    if (offset > offset_aligned) {
-        const auto val = read_reg(m, ar.get_start() + offset_aligned);
-        const auto partial = offset - offset_aligned;
-        memcpy(scratch, &val, partial);
-        length -= partial;
-        offset += partial;
-    }
-    // Now we are aligned, do all complete registers
-    const uint64_t paddr_start = ar.get_start() + offset;
-    const uint64_t length_aligned = length & ~(sizeof(uint64_t) - 1);
-    const uint64_t paddr_end = paddr_start + length_aligned;
-    for (uint64_t paddr = paddr_start; paddr < paddr_end; paddr += sizeof(uint64_t)) {
-        const auto val = read_reg(m, paddr);
-        aliased_aligned_write<uint64_t>(scratch + (paddr - paddr_start), val);
-    }
-    // Final, potentially partial register read
-    if (length > length_aligned) {
-        const auto partial = length - length_aligned;
-        const auto val = read_reg(m, paddr_end);
-        memcpy(scratch + length_aligned, &val, partial);
-    }
-    *data = scratch;
-    return true;
-}
-
-} // namespace cartesi
-
-#endif
diff --git a/src/shadow-state.h b/src/shadow-registers.h
similarity index 53%
rename from src/shadow-state.h
rename to src/shadow-registers.h
index f0742acfb..807c7dcf3 100644
--- a/src/shadow-state.h
+++ b/src/shadow-registers.h
@@ -14,8 +14,8 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#ifndef SHADOW_STATE_H
-#define SHADOW_STATE_H
+#ifndef SHADOW_REGISTERS_STATE_H
+#define SHADOW_REGISTERS_STATE_H
 
 #include <cstddef>
 #include <cstdint>
@@ -110,142 +110,142 @@ struct registers_state final {
 };
 
 /// \brief Shadow memory layout
-using shadow_state = registers_state;
+using shadow_registers_state = registers_state;
 
 // We need strong guarantees that shadow_state has fixed size and alignment across platforms.
-static_assert(sizeof(shadow_state) == 106 * sizeof(uint64_t), "unexpected registers state size");
-static_assert(alignof(shadow_state) == sizeof(uint64_t), "unexpected registers state alignment");
+static_assert(sizeof(shadow_registers_state) == 106 * sizeof(uint64_t), "unexpected registers state size");
+static_assert(alignof(shadow_registers_state) == sizeof(uint64_t), "unexpected registers state alignment");
 
-enum class shadow_state_what : uint64_t {
-    x0 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[0]),
-    x1 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[1]),
-    x2 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[2]),
-    x3 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[3]),
-    x4 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[4]),
-    x5 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[5]),
-    x6 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[6]),
-    x7 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[7]),
-    x8 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[8]),
-    x9 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[9]),
-    x10 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[10]),
-    x11 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[11]),
-    x12 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[12]),
-    x13 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[13]),
-    x14 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[14]),
-    x15 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[15]),
-    x16 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[16]),
-    x17 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[17]),
-    x18 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[18]),
-    x19 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[19]),
-    x20 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[20]),
-    x21 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[21]),
-    x22 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[22]),
-    x23 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[23]),
-    x24 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[24]),
-    x25 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[25]),
-    x26 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[26]),
-    x27 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[27]),
-    x28 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[28]),
-    x29 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[29]),
-    x30 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[30]),
-    x31 = AR_SHADOW_STATE_START + offsetof(shadow_state, x[31]),
-    f0 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[0]),
-    f1 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[1]),
-    f2 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[2]),
-    f3 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[3]),
-    f4 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[4]),
-    f5 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[5]),
-    f6 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[6]),
-    f7 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[7]),
-    f8 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[8]),
-    f9 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[9]),
-    f10 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[10]),
-    f11 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[11]),
-    f12 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[12]),
-    f13 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[13]),
-    f14 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[14]),
-    f15 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[15]),
-    f16 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[16]),
-    f17 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[17]),
-    f18 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[18]),
-    f19 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[19]),
-    f20 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[20]),
-    f21 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[21]),
-    f22 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[22]),
-    f23 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[23]),
-    f24 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[24]),
-    f25 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[25]),
-    f26 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[26]),
-    f27 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[27]),
-    f28 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[28]),
-    f29 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[29]),
-    f30 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[30]),
-    f31 = AR_SHADOW_STATE_START + offsetof(shadow_state, f[31]),
-    pc = AR_SHADOW_STATE_START + offsetof(shadow_state, pc),
-    fcsr = AR_SHADOW_STATE_START + offsetof(shadow_state, fcsr),
-    mvendorid = AR_SHADOW_STATE_START + offsetof(shadow_state, mvendorid),
-    marchid = AR_SHADOW_STATE_START + offsetof(shadow_state, marchid),
-    mimpid = AR_SHADOW_STATE_START + offsetof(shadow_state, mimpid),
-    mcycle = AR_SHADOW_STATE_START + offsetof(shadow_state, mcycle),
-    icycleinstret = AR_SHADOW_STATE_START + offsetof(shadow_state, icycleinstret),
-    mstatus = AR_SHADOW_STATE_START + offsetof(shadow_state, mstatus),
-    mtvec = AR_SHADOW_STATE_START + offsetof(shadow_state, mtvec),
-    mscratch = AR_SHADOW_STATE_START + offsetof(shadow_state, mscratch),
-    mepc = AR_SHADOW_STATE_START + offsetof(shadow_state, mepc),
-    mcause = AR_SHADOW_STATE_START + offsetof(shadow_state, mcause),
-    mtval = AR_SHADOW_STATE_START + offsetof(shadow_state, mtval),
-    misa = AR_SHADOW_STATE_START + offsetof(shadow_state, misa),
-    mie = AR_SHADOW_STATE_START + offsetof(shadow_state, mie),
-    mip = AR_SHADOW_STATE_START + offsetof(shadow_state, mip),
-    medeleg = AR_SHADOW_STATE_START + offsetof(shadow_state, medeleg),
-    mideleg = AR_SHADOW_STATE_START + offsetof(shadow_state, mideleg),
-    mcounteren = AR_SHADOW_STATE_START + offsetof(shadow_state, mcounteren),
-    menvcfg = AR_SHADOW_STATE_START + offsetof(shadow_state, menvcfg),
-    stvec = AR_SHADOW_STATE_START + offsetof(shadow_state, stvec),
-    sscratch = AR_SHADOW_STATE_START + offsetof(shadow_state, sscratch),
-    sepc = AR_SHADOW_STATE_START + offsetof(shadow_state, sepc),
-    scause = AR_SHADOW_STATE_START + offsetof(shadow_state, scause),
-    stval = AR_SHADOW_STATE_START + offsetof(shadow_state, stval),
-    satp = AR_SHADOW_STATE_START + offsetof(shadow_state, satp),
-    scounteren = AR_SHADOW_STATE_START + offsetof(shadow_state, scounteren),
-    senvcfg = AR_SHADOW_STATE_START + offsetof(shadow_state, senvcfg),
-    ilrsc = AR_SHADOW_STATE_START + offsetof(shadow_state, ilrsc),
-    iprv = AR_SHADOW_STATE_START + offsetof(shadow_state, iprv),
-    iflags_X = AR_SHADOW_STATE_START + offsetof(shadow_state, iflags.X),
-    iflags_Y = AR_SHADOW_STATE_START + offsetof(shadow_state, iflags.Y),
-    iflags_H = AR_SHADOW_STATE_START + offsetof(shadow_state, iflags.H),
-    iunrep = AR_SHADOW_STATE_START + offsetof(shadow_state, iunrep),
-    clint_mtimecmp = AR_SHADOW_STATE_START + offsetof(shadow_state, clint.mtimecmp),
-    plic_girqpend = AR_SHADOW_STATE_START + offsetof(shadow_state, plic.girqpend),
-    plic_girqsrvd = AR_SHADOW_STATE_START + offsetof(shadow_state, plic.girqsrvd),
-    htif_tohost = AR_SHADOW_STATE_START + offsetof(shadow_state, htif.tohost),
-    htif_fromhost = AR_SHADOW_STATE_START + offsetof(shadow_state, htif.fromhost),
-    htif_ihalt = AR_SHADOW_STATE_START + offsetof(shadow_state, htif.ihalt),
-    htif_iconsole = AR_SHADOW_STATE_START + offsetof(shadow_state, htif.iconsole),
-    htif_iyield = AR_SHADOW_STATE_START + offsetof(shadow_state, htif.iyield),
+enum class shadow_registers_what : uint64_t {
+    x0 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[0]),
+    x1 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[1]),
+    x2 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[2]),
+    x3 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[3]),
+    x4 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[4]),
+    x5 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[5]),
+    x6 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[6]),
+    x7 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[7]),
+    x8 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[8]),
+    x9 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[9]),
+    x10 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[10]),
+    x11 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[11]),
+    x12 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[12]),
+    x13 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[13]),
+    x14 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[14]),
+    x15 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[15]),
+    x16 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[16]),
+    x17 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[17]),
+    x18 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[18]),
+    x19 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[19]),
+    x20 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[20]),
+    x21 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[21]),
+    x22 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[22]),
+    x23 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[23]),
+    x24 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[24]),
+    x25 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[25]),
+    x26 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[26]),
+    x27 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[27]),
+    x28 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[28]),
+    x29 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[29]),
+    x30 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[30]),
+    x31 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, x[31]),
+    f0 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[0]),
+    f1 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[1]),
+    f2 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[2]),
+    f3 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[3]),
+    f4 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[4]),
+    f5 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[5]),
+    f6 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[6]),
+    f7 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[7]),
+    f8 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[8]),
+    f9 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[9]),
+    f10 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[10]),
+    f11 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[11]),
+    f12 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[12]),
+    f13 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[13]),
+    f14 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[14]),
+    f15 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[15]),
+    f16 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[16]),
+    f17 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[17]),
+    f18 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[18]),
+    f19 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[19]),
+    f20 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[20]),
+    f21 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[21]),
+    f22 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[22]),
+    f23 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[23]),
+    f24 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[24]),
+    f25 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[25]),
+    f26 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[26]),
+    f27 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[27]),
+    f28 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[28]),
+    f29 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[29]),
+    f30 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[30]),
+    f31 = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, f[31]),
+    pc = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, pc),
+    fcsr = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, fcsr),
+    mvendorid = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, mvendorid),
+    marchid = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, marchid),
+    mimpid = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, mimpid),
+    mcycle = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, mcycle),
+    icycleinstret = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, icycleinstret),
+    mstatus = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, mstatus),
+    mtvec = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, mtvec),
+    mscratch = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, mscratch),
+    mepc = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, mepc),
+    mcause = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, mcause),
+    mtval = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, mtval),
+    misa = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, misa),
+    mie = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, mie),
+    mip = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, mip),
+    medeleg = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, medeleg),
+    mideleg = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, mideleg),
+    mcounteren = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, mcounteren),
+    menvcfg = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, menvcfg),
+    stvec = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, stvec),
+    sscratch = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, sscratch),
+    sepc = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, sepc),
+    scause = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, scause),
+    stval = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, stval),
+    satp = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, satp),
+    scounteren = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, scounteren),
+    senvcfg = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, senvcfg),
+    ilrsc = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, ilrsc),
+    iprv = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, iprv),
+    iflags_X = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, iflags.X),
+    iflags_Y = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, iflags.Y),
+    iflags_H = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, iflags.H),
+    iunrep = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, iunrep),
+    clint_mtimecmp = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, clint.mtimecmp),
+    plic_girqpend = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, plic.girqpend),
+    plic_girqsrvd = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, plic.girqsrvd),
+    htif_tohost = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, htif.tohost),
+    htif_fromhost = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, htif.fromhost),
+    htif_ihalt = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, htif.ihalt),
+    htif_iconsole = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, htif.iconsole),
+    htif_iyield = AR_SHADOW_REGISTERS_START + offsetof(shadow_registers_state, htif.iyield),
     unknown_ = UINT64_C(1) << 63, // Outside of RISC-V address space
 };
 
-static constexpr shadow_state_what shadow_state_get_what(uint64_t paddr) {
-    if (paddr < AR_SHADOW_STATE_START || paddr - AR_SHADOW_STATE_START >= sizeof(shadow_state) ||
+static constexpr shadow_registers_what shadow_registers_get_what(uint64_t paddr) {
+    if (paddr < AR_SHADOW_REGISTERS_START || paddr - AR_SHADOW_REGISTERS_START >= sizeof(shadow_registers_state) ||
         (paddr & (sizeof(uint64_t) - 1)) != 0) {
-        return shadow_state_what::unknown_;
+        return shadow_registers_what::unknown_;
     }
     // NOLINTNEXTLINE(clang-analyzer-optin.core.EnumCastOutOfRange)
-    return static_cast<shadow_state_what>(paddr);
+    return static_cast<shadow_registers_what>(paddr);
 }
 
-static constexpr shadow_state_what shadow_state_get_what(shadow_state_what what, int i) {
-    return static_cast<shadow_state_what>(static_cast<uint64_t>(what) + (i * sizeof(uint64_t)));
+static constexpr shadow_registers_what shadow_registers_get_what(shadow_registers_what what, int i) {
+    return static_cast<shadow_registers_what>(static_cast<uint64_t>(what) + (i * sizeof(uint64_t)));
 }
 
-static constexpr const char *shadow_state_get_what_name(shadow_state_what what) {
+static constexpr const char *shadow_registers_get_what_name(shadow_registers_what what) {
     const auto paddr = static_cast<uint64_t>(what);
-    if (paddr < AR_SHADOW_STATE_START || paddr - AR_SHADOW_STATE_START >= sizeof(shadow_state) ||
+    if (paddr < AR_SHADOW_REGISTERS_START || paddr - AR_SHADOW_REGISTERS_START >= sizeof(shadow_registers_state) ||
         (paddr & (sizeof(uint64_t) - 1)) != 0) {
         return "state.unknown_";
     }
-    using reg = shadow_state_what;
+    using reg = shadow_registers_what;
     switch (what) {
         case reg::x0:
             return "x0";
diff --git a/src/shadow-state-address-range.cpp b/src/shadow-state-address-range.cpp
deleted file mode 100644
index d2944946c..000000000
--- a/src/shadow-state-address-range.cpp
+++ /dev/null
@@ -1,47 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#include "shadow-state-address-range.h"
-
-#include <cstdint>
-
-#include "machine-reg.h"
-#include "machine.h"
-#include "shadow-peek.h"
-
-namespace cartesi {
-
-bool shadow_state_address_range::do_peek(const machine &m, uint64_t offset, uint64_t length, const unsigned char **data,
-    unsigned char *scratch) const noexcept {
-    // If past useful range
-    if (offset >= sizeof(shadow_state)) {
-        *data = nullptr;
-        return contains_relative(offset, length);
-    }
-    // Otherwise, copy and return register data
-    return shadow_peek(
-        [](const machine &m, uint64_t paddr) {
-            auto reg = shadow_state_get_what(paddr);
-            uint64_t val = 0;
-            if (reg != shadow_state_what::unknown_) {
-                val = m.read_reg(machine_reg_enum(reg));
-            }
-            return val;
-        },
-        *this, m, offset, length, data, scratch);
-}
-
-} // namespace cartesi
diff --git a/src/shadow-state-address-range.h b/src/shadow-state-address-range.h
deleted file mode 100644
index d11e7e996..000000000
--- a/src/shadow-state-address-range.h
+++ /dev/null
@@ -1,72 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef SHADOW_STATE_ADDRESS_RANGE_H
-#define SHADOW_STATE_ADDRESS_RANGE_H
-
-#include <cstddef>
-#include <cstdint>
-
-#include "address-range-constants.h"
-#include "address-range.h"
-#include "shadow-state.h"
-
-/// \file
-/// \brief Shadow state address range.
-
-namespace cartesi {
-
-class shadow_state_address_range final : public address_range {
-
-    static constexpr pmas_flags m_shadow_state_flags{
-        .M = false,
-        .IO = false,
-        .R = false,
-        .W = false,
-        .X = false,
-        .IR = false,
-        .IW = false,
-        .DID = PMA_ISTART_DID::shadow_state,
-    };
-
-public:
-    template <typename ABRT>
-    explicit shadow_state_address_range(ABRT abrt) :
-        address_range("shadow state", AR_SHADOW_STATE_START, AR_SHADOW_STATE_LENGTH, m_shadow_state_flags, abrt) {
-        ;
-    }
-
-    shadow_state_address_range(const shadow_state_address_range &) = default;
-    shadow_state_address_range &operator=(const shadow_state_address_range &) = default;
-    shadow_state_address_range(shadow_state_address_range &&) noexcept = default;
-    shadow_state_address_range &operator=(shadow_state_address_range &&) noexcept = default;
-    ~shadow_state_address_range() override = default;
-
-private:
-#ifndef MICROARCHITECTURE
-    bool do_peek(const machine &m, uint64_t offset, uint64_t length, const unsigned char **data,
-        unsigned char *scratch) const noexcept override;
-#endif
-};
-
-template <typename ABRT>
-static inline shadow_state_address_range make_shadow_state_address_range(ABRT abrt) {
-    return shadow_state_address_range{abrt};
-}
-
-} // namespace cartesi
-
-#endif
diff --git a/src/shadow-tlb-address-range.cpp b/src/shadow-tlb-address-range.cpp
deleted file mode 100644
index d9f52fc96..000000000
--- a/src/shadow-tlb-address-range.cpp
+++ /dev/null
@@ -1,48 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#include "shadow-tlb-address-range.h"
-
-#include <cstdint>
-
-#include "machine.h"
-#include "shadow-peek.h"
-
-namespace cartesi {
-
-bool shadow_tlb_address_range::do_peek(const machine &m, uint64_t offset, uint64_t length, const unsigned char **data,
-    unsigned char *scratch) const noexcept {
-    // If past useful range
-    if (offset >= sizeof(shadow_tlb_state)) {
-        *data = nullptr;
-        return contains_relative(offset, length);
-    }
-    // Otherwise, copy and return register data
-    return shadow_peek(
-        [](const machine &m, uint64_t paddr) {
-            TLB_set_index set_index{};
-            uint64_t slot_index{};
-            auto reg = shadow_tlb_get_what(paddr, set_index, slot_index);
-            uint64_t val = 0;
-            if (reg != shadow_tlb_what::unknown_) {
-                val = m.read_shadow_tlb(set_index, slot_index, reg);
-            }
-            return val;
-        },
-        *this, m, offset, length, data, scratch);
-}
-
-} // namespace cartesi
diff --git a/src/shadow-tlb-address-range.h b/src/shadow-tlb-address-range.h
deleted file mode 100644
index e82ba76c2..000000000
--- a/src/shadow-tlb-address-range.h
+++ /dev/null
@@ -1,72 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef SHADOW_TLB_ADDRESS_RANGE_H
-#define SHADOW_TLB_ADDRESS_RANGE_H
-
-#include <cstddef>
-#include <cstdint>
-
-#include "address-range-constants.h"
-#include "address-range.h"
-#include "shadow-state.h"
-
-/// \file
-/// \brief Shadow state address range.
-
-namespace cartesi {
-
-class shadow_tlb_address_range final : public address_range {
-
-    static constexpr pmas_flags m_shadow_tlb_flags{
-        .M = false,
-        .IO = false,
-        .R = false,
-        .W = false,
-        .X = false,
-        .IR = false,
-        .IW = false,
-        .DID = PMA_ISTART_DID::shadow_TLB,
-    };
-
-public:
-    template <typename ABRT>
-    explicit shadow_tlb_address_range(ABRT abrt) :
-        address_range("shadow TLB", AR_SHADOW_TLB_START, AR_SHADOW_TLB_LENGTH, m_shadow_tlb_flags, abrt) {
-        ;
-    }
-
-    shadow_tlb_address_range(const shadow_tlb_address_range &) = default;
-    shadow_tlb_address_range &operator=(const shadow_tlb_address_range &) = default;
-    shadow_tlb_address_range(shadow_tlb_address_range &&) noexcept = default;
-    shadow_tlb_address_range &operator=(shadow_tlb_address_range &&) noexcept = default;
-    ~shadow_tlb_address_range() override = default;
-
-private:
-#ifndef MICROARCHITECTURE
-    bool do_peek(const machine &m, uint64_t offset, uint64_t length, const unsigned char **data,
-        unsigned char *scratch) const noexcept override;
-#endif
-};
-
-template <typename ABRT>
-static inline shadow_tlb_address_range make_shadow_tlb_address_range(ABRT abrt) {
-    return shadow_tlb_address_range{abrt};
-}
-
-} // namespace cartesi
-
-#endif
diff --git a/src/shadow-tlb-factory.h b/src/shadow-tlb-factory.h
deleted file mode 100644
index 635b63d3e..000000000
--- a/src/shadow-tlb-factory.h
+++ /dev/null
@@ -1,35 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef SHADOW_TLB_FACTORY_H
-#define SHADOW_TLB_FACTORY_H
-
-/// \file
-/// \brief TLB device factory.
-
-#include <cstdint>
-
-namespace cartesi {
-
-/// \brief Creates a PMA entry for the TLB device
-/// \param start Start address for memory range.
-/// \param length Length of memory range.
-/// \returns Corresponding PMA entry
-pmas_entry make_shadow_tlb_pmas_entry(uint64_t start, uint64_t length);
-
-} // namespace cartesi
-
-#endif
diff --git a/src/shadow-tlb.h b/src/shadow-tlb.h
index f6e9bfeee..d8589d11b 100644
--- a/src/shadow-tlb.h
+++ b/src/shadow-tlb.h
@@ -26,10 +26,45 @@
 #include <cstdint>
 
 #include "compiler-defines.h"
-#include "tlb.h"
+#include "pmas-constants.h"
+#include "riscv-constants.h"
 
 namespace cartesi {
 
+/// \brief Index of TLB set
+enum TLB_set_index : uint64_t { TLB_CODE, TLB_READ, TLB_WRITE, TLB_LAST_ = TLB_WRITE, TLB_NUM_SETS_ = TLB_WRITE + 1 };
+
+/// \brief TLB constants.
+enum TLB_constants : uint64_t {
+    TLB_SET_SIZE = 256,
+    TLB_INVALID_PAGE = UINT64_C(-1),
+    TLB_INVALID_PMA_INDEX = UINT64_C(-1),
+};
+
+/// \brief Gets a TLB slot index for a page.
+/// \param vaddr Target virtual address.
+/// \returns TLB slot index.
+constexpr uint64_t tlb_slot_index(uint64_t vaddr) {
+    return (vaddr >> LOG2_PAGE_SIZE) & (TLB_SET_SIZE - 1);
+}
+
+/// \brief Checks for a TLB hit.
+/// \tparam T Type of access needed (uint8_t, uint16_t, uint32_t, uint64_t).
+/// \param slot_vaddr_page vaddr_page in TLB slot
+/// \param vaddr Target virtual address being looked up.
+/// \returns True on hit, false otherwise.
+template <typename T>
+constexpr bool tlb_is_hit(uint64_t slot_vaddr_page, uint64_t vaddr) {
+    // Make sure misaligned accesses are always considered a miss
+    // Otherwise, we could report a hit for a word that goes past the end of the page.
+    // Aligned accesses smaller than a page size cannot straddle two pages.
+    return slot_vaddr_page == (vaddr & ~(PAGE_OFFSET_MASK & ~(sizeof(T) - 1)));
+}
+
+constexpr uint64_t tlb_addr_page(uint64_t addr) {
+    return addr & ~PAGE_OFFSET_MASK;
+}
+
 /// \brief Shadow TLB slot
 /// \details
 /// Given a target virtual address vaddr within a page matching vaddr_page in TLB slot, the corresponding
@@ -39,12 +74,11 @@ namespace cartesi {
 /// We can only do /aligned/ atomic writes.
 /// Therefore, TLB slot cannot be misaligned.
 /// To complete the power-of-two size, we include a zero_padding_ entry.
-struct PACKED shadow_tlb_slot {
-    uint64_t vaddr_page;    ///< Target virtual address of start of page
-    uint64_t vp_offset;     ///< Offset from target virtual address to target physical address within page
-    uint64_t pma_index;     ///< Index of PMA where physical page falls
-                            /// and host addresses
-    uint64_t zero_padding_; ///< Padding to make sure the sizeof(shadow_tlb_slot) is a power of 2
+struct shadow_tlb_slot final {
+    uint64_t vaddr_page{TLB_INVALID_PAGE}; ///< Target virtual address of start of page
+    uint64_t vp_offset{0}; ///< Offset from target virtual address to target physical address within page
+    uint64_t pma_index{TLB_INVALID_PMA_INDEX}; ///< Index of PMA where physical page falls and host addresses
+    uint64_t zero_padding_{0};                 ///< Padding to make sure the sizeof(shadow_tlb_slot) is a power of 2
 };
 
 constexpr uint64_t SHADOW_TLB_SLOT_SIZE = sizeof(shadow_tlb_slot);
diff --git a/src/shadow-uarch-state-address-range.cpp b/src/shadow-uarch-state-address-range.cpp
deleted file mode 100644
index 61dfdf649..000000000
--- a/src/shadow-uarch-state-address-range.cpp
+++ /dev/null
@@ -1,50 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#include "shadow-uarch-state-address-range.h"
-
-#include <cstdint>
-
-#include "machine-reg.h"
-#include "machine.h"
-#include "pmas-constants.h"
-#include "shadow-peek.h"
-#include "shadow-uarch-state.h"
-
-namespace cartesi {
-
-/// \brief Shadow uarch state device peek callback. See ::pmas_peek.
-bool shadow_uarch_state_address_range::do_peek(const machine &m, uint64_t offset, uint64_t length,
-    const unsigned char **data, unsigned char *scratch) const noexcept {
-    // If past useful range
-    if (offset >= sizeof(shadow_uarch_state)) {
-        *data = nullptr;
-        return contains_relative(offset, length);
-    }
-    // Otherwise, copy and return register data
-    return shadow_peek(
-        [](const machine &m, uint64_t paddr) {
-            const auto reg = shadow_uarch_state_get_what(paddr);
-            uint64_t val = 0;
-            if (reg != shadow_uarch_state_what::unknown_) {
-                val = m.read_reg(machine_reg_enum(reg));
-            }
-            return val;
-        },
-        *this, m, offset, length, data, scratch);
-}
-
-} // namespace cartesi
diff --git a/src/shadow-uarch-state-address-range.h b/src/shadow-uarch-state-address-range.h
deleted file mode 100644
index 9ddd4a4df..000000000
--- a/src/shadow-uarch-state-address-range.h
+++ /dev/null
@@ -1,73 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef SHADOW_UARCH_STATE_ADDRESS_RANGE_H
-#define SHADOW_UARCH_STATE_ADDRESS_RANGE_H
-
-#include <cstddef>
-#include <cstdint>
-
-#include "address-range.h"
-#include "shadow-uarch-state.h"
-
-/// \file
-/// \brief Shadow uarch state address range.
-
-namespace cartesi {
-
-class shadow_uarch_state_address_range final : public address_range {
-
-    static constexpr pmas_flags m_shadow_uarch_state_flags{
-        .M = false,
-        .IO = false,
-        .R = false,
-        .W = false,
-        .X = false,
-        .IR = false,
-        .IW = false,
-        .DID = PMA_ISTART_DID::shadow_uarch_state,
-    };
-
-public:
-    template <typename ABRT>
-    explicit shadow_uarch_state_address_range(ABRT abrt) :
-        address_range("shadow uarch state", AR_SHADOW_UARCH_STATE_START, AR_SHADOW_UARCH_STATE_LENGTH,
-            m_shadow_uarch_state_flags, abrt) {
-        ;
-    }
-
-    shadow_uarch_state_address_range(const shadow_uarch_state_address_range &) = delete;
-    shadow_uarch_state_address_range &operator=(const shadow_uarch_state_address_range &) = delete;
-    shadow_uarch_state_address_range &operator=(shadow_uarch_state_address_range &&) noexcept = delete;
-
-    shadow_uarch_state_address_range(shadow_uarch_state_address_range &&) noexcept = default;
-    ~shadow_uarch_state_address_range() override = default;
-
-private:
-#ifndef MICROARCHITECTURE
-    bool do_peek(const machine &m, uint64_t offset, uint64_t length, const unsigned char **data,
-        unsigned char *scratch) const noexcept override;
-#endif
-};
-
-template <typename ABRT>
-static inline shadow_uarch_state_address_range make_shadow_uarch_state_address_range(ABRT abrt) {
-    return shadow_uarch_state_address_range{abrt};
-}
-
-} // namespace cartesi
-
-#endif
diff --git a/src/state-access.h b/src/state-access.h
index 1665cfea0..927b77d26 100644
--- a/src/state-access.h
+++ b/src/state-access.h
@@ -33,10 +33,10 @@
 #include "i-interactive-state-access.h"
 #include "i-state-access.h"
 #include "interpret.h"
-#include "machine-state.h"
 #include "machine.h"
 #include "os.h"
 #include "pmas-constants.h"
+#include "processor-state.h"
 #include "riscv-constants.h"
 #include "shadow-tlb.h"
 #include "strict-aliasing.h"
@@ -77,44 +77,44 @@ class state_access :
     friend i_state_access<state_access>;
 
     uint64_t do_read_x(int i) const {
-        return m_m.get_state().registers.x[i];
+        return m_m.get_state().shadow.registers.x[i];
     }
 
     void do_write_x(int i, uint64_t val) const {
         assert(i != 0);
-        m_m.get_state().registers.x[i] = val;
+        m_m.get_state().shadow.registers.x[i] = val;
     }
 
     uint64_t do_read_f(int i) const {
-        return m_m.get_state().registers.f[i];
+        return m_m.get_state().shadow.registers.f[i];
     }
 
     void do_write_f(int i, uint64_t val) const {
-        m_m.get_state().registers.f[i] = val;
+        m_m.get_state().shadow.registers.f[i] = val;
     }
 
     uint64_t do_read_pc() const {
-        return m_m.get_state().registers.pc;
+        return m_m.get_state().shadow.registers.pc;
     }
 
     void do_write_pc(uint64_t val) const {
-        m_m.get_state().registers.pc = val;
+        m_m.get_state().shadow.registers.pc = val;
     }
 
     uint64_t do_read_fcsr() const {
-        return m_m.get_state().registers.fcsr;
+        return m_m.get_state().shadow.registers.fcsr;
     }
 
     void do_write_fcsr(uint64_t val) const {
-        m_m.get_state().registers.fcsr = val;
+        m_m.get_state().shadow.registers.fcsr = val;
     }
 
     uint64_t do_read_icycleinstret() const {
-        return m_m.get_state().registers.icycleinstret;
+        return m_m.get_state().shadow.registers.icycleinstret;
     }
 
     void do_write_icycleinstret(uint64_t val) const {
-        m_m.get_state().registers.icycleinstret = val;
+        m_m.get_state().shadow.registers.icycleinstret = val;
     }
 
     uint64_t do_read_mvendorid() const { // NOLINT(readability-convert-member-functions-to-static)
@@ -130,279 +130,279 @@ class state_access :
     }
 
     uint64_t do_read_mcycle() const {
-        return m_m.get_state().registers.mcycle;
+        return m_m.get_state().shadow.registers.mcycle;
     }
 
     void do_write_mcycle(uint64_t val) const {
-        m_m.get_state().registers.mcycle = val;
+        m_m.get_state().shadow.registers.mcycle = val;
     }
 
     uint64_t do_read_mstatus() const {
-        return m_m.get_state().registers.mstatus;
+        return m_m.get_state().shadow.registers.mstatus;
     }
 
     void do_write_mstatus(uint64_t val) const {
-        m_m.get_state().registers.mstatus = val;
+        m_m.get_state().shadow.registers.mstatus = val;
     }
 
     uint64_t do_read_menvcfg() const {
-        return m_m.get_state().registers.menvcfg;
+        return m_m.get_state().shadow.registers.menvcfg;
     }
 
     void do_write_menvcfg(uint64_t val) const {
-        m_m.get_state().registers.menvcfg = val;
+        m_m.get_state().shadow.registers.menvcfg = val;
     }
 
     uint64_t do_read_mtvec() const {
-        return m_m.get_state().registers.mtvec;
+        return m_m.get_state().shadow.registers.mtvec;
     }
 
     void do_write_mtvec(uint64_t val) const {
-        m_m.get_state().registers.mtvec = val;
+        m_m.get_state().shadow.registers.mtvec = val;
     }
 
     uint64_t do_read_mscratch() const {
-        return m_m.get_state().registers.mscratch;
+        return m_m.get_state().shadow.registers.mscratch;
     }
 
     void do_write_mscratch(uint64_t val) const {
-        m_m.get_state().registers.mscratch = val;
+        m_m.get_state().shadow.registers.mscratch = val;
     }
 
     uint64_t do_read_mepc() const {
-        return m_m.get_state().registers.mepc;
+        return m_m.get_state().shadow.registers.mepc;
     }
 
     void do_write_mepc(uint64_t val) const {
-        m_m.get_state().registers.mepc = val;
+        m_m.get_state().shadow.registers.mepc = val;
     }
 
     uint64_t do_read_mcause() const {
-        return m_m.get_state().registers.mcause;
+        return m_m.get_state().shadow.registers.mcause;
     }
 
     void do_write_mcause(uint64_t val) const {
-        m_m.get_state().registers.mcause = val;
+        m_m.get_state().shadow.registers.mcause = val;
     }
 
     uint64_t do_read_mtval() const {
-        return m_m.get_state().registers.mtval;
+        return m_m.get_state().shadow.registers.mtval;
     }
 
     void do_write_mtval(uint64_t val) const {
-        m_m.get_state().registers.mtval = val;
+        m_m.get_state().shadow.registers.mtval = val;
     }
 
     uint64_t do_read_misa() const {
-        return m_m.get_state().registers.misa;
+        return m_m.get_state().shadow.registers.misa;
     }
 
     void do_write_misa(uint64_t val) const {
-        m_m.get_state().registers.misa = val;
+        m_m.get_state().shadow.registers.misa = val;
     }
 
     uint64_t do_read_mie() const {
-        return m_m.get_state().registers.mie;
+        return m_m.get_state().shadow.registers.mie;
     }
 
     void do_write_mie(uint64_t val) const {
-        m_m.get_state().registers.mie = val;
+        m_m.get_state().shadow.registers.mie = val;
     }
 
     uint64_t do_read_mip() const {
-        return m_m.get_state().registers.mip;
+        return m_m.get_state().shadow.registers.mip;
     }
 
     void do_write_mip(uint64_t val) const {
-        m_m.get_state().registers.mip = val;
+        m_m.get_state().shadow.registers.mip = val;
     }
 
     uint64_t do_read_medeleg() const {
-        return m_m.get_state().registers.medeleg;
+        return m_m.get_state().shadow.registers.medeleg;
     }
 
     void do_write_medeleg(uint64_t val) const {
-        m_m.get_state().registers.medeleg = val;
+        m_m.get_state().shadow.registers.medeleg = val;
     }
 
     uint64_t do_read_mideleg() const {
-        return m_m.get_state().registers.mideleg;
+        return m_m.get_state().shadow.registers.mideleg;
     }
 
     void do_write_mideleg(uint64_t val) const {
-        m_m.get_state().registers.mideleg = val;
+        m_m.get_state().shadow.registers.mideleg = val;
     }
 
     uint64_t do_read_mcounteren() const {
-        return m_m.get_state().registers.mcounteren;
+        return m_m.get_state().shadow.registers.mcounteren;
     }
 
     void do_write_mcounteren(uint64_t val) const {
-        m_m.get_state().registers.mcounteren = val;
+        m_m.get_state().shadow.registers.mcounteren = val;
     }
 
     uint64_t do_read_senvcfg() const {
-        return m_m.get_state().registers.senvcfg;
+        return m_m.get_state().shadow.registers.senvcfg;
     }
 
     void do_write_senvcfg(uint64_t val) const {
-        m_m.get_state().registers.senvcfg = val;
+        m_m.get_state().shadow.registers.senvcfg = val;
     }
 
     uint64_t do_read_stvec() const {
-        return m_m.get_state().registers.stvec;
+        return m_m.get_state().shadow.registers.stvec;
     }
 
     void do_write_stvec(uint64_t val) const {
-        m_m.get_state().registers.stvec = val;
+        m_m.get_state().shadow.registers.stvec = val;
     }
 
     uint64_t do_read_sscratch() const {
-        return m_m.get_state().registers.sscratch;
+        return m_m.get_state().shadow.registers.sscratch;
     }
 
     void do_write_sscratch(uint64_t val) const {
-        m_m.get_state().registers.sscratch = val;
+        m_m.get_state().shadow.registers.sscratch = val;
     }
 
     uint64_t do_read_sepc() const {
-        return m_m.get_state().registers.sepc;
+        return m_m.get_state().shadow.registers.sepc;
     }
 
     void do_write_sepc(uint64_t val) const {
-        m_m.get_state().registers.sepc = val;
+        m_m.get_state().shadow.registers.sepc = val;
     }
 
     uint64_t do_read_scause() const {
-        return m_m.get_state().registers.scause;
+        return m_m.get_state().shadow.registers.scause;
     }
 
     void do_write_scause(uint64_t val) const {
-        m_m.get_state().registers.scause = val;
+        m_m.get_state().shadow.registers.scause = val;
     }
 
     uint64_t do_read_stval() const {
-        return m_m.get_state().registers.stval;
+        return m_m.get_state().shadow.registers.stval;
     }
 
     void do_write_stval(uint64_t val) const {
-        m_m.get_state().registers.stval = val;
+        m_m.get_state().shadow.registers.stval = val;
     }
 
     uint64_t do_read_satp() const {
-        return m_m.get_state().registers.satp;
+        return m_m.get_state().shadow.registers.satp;
     }
 
     void do_write_satp(uint64_t val) const {
-        m_m.get_state().registers.satp = val;
+        m_m.get_state().shadow.registers.satp = val;
     }
 
     uint64_t do_read_scounteren() const {
-        return m_m.get_state().registers.scounteren;
+        return m_m.get_state().shadow.registers.scounteren;
     }
 
     void do_write_scounteren(uint64_t val) const {
-        m_m.get_state().registers.scounteren = val;
+        m_m.get_state().shadow.registers.scounteren = val;
     }
 
     uint64_t do_read_ilrsc() const {
-        return m_m.get_state().registers.ilrsc;
+        return m_m.get_state().shadow.registers.ilrsc;
     }
 
     void do_write_ilrsc(uint64_t val) const {
-        m_m.get_state().registers.ilrsc = val;
+        m_m.get_state().shadow.registers.ilrsc = val;
     }
 
     uint64_t do_read_iprv() const {
-        return m_m.get_state().registers.iprv;
+        return m_m.get_state().shadow.registers.iprv;
     }
 
     void do_write_iprv(uint64_t val) const {
-        m_m.get_state().registers.iprv = val;
+        m_m.get_state().shadow.registers.iprv = val;
     }
 
     uint64_t do_read_iflags_X() const {
-        return m_m.get_state().registers.iflags.X;
+        return m_m.get_state().shadow.registers.iflags.X;
     }
 
     void do_write_iflags_X(uint64_t val) const {
-        m_m.get_state().registers.iflags.X = val;
+        m_m.get_state().shadow.registers.iflags.X = val;
     }
 
     uint64_t do_read_iflags_Y() const {
-        return m_m.get_state().registers.iflags.Y;
+        return m_m.get_state().shadow.registers.iflags.Y;
     }
 
     void do_write_iflags_Y(uint64_t val) const {
-        m_m.get_state().registers.iflags.Y = val;
+        m_m.get_state().shadow.registers.iflags.Y = val;
     }
 
     uint64_t do_read_iflags_H() const {
-        return m_m.get_state().registers.iflags.H;
+        return m_m.get_state().shadow.registers.iflags.H;
     }
 
     void do_write_iflags_H(uint64_t val) const {
-        m_m.get_state().registers.iflags.H = val;
+        m_m.get_state().shadow.registers.iflags.H = val;
     }
 
     uint64_t do_read_iunrep() const {
-        return m_m.get_state().registers.iunrep;
+        return m_m.get_state().shadow.registers.iunrep;
     }
 
     void do_write_iunrep(uint64_t val) const {
-        m_m.get_state().registers.iunrep = val;
+        m_m.get_state().shadow.registers.iunrep = val;
     }
 
     uint64_t do_read_clint_mtimecmp() const {
-        return m_m.get_state().registers.clint.mtimecmp;
+        return m_m.get_state().shadow.registers.clint.mtimecmp;
     }
 
     void do_write_clint_mtimecmp(uint64_t val) const {
-        m_m.get_state().registers.clint.mtimecmp = val;
+        m_m.get_state().shadow.registers.clint.mtimecmp = val;
     }
 
     uint64_t do_read_plic_girqpend() const {
-        return m_m.get_state().registers.plic.girqpend;
+        return m_m.get_state().shadow.registers.plic.girqpend;
     }
 
     void do_write_plic_girqpend(uint64_t val) const {
-        m_m.get_state().registers.plic.girqpend = val;
+        m_m.get_state().shadow.registers.plic.girqpend = val;
     }
 
     uint64_t do_read_plic_girqsrvd() const {
-        return m_m.get_state().registers.plic.girqsrvd;
+        return m_m.get_state().shadow.registers.plic.girqsrvd;
     }
 
     void do_write_plic_girqsrvd(uint64_t val) const {
-        m_m.get_state().registers.plic.girqsrvd = val;
+        m_m.get_state().shadow.registers.plic.girqsrvd = val;
     }
 
     uint64_t do_read_htif_fromhost() const {
-        return m_m.get_state().registers.htif.fromhost;
+        return m_m.get_state().shadow.registers.htif.fromhost;
     }
 
     void do_write_htif_fromhost(uint64_t val) const {
-        m_m.get_state().registers.htif.fromhost = val;
+        m_m.get_state().shadow.registers.htif.fromhost = val;
     }
 
     uint64_t do_read_htif_tohost() const {
-        return m_m.get_state().registers.htif.tohost;
+        return m_m.get_state().shadow.registers.htif.tohost;
     }
 
     void do_write_htif_tohost(uint64_t val) const {
-        m_m.get_state().registers.htif.tohost = val;
+        m_m.get_state().shadow.registers.htif.tohost = val;
     }
 
     uint64_t do_read_htif_ihalt() const {
-        return m_m.get_state().registers.htif.ihalt;
+        return m_m.get_state().shadow.registers.htif.ihalt;
     }
 
     uint64_t do_read_htif_iconsole() const {
-        return m_m.get_state().registers.htif.iconsole;
+        return m_m.get_state().shadow.registers.htif.iconsole;
     }
 
     uint64_t do_read_htif_iyield() const {
-        return m_m.get_state().registers.htif.iyield;
+        return m_m.get_state().shadow.registers.htif.iyield;
     }
 
     bool do_read_memory(uint64_t paddr, unsigned char *data, uint64_t length) const {
@@ -458,17 +458,17 @@ class state_access :
 
     template <TLB_set_index SET>
     uint64_t do_read_tlb_vaddr_page(uint64_t slot_index) const {
-        return m_m.get_state().tlb.hot[SET][slot_index].vaddr_page;
+        return m_m.get_state().penumbra.tlb[SET][slot_index].vaddr_page;
     }
 
     template <TLB_set_index SET>
-    host_addr do_read_tlb_vp_offset(uint64_t slot_index) const {
-        return m_m.get_state().tlb.hot[SET][slot_index].vh_offset;
+    host_addr do_read_tlb_vf_offset(uint64_t slot_index) const {
+        return m_m.get_state().penumbra.tlb[SET][slot_index].vh_offset;
     }
 
     template <TLB_set_index SET>
     uint64_t do_read_tlb_pma_index(uint64_t slot_index) const {
-        return m_m.get_state().tlb.cold[SET][slot_index].pma_index;
+        return m_m.get_state().shadow.tlb[SET][slot_index].pma_index;
     }
 
     template <TLB_set_index SET>
@@ -504,7 +504,7 @@ class state_access :
     }
 
     bool do_get_soft_yield() const {
-        return m_m.get_state().soft_yield;
+        return m_m.is_soft_yield();
     }
 
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
diff --git a/src/tlb.h b/src/tlb.h
deleted file mode 100644
index f78905b1d..000000000
--- a/src/tlb.h
+++ /dev/null
@@ -1,101 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef TLB_H
-#define TLB_H
-
-/// \file
-/// \brief TLB definitions
-/// \details The Translation Lookaside Buffer is a small cache used to speed up translation between address spaces.
-
-#include <array>
-#include <cstddef>
-#include <cstdint>
-
-#include "host-addr.h"
-#include "pmas-constants.h"
-#include "riscv-constants.h"
-
-namespace cartesi {
-
-/// \brief Index of TLB set
-enum TLB_set_index : uint64_t { TLB_CODE, TLB_READ, TLB_WRITE, TLB_LAST_ = TLB_WRITE };
-
-/// \brief TLB constants.
-enum TLB_constants : uint64_t {
-    TLB_SET_SIZE = 256,
-    TLB_INVALID_PAGE = UINT64_C(-1),
-    TLB_INVALID_PMA_INDEX = UINT64_C(-1)
-};
-
-/// \brief TLB hot slot.
-/// \details
-/// Given a target virtual address vaddr within a page matching vaddr_page in TLB slot, the corresponding host address
-/// haddr = vaddr + vh_offset.
-struct tlb_hot_slot final {
-    uint64_t vaddr_page; ///< Target virtual address of start of page
-    host_addr vh_offset; ///< Offset from target virtual address in the same page to host address
-};
-
-using tlb_hot_set = std::array<tlb_hot_slot, TLB_SET_SIZE>;
-
-/// \brief TLB cold slot.
-/// \details
-/// The pma_index helps translate between target physical addresses and host addresses when needed.
-struct tlb_cold_slot final {
-    uint64_t pma_index; ///< Index of PMA where physical address falls
-};
-
-using tlb_cold_set = std::array<tlb_cold_slot, TLB_SET_SIZE>;
-
-/// \brief TLB state.
-struct tlb_state {
-    std::array<tlb_hot_set, TLB_LAST_ + 1> hot;
-    std::array<tlb_cold_set, TLB_LAST_ + 1> cold;
-};
-
-static_assert(sizeof(uint64_t) >= sizeof(uintptr_t), "TLB expects host pointer fit in 64 bits");
-//??D why?
-static_assert((sizeof(tlb_hot_slot) & (sizeof(tlb_hot_slot) - 1)) == 0, "TLB slot size must be a power of 2");
-static_assert((sizeof(tlb_cold_slot) & (sizeof(tlb_cold_slot) - 1)) == 0, "TLB slot size must be a power of 2");
-
-/// \brief Gets a TLB slot index for a page.
-/// \param vaddr Target virtual address.
-/// \returns TLB slot index.
-constexpr uint64_t tlb_slot_index(uint64_t vaddr) {
-    return (vaddr >> LOG2_PAGE_SIZE) & (TLB_SET_SIZE - 1);
-}
-
-/// \brief Checks for a TLB hit.
-/// \tparam T Type of access needed (uint8_t, uint16_t, uint32_t, uint64_t).
-/// \param slot_vaddr_page vaddr_page in TLB slot
-/// \param vaddr Target virtual address being looked up.
-/// \returns True on hit, false otherwise.
-template <typename T>
-constexpr bool tlb_is_hit(uint64_t slot_vaddr_page, uint64_t vaddr) {
-    // Make sure misaligned accesses are always considered a miss
-    // Otherwise, we could report a hit for a word that goes past the end of the page.
-    // Aligned accesses smaller than a page size cannot straddle two pages.
-    return slot_vaddr_page == (vaddr & ~(PAGE_OFFSET_MASK & ~(sizeof(T) - 1)));
-}
-
-constexpr uint64_t tlb_addr_page(uint64_t addr) {
-    return addr & ~PAGE_OFFSET_MASK;
-}
-
-} // namespace cartesi
-
-#endif
diff --git a/src/uarch-state.h b/src/uarch-processor-state.h
similarity index 64%
rename from src/uarch-state.h
rename to src/uarch-processor-state.h
index 51bff79af..f23374a37 100644
--- a/src/uarch-state.h
+++ b/src/uarch-processor-state.h
@@ -14,11 +14,11 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#ifndef UARCH_STATE_H
-#define UARCH_STATE_H
+#ifndef UARCH_PROCESSOR_STATE_H
+#define UARCH_PROCESSOR_STATE_H
 
 /// \file
-/// \brief Cartesi microarchitecture machine state structure definition.
+/// \brief Cartesi microarchitecture machine processor state structure definition.
 
 #include <array>
 #include <cstdint>
@@ -30,20 +30,13 @@
 
 namespace cartesi {
 
-struct uarch_state final {
-    uarch_state() = default;
-    ~uarch_state() = default;
-
-    /// \brief No copy or move constructor or assignment
-    uarch_state(const uarch_state &other) = delete;
-    uarch_state(uarch_state &&other) = delete;
-    uarch_state &operator=(const uarch_state &other) = delete;
-    uarch_state &operator=(uarch_state &&other) = delete;
-
-    // Shadow region.
-    uarch_registers_state registers; ///< Uarch registers
+struct uarch_processor_state final {
+    uarch_registers_state registers;    ///< Uarch registers
+    uint64_t registers_padding_[477]{}; ///< Padding to align next field to a page boundary
 };
 
+static_assert(sizeof(uarch_processor_state) % 4096 == 0, "machine state size must be multiple of a page size");
+
 } // namespace cartesi
 
 #endif
diff --git a/src/uarch-record-state-access.h b/src/uarch-record-state-access.h
index 498c4681f..d56c07e4b 100644
--- a/src/uarch-record-state-access.h
+++ b/src/uarch-record-state-access.h
@@ -41,7 +41,7 @@
 #include "uarch-constants.h"
 #include "uarch-pristine-state-hash.h"
 #include "uarch-pristine.h"
-#include "uarch-state.h"
+#include "uarch-processor-state.h"
 
 namespace cartesi {
 
diff --git a/src/unique-c-ptr.h b/src/unique-c-ptr.h
index 965ab7523..4feb149d7 100644
--- a/src/unique-c-ptr.h
+++ b/src/unique-c-ptr.h
@@ -48,15 +48,6 @@ struct fclose_deleter {
     }
 };
 
-struct mmap_deleter {
-    size_t m_size;
-    explicit mmap_deleter(size_t size) : m_size(size) {};
-    template <typename T>
-    void operator()(T *ptr) const {
-        os_unmap_file(ptr, m_size);
-    }
-};
-
 } // namespace detail
 
 template <typename T>
@@ -64,9 +55,6 @@ using unique_calloc_ptr = std::unique_ptr<T, detail::free_deleter>;
 
 using unique_file_ptr = std::unique_ptr<FILE, detail::fclose_deleter>;
 
-template <typename T>
-using unique_mmap_ptr = std::unique_ptr<T, detail::mmap_deleter>;
-
 template <typename T>
 static inline auto make_unique_calloc(size_t nmemb) {
     // NOLINTNEXTLINE(cppcoreguidelines-no-malloc,hicpp-no-malloc)
@@ -96,13 +84,6 @@ static inline auto make_unique_fopen(const char *pathname, const char *mode, con
     return unique_file_ptr{fopen(pathname, mode)};
 }
 
-template <typename T>
-static inline auto make_unique_mmap(const char *pathname, size_t nmemb, bool shared) {
-    const size_t size = nmemb * sizeof(T);
-    T *ptr = static_cast<T *>(os_map_file(pathname, size, shared)); // os_map_file throws on error
-    return unique_mmap_ptr<T>(ptr, detail::mmap_deleter{size});
-}
-
 template <typename T>
 static auto inline make_moved_unique(T &&t)
     requires std::is_rvalue_reference_v<T &&>
diff --git a/tests/lua/machine-bind.lua b/tests/lua/machine-bind.lua
index 2f4870d2c..9889c7037 100755
--- a/tests/lua/machine-bind.lua
+++ b/tests/lua/machine-bind.lua
@@ -373,7 +373,6 @@ local function test_config(config)
         "ram",
         "dtb",
         "flash_drive",
-        "tlb",
         "virtio",
         "cmio",
         "pmas",
@@ -442,13 +441,14 @@ local function test_config(config)
     assertfield(config, "dtb.init", "string")
     assertfield(config, "dtb.entrypoint", "string")
     test_backing_store_config(config, "dtb.backing_store")
-    test_backing_store_config(config, "tlb.backing_store")
+    test_backing_store_config(config, "processor.backing_store")
     test_backing_store_config(config, "pmas.backing_store")
     for i, f in ipairs(config.flash_drive or {}) do
         test_flash_drive_config(f, "config.flash_drive[" .. i .. "]")
     end
     test_backing_store_config(config, "cmio.rx_buffer.backing_store")
     test_backing_store_config(config, "cmio.tx_buffer.backing_store")
+    test_backing_store_config(config, "uarch.processor.backing_store")
     test_backing_store_config(config, "uarch.ram.backing_store")
     assertfield(config, "hash_tree.shared", "boolean")
     assertfield(config, "hash_tree.truncate", "boolean")
diff --git a/tests/misc/test-machine-c-api.cpp b/tests/misc/test-machine-c-api.cpp
index 6e92c4efe..710f03e02 100644
--- a/tests/misc/test-machine-c-api.cpp
+++ b/tests/misc/test-machine-c-api.cpp
@@ -162,7 +162,9 @@ class machine_flash_simple_fixture : public incomplete_machine_fixture {
 public:
     machine_flash_simple_fixture() {
         _machine_config["flash_drive"] = {{{"start", 0x80000000000000}, {"length", 0x3c00000}, {"read_only", false},
-            {"backing_store", {{"shared", false}, {"truncate", false}, {"data_filename", ""}, {"dht_filename", ""}}}}};
+            {"backing_store",
+                {{"shared", false}, {"create", false}, {"truncate", false}, {"data_filename", ""},
+                    {"dht_filename", ""}}}}};
     }
 
     machine_flash_simple_fixture(const machine_flash_simple_fixture &other) = delete;
@@ -312,7 +314,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(store_machine_config_version_test, store_file_fix
     auto j = nlohmann::json::parse(ifs);
     BOOST_REQUIRE(j.contains("archive_version"));
     BOOST_REQUIRE(j["archive_version"].is_number_integer());
-    BOOST_CHECK_EQUAL(j["archive_version"].get<int>(), 5);
+    BOOST_CHECK_EQUAL(j["archive_version"].get<int>(), 6);
 }
 
 BOOST_FIXTURE_TEST_CASE_NOLINT(store_null_machine_test, ordinary_machine_fixture) {
@@ -534,14 +536,14 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(read_write_virtual_memory_null_data_test, ordinar
 
 BOOST_FIXTURE_TEST_CASE_NOLINT(write_memory_invalid_address_range_test, ordinary_machine_fixture) {
     uint64_t write_value = 0x1234;
-    uint64_t address = 0x100;
+    uint64_t address = 0x40008000; // HTIF
     std::array<uint8_t, sizeof(uint64_t)> write_data{};
     memcpy(write_data.data(), &write_value, write_data.size());
 
     cm_error error_code = cm_write_memory(_machine, address, write_data.data(), write_data.size());
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
     std::string result = cm_get_last_error_message();
-    std::string origin("address range to write is not entirely in single memory range");
+    std::string origin("attempted write to device memory range");
     BOOST_CHECK_EQUAL(origin, result);
 }
 
@@ -627,14 +629,14 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(read_write_memory_massive_test, ordinary_machine_
 
 BOOST_FIXTURE_TEST_CASE_NOLINT(write_virtual_memory_invalid_address_range_test, ordinary_machine_fixture) {
     uint64_t write_value = 0x1234;
-    uint64_t address = 0x100;
+    uint64_t address = 0x40008000; // HTIF
     std::array<uint8_t, sizeof(uint64_t)> write_data{};
     memcpy(write_data.data(), &write_value, write_data.size());
 
     cm_error error_code = cm_write_virtual_memory(_machine, address, write_data.data(), write_data.size());
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
     std::string result = cm_get_last_error_message();
-    std::string origin("address range to write is not entirely in single memory range");
+    std::string origin("attempted write to device memory range");
     BOOST_CHECK_EQUAL(origin, result);
 }
 
diff --git a/uarch/compute-uarch-pristine-hash.cpp b/uarch/compute-uarch-pristine-hash.cpp
index 87ed4f92e..d3d0edca9 100644
--- a/uarch/compute-uarch-pristine-hash.cpp
+++ b/uarch/compute-uarch-pristine-hash.cpp
@@ -22,7 +22,7 @@
 #include <shadow-uarch-state.h>
 #include <uarch-constants.h>
 #include <uarch-pristine.h>
-#include <uarch-state.h>
+#include <uarch-processor-state.h>
 #include <unique-c-ptr.h>
 
 /// \file
diff --git a/uarch/machine-uarch-bridge-state-access.h b/uarch/machine-uarch-bridge-state-access.h
index 65230497e..40adec521 100644
--- a/uarch/machine-uarch-bridge-state-access.h
+++ b/uarch/machine-uarch-bridge-state-access.h
@@ -88,11 +88,11 @@ class machine_uarch_bridge_state_access :
     // -----
     friend i_prefer_shadow_state<machine_uarch_bridge_state_access>;
 
-    uint64_t do_read_shadow_state(shadow_state_what what) const {
+    uint64_t do_read_shadow_register(shadow_registers_what what) const {
         return bridge_read_reg(machine_reg_enum(what));
     }
 
-    void do_write_shadow_state(shadow_state_what what, uint64_t val) const {
+    void do_write_shadow_register(shadow_registers_what what, uint64_t val) const {
         bridge_write_reg(machine_reg_enum(what), val);
     }
 
@@ -151,7 +151,7 @@ class machine_uarch_bridge_state_access :
     }
 
     template <TLB_set_index SET>
-    uint64_t do_read_tlb_vp_offset(uint64_t slot_index) const {
+    uint64_t do_read_tlb_vf_offset(uint64_t slot_index) const {
         return bridge_read_shadow_tlb(SET, slot_index, shadow_tlb_what::vp_offset);
     }
 

From 01bfbacb940ea3815c94baaca6592364aa2698c3 Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Fri, 14 Mar 2025 17:45:32 +0000
Subject: [PATCH 36/82] refactor: new merkle tree implementation

---
 .clang-tidy                              |   1 +
 .github/workflows/build.yml              |   4 +-
 Dockerfile                               |   2 +-
 README.md                                |   6 +-
 src/Makefile                             |  12 +-
 src/access-log.h                         |  32 +-
 src/address-range-constants.h            |   4 +-
 src/address-range-defines.h              |   2 +-
 src/address-range.h                      | 179 +++--
 src/back-merkle-tree.cpp                 |  24 +-
 src/back-merkle-tree.h                   |  92 +--
 src/base64.cpp                           |  32 +-
 src/base64.h                             |  43 +-
 src/cartesi-machine.lua                  |  18 +-
 src/circular-buffer.h                    | 406 +++++++++++
 src/clint-address-range.h                |   6 +-
 src/clua-cartesi.cpp                     |  18 +-
 src/clua-i-machine.cpp                   | 148 ++--
 src/complete-merkle-tree.cpp             |  14 +-
 src/complete-merkle-tree.h               |  21 +-
 src/concepts.h                           |  58 ++
 src/dense-hash-tree.h                    | 108 +++
 src/dirty-page-tree.h                    | 334 +++++++++
 src/full-merkle-tree.cpp                 |  18 +-
 src/full-merkle-tree.h                   |  30 +-
 src/hash-tree-constants.h                |  32 +
 src/hash-tree.cpp                        | 845 +++++++++++++++++++++++
 src/hash-tree.h                          | 191 +++++
 src/htif-address-range.h                 |   6 +-
 src/i-dense-hash-tree.h                  |  73 ++
 src/i-dirty-page-tree.h                  | 358 ++++++++++
 src/i-hasher.h                           | 128 ++--
 src/i-machine.h                          |  61 +-
 src/is-pristine.h                        |  25 +-
 src/json-util.cpp                        |  91 ++-
 src/json-util.h                          |  48 +-
 src/jsonrpc-discover.json                |  20 +-
 src/jsonrpc-machine.cpp                  |  60 +-
 src/jsonrpc-machine.h                    |  24 +-
 src/jsonrpc-remote-machine.cpp           |  77 +--
 src/keccak-256-hasher.h                  |  21 +-
 src/local-machine.cpp                    |  33 +-
 src/local-machine.h                      |  25 +-
 src/machine-address-ranges.cpp           | 108 +--
 src/machine-address-ranges.h             |  65 +-
 src/machine-c-api.cpp                    | 111 +--
 src/machine-c-api.h                      |  20 +-
 src/machine-config.cpp                   |  10 +-
 src/machine-config.h                     |  19 +-
 src/machine-hash.h                       |  35 +
 src/machine-merkle-tree.cpp              | 471 -------------
 src/machine-merkle-tree.h                | 368 ----------
 src/machine-runtime-config.h             |   2 +-
 src/machine.cpp                          | 440 ++++--------
 src/machine.h                            |  83 ++-
 src/memory-address-range.cpp             |  49 +-
 src/memory-address-range.h               | 105 ++-
 src/merkle-tree-hash.cpp                 |  22 +-
 src/merkle-tree-proof.h                  |  87 +--
 src/meta.h                               |   3 +
 src/page-hash-tree-cache.h               | 435 ++++++++++++
 src/plic-address-range.h                 |   6 +-
 src/pristine-address-range.h             |  59 --
 src/pristine-merkle-tree.cpp             |   4 +-
 src/pristine-merkle-tree.h               |  14 +-
 src/ranges.h                             |  47 ++
 src/record-send-cmio-state-access.h      |  50 +-
 src/record-step-state-access.h           |  30 +-
 src/replay-send-cmio-state-access.h      |  57 +-
 src/replay-step-state-access-interop.cpp |  23 +-
 src/replay-step-state-access.h           |   6 +-
 src/send-cmio-response.cpp               |   6 +-
 src/state-access.h                       |   2 +-
 src/uarch-pristine-state-hash.cpp        |  10 +-
 src/uarch-pristine-state-hash.h          |   4 +-
 src/uarch-processor-state.h              |   2 +-
 src/uarch-record-state-access.h          |  35 +-
 src/uarch-replay-state-access.h          |  45 +-
 src/virtio-address-range.cpp             |   2 +-
 src/virtio-address-range.h               |   4 +-
 src/virtio-p9fs-address-range.cpp        |   2 +-
 tests/Makefile                           |   5 +-
 tests/lua/cartesi-machine-tests.lua      |  12 +-
 tests/lua/cmio-test.lua                  |   4 +-
 tests/lua/hash-tree.lua                  | 272 ++++++++
 tests/lua/machine-bind.lua               |  32 +-
 tests/lua/machine-test.lua               |  12 +-
 tests/misc/Makefile                      |   5 +-
 tests/misc/test-machine-c-api.cpp        |  74 +-
 tests/misc/test-merkle-tree-hash.cpp     |   5 +-
 tests/misc/test-utils.h                  |   9 +-
 tools/template/control.template          |   2 +-
 uarch/Makefile                           |   1 -
 uarch/compute-uarch-pristine-hash.cpp    |  74 +-
 94 files changed, 4580 insertions(+), 2498 deletions(-)
 create mode 100644 src/circular-buffer.h
 create mode 100644 src/concepts.h
 create mode 100644 src/dense-hash-tree.h
 create mode 100644 src/dirty-page-tree.h
 create mode 100644 src/hash-tree-constants.h
 create mode 100644 src/hash-tree.cpp
 create mode 100644 src/hash-tree.h
 create mode 100644 src/i-dense-hash-tree.h
 create mode 100644 src/i-dirty-page-tree.h
 create mode 100644 src/machine-hash.h
 delete mode 100644 src/machine-merkle-tree.cpp
 delete mode 100644 src/machine-merkle-tree.h
 create mode 100644 src/page-hash-tree-cache.h
 delete mode 100644 src/pristine-address-range.h
 create mode 100644 src/ranges.h
 create mode 100755 tests/lua/hash-tree.lua

diff --git a/.clang-tidy b/.clang-tidy
index c4a280dff..fdcbda1dd 100644
--- a/.clang-tidy
+++ b/.clang-tidy
@@ -42,6 +42,7 @@ Checks: >-
   -readability-identifier-length,
   -readability-magic-numbers,
   -readability-enum-initial-value,
+  -readability-static-accessed-through-instance,
 WarningsAsErrors: >-
   boost*,
   bugprone*,
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 62fe73d45..997fda5bf 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -227,7 +227,7 @@ jobs:
 
       - name: Run test suite with microarchitecture and host based interpreters comparing machine hashes at every step
         run: |
-          docker run --rm -t ${{ github.repository_owner }}/machine-emulator:tests cartesi-machine-tests --concurrency=update_merkle_tree:1 --test="^rv64ui.*$" --jobs=$(nproc) run_host_and_uarch
+          docker run --rm -t ${{ github.repository_owner }}/machine-emulator:tests cartesi-machine-tests --concurrency=update_hash_tree:1 --test="^rv64ui.*$" --jobs=$(nproc) run_host_and_uarch
 
       - name: Create uarch json logs to be used to test the Solidity based microarchitecture interpreter
         run: |
@@ -395,7 +395,7 @@ jobs:
 
       - name: Run test suite with microarchitecture and host based interpreters comparing machine hashes at every step
         run: |
-          docker run --platform linux/arm64 --rm -t ${{ github.repository_owner }}/machine-emulator:tests cartesi-machine-tests  --test="^rv64ui%-v%-add.bin$" --concurrency=update_merkle_tree:1 --jobs=$(nproc) run_host_and_uarch
+          docker run --platform linux/arm64 --rm -t ${{ github.repository_owner }}/machine-emulator:tests cartesi-machine-tests  --test="^rv64ui%-v%-add.bin$" --concurrency=update_hash_tree:1 --jobs=$(nproc) run_host_and_uarch
 
       - name: Build machine-emulator "tests" docker image
         uses: docker/build-push-action@v5
diff --git a/Dockerfile b/Dockerfile
index 90b21a40a..cbab55718 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -3,7 +3,7 @@ FROM debian:bookworm-20250407 AS toolchain
 RUN apt-get update && \
     DEBIAN_FRONTEND=noninteractive apt-get install --no-install-recommends -y \
         build-essential vim wget git lcov \
-        libboost1.81-dev libssl-dev libslirp-dev \
+        libomp-19-dev libboost1.81-dev libssl-dev libslirp-dev \
         ca-certificates pkg-config lua5.4 liblua5.4-dev \
         luarocks xxd procps \
         g++-12-riscv64-linux-gnu=12.2.0-13cross1 \
diff --git a/README.md b/README.md
index b6bc506cf..5739f7576 100644
--- a/README.md
+++ b/README.md
@@ -125,19 +125,19 @@ brew install cartesi-machine
 ###### Debian Requirements
 
 ```sh
-sudo apt-get install build-essential git wget libboost1.81-dev liblua5.4-dev libslirp-dev lua5.4
+sudo apt-get install build-essential git wget libgomp-dev libboost1.81-dev liblua5.4-dev libslirp-dev lua5.4
 ```
 
 ###### MacPorts Requirements
 
 ```sh
-sudo port install clang boost181 wget pkgconfig lua54 libslirp
+sudo port install clang libomp boost181 wget pkgconfig lua54 libslirp
 ```
 
 ###### Homebrew Requirements
 
 ```sh
-brew install llvm boost wget pkg-config lua libslirp
+brew install llvm libomp boost wget pkg-config lua libslirp
 ```
 
 #### Build
diff --git a/src/Makefile b/src/Makefile
index 03761c571..db2098986 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -61,8 +61,8 @@ PICCFLAGS=-fPIC
 SOLDFLAGS=-dynamiclib -undefined dynamic_lookup
 LIBLDFLAGS=-dynamiclib
 EXELDFLAGS=
-PTHREAD_CFLAGS=
-PTHREAD_LDFLAGS=-lpthread
+PTHREAD_CFLAGS=-I/opt/local/include/libomp -fopenmp
+PTHREAD_LDFLAGS=-L/opt/local/lib/libomp -lgomp
 CC=clang
 CXX=clang++
 AR=libtool -static -o
@@ -111,8 +111,8 @@ PICCFLAGS=-fPIC
 SOLDFLAGS=-shared $(PICCFLAGS) $(GCLDFLAGS)
 LIBLDFLAGS=$(SOLDFLAGS) -Wl,--no-undefined
 EXELDFLAGS=$(GCLDFLAGS) -Wl,--no-undefined
-PTHREAD_CFLAGS=-pthread
-PTHREAD_LDFLAGS=-pthread -lpthread
+PTHREAD_CFLAGS=-fopenmp
+PTHREAD_LDFLAGS=-fopenmp
 CC=gcc
 CXX=g++
 AR=ar rcs
@@ -176,6 +176,7 @@ DEFS+=-D_FILE_OFFSET_BITS=64
 DEFS+=-DJSON_HAS_FILESYSTEM=0
 
 ifeq ($(dump),yes)
+DUMP_DEFS+=-DDUMP_HASH_TREE_STATS
 DUMP_DEFS+=-DDUMP_ILLEGAL_INSN_EXCEPTIONS
 DUMP_DEFS+=-DDUMP_EXCEPTIONS
 DUMP_DEFS+=-DDUMP_INTERRUPTS
@@ -354,12 +355,12 @@ LIBCARTESI_OBJS:= \
 	base64.o \
 	clint-address-range.o \
 	dtb.o \
+	hash-tree.o \
 	htif-address-range.o \
 	interpret.o \
 	json-util.o \
 	machine-c-api.o \
 	machine-config.o \
-	machine-merkle-tree.o \
 	machine.o \
 	machine-address-ranges.o \
 	memory-address-range.o \
@@ -397,7 +398,6 @@ LUACARTESI_OBJS:= \
 
 LIBCARTESI_MERKLE_TREE_OBJS:= \
 	sha3.o \
-	machine-merkle-tree.o \
 	back-merkle-tree.o \
 	pristine-merkle-tree.o \
 	complete-merkle-tree.o \
diff --git a/src/access-log.h b/src/access-log.h
index 7e5e45c9c..26cbcb5ad 100644
--- a/src/access-log.h
+++ b/src/access-log.h
@@ -33,8 +33,9 @@
 #include <boost/container/small_vector.hpp>
 
 #include "bracket-note.h"
+#include "hash-tree.h"
 #include "machine-c-api.h"
-#include "machine-merkle-tree.h"
+#include "machine-hash.h"
 #include "strict-aliasing.h"
 
 namespace cartesi {
@@ -67,12 +68,9 @@ static inline uint64_t get_word_access_data(const access_data &ad, uint64_t offs
 /// \brief Records an access to the machine state
 class access {
 
-    using hasher_type = machine_merkle_tree::hasher_type;
-
 public:
-    using hash_type = machine_merkle_tree::hash_type;
-    using sibling_hashes_type = std::vector<hash_type>;
-    using proof_type = machine_merkle_tree::proof_type;
+    using proof_type = hash_tree::proof_type;
+    using sibling_hashes_type = hash_tree::sibling_hashes_type;
 
     void set_type(access_type type) {
         m_type = type;
@@ -143,43 +141,43 @@ class access {
 
     /// \brief Sets hash of data that was written at address after access.
     /// \param hash Hash of new data at address.
-    void set_written_hash(const hash_type &hash) {
+    void set_written_hash(const machine_hash &hash) {
         m_written_hash = hash;
     }
 
     /// \brief Gets hash of data that was written at address after access.
     /// \returns Hash of written data at address.
-    const std::optional<hash_type> &get_written_hash() const {
+    const std::optional<machine_hash> &get_written_hash() const {
         return m_written_hash;
     }
-    std::optional<hash_type> &get_written_hash() {
+    std::optional<machine_hash> &get_written_hash() {
         return m_written_hash;
     }
 
     /// \brief Sets hash of data that can be read at address before access.
     /// \param hash Hash of data at address.
-    void set_read_hash(const hash_type &hash) {
+    void set_read_hash(const machine_hash &hash) {
         m_read_hash = hash;
     }
 
     /// \brief Gets hash of data that can be read at address before access.
     /// \returns Hash of data at address.
-    const hash_type &get_read_hash() const {
+    const machine_hash &get_read_hash() const {
         return m_read_hash;
     }
-    hash_type &get_read_hash() {
+    machine_hash &get_read_hash() {
         return m_read_hash;
     }
 
     /// \brief Constructs a proof using this access' data and a given root hash.
     /// \param root_hash Hash to be used as the root of the proof.
     /// \return The corresponding proof
-    proof_type make_proof(const hash_type root_hash) const {
+    proof_type make_proof(const machine_hash root_hash) const {
         // the access can be of data smaller than the merkle tree word size
         // however, the proof must be at least as big as the merkle tree word size
-        const int proof_log2_size = std::max(m_log2_size, machine_merkle_tree::get_log2_word_size());
+        const int proof_log2_size = std::max(m_log2_size, HASH_TREE_LOG2_WORD_SIZE);
         // the proof address is the access address aligned to the merkle tree word size
-        const uint64_t proof_address = m_address & ~(machine_merkle_tree::get_word_size() - 1);
+        const uint64_t proof_address = m_address & ~(HASH_TREE_WORD_SIZE - 1);
         if (!m_sibling_hashes.has_value()) {
             throw std::runtime_error("can't make proof if access doesn't have sibling hashes");
         }
@@ -218,9 +216,9 @@ class access {
     uint64_t m_address{0};                               ///< Address of access
     int m_log2_size{0};                                  ///< Log2 of size of access
     std::optional<access_data> m_read;                   ///< Data before access
-    hash_type m_read_hash{};                             ///< Hash of data before access
+    machine_hash m_read_hash{};                          ///< Hash of data before access
     std::optional<access_data> m_written;                ///< Written data
-    std::optional<hash_type> m_written_hash;             ///< Hash of written data
+    std::optional<machine_hash> m_written_hash;          ///< Hash of written data
     std::optional<sibling_hashes_type> m_sibling_hashes; ///< Hashes of siblings in path from address to root
 };
 
diff --git a/src/address-range-constants.h b/src/address-range-constants.h
index 77f07e279..0d021cbc0 100644
--- a/src/address-range-constants.h
+++ b/src/address-range-constants.h
@@ -69,8 +69,8 @@ static_assert(AR_SHADOW_STATE_START == AR_SHADOW_REGISTERS_START);
 
 /// \brief PMA constants.
 enum AR_constants : uint64_t {
-    AR_PAGE_SIZE_LOG2 = EXPAND_UINT64_C(AR_PAGE_SIZE_LOG2_DEF), ///< Log<sub>2</sub> of physical memory page size.
-    AR_PAGE_SIZE = (UINT64_C(1) << AR_PAGE_SIZE_LOG2_DEF),      ///< Physical memory page size.
+    AR_LOG2_PAGE_SIZE = EXPAND_UINT64_C(AR_LOG2_PAGE_SIZE_DEF), ///< Log<sub>2</sub> of physical memory page size.
+    AR_PAGE_SIZE = (UINT64_C(1) << AR_LOG2_PAGE_SIZE_DEF),      ///< Physical memory page size.
 };
 
 /// \brief PMA masks.
diff --git a/src/address-range-defines.h b/src/address-range-defines.h
index dd89cc9a9..4bf43c51b 100644
--- a/src/address-range-defines.h
+++ b/src/address-range-defines.h
@@ -50,7 +50,7 @@
 
 #define AR_RAM_START_DEF 0x80000000 ///< RAM start address
 
-#define AR_PAGE_SIZE_LOG2_DEF 12 ///< log<sub>2</sub> of physical memory page size.
+#define AR_LOG2_PAGE_SIZE_DEF 12 ///< log<sub>2</sub> of physical memory page size.
 
 // helper for using UINT64_C with defines
 #ifndef EXPAND_UINT64_C
diff --git a/src/address-range.h b/src/address-range.h
index fc53811d1..0865f0617 100644
--- a/src/address-range.h
+++ b/src/address-range.h
@@ -22,16 +22,19 @@
 #include <cinttypes>
 #include <cstdint>
 #include <tuple>
+#include <utility>
 
 #include "assert-printf.h"
 #include "i-device-state-access.h"
 #include "interpret.h"
 #include "pmas.h"
 
-namespace cartesi {
+#ifndef MICROARCHITECTURE
+#include "i-dense-hash-tree.h"
+#include "i-dirty-page-tree.h"
+#endif
 
-// Forward declarations
-class machine;
+namespace cartesi {
 
 /// \file
 /// \brief Physical address range
@@ -59,10 +62,6 @@ class address_range {
         }
     }
 
-    address_range(const address_range &other) = default;
-    address_range &operator=(const address_range &other) = default;
-    address_range(address_range &&other) = default;
-    address_range &operator=(address_range &&other) = default;
     // NOLINTNEXTLINE(hicpp-use-equals-default,modernize-use-equals-default)
     constexpr virtual ~address_range() {}; // = default; // doesn't work due to bug in gcc
 
@@ -82,7 +81,8 @@ class address_range {
     /// \param length Length of range, in bytes
     /// \param f Physical memory attribute flags for range
     template <typename ABRT>
-    address_range(const char *description, uint64_t start, uint64_t length, const pmas_flags &flags, ABRT abrt) :
+    constexpr address_range(const char *description, uint64_t start, uint64_t length, const pmas_flags &flags,
+        ABRT abrt) :
         m_description{},
         m_start{start},
         m_end{start + length},
@@ -119,11 +119,16 @@ class address_range {
         }
     }
 
+    address_range(const address_range &other) = default;
+    address_range &operator=(const address_range &other) = default;
+    address_range(address_range &&other) = default;
+    address_range &operator=(address_range &&other) = default;
+
     /// \brief Checks if a range of addresses is entirely contained within this range
     /// \param offset Start of range of interest, relative to start of this range
     /// \param length Length of range of interest, in bytes
     /// \returns True if and only if range of interest is entirely contained within this range
-    bool contains_relative(uint64_t offset, uint64_t length) const noexcept {
+    constexpr bool contains_relative(uint64_t offset, uint64_t length) const noexcept {
         return get_length() >= length && offset <= get_length() - length;
     }
 
@@ -131,94 +136,94 @@ class address_range {
     /// \param start Target phyisical address of start of range of interest
     /// \param length Length of range of interest, in bytes
     /// \returns True if and only if range of interest is entirely contained within this range
-    bool contains_absolute(uint64_t start, uint64_t length) const noexcept {
+    constexpr bool contains_absolute(uint64_t start, uint64_t length) const noexcept {
         return start >= get_start() && contains_relative(start - get_start(), length);
     }
 
     /// \brief Returns PMA flags used during construction
     /// \returns Flags
-    const pmas_flags &get_flags() const noexcept {
+    constexpr const pmas_flags &get_flags() const noexcept {
         return m_flags;
     }
 
     /// \brief Returns description of address range for use in error messages.
     /// \returns Description
-    const char *get_description() const noexcept {
+    constexpr const char *get_description() const noexcept {
         return m_description.data();
     }
 
     /// \brief Returns target physical address where range starts.
     /// \returns Start of range
-    uint64_t get_start() const noexcept {
+    constexpr uint64_t get_start() const noexcept {
         return m_start;
     }
 
     /// \brief Returns target physical address right past end of range.
     /// \returns End of range
-    uint64_t get_end() const noexcept {
+    constexpr uint64_t get_end() const noexcept {
         return m_end;
     }
 
     /// \brief Returns length of range, in bytes.
     /// \returns Length of range
-    uint64_t get_length() const noexcept {
+    constexpr uint64_t get_length() const noexcept {
         return m_end - m_start;
     }
 
     /// \brief Test if address range is occupied by memory
     /// \returns True if and only if range is occupied by memory
     /// \details In this case, get_host_memory() is guaranteed not to return nullptr.
-    bool is_memory() const noexcept {
+    constexpr bool is_memory() const noexcept {
         return m_flags.M;
     }
 
     /// \brief Test if address range is occupied by a device
     /// \returns True if and only if range is occupied by a device
     /// \details In this case, read_device() and write_device() are operational.
-    bool is_device() const noexcept {
+    constexpr bool is_device() const noexcept {
         return m_flags.IO;
     }
 
     /// \brief Test if address range is empty
     /// \returns True if and only if range is empty
     /// \details Empty ranges should be used only for sentinels.
-    bool is_empty() const noexcept {
+    constexpr bool is_empty() const noexcept {
         return m_end == 0;
     }
 
     /// \brief Tests if range is readable
     /// \returns True if and only if range is readable from within the machine.
-    bool is_readable() const noexcept {
+    constexpr bool is_readable() const noexcept {
         return m_flags.R;
     }
 
     /// \brief Tests if range is writeable
     /// \returns True if and only if range is writeable from within the machine.
-    bool is_writeable() const noexcept {
+    constexpr bool is_writeable() const noexcept {
         return m_flags.W;
     }
 
     /// \brief Tests if range is executable
     /// \returns True if and only if range is executable from within the machine.
-    bool is_executable() const noexcept {
+    constexpr bool is_executable() const noexcept {
         return m_flags.X;
     }
 
     /// \brief Tests if range is read-idempotent
     /// \returns True if and only if what is read from range remains there until written to
-    bool is_read_idempotent() const noexcept {
+    constexpr bool is_read_idempotent() const noexcept {
         return m_flags.IR;
     }
 
     /// \brief Tests if range is write-idempotent
     /// \returns True if and only if what is written to range remains there and can be read until written to again
-    bool is_write_idempotent() const noexcept {
+    constexpr bool is_write_idempotent() const noexcept {
         return m_flags.IW;
     }
 
     /// \brief Returns driver ID associated to range
     /// \returns The driver ID
-    PMA_ISTART_DID get_driver_id() const noexcept {
+    constexpr PMA_ISTART_DID get_driver_id() const noexcept {
         return m_flags.DID;
     }
 
@@ -235,18 +240,32 @@ class address_range {
         return get_length();
     }
 
-    /// \brief Read contents from address range with, no side-effects.
-    /// \param m Reference to machine.
-    /// \param offset Offset within range to start reading.
-    /// \param length Number of bytes to read.
-    /// \param data Receives pointer to start of data, or nullptr if data is constant *and* pristine (filled with
-    /// zeros).
-    /// \param scratch Pointer to memory buffer that must be able to hold \p length bytes.
-    /// \returns True if operation succeeded, false otherwise.
-    bool peek(const machine &m, uint64_t offset, uint64_t length, const unsigned char **data,
-        unsigned char *scratch) const noexcept {
-        return do_peek(m, offset, length, data, scratch);
-    };
+    /// \brief Returns number of levels in a tree where each leaf is a page
+    int get_level_count() const noexcept {
+        return get_level_count(get_length());
+    }
+
+#ifndef MICROARCHITECTURE
+    /// \brief Returns reference to dirty page tree.
+    i_dirty_page_tree &get_dirty_page_tree() noexcept {
+        return do_get_dirty_page_tree();
+    }
+
+    /// \brief Returns const reference to dirty page tree.
+    const i_dirty_page_tree &get_dirty_page_tree() const noexcept {
+        return do_get_dirty_page_tree();
+    }
+
+    /// \brief Returns reference to dense hash tree.
+    i_dense_hash_tree &get_dense_hash_tree() noexcept {
+        return do_get_dense_hash_tree();
+    }
+
+    /// \brief Returns const reference to dense hash tree tree.
+    const i_dense_hash_tree &get_dense_hash_tree() const noexcept {
+        return do_get_dense_hash_tree();
+    }
+#endif
 
     // -----
     // These are only for device ranges
@@ -288,60 +307,25 @@ class address_range {
         return do_get_host_memory();
     }
 
-    /// \brief Mark a given page as dirty
-    /// \param offset Any offset in range within desired page
-    void mark_dirty_page(uint64_t offset) noexcept {
-        do_mark_dirty_page(offset);
-    }
-
-    /// \brief Mark all pages in a range of interest as dirty
-    /// \param offset Start of range of interest, relative to start of this range
-    /// \param length Length of range of interest, in bytes
-    void mark_dirty_pages(uint64_t offset, uint64_t length) noexcept {
-        auto offset_aligned = offset &= ~(AR_PAGE_SIZE - 1);
-        const auto length_aligned = length + (offset - offset_aligned);
-        for (; offset_aligned < length_aligned; offset_aligned += AR_PAGE_SIZE) {
-            mark_dirty_page(offset_aligned);
-        }
-    }
-
-    /// \brief Mark a given page as clean
-    /// \param offset Any offset in range within desired page
-    void mark_clean_page(uint64_t offset) noexcept {
-        do_mark_clean_page(offset);
-    }
-
-    /// \brief Marks all pages in range as clean
-    void mark_pages_clean() noexcept {
-        do_mark_pages_clean();
-    }
-
-    /// \brief Tests if a given page is dirty
-    /// \param offset Any offset in range within desired page
-    /// \returns True if and only if page is marked dirty
-    bool is_page_marked_dirty(uint64_t offset) const noexcept {
-        return do_is_page_marked_dirty(offset);
-    }
-
     /// \brief Returns true if the mapped memory is read-only on the host
     /// \returns True if the memory is read-only in the host
     bool is_host_read_only() const noexcept {
         return do_is_host_read_only();
     }
 
-    /// \brief Returns true if pages marked as dirty once are uncleanable
-    /// \returns True if and only if dirty pages are uncleanable
-    bool is_page_uncleanable() const noexcept {
-        return do_is_page_uncleanable();
+protected:
+    /// \brief Returns number of levels in a tree where each leaf is a page
+    /// \param length Length of range, in bytes
+    static constexpr int get_level_count(uint64_t length) noexcept {
+        auto page_count = length >> AR_LOG2_PAGE_SIZE;
+        if (page_count == 0) {
+            return 0;
+        }
+        // NOLINTNEXTLINE(bugprone-narrowing-conversions,cppcoreguidelines-narrowing-conversions)
+        return std::bit_width(std::bit_ceil(page_count));
     }
 
 private:
-    // Default implementation of peek() always fails
-    virtual bool do_peek(const machine & /*m*/, uint64_t /*offset*/, uint64_t /*length*/,
-        const unsigned char ** /*data*/, unsigned char * /*scratch*/) const noexcept {
-        return false;
-    }
-
     // Default implementation of read_device() for non-device ranges always fails
     virtual bool do_read_device(i_device_state_access * /*a*/, uint64_t /*offset*/, int /*log2_size*/,
         uint64_t * /*val*/) const noexcept {
@@ -363,30 +347,33 @@ class address_range {
         return nullptr;
     }
 
-    // Default implementation always assumes every page is always dirty
-    virtual void do_mark_dirty_page(uint64_t /*offset*/) noexcept {
-        ;
-    }
-
-    virtual void do_mark_clean_page(uint64_t /*offset*/) noexcept {
-        ;
+    virtual bool do_is_host_read_only() const noexcept {
+        return false;
     }
 
-    virtual void do_mark_pages_clean() noexcept {
-        ;
+#ifndef MICROARCHITECTURE
+    // Defaul implemenation returns always dirty tree
+    virtual const i_dirty_page_tree &do_get_dirty_page_tree() const noexcept {
+        const static empty_dirty_page_tree no_dirty{};
+        return no_dirty;
     }
 
-    virtual bool do_is_page_marked_dirty(uint64_t /*offset*/) const noexcept {
-        return true;
+    virtual i_dirty_page_tree &do_get_dirty_page_tree() noexcept {
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-const-cast)
+        return const_cast<i_dirty_page_tree &>(std::as_const(*this).do_get_dirty_page_tree());
     }
 
-    virtual bool do_is_host_read_only() const noexcept {
-        return false;
+    // Defaul implemenation returns no hashes
+    virtual const i_dense_hash_tree &do_get_dense_hash_tree() const noexcept {
+        const static empty_dense_hash_tree no_hashes{};
+        return no_hashes;
     }
 
-    virtual bool do_is_page_uncleanable() const noexcept {
-        return false;
+    virtual i_dense_hash_tree &do_get_dense_hash_tree() noexcept {
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-const-cast)
+        return const_cast<i_dense_hash_tree &>(std::as_const(*this).do_get_dense_hash_tree());
     }
+#endif
 };
 
 template <size_t N>
diff --git a/src/back-merkle-tree.cpp b/src/back-merkle-tree.cpp
index 93eaced27..9fbcafe28 100644
--- a/src/back-merkle-tree.cpp
+++ b/src/back-merkle-tree.cpp
@@ -32,7 +32,7 @@ namespace cartesi {
 back_merkle_tree::back_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size) :
     m_log2_root_size{log2_root_size},
     m_log2_leaf_size{log2_leaf_size},
-    m_max_leaves{address_type{1} << (log2_root_size - log2_leaf_size)},
+    m_max_leaves{UINT64_C(1) << (log2_root_size - log2_leaf_size)},
     m_context(std::max(1, log2_root_size - log2_leaf_size + 1)),
     m_pristine_hashes{log2_root_size, log2_word_size} {
     if (log2_root_size < 0) {
@@ -50,20 +50,20 @@ back_merkle_tree::back_merkle_tree(int log2_root_size, int log2_leaf_size, int l
     if (log2_word_size > log2_leaf_size) {
         throw std::out_of_range{"log2_word_size is greater than log2_word_size"};
     }
-    if (log2_root_size - m_log2_leaf_size >= std::numeric_limits<address_type>::digits) {
+    if (log2_root_size - m_log2_leaf_size >= std::numeric_limits<uint64_t>::digits) {
         throw std::out_of_range{"tree is too large for address type"};
     }
 }
 
-void back_merkle_tree::push_back(const hash_type &new_leaf_hash) {
+void back_merkle_tree::push_back(const machine_hash &new_leaf_hash) {
     hasher_type h;
-    hash_type right = new_leaf_hash;
+    machine_hash right = new_leaf_hash;
     if (m_leaf_count >= m_max_leaves) {
         throw std::out_of_range{"too many leaves"};
     }
     const int depth = m_log2_root_size - m_log2_leaf_size;
     for (int i = 0; i <= depth; ++i) {
-        if ((m_leaf_count & (address_type{1} << i)) != 0) {
+        if ((m_leaf_count & (UINT64_C(1) << i)) != 0) {
             const auto &left = m_context[i];
             get_concat_hash(h, left, right, right);
         } else {
@@ -82,7 +82,7 @@ void back_merkle_tree::pad_back(uint64_t new_leaf_count) {
     const int depth = m_log2_root_size - m_log2_leaf_size;
     int j = 0;
     while (j <= depth) {
-        const uint64_t j_span = address_type{1} << j;
+        const uint64_t j_span = UINT64_C(1) << j;
         if (j_span > new_leaf_count) {
             break;
         }
@@ -91,7 +91,7 @@ void back_merkle_tree::pad_back(uint64_t new_leaf_count) {
             // if so, we can add 2^j pristine leaves directly
             auto right = m_pristine_hashes.get_hash(m_log2_leaf_size + j);
             for (int i = j; i <= depth; ++i) {
-                const uint64_t i_span = address_type{1} << i;
+                const uint64_t i_span = UINT64_C(1) << i;
                 if ((m_leaf_count & i_span) != 0) {
                     const auto &left = m_context[i];
                     get_concat_hash(h, left, right, right);
@@ -110,7 +110,7 @@ void back_merkle_tree::pad_back(uint64_t new_leaf_count) {
     }
     // now add the rest of the padding directly to the context
     for (int i = 0; i <= depth; ++i) {
-        const uint64_t i_span = address_type{1} << i;
+        const uint64_t i_span = UINT64_C(1) << i;
         if ((new_leaf_count & i_span) != 0) {
             m_context[i] = m_pristine_hashes.get_hash(m_log2_leaf_size + i);
             new_leaf_count = new_leaf_count - i_span;
@@ -119,14 +119,14 @@ void back_merkle_tree::pad_back(uint64_t new_leaf_count) {
     }
 }
 
-back_merkle_tree::hash_type back_merkle_tree::get_root_hash() const {
+machine_hash back_merkle_tree::get_root_hash() const {
     hasher_type h;
     assert(m_leaf_count <= m_max_leaves);
     const int depth = m_log2_root_size - m_log2_leaf_size;
     if (m_leaf_count < m_max_leaves) {
         auto root = m_pristine_hashes.get_hash(m_log2_leaf_size);
         for (int i = 0; i < depth; ++i) {
-            if ((m_leaf_count & (address_type{1} << i)) != 0) {
+            if ((m_leaf_count & (UINT64_C(1) << i)) != 0) {
                 const auto &left = m_context[i];
                 get_concat_hash(h, left, root, root);
             } else {
@@ -148,9 +148,9 @@ back_merkle_tree::proof_type back_merkle_tree::get_next_leaf_proof() const {
     proof_type proof{m_log2_root_size, m_log2_leaf_size};
     proof.set_target_address(m_leaf_count << m_log2_leaf_size);
     proof.set_target_hash(m_pristine_hashes.get_hash(m_log2_leaf_size));
-    hash_type hash = m_pristine_hashes.get_hash(m_log2_leaf_size);
+    machine_hash hash = m_pristine_hashes.get_hash(m_log2_leaf_size);
     for (int i = 0; i < depth; ++i) {
-        if ((m_leaf_count & (address_type{1} << i)) != 0) {
+        if ((m_leaf_count & (UINT64_C(1) << i)) != 0) {
             const auto &left = m_context[i];
             proof.set_sibling_hash(left, m_log2_leaf_size + i);
             get_concat_hash(h, left, hash, hash);
diff --git a/src/back-merkle-tree.h b/src/back-merkle-tree.h
index fd1902b80..e7eaf6bb4 100644
--- a/src/back-merkle-tree.h
+++ b/src/back-merkle-tree.h
@@ -21,6 +21,7 @@
 #include <vector>
 
 #include "keccak-256-hasher.h"
+#include "machine-hash.h"
 #include "merkle-tree-proof.h"
 #include "pristine-merkle-tree.h"
 
@@ -42,14 +43,11 @@ class back_merkle_tree {
     /// \brief Hasher class.
     using hasher_type = keccak_256_hasher;
 
-    /// \brief Storage for a hash.
-    using hash_type = hasher_type::hash_type;
-
-    /// \brief Storage for a hash.
-    using address_type = uint64_t;
+    /// \brief Hasher class.
+    using hash_type = machine_hash;
 
     /// \brief Storage for the proof of a word value.
-    using proof_type = merkle_tree_proof<hash_type, address_type>;
+    using proof_type = merkle_tree_proof;
 
     /// \brief Constructor
     /// \param log2_root_size Log<sub>2</sub> of root node
@@ -61,33 +59,23 @@ class back_merkle_tree {
     /// \param new_leaf_hash Hash of new leaf data
     /// \details
     /// Consider the tree down to the leaf level.
-    /// The tree is only complete after 2^(log2_root_size-log2_leaf_size)
-    /// leaves have been added.
-    /// Before that, when leaf_count leaves have been added, we assume the rest
-    /// of the leaves are filled with zeros (i.e., they are pristine).
-    /// The trick is that we do not need to store the hashes of all leaf_count
-    /// leaves already added to the stream.
-    /// This is because, whenever a subtree is complete, all we need is its
-    /// root hash.
-    /// The complete subtrees are disjoint, abutting, and appear in decreasing
-    /// size.
-    /// In fact, there is exactly one complete subtree for each bit set in
-    /// leaf_count.
-    /// We only need log2_root_size-log2_leaf_size+1 bits to represent
-    /// leaf_count.
-    /// So our context is a vector with log2_root_size-log2_leaf_size+1 entries,
-    /// where entry i contains the hash for a complete subtree of
-    /// size 2^i leaves.
-    /// We will only use the entries i if the corresponding bit is set
-    /// in leaf_count.
+    /// The tree is only complete after 2^(log2_root_size-log2_leaf_size) leaves have been added.
+    /// Before that, when leaf_count leaves have been added, we assume the rest of the leaves are
+    /// filled with zeros (i.e., they are pristine).
+    /// The trick is that we do not need to store the hashes of all leaf_count leaves already added to the stream.
+    /// This is because, whenever a subtree is complete, all we need is its root hash.
+    /// The complete subtrees are disjoint, abutting, and appear in decreasing size.
+    /// In fact, there is exactly one complete subtree for each bit set in leaf_count.
+    /// We only need log2_root_size-log2_leaf_size+1 bits to represent leaf_count.
+    /// So our context is a vector with log2_root_size-log2_leaf_size+1 entries, where entry i contains
+    /// the hash for a complete subtree of size 2^i leaves.
+    /// We will only use the entries i if the corresponding bit is set in leaf_count.
     /// Adding a new leaf hash exactly like adding 1 to leaf_count.
     /// We scan from least to most significant bit in leaf_count.
     /// We start with the right = leaf_hash and i = 0.
-    /// If the bit i is set in leaf_count, we replace
-    /// context[i] = hash(context[i], right) and move up a bit.
-    /// If the bit is not set, we simply store context[i] = right and break
-    /// In other words, we can update the context in
-    /// log time (log2_root_size-log2_leaf_size)
+    /// If the bit i is set in leaf_count, we replace context[i] = hash(context[i], right) and move up a bit.
+    /// If the bit is not set, we simply store context[i] = right and break.
+    /// In other words, we can update the context in log time (log2_root_size-log2_leaf_size)
     void push_back(const hash_type &new_leaf_hash);
 
     /// \brief Appends a number of padding hashes to the tree
@@ -96,16 +84,12 @@ class back_merkle_tree {
     /// Recall that a bit i set in leaf_count represents a complete subtree
     /// of size 2^i for which we have a hash in context[i].
     /// The remaining entries in the context are unused.
-    /// The base case is when the least significant bit set in leaf_count is
-    /// bigger than new_leaf_count.
-    /// We can simply add to context[j] a pristine subtree of size 2^j
-    /// for each bit j set in new_leaf_count.
+    /// The base case is when the least significant bit set in leaf_count is bigger than new_leaf_count.
+    /// We can simply add to context[j] a pristine subtree of size 2^j for each bit j set in new_leaf_count.
     /// No used used entry in the context will be overwritten.
     /// We can then simply add new_leaf_count to leaf_count and we are done.
-    /// In the general case, the least significant bit set i in leaf_count is
-    /// less than or equal to new_leaf_count.
-    /// Here, we add a pristine subtree of size 2^i to the context and
-    /// bubble up.
+    /// In the general case, the least significant bit set i in leaf_count is less than or equal to new_leaf_count.
+    /// Here, we add a pristine subtree of size 2^i to the context and bubble up.
     /// We add 2^i to leaf_count and subtract 2^i from new_leaf_count.
     /// Then we repeat this process until we reach the base case.
     void pad_back(uint64_t new_leaf_count);
@@ -113,24 +97,16 @@ class back_merkle_tree {
     /// \brief Returns the root tree hash
     /// \returns Root tree hash
     /// \details
-    /// We can produce the tree root hash from the context at any time, also
-    /// in log time
-    /// Ostensibly, we add pristine leaves until the leaf_count
-    /// hits 2^(log2_root_size-log2_leaf_size)
-    /// To do this in log time, we start by precomputing the hashes for all
-    /// completely pristine subtree sizes
-    /// If leaf_count is already 2^(log2_root_size-log2_leaf_size), we
-    /// return context[i]
-    /// Otherwise, we start with i = 0 and root = pristine[i+log2_leaf_size]
-    /// (i.e., the invariant is that root contains the hash of the rightmost
-    /// subtree whose log size is i + log2_leaf_size)
-    /// If bit i is set, we set root = hash(context[i], root) and move up a bit
-    /// (i.e., the subtree we are growing is to the right of what is
-    /// in the context)
-    /// If bit i is not set, we set
-    /// root = hash(root, pristine[i+log2_leaf_size]) and move up a bit
-    /// (i.e., to grow our subtree, we need to pad it on the right with
-    /// a pristine subtree of the same size)
+    /// We can produce the tree root hash from the context at any time, also in log time
+    /// Ostensibly, we add pristine leaves until the leaf_count hits 2^(log2_root_size-log2_leaf_size)
+    /// To do this in log time, we start by precomputing the hashes for all completely pristine subtree sizes
+    /// If leaf_count is already 2^(log2_root_size-log2_leaf_size), we return context[i].
+    /// Otherwise, we start with i = 0 and root = pristine[i+log2_leaf_size] (i.e., the invariant is that
+    /// root contains the hash of the rightmost subtree whose log size is i + log2_leaf_size)
+    /// If bit i is set, we set root = hash(context[i], root) and move up a bit (i.e., the subtree we
+    /// are growing is to the right of what is in the context)
+    /// If bit i is not set, we set root = hash(root, pristine[i+log2_leaf_size]) and move up a bit
+    /// (i.e., to grow our subtree, we need to pad it on the right with a pristine subtree of the same size)
     hash_type get_root_hash() const;
 
     /// \brief Returns proof for the next pristine leaf
@@ -142,8 +118,8 @@ class back_merkle_tree {
 private:
     int m_log2_root_size;                   ///< Log<sub>2</sub> of tree size
     int m_log2_leaf_size;                   ///< Log<sub>2</sub> of leaf size
-    address_type m_leaf_count{0};           ///< Number of leaves already added
-    address_type m_max_leaves;              ///< Maximum number of leaves
+    uint64_t m_leaf_count{0};               ///< Number of leaves already added
+    uint64_t m_max_leaves;                  ///< Maximum number of leaves
     std::vector<hash_type> m_context;       ///< Hashes of bits set in leaf_count
     pristine_merkle_tree m_pristine_hashes; ///< Hash of pristine subtrees of all sizes
 };
diff --git a/src/base64.cpp b/src/base64.cpp
index d77f55ea2..0fcb4aec2 100644
--- a/src/base64.cpp
+++ b/src/base64.cpp
@@ -21,9 +21,8 @@
 #include <sstream>
 #include <stdexcept>
 #include <string>
-#include <string_view>
 
-namespace cartesi {
+namespace cartesi::detail {
 
 // Base64 globals
 static constexpr uint8_t b64base[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
@@ -43,7 +42,7 @@ static constexpr uint8_t b64unbase[] = {255, 255, 255, 255, 255, 255, 255, 255,
 // Accumulates bytes in input buffer until 3 bytes are available.
 // Translate the 3 bytes into Base64 form and append to buffer.
 // Returns new number of bytes in buffer.
-static size_t b64encode(uint8_t c, uint8_t *input, size_t size, std::ostringstream &sout) {
+size_t b64encode(uint8_t c, uint8_t *input, size_t size, std::ostringstream &sout) {
     input[size++] = c;
     if (size == 3) {
         uint8_t code[4];
@@ -70,7 +69,7 @@ static size_t b64encode(uint8_t c, uint8_t *input, size_t size, std::ostringstre
 // Encodes the Base64 last 1 or 2 bytes and adds padding '='
 // Result, if any, is appended to buffer.
 // Returns 0.
-static size_t b64pad(const uint8_t *input, size_t size, std::ostringstream &sout) {
+size_t b64pad(const uint8_t *input, size_t size, std::ostringstream &sout) {
     uint64_t value = 0;
     uint8_t code[4] = {'=', '=', '=', '='};
     switch (size) {
@@ -104,7 +103,7 @@ static size_t b64pad(const uint8_t *input, size_t size, std::ostringstream &sout
 // Accumulates bytes in input buffer until 4 bytes are available.
 // Translate the 4 bytes from Base64 form and append to buffer.
 // Returns new number of bytes in buffer.
-static size_t b64decode(uint8_t c, uint8_t *input, size_t size, std::ostringstream &sout) {
+size_t b64decode(uint8_t c, uint8_t *input, size_t size, std::ostringstream &sout) {
     if (b64unbase[c] > 64) {
         if (c == ' ' || c == '\t' || c == '\n' || c == '\v' || c == '\f' || c == '\r') { // ignore whitespace characters
             return size;
@@ -145,25 +144,4 @@ static size_t b64decode(uint8_t c, uint8_t *input, size_t size, std::ostringstre
     return size;
 }
 
-std::string encode_base64(const std::string_view &input) {
-    std::ostringstream sout;
-    uint8_t ctx[4]{};
-    size_t ctxlen = 0;
-    for (const char b : input) {
-        ctxlen = b64encode(static_cast<uint8_t>(b), ctx, ctxlen, sout);
-    }
-    b64pad(ctx, ctxlen, sout);
-    return sout.str();
-}
-
-std::string decode_base64(const std::string_view &input) {
-    std::ostringstream sout;
-    uint8_t ctx[4]{};
-    size_t ctxlen = 0;
-    for (const char b : input) {
-        ctxlen = b64decode(static_cast<uint8_t>(b), ctx, ctxlen, sout);
-    }
-    return sout.str();
-}
-
-} // namespace cartesi
+} // namespace cartesi::detail
diff --git a/src/base64.h b/src/base64.h
index b2ebe8d20..ba34cb0c7 100644
--- a/src/base64.h
+++ b/src/base64.h
@@ -17,14 +17,51 @@
 #ifndef BASE64_H
 #define BASE64_H
 
+#include <cstdint>
+#include <sstream>
 #include <string>
-#include <string_view>
+
+#include "concepts.h"
 
 namespace cartesi {
 
-std::string encode_base64(const std::string_view &input);
+namespace detail {
+
+size_t b64encode(uint8_t c, uint8_t *input, size_t size, std::ostringstream &sout);
+size_t b64pad(const uint8_t *input, size_t size, std::ostringstream &sout);
+size_t b64decode(uint8_t c, uint8_t *input, size_t size, std::ostringstream &sout);
+
+} // namespace detail
+
+/// \brief Encodes binary data into base64
+/// \param data Input data range
+/// \returns String with encoded data
+template <ContiguousRangeOfByteLike R>
+std::string encode_base64(R &&data) { // NOLINT(cppcoreguidelines-missing-std-forward)
+    //??D we could make this faster by avoiding ostringstream altogether...
+    std::ostringstream sout;
+    uint8_t ctx[4]{};
+    size_t ctxlen = 0;
+    for (auto b : data) {
+        ctxlen = detail::b64encode(static_cast<uint8_t>(b), ctx, ctxlen, sout);
+    }
+    detail::b64pad(ctx, ctxlen, sout);
+    return sout.str();
+}
 
-std::string decode_base64(const std::string_view &input);
+/// \brief Decodes binary data from base64
+/// \param data Input data range
+/// \returns String with decoded data
+template <ContiguousRangeOfByteLike R>
+std::string decode_base64(R &&data) { // NOLINT(cppcoreguidelines-missing-std-forward)
+    std::ostringstream sout;
+    uint8_t ctx[4]{};
+    size_t ctxlen = 0;
+    for (auto b : data) {
+        ctxlen = detail::b64decode(static_cast<uint8_t>(b), ctx, ctxlen, sout);
+    }
+    return sout.str();
+}
 
 } // namespace cartesi
 
diff --git a/src/cartesi-machine.lua b/src/cartesi-machine.lua
index 80c36b181..20d912bfb 100755
--- a/src/cartesi-machine.lua
+++ b/src/cartesi-machine.lua
@@ -298,10 +298,10 @@ where options are:
     configures the number of threads used in some implementation parts.
 
     <key>:<value> is one of
-        update_merkle_tree:<number>
+        update_hash_tree:<number>
 
-        update_merkle_tree (optional)
-        defines the number of threads to use while calculating the merkle tree.
+        update_hash_tree (optional)
+        defines the number of threads to use while calculating the hash tree.
         when omitted or defined as 0, the number of hardware threads is used if
         it can be identified or else a single thread is used.
 
@@ -676,7 +676,7 @@ local pmas = {}
 local hash_tree = {
     hasher = default_config.hash_tree.hasher,
 }
-local concurrency_update_merkle_tree = 0
+local concurrency_update_hash_tree = 0
 local skip_root_hash_check = false
 local skip_root_hash_store = false
 local skip_version_check = false
@@ -1278,11 +1278,11 @@ local options = {
         "^(%-%-concurrency%=(.+))$",
         function(all, opts)
             local c = util.parse_options(opts, {
-                update_merkle_tree = true,
+                update_hash_tree = true,
             })
-            c.update_merkle_tree =
-                assert(util.parse_number(c.update_merkle_tree), "invalid update_merkle_tree number in " .. all)
-            concurrency_update_merkle_tree = c.update_merkle_tree
+            c.update_hash_tree =
+                assert(util.parse_number(c.update_hash_tree), "invalid update_hash_tree number in " .. all)
+            concurrency_update_hash_tree = c.update_hash_tree
             return true
         end,
     },
@@ -1801,7 +1801,7 @@ end
 
 local runtime_config = {
     concurrency = {
-        update_merkle_tree = concurrency_update_merkle_tree,
+        update_hash_tree = concurrency_update_hash_tree,
     },
     htif = {
         no_console_putchar = htif_no_console_putchar,
diff --git a/src/circular-buffer.h b/src/circular-buffer.h
new file mode 100644
index 000000000..6cffb5755
--- /dev/null
+++ b/src/circular-buffer.h
@@ -0,0 +1,406 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef CIRCULAR_BUFFER_H
+#define CIRCULAR_BUFFER_H
+
+/// \file
+/// \brief Circular buffer container
+
+#include <concepts>
+#include <cstddef>
+#include <iterator>
+#include <span>
+#include <utility>
+
+#include <boost/container/static_vector.hpp>
+#include <boost/iterator/iterator_adaptor.hpp>
+
+#include "meta.h"
+
+namespace cartesi {
+
+/// \brief Circular buffer container.
+/// \tparam T type of entry in container.
+/// \tparam N maximum number of entries container can hold.
+/// \details The circular buffer contianer with a fixed number of entries.
+/// The container that be statically allocated, when \p N is passed as a template argument at compile time.
+/// It can be dynamically allocated, with the size is chosen in the constructor at runtime.
+/// \p T does not need to be default-constructible.
+template <typename T, size_t N = std::dynamic_extent>
+class circular_buffer {
+    using base = circular_buffer<T, N>;
+    using container_dynamic = std::vector<T>;
+    using container_static = boost::container::static_vector<T, N + 1>;
+    using container_base = std::conditional_t<N == std::dynamic_extent, container_dynamic, container_static>;
+
+public:
+    using value_type = typename container_base::value_type;
+    using size_type = typename container_base::size_type;
+    using difference_type = typename container_base::difference_type;
+    using reference = typename container_base::reference;
+    using const_reference = typename container_base::const_reference;
+    using pointer = typename container_base::pointer;
+    using const_pointer = typename container_base::const_pointer;
+
+    static constexpr auto max_size = std::numeric_limits<difference_type>::max() - 1;
+
+    /// \brief Constructor for statically allocated container
+    constexpr circular_buffer() noexcept
+        requires(N > 0 && N < max_size && N != std::dynamic_extent)
+        : m_uninitialized_entries{modulus()} {}
+
+    /// \brief Constructor for dynamically allocated container
+    /// \param n maximum number of entries container can hold
+    explicit circular_buffer(size_type n)
+        requires(N == std::dynamic_extent)
+        : m_uninitialized_entries{static_cast<difference_type>(n + 1)}, m_modulus{static_cast<difference_type>(n + 1)} {
+        if (n == 0) {
+            throw std::invalid_argument{"capacity must be > 0"};
+        }
+        if (n > max_size) {
+            throw std::invalid_argument{"capacity is too large"};
+        }
+        m_storage.reserve(n + 1); // Allocate once and for all
+    }
+
+    // Default move and copy constructors
+    circular_buffer(const circular_buffer &) = default;
+    circular_buffer(circular_buffer &&) noexcept = default;
+    circular_buffer &operator=(const circular_buffer &) = default;
+    circular_buffer &operator=(circular_buffer &&) noexcept = default;
+    ~circular_buffer() = default;
+
+    /// \brief Returns number of entries currently in container
+    /// \returns Number of entries currently in container
+    [[nodiscard]] size_type size() const noexcept {
+        auto n = m_end - m_begin;
+        if (n < 0) {
+            n += modulus();
+        }
+        return static_cast<size_type>(n);
+    }
+
+    /// \brief Returns maximum number of entries container can hold
+    /// \returns Maximum number of entries container can hold
+    [[nodiscard]] constexpr size_type capacity() const noexcept {
+        if constexpr (N == std::dynamic_extent) {
+            return m_modulus - 1;
+        } else {
+            return N;
+        }
+    }
+
+    /// \brief Returns modulus to use for modular arithmetic
+    /// \returns Modulus to use for modular arithmetic
+    [[nodiscard]] constexpr difference_type modulus() const noexcept {
+        if constexpr (N == std::dynamic_extent) {
+            return m_modulus;
+        } else {
+            return static_cast<difference_type>(N + 1);
+        }
+    }
+
+    /// \brief Tells if container is empty
+    /// \returns True if empty, false otherwise
+    [[nodiscard]] bool empty() const noexcept {
+        return m_begin == m_end;
+    }
+
+    /// \brief Tells if container is full
+    /// \returns True if true, false otherwise
+    [[nodiscard]] bool full() const noexcept {
+        return size() == capacity();
+    }
+
+    /// \brief Adds new entry to back of container
+    /// \tparam U Type for universal reference to value
+    /// \param value Value to insert. L-value references are copied, r-value references are moved.
+    template <typename U>
+        requires std::constructible_from<T, U &&>
+    void push_back(U &&value) noexcept {
+        // If we still have uninitialized entries, push_back into storage
+        if (m_uninitialized_entries != 0) {
+            --m_uninitialized_entries;
+            m_storage.push_back(std::forward<U>(value));
+            // Otherwise, simply copy/move construct over initialized entries
+        } else {
+            dereference_offset(m_end) = std::forward<U>(value);
+        }
+        increment_offset(m_end);
+        if (m_end == m_begin) {
+            increment_offset(m_begin);
+        }
+    }
+
+    /// \brief Construct entry at back of container
+    /// \tparam Args... Types of entry constructor arguments
+    /// \param ...args Arguments to entry constructor
+    template <typename... Args>
+        requires std::constructible_from<T, Args...>
+    void emplace_back(Args &&...args) {
+        if (m_uninitialized_entries != 0) {
+            --m_uninitialized_entries;
+            m_storage.emplace_back(std::forward<Args>(args)...);
+        } else {
+            dereference_offset(m_end) = T(std::forward<Args>(args)...);
+        }
+        increment_offset(m_end);
+        if (m_end == m_begin) {
+            increment_offset(m_begin);
+        }
+    }
+
+    /// \brief Adds new entry to back of container, if not already there
+    /// \tparam U Type for universal reference to value
+    /// \param value Value to insert. L-value references are copied, r-value references are moved.
+    template <typename U>
+        requires std::constructible_from<T, U &&> && std::equality_comparable_with<T, U>
+    void try_push_back(U &&value) noexcept {
+        if (empty() || back() != value) {
+            push_back(std::forward<U>(value));
+        }
+    }
+
+    /// \brief Removes entry at back of container, if any
+    void pop_back() noexcept {
+        if (!empty()) {
+            decrement_offset(m_end);
+        }
+    }
+
+    /// \brief Removes entry at the front of container, if any
+    void pop_front() noexcept {
+        if (!empty()) {
+            increment_offset(m_begin);
+        }
+    }
+
+    /// \brief Returns entry at front of container
+    /// \detail If container is empty, returns garbage
+    reference front() noexcept {
+        return dereference_offset(m_begin);
+    }
+
+    /// \brief Returns entry at front of container
+    /// \detail If container is empty, returns garbage
+    const_reference front() const noexcept {
+        return dereference_offset(m_begin);
+    }
+
+    /// \brief Returns entry at back of container
+    /// \detail If container is empty, returns garbage
+    reference back() noexcept {
+        auto b = m_end;
+        decrement_offset(b);
+        return dereference_offset(b);
+    }
+
+    /// \brief Returns entry at back of container
+    /// \detail If container is empty, returns garbage
+    const_reference back() const noexcept {
+        auto b = m_end;
+        decrement_offset(b);
+        return dereference_offset(b);
+    }
+
+    /// \brief Removes all entries from container
+    void clear() noexcept {
+        m_storage.clear();
+        m_storage.reserve(modulus());
+        m_begin = m_end = 0;
+        m_uninitialized_entries = modulus();
+    }
+
+    /// \brief Base class for all iterators
+    /// \tparam CB class of container (so it works with const and non-const)
+    /// \tparam Value class of container entry (so it works with const and non-const)
+    template <typename CB, typename Value>
+    class iterator_base :
+        public boost::iterator_facade<iterator_base<CB, Value>, Value, std::random_access_iterator_tag, Value &,
+            difference_type> {
+        CB *m_cb;
+        difference_type m_offset;
+
+    public:
+        iterator_base() noexcept : iterator_base::iterator_facade_{}, m_cb{}, m_offset{0} {}
+
+        iterator_base(CB *cb, difference_type offset) noexcept :
+            iterator_base::iterator_facade_{},
+            m_cb{cb},
+            m_offset{offset} {}
+
+    private:
+        friend class boost::iterator_core_access;
+
+        void increment() {
+            m_cb->increment_offset(m_offset);
+        }
+
+        void decrement() {
+            m_cb->decrement_offset(m_offset);
+        }
+
+        template <typename CB_Other, typename ValueOther>
+
+        bool equal(const iterator_base<CB_Other, ValueOther> &other) const
+            requires SameAsNoCVRef<CB, CB_Other> && SameAsNoCVRef<Value, ValueOther>
+        {
+            if (m_cb != other.m_cb) {
+                return false;
+            }
+            return m_cb->equal_offset(m_offset, other.m_offset);
+        }
+
+        Value &dereference() const {
+            return m_cb->dereference_offset(m_offset);
+        }
+    };
+
+    // Friend declaration so iterators can use private methods in container
+    template <typename CB, typename Value>
+    friend class iterator_base;
+
+    // Iterator types
+    using iterator = iterator_base<base, value_type>;
+    using const_iterator = iterator_base<const base, const value_type>;
+    using const_reverse_iterator = std::reverse_iterator<const_iterator>;
+    using reverse_iterator = std::reverse_iterator<iterator>;
+
+    /// \brief Returns iterator to first entry in container
+    /// \returns Iterator to first entry in container
+    auto begin() noexcept {
+        return iterator{this, m_begin};
+    }
+
+    /// \brief Returns iterator to one past last entry in container
+    /// \returns Iterator to one past last entry in container
+    auto end() noexcept {
+        return iterator{this, m_end};
+    }
+
+    /// \brief Returns iterator to first entry in container
+    /// \returns Iterator to first entry in container
+    auto begin() const noexcept {
+        return const_iterator{this, m_begin};
+    }
+
+    /// \brief Returns iterator to one past last entry in container
+    /// \returns Iterator to one past last entry in container
+    auto end() const noexcept {
+        return const_iterator{this, m_end};
+    }
+
+    /// \brief Returns constant iterator to first entry in container
+    /// \returns Constant iterator to first entry in container
+    auto cbegin() const noexcept {
+        return const_iterator{this, m_begin};
+    }
+
+    /// \brief Returns constant iterator to one past last entry in container
+    /// \returns Constant iterator to one past last entry in container
+    auto cend() const noexcept {
+        return const_iterator{this, m_end};
+    }
+
+    /// \brief Returns iterator to first entry in reversed container
+    /// \returns Iterator to first entry in reversed container
+    auto rbegin() noexcept {
+        return reverse_iterator{end()};
+    }
+
+    /// \brief Returns iterator to one past last entry in revesed container
+    /// \returns Iterator to one past last entry in revesed container
+    auto rend() noexcept {
+        return reverse_iterator{begin()};
+    }
+
+    /// \brief Returns iterator to first entry in reversed container
+    /// \returns Iterator to first entry in reversed container
+    auto rbegin() const noexcept {
+        return const_reverse_iterator{end()};
+    }
+
+    /// \brief Returns iterator to one past last entry in revesed container
+    /// \returns Iterator to one past last entry in revesed container
+    auto rend() const noexcept {
+        return const_reverse_iterator{begin()};
+    }
+
+    /// \brief Returns constant iterator to first entry in reversed container
+    /// \returns Constant iterator to first entry in reversed container
+    auto crbegin() const noexcept {
+        return const_reverse_iterator{end()};
+    }
+
+    /// \brief Returns constant iterator to one past last entry in revesed container
+    /// \returns Constant iterator to one past last entry in revesed container
+    auto crend() const noexcept {
+        return const_reverse_iterator{begin()};
+    }
+
+private:
+    /// \brief Increment offset using modular arithmetic
+    /// \details Assumes offset is in {0, ..., modulus()-1}
+    void increment_offset(difference_type &offset) noexcept {
+        assert(offset >= 0 && offset < modulus() && "offset is out of range");
+        ++offset;
+        if (offset >= modulus()) {
+            offset -= modulus();
+        }
+    }
+
+    /// \brief Decrements offset using modular arithmetic
+    /// \details Assumes offset is in {0, ..., modulus()-1}
+    void decrement_offset(difference_type &offset) noexcept {
+        assert(offset >= 0 && offset < modulus() && "offset is out of range");
+        --offset;
+        if (offset < 0) {
+            offset += modulus();
+        }
+    }
+
+    /// \brief Returns reference to entry at offset
+    /// \details Assumes offset is in {0, ..., modulus()-1}
+    reference dereference_offset(difference_type offset) noexcept {
+        assert(offset >= 0 && offset < modulus() && "offset is out of range");
+        return *(m_storage.data() + offset);
+    }
+
+    /// \brief Returns constant reference to entry at offset
+    /// \details Assumes offset is in {0, ..., modulus()-1}
+    const_reference dereference_offset(difference_type offset) const noexcept {
+        assert(offset >= 0 && offset < modulus() && "offset is out of range");
+        return *(m_storage.data() + offset);
+    }
+
+    /// \brief Checks if offsets refer to same entry
+    /// \details Assumes offset is in {0, ..., modulus()-1}
+    static bool equal_offset(difference_type a, difference_type b) noexcept {
+        return a == b;
+    }
+
+    container_base m_storage; // Storage for all entries. Starts empty (but already allocated).
+    // m_begin and m_end use modular arithmetic and are always in {0, modulus()-1}
+    difference_type m_begin{0};              // First entry
+    difference_type m_end{0};                // One past past last entry
+    difference_type m_uninitialized_entries; // Number of entries not yet initialized
+    [[no_unique_address]] std::conditional_t<N == std::dynamic_extent, difference_type, std::monostate> m_modulus;
+};
+
+} // namespace cartesi
+
+#endif // CIRCULAR_BUFFER_H
diff --git a/src/clint-address-range.h b/src/clint-address-range.h
index 3a785a749..695d0315f 100644
--- a/src/clint-address-range.h
+++ b/src/clint-address-range.h
@@ -20,14 +20,14 @@
 #include <cstdint>
 
 #include "address-range-constants.h"
-#include "pristine-address-range.h"
+#include "address-range.h"
 
 /// \file
 /// \brief Core-Local Interruptor device.
 
 namespace cartesi {
 
-class clint_address_range final : public pristine_address_range {
+class clint_address_range final : public address_range {
 
     static constexpr pmas_flags m_clint_flags{
         .M = false,
@@ -43,7 +43,7 @@ class clint_address_range final : public pristine_address_range {
 public:
     template <typename ABRT>
     explicit clint_address_range(ABRT abrt) :
-        pristine_address_range("CLINT device", AR_CLINT_START, AR_CLINT_LENGTH, m_clint_flags, abrt) {
+        address_range("CLINT device", AR_CLINT_START, AR_CLINT_LENGTH, m_clint_flags, abrt) {
         ;
     }
 
diff --git a/src/clua-cartesi.cpp b/src/clua-cartesi.cpp
index 5a196b45c..6ec6923a6 100644
--- a/src/clua-cartesi.cpp
+++ b/src/clua-cartesi.cpp
@@ -63,7 +63,7 @@ static const auto gperf_meta = clua_make_luaL_Reg_array({
 static int cartesi_mod_keccak(lua_State *L) {
     using namespace cartesi;
     keccak_256_hasher h;
-    keccak_256_hasher::hash_type hash;
+    machine_hash hash;
     if (lua_gettop(L) > 2) {
         luaL_argerror(L, 3, "too many arguments");
     }
@@ -77,7 +77,7 @@ static int cartesi_mod_keccak(lua_State *L) {
         uint64_t word = luaL_checkinteger(L, 1);
         h.begin();
         // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        h.add_data(reinterpret_cast<const unsigned char *>(&word), sizeof(word));
+        h.add_data(std::span<unsigned char>(reinterpret_cast<unsigned char *>(&word), sizeof(word)));
         h.end(hash);
         // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
         lua_pushlstring(L, reinterpret_cast<const char *>(hash.data()), hash.size());
@@ -87,11 +87,11 @@ static int cartesi_mod_keccak(lua_State *L) {
     size_t len1 = 0;
     const char *hash1 = luaL_checklstring(L, 1, &len1);
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-    h.add_data(reinterpret_cast<const unsigned char *>(hash1), len1);
+    h.add_data(std::span<const char>(hash1, len1));
     size_t len2 = 0;
     const char *hash2 = luaL_optlstring(L, 2, "", &len2);
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-    h.add_data(reinterpret_cast<const unsigned char *>(hash2), len2);
+    h.add_data(std::span<const char>(hash2, len2));
     h.end(hash);
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
     lua_pushlstring(L, reinterpret_cast<const char *>(hash.data()), hash.size());
@@ -105,7 +105,7 @@ static int cartesi_mod_tobase64(lua_State *L) try {
     lua_pushlstring(L, value.data(), value.size());
     value.clear();
     return 1;
-} catch (std::exception &e) {
+} catch (const std::exception &e) {
     luaL_error(L, "%s", e.what());
     return 1;
 }
@@ -117,7 +117,7 @@ static int cartesi_mod_frombase64(lua_State *L) try {
     lua_pushlstring(L, value.data(), value.size());
     value.clear();
     return 1;
-} catch (std::exception &e) {
+} catch (const std::exception &e) {
     luaL_error(L, "%s", e.what());
     return 1;
 }
@@ -127,7 +127,7 @@ static int cartesi_mod_tojson(lua_State *L) try {
     lua_settop(L, 1);
     clua_check_json_string(L, 1, indent);
     return 1;
-} catch (std::exception &e) {
+} catch (const std::exception &e) {
     luaL_error(L, "%s", e.what());
     return 1;
 }
@@ -135,7 +135,7 @@ static int cartesi_mod_tojson(lua_State *L) try {
 static int cartesi_mod_fromjson(lua_State *L) try {
     clua_push_json_table(L, luaL_checkstring(L, 1));
     return 1;
-} catch (std::exception &e) {
+} catch (const std::exception &e) {
     luaL_error(L, "%s", e.what());
     return 1;
 }
@@ -146,7 +146,7 @@ static int cartesi_mod_new(lua_State *L) try {
         return luaL_error(L, "%s", cm_get_last_error_message());
     }
     return 1;
-} catch (std::exception &e) {
+} catch (const std::exception &e) {
     luaL_error(L, "%s", e.what());
     return 1;
 }
diff --git a/src/clua-i-machine.cpp b/src/clua-i-machine.cpp
index bc5a1a3f7..b1b064979 100644
--- a/src/clua-i-machine.cpp
+++ b/src/clua-i-machine.cpp
@@ -362,7 +362,7 @@ const char *clua_check_json_string(lua_State *L, int idx, int indent, int ctxidx
         lua_replace(L, idx);             // replace the Lua value with its JSON string representation
         lua_pop(L, 2);                   // pop s, j references
         return luaL_checkstring(L, idx); // return the string
-    } catch (std::exception &e) {
+    } catch (const std::exception &e) {
         luaL_error(L, "failed to parse JSON from a Lua table: %s", e.what());
         return nullptr;
     }
@@ -443,63 +443,61 @@ void clua_push_json_table(lua_State *L, const char *s, int ctxidx, const nlohman
         clua_push_json_value(L, j, ctxidx, schema, schema_dict);
         lua_replace(L, -3); // move into the placeholder slot
         lua_pop(L, 1);      // pop j reference
-    } catch (std::exception &e) {
+    } catch (const std::exception &e) {
         luaL_error(L, "failed to parse JSON from a string: %s", e.what());
     }
 }
 
-static const nlohmann::json &clua_get_machine_schema_dict(lua_State *L) {
-    try {
-        // In order to convert Lua tables <-> JSON objects we have to define a schema
-        // to transform some special fields, we only care about:
-        // - Binary strings (translate Base64 strings in JSON to binary strings in Lua)
-        // - Array indexes (translate 0 based index in JSON to 1 based index in Lua)
-        static const nlohmann::json machine_schema_dict = {
-            {"Base64", "Base64"},
-            {"ArrayIndex", "ArrayIndex"},
-            {"Base64Array",
-                {
-                    {"items", "Base64"},
-                }},
-            {"Proof",
-                {
-                    {"target_hash", "Base64"},
-                    {"root_hash", "Base64"},
-                    {"sibling_hashes", "Base64Array"},
-                }},
-            {"Access",
-                {
-                    {"read", "Base64"},
-                    {"read_hash", "Base64"},
-                    {"written", "Base64"},
-                    {"written_hash", "Base64"},
-                    {"sibling_hashes", "Base64Array"},
-                }},
-            {"AccessArray",
-                {
-                    {"items", "Access"},
-                }},
-            {"Bracket",
-                {
-                    {"where", "ArrayIndex"},
-                }},
-            {"BracketArray",
-                {
-                    {"items", "Bracket"},
-                }},
-            {"AccessLog",
-                {
-                    {"accesses", "AccessArray"},
-                    {"brackets", "BracketArray"},
-                }},
-        };
-        return machine_schema_dict;
-    } catch (std::exception &e) {
-        luaL_error(L, "failed to create machine schema dictionary: %s", e.what());
-        static const nlohmann::json dummy;
-        return dummy;
-    }
-};
+static const nlohmann::json &clua_get_machine_schema_dict(lua_State *L) try {
+    // In order to convert Lua tables <-> JSON objects we have to define a schema
+    // to transform some special fields, we only care about:
+    // - Binary strings (translate Base64 strings in JSON to binary strings in Lua)
+    // - Array indexes (translate 0 based index in JSON to 1 based index in Lua)
+    static const nlohmann::json machine_schema_dict = {
+        {"Base64", "Base64"},
+        {"ArrayIndex", "ArrayIndex"},
+        {"Base64Array",
+            {
+                {"items", "Base64"},
+            }},
+        {"Proof",
+            {
+                {"target_hash", "Base64"},
+                {"root_hash", "Base64"},
+                {"sibling_hashes", "Base64Array"},
+            }},
+        {"Access",
+            {
+                {"read", "Base64"},
+                {"read_hash", "Base64"},
+                {"written", "Base64"},
+                {"written_hash", "Base64"},
+                {"sibling_hashes", "Base64Array"},
+            }},
+        {"AccessArray",
+            {
+                {"items", "Access"},
+            }},
+        {"Bracket",
+            {
+                {"where", "ArrayIndex"},
+            }},
+        {"BracketArray",
+            {
+                {"items", "Bracket"},
+            }},
+        {"AccessLog",
+            {
+                {"accesses", "AccessArray"},
+                {"brackets", "BracketArray"},
+            }},
+    };
+    return machine_schema_dict;
+} catch (const std::exception &e) {
+    luaL_error(L, "failed to create machine schema dictionary: %s", e.what());
+    static const nlohmann::json dummy;
+    return dummy;
+}
 
 const char *clua_check_schemed_json_string(lua_State *L, int idx, const std::string &schema_name, int ctxidx) {
     const auto &machine_schema_dict = clua_get_machine_schema_dict(L);
@@ -579,6 +577,20 @@ static int machine_obj_index_get_root_hash(lua_State *L) {
     return 1;
 }
 
+/// \brief This is the machine:get_node_hash() method implementation.
+/// \param L Lua state.
+static int machine_obj_index_get_node_hash(lua_State *L) {
+    auto &m = clua_check<clua_managed_cm_ptr<cm_machine>>(L, 1);
+    const uint64_t address = luaL_checkinteger(L, 2);
+    const int log2_size = static_cast<int>(luaL_checkinteger(L, 3));
+    cm_hash node_hash{};
+    if (cm_get_node_hash(m.get(), address, log2_size, &node_hash) != 0) {
+        return luaL_error(L, "%s", cm_get_last_error_message());
+    }
+    clua_push_cm_hash(L, &node_hash);
+    return 1;
+}
+
 /// \brief This is the machine:read_reg() method implementation.
 /// \param L Lua state.
 static int machine_obj_index_read_reg(lua_State *L) {
@@ -601,7 +613,7 @@ static int machine_obj_index_read_memory(lua_State *L) {
     unsigned char *data{};
     try {
         data = new unsigned char[length];
-    } catch (std::bad_alloc &e) {
+    } catch (const std::bad_alloc &e) {
         luaL_error(L, "failed to allocate memory for buffer");
     }
     auto &managed_data = clua_push_to(L, clua_managed_cm_ptr<unsigned char>(data));
@@ -624,7 +636,7 @@ static int machine_obj_index_read_virtual_memory(lua_State *L) {
     unsigned char *data{};
     try {
         data = new unsigned char[length];
-    } catch (std::bad_alloc &e) {
+    } catch (const std::bad_alloc &e) {
         luaL_error(L, "failed to allocate memory for buffer");
     }
     auto &managed_data = clua_push_to(L, clua_managed_cm_ptr<unsigned char>(data));
@@ -743,24 +755,12 @@ static int machine_obj_index_store(lua_State *L) {
     return 0;
 }
 
-/// \brief This is the machine:verify_dirty_page_maps() method implementation.
-/// \param L Lua state.
-static int machine_obj_index_verify_dirty_page_maps(lua_State *L) {
-    auto &m = clua_check<clua_managed_cm_ptr<cm_machine>>(L, 1);
-    bool result{};
-    if (cm_verify_dirty_page_maps(m.get(), &result) != 0) {
-        return luaL_error(L, "%s", cm_get_last_error_message());
-    }
-    lua_pushboolean(L, static_cast<int>(result));
-    return 1;
-}
-
-/// \brief This is the machine:verify_merkle_tree() method implementation.
+/// \brief This is the machine:verify_hash_tree() method implementation.
 /// \param L Lua state.
-static int machine_obj_index_verify_merkle_tree(lua_State *L) {
+static int machine_obj_index_verify_hash_tree(lua_State *L) {
     auto &m = clua_check<clua_managed_cm_ptr<cm_machine>>(L, 1);
     bool result{};
-    if (cm_verify_merkle_tree(m.get(), &result) != 0) {
+    if (cm_verify_hash_tree(m.get(), &result) != 0) {
         return luaL_error(L, "%s", cm_get_last_error_message());
     }
     lua_pushboolean(L, static_cast<int>(result));
@@ -848,7 +848,7 @@ static int machine_obj_index_receive_cmio_request(lua_State *L) {
     unsigned char *data{};
     try {
         data = new unsigned char[length];
-    } catch (std::bad_alloc &e) {
+    } catch (const std::bad_alloc &e) {
         luaL_error(L, "failed to allocate memory for buffer");
     }
     auto &managed_data = clua_push_to(L, clua_managed_cm_ptr<unsigned char>(data));
@@ -1050,6 +1050,7 @@ static const auto machine_obj_index = cartesi::clua_make_luaL_Reg_array({
     {"get_proof", machine_obj_index_get_proof},
     {"get_reg_address", machine_obj_index_get_reg_address},
     {"get_root_hash", machine_obj_index_get_root_hash},
+    {"get_node_hash", machine_obj_index_get_node_hash},
     {"get_runtime_config", machine_obj_index_get_runtime_config},
     {"is_empty", machine_obj_index_is_empty},
     {"load", machine_obj_index_load},
@@ -1071,8 +1072,7 @@ static const auto machine_obj_index = cartesi::clua_make_luaL_Reg_array({
     {"store", machine_obj_index_store},
     {"swap", machine_obj_index_swap},
     {"translate_virtual_address", machine_obj_index_translate_virtual_address},
-    {"verify_dirty_page_maps", machine_obj_index_verify_dirty_page_maps},
-    {"verify_merkle_tree", machine_obj_index_verify_merkle_tree},
+    {"verify_hash_tree", machine_obj_index_verify_hash_tree},
     {"verify_reset_uarch", machine_obj_index_verify_reset_uarch},
     {"verify_send_cmio_response", machine_obj_index_verify_send_cmio_response},
     {"verify_step", machine_obj_index_verify_step},
diff --git a/src/complete-merkle-tree.cpp b/src/complete-merkle-tree.cpp
index 658dbe324..334862846 100644
--- a/src/complete-merkle-tree.cpp
+++ b/src/complete-merkle-tree.cpp
@@ -41,7 +41,7 @@ complete_merkle_tree::complete_merkle_tree(int log2_root_size, int log2_leaf_siz
 /// \param address Node address
 /// \param log2_size Log<sub>2</sub> size subintended by node
 /// \returns Proof, or throws exception
-complete_merkle_tree::proof_type complete_merkle_tree::get_proof(address_type address, int log2_size) const {
+complete_merkle_tree::proof_type complete_merkle_tree::get_proof(uint64_t address, int log2_size) const {
     if (log2_size < get_log2_leaf_size() || log2_size > get_log2_root_size()) {
         throw std::out_of_range{"log2_size is out of bounds"};
     }
@@ -54,7 +54,7 @@ complete_merkle_tree::proof_type complete_merkle_tree::get_proof(address_type ad
     proof.set_target_address(address);
     proof.set_target_hash(get_node_hash(address, log2_size));
     for (int log2_sibling_size = log2_size; log2_sibling_size < get_log2_root_size(); ++log2_sibling_size) {
-        auto sibling_address = address ^ (address_type{1} << log2_sibling_size);
+        auto sibling_address = address ^ (UINT64_C(1) << log2_sibling_size);
         proof.set_sibling_hash(get_node_hash(sibling_address, log2_sibling_size), log2_sibling_size);
     }
     return proof;
@@ -62,9 +62,9 @@ complete_merkle_tree::proof_type complete_merkle_tree::get_proof(address_type ad
 
 /// \brief Appends a new leaf hash to the tree
 /// \param hash Hash to append
-void complete_merkle_tree::push_back(const hash_type &hash) {
+void complete_merkle_tree::push_back(const machine_hash &hash) {
     auto &leaves = get_level(get_log2_leaf_size());
-    if (leaves.size() >= address_type{1} << (get_log2_root_size() - get_log2_leaf_size())) {
+    if (leaves.size() >= UINT64_C(1) << (get_log2_root_size() - get_log2_leaf_size())) {
         throw std::out_of_range{"tree is full"};
     }
     leaves.push_back(hash);
@@ -87,15 +87,15 @@ void complete_merkle_tree::check_log2_sizes(int log2_root_size, int log2_leaf_si
     if (log2_word_size > log2_leaf_size) {
         throw std::out_of_range{"log2_word_size is greater than log2_word_size"};
     }
-    if (log2_root_size >= std::numeric_limits<address_type>::digits) {
+    if (log2_root_size >= std::numeric_limits<uint64_t>::digits) {
         throw std::out_of_range{"tree is too large for address type"};
     }
 }
 
-const complete_merkle_tree::hash_type &complete_merkle_tree::get_node_hash(address_type address, int log2_size) const {
+const machine_hash &complete_merkle_tree::get_node_hash(uint64_t address, int log2_size) const {
     const auto &level = get_level(log2_size);
     address >>= log2_size;
-    if (address >= (address_type{1} << (get_log2_root_size() - log2_size))) {
+    if (address >= (UINT64_C(1) << (get_log2_root_size() - log2_size))) {
         throw std::out_of_range{"log2_size is out of bounds"};
     }
     if (address < level.size()) {
diff --git a/src/complete-merkle-tree.h b/src/complete-merkle-tree.h
index 72d3e8fea..b9205d1bf 100644
--- a/src/complete-merkle-tree.h
+++ b/src/complete-merkle-tree.h
@@ -22,6 +22,7 @@
 #include <vector>
 
 #include "keccak-256-hasher.h"
+#include "machine-hash.h"
 #include "merkle-tree-proof.h"
 #include "meta.h"
 #include "pristine-merkle-tree.h"
@@ -41,17 +42,11 @@ class complete_merkle_tree {
     /// \brief Hasher class.
     using hasher_type = keccak_256_hasher;
 
-    /// \brief Storage for a hash.
-    using hash_type = hasher_type::hash_type;
-
-    /// \brief Storage for an address.
-    using address_type = uint64_t;
-
     /// \brief Storage for a proof.
-    using proof_type = merkle_tree_proof<hash_type, address_type>;
+    using proof_type = merkle_tree_proof;
 
     /// \brief Storage for a level in the tree.
-    using level_type = std::vector<hash_type>;
+    using level_type = std::vector<machine_hash>;
 
     /// \brief Constructor for pristine tree
     /// \param log2_root_size Log<sub>2</sub> of tree size
@@ -73,27 +68,27 @@ class complete_merkle_tree {
 
     /// \brief Returns the tree's root hash
     /// \returns Root hash
-    hash_type get_root_hash() const {
+    machine_hash get_root_hash() const {
         return get_node_hash(0, get_log2_root_size());
     }
 
     /// \brief Returns the hash of a node at a given address of a given size
     /// \param address Node address
     /// \param log2_size Log<sub>2</sub> size subintended by node
-    const hash_type &get_node_hash(address_type address, int log2_size) const;
+    const machine_hash &get_node_hash(uint64_t address, int log2_size) const;
 
     /// \brief Returns proof for a given node
     /// \param address Node address
     /// \param log2_size Log<sub>2</sub> size subintended by node
     /// \returns Proof, or throws exception
-    proof_type get_proof(address_type address, int log2_size) const;
+    proof_type get_proof(uint64_t address, int log2_size) const;
 
     /// \brief Appends a new leaf hash to the tree
     /// \param hash Hash to append
-    void push_back(const hash_type &hash);
+    void push_back(const machine_hash &hash);
 
     /// \brief Returns number of leaves in tree
-    address_type size() const {
+    uint64_t size() const {
         return get_level(get_log2_leaf_size()).size();
     };
 
diff --git a/src/concepts.h b/src/concepts.h
new file mode 100644
index 000000000..fe02342ca
--- /dev/null
+++ b/src/concepts.h
@@ -0,0 +1,58 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef CONCEPTS_H
+#define CONCEPTS_H
+
+#include <ranges>
+
+/// \file
+/// \brief Concepts helper functions.
+
+namespace cartesi {
+
+// C++20 concept for a POD type
+template <typename T>
+concept POD = std::is_trivially_copyable_v<T> && std::is_standard_layout_v<T>;
+
+// C++20 concept for something that is just like a byte
+template <typename T>
+concept ByteLike = POD<T> && (sizeof(T) == 1);
+
+// C++20 concept for a contiguous range of byte-like elements
+template <typename D>
+concept ContiguousRangeOfByteLike =
+    std::ranges::contiguous_range<D> && ByteLike<std::ranges::range_value_t<std::remove_cvref_t<D>>>;
+
+// C++20 concept for a (not necessarily contiguous) range of byte-like elements
+template <typename D>
+concept RangeOfByteLike = std::ranges::range<D> && ByteLike<std::ranges::range_value_t<std::remove_cvref_t<D>>>;
+
+// C++20 concept comparing types while ignoring const, volatile, reference
+template <typename T, typename U>
+concept SameAsNoCVRef = std::same_as<std::remove_cvref_t<T>, std::remove_cvref_t<U>>;
+
+// C++20 concept to check for scoped enums
+template <typename E>
+concept ScopedEnum = std::is_enum_v<E> && !std::is_convertible_v<E, std::underlying_type_t<E>>;
+
+// C++20 concept to check for multiple accepted types
+template <typename T, typename... Ts>
+concept SameAsAny = (std::same_as<T, Ts> || ...);
+
+} // namespace cartesi
+
+#endif
diff --git a/src/dense-hash-tree.h b/src/dense-hash-tree.h
new file mode 100644
index 000000000..1c0bae7a1
--- /dev/null
+++ b/src/dense-hash-tree.h
@@ -0,0 +1,108 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef DENSE_HASH_TREE_H
+#define DENSE_HASH_TREE_H
+
+#include <vector>
+
+#include "hash-tree-constants.h"
+#include "i-dense-hash-tree.h"
+#include "machine-hash.h"
+
+namespace cartesi {
+
+class dense_hash_tree : public i_dense_hash_tree {
+
+    using container_type = std::vector<machine_hash>;
+    using size_type = container_type::size_type;
+
+    static constexpr auto invalid_index = std::numeric_limits<size_type>::max();
+
+    static int check_level_count(int level_count, size_type leaf_count) {
+        if (level_count < 0) {
+            throw std::invalid_argument{"level count must be non-negative"};
+        }
+        if (level_count > 0 && leaf_count > (size_type{1} << (level_count - 1))) {
+            throw std::invalid_argument{"too many leaves for level count"};
+        }
+        if (level_count == 0 && leaf_count != 0) {
+            throw std::invalid_argument{"too many leaves for level count"};
+        }
+        // Make sure we can allocate a vector of size 1 << level_count
+        if ((container_type{}.max_size() >> level_count) == 0) {
+            throw std::invalid_argument{"too many levels"};
+        }
+        return level_count;
+    }
+
+    static constexpr int m_log2_page_size = HASH_TREE_LOG2_PAGE_SIZE;
+    static constexpr int m_log2_word_size = HASH_TREE_LOG2_WORD_SIZE;
+
+public:
+    dense_hash_tree(int level_count, size_type leaf_count) :
+        m_level_count{check_level_count(level_count, leaf_count)},
+        m_storage{size_type{1} << level_count} {}
+
+    machine_hash_view do_node_hash_view(uint64_t offset, int log2_size) noexcept override {
+        if (auto index = to_index(offset, log2_size); index != invalid_index) {
+            return machine_hash_view{m_storage[index]};
+        }
+        return no_hash_view();
+    }
+
+    const_machine_hash_view do_node_hash_view(uint64_t offset, int log2_size) const noexcept override {
+        if (auto index = to_index(offset, log2_size); index != invalid_index) {
+            return const_machine_hash_view{m_storage[index]};
+        }
+        return no_hash_view();
+    }
+
+    const_machine_hash_view do_root_hash_view() const noexcept override {
+        if (m_level_count != 0) {
+            return m_storage[1];
+        }
+        return no_hash_view();
+    }
+
+private:
+    /// \brief Converts a node size to its level in the tree
+    /// \param log2_size Log<sub>2</sub> of node size
+    /// \returns Corresponding level (which may be out of range)
+    static int to_level(int log2_size) noexcept {
+        return log2_size - static_cast<int>(AR_LOG2_PAGE_SIZE);
+    }
+
+    size_type to_index(uint64_t offset, int log2_size) const {
+        const int level = to_level(log2_size);
+        if (level < 0 || level >= m_level_count) {
+            return invalid_index;
+        }
+        const size_type start = size_type{1} << (m_level_count - level - 1);
+        const size_type index = offset >> log2_size;
+        if (index >= start) {
+            return invalid_index;
+        }
+        return start + index;
+    }
+
+    int m_level_count;
+    std::vector<machine_hash> m_storage;
+};
+
+} // namespace cartesi
+
+#endif // PAGE_HASH_TREE_CACHE_H
diff --git a/src/dirty-page-tree.h b/src/dirty-page-tree.h
new file mode 100644
index 000000000..85d5de0e9
--- /dev/null
+++ b/src/dirty-page-tree.h
@@ -0,0 +1,334 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef DIRTY_PAGE_TREE_H
+#define DIRTY_PAGE_TREE_H
+
+/// \file
+/// \brief Dirty map as a complete tree
+
+#include <algorithm>
+#include <concepts>
+#include <cstdint>
+#include <iostream>
+#include <iterator>
+#include <ranges>
+#include <stdexcept>
+
+#include "i-dirty-page-tree.h"
+#include "ranges.h"
+
+namespace cartesi {
+
+/// \brief Dirty page tree
+class dirty_page_tree : public i_dirty_page_tree {
+public:
+    /// \brief Each node in tree is either clean or dirty
+    enum class status_type : uint8_t { clean, dirty };
+
+private:
+    using container_type = std::vector<status_type>;
+
+    /// \brief Checks if we can represent a tree with this many levels
+    static int check_level_count(int level_count, size_type leaf_count) {
+        if (level_count < 0) {
+            throw std::invalid_argument{"level count must be non-negative"};
+        }
+        if (level_count > 0 && leaf_count > (size_type{1} << (level_count - 1))) {
+            throw std::invalid_argument{"too many leaves for level count"};
+        }
+        if (level_count == 0 && leaf_count != 0) {
+            throw std::invalid_argument{"too many leaves for level count"};
+        }
+        // Make sure we can allocate a vector of size 1 << level_count
+        if ((container_type{}.max_size() >> level_count) == 0) {
+            throw std::invalid_argument{"too many levels"};
+        }
+        // Make sure we can address position 1 << level_count
+        if ((std::numeric_limits<position_iterator::value_type>::max() >> level_count) == 0) {
+            throw std::invalid_argument{"too many levels"};
+        }
+        return level_count;
+    }
+
+public:
+    /// \brief Constructor for leaves marked the same way
+    /// \param leaf_count Number of leaves in tree. This is rounded up to the next power of 2.
+    /// \param init Status of the first \p leaf_count leaves (the ones past leaf_count start clean)
+    explicit dirty_page_tree(int level_count, size_type leaf_count, status_type init = status_type::dirty) :
+        i_dirty_page_tree{check_level_count(level_count, leaf_count)},
+        m_leaf_positions{level_positions_view(0)},
+        m_valid_positions{position_iterator(1), position_iterator(position_iterator::value_type{1} << level_count)},
+        m_tree{typename container_type::size_type{1} << level_count, init} {
+        // Leaves past leaf_count start clean because they don't really exist
+        if (init != status_type::clean) {
+            auto past_leaf_count = m_tree | std::views::drop(leaf_positions_view().front() + leaf_count);
+            std::ranges::fill(past_leaf_count, status_type::clean);
+        }
+    }
+
+    /// \brief Constructor from initializer list
+    /// \param leaves Status of first few leaves in tree.
+    /// \details This is a constructor mostly used in simple tests
+    explicit dirty_page_tree(int level_count, std::initializer_list<status_type> leaves) :
+        dirty_page_tree{level_count, leaves.size(), status_type::clean} {
+        std::ranges::copy(leaves, &m_tree[leaf_positions_view().front()]);
+        for (auto level : levels_view() | std::views::drop(1)) {
+            for (auto pos : views::iterators(level_positions_view(level))) {
+                if (is_dirty_position(get_left_child_position(pos)) ||
+                    is_dirty_position(get_right_child_position(pos))) {
+                    m_tree[*pos] = status_type::dirty;
+                }
+            }
+        }
+    }
+
+    // Dump tree in DOT format
+    void dump() const {
+        std::cout << "digraph HashTree {\n";
+        std::cout << "    node [shape=circle, width=0.5, height=0.5, fixedsize=true, style=filled];\n";
+        std::cout << "  subgraph Dirty {\n";
+        for (auto pos : views::iterators(valid_positions_view())) {
+            if (is_dirty_position(pos)) {
+                std::cout << "    A" << *pos << "[fillcolor=gray, label=\"" << *pos << "\"];\n";
+            }
+        }
+        std::cout << "  }\n";
+        std::cout << "  subgraph Clean {\n";
+        for (auto pos : views::iterators(valid_positions_view())) {
+            if (is_clean_position(pos)) {
+                std::cout << "    A" << *pos << "[fillcolor=white, label=\"" << *pos << "\"];\n";
+            }
+        }
+        std::cout << "  }\n";
+        for (auto level : levels_view()) {
+            std::cout << "  { rank = same; ";
+            for (auto pos : level_positions_view(level)) {
+                std::cout << "A" << pos << "; ";
+            }
+            std::cout << "}\n";
+        }
+        dump_edges();
+        for (auto level : levels_view()) {
+            const auto bounds = level_positions_view(level);
+            for (auto pos : std::views::iota(bounds.begin(), bounds.end() - 1)) {
+                std::cout << "  A" << *pos << " -> A" << *pos + 1 << " [style=invis];\n";
+            }
+        }
+        std::cout << "}\n";
+    }
+
+private:
+    /// \brief Returns view of all valid positions (for use with range-based for loops)
+    positions_range leaf_positions_view() const {
+        return m_leaf_positions;
+    }
+
+    /// \brief Returns position of left child of a node
+    /// \param pos Position of node
+    /// \returns Position of its left child
+    static constexpr position_iterator get_left_child_position(position_iterator pos) {
+        return position_iterator{(*pos) * 2};
+    }
+
+    /// \brief Returns position of right child of a node
+    /// \param node Position of node
+    /// \returns Position of its right child
+    static constexpr position_iterator get_right_child_position(position_iterator pos) {
+        return position_iterator{((*pos) * 2) + 1};
+    }
+
+    /// \brief Returns position of parent of a node
+    /// \param node Position of node
+    /// \returns Position of its parent
+    static constexpr position_iterator get_parent_position(position_iterator pos) {
+        return position_iterator{(*pos) / 2};
+    }
+
+    /// \brief Returns position of sibling a node
+    /// \param node Position of node
+    /// \returns Position of its sibling
+    static constexpr position_iterator get_sibling_position(position_iterator pos) {
+        return position_iterator{(*pos) ^ 1};
+    }
+
+    /// \brief Returns position of left sibling a node
+    /// \param node Position of node
+    /// \returns Position of its left sibling (which can be the node itself)
+    static constexpr position_iterator get_left_sibling_position(position_iterator pos) {
+        constexpr auto left_mask = ~position_iterator::value_type{1};
+        return position_iterator{(*pos) & left_mask};
+    }
+
+    /// \brief Returns position of right sibling a node
+    /// \param node Position of node
+    /// \returns Position of its right sibling (which can be the node itself)
+    static constexpr position_iterator get_right_sibling_position(position_iterator pos) {
+        return position_iterator{(*pos) | 1};
+    }
+
+    /// \brief Returns position of root node
+    /// \returns Position of root node
+    static constexpr position_iterator get_root_position() {
+        return position_iterator{1};
+    }
+
+    /// \brief Checks if a node belongs to a given level
+    /// \param pos Position of node
+    /// \param bounds Position bounds
+    /// \returns True if node is within bounds, false otherwise
+    static constexpr bool is_position_in(position_iterator pos, positions_range bounds) {
+        return pos >= bounds.begin() && pos < bounds.end();
+    }
+
+    /// \brief Returns view of all valid positions (for use with range-based for loops)
+    positions_range valid_positions_view() const {
+        return m_valid_positions;
+    }
+
+    /// \brief Checks if position valid for a node
+    /// \param node Position of node
+    /// \returns True if valid, false otherwise
+    bool is_valid_position(position_iterator pos) const {
+        return is_position_in(pos, valid_positions_view());
+    }
+
+    /// \brief Skip over clean nodes to reach the next dirty node
+    /// \details The idea is to go up the tree until we are at a left sibling with a dirty right sibling,
+    /// then go down, going left whenever the left child is dirty, until we are back at the correct level
+    void up_then_down(position_iterator &pos, positions_range level) const {
+        if (!is_valid_position(pos)) {
+            pos = invalid_position;
+            return;
+        }
+        while (pos != get_root_position()) {
+            if (pos == get_left_sibling_position(pos)) {
+                const auto r = get_right_sibling_position(pos);
+                if (is_dirty_position(r)) {
+                    pos = r;
+                    down(pos, level);
+                    return;
+                }
+            }
+            pos = get_parent_position(pos);
+        }
+        pos = invalid_position;
+    }
+
+    void down(position_iterator &pos, positions_range level) const {
+        while (!is_position_in(pos, level)) {
+            auto el = get_left_child_position(pos);
+            if (!is_dirty_position(el)) {
+                auto r = get_right_child_position(pos);
+                if (!is_dirty_position(r)) {
+                    // no more dirty entries
+                    pos = invalid_position;
+                    return;
+                }
+                pos = r;
+            } else {
+                pos = el;
+            }
+        }
+    }
+
+    /// \brief Checks if node at valid position is dirty
+    /// \param node Position of node
+    /// \returns True if dirty, false otherwise
+    bool is_dirty_position(position_iterator pos) const {
+        return m_tree[*pos] == status_type::dirty;
+    }
+
+    /// \brief Checks if node at valid position is clean
+    /// \param node Position of node
+    /// \returns True if clean, false otherwise
+    bool is_clean_position(position_iterator pos) const {
+        return m_tree[*pos] == status_type::clean;
+    }
+
+    // Dump tree edges in DOT format
+    void dump_edges(position_iterator pos = get_root_position()) const {
+        if (is_valid_position(get_left_child_position(pos))) {
+            auto el = get_left_child_position(pos);
+            std::cout << "  A" << *pos << " -> A" << *el << ";\n";
+            auto r = get_right_child_position(pos);
+            std::cout << "  A" << *pos << " -> A" << *r << ";\n";
+            dump_edges(el);
+            dump_edges(r);
+        }
+    }
+
+    // -----
+    // i_dirty_page_tree interface
+    // -----
+
+    /// \brief Advances a position to the next dirty position within a level
+    void do_advance_dirty_position(position_iterator &pos, positions_range level) const noexcept override {
+        up_then_down(pos, level);
+    }
+
+    /// \brief Marks the node at given position clean (and all its ancestors that only have clean descendants)
+    /// \param pos Leaf position
+    /// \details Assumes \p pos points to a leaf position
+    void do_mark_clean_leaf_position_and_up([[maybe_unused]] position_iterator pos) noexcept override {
+        while (pos != get_root_position()) {
+            m_tree[*pos] = status_type::clean;
+            if (m_tree[*get_sibling_position(pos)] != status_type::clean) {
+                return;
+            }
+            pos = get_parent_position(pos);
+        }
+        m_tree[*get_root_position()] = status_type::clean;
+    }
+
+    /// \brief Marks the leaf at a given position dirty (and all its ancestors as well)
+    /// \param pos Position of leaf node
+    /// \details Assumes \p pos points to a leaf position
+    void do_mark_dirty_leaf_position_and_up(position_iterator pos) noexcept override {
+        while (pos != get_root_position()) {
+            if (m_tree[*pos] == status_type::dirty) {
+                return;
+            }
+            m_tree[*pos] = status_type::dirty;
+            pos = get_parent_position(pos);
+        }
+        m_tree[*get_root_position()] = status_type::dirty;
+    }
+
+    /// \brief Tells if the node at given position is dirty
+    bool do_is_dirty_position(position_iterator pos) const noexcept override {
+        return is_dirty_position(pos);
+    }
+
+    /// \brief Clean entire tree
+    void do_clean() noexcept override {
+        for (auto pos : dirty_positions_view(leaf_positions_view())) {
+            do_mark_clean_leaf_position_and_up(pos);
+        }
+    }
+
+    // -----
+    // Fields
+    // -----
+
+    positions_range m_leaf_positions;  // Bounds on leaf positions
+    positions_range m_valid_positions; // Bounds on all positions
+    container_type m_tree;             // Complete tree of flags
+};
+
+} // namespace cartesi
+
+#endif // DIRTY_PAGE_TREE_H
diff --git a/src/full-merkle-tree.cpp b/src/full-merkle-tree.cpp
index e59cad55d..286673a1c 100644
--- a/src/full-merkle-tree.cpp
+++ b/src/full-merkle-tree.cpp
@@ -32,17 +32,17 @@ namespace cartesi {
 full_merkle_tree::full_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size) :
     m_log2_root_size{log2_root_size},
     m_log2_leaf_size{log2_leaf_size},
-    m_max_leaves{address_type{1} << std::max(0, log2_root_size - log2_leaf_size)} {
+    m_max_leaves{UINT64_C(1) << std::max(0, log2_root_size - log2_leaf_size)} {
     check_log2_sizes(log2_root_size, log2_leaf_size, log2_word_size);
     m_tree.resize(2 * m_max_leaves);
     init_pristine_subtree(pristine_merkle_tree{log2_root_size, log2_word_size}, 1, log2_root_size);
 }
 
 full_merkle_tree::full_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size,
-    const std::vector<hash_type> &leaves) :
+    const std::vector<machine_hash> &leaves) :
     m_log2_root_size(log2_root_size),
     m_log2_leaf_size(log2_leaf_size),
-    m_max_leaves{address_type{1} << std::max(0, log2_root_size - log2_leaf_size)} {
+    m_max_leaves{UINT64_C(1) << std::max(0, log2_root_size - log2_leaf_size)} {
     check_log2_sizes(log2_root_size, log2_leaf_size, log2_word_size);
     if (leaves.size() > m_max_leaves) {
         throw std::out_of_range{"too many leaves"};
@@ -51,7 +51,7 @@ full_merkle_tree::full_merkle_tree(int log2_root_size, int log2_leaf_size, int l
     init_tree(pristine_merkle_tree{log2_root_size, log2_word_size}, leaves);
 }
 
-full_merkle_tree::proof_type full_merkle_tree::get_proof(address_type address, int log2_size) const {
+full_merkle_tree::proof_type full_merkle_tree::get_proof(uint64_t address, int log2_size) const {
     if (log2_size < get_log2_leaf_size() || log2_size > get_log2_root_size()) {
         throw std::out_of_range{"log2_size is out of bounds"};
     }
@@ -64,7 +64,7 @@ full_merkle_tree::proof_type full_merkle_tree::get_proof(address_type address, i
     proof.set_target_address(address);
     proof.set_target_hash(get_node_hash(address, log2_size));
     for (int log2_sibling_size = log2_size; log2_sibling_size < get_log2_root_size(); ++log2_sibling_size) {
-        auto sibling_address = address ^ (address_type{1} << log2_sibling_size);
+        auto sibling_address = address ^ (UINT64_C(1) << log2_sibling_size);
         proof.set_sibling_hash(get_node_hash(sibling_address, log2_sibling_size), log2_sibling_size);
     }
 #ifndef NDEBUG
@@ -92,7 +92,7 @@ void full_merkle_tree::check_log2_sizes(int log2_root_size, int log2_leaf_size,
     if (log2_word_size > log2_leaf_size) {
         throw std::out_of_range{"log2_word_size is greater than log2_word_size"};
     }
-    if (log2_root_size >= std::numeric_limits<address_type>::digits) {
+    if (log2_root_size >= std::numeric_limits<uint64_t>::digits) {
         throw std::out_of_range{"tree is too large for address type"};
     }
 }
@@ -113,7 +113,7 @@ void full_merkle_tree::init_subtree(hasher_type &h, int index, int log2_size) {
     }
 }
 
-void full_merkle_tree::init_tree(const pristine_merkle_tree &pristine, const std::vector<hash_type> &leaves) {
+void full_merkle_tree::init_tree(const pristine_merkle_tree &pristine, const std::vector<machine_hash> &leaves) {
     std::copy(leaves.begin(), leaves.end(), &m_tree[m_max_leaves]);
     std::fill_n(&m_tree[m_max_leaves + leaves.size()], m_max_leaves - leaves.size(),
         pristine.get_hash(get_log2_leaf_size()));
@@ -121,11 +121,11 @@ void full_merkle_tree::init_tree(const pristine_merkle_tree &pristine, const std
     init_subtree(h, 1, get_log2_root_size());
 }
 
-full_merkle_tree::address_type full_merkle_tree::get_node_index(address_type address, int log2_size) const {
+uint64_t full_merkle_tree::get_node_index(uint64_t address, int log2_size) const {
     if (log2_size < get_log2_leaf_size() || log2_size > get_log2_root_size()) {
         throw std::out_of_range{"log2_size is out of bounds"};
     }
-    const address_type base = address_type{1} << (get_log2_root_size() - log2_size);
+    const uint64_t base = UINT64_C(1) << (get_log2_root_size() - log2_size);
     // Nodes of log2_size live in indices [base, 2*base)
     // 0 <unused>
     // 1 log2_root_size
diff --git a/src/full-merkle-tree.h b/src/full-merkle-tree.h
index cc3035538..2c460b24f 100644
--- a/src/full-merkle-tree.h
+++ b/src/full-merkle-tree.h
@@ -21,6 +21,7 @@
 #include <vector>
 
 #include "keccak-256-hasher.h"
+#include "machine-hash.h"
 #include "merkle-tree-proof.h"
 #include "pristine-merkle-tree.h"
 
@@ -36,14 +37,8 @@ class full_merkle_tree {
     /// \brief Hasher class.
     using hasher_type = keccak_256_hasher;
 
-    /// \brief Storage for a hash.
-    using hash_type = hasher_type::hash_type;
-
-    /// \brief Storage for an address.
-    using address_type = uint64_t;
-
     /// \brief Storage for a proof.
-    using proof_type = merkle_tree_proof<hash_type, address_type>;
+    using proof_type = merkle_tree_proof;
 
     /// \brief Constructor for a pristine tree
     /// \param log2_root_size Log<sub>2</sub> of root node
@@ -56,7 +51,8 @@ class full_merkle_tree {
     /// \param log2_leaf_size Log<sub>2</sub> of leaf node
     /// \param log2_word_size Log<sub>2</sub> of word
     /// \param leaves List of leaf hashes
-    full_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size, const std::vector<hash_type> &leaves);
+    full_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size,
+        const std::vector<machine_hash> &leaves);
 
     /// \brief Returns log<sub>2</sub> of size of tree
     int get_log2_root_size() const {
@@ -70,14 +66,14 @@ class full_merkle_tree {
 
     /// \brief Returns the tree's root hash
     /// \returns Root hash
-    const hash_type &get_root_hash() const {
+    const machine_hash &get_root_hash() const {
         return get_node_hash(0, get_log2_root_size());
     }
 
     /// \brief Returns the hash of a node at a given address of a given size
     /// \param address Node address
     /// \param log2_size Log<sub>2</sub> size subintended by node
-    const hash_type &get_node_hash(address_type address, int log2_size) const {
+    const machine_hash &get_node_hash(uint64_t address, int log2_size) const {
         return m_tree[get_node_index(address, log2_size)];
     }
 
@@ -85,7 +81,7 @@ class full_merkle_tree {
     /// \param address Node address
     /// \param log2_size Log<sub>2</sub> size subintended by node
     /// \returns Proof, or throws exception
-    proof_type get_proof(address_type address, int log2_size) const;
+    proof_type get_proof(uint64_t address, int log2_size) const;
 
 private:
     /// \brief Throws exception if log<sub>2</sub> sizes are inconsistent
@@ -125,17 +121,17 @@ class full_merkle_tree {
     /// \details The page hashes in leaves are copied to the appropriate
     /// subtree nodes, in order, and the rest are filled with pristine
     /// page hashes
-    void init_tree(const pristine_merkle_tree &pristine, const std::vector<hash_type> &leaves);
+    void init_tree(const pristine_merkle_tree &pristine, const std::vector<machine_hash> &leaves);
 
     /// \brief Returns index of a node in the tree array
     /// \param address Node address
     /// \param log2_size
-    address_type get_node_index(address_type address, int log2_size) const;
+    uint64_t get_node_index(uint64_t address, int log2_size) const;
 
-    int m_log2_root_size;          ///< Log<sub>2</sub> of tree size
-    int m_log2_leaf_size;          ///< Log<sub>2</sub> of leaf size
-    address_type m_max_leaves;     ///< Maximum number of leaves
-    std::vector<hash_type> m_tree; ///< Binary heap with tree node hashes
+    int m_log2_root_size;             ///< Log<sub>2</sub> of tree size
+    int m_log2_leaf_size;             ///< Log<sub>2</sub> of leaf size
+    uint64_t m_max_leaves;            ///< Maximum number of leaves
+    std::vector<machine_hash> m_tree; ///< Binary heap with tree node hashes
 };
 
 } // namespace cartesi
diff --git a/src/hash-tree-constants.h b/src/hash-tree-constants.h
new file mode 100644
index 000000000..67ea14ba5
--- /dev/null
+++ b/src/hash-tree-constants.h
@@ -0,0 +1,32 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef HASH_TREE_CONSTANTS_H
+#define HASH_TREE_CONSTANTS_H
+
+#include <cstdint>
+
+namespace cartesi {
+
+const constexpr int HASH_TREE_LOG2_ROOT_SIZE = 64;
+const constexpr int HASH_TREE_LOG2_WORD_SIZE = 5;
+const constexpr uint64_t HASH_TREE_WORD_SIZE = UINT64_C(1) << HASH_TREE_LOG2_WORD_SIZE;
+const constexpr int HASH_TREE_LOG2_PAGE_SIZE = 12;
+const constexpr uint64_t HASH_TREE_PAGE_SIZE = UINT64_C(1) << HASH_TREE_LOG2_PAGE_SIZE;
+
+} // namespace cartesi
+
+#endif
diff --git a/src/hash-tree.cpp b/src/hash-tree.cpp
new file mode 100644
index 000000000..abb050214
--- /dev/null
+++ b/src/hash-tree.cpp
@@ -0,0 +1,845 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#include "hash-tree.h"
+
+#include <atomic>
+#include <bit>
+#include <iostream>
+#include <queue>
+#include <ranges>
+#include <string>
+#include <utility>
+
+#include <omp.h>
+
+#include "machine-address-ranges.h"
+
+#ifdef __APPLE__
+#define CONCAT(x, y) x##y
+
+#define SCOPED_SIGNPOST_IMPL(log, id, name, line, ...)                                                                 \
+    struct CONCAT(scoped_signpost_, line) {                                                                            \
+        os_log_t m_log;                                                                                                \
+        os_signpost_id_t m_id;                                                                                         \
+        CONCAT(scoped_signpost_, line)(os_log_t l, os_signpost_id_t i) : m_log(l), m_id(i) {                           \
+            os_signpost_interval_begin(l, i, name, __VA_ARGS__);                                                       \
+        }                                                                                                              \
+        ~CONCAT(scoped_signpost_, line)() {                                                                            \
+            os_signpost_interval_end(m_log, m_id, name, __VA_ARGS__);                                                  \
+        }                                                                                                              \
+    } CONCAT(signpost_instance_, line)(log, id)
+
+#define SCOPED_SIGNPOST(log, id, name, ...) SCOPED_SIGNPOST_IMPL(log, id, name, __LINE__, __VA_ARGS__)
+#else
+#define SCOPED_SIGNPOST(log, id, name, ...)
+#endif
+
+namespace cartesi {
+
+using namespace std::string_literals;
+
+static inline machine_hash to_hash(const_machine_hash_view view) {
+    machine_hash hash;
+    std::ranges::copy(view, hash.begin());
+    return hash;
+}
+
+const_machine_hash_view hash_tree::get_sparse_node_hash_view(index_type node_index, int log2_size) const noexcept {
+    // Pristine node
+    if (is_pristine(node_index)) {
+        return const_machine_hash_view{m_pristine_hashes[log2_size]};
+    }
+    return m_sparse_nodes[node_index].hash;
+}
+
+void hash_tree::get_pristine_proof(int curr_log2_size, proof_type &proof) const {
+    const auto log2_target_size = proof.get_log2_target_size();
+    for (int log2_size = curr_log2_size - 1; log2_size >= log2_target_size; --log2_size) {
+        proof.set_sibling_hash(m_pristine_hashes[log2_size], log2_size);
+    }
+    proof.set_target_hash(m_pristine_hashes[log2_target_size]);
+}
+
+static inline uint64_t get_sibling_address(uint64_t address, int log2_size) {
+    const uint64_t bit = UINT64_C(1) << log2_size;
+    const uint64_t mask = ~(bit - 1);
+    return (address ^ bit) & mask;
+}
+
+static inline uint64_t get_aligned_address(uint64_t address, int log2_size) {
+    const uint64_t bit = UINT64_C(1) << log2_size;
+    const uint64_t mask = ~(bit - 1);
+    return address & mask;
+}
+
+void hash_tree::get_page_proof(address_range &ar, uint64_t address, proof_type &proof) {
+    const auto paddr_page = address & ~(HASH_TREE_PAGE_SIZE - 1);
+    bool hit = false;
+    auto opt_br = m_page_cache.borrow_entry(paddr_page, hit);
+    assert(opt_br && "page hash-tree cache has no entries to lend");
+    if (!hit) {
+        hasher_type h;
+        [[maybe_unused]] bool changed = false;
+        update_dirty_page(h, ar, opt_br->get(), changed);
+    }
+    const auto log2_target_size = proof.get_log2_target_size();
+    assert(log2_target_size >= HASH_TREE_LOG2_WORD_SIZE && "log2_size is too small");
+    const auto &entry = opt_br->get();
+    const auto node_offset = address & (HASH_TREE_PAGE_SIZE - 1);
+    for (int log2_size = HASH_TREE_LOG2_PAGE_SIZE - 1; log2_size >= log2_target_size; --log2_size) {
+        proof.set_sibling_hash(entry.node_hash_view(get_sibling_address(node_offset, log2_size), log2_size), log2_size);
+    }
+    proof.set_target_hash(entry.node_hash_view(node_offset, log2_target_size));
+    m_page_cache.return_entry(*opt_br);
+}
+
+void hash_tree::get_dense_proof(address_range &ar, int ar_log2_size, uint64_t address, proof_type &proof) {
+    const auto &dht = ar.get_dense_hash_tree();
+    const auto log2_target_size = proof.get_log2_target_size();
+    const auto dht_end = std::max<int>(HASH_TREE_LOG2_PAGE_SIZE, log2_target_size);
+    const auto node_offset = address - ar.get_start();
+    for (int log2_size = ar_log2_size - 1; log2_size >= dht_end; --log2_size) {
+        const auto sibling_offset = get_sibling_address(node_offset, log2_size);
+        proof.set_sibling_hash(dht.node_hash_view(sibling_offset, log2_size), log2_size);
+    }
+    if (log2_target_size >= HASH_TREE_LOG2_PAGE_SIZE) {
+        proof.set_target_hash(dht.node_hash_view(node_offset, log2_target_size));
+    } else {
+        get_page_proof(ar, address, proof);
+    }
+}
+
+hash_tree::proof_type hash_tree::get_proof(address_ranges ars, uint64_t address, int log2_size) {
+    if (log2_size < HASH_TREE_LOG2_WORD_SIZE || log2_size > HASH_TREE_LOG2_ROOT_SIZE) {
+        throw std::domain_error{"invalid log2_size"};
+    }
+    if (log2_size == HASH_TREE_LOG2_ROOT_SIZE) {
+        if (address != 0) {
+            throw std::domain_error{"address not aligned to log2_size"};
+        }
+    } else if (((address >> log2_size) << log2_size) != address) {
+        throw std::domain_error{"address not aligned to log2_size"};
+    }
+    proof_type proof{HASH_TREE_LOG2_ROOT_SIZE, log2_size};
+    proof.set_target_address(address);
+    proof.set_root_hash(get_root_hash());
+    index_type node_index = 1;
+    int curr_log2_size = HASH_TREE_LOG2_ROOT_SIZE;
+    for (;;) {
+        // hit pristine node
+        if (is_pristine(node_index)) {
+            get_pristine_proof(curr_log2_size, proof);
+            return proof;
+        }
+        const auto &node = m_sparse_nodes[node_index];
+        assert(static_cast<int>(node.log2_size) == curr_log2_size && "incorrect node log2_size");
+        // hit sparse tree node
+        if (curr_log2_size == log2_size) {
+            proof.set_target_hash(node.hash);
+            return proof;
+        }
+        // transition to dense tree
+        if (is_ar_node(node)) {
+            auto &ar = ars[node.right];
+            const int ar_log2_size = HASH_TREE_LOG2_PAGE_SIZE + ar.get_level_count() - 1;
+            assert(curr_log2_size == ar_log2_size && "incorrect ar node log2_size");
+            get_dense_proof(ar, ar_log2_size, address, proof);
+            return proof;
+        }
+        // go down left or right on sparse tree depending on address
+        --curr_log2_size;
+        if ((address & (UINT64_C(1) << curr_log2_size)) == 0) {
+            proof.set_sibling_hash(get_sparse_node_hash_view(node.right, curr_log2_size), curr_log2_size);
+            node_index = node.left;
+        } else {
+            proof.set_sibling_hash(get_sparse_node_hash_view(node.left, curr_log2_size), curr_log2_size);
+            node_index = node.right;
+        }
+    }
+}
+
+void hash_tree::clear_stats() {
+    m_page_cache.clear_stats();
+#ifdef DUMP_HASH_TREE_STATS
+    m_sparse_node_hashes = 0;
+    for (auto &a : m_dense_node_hashes) {
+        a = 0;
+    }
+#endif
+}
+
+bool hash_tree::update_dirty_page(hasher_type &h, address_range &ar, page_hash_tree_cache::entry &entry,
+    bool &changed) {
+    const auto paddr_page = entry.get_paddr_page();
+    const auto *base = ar.get_host_memory();
+    if (!ar.is_memory() || base == nullptr || !ar.contains_absolute(paddr_page, HASH_TREE_PAGE_SIZE)) {
+        return false;
+    }
+    const auto offset = paddr_page - ar.get_start();
+    const auto page_view = std::span<const unsigned char, HASH_TREE_PAGE_SIZE>{base + offset, HASH_TREE_PAGE_SIZE};
+    auto ret = entry.update(h, page_view, m_page_cache.get_pristine_page_hash_tree());
+    auto node_hash_view = ar.get_dense_hash_tree().node_hash_view(offset, HASH_TREE_LOG2_PAGE_SIZE);
+    changed = !std::ranges::equal(entry.root_hash_view(), node_hash_view);
+    if (changed) {
+        std::ranges::copy(entry.root_hash_view(), node_hash_view.begin());
+    }
+    return ret;
+}
+
+bool hash_tree::return_updated_dirty_pages(address_ranges ars, dirty_pages &batch,
+    changed_address_ranges &changed_ars) {
+    std::atomic<int> update_failed{0}; // NOLINT(misc-const-correctness)
+//??D The batch size past which we switch to parallel updates needs to be tuned empirically
+#pragma omp parallel if (static_cast<int>(batch.size()) > omp_get_max_threads() * 4)
+    {
+        hasher_type h; // NOLINT(misc-const-correctness)
+#pragma omp for
+        // NOLINTNEXTLINE(modernize-loop-convert)
+        for (decltype(batch.size()) i = 0; i < batch.size(); ++i) {
+            auto &[ar_index, br, changed] = batch[i];
+            auto &ar = ars[ar_index];
+            if (!update_dirty_page(h, ar, br, changed)) {
+                update_failed.store(1, std::memory_order_relaxed);
+#pragma omp cancel for
+            }
+#pragma omp cancellation point for
+        }
+    }
+    // Return all entries and collect address ranges that were actually changed by update
+    for (auto &[ar_index, br, changed] : batch) {
+        auto &ar = ars[ar_index];
+        auto offset = br.get_paddr_page() - ar.get_start();
+        if (m_page_cache.return_entry(br)) {
+            // If page hash was changed during update
+            if (changed) {
+                // If we haven't already done so, add changed address range to list
+                if (changed_ars.empty() || ar_index != changed_ars.back()) {
+                    changed_ars.push_back(ar_index);
+                }
+                // If page was marked dirty but was not in fact dirty
+            } else {
+                // We can safely mark the page clean because its contents already matched its
+                // So we won't need to "bubble-up" any hash changes based on it
+                ar.get_dirty_page_tree().mark_clean_page_and_up(offset);
+            }
+        } else {
+            update_failed.store(1, std::memory_order_relaxed);
+        }
+    }
+    // Done with batch
+    batch.clear();
+    return static_cast<bool>(update_failed.load(std::memory_order_relaxed));
+}
+
+hash_tree::~hash_tree() {
+#ifdef DUMP_HASH_TREE_STATS
+    std::cerr << "sparse node hashes: " << std::dec << m_sparse_node_hashes << '\n';
+    std::cerr << "dense node hashes: \n";
+    int sum = 0;
+    for (int i = 0; auto &a : m_dense_node_hashes) {
+        auto av = a.load();
+        sum += av;
+        if (av != 0) {
+            std::cerr << "    " << std::dec << i << ": " << av << '\n';
+        }
+        ++i;
+    }
+    std::cerr << "    total: " << sum << '\n';
+#endif
+}
+
+bool hash_tree::update_dirty_pages(address_ranges ars, changed_address_ranges &changed_ars) {
+    SCOPED_SIGNPOST(m_log, m_spid_update_page_hashes, "update page hashes", "");
+    bool update_failed = false;
+    dirty_pages batch;
+    batch.reserve(m_page_cache.capacity());
+    // Go sequentially over dirty pages of all address ranges, collecting borrowed cache entries for them.
+    // The cache eventually runs out of entries to lend.
+    // At this point, we have accumulated a batch of cache entries for dirty pages.
+    // We update all these cache entries in parallel.
+    // After that, we sequentially return the updated entries to the cache.
+    // ??D In C++23, use views::enumerate instead
+    for (int ar_index = 0; auto &ar : ars) {
+        // Break out if there were previous failures
+        if (update_failed) {
+            break;
+        }
+        const auto start = ar.get_start();
+        auto view = ar.get_dirty_page_tree().dirty_offsets_view(HASH_TREE_LOG2_PAGE_SIZE) |
+            std::views::filter([length = ar.get_length()](auto offset) { return offset < length; });
+        for (auto offset : view) {
+            const auto paddr_page = start + offset;
+            auto opt_br = m_page_cache.borrow_entry(paddr_page);
+            // If we have no entry, the cache ran out of entries to lend
+            if (!opt_br) {
+                // So we update all entries and return them to the cache
+                update_failed |= return_updated_dirty_pages(ars, batch, changed_ars);
+                // In theory, we have now returned all borrowed cache entries
+                opt_br = m_page_cache.borrow_entry(paddr_page);
+                // So we must have succeeded borrowing, unless there was a prior failure
+                if (!opt_br) {
+                    update_failed = true;
+                    break;
+                }
+            }
+            // Add borrowed entry to batch
+            batch.emplace_back(ar_index, *opt_br, false);
+        }
+        ++ar_index;
+    }
+    // Update and return last batch
+    update_failed |= return_updated_dirty_pages(ars, batch, changed_ars);
+    if (update_failed) {
+        // Kill cache because it is most likely corrupted
+        m_page_cache.clear();
+        return false;
+    }
+    return true;
+}
+
+// NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+void hash_tree::update_and_clear_dense_node_entries(dense_node_entries &batch, int log2_size) {
+    if (batch.empty()) {
+        return;
+    }
+//??D The batch size past which we switch to parallel updates needs to be tuned empirically
+#pragma omp parallel if (static_cast<int>(batch.size()) > omp_get_max_threads() * 32)
+    {
+        hasher_type h; // NOLINT(misc-const-correctness)
+#ifdef DUMP_HASH_TREE_STATS
+        int updates = 0;
+#endif
+#pragma omp for
+        // NOLINTNEXTLINE(modernize-loop-convert)
+        for (decltype(batch.size()) i = 0; i < batch.size(); ++i) {
+            auto &[dht, offset] = batch[i];
+            auto child_size = UINT64_C(1) << (log2_size - 1);
+            auto parent = dht.node_hash_view(offset, log2_size);
+            auto left = dht.node_hash_view(offset, log2_size - 1);
+            auto right = dht.node_hash_view(offset + child_size, log2_size - 1);
+            get_concat_hash(h, left, right, parent);
+#ifdef DUMP_HASH_TREE_STATS
+            ++updates;
+#endif
+        }
+#ifdef DUMP_HASH_TREE_STATS
+        m_dense_node_hashes[log2_size] += updates;
+#endif
+    }
+    batch.clear();
+}
+
+bool hash_tree::update_dense_trees(address_ranges ars, const changed_address_ranges &changed_ars) {
+    SCOPED_SIGNPOST(m_log, m_spid_update_dense_trees, "update dense trees", "");
+    if (changed_ars.empty()) {
+        return true;
+    }
+    const auto thread_count = 8;
+    const auto batch_size = thread_count << 10;
+    dense_node_entries batch;
+    batch.reserve(batch_size);
+    // Get maximum log2_size of all address ranges
+    const auto max_level_count = std::ranges::max(
+        changed_ars | std::views::transform([ars](auto ar_index) { return ars[ar_index].get_level_count(); }));
+    // Go from page size up until we have updated all dirty nodes of all all dense trees
+    for (int level = 1; level < max_level_count; ++level) {
+        auto log2_size = HASH_TREE_LOG2_PAGE_SIZE + level;
+        for (auto ar_index : changed_ars) {
+            auto &ar = ars[ar_index];
+            //??D If there are too many address ranges (not the case now), we could optimize this by
+            //??D looping over only those with enough levels
+            if (level > ar.get_level_count()) {
+                continue;
+            }
+            auto &dht = ar.get_dense_hash_tree();
+            for (auto offset : ar.get_dirty_page_tree().dirty_offsets_view(log2_size)) {
+                if (batch.size() == batch_size) {
+                    update_and_clear_dense_node_entries(batch, log2_size);
+                }
+                batch.emplace_back(dht, offset);
+            }
+        }
+        update_and_clear_dense_node_entries(batch, log2_size);
+    }
+    return true;
+}
+
+bool hash_tree::update_sparse_tree(address_ranges ars, const changed_address_ranges &changed_ars) {
+    SCOPED_SIGNPOST(m_log, m_spid_update_sparse_tree, "update sparse tree", "");
+    // If there no changed address ranges, we are done
+    // Otherwise, allocate a fifo that holds at most one entry per changed address-range leaf-node
+    // For each changed address-range leaf-node,
+    //     Copy the hash from the root of the address-range dense hash tree to the leaf-node
+    //     Enqueue its sparse node's parent for update
+    // Until the queue is empty
+    //     Update the hash of the node at the front from the hash of its children nodes
+    //     If node is not the root, enqueue its parent for update
+    auto changed_count = std::ranges::size(changed_ars);
+    if (changed_count == 0) {
+        return true;
+    }
+    using E = std::pair<int, int>;
+    std::vector<E> changed_backing;
+    changed_backing.reserve(changed_count);
+    std::priority_queue<E, std::vector<E>, std::greater<>> changed(std::greater<>{}, std::move(changed_backing));
+    for (auto ar_index : changed_ars) {
+        auto ar_node_index = get_ar_sparse_node_index(ar_index);
+        auto &ar_node = m_sparse_nodes[ar_node_index];
+        auto ar_root_hash_view = ars[ar_index].get_dense_hash_tree().root_hash_view();
+        std::ranges::copy(ar_root_hash_view, ar_node.hash.begin());
+        auto &ar_parent_node = m_sparse_nodes[ar_node.parent];
+        if (ar_parent_node.marked == 0) {
+            ar_parent_node.marked = 1;
+            changed.emplace(ar_parent_node.log2_size, ar_node.parent);
+        }
+    }
+    hasher_type h;
+    while (!changed.empty()) {
+        auto [log2_size, inner_index] = changed.top();
+        changed.pop();
+        auto &inner_node = m_sparse_nodes[inner_index];
+        // Every node with smaller log2_size than inner_node has already been processed.
+        // By implication, its children have already been processed.
+        // So we can clear the mark with no fear inner_node will be added back to the queue.
+        inner_node.marked = 0;
+        auto left_hash_view = get_sparse_node_hash_view(inner_node.left, log2_size - 1);
+        auto right_hash_view = get_sparse_node_hash_view(inner_node.right, log2_size - 1);
+        get_concat_hash(h, left_hash_view, right_hash_view, inner_node.hash);
+#ifdef DUMP_HASH_TREE_STATS
+        ++m_sparse_node_hashes;
+#endif
+        if (!is_pristine(inner_node.parent)) {
+            auto &parent_node = m_sparse_nodes[inner_node.parent];
+            if (parent_node.marked == 0) {
+                parent_node.marked = 1;
+                changed.emplace(log2_size + 1, inner_node.parent);
+            }
+        }
+    }
+    return true;
+}
+
+machine_hash hash_tree::get_root_hash() const noexcept {
+    return m_sparse_nodes[1].hash;
+}
+
+machine_hash hash_tree::get_dense_node_hash(address_range &ar, uint64_t address, int log2_size) {
+    assert(ar.contains_absolute(address, HASH_TREE_WORD_SIZE) && "address not in expected address range");
+    if (log2_size < HASH_TREE_LOG2_PAGE_SIZE) {
+        assert(log2_size >= HASH_TREE_LOG2_WORD_SIZE && "invalid log2_size");
+        const auto paddr_page = address & ~(HASH_TREE_PAGE_SIZE - 1);
+        bool hit = false;
+        auto opt_br = m_page_cache.borrow_entry(paddr_page, hit);
+        assert(opt_br && "page hash-tree cache has no entries to lend");
+        if (!hit) {
+            hasher_type h;
+            [[maybe_unused]] bool changed = false;
+            update_dirty_page(h, ar, *opt_br, changed);
+        }
+        auto node_offset = address - paddr_page;
+        auto hash = to_hash(opt_br->get().node_hash_view(node_offset, log2_size));
+        m_page_cache.return_entry(*opt_br);
+        return hash;
+    }
+    const auto offset = address - ar.get_start();
+    return to_hash(ar.get_dense_hash_tree().node_hash_view(offset, log2_size));
+}
+
+machine_hash hash_tree::get_node_hash(address_ranges ars, uint64_t address, int log2_size) {
+    if (log2_size < HASH_TREE_LOG2_WORD_SIZE || log2_size > HASH_TREE_LOG2_ROOT_SIZE) {
+        throw std::invalid_argument{"invalid log2_size"};
+    }
+    if (log2_size == HASH_TREE_LOG2_ROOT_SIZE) {
+        if (address != 0) {
+            throw std::invalid_argument{"address not aligned to log2_size"};
+        }
+    } else if (((address >> log2_size) << log2_size) != address) {
+        throw std::invalid_argument{"address not aligned to log2_size"};
+    }
+    index_type node_index = 1;
+    int curr_log2_size = HASH_TREE_LOG2_ROOT_SIZE;
+    for (;;) {
+        // hit pristine node
+        if (is_pristine(node_index)) {
+            return m_pristine_hashes[log2_size];
+        }
+        const auto &node = m_sparse_nodes[node_index];
+        assert(static_cast<int>(node.log2_size) == curr_log2_size && "incorrect node log2_size");
+        // hit sparse tree node
+        if (curr_log2_size == log2_size) {
+            return node.hash;
+        }
+        // transition to dense tree
+        if (is_ar_node(node)) {
+            auto &ar = ars[node.right];
+            const int ar_log2_size = HASH_TREE_LOG2_PAGE_SIZE + ar.get_level_count() - 1;
+            assert(curr_log2_size == ar_log2_size && "incorrect ar node log2_size");
+            return get_dense_node_hash(ar, address, log2_size);
+        }
+        // go down left or right on sparse tree depending on address
+        --curr_log2_size;
+        if ((address & (UINT64_C(1) << curr_log2_size)) == 0) {
+            node_index = node.left;
+        } else {
+            node_index = node.right;
+        }
+    }
+}
+
+bool hash_tree::verify(address_ranges ars) const {
+    hasher_type h;
+    bool ret = true;
+    for (auto ar_node_index = get_ar_sparse_node_index(0); const auto &ar : ars) {
+        const std::span<const unsigned char> mem{ar.get_host_memory(), ar.get_length()};
+        const auto &dht = ar.get_dense_hash_tree();
+        const auto &dpt = ar.get_dirty_page_tree();
+        auto ar_actually_dirty = false;
+        for (uint64_t offset = 0; offset < ar.get_length(); offset += HASH_TREE_PAGE_SIZE) {
+            auto page = mem.subspan(offset, HASH_TREE_PAGE_SIZE);
+            auto page_hash = get_merkle_tree_hash(h, page, HASH_TREE_WORD_SIZE);
+            auto actually_dirty = !std::ranges::equal(page_hash, dht.node_hash_view(offset, HASH_TREE_LOG2_PAGE_SIZE));
+            ar_actually_dirty = ar_actually_dirty || actually_dirty;
+            auto marked_dirty = dpt.is_node_dirty(offset, HASH_TREE_LOG2_PAGE_SIZE);
+            if (actually_dirty != marked_dirty) {
+                if (!marked_dirty) {
+                    std::cerr << "page 0x" << std::hex << std::uppercase << offset << " of " << ar.get_description()
+                              << " is " << (marked_dirty ? "" : "not ") << "marked dirty but is "
+                              << (actually_dirty ? "" : "not ") << "dirty";
+                    ret = false;
+                    std::cerr << "! FAILED!";
+                }
+                std::cerr << "\n";
+            }
+        }
+        const int ar_log2_size = HASH_TREE_LOG2_PAGE_SIZE + ar.get_level_count() - 1;
+        auto ar_marked_dirty = dpt.is_node_dirty(0, ar_log2_size);
+        if (ar_actually_dirty != ar_marked_dirty) {
+            if (!ar_marked_dirty) {
+                std::cerr << ar.get_description() << " is " << (ar_marked_dirty ? "" : "not ") << "marked dirty but is "
+                          << (ar_actually_dirty ? "" : "not ") << "dirty";
+                ret = false;
+                std::cerr << "! FAILED!";
+            }
+            std::cerr << "\n";
+        }
+        const auto &ar_node = m_sparse_nodes[ar_node_index];
+        if (!std::ranges::equal(ar_node.hash, dht.node_hash_view(0, ar_log2_size))) {
+            std::cerr << ar.get_description() << " dense hash tree root does not match sparse node hash\n";
+        }
+        ++ar_node_index;
+    }
+    return ret;
+}
+
+bool hash_tree::update(address_ranges ars) {
+    SCOPED_SIGNPOST(m_log, m_spid_update, "update hash tree", "");
+    omp_set_num_threads(m_concurrency);
+    changed_address_ranges changed_ars;
+    auto update_succeeded = update_dirty_pages(ars, changed_ars) && update_dense_trees(ars, changed_ars) &&
+        update_sparse_tree(ars, changed_ars);
+    if (update_succeeded) {
+        for (auto ar_index : changed_ars) {
+            ars[ar_index].get_dirty_page_tree().clean();
+        }
+    }
+    return update_succeeded;
+}
+
+bool hash_tree::update_page(address_ranges ars, uint64_t paddr_page) {
+    paddr_page >>= HASH_TREE_LOG2_PAGE_SIZE;
+    paddr_page <<= HASH_TREE_LOG2_PAGE_SIZE;
+    hasher_type h;
+    // Find address range where page might lie
+    auto it = std::ranges::find_if(ars,
+        [paddr_page](auto &ar) { return ar.contains_absolute(paddr_page, HASH_TREE_PAGE_SIZE); });
+    if (it == ars.end()) {
+        throw std::runtime_error{"page to update is not in a memory address range"};
+    }
+    const auto ar_index = it - ars.begin();
+    auto &ar = ars[ar_index];
+    // Get page entry from page hash-tree cache
+    auto opt_br = m_page_cache.borrow_entry(paddr_page);
+    assert(opt_br && "page hash-tree cache has no entries to lend");
+    auto &entry = opt_br->get();
+    bool changed = false;
+    // Update page with data from address range
+    update_dirty_page(h, ar, entry, changed);
+    // If nothing changed, we are done
+    if (!changed) {
+        m_page_cache.return_entry(entry);
+        return true;
+    }
+    // Copy new page hash to address range's dense hash tree
+    const auto page_offset = paddr_page - ar.get_start();
+    auto &dht = ar.get_dense_hash_tree();
+    auto page_hash_view = dht.node_hash_view(page_offset, HASH_TREE_LOG2_PAGE_SIZE);
+    std::ranges::copy(entry.root_hash_view(), page_hash_view.begin());
+    // Bubble up the dense hash tree
+    const int ar_log2_size = HASH_TREE_LOG2_PAGE_SIZE + ar.get_level_count() - 1;
+    for (int log2_size = HASH_TREE_LOG2_PAGE_SIZE + 1; log2_size <= ar_log2_size; ++log2_size) {
+        auto child_size = UINT64_C(1) << (log2_size - 1);
+        auto node_offset = get_aligned_address(page_offset, log2_size);
+        auto parent = dht.node_hash_view(node_offset, log2_size);
+        auto left = dht.node_hash_view(node_offset, log2_size - 1);
+        auto right = dht.node_hash_view(node_offset + child_size, log2_size - 1);
+        get_concat_hash(h, left, right, parent);
+    }
+    // Copy address range hash to corresponding sparse node
+    auto node_index = get_ar_sparse_node_index(ar_index);
+    std::ranges::copy(dht.node_hash_view(0, ar_log2_size), m_sparse_nodes[node_index].hash.begin());
+    // Bubble up sparse hash tree
+    node_index = m_sparse_nodes[node_index].parent;
+    int log2_size = ar_log2_size + 1;
+    while (node_index != 0) {
+        auto &node = m_sparse_nodes[node_index];
+        assert(log2_size == static_cast<int>(node.log2_size) && "invalid sparse node log2_size");
+        auto left_hash_view = get_sparse_node_hash_view(node.left, log2_size - 1);
+        auto right_hash_view = get_sparse_node_hash_view(node.right, log2_size - 1);
+        get_concat_hash(h, left_hash_view, right_hash_view, node.hash);
+        node_index = node.parent;
+        ++log2_size;
+    }
+    assert(log2_size == HASH_TREE_LOG2_ROOT_SIZE + 1 && "invalid sparse tree log2_size");
+    m_page_cache.return_entry(entry);
+    return true;
+}
+
+hash_tree::pristine_hashes hash_tree::get_pristine_hashes() {
+    hasher_type h;
+    pristine_hashes hashes{};
+    std::array<unsigned char, HASH_TREE_WORD_SIZE> zero{};
+    machine_hash hash = get_hash(h, zero);
+    for (auto log2_size : std::views::iota(HASH_TREE_LOG2_WORD_SIZE, static_cast<int>(hashes.size()))) {
+        hashes[log2_size] = hash;
+        get_concat_hash(h, hash, hash, hash);
+    }
+    return hashes;
+};
+
+static int get_concurrency(int value) {
+    const int concurrency = value != 0 ? value : omp_get_max_threads();
+    return std::min(concurrency, omp_get_max_threads());
+}
+
+hash_tree::hash_tree(const hash_tree_config &config, uint64_t concurrency, const_address_ranges ars) :
+    m_sparse_nodes{create_nodes(ars)},
+    m_page_cache{hasher_type{}, config.phtc_size},
+    m_pristine_hashes{get_pristine_hashes()},
+    m_concurrency{get_concurrency(static_cast<int>(concurrency))} {
+#ifdef __APPLE__
+    m_log = os_log_create("io.cartesi.machine-emulator", "hash-tree");
+    m_spid_update = os_signpost_id_generate(m_log);
+    m_spid_update_page_hashes = os_signpost_id_generate(m_log);
+    m_spid_update_dense_trees = os_signpost_id_generate(m_log);
+    m_spid_update_sparse_tree = os_signpost_id_generate(m_log);
+#endif
+}
+
+void hash_tree::check_address_ranges(const_address_ranges ars) {
+    for (int ar_i = 0; auto &&ar : ars) {
+        // Empty ranges are not supported
+        if (ar.is_empty()) {
+            throw std::invalid_argument{"empty ranges are not supported"};
+        }
+        // Length must not overflow when rounded up to the next power of 2
+        const auto length = ar.get_length();
+        if (length > (UINT64_C(1) << 63)) {
+            throw std::invalid_argument{
+                "length of "s.append(ar.get_description()).append(" overflows when rounded up to a power of 2")};
+        }
+        const auto length_bit_ceil = std::bit_ceil(length);
+        const auto start = ar.get_start();
+        // Start must be aligned to length rounded up to the next power of 2
+        if ((start & (length_bit_ceil - 1)) != 0) {
+            throw std::invalid_argument{"start of "s.append(ar.get_description())
+                    .append(" is not aligned to its length rounded up to a power of 2")};
+        }
+        // Range cannot overflow when length is rounded up to the next power of 2
+        if (start >= UINT64_MAX - length_bit_ceil) {
+            throw std::invalid_argument{"range "s.append(ar.get_description())
+                    .append(" overflows when its length is rounded up to a power of 2")};
+        }
+        // Ranges must lot overlap, even when their lengths are rounded up to the next power of 2
+        const auto end = start + length_bit_ceil;
+        for (auto &&prev_ar : std::views::take(ars, ar_i)) {
+            const auto prev_start = prev_ar.get_start();
+            const auto prev_length_bit_ceil = std::bit_ceil(prev_ar.get_length());
+            const auto prev_end = prev_start + prev_length_bit_ceil;
+            if (start < prev_end && end > prev_start) {
+                throw std::invalid_argument{"address range of "s.append(ar.get_description())
+                        .append(" overlaps with address range of ")
+                        .append(prev_ar.get_description())
+                        .append(" when lengths are rounded up to powers of 2")};
+            }
+        }
+        ++ar_i;
+    }
+}
+
+template <std::random_access_iterator Iter, std::sentinel_for<Iter> Sent>
+    requires(std::same_as<std::remove_cvref_t<std::iter_reference_t<Iter>>, address_range> &&
+        std::is_reference_v<std::iter_reference_t<Iter>>)
+hash_tree::index_type hash_tree::append_nodes(uint64_t begin_page_index, uint64_t log2_page_count,
+    Iter &ar_curr /* modifiable! */, Iter ar_begin, Sent ar_sent, nodes_type &nodes, index_type parent) {
+    const auto log2_size = log2_page_count + HASH_TREE_LOG2_PAGE_SIZE;
+    // Page range is past the last occupied address ranges
+    if (ar_curr == ar_sent) {
+        // Entire subtree is pristine, simply return index to pristine node
+        return 0;
+    }
+    auto &&ar = *ar_curr;
+    const auto page_count = UINT64_C(1) << log2_page_count;
+    const auto end_page_index = begin_page_index + page_count;
+    const auto ar_begin_page_index = ar.get_start() >> HASH_TREE_LOG2_PAGE_SIZE;
+    // Page range ends before next occupied address range starts
+    if (ar_begin_page_index >= end_page_index) {
+        // Entire subtree is pristine, simply return index to pristine node
+        return 0;
+    }
+    // Page range matches next occopied address range exactly
+    const auto ar_page_count = std::bit_ceil(ar.get_length()) >> HASH_TREE_LOG2_PAGE_SIZE;
+    if (ar_begin_page_index == begin_page_index && ar_page_count == page_count) {
+        auto ar_index = static_cast<index_type>(ar_curr - ar_begin);
+        const auto ar_node_index = get_ar_sparse_node_index(ar_index);
+        auto &ar_node = nodes[ar_node_index]; // Address-range leaf-nodes are already there
+        ar_node = node_type{
+            .left = AR_NODE_TAG,
+            .right = ar_index,
+            .parent = parent,
+            .log2_size = static_cast<uint32_t>(log2_size),
+            .marked = 0,
+        };
+        // Consume range
+        ++ar_curr;
+        return ar_node_index;
+    }
+    // We already subdivided to page level and found nothing
+    if (log2_page_count == 0) {
+        // Node is pristine, no need to allocate a node
+        return 0;
+    }
+    index_type inner_index = 1;
+    if (parent != 0) { // If not root, add inner node, otherwise use root node already there
+        inner_index = static_cast<index_type>(nodes.size());
+        nodes.push_back(node_type{});
+    }
+    // Otherwise, allocate inner node and recurse first left, then right
+    nodes[inner_index].left = append_nodes(begin_page_index, log2_page_count - 1, ar_curr, ar_begin, ar_sent, nodes,
+        inner_index); // must index into vector because function appends to it
+    nodes[inner_index].right = append_nodes(begin_page_index + (page_count >> 1), log2_page_count - 1, ar_curr,
+        ar_begin, ar_sent, nodes, inner_index); // must index into vector because function appends to it
+    nodes[inner_index].parent = parent;
+    nodes[inner_index].log2_size = log2_size;
+    return inner_index;
+}
+
+hash_tree::nodes_type hash_tree::create_nodes(const_address_ranges ars) {
+    check_address_ranges(ars);
+    nodes_type nodes;
+    // Node at 0 is reserved to avoid confusion with index 0 that means "pristine"
+    // Node at 1 is the root, so we always know where it is
+    // Address-range leaf-nodes come next, so we always know where they are from their index in ars
+    // The rest of the nodes are added as needed, in an order we do not care about
+    nodes.resize(1 + 1 + ars.size());
+    const auto begin_page_index = 0;
+    const auto log2_page_count = HASH_TREE_LOG2_ROOT_SIZE - HASH_TREE_LOG2_PAGE_SIZE;
+    auto ar_iter = ars.begin();
+    auto root_index = append_nodes(begin_page_index, log2_page_count, ar_iter, ars.begin(), ars.end(), nodes, 0);
+    if (root_index != 1) {
+        throw std::logic_error{"expected root index to be 1 (got "s.append(std::to_string(root_index)).append(")")};
+    }
+    return nodes;
+}
+
+void hash_tree::dump(const_address_ranges ars, std::ostream &out) {
+    out << "digraph HashTree {\n";
+    out << "  rankdir=TB;\n";
+    out << "  node [shape=circle];\n";
+    for (int index = 1; const auto &node : m_sparse_nodes | std::views::drop(1)) {
+        if (is_ar_node(node)) {
+            const auto &ar = ars[node.right];
+            out << "  A" << index << " [label=\"" << index << "," << ar.get_description() << "\"];\n";
+        }
+        ++index;
+    }
+    out << "  subgraph InnerNodesOneChild {\n";
+    out << "    node [shape=circle, width=0.5, height=0.5, label=\"\", style=filled, fillcolor=gray, "
+           "fixedsize=true];\n";
+    for (int index = 1; const auto &node : m_sparse_nodes | std::views::drop(1)) {
+        if (!is_ar_node(node)) {
+            if (is_pristine(node.left) || is_pristine(node.right)) {
+                out << "    A" << index << "[label=\"" << index << "\"];\n";
+            }
+        }
+        ++index;
+    }
+    out << "  }\n";
+    out << "  subgraph InnerNodesTwoChildren {\n";
+    out << "    node [shape=circle, width=0.5, height=0.5, label=\"\", style=filled, fillcolor=red, fixedsize=true];\n";
+    for (int index = 1; const auto &node : m_sparse_nodes | std::views::drop(1)) {
+        if (!is_ar_node(node)) {
+            if (!is_pristine(node.left) && !is_pristine(node.right)) {
+                out << "    A" << index << ";\n";
+            }
+        }
+        ++index;
+    }
+    out << "  }\n";
+    out << "  subgraph NullNodes {\n";
+    out << "    node [shape=circle, width=0.5, height=0.5, label=\"\", style=filled, fillcolor=white, color=black, "
+           "fixedsize=true];\n";
+    for (int null_index = 0; const auto &node : m_sparse_nodes | std::views::drop(1)) {
+        if (!is_ar_node(node)) {
+            if (is_pristine(node.left)) {
+                out << "    N" << ++null_index << ";\n";
+            }
+            if (is_pristine(node.right)) {
+                out << "    N" << ++null_index << ";\n";
+            }
+        }
+    }
+    out << "  }\n";
+    for (int index = 1, null_index = 0; const auto &node : m_sparse_nodes | std::views::drop(1)) {
+        if (!is_ar_node(node)) {
+            if (!is_pristine(node.left)) {
+                out << "  A" << index << " -> A" << node.left << ";\n";
+            } else {
+                out << "  A" << index << " -> N" << ++null_index << ";\n";
+            }
+            if (!is_pristine(node.right)) {
+                out << "  A" << index << " -> A" << node.right << ";\n";
+            } else {
+                out << "  A" << index << " -> N" << ++null_index << ";\n";
+            }
+        }
+        ++index;
+    }
+    for (auto index = get_ar_sparse_node_index(0); const auto &node : m_sparse_nodes | std::views::drop(2)) {
+        out << "  A" << index << " -> A" << node.parent << " [constraint=false, color=gray, style=dashed];\n";
+        ++index;
+    }
+    out << "}\n";
+}
+
+#ifdef DUMP_HASH_TREE_STATS
+std::atomic<int> page_hash_tree_cache::entry::m_word_hit{0};
+std::atomic<int> page_hash_tree_cache::entry::m_word_miss{0};
+std::atomic<int> page_hash_tree_cache::entry::m_inner_page_node_hashes{0};
+std::array<std::atomic<int>, 64> hash_tree::m_dense_node_hashes{};
+#endif
+
+} // namespace cartesi
diff --git a/src/hash-tree.h b/src/hash-tree.h
new file mode 100644
index 000000000..127f6ddb5
--- /dev/null
+++ b/src/hash-tree.h
@@ -0,0 +1,191 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef HASH_TREE_H
+#define HASH_TREE_H
+
+#include <iosfwd>
+#include <vector>
+
+#include "address-range.h"
+#include "hash-tree-constants.h"
+#include "keccak-256-hasher.h"
+#include "machine-address-ranges.h"
+#include "machine-config.h"
+#include "machine-hash.h"
+#include "merkle-tree-proof.h"
+#include "page-hash-tree-cache.h"
+#include "unique-c-ptr.h"
+
+#ifdef __APPLE__
+#include <os/log.h>
+#include <os/signpost.h>
+#endif
+
+namespace cartesi {
+
+class hash_tree {
+
+    struct dirty_page {
+        int ar_index; ///< Source address range
+        // NOLINTNEXTLINE(cppcoreguidelines-avoid-const-or-ref-data-members)
+        page_hash_tree_cache::entry &br; ///< Borrowed page hash-tree cache entry
+        bool changed;                    ///< Whether the update operation really changed the page
+    };
+
+    using dirty_pages = std::vector<dirty_page>;
+    using dense_node_entry = std::pair<i_dense_hash_tree &, uint64_t>;
+    using dense_node_entries = std::vector<dense_node_entry>;
+    using pristine_hashes = std::array<machine_hash, HASH_TREE_LOG2_ROOT_SIZE + 1>;
+
+    using index_type = int64_t;
+
+    static constexpr index_type AR_NODE_TAG{-1};
+    static constexpr index_type PRISTINE_NODE_TAG{0};
+
+    struct node_type {
+        index_type left{};
+        index_type right{};
+        index_type parent{};
+        uint32_t log2_size{};
+        uint32_t marked{};
+        machine_hash hash{};
+    };
+
+    static bool is_ar_node(const node_type &node) {
+        return node.left == AR_NODE_TAG;
+    }
+
+    static bool is_pristine(index_type index) {
+        return index == PRISTINE_NODE_TAG;
+    }
+
+    static index_type get_ar_sparse_node_index(index_type ar_index) {
+        return ar_index + 2;
+    }
+
+    // This is ensures we use the hash_tree_view of machine_address_ranges everywhere
+    template <typename MAR>
+    class hash_tree_view : public std::ranges::view_interface<hash_tree_view<MAR>> {
+        using V = decltype(std::declval<MAR>().hash_tree_view());
+        static_assert(std::ranges::random_access_range<V>, "not a random access range");
+        static_assert(std::ranges::view<V>, "not a view");
+        V m_view;
+
+    public:
+        /// \brief Automatic construction from object of type MAR
+        explicit(false) hash_tree_view(MAR &ars) : m_view{ars.hash_tree_view()} {}
+        auto begin() const
+            requires std::ranges::range<const V>
+        {
+            return std::ranges::begin(m_view);
+        }
+        auto end() const
+            requires std::ranges::range<const V>
+        {
+            return std::ranges::end(m_view);
+        }
+        auto begin() {
+            return std::ranges::begin(m_view);
+        }
+        auto end() {
+            return std::ranges::end(m_view);
+        }
+    };
+    using address_ranges = hash_tree_view<machine_address_ranges>;
+    using const_address_ranges = hash_tree_view<const machine_address_ranges>;
+
+public:
+    using hasher_type = keccak_256_hasher;
+    using proof_type = merkle_tree_proof;
+
+    using nodes_type = std::vector<node_type>;
+    using sibling_hashes_type = std::vector<machine_hash>;
+
+    hash_tree(const hash_tree_config &config, uint64_t concurrency, const_address_ranges ars);
+
+    hash_tree(const hash_tree &other) = delete;
+    hash_tree(hash_tree &&other) = delete;
+    hash_tree &operator=(hash_tree &&other) = delete;
+    hash_tree &operator=(const hash_tree &other) = delete;
+
+    ~hash_tree();
+
+    bool update(address_ranges ars);
+
+    bool update_page(address_ranges ars, uint64_t paddr_page);
+
+    bool verify(address_ranges ars) const;
+
+    machine_hash get_root_hash() const noexcept;
+    machine_hash get_node_hash(address_ranges ars, uint64_t address, int log2_size);
+    proof_type get_proof(address_ranges ars, uint64_t address, int log2_size);
+
+    void dump(const_address_ranges ars, std::ostream &out);
+
+    void clear_stats();
+
+private:
+    using changed_address_ranges = std::vector<int>;
+
+    void get_pristine_proof(int curr_log2_size, proof_type &proof) const;
+    void get_dense_proof(address_range &ar, int ar_log2_size, uint64_t address, proof_type &proof);
+    void get_page_proof(address_range &ar, uint64_t address, proof_type &proof);
+
+    machine_hash get_dense_node_hash(address_range &ar, uint64_t address, int log2_size);
+
+    static pristine_hashes get_pristine_hashes();
+
+    bool update_dirty_pages(address_ranges ars, changed_address_ranges &changed_ars);
+    bool update_dirty_page(hasher_type &h, address_range &ar, page_hash_tree_cache::entry &entry, bool &changed);
+    bool return_updated_dirty_pages(address_ranges ars, dirty_pages &batch, changed_address_ranges &changed_ars);
+
+    bool update_dense_trees(address_ranges ars, const changed_address_ranges &changed_ars);
+    void update_and_clear_dense_node_entries(dense_node_entries &batch, int log2_size);
+
+    const_machine_hash_view get_sparse_node_hash_view(index_type node_index, int log2_size) const noexcept;
+    bool update_sparse_tree(address_ranges ars, const changed_address_ranges &changed_ars);
+
+    template <std::random_access_iterator Iter, std::sentinel_for<Iter> Sent>
+        requires(std::same_as<std::remove_cvref_t<std::iter_reference_t<Iter>>, address_range> &&
+            std::is_reference_v<std::iter_reference_t<Iter>>)
+    static index_type append_nodes(uint64_t begin_page_index, uint64_t log2_page_count, Iter &ar_curr /* modifiable! */,
+        Iter ar_begin, Sent ar_sent, hash_tree::nodes_type &nodes, index_type parent);
+
+    static nodes_type create_nodes(const_address_ranges ars);
+    static void check_address_ranges(const_address_ranges ars);
+
+    //??D Replace std::vector so entries can live on disk
+    nodes_type m_sparse_nodes;
+    mutable page_hash_tree_cache m_page_cache;
+    const pristine_hashes m_pristine_hashes;
+    int m_concurrency;
+#ifdef __APPLE__
+    os_log_t m_log;
+    os_signpost_id_t m_spid_update;
+    os_signpost_id_t m_spid_update_page_hashes;
+    os_signpost_id_t m_spid_update_dense_trees;
+    os_signpost_id_t m_spid_update_sparse_tree;
+#endif
+#ifdef DUMP_HASH_TREE_STATS
+    int m_sparse_node_hashes{0};
+    static std::array<std::atomic<int>, 64> m_dense_node_hashes;
+#endif
+};
+
+} // namespace cartesi
+
+#endif // HASH_TREE_H
diff --git a/src/htif-address-range.h b/src/htif-address-range.h
index c48b27c3e..a7daa8a07 100644
--- a/src/htif-address-range.h
+++ b/src/htif-address-range.h
@@ -20,16 +20,16 @@
 #include <cstdint>
 
 #include "address-range-constants.h"
+#include "address-range.h"
 #include "i-device-state-access.h"
 #include "pmas-constants.h"
-#include "pristine-address-range.h"
 
 /// \file
 /// \brief Host-Target InterFace device.
 
 namespace cartesi {
 
-class htif_address_range final : public pristine_address_range {
+class htif_address_range final : public address_range {
 
     static constexpr pmas_flags m_htif_flags{
         .M = false,
@@ -45,7 +45,7 @@ class htif_address_range final : public pristine_address_range {
 public:
     template <typename ABRT>
     explicit htif_address_range(ABRT abrt) :
-        pristine_address_range("HTIF device", AR_HTIF_START, AR_HTIF_LENGTH, m_htif_flags, abrt) {
+        address_range("HTIF device", AR_HTIF_START, AR_HTIF_LENGTH, m_htif_flags, abrt) {
         ;
     }
 
diff --git a/src/i-dense-hash-tree.h b/src/i-dense-hash-tree.h
new file mode 100644
index 000000000..951eee653
--- /dev/null
+++ b/src/i-dense-hash-tree.h
@@ -0,0 +1,73 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef I_DENSE_HASH_TREE_H
+#define I_DENSE_HASH_TREE_H
+
+#include "hash-tree-constants.h"
+#include "machine-hash.h"
+
+namespace cartesi {
+
+class i_dense_hash_tree {
+public:
+    machine_hash_view node_hash_view(uint64_t offset, int log2_size) noexcept {
+        return do_node_hash_view(offset, log2_size);
+    }
+    const_machine_hash_view node_hash_view(uint64_t offset, int log2_size) const noexcept {
+        return do_node_hash_view(offset, log2_size);
+    }
+    const_machine_hash_view root_hash_view() const noexcept {
+        return do_root_hash_view();
+    }
+
+    i_dense_hash_tree() = default;
+    i_dense_hash_tree(const i_dense_hash_tree &) = default;
+    i_dense_hash_tree(i_dense_hash_tree &&) = default;
+    i_dense_hash_tree &operator=(i_dense_hash_tree &&) = default;
+    i_dense_hash_tree &operator=(const i_dense_hash_tree &) = default;
+
+    virtual ~i_dense_hash_tree() {
+        ;
+    }
+
+protected:
+    static machine_hash_view no_hash_view() noexcept {
+        static machine_hash no_hash{};
+        return machine_hash_view{no_hash};
+    }
+
+private:
+    virtual const_machine_hash_view do_node_hash_view(uint64_t offset, int log2_size) const noexcept = 0;
+    virtual machine_hash_view do_node_hash_view(uint64_t offset, int log2_size) noexcept = 0;
+    virtual const_machine_hash_view do_root_hash_view() const noexcept = 0;
+};
+
+class empty_dense_hash_tree : public i_dense_hash_tree {
+    const_machine_hash_view do_node_hash_view(uint64_t /*offset*/, int /*log2_size*/) const noexcept override {
+        return no_hash_view();
+    }
+    machine_hash_view do_node_hash_view(uint64_t /*offset*/, int /*log2_size*/) noexcept override {
+        return no_hash_view();
+    }
+    const_machine_hash_view do_root_hash_view() const noexcept override {
+        return no_hash_view();
+    }
+};
+
+} // namespace cartesi
+
+#endif // I_DENSE_HASH_TREE_H
diff --git a/src/i-dirty-page-tree.h b/src/i-dirty-page-tree.h
new file mode 100644
index 000000000..0082e14fa
--- /dev/null
+++ b/src/i-dirty-page-tree.h
@@ -0,0 +1,358 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef I_DIRTY_PAGE_TREE_H
+#define I_DIRTY_PAGE_TREE_H
+
+/// \file
+/// \brief Dirty map as a complete tree
+
+#include <cstdint>
+#include <iterator>
+#include <limits>
+#include <ranges>
+
+#include "address-range-constants.h"
+
+namespace cartesi {
+
+/// \brief Dirty page tree interface
+/// \detail This class maintains the dirty flags for a contiguous range of pages.
+/// Page_size = 2^AR_LOG2_PAGE_SIZE.
+/// The flags are structured as a tree.
+/// In the public interface, each node is given by its starting offset and its log2_size.
+/// The first page is (0, AR_LOG2_PAGE_SIZE), the second at (page_size, AR_LOG2_PAGE_SIZE) ...
+/// So the parent of pages 0 and page_size is defined by (0, AR_LOG2_PAGE_SIZE+1) and so on.
+/// Ostensibly, the tree is represented as a byte array, each node taking a single byte that
+/// tells if that node is clean or dirty.
+/// Each node is therefore also identified by its position in this array.
+/// The the root is at position 1.
+/// As usual, the left and right children of the node at pos are 2*position and (2*posision+1), respectively.
+/// The tree maintains the following invariants:
+///   1) When a node is dirty, all parent nodes in the path torwards the root are also dirty;
+///   2) A node is clean only if all its children nodes are also clean.
+/// The leaves (page nodes) are at level 0, and the root is at level log2_leaf_count.
+/// The number level_count of levels in the tree is ceil(log2_page_count)+1.
+/// The interface allows for derived classes to compactly model a tree that is always dirty using the same
+/// interface .
+class i_dirty_page_tree {
+protected:
+    using size_type = uint64_t;
+
+    /// \brief View of all positions (in level, in entire tree etc)
+    using positions_range = std::ranges::iota_view<size_type, size_type>;
+
+    /// \brief Type used for positions of node in storage (no confusion with indices per level or page offsets)
+    using position_iterator = std::ranges::iterator_t<positions_range>;
+    static_assert(std::is_same_v<position_iterator::value_type, size_type>);
+
+    static constexpr auto invalid_position = position_iterator{std::numeric_limits<size_type>::max()};
+
+    /// \brief Returns view of all positions at a given level (for use with range-based for loops)
+    /// \param level Desired level
+    /// \returns Range of positions for level, or empty invalid range if level is out of bounds
+    constexpr positions_range level_positions_view(int level) const {
+        if (level >= 0 && level < level_count()) {
+            const auto begin = position_iterator::value_type{1} << (level_count() - level - 1);
+            return {begin, 2 * begin};
+        }
+        return {invalid_position, invalid_position};
+    }
+
+    /// \brief Returns number of levels in tree, from root to leaves
+    constexpr int level_count() const noexcept {
+        return m_level_count;
+    }
+
+    /// \brief Returns view of all levels (for use with range-based for loops)
+    constexpr auto levels_view() const noexcept {
+        return std::views::iota(0, level_count());
+    }
+
+    /// \brief Iterator over dirty nodes at a given level
+    class dirty_iterator {
+    public:
+        using value_type = position_iterator;
+        using reference = position_iterator;
+        using difference_type = position_iterator::difference_type;
+
+        using iterator_category = std::forward_iterator_tag;
+        using iterator_concept = std::forward_iterator_tag;
+
+        dirty_iterator() = default;
+
+        dirty_iterator(const i_dirty_page_tree *dt, positions_range level) noexcept :
+            m_dt{dt},
+            m_level{level},
+            m_pos{m_level.begin()} {
+            // First position at level may not be dirty, so advance until first dirty or end
+            while (!at_end() && !m_dt->is_dirty_position(m_pos)) {
+                m_dt->advance_dirty_position(m_pos, m_level);
+            }
+        }
+
+        constexpr position_iterator operator*() const noexcept {
+            return m_pos;
+        }
+
+        dirty_iterator &operator++() noexcept {
+            m_dt->advance_dirty_position(m_pos, m_level);
+            return *this;
+        }
+
+        dirty_iterator operator++(int) noexcept {
+            auto tmp = *this;
+            ++(*this);
+            return tmp;
+        }
+
+        constexpr bool operator==(const dirty_iterator &rhs) const noexcept {
+            return m_pos == rhs.m_pos;
+        }
+
+        constexpr bool operator!=(const dirty_iterator &rhs) const noexcept {
+            return !(*this == rhs);
+        }
+
+        constexpr bool at_end() const noexcept {
+            return m_pos >= m_level.end();
+        }
+
+        const i_dirty_page_tree *m_dt{nullptr};
+        positions_range m_level{invalid_position, invalid_position};
+        position_iterator m_pos{invalid_position};
+    };
+
+    friend dirty_iterator;
+
+    /// \brief Sentinel for dirty nodes iterator
+    struct dirty_sentinel {
+        constexpr bool operator==(const dirty_iterator &it) const noexcept {
+            return it.at_end();
+        }
+
+        constexpr bool operator!=(const dirty_iterator &it) const noexcept {
+            return !(*this == it);
+        }
+
+        friend constexpr bool operator==(const dirty_iterator &it, const dirty_sentinel &s) noexcept {
+            return s == it;
+        }
+
+        friend constexpr bool operator!=(const dirty_iterator &it, const dirty_sentinel &s) noexcept {
+            return !(s == it);
+        }
+    };
+
+    // -----
+    // Private methods that must be overriden by derived class
+    // These will only ever be called by the base class, and always with valid arguments
+    // -----
+
+    /// \brief Advances a position to the next dirty position within a level
+    /// \param pos Current position to advanced
+    /// \param level Range of positions for level
+    virtual void do_advance_dirty_position(position_iterator &pos, positions_range level) const noexcept = 0;
+
+    /// \brief Marks the node at given position clean (and all its ancestors that only have clean descendants)
+    /// \param pos Node position
+    /// \detail The derived class is free to ignore the operation
+    virtual void do_mark_clean_leaf_position_and_up(position_iterator pos) noexcept = 0;
+
+    /// \brief Marks the node at a given position dirty (and all its ancestors as well)
+    /// \param pos Node position
+    /// \detail The derived class is free to ignore the operation
+    virtual void do_mark_dirty_leaf_position_and_up(position_iterator pos) noexcept = 0;
+
+    /// \brief Tells if the node at given position is dirty
+    /// \param pos Node position
+    /// \returns True if node is dirty, false otherwise
+    virtual bool do_is_dirty_position(position_iterator pos) const noexcept = 0;
+
+    /// \brief Cleans entire tree
+    /// \detail The derived class is free to ignore the operation
+    virtual void do_clean() noexcept = 0;
+
+    /// Non-Virtual Interface (NVI) pattern for do_is_dirty_position()
+    bool is_dirty_position(position_iterator pos) const noexcept {
+        return do_is_dirty_position(pos);
+    }
+
+    /// Non-Virtual Interface (NVI) pattern for do_advance_dirty_position()
+    void advance_dirty_position(position_iterator &pos, positions_range lp) const noexcept {
+        do_advance_dirty_position(pos, lp);
+    }
+
+    /// Non-Virtual Interface (NVI) pattern for do_mark_clean_position_and_up()
+    void mark_clean_leaf_position_and_up(position_iterator pos) noexcept {
+        do_mark_clean_leaf_position_and_up(pos);
+    }
+
+    /// Non-Virtual Interface (NVI) pattern for do_mark_dirty_position_and_up()
+    void mark_dirty_leaf_position_and_up(position_iterator pos) noexcept {
+        do_mark_dirty_leaf_position_and_up(pos);
+    }
+
+    // -----
+    // Private interface
+    // -----
+
+    /// \brief View over dirty positions
+    using dirty_range = std::ranges::subrange<dirty_iterator, dirty_sentinel, std::ranges::subrange_kind::unsized>;
+
+    /// \brief Returns views over all dirty positions within a level
+    /// \param lp Range of positions for desired level
+    dirty_range dirty_positions_view(positions_range lp) const {
+        return dirty_range{dirty_iterator{this, lp}, dirty_sentinel{}};
+    }
+
+    /// \brief Converts a node size to its level in the tree
+    /// \param log2_size Log<sub>2</sub> of node size
+    /// \returns Corresponding level (which may be out of range)
+    static int to_level(int log2_size) {
+        return log2_size - static_cast<int>(AR_LOG2_PAGE_SIZE);
+    }
+
+    /// \brief Converts a node offset/size to the corresponding position
+    /// \param offset Offset in node
+    /// \param log2_size Log<sub>2</sub> of node size
+    /// \returns Corresponding position, or invalid position if out of range
+    position_iterator to_position(uint64_t offset, int log2_size) const {
+        const int level = to_level(log2_size);
+        const auto lp = level_positions_view(level);
+        offset >>= log2_size;
+        if (offset < lp.size()) {
+            return lp.begin() + offset;
+        }
+        return invalid_position;
+    }
+
+public:
+    // -----
+    // Public interface
+    // -----
+
+    /// \brief Constructor from number of leaves
+    /// \param Number of pages in contiguous range
+    explicit constexpr i_dirty_page_tree(int level_count) : m_level_count{level_count} {
+        ;
+    }
+
+    i_dirty_page_tree(const i_dirty_page_tree &other) = default;
+    i_dirty_page_tree &operator=(const i_dirty_page_tree &other) = default;
+    i_dirty_page_tree(i_dirty_page_tree &&other) = default;
+    i_dirty_page_tree &operator=(i_dirty_page_tree &&other) = default;
+
+    // NOLINTNEXTLINE(hicpp-use-equals-default,modernize-use-equals-default)
+    constexpr virtual ~i_dirty_page_tree() {}; // = default; // doesn't work due to bug in gcc
+
+    /// \brief Returns view over the starting offset of all dirty nodes of a given log2_size
+    /// \param log2_size Log<sub>2</sub> of node size
+    /// \details If \p log2_size is out of bounds, returns an empty range
+    auto dirty_offsets_view(int log2_size) const noexcept {
+        const auto lp = level_positions_view(to_level(log2_size)); // Return empty range if level is out of bounds
+        const auto os = lp.empty() ? 0 : lp.front();
+        const int shl = log2_size;
+        return std::views::transform(dirty_positions_view(lp), [os, shl](auto pos) { return (*pos - os) << shl; });
+    }
+
+    /// \brief Marks a page dirty (and all its ancestors as well)
+    /// \param offset Offset within page
+    /// \detail The derived class is free to ignore the operation
+    void mark_dirty_page_and_up(uint64_t offset) noexcept {
+        const auto pos = to_position(offset, AR_LOG2_PAGE_SIZE); // Returns invalid position if node is out of bounds
+        if (pos != invalid_position) {
+            mark_dirty_leaf_position_and_up(pos);
+        }
+    }
+
+    /// \brief Cleans all nodes
+    /// \detail The derived class is free to ignore the operation
+    void clean() noexcept {
+        do_clean();
+    }
+
+    /// \brief Marks a page clean (and all its ancestors that only have clean descendants)
+    /// \param offset Offset within page
+    /// \detail The derived class is free to ignore the operation
+    void mark_clean_page_and_up(uint64_t offset) noexcept {
+        const auto pos = to_position(offset, AR_LOG2_PAGE_SIZE); // Returns invalid position if node is out of bounds
+        if (pos != invalid_position) {
+            mark_clean_leaf_position_and_up(pos);
+        }
+    }
+
+    /// \brief Mark all pages in a range of interest as dirty (including their ancestors)
+    /// \param offset Start of range of interest, relative to start of this range
+    /// \param length Length of range of interest, in bytes
+    void mark_dirty_pages_and_up(uint64_t offset, uint64_t length) noexcept {
+        auto offset_aligned = offset & ~(AR_PAGE_SIZE - 1);
+        const auto length_aligned = length + (offset - offset_aligned);
+        for (; offset_aligned < length_aligned; offset_aligned += AR_PAGE_SIZE) {
+            mark_dirty_page_and_up(offset_aligned);
+        }
+    }
+
+    /// \brief Checks if a node is marked dirty
+    /// \param offset Offset within node
+    /// \param log2_size Log<sub>2</sub> of node size
+    bool is_node_dirty(uint64_t offset, int log2_size) const noexcept {
+        const auto pos = to_position(offset, log2_size); // Returns invalid position if node is out of bounds
+        return (pos != invalid_position) && is_dirty_position(pos);
+    }
+
+private:
+    int m_level_count; // Number of levels in tree
+};
+
+/// \brief Dirty page tree that is forever dirty
+class empty_dirty_page_tree final : public i_dirty_page_tree {
+
+    void do_advance_dirty_position(position_iterator &pos, positions_range /*level*/) const noexcept override {
+        pos = invalid_position;
+    }
+
+    void do_mark_dirty_leaf_position_and_up(position_iterator /*pos*/) noexcept override {
+        ;
+    }
+
+    void do_mark_clean_leaf_position_and_up(position_iterator /*pos*/) noexcept override {
+        ;
+    }
+
+    bool do_is_dirty_position(position_iterator /*pos*/) const noexcept override {
+        return true;
+    }
+
+    void do_clean() noexcept override {
+        ;
+    }
+
+public:
+    empty_dirty_page_tree() noexcept : i_dirty_page_tree{0} {
+        ;
+    }
+    empty_dirty_page_tree(const empty_dirty_page_tree &other) = default;
+    empty_dirty_page_tree &operator=(const empty_dirty_page_tree &other) = default;
+    empty_dirty_page_tree(empty_dirty_page_tree &&other) = default;
+    empty_dirty_page_tree &operator=(empty_dirty_page_tree &&other) = default;
+    // NOLINTNEXTLINE(hicpp-use-equals-default,modernize-use-equals-default)
+    constexpr ~empty_dirty_page_tree() override {}; // = default; // doesn't work due to bug in gcc
+};
+
+} // namespace cartesi
+
+#endif // I_DIRTY_PAGE_TREE_H
diff --git a/src/i-hasher.h b/src/i-hasher.h
index b00645493..ad9429a6a 100644
--- a/src/i-hasher.h
+++ b/src/i-hasher.h
@@ -20,20 +20,22 @@
 /// \file
 /// \brief Hasher interface
 
-#include <array>
 #include <cstddef>
 #include <cstdint>
+#include <ranges>
+#include <span>
 #include <stdexcept>
 #include <type_traits>
 
+#include "concepts.h"
+#include "machine-hash.h"
 #include "meta.h"
 
 namespace cartesi {
 
 /// \brief Hasher interface.
 /// \tparam DERIVED Derived class implementing the interface. (An example of CRTP.)
-/// \tparam HASH_SIZE Size of hash.
-template <typename DERIVED, typename HASH_SIZE>
+template <typename DERIVED>
 class i_hasher { // CRTP
     /// \brief Returns object cast as the derived class
     DERIVED &derived() {
@@ -46,19 +48,16 @@ class i_hasher { // CRTP
     }
 
 public:
-    constexpr static size_t hash_size = HASH_SIZE::value;
-
-    using hash_type = std::array<unsigned char, hash_size>;
-
-    void begin() {
+    void begin() noexcept {
         return derived().do_begin();
     }
 
-    void add_data(const unsigned char *data, size_t length) {
-        return derived().do_add_data(data, length);
+    template <ContiguousRangeOfByteLike D>
+    void add_data(D &&data) noexcept {
+        return derived().do_add_data(std::forward<D>(data));
     }
 
-    void end(hash_type &hash) {
+    void end(machine_hash_view hash) noexcept {
         return derived().do_end(hash);
     }
 };
@@ -69,19 +68,46 @@ using is_an_i_hasher = std::integral_constant<bool, is_template_base_of_v<i_hash
 template <typename DERIVED>
 constexpr bool is_an_i_hasher_v = is_an_i_hasher<DERIVED>::value;
 
+// C++20 concept for is_an_i_hasher_v
+template <typename T>
+concept IHasher = is_an_i_hasher_v<T>;
+
+/// \brief Computes the hash of data
+/// \tparam H Hasher class
+/// \param h Hasher object
+/// \param data Data to hash
+/// \param result Receives the hash of data
+template <IHasher H, ContiguousRangeOfByteLike D>
+inline static void get_hash(H &h, D &&data, machine_hash_view result) noexcept {
+    h.begin();
+    h.add_data(std::forward<D>(data));
+    h.end(result);
+}
+
+/// \brief Computes the hash of data
+/// \tparam H Hasher class
+/// \param h Hasher object
+/// \param data Data to hash
+/// \returns The hash of data
+template <IHasher H, ContiguousRangeOfByteLike D>
+inline static machine_hash get_hash(H &&h, D &&data) noexcept {
+    machine_hash result;
+    get_hash(std::forward<H>(h), std::forward<D>(data), result);
+    return result;
+}
+
 /// \brief Computes the hash of concatenated hashes
 /// \tparam H Hasher class
 /// \param h Hasher object
 /// \param left Left hash to concatenate
 /// \param right Right hash to concatenate
 /// \param result Receives the hash of the concatenation
-template <typename H>
-inline static void get_concat_hash(H &h, const typename H::hash_type &left, const typename H::hash_type &right,
-    typename H::hash_type &result) {
-    static_assert(is_an_i_hasher_v<H>, "not an i_hasher");
+template <IHasher H>
+inline static void get_concat_hash(H &h, const_machine_hash_view left, const_machine_hash_view right,
+    machine_hash_view result) noexcept {
     h.begin();
-    h.add_data(left.data(), static_cast<int>(left.size()));
-    h.add_data(right.data(), static_cast<int>(right.size()));
+    h.add_data(left);
+    h.add_data(right);
     h.end(result);
 }
 
@@ -91,50 +117,58 @@ inline static void get_concat_hash(H &h, const typename H::hash_type &left, cons
 /// \param left Left hash to concatenate
 /// \param right Right hash to concatenate
 /// \return The hash of the concatenation
-template <typename H>
-inline static typename H::hash_type get_concat_hash(H &h, const typename H::hash_type &left,
-    const typename H::hash_type &right) {
-    static_assert(is_an_i_hasher_v<H>, "not an i_hasher");
-    h.begin();
-    h.add_data(left.data(), left.size());
-    h.add_data(right.data(), right.size());
-    typename H::hash_type result;
-    h.end(result);
+template <IHasher H>
+inline static machine_hash get_concat_hash(H &&h, const_machine_hash_view left,
+    const_machine_hash_view right) noexcept {
+    machine_hash result;
+    get_concat_hash(std::forward<H>(h), left, right, result);
     return result;
 }
 
 /// \brief  Computes a merkle tree hash of a data buffer
 /// \tparam H Hasher class
+/// \tparam D Contiguous range class
 /// \param h Hasher object
 /// \param data Data to be hashed
-/// \param data_length Length of data
-/// \param word_length  Length of each word
+/// \param leaf_length  Length of each leaf
 /// \param result Receives the resulting merkle tree hash
-template <typename H>
-inline static void get_merkle_tree_hash(H &h, const unsigned char *data, uint64_t data_length, uint64_t word_length,
-    typename H::hash_type &result) {
-    if (data_length > word_length) {
-        if (data_length & 1) {
-            throw std::invalid_argument("data_length must be a power of 2 multiple of word_length");
+template <IHasher H, ContiguousRangeOfByteLike D>
+inline static void get_merkle_tree_hash(H &&h, D &&data, uint64_t leaf_length, machine_hash_view result) {
+    const auto size = std::ranges::size(data);
+    if (size > leaf_length) {
+        if (size & 1) {
+            throw std::invalid_argument("data size must be a power of 2 multiple of leaf_length");
         }
-        data_length = data_length / 2;
-        typename H::hash_type left;
-        get_merkle_tree_hash(h, data, data_length, word_length, left);
-        get_merkle_tree_hash(h, data + data_length, data_length, word_length, result);
-        h.begin();
-        h.add_data(left.data(), left.size());
-        h.add_data(result.data(), result.size());
-        h.end(result);
+        machine_hash left;
+        const auto half_size = size >> 1;
+        auto start = std::ranges::begin(data);
+        get_merkle_tree_hash(h, std::ranges::subrange(start, start + half_size), leaf_length, left);
+        get_merkle_tree_hash(h, std::ranges::subrange(start + half_size, start + size), leaf_length, result);
+        get_concat_hash(h, left, result, result);
     } else {
-        if (data_length != word_length) {
-            throw std::invalid_argument("data_length must be a power of 2 multiple of word_length");
+        if (size != leaf_length) {
+            throw std::invalid_argument("data size must be a power of 2 multiple of leaf length");
         }
-        h.begin();
-        h.add_data(data, data_length);
-        h.end(result);
+        //??D we use universal references so the function works with non-const l- and r-value references
+        //??D forwarding just to silence linter.
+        get_hash(std::forward<H>(h), std::forward<D>(data), result);
     }
 }
 
+/// \brief  Computes a merkle tree hash of a data buffer
+/// \tparam H Hasher class
+/// \tparam D Contiguous range class
+/// \param h Hasher object
+/// \param data Data to be hashed
+/// \param leaf_length  Length of each leaf
+/// \returns The resulting merkle tree hash
+template <IHasher H, ContiguousRangeOfByteLike D>
+inline static machine_hash get_merkle_tree_hash(H &&h, D &&data, uint64_t leaf_length) {
+    machine_hash hash;
+    get_merkle_tree_hash(std::forward<H>(h), std::forward<D>(data), leaf_length, hash);
+    return hash;
+}
+
 } // namespace cartesi
 
 #endif
diff --git a/src/i-machine.h b/src/i-machine.h
index ee82aa6be..4a2da1142 100644
--- a/src/i-machine.h
+++ b/src/i-machine.h
@@ -22,9 +22,10 @@
 
 #include "access-log.h"
 #include "address-range-description.h"
+#include "hash-tree.h"
 #include "interpret.h"
 #include "machine-config.h"
-#include "machine-merkle-tree.h"
+#include "machine-hash.h"
 #include "machine.h"
 #include "uarch-interpret.h"
 
@@ -44,7 +45,7 @@ namespace cartesi {
 /// \}
 class i_machine {
 public:
-    using hash_type = machine_merkle_tree::hash_type;
+    using proof_type = hash_tree::proof_type;
     using reg = machine_reg;
 
     /// \brief Constructor
@@ -99,18 +100,23 @@ class i_machine {
     }
 
     /// \brief Obtains the proof for a node in the Merkle tree.
-    machine_merkle_tree::proof_type get_proof(uint64_t address, int log2_size) const {
+    proof_type get_proof(uint64_t address, int log2_size) const {
         return do_get_proof(address, log2_size);
     }
 
     /// \brief Obtains the root hash of the Merkle tree.
-    void get_root_hash(hash_type &hash) const {
-        do_get_root_hash(hash);
+    machine_hash get_root_hash() const {
+        return do_get_root_hash();
+    }
+
+    /// \brief Obtains the root hash of the Merkle tree.
+    machine_hash get_node_hash(uint64_t address, int log2_size) const {
+        return do_get_node_hash(address, log2_size);
     }
 
     /// \brief Verifies integrity of Merkle tree.
-    bool verify_merkle_tree() const {
-        return do_verify_merkle_tree();
+    bool verify_hash_tree() const {
+        return do_verify_hash_tree();
     }
 
     /// \brief Reads the value of any register
@@ -158,11 +164,6 @@ class i_machine {
         return do_read_word(address);
     }
 
-    /// \brief Verify if dirty page maps are consistent.
-    bool verify_dirty_page_maps() const {
-        return do_verify_dirty_page_maps();
-    }
-
     /// \brief Returns copy of initialization config.
     machine_config get_initial_config() const {
         return do_get_initial_config();
@@ -226,26 +227,26 @@ class i_machine {
     }
 
     /// \brief Checks the validity of a state transition caused by log_step.
-    interpreter_break_reason verify_step(const hash_type &root_hash_before, const std::string &log_filename,
-        uint64_t mcycle_count, const hash_type &root_hash_after) const {
+    interpreter_break_reason verify_step(const machine_hash &root_hash_before, const std::string &log_filename,
+        uint64_t mcycle_count, const machine_hash &root_hash_after) const {
         return do_verify_step(root_hash_before, log_filename, mcycle_count, root_hash_after);
     }
 
     /// \brief Checks the validity of a state transition caused by log_step_uarch.
-    void verify_step_uarch(const hash_type &root_hash_before, const access_log &log,
-        const hash_type &root_hash_after) const {
+    void verify_step_uarch(const machine_hash &root_hash_before, const access_log &log,
+        const machine_hash &root_hash_after) const {
         do_verify_step_uarch(root_hash_before, log, root_hash_after);
     }
 
     /// \brief Checks the validity of a state transition caused by log_reset_uarch.
-    void verify_reset_uarch(const hash_type &root_hash_before, const access_log &log,
-        const hash_type &root_hash_after) const {
+    void verify_reset_uarch(const machine_hash &root_hash_before, const access_log &log,
+        const machine_hash &root_hash_after) const {
         do_verify_reset_uarch(root_hash_before, log, root_hash_after);
     }
 
     /// \brief Checks the validity of state transitions caused by log_send_cmio_response.
     void verify_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
-        const hash_type &root_hash_before, const access_log &log, const hash_type &root_hash_after) const {
+        const machine_hash &root_hash_before, const access_log &log, const machine_hash &root_hash_after) const {
         do_verify_send_cmio_response(reason, data, length, root_hash_before, log, root_hash_after);
     }
 
@@ -263,9 +264,9 @@ class i_machine {
     virtual void do_store(const std::string &dir) const = 0;
     virtual interpreter_break_reason do_log_step(uint64_t mcycle_count, const std::string &filename) = 0;
     virtual access_log do_log_step_uarch(const access_log::type &log_type) = 0;
-    virtual machine_merkle_tree::proof_type do_get_proof(uint64_t address, int log2_size) const = 0;
-    virtual void do_get_root_hash(hash_type &hash) const = 0;
-    virtual bool do_verify_merkle_tree() const = 0;
+    virtual proof_type do_get_proof(uint64_t address, int log2_size) const = 0;
+    virtual machine_hash do_get_root_hash() const = 0;
+    virtual machine_hash do_get_node_hash(uint64_t address, int log2_size) const = 0;
     virtual uint64_t do_read_reg(reg r) const = 0;
     virtual void do_write_reg(reg w, uint64_t val) = 0;
     virtual void do_read_memory(uint64_t address, unsigned char *data, uint64_t length) const = 0;
@@ -275,7 +276,6 @@ class i_machine {
     virtual uint64_t do_translate_virtual_address(uint64_t vaddr) = 0;
     virtual void do_replace_memory_range(const memory_range_config &new_range) = 0;
     virtual uint64_t do_read_word(uint64_t address) const = 0;
-    virtual bool do_verify_dirty_page_maps() const = 0;
     virtual machine_config do_get_initial_config() const = 0;
     virtual machine_runtime_config do_get_runtime_config() const = 0;
     virtual void do_set_runtime_config(const machine_runtime_config &r) = 0;
@@ -289,14 +289,15 @@ class i_machine {
         const access_log::type &log_type) = 0;
     virtual uint64_t do_get_reg_address(reg r) const = 0;
     virtual machine_config do_get_default_config() const = 0;
-    virtual interpreter_break_reason do_verify_step(const hash_type &root_hash_before, const std::string &log_filename,
-        uint64_t mcycle_count, const hash_type &root_hash_after) const = 0;
-    virtual void do_verify_step_uarch(const hash_type &root_hash_before, const access_log &log,
-        const hash_type &root_hash_after) const = 0;
-    virtual void do_verify_reset_uarch(const hash_type &root_hash_before, const access_log &log,
-        const hash_type &root_hash_after) const = 0;
+    virtual interpreter_break_reason do_verify_step(const machine_hash &root_hash_before,
+        const std::string &log_filename, uint64_t mcycle_count, const machine_hash &root_hash_after) const = 0;
+    virtual void do_verify_step_uarch(const machine_hash &root_hash_before, const access_log &log,
+        const machine_hash &root_hash_after) const = 0;
+    virtual void do_verify_reset_uarch(const machine_hash &root_hash_before, const access_log &log,
+        const machine_hash &root_hash_after) const = 0;
     virtual void do_verify_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
-        const hash_type &root_hash_before, const access_log &log, const hash_type &root_hash_after) const = 0;
+        const machine_hash &root_hash_before, const access_log &log, const machine_hash &root_hash_after) const = 0;
+    virtual bool do_verify_hash_tree() const = 0;
     virtual bool do_is_jsonrpc_machine() const {
         return false;
     }
diff --git a/src/is-pristine.h b/src/is-pristine.h
index 7f94c0384..f371399ab 100644
--- a/src/is-pristine.h
+++ b/src/is-pristine.h
@@ -17,17 +17,19 @@
 #ifndef IS_PRISTINE_H
 #define IS_PRISTINE_H
 
-#include "compiler-defines.h"
-#include <stddef.h>
-#include <stdint.h>
+#include <cstddef>
+#include <cstdint>
+#include <ranges>
+
+#include "meta.h"
 
 namespace cartesi {
 
 /// \brief This is an optimized function for checking if memory page is pristine.
 /// \param data Memory pointer
 /// \param length Memory length
-/// \details It's instead to be used in situations where length is equal or less than a page size.
-// NOLINTNEXTLINE(clang-diagnostic-unknown-attributes)
+/// \returns True if all values are 0, false otherwise
+/// \details It's to be used in situations where length is equal or less than a page size.
 static inline bool is_pristine(const unsigned char *data, size_t length) {
     // This tight for loop has no branches, and is optimized to SIMD instructions in x86_64,
     // making it very fast to check if a given page is pristine.
@@ -38,6 +40,19 @@ static inline bool is_pristine(const unsigned char *data, size_t length) {
     return bits == 0;
 }
 
+/// \brief This is an optimized function for checking if memory page is pristine.
+/// \param r Contiguous range of byte-like values
+/// \returns True if all values are 0, false otherwise
+/// \details It's to be used in situations where length is equal or less than a page size.
+template <ContiguousRangeOfByteLike R>
+static inline bool is_pristine(R &&r) { // NOLINT(cppcoreguidelines-missing-std-forward)
+    std::ranges::range_value_t<R> bits{0};
+    for (auto b : r) {
+        bits |= b;
+    }
+    return bits == 0;
+}
+
 } // namespace cartesi
 
 #endif
diff --git a/src/json-util.cpp b/src/json-util.cpp
index 2349bd54c..0dde7f9db 100644
--- a/src/json-util.cpp
+++ b/src/json-util.cpp
@@ -36,12 +36,14 @@
 #include "address-range-description.h"
 #include "base64.h"
 #include "bracket-note.h"
+#include "hash-tree.h"
 #include "interpret.h"
 #include "jsonrpc-fork-result.h"
 #include "machine-config.h"
-#include "machine-merkle-tree.h"
+#include "machine-hash.h"
 #include "machine-runtime-config.h"
 #include "machine.h"
+#include "meta.h"
 #include "semantic-version.h"
 #include "uarch-interpret.h"
 
@@ -55,20 +57,6 @@ std::string to_string(const char *s) {
     return s;
 }
 
-std::string encode_base64(const unsigned char *data, uint64_t length) {
-    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-    const std::string input(reinterpret_cast<const char *>(data), length);
-    return encode_base64(input);
-}
-
-std::string encode_base64(const machine_merkle_tree::hash_type &hash) {
-    return encode_base64(hash.data(), hash.size());
-}
-
-std::string encode_base64(const access_data &data) {
-    return encode_base64(data.data(), data.size());
-}
-
 /// \brief Converts between a register name and a register index
 /// \param name Register name
 /// \returns The register index
@@ -773,7 +761,7 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, concurrency_runtime
     if (!contains(j, key, path)) {
         return;
     }
-    ju_get_opt_field(j[key], "update_merkle_tree"s, value.update_merkle_tree, path + to_string(key) + "/");
+    ju_get_opt_field(j[key], "update_hash_tree"s, value.update_hash_tree, path + to_string(key) + "/");
 }
 
 template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key,
@@ -816,8 +804,7 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
     machine_runtime_config &value, const std::string &path);
 
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, machine_merkle_tree::proof_type::hash_type &value,
-    const std::string &path) {
+void ju_get_opt_field(const nlohmann::json &j, const K &key, machine_hash &value, const std::string &path) {
     if (!contains(j, key, path)) {
         return;
     }
@@ -829,12 +816,12 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, machine_merkle_tree
     if (bin.size() != value.size()) {
         throw std::invalid_argument("\""s + path + to_string(key) + "\" not a base64-encoded 256-bit hash");
     }
-    std::copy(bin.begin(), bin.end(), value.data());
+    std::ranges::copy(bin | views::cast_to<machine_hash::value_type>, std::ranges::data(value));
 }
 
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key,
-    std::optional<machine_merkle_tree::proof_type::hash_type> &optional, const std::string &path) {
+void ju_get_opt_field(const nlohmann::json &j, const K &key, std::optional<machine_hash> &optional,
+    const std::string &path) {
     optional = {};
     if (!contains(j, key, path)) {
         return;
@@ -848,18 +835,18 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key,
     if (bin.size() != optional.value().size()) {
         throw std::invalid_argument("\""s + path + to_string(key) + "\" not a base64-encoded 256-bit hash");
     }
-    std::copy(bin.begin(), bin.end(), optional.value().data());
+    std::ranges::copy(bin | views::cast_to<machine_hash::value_type>, std::ranges::data(optional.value()));
 }
 
-template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key,
-    machine_merkle_tree::proof_type::hash_type &value, const std::string &path);
+template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, machine_hash &value,
+    const std::string &path);
 
-template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key,
-    machine_merkle_tree::proof_type::hash_type &value, const std::string &path);
+template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key, machine_hash &value,
+    const std::string &path);
 
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key,
-    not_default_constructible<machine_merkle_tree::proof_type> &value, const std::string &path) {
+void ju_get_opt_field(const nlohmann::json &j, const K &key, not_default_constructible<hash_tree::proof_type> &value,
+    const std::string &path) {
     value = {};
     if (!contains(j, key, path)) {
         return;
@@ -878,13 +865,13 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key,
     }
     value.emplace(static_cast<int>(log2_root_size), static_cast<int>(log2_target_size));
     auto &proof = value.value();
-    machine_merkle_tree::proof_type::address_type target_address = 0;
+    uint64_t target_address = 0;
     ju_get_field(jk, "target_address"s, target_address, new_path);
     proof.set_target_address(target_address);
-    machine_merkle_tree::proof_type::hash_type target_hash;
+    machine_hash target_hash;
     ju_get_field(jk, "target_hash"s, target_hash, new_path);
     proof.set_target_hash(target_hash);
-    machine_merkle_tree::proof_type::hash_type root_hash;
+    machine_hash root_hash;
     ju_get_field(jk, "root_hash"s, root_hash, new_path);
     proof.set_root_hash(root_hash);
     if (!contains(jk, "sibling_hashes", new_path)) {
@@ -897,17 +884,17 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key,
     const auto sibling_hashes_base = path + "sibling_hashes/";
     for (int log2_size = proof.get_log2_target_size(), i = 0; log2_size < proof.get_log2_root_size();
         ++log2_size, ++i) {
-        machine_merkle_tree::proof_type::hash_type sibling_hash;
+        machine_hash sibling_hash;
         ju_get_field(sh, i, sibling_hash, sibling_hashes_base);
         proof.set_sibling_hash(sibling_hash, log2_size);
     }
 }
 
 template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key,
-    not_default_constructible<machine_merkle_tree::proof_type> &value, const std::string &path);
+    not_default_constructible<hash_tree::proof_type> &value, const std::string &path);
 
 template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key,
-    not_default_constructible<machine_merkle_tree::proof_type> &value, const std::string &path);
+    not_default_constructible<hash_tree::proof_type> &value, const std::string &path);
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, access_type &value, const std::string &path) {
@@ -991,17 +978,16 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, access &access, con
         throw std::domain_error("\""s + new_path + "log2_size\" is out of bounds");
     }
     access.set_log2_size(static_cast<int>(log2_size));
-    // Minimum logged data size is merkle tree word size
-    const uint64_t data_log2_size =
-        std::max(log2_size, static_cast<uint64_t>(machine_merkle_tree::get_log2_word_size()));
+    // Minimum logged data size is hash-tree word size
+    const uint64_t data_log2_size = std::max(log2_size, static_cast<uint64_t>(HASH_TREE_LOG2_WORD_SIZE));
     uint64_t address = 0;
     ju_get_field(jk, "address"s, address, new_path);
     access.set_address(address);
-    machine_merkle_tree::proof_type::hash_type read_hash;
+    machine_hash read_hash;
     ju_get_field(jk, "read_hash", read_hash, new_path);
     access.set_read_hash(read_hash);
 
-    not_default_constructible<machine_merkle_tree::proof_type::hash_type> written_hash;
+    not_default_constructible<machine_hash> written_hash;
     ju_get_opt_field(jk, "written_hash", written_hash, new_path);
     if (written_hash.has_value()) {
         access.set_written_hash(written_hash.value());
@@ -1030,7 +1016,7 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, access &access, con
         // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
         auto &sibling_hashes = access.get_sibling_hashes().value();
         ju_get_vector_like_field(jk, "sibling_hashes"s, sibling_hashes, new_path);
-        auto expected_depth = static_cast<size_t>(machine_merkle_tree::get_log2_root_size() - data_log2_size);
+        auto expected_depth = static_cast<size_t>(HASH_TREE_LOG2_ROOT_SIZE - data_log2_size);
         if (sibling_hashes.size() != expected_depth) {
             throw std::invalid_argument("\""s + new_path + "sibling_hashes\" has wrong length");
         }
@@ -1354,7 +1340,6 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, hash_tree_config &v
     ju_get_opt_field(jconfig, "shared"s, value.shared, new_path);
     ju_get_opt_field(jconfig, "create"s, value.create, new_path);
     ju_get_opt_field(jconfig, "truncate"s, value.truncate, new_path);
-    ju_get_opt_field(jconfig, "hasher"s, value.hasher, new_path);
     ju_get_opt_field(jconfig, "sht_filename"s, value.sht_filename, new_path);
     ju_get_opt_field(jconfig, "phtc_filename"s, value.phtc_filename, new_path);
     ju_get_opt_field(jconfig, "phtc_size"s, value.phtc_size, new_path);
@@ -1378,6 +1363,7 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, backing_store_confi
     ju_get_opt_field(jconfig, "truncate"s, value.truncate, new_path);
     ju_get_opt_field(jconfig, "data_filename"s, value.data_filename, new_path);
     ju_get_opt_field(jconfig, "dht_filename"s, value.dht_filename, new_path);
+    ju_get_opt_field(jconfig, "dpt_filename"s, value.dpt_filename, new_path);
 }
 
 template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, backing_store_config &value,
@@ -1748,17 +1734,17 @@ void to_json(nlohmann::json &j, const machine::reg &reg) {
     j = reg_to_name(reg);
 }
 
-void to_json(nlohmann::json &j, const machine_merkle_tree::hash_type &h) {
+void to_json(nlohmann::json &j, const machine_hash &h) {
     j = encode_base64(h);
 }
 
-void to_json(nlohmann::json &j, const std::vector<machine_merkle_tree::hash_type> &hs) {
+void to_json(nlohmann::json &j, const std::vector<machine_hash> &hs) {
     j = nlohmann::json::array();
     std::transform(hs.cbegin(), hs.cend(), std::back_inserter(j),
-        [](const machine_merkle_tree::hash_type &h) -> nlohmann::json { return h; });
+        [](const machine_hash &h) -> nlohmann::json { return h; });
 }
 
-void to_json(nlohmann::json &j, const machine_merkle_tree::proof_type &p) {
+void to_json(nlohmann::json &j, const hash_tree::proof_type &p) {
     nlohmann::json s = nlohmann::json::array();
     for (int log2_size = p.get_log2_target_size(); log2_size < p.get_log2_root_size(); ++log2_size) {
         s.push_back(encode_base64(p.get_sibling_hash(log2_size)));
@@ -1794,9 +1780,9 @@ void to_json(nlohmann::json &j, const access &a) {
     if (a.get_sibling_hashes().has_value()) {
         // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
         const auto &sibling_hashes = a.get_sibling_hashes().value();
-        // Minimum logged data size is merkle tree word size
-        auto data_log2_size = std::max(a.get_log2_size(), machine_merkle_tree::get_log2_word_size());
-        auto depth = machine_merkle_tree::get_log2_root_size() - data_log2_size;
+        // Minimum logged data size is hash-tree word size
+        auto data_log2_size = std::max(a.get_log2_size(), HASH_TREE_LOG2_WORD_SIZE);
+        auto depth = HASH_TREE_LOG2_ROOT_SIZE - data_log2_size;
         nlohmann::json s = nlohmann::json::array();
         for (int i = 0; i < depth; i++) {
             s.push_back(encode_base64(sibling_hashes[i]));
@@ -1834,7 +1820,8 @@ void to_json(nlohmann::json &j, const access_log &log) {
 
 void to_json(nlohmann::json &j, const backing_store_config &config) {
     j = nlohmann::json{{"shared", config.shared}, {"create", config.create}, {"truncate", config.truncate},
-        {"data_filename", config.data_filename}, {"dht_filename", config.dht_filename}};
+        {"data_filename", config.data_filename}, {"dht_filename", config.dht_filename},
+        {"dpt_filename", config.dpt_filename}};
 }
 
 void to_json(nlohmann::json &j, const backing_store_config_only &config) {
@@ -1847,8 +1834,8 @@ void to_json(nlohmann::json &j, const memory_range_config &config) {
 }
 
 void to_json(nlohmann::json &j, const hash_tree_config &config) {
-    j = nlohmann::json{{"hasher", config.hasher}, {"shared", config.shared}, {"create", config.create},
-        {"truncate", config.truncate}, {"sht_filename", config.sht_filename}, {"phtc_filename", config.phtc_filename},
+    j = nlohmann::json{{"shared", config.shared}, {"create", config.create}, {"truncate", config.truncate},
+        {"sht_filename", config.sht_filename}, {"phtc_filename", config.phtc_filename},
         {"phtc_size", config.phtc_size}};
 }
 
@@ -2047,7 +2034,7 @@ void to_json(nlohmann::json &j, const machine_config &config) {
 
 void to_json(nlohmann::json &j, const concurrency_runtime_config &config) {
     j = nlohmann::json{
-        {"update_merkle_tree", config.update_merkle_tree},
+        {"update_hash_tree", config.update_hash_tree},
     };
 }
 
diff --git a/src/json-util.h b/src/json-util.h
index 4f6e9d186..cc6469f69 100644
--- a/src/json-util.h
+++ b/src/json-util.h
@@ -30,10 +30,11 @@
 #include "access-log.h"
 #include "address-range-description.h"
 #include "bracket-note.h"
+#include "hash-tree.h"
 #include "interpret.h"
 #include "jsonrpc-fork-result.h"
 #include "machine-config.h"
-#include "machine-merkle-tree.h"
+#include "machine-hash.h"
 #include "machine-runtime-config.h"
 #include "machine.h"
 #include "semantic-version.h"
@@ -209,8 +210,7 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, machine_runtime_con
 /// \param value Object to store value
 /// \param path Path to j
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, machine_merkle_tree::proof_type::hash_type &value,
-    const std::string &path = "params/");
+void ju_get_opt_field(const nlohmann::json &j, const K &key, machine_hash &value, const std::string &path = "params/");
 
 /// \brief Attempts to load a hash from a field in a JSON object
 /// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
@@ -219,8 +219,8 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, machine_merkle_tree
 /// \param value Object to store value
 /// \param path Path to j
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key,
-    std::optional<machine_merkle_tree::proof_type::hash_type> &optional, const std::string &path = "params/");
+void ju_get_opt_field(const nlohmann::json &j, const K &key, std::optional<machine_hash> &optional,
+    const std::string &path = "params/");
 
 /// \brief Attempts to load an Merkle tree proof object from a field in a JSON object
 /// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
@@ -229,8 +229,8 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key,
 /// \param value Object to store value
 /// \param path Path to j
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key,
-    not_default_constructible<machine_merkle_tree::proof_type> &value, const std::string &path = "params/");
+void ju_get_opt_field(const nlohmann::json &j, const K &key, not_default_constructible<hash_tree::proof_type> &value,
+    const std::string &path = "params/");
 
 /// \brief Attempts to load an access_type name from a field in a JSON object
 /// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
@@ -613,27 +613,11 @@ void ju_get_field(const nlohmann::json &j, const K &key, T &value, const std::st
     ju_get_opt_field(j, key, value, path);
 }
 
-/// \brief Encodes binary data into base64
-/// \param data Pointer to start of binary data
-/// \param length Length of data
-/// \returns Encoded data
-std::string encode_base64(const unsigned char *data, uint64_t length);
-
-/// \brief Encodes a hash as a base64 string
-/// \param hash Hash to encode
-/// \returns Encoded data
-std::string encode_base64(const machine_merkle_tree::hash_type &hash);
-
-/// \brief Encodes an access_data object as a base64 string
-/// \param data Access data to encode
-/// \returns Encoded data
-std::string encode_base64(const access_data &data);
-
 // Automatic conversion functions from Cartesi types to nlohmann::json
 void to_json(nlohmann::json &j, const access_log::type &log_type);
-void to_json(nlohmann::json &j, const machine_merkle_tree::hash_type &h);
-void to_json(nlohmann::json &j, const std::vector<machine_merkle_tree::hash_type> &hs);
-void to_json(nlohmann::json &j, const machine_merkle_tree::proof_type &p);
+void to_json(nlohmann::json &j, const machine_hash &h);
+void to_json(nlohmann::json &j, const std::vector<machine_hash> &hs);
+void to_json(nlohmann::json &j, const hash_tree::proof_type &p);
 void to_json(nlohmann::json &j, const access &a);
 void to_json(nlohmann::json &j, const bracket_note &b);
 void to_json(nlohmann::json &j, const std::vector<bracket_note> &bs);
@@ -713,14 +697,14 @@ extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &k
     const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, machine_runtime_config &value,
     const std::string &base = "params/");
+extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, machine_hash &value,
+    const std::string &base = "params/");
+extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, machine_hash &value,
+    const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key,
-    machine_merkle_tree::proof_type::hash_type &value, const std::string &base = "params/");
-extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key,
-    machine_merkle_tree::proof_type::hash_type &value, const std::string &base = "params/");
-extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key,
-    not_default_constructible<machine_merkle_tree::proof_type> &value, const std::string &base = "params/");
+    not_default_constructible<hash_tree::proof_type> &value, const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key,
-    not_default_constructible<machine_merkle_tree::proof_type> &value, const std::string &base = "params/");
+    not_default_constructible<hash_tree::proof_type> &value, const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, access_type &value,
     const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, access_type &value,
diff --git a/src/jsonrpc-discover.json b/src/jsonrpc-discover.json
index 07775c656..60de86bb9 100644
--- a/src/jsonrpc-discover.json
+++ b/src/jsonrpc-discover.json
@@ -688,24 +688,12 @@
       }
     },
     {
-      "name": "machine.verify_merkle_tree",
-      "summary": "Verifies sanity of Merkle tree",
+      "name": "machine.verify_hash_tree",
+      "summary": "Verifies sanity of hash tree",
       "params": [],
       "result": {
         "name": "valid",
-        "description": "True if Merkle tree is sane",
-        "schema": {
-          "type": "boolean"
-        }
-      }
-    },
-    {
-      "name": "machine.verify_dirty_page_maps",
-      "summary": "Verifies sanity of dirty page maps",
-      "params": [],
-      "result": {
-        "name": "valid",
-        "description": "True if dirty page maps are sane",
+        "description": "True if hash tree is sane",
         "schema": {
           "type": "boolean"
         }
@@ -962,7 +950,7 @@
         "title": "ConcurrencyRuntimeConfig",
         "type": "object",
         "properties": {
-          "update_merkle_tree": {
+          "update_hash_tree": {
             "$ref": "#/components/schemas/UnsignedInteger"
           }
         }
diff --git a/src/jsonrpc-machine.cpp b/src/jsonrpc-machine.cpp
index 44ffe334e..b6231ca09 100644
--- a/src/jsonrpc-machine.cpp
+++ b/src/jsonrpc-machine.cpp
@@ -69,7 +69,6 @@
 #include "jsonrpc-fork-result.h"
 #include "jsonrpc-version.h"
 #include "machine-config.h"
-#include "machine-merkle-tree.h"
 #include "machine-runtime-config.h"
 #include "os.h"
 #include "scope-exit.h"
@@ -78,7 +77,6 @@
 
 using namespace std::string_literals;
 using json = nlohmann::json;
-using hash_type = cartesi::machine_merkle_tree::hash_type;
 
 namespace beast = boost::beast; // from <boost/beast.hpp>
 namespace http = beast::http;   // from <boost/beast/http.hpp>
@@ -124,7 +122,7 @@ static asio::ip::tcp::endpoint parse_endpoint(const std::string &address) {
             throw std::runtime_error("invalid port number"s);
         }
         return {asio::ip::make_address(host), static_cast<uint16_t>(port)};
-    } catch (std::exception &e) {
+    } catch (const std::exception &e) {
         throw std::runtime_error("failed to parse endpoint from address \""s + address + "\": "s + e.what());
     }
 }
@@ -279,13 +277,13 @@ static void jsonrpc_request(std::unique_ptr<boost::asio::io_context> &ioc, std::
     std::string response_s;
     try {
         response_s = json_post(*ioc, *stream, remote_address, request, timeout_at, keep_alive);
-    } catch (std::exception &x) {
+    } catch (const std::exception &x) {
         throw std::runtime_error("jsonrpc error: post error contacting "s + remote_address + " ("s + x.what() + ")"s);
     }
     json response;
     try {
         response = json::parse(response_s);
-    } catch (std::exception &x) {
+    } catch (const std::exception &x) {
         throw std::runtime_error("jsonrpc server error: invalid response ("s + x.what() + ")"s);
     }
     if (!response.contains("jsonrpc")) {
@@ -323,7 +321,7 @@ static void jsonrpc_request(std::unique_ptr<boost::asio::io_context> &ioc, std::
     }
     try {
         cartesi::ju_get_field(response, "result"s, result, ""s);
-    } catch (std::exception &x) {
+    } catch (const std::exception &x) {
         throw std::runtime_error("jsonrpc server error: "s + x.what());
     }
 }
@@ -430,7 +428,7 @@ static boost::asio::ip::tcp::endpoint address_to_endpoint(const std::string &add
             throw std::runtime_error{"invalid port"};
         }
         return {boost::asio::ip::make_address(ip), static_cast<uint16_t>(port)};
-    } catch (std::exception &e) {
+    } catch (const std::exception &e) {
         throw std::runtime_error{"invalid endpoint address \"" + address + "\""};
     }
 }
@@ -697,7 +695,7 @@ void jsonrpc_machine::do_read_memory(uint64_t address, unsigned char *data, uint
 
 void jsonrpc_machine::do_write_memory(uint64_t address, const unsigned char *data, uint64_t length) {
     bool result = false;
-    std::string b64 = cartesi::encode_base64(data, length);
+    std::string b64 = cartesi::encode_base64(std::span<const unsigned char>{data, length});
     request("machine.write_memory", std::tie(address, b64), result);
 }
 
@@ -713,7 +711,7 @@ void jsonrpc_machine::do_read_virtual_memory(uint64_t address, unsigned char *da
 
 void jsonrpc_machine::do_write_virtual_memory(uint64_t address, const unsigned char *data, uint64_t length) {
     bool result = false;
-    std::string b64 = cartesi::encode_base64(data, length);
+    std::string b64 = cartesi::encode_base64(std::span<const unsigned char>{data, length});
     request("machine.write_virtual_memory", std::tie(address, b64), result);
 }
 
@@ -737,12 +735,20 @@ access_log jsonrpc_machine::do_log_reset_uarch(const access_log::type &log_type)
     return std::move(result).value();
 }
 
-void jsonrpc_machine::do_get_root_hash(hash_type &hash) const {
+machine_hash jsonrpc_machine::do_get_root_hash() const {
+    machine_hash hash;
     request("machine.get_root_hash", std::tie(), hash);
+    return hash;
 }
 
-machine_merkle_tree::proof_type jsonrpc_machine::do_get_proof(uint64_t address, int log2_size) const {
-    not_default_constructible<machine_merkle_tree::proof_type> result;
+machine_hash jsonrpc_machine::do_get_node_hash(uint64_t address, int log2_size) const {
+    machine_hash hash;
+    request("machine.get_node_hash", std::tie(address, log2_size), hash);
+    return hash;
+}
+
+i_machine::proof_type jsonrpc_machine::do_get_proof(uint64_t address, int log2_size) const {
+    not_default_constructible<proof_type> result;
     request("machine.get_proof", std::tie(address, log2_size), result);
     if (!result.has_value()) {
         throw std::runtime_error("jsonrpc server error: missing result");
@@ -769,21 +775,15 @@ void jsonrpc_machine::do_destroy() {
     request("machine.destroy", std::tie(), result);
 }
 
-bool jsonrpc_machine::do_verify_dirty_page_maps() const {
-    bool result = false;
-    request("machine.verify_dirty_page_maps", std::tie(), result);
-    return result;
-}
-
 uint64_t jsonrpc_machine::do_read_word(uint64_t address) const {
     uint64_t result = 0;
     request("machine.read_word", std::tie(address), result);
     return result;
 }
 
-bool jsonrpc_machine::do_verify_merkle_tree() const {
+bool jsonrpc_machine::do_verify_hash_tree() const {
     bool result = false;
-    request("machine.verify_merkle_tree", std::tie(), result);
+    request("machine.verify_hash_tree", std::tie(), result);
     return result;
 }
 
@@ -801,14 +801,14 @@ address_range_descriptions jsonrpc_machine::do_get_address_ranges() const {
 
 void jsonrpc_machine::do_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length) {
     bool result = false;
-    std::string b64 = cartesi::encode_base64(data, length);
+    std::string b64 = cartesi::encode_base64(std::span<const unsigned char>{data, length});
     request("machine.send_cmio_response", std::tie(reason, b64), result);
 }
 
 access_log jsonrpc_machine::do_log_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
     const access_log::type &log_type) {
     not_default_constructible<access_log> result;
-    std::string b64 = cartesi::encode_base64(data, length);
+    std::string b64 = cartesi::encode_base64(std::span<const unsigned char>{data, length});
     request("machine.log_send_cmio_response", std::tie(reason, b64, log_type), result);
     if (!result.has_value()) {
         throw std::runtime_error("jsonrpc server error: missing result");
@@ -828,8 +828,8 @@ machine_config jsonrpc_machine::do_get_default_config() const {
     return result;
 }
 
-interpreter_break_reason jsonrpc_machine::do_verify_step(const hash_type &root_hash_before,
-    const std::string &log_filename, uint64_t mcycle_count, const hash_type &root_hash_after) const {
+interpreter_break_reason jsonrpc_machine::do_verify_step(const machine_hash &root_hash_before,
+    const std::string &log_filename, uint64_t mcycle_count, const machine_hash &root_hash_after) const {
     interpreter_break_reason result = interpreter_break_reason::failed;
     auto b64_root_hash_before = encode_base64(root_hash_before);
     auto b64_root_hash_after = encode_base64(root_hash_after);
@@ -838,16 +838,16 @@ interpreter_break_reason jsonrpc_machine::do_verify_step(const hash_type &root_h
     return result;
 }
 
-void jsonrpc_machine::do_verify_step_uarch(const hash_type &root_hash_before, const access_log &log,
-    const hash_type &root_hash_after) const {
+void jsonrpc_machine::do_verify_step_uarch(const machine_hash &root_hash_before, const access_log &log,
+    const machine_hash &root_hash_after) const {
     bool result = false;
     auto b64_root_hash_before = encode_base64(root_hash_before);
     auto b64_root_hash_after = encode_base64(root_hash_after);
     request("machine.verify_step_uarch", std::tie(b64_root_hash_before, log, b64_root_hash_after), result);
 }
 
-void jsonrpc_machine::do_verify_reset_uarch(const hash_type &root_hash_before, const access_log &log,
-    const hash_type &root_hash_after) const {
+void jsonrpc_machine::do_verify_reset_uarch(const machine_hash &root_hash_before, const access_log &log,
+    const machine_hash &root_hash_after) const {
     bool result = false;
     auto b64_root_hash_before = encode_base64(root_hash_before);
     auto b64_root_hash_after = encode_base64(root_hash_after);
@@ -855,9 +855,9 @@ void jsonrpc_machine::do_verify_reset_uarch(const hash_type &root_hash_before, c
 }
 
 void jsonrpc_machine::do_verify_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
-    const hash_type &root_hash_before, const access_log &log, const hash_type &root_hash_after) const {
+    const machine_hash &root_hash_before, const access_log &log, const machine_hash &root_hash_after) const {
     bool result = false;
-    std::string b64_data = cartesi::encode_base64(data, length);
+    std::string b64_data = cartesi::encode_base64(std::span<const unsigned char>{data, length});
     auto b64_root_hash_before = encode_base64(root_hash_before);
     auto b64_root_hash_after = encode_base64(root_hash_after);
     request("machine.verify_send_cmio_response",
diff --git a/src/jsonrpc-machine.h b/src/jsonrpc-machine.h
index 5bee677a8..b13b16caa 100644
--- a/src/jsonrpc-machine.h
+++ b/src/jsonrpc-machine.h
@@ -27,7 +27,6 @@
 #include "interpret.h"
 #include "jsonrpc-fork-result.h"
 #include "machine-config.h"
-#include "machine-merkle-tree.h"
 #include "machine-runtime-config.h"
 #include "semantic-version.h"
 #include "uarch-interpret.h"
@@ -120,16 +119,16 @@ class jsonrpc_machine final : public i_machine {
     uint64_t do_translate_virtual_address(uint64_t vaddr) override;
     void do_reset_uarch() override;
     access_log do_log_reset_uarch(const access_log::type &log_type) override;
-    void do_get_root_hash(hash_type &hash) const override;
-    machine_merkle_tree::proof_type do_get_proof(uint64_t address, int log2_size) const override;
+    machine_hash do_get_root_hash() const override;
+    machine_hash do_get_node_hash(uint64_t address, int log2_size) const override;
+    proof_type do_get_proof(uint64_t address, int log2_size) const override;
     void do_replace_memory_range(const memory_range_config &new_range) override;
     access_log do_log_step_uarch(const access_log::type &log_type) override;
     machine_runtime_config do_get_runtime_config() const override;
     void do_set_runtime_config(const machine_runtime_config &r) override;
     void do_destroy() override;
-    bool do_verify_dirty_page_maps() const override;
     uint64_t do_read_word(uint64_t address) const override;
-    bool do_verify_merkle_tree() const override;
+    bool do_verify_hash_tree() const override;
     uarch_interpreter_break_reason do_run_uarch(uint64_t uarch_cycle_end) override;
     address_range_descriptions do_get_address_ranges() const override;
     void do_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length) override;
@@ -137,14 +136,15 @@ class jsonrpc_machine final : public i_machine {
         const access_log::type &log_type) override;
     uint64_t do_get_reg_address(reg r) const override;
     machine_config do_get_default_config() const override;
-    interpreter_break_reason do_verify_step(const hash_type &root_hash_before, const std::string &log_filename,
-        uint64_t mcycle_count, const hash_type &root_hash_after) const override;
-    void do_verify_step_uarch(const hash_type &root_hash_before, const access_log &log,
-        const hash_type &root_hash_after) const override;
-    void do_verify_reset_uarch(const hash_type &root_hash_before, const access_log &log,
-        const hash_type &root_hash_after) const override;
+    interpreter_break_reason do_verify_step(const machine_hash &root_hash_before, const std::string &log_filename,
+        uint64_t mcycle_count, const machine_hash &root_hash_after) const override;
+    void do_verify_step_uarch(const machine_hash &root_hash_before, const access_log &log,
+        const machine_hash &root_hash_after) const override;
+    void do_verify_reset_uarch(const machine_hash &root_hash_before, const access_log &log,
+        const machine_hash &root_hash_after) const override;
     void do_verify_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
-        const hash_type &root_hash_before, const access_log &log, const hash_type &root_hash_after) const override;
+        const machine_hash &root_hash_before, const access_log &log,
+        const machine_hash &root_hash_after) const override;
     bool do_is_jsonrpc_machine() const override;
 
     void check_server_version(std::chrono::time_point<std::chrono::steady_clock> timeout_at) const;
diff --git a/src/jsonrpc-remote-machine.cpp b/src/jsonrpc-remote-machine.cpp
index de422fab0..4ac1cd69f 100644
--- a/src/jsonrpc-remote-machine.cpp
+++ b/src/jsonrpc-remote-machine.cpp
@@ -70,7 +70,7 @@
 #include "jsonrpc-fork-result.h"
 #include "jsonrpc-version.h"
 #include "machine-config.h"
-#include "machine-merkle-tree.h"
+#include "machine-hash.h"
 #include "machine-runtime-config.h"
 #include "machine.h"
 #include "os.h"
@@ -758,7 +758,7 @@ static tcp::endpoint address_to_endpoint(const std::string &address) {
             throw std::runtime_error{"invalid port"};
         }
         return {asio::ip::make_address(ip), static_cast<uint16_t>(port)};
-    } catch (std::exception &e) {
+    } catch (const std::exception &e) {
         throw std::runtime_error{"invalid endpoint address \"" + address + "\""};
     }
 }
@@ -1055,8 +1055,7 @@ static json jsonrpc_machine_log_reset_uarch_handler(const json &j, const std::sh
 static json jsonrpc_machine_verify_step_handler(const json &j, const std::shared_ptr<http_session> &session) {
     (void) session;
     static const char *param_name[] = {"root_hash_before", "filename", "mcycle_count", "root_hash_after"};
-    auto args = parse_args<cartesi::machine_merkle_tree::hash_type, std::string, uint64_t,
-        cartesi::machine_merkle_tree::hash_type>(j, param_name);
+    auto args = parse_args<cartesi::machine_hash, std::string, uint64_t, cartesi::machine_hash>(j, param_name);
     // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
     auto reason =
         cartesi::machine::verify_step(std::get<0>(args), std::get<1>(args), std::get<2>(args), std::get<3>(args));
@@ -1070,9 +1069,8 @@ static json jsonrpc_machine_verify_step_handler(const json &j, const std::shared
 static json jsonrpc_machine_verify_step_uarch_handler(const json &j,
     const std::shared_ptr<http_session> & /*session*/) {
     static const char *param_name[] = {"root_hash_before", "log", "root_hash_after"};
-    auto args =
-        parse_args<cartesi::machine_merkle_tree::hash_type, cartesi::not_default_constructible<cartesi::access_log>,
-            cartesi::machine_merkle_tree::hash_type>(j, param_name);
+    auto args = parse_args<cartesi::machine_hash, cartesi::not_default_constructible<cartesi::access_log>,
+        cartesi::machine_hash>(j, param_name);
     // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
     cartesi::machine::verify_step_uarch(std::get<0>(args), std::get<1>(args).value(), std::get<2>(args));
     return jsonrpc_response_ok(j);
@@ -1085,9 +1083,8 @@ static json jsonrpc_machine_verify_step_uarch_handler(const json &j,
 static json jsonrpc_machine_verify_reset_uarch_handler(const json &j,
     const std::shared_ptr<http_session> & /*session*/) {
     static const char *param_name[] = {"root_hash_before", "log", "root_hash_after"};
-    auto args =
-        parse_args<cartesi::machine_merkle_tree::hash_type, cartesi::not_default_constructible<cartesi::access_log>,
-            cartesi::machine_merkle_tree::hash_type>(j, param_name);
+    auto args = parse_args<cartesi::machine_hash, cartesi::not_default_constructible<cartesi::access_log>,
+        cartesi::machine_hash>(j, param_name);
     // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
     cartesi::machine::verify_reset_uarch(std::get<0>(args), std::get<1>(args).value(), std::get<2>(args));
     return jsonrpc_response_ok(j);
@@ -1110,16 +1107,16 @@ static json jsonrpc_machine_get_proof_handler(const json &j, const std::shared_p
         session->handler->machine->get_proof(std::get<0>(args), static_cast<int>(std::get<1>(args))));
 }
 
-/// \brief JSONRPC handler for the machine.verify_merkle_tree method
+/// \brief JSONRPC handler for the machine.verify_hash_tree method
 /// \param j JSON request object
 /// \param session HTTP session
 /// \returns JSON response object
-static json jsonrpc_machine_verify_merkle_tree_handler(const json &j, const std::shared_ptr<http_session> &session) {
+static json jsonrpc_machine_verify_hash_tree_handler(const json &j, const std::shared_ptr<http_session> &session) {
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
     jsonrpc_check_no_params(j);
-    return jsonrpc_response_ok(j, session->handler->machine->verify_merkle_tree());
+    return jsonrpc_response_ok(j, session->handler->machine->verify_hash_tree());
 }
 
 /// \brief JSONRPC handler for the machine.get_root_hash method
@@ -1131,8 +1128,24 @@ static json jsonrpc_machine_get_root_hash_handler(const json &j, const std::shar
         return jsonrpc_response_invalid_request(j, "no machine");
     }
     jsonrpc_check_no_params(j);
-    cartesi::machine_merkle_tree::hash_type hash;
-    session->handler->machine->get_root_hash(hash);
+    auto hash = session->handler->machine->get_root_hash();
+    return jsonrpc_response_ok(j, cartesi::encode_base64(hash));
+}
+
+/// \brief JSONRPC handler for the machine.get_node_hash method
+/// \param j JSON request object
+/// \param session HTTP session
+/// \returns JSON response object
+static json jsonrpc_machine_get_node_hash_handler(const json &j, const std::shared_ptr<http_session> &session) {
+    if (!session->handler->machine) {
+        return jsonrpc_response_invalid_request(j, "no machine");
+    }
+    static const char *param_name[] = {"address", "log2_size"};
+    auto args = parse_args<uint64_t, uint64_t>(j, param_name);
+    if (std::get<1>(args) > INT_MAX) {
+        throw std::domain_error("log2_size is out of range");
+    }
+    auto hash = session->handler->machine->get_node_hash(std::get<0>(args), static_cast<int>(std::get<1>(args)));
     return jsonrpc_response_ok(j, cartesi::encode_base64(hash));
 }
 
@@ -1164,7 +1177,7 @@ static json jsonrpc_machine_read_memory_handler(const json &j, const std::shared
     auto length = std::get<1>(args);
     auto data = cartesi::make_unique_calloc<unsigned char>(length);
     session->handler->machine->read_memory(address, data.get(), length);
-    return jsonrpc_response_ok(j, cartesi::encode_base64(data.get(), length));
+    return jsonrpc_response_ok(j, cartesi::encode_base64(std::span<unsigned char>{data.get(), length}));
 }
 
 /// \brief JSONRPC handler for the machine.write_memory method
@@ -1198,7 +1211,7 @@ static json jsonrpc_machine_read_virtual_memory_handler(const json &j, const std
     auto length = std::get<1>(args);
     auto data = cartesi::make_unique_calloc<unsigned char>(length);
     session->handler->machine->read_virtual_memory(address, data.get(), length);
-    return jsonrpc_response_ok(j, cartesi::encode_base64(data.get(), length));
+    return jsonrpc_response_ok(j, cartesi::encode_base64(std::span<unsigned char>{data.get(), length}));
 }
 
 /// \brief JSONRPC handler for the machine.write_virtual_memory method
@@ -1345,19 +1358,6 @@ static json jsonrpc_machine_get_default_config_handler(const json &j,
     return jsonrpc_response_ok(j, cartesi::machine::get_default_config());
 }
 
-/// \brief JSONRPC handler for the machine.verify_dirty_page_maps method
-/// \param j JSON request object
-/// \param session HTTP session
-/// \returns JSON response object
-static json jsonrpc_machine_verify_dirty_page_maps_handler(const json &j,
-    const std::shared_ptr<http_session> &session) {
-    if (!session->handler->machine) {
-        return jsonrpc_response_invalid_request(j, "no machine");
-    }
-    jsonrpc_check_no_params(j);
-    return jsonrpc_response_ok(j, session->handler->machine->verify_dirty_page_maps());
-}
-
 /// \brief JSONRPC handler for the machine.get_address_ranges method
 /// \param j JSON request object
 /// \param session HTTP session
@@ -1412,9 +1412,8 @@ static json jsonrpc_machine_log_send_cmio_response_handler(const json &j,
 static json jsonrpc_machine_verify_send_cmio_response_handler(const json &j,
     const std::shared_ptr<http_session> & /*session*/) {
     static const char *param_name[] = {"reason", "data", "root_hash_before", "log", "root_hash_after"};
-    auto args = parse_args<uint16_t, std::string, cartesi::machine_merkle_tree::hash_type,
-        cartesi::not_default_constructible<cartesi::access_log>, cartesi::machine_merkle_tree::hash_type>(j,
-        param_name);
+    auto args = parse_args<uint16_t, std::string, cartesi::machine_hash,
+        cartesi::not_default_constructible<cartesi::access_log>, cartesi::machine_hash>(j, param_name);
 
     auto bin = cartesi::decode_base64(std::get<1>(args));
     // NOLINTBEGIN(bugprone-unchecked-optional-access)
@@ -1491,6 +1490,7 @@ static json jsonrpc_dispatch_method(const json &j, const std::shared_ptr<http_se
         {"machine.verify_step_uarch", jsonrpc_machine_verify_step_uarch_handler},
         {"machine.get_proof", jsonrpc_machine_get_proof_handler},
         {"machine.get_root_hash", jsonrpc_machine_get_root_hash_handler},
+        {"machine.get_node_hash", jsonrpc_machine_get_node_hash_handler},
         {"machine.read_word", jsonrpc_machine_read_word_handler},
         {"machine.read_memory", jsonrpc_machine_read_memory_handler},
         {"machine.write_memory", jsonrpc_machine_write_memory_handler},
@@ -1505,8 +1505,7 @@ static json jsonrpc_dispatch_method(const json &j, const std::shared_ptr<http_se
         {"machine.get_default_config", jsonrpc_machine_get_default_config_handler},
         {"machine.get_runtime_config", jsonrpc_machine_get_runtime_config_handler},
         {"machine.set_runtime_config", jsonrpc_machine_set_runtime_config_handler},
-        {"machine.verify_merkle_tree", jsonrpc_machine_verify_merkle_tree_handler},
-        {"machine.verify_dirty_page_maps", jsonrpc_machine_verify_dirty_page_maps_handler},
+        {"machine.verify_hash_tree", jsonrpc_machine_verify_hash_tree_handler},
         {"machine.get_address_ranges", jsonrpc_machine_get_address_ranges_handler},
         {"machine.send_cmio_response", jsonrpc_machine_send_cmio_response_handler},
         {"machine.log_send_cmio_response", jsonrpc_machine_log_send_cmio_response_handler},
@@ -1520,9 +1519,9 @@ static json jsonrpc_dispatch_method(const json &j, const std::shared_ptr<http_se
         return found->second(j, session);
     }
     return jsonrpc_response_method_not_found(j, method);
-} catch (std::invalid_argument &x) {
+} catch (const std::invalid_argument &x) {
     return jsonrpc_response_invalid_params(j, x.what());
-} catch (std::exception &x) {
+} catch (const std::exception &x) {
     return jsonrpc_response_internal_error(j, x.what());
 }
 
@@ -1574,7 +1573,7 @@ http::message_generator handle_request(HTTP_REQ &&rreq, const std::shared_ptr<ht
     json j;
     try {
         j = json::parse(req.body().data());
-    } catch (std::exception &x) {
+    } catch (const std::exception &x) {
         return jsonrpc_http_reply(req, jsonrpc_response_parse_error(x.what()), session);
     }
     // JSONRPC allows batch requests, each an entry in an array
@@ -1813,7 +1812,7 @@ int main(int argc, char *argv[]) try {
 
     SLOG(trace) << "remote machine server exiting";
     return 0;
-} catch (std::exception &e) {
+} catch (const std::exception &e) {
     SLOG(fatal) << "caught exception: " << e.what();
     return 1;
 } catch (...) {
diff --git a/src/keccak-256-hasher.h b/src/keccak-256-hasher.h
index bac5d8963..89fdf3e7e 100644
--- a/src/keccak-256-hasher.h
+++ b/src/keccak-256-hasher.h
@@ -22,6 +22,7 @@
 #include <type_traits>
 
 #include "i-hasher.h"
+#include "machine-hash.h"
 
 extern "C" {
 #include "sha3.h"
@@ -37,22 +38,24 @@ struct keccak_instance final {
     int pt;
 };
 
-class keccak_256_hasher final : public i_hasher<keccak_256_hasher, std::integral_constant<int, 32>> {
+class keccak_256_hasher final : public i_hasher<keccak_256_hasher> {
     sha3_ctx_t m_ctx{};
-    using base = i_hasher<keccak_256_hasher, std::integral_constant<int, 32>>;
 
-    friend base;
+    friend i_hasher<keccak_256_hasher>;
 
-    void do_begin() {
-        sha3_init(&m_ctx, 32, 0x01);
+    void do_begin() noexcept {
+        sha3_init(&m_ctx, machine_hash_size, 0x01);
     }
 
-    void do_add_data(const unsigned char *data, size_t length) {
-        sha3_update(&m_ctx, data, length);
+    template <ContiguousRangeOfByteLike R>
+    void do_add_data(R &&r) noexcept { // NOLINT(cppcoreguidelines-missing-std-forward)
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        sha3_update(&m_ctx, reinterpret_cast<const unsigned char *>(std::ranges::data(r)), std::ranges::size(r));
     }
 
-    void do_end(hash_type &hash) {
-        sha3_final(hash.data(), &m_ctx);
+    void do_end(machine_hash_view hash) noexcept {
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        sha3_final(reinterpret_cast<unsigned char *>(hash.data()), &m_ctx);
     }
 
 public:
diff --git a/src/local-machine.cpp b/src/local-machine.cpp
index c010460bc..51b21de16 100644
--- a/src/local-machine.cpp
+++ b/src/local-machine.cpp
@@ -24,7 +24,6 @@
 #include "i-machine.h"
 #include "interpret.h"
 #include "machine-config.h"
-#include "machine-merkle-tree.h"
 #include "machine-runtime-config.h"
 #include "machine.h"
 #include "uarch-interpret.h"
@@ -82,16 +81,20 @@ access_log local_machine::do_log_step_uarch(const access_log::type &log_type) {
     return get_machine()->log_step_uarch(log_type);
 }
 
-machine_merkle_tree::proof_type local_machine::do_get_proof(uint64_t address, int log2_size) const {
+i_machine::proof_type local_machine::do_get_proof(uint64_t address, int log2_size) const {
     return get_machine()->get_proof(address, log2_size);
 }
 
-void local_machine::do_get_root_hash(hash_type &hash) const {
-    get_machine()->get_root_hash(hash);
+machine_hash local_machine::do_get_root_hash() const {
+    return get_machine()->get_root_hash();
 }
 
-bool local_machine::do_verify_merkle_tree() const {
-    return get_machine()->verify_merkle_tree();
+machine_hash local_machine::do_get_node_hash(uint64_t address, int log2_size) const {
+    return get_machine()->get_node_hash(address, log2_size);
+}
+
+bool local_machine::do_verify_hash_tree() const {
+    return get_machine()->verify_hash_tree();
 }
 
 uint64_t local_machine::do_read_reg(reg r) const {
@@ -130,10 +133,6 @@ uint64_t local_machine::do_read_word(uint64_t address) const {
     return get_machine()->read_word(address);
 }
 
-bool local_machine::do_verify_dirty_page_maps() const {
-    return get_machine()->verify_dirty_page_maps();
-}
-
 machine_config local_machine::do_get_initial_config() const {
     return get_machine()->get_initial_config();
 }
@@ -184,23 +183,23 @@ machine_config local_machine::do_get_default_config() const {
     return machine::get_default_config();
 }
 
-interpreter_break_reason local_machine::do_verify_step(const hash_type &root_hash_before,
-    const std::string &log_filename, uint64_t mcycle_count, const hash_type &root_hash_after) const {
+interpreter_break_reason local_machine::do_verify_step(const machine_hash &root_hash_before,
+    const std::string &log_filename, uint64_t mcycle_count, const machine_hash &root_hash_after) const {
     return machine::verify_step(root_hash_before, log_filename, mcycle_count, root_hash_after);
 }
 
-void local_machine::do_verify_step_uarch(const hash_type &root_hash_before, const access_log &log,
-    const hash_type &root_hash_after) const {
+void local_machine::do_verify_step_uarch(const machine_hash &root_hash_before, const access_log &log,
+    const machine_hash &root_hash_after) const {
     machine::verify_step_uarch(root_hash_before, log, root_hash_after);
 }
 
-void local_machine::do_verify_reset_uarch(const hash_type &root_hash_before, const access_log &log,
-    const hash_type &root_hash_after) const {
+void local_machine::do_verify_reset_uarch(const machine_hash &root_hash_before, const access_log &log,
+    const machine_hash &root_hash_after) const {
     machine::verify_reset_uarch(root_hash_before, log, root_hash_after);
 }
 
 void local_machine::do_verify_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
-    const hash_type &root_hash_before, const access_log &log, const hash_type &root_hash_after) const {
+    const machine_hash &root_hash_before, const access_log &log, const machine_hash &root_hash_after) const {
     machine::verify_send_cmio_response(reason, data, length, root_hash_before, log, root_hash_after);
 }
 
diff --git a/src/local-machine.h b/src/local-machine.h
index 0f98e064a..350146492 100644
--- a/src/local-machine.h
+++ b/src/local-machine.h
@@ -25,7 +25,7 @@
 #include "i-machine.h"
 #include "interpret.h"
 #include "machine-config.h"
-#include "machine-merkle-tree.h"
+#include "machine-hash.h"
 #include "machine-runtime-config.h"
 #include "machine.h"
 #include "uarch-interpret.h"
@@ -52,9 +52,10 @@ class local_machine : public i_machine {
     interpreter_break_reason do_log_step(uint64_t mcycle_count, const std::string &filename) override;
     void do_store(const std::string &directory) const override;
     access_log do_log_step_uarch(const access_log::type &log_type) override;
-    machine_merkle_tree::proof_type do_get_proof(uint64_t address, int log2_size) const override;
-    void do_get_root_hash(hash_type &hash) const override;
-    bool do_verify_merkle_tree() const override;
+    proof_type do_get_proof(uint64_t address, int log2_size) const override;
+    machine_hash do_get_root_hash() const override;
+    machine_hash do_get_node_hash(uint64_t address, int log2_size) const override;
+    bool do_verify_hash_tree() const override;
     uint64_t do_read_reg(reg r) const override;
     void do_write_reg(reg w, uint64_t val) override;
     void do_read_memory(uint64_t address, unsigned char *data, uint64_t length) const override;
@@ -64,7 +65,6 @@ class local_machine : public i_machine {
     uint64_t do_translate_virtual_address(uint64_t vaddr) override;
     void do_replace_memory_range(const memory_range_config &new_range) override;
     uint64_t do_read_word(uint64_t address) const override;
-    bool do_verify_dirty_page_maps() const override;
     machine_config do_get_initial_config() const override;
     machine_runtime_config do_get_runtime_config() const override;
     void do_set_runtime_config(const machine_runtime_config &r) override;
@@ -78,14 +78,15 @@ class local_machine : public i_machine {
         const access_log::type &log_type) override;
     uint64_t do_get_reg_address(reg r) const override;
     machine_config do_get_default_config() const override;
-    interpreter_break_reason do_verify_step(const hash_type &root_hash_before, const std::string &log_filename,
-        uint64_t mcycle_count, const hash_type &root_hash_after) const override;
-    void do_verify_step_uarch(const hash_type &root_hash_before, const access_log &log,
-        const hash_type &root_hash_after) const override;
-    void do_verify_reset_uarch(const hash_type &root_hash_before, const access_log &log,
-        const hash_type &root_hash_after) const override;
+    interpreter_break_reason do_verify_step(const machine_hash &root_hash_before, const std::string &log_filename,
+        uint64_t mcycle_count, const machine_hash &root_hash_after) const override;
+    void do_verify_step_uarch(const machine_hash &root_hash_before, const access_log &log,
+        const machine_hash &root_hash_after) const override;
+    void do_verify_reset_uarch(const machine_hash &root_hash_before, const access_log &log,
+        const machine_hash &root_hash_after) const override;
     void do_verify_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
-        const hash_type &root_hash_before, const access_log &log, const hash_type &root_hash_after) const override;
+        const machine_hash &root_hash_before, const access_log &log,
+        const machine_hash &root_hash_after) const override;
 
     machine *get_machine();
     const machine *get_machine() const;
diff --git a/src/machine-address-ranges.cpp b/src/machine-address-ranges.cpp
index 7afee20d8..c09be93d2 100644
--- a/src/machine-address-ranges.cpp
+++ b/src/machine-address-ranges.cpp
@@ -69,7 +69,7 @@ static inline auto make_pmas_address_range(const pmas_config &config) {
         .IW = false,
         .DID = PMA_ISTART_DID::memory,
     };
-    return memory_address_range{"PMAs", AR_PMAS_START, AR_PMAS_LENGTH, pmas_flags, config.backing_store};
+    return make_memory_address_range("PMAs", AR_PMAS_START, AR_PMAS_LENGTH, pmas_flags, config.backing_store);
 }
 
 static inline auto make_dtb_address_range(const dtb_config &config) {
@@ -85,7 +85,7 @@ static inline auto make_dtb_address_range(const dtb_config &config) {
         .IW = true,
         .DID = PMA_ISTART_DID::memory,
     };
-    return memory_address_range{"DTB"s, AR_DTB_START, AR_DTB_LENGTH, dtb_flags, config.backing_store};
+    return make_memory_address_range("DTB"s, AR_DTB_START, AR_DTB_LENGTH, dtb_flags, config.backing_store);
 }
 
 static inline auto make_shadow_state_address_range(const processor_config &config) {
@@ -99,12 +99,9 @@ static inline auto make_shadow_state_address_range(const processor_config &confi
         .IW = false,
         .DID = PMA_ISTART_DID::shadow_state,
     };
-    auto ar = memory_address_range{"shadow state", AR_SHADOW_STATE_START, AR_SHADOW_STATE_LENGTH, shadow_state_flags,
-        config.backing_store, memory_address_range_flags{.page_uncleanable = true}, sizeof(processor_state)};
-    // Mark pages that are permanently dirty in the shadow
-    ar.mark_dirty_pages(AR_SHADOW_REGISTERS_START - AR_SHADOW_STATE_START, AR_SHADOW_REGISTERS_LENGTH);
-    ar.mark_dirty_pages(AR_SHADOW_TLB_START - AR_SHADOW_STATE_START, AR_SHADOW_TLB_LENGTH);
-    return ar;
+    static constexpr memory_address_range_config shadow_state_config{.host_length = sizeof(processor_state)};
+    return memory_address_range("shadow state", AR_SHADOW_STATE_START, AR_SHADOW_STATE_LENGTH, shadow_state_flags,
+        config.backing_store, shadow_state_config);
 }
 
 static inline auto make_shadow_uarch_state_address_range(const uarch_processor_config &config) {
@@ -118,12 +115,17 @@ static inline auto make_shadow_uarch_state_address_range(const uarch_processor_c
         .IW = false,
         .DID = PMA_ISTART_DID::shadow_uarch_state,
     };
-    auto ar = memory_address_range{"shadow uarch state", AR_SHADOW_UARCH_STATE_START, AR_SHADOW_UARCH_STATE_LENGTH,
-        shadow_uarch_state_flags, config.backing_store, memory_address_range_flags{.page_uncleanable = true},
-        sizeof(uarch_processor_state)};
-    // Mark pages that are permanently dirty in the shadow
-    ar.mark_dirty_pages(0, AR_SHADOW_UARCH_STATE_LENGTH);
-    return ar;
+    static constexpr memory_address_range_config shadow_uarch_state_config{
+        .host_length = sizeof(uarch_processor_state)};
+    return make_memory_address_range("shadow uarch state", AR_SHADOW_UARCH_STATE_START, AR_SHADOW_UARCH_STATE_LENGTH,
+        shadow_uarch_state_flags, config.backing_store, shadow_uarch_state_config);
+}
+
+void machine_address_ranges::mark_always_dirty_pages() {
+    m_all[m_shadow_uarch_state_index]->get_dirty_page_tree().mark_dirty_pages_and_up(0, AR_SHADOW_UARCH_STATE_LENGTH);
+    auto &shadow_dpt = m_all[m_shadow_state_index]->get_dirty_page_tree();
+    shadow_dpt.mark_dirty_pages_and_up(AR_SHADOW_REGISTERS_START - AR_SHADOW_STATE_START, AR_SHADOW_REGISTERS_LENGTH);
+    shadow_dpt.mark_dirty_pages_and_up(AR_SHADOW_TLB_START - AR_SHADOW_STATE_START, AR_SHADOW_TLB_LENGTH);
 }
 
 template <typename AR>
@@ -134,11 +136,11 @@ AR &machine_address_ranges::push_back(AR &&ar, register_where where) {
     AR &ar_ref = *ptr;                                  // Get reference to object, already in heap, to return later
     const auto index = m_all.size();                    // Get index the new address range will occupy
     m_all.push_back(std::move(ptr));                    // Move ptr to list of address ranges
-    if (where.interpret) {                              // Register with interpreter
-        m_interpret.push_back(index);
+    if (where.pmas) {                                   // Register as a PMA
+        m_pmas.push_back(index);
     }
-    if (where.merkle) { // Register with Merkle tree
-        m_merkle.push_back(index);
+    if (where.hash_tree) { // Register with the hash tree
+        m_hash_tree.push_back(index);
     }
     if constexpr (std::is_convertible_v<AR *, virtio_address_range *>) { // Register with VirtIO
         m_virtio.push_back(&ar_ref);
@@ -148,23 +150,25 @@ AR &machine_address_ranges::push_back(AR &&ar, register_where where) {
 
 machine_address_ranges::machine_address_ranges(machine_config &c) {
     // Add all address ranges to m_all, and potentially to interpret and merkle
-    push_back(make_shadow_state_address_range(c.processor), register_where{.merkle = true, .interpret = false});
+    m_shadow_state_index = static_cast<int>(m_all.size()); // NOLINT(cppcoreguidelines-prefer-member-initializer)
+    push_back(make_shadow_state_address_range(c.processor), register_where{.hash_tree = true, .pmas = false});
+    m_shadow_uarch_state_index = static_cast<int>(m_all.size()); // NOLINT(cppcoreguidelines-prefer-member-initializer)
     push_back(make_shadow_uarch_state_address_range(c.uarch.processor),
-        register_where{.merkle = true, .interpret = false});
+        register_where{.hash_tree = true, .pmas = false});
     push_back_uarch_ram(c.uarch.ram);
     push_back_ram(c.ram);
-    push_back(make_dtb_address_range(c.dtb), register_where{.merkle = true, .interpret = true});
+    push_back(make_dtb_address_range(c.dtb), register_where{.hash_tree = true, .pmas = true});
     push_back_flash_drives(c.flash_drive);
     push_back_cmio(c.cmio);
-    push_back(make_htif_address_range(throw_invalid_argument), register_where{.merkle = false, .interpret = true});
-    push_back(make_clint_address_range(throw_invalid_argument), register_where{.merkle = false, .interpret = true});
-    push_back(make_plic_address_range(throw_invalid_argument), register_where{.merkle = false, .interpret = true});
-    push_back(make_pmas_address_range(c.pmas), register_where{.merkle = true, .interpret = true});
+    push_back(make_htif_address_range(throw_invalid_argument), register_where{.hash_tree = false, .pmas = true});
+    push_back(make_clint_address_range(throw_invalid_argument), register_where{.hash_tree = false, .pmas = true});
+    push_back(make_plic_address_range(throw_invalid_argument), register_where{.hash_tree = false, .pmas = true});
+    push_back(make_pmas_address_range(c.pmas), register_where{.hash_tree = true, .pmas = true});
     push_back_virtio(c.virtio, c.processor.registers.iunrep);
 
-    // Sort indices visible to Merkle tree by the start of corresponding address range
+    // Sort indices visible to hash tree by the start of corresponding address range
     std::ranges::sort(
-        m_merkle, [](const auto &a, const auto &b) { return a.get_start() < b.get_start(); },
+        m_hash_tree, [](const auto &a, const auto &b) { return a.get_start() < b.get_start(); },
         [this](const auto i) { return *m_all[i]; });
 
     // Create descriptions and sort by start address
@@ -191,10 +195,9 @@ void machine_address_ranges::push_back_uarch_ram(const uarch_ram_config &uram) {
         .DID = PMA_ISTART_DID::memory,
     };
     constexpr auto ram_description = "uarch RAM";
-    auto &ar = push_back(
-        memory_address_range{ram_description, AR_UARCH_RAM_START, AR_UARCH_RAM_LENGTH, uram_flags, uram.backing_store},
-        register_where{.merkle = true, .interpret = false});
-
+    auto &ar = push_back(make_memory_address_range(ram_description, AR_UARCH_RAM_START, AR_UARCH_RAM_LENGTH, uram_flags,
+                             uram.backing_store),
+        register_where{.hash_tree = true, .pmas = false});
     // Initialize uarch RAM
     if (uram.backing_store.data_filename.empty() || uram.backing_store.create) {
         if (uarch_pristine_ram_len > AR_UARCH_RAM_LENGTH) {
@@ -205,7 +208,7 @@ void machine_address_ranges::push_back_uarch_ram(const uarch_ram_config &uram) {
 }
 
 void machine_address_ranges::check(const address_range &new_ar, register_where where) {
-    if (!where.interpret && !where.merkle) {
+    if (!where.pmas && !where.hash_tree) {
         throw std::runtime_error{"address range "s + new_ar.get_description() + " must be registered somewhere"s};
     }
     const auto start = new_ar.get_start();
@@ -239,8 +242,8 @@ void machine_address_ranges::push_back_ram(const ram_config &ram) {
     if (ram.length == 0) {
         throw std::invalid_argument("RAM length cannot be zero");
     }
-    push_back(memory_address_range{"RAM"s, AR_RAM_START, ram.length, ram_flags, ram.backing_store},
-        register_where{.merkle = true, .interpret = true});
+    push_back(make_memory_address_range("RAM"s, AR_RAM_START, ram.length, ram_flags, ram.backing_store),
+        register_where{.hash_tree = true, .pmas = true});
 }
 
 void machine_address_ranges::push_back_flash_drives(flash_drive_configs &flash_drive) {
@@ -290,8 +293,8 @@ void machine_address_ranges::push_back_flash_drives(flash_drive_configs &flash_d
             .DID = PMA_ISTART_DID::flash_drive,
         };
         push_back(memory_address_range{flash_description, f.start, f.length, flash_flags, f.backing_store,
-                      memory_address_range_flags{.read_only = f.read_only}},
-            register_where{.merkle = true, .interpret = true});
+                      memory_address_range_config{.host_read_only = f.read_only}},
+            register_where{.hash_tree = true, .pmas = true});
         i++;
     }
 }
@@ -309,7 +312,7 @@ void machine_address_ranges::push_back_virtio(const virtio_configs &virtio, uint
     }
     uint32_t virtio_idx = 0;
     for (const auto &c : virtio) {
-        const auto where = register_where{.merkle = false, .interpret = true};
+        const auto where = register_where{.hash_tree = false, .pmas = true};
         const auto visitor = overloads{
             [this, virtio_idx, where](const virtio_console_config &) {
                 const auto start = AR_FIRST_VIRTIO_START + (virtio_idx * AR_VIRTIO_LENGTH);
@@ -382,12 +385,12 @@ void machine_address_ranges::push_back_cmio(const cmio_config &c) {
         .IW = true,
         .DID = PMA_ISTART_DID::cmio_rx_buffer,
     };
-    push_back(memory_address_range{"CMIO tx buffer memory range"s, AR_CMIO_TX_BUFFER_START, AR_CMIO_TX_BUFFER_LENGTH,
-                  tx_flags, c.tx_buffer.backing_store},
-        register_where{.merkle = true, .interpret = true});
-    push_back(memory_address_range{"CMIO rx buffer memory range"s, AR_CMIO_RX_BUFFER_START, AR_CMIO_RX_BUFFER_LENGTH,
-                  rx_flags, c.rx_buffer.backing_store},
-        register_where{.merkle = true, .interpret = true});
+    push_back(make_memory_address_range("CMIO tx buffer"s, AR_CMIO_TX_BUFFER_START, AR_CMIO_TX_BUFFER_LENGTH, tx_flags,
+                  c.tx_buffer.backing_store),
+        register_where{.hash_tree = true, .pmas = true});
+    push_back(make_memory_address_range("CMIO rx buffer"s, AR_CMIO_RX_BUFFER_START, AR_CMIO_RX_BUFFER_LENGTH, rx_flags,
+                  c.rx_buffer.backing_store),
+        register_where{.hash_tree = true, .pmas = true});
 }
 
 void machine_address_ranges::replace(const memory_range_config &config) {
@@ -395,24 +398,29 @@ void machine_address_ranges::replace(const memory_range_config &config) {
         if (ar->get_start() == config.start && ar->get_length() == config.length) {
             if (!ar->is_memory() || pmas_is_protected(ar->get_driver_id())) {
                 throw std::invalid_argument{
-                    std::string{"attempt to replace a protected range "}.append(ar->get_description())};
+                    std::string{"attempted replace of protected memory range "}.append(ar->get_description())};
             }
-            if (ar->is_host_read_only()) {
+            if (ar->is_host_read_only() || !ar->is_writeable()) {
                 throw std::invalid_argument{
-                    std::string{"attempt to replace a read-only range "}.append(ar->get_description())};
+                    std::string{"attempted replace of read-only memory range "}.append(ar->get_description())};
+            }
+            if (config.read_only) {
+                throw std::invalid_argument{std::string{"attempted replace of read-write memory range "}
+                        .append(ar->get_description())
+                        .append(" with read-only memory range")};
             }
             // Replace range, preserving original flags.
             // This will automatically start with all pages dirty.
-            ar = make_moved_unique(memory_address_range{ar->get_description(), ar->get_start(), ar->get_length(),
-                ar->get_flags(), config.backing_store, memory_address_range_flags{.read_only = config.read_only}});
+            ar = make_moved_unique(make_memory_address_range(ar->get_description(), ar->get_start(), ar->get_length(),
+                ar->get_flags(), config.backing_store));
             return;
         }
     }
-    throw std::invalid_argument{"attempt to replace inexistent memory range"};
+    throw std::invalid_argument{"attempted replace of inexistent memory range"};
 }
 
 const address_range &machine_address_ranges::find(uint64_t paddr, uint64_t length) const noexcept {
-    static constexpr auto sentinel = make_empty_address_range("sentinel");
+    static auto sentinel = make_empty_address_range("sentinel");
     for (const auto &ar : m_all) {
         if (ar->contains_absolute(paddr, length)) {
             return *ar;
diff --git a/src/machine-address-ranges.h b/src/machine-address-ranges.h
index 3b63e6de0..9dbd10a03 100644
--- a/src/machine-address-ranges.h
+++ b/src/machine-address-ranges.h
@@ -38,11 +38,14 @@ namespace cartesi {
 /// \brief Machine address ranges.
 /// \details Class holding all address ranges in the machine
 class machine_address_ranges {
+
     std::vector<std::unique_ptr<address_range>> m_all; ///< Owner of all address ranges
-    std::vector<uint64_t> m_merkle;                    ///< Indices of address ranges registered with Merkle tree
-    std::vector<uint64_t> m_interpret;                 ///< Indices of address ranges registered with interpret (PMAs)
+    std::vector<uint64_t> m_hash_tree;                 ///< Indices of address ranges registered with hash tree
+    std::vector<uint64_t> m_pmas;                      ///< Indices of address ranges registered as PMAs
     std::vector<virtio_address_range *> m_virtio;      ///< Pointers to all VirtIO address ranges
     address_range_descriptions m_descrs;               ///< Address range descriptions for users
+    int m_shadow_state_index;                          ///< Index of shadow state address range
+    int m_shadow_uarch_state_index;                    ///< Index of shadow uarch state address range
 
 public:
     /// \brief Constructor
@@ -54,34 +57,44 @@ class machine_address_ranges {
         return std::views::transform(m_all, [](const auto &p) -> const address_range & { return *p; });
     }
 
-    /// \brief Const view of address ranges registered with Merkle tree
-    auto merkle() const {
-        return std::views::transform(m_merkle, [this](auto i) -> const address_range & { return *m_all[i]; });
+    /// \brief Const view of address ranges registered with hash tree
+    auto hash_tree_view() const {
+        return std::views::transform(m_hash_tree, [this](auto i) -> const address_range & { return *m_all[i]; });
+    }
+
+    /// \brief View of address ranges registered with hash tree
+    auto hash_tree_view() {
+        return std::views::transform(m_hash_tree, [this](auto i) -> address_range & { return *m_all[i]; });
     }
 
-    /// \brief View of address ranges registered with Merkle tree
-    auto merkle() {
-        return std::views::transform(m_merkle, [this](auto i) -> address_range & { return *m_all[i]; });
+    /// \brief Const view of address ranges registered as PMAs
+    auto pmas_view() const {
+        return std::views::transform(m_pmas, [this](auto i) -> const address_range & { return *m_all[i]; });
     }
 
-    /// \brief View of address ranges registered with interpret (PMAs)
-    auto interpret() const {
-        return std::views::transform(m_interpret, [this](auto i) -> address_range & { return *m_all[i]; });
+    /// \brief Const view of address ranges registered as PMAs
+    auto pmas_view() {
+        return std::views::transform(m_pmas, [this](auto i) -> address_range & { return *m_all[i]; });
     }
 
     /// \brief View of all VirtIO address ranges
-    auto virtio() {
+    auto virtio_view() {
         return std::views::transform(m_virtio, [](auto *p) -> virtio_address_range & { return *p; });
     }
 
-    /// \brief Returns the ith address range registered with interpret
+    /// \brief View of all VirtIO address ranges
+    auto virtio_view() const {
+        return std::views::transform(m_virtio, [](auto *p) -> const virtio_address_range & { return *p; });
+    }
+
+    /// \brief Returns the address range corresponding to the ith PMA
     const address_range &read_pma(uint64_t index) const noexcept {
-        if (index >= m_interpret.size()) {
-            static constexpr auto sentinel = make_empty_address_range("sentinel");
+        if (index >= m_pmas.size()) {
+            static auto sentinel = make_empty_address_range("sentinel");
             return sentinel;
         }
         // NOLINTNEXTLINE(bugprone-narrowing-conversions)
-        return *m_all[static_cast<int>(m_interpret[static_cast<int>(index)])];
+        return *m_all[static_cast<int>(m_pmas[static_cast<int>(index)])];
     }
 
     /// \brief Returns const address range that covers a given physical memory region
@@ -123,15 +136,18 @@ class machine_address_ranges {
     void replace(const memory_range_config &config);
 
     /// \brief Returns descriptions of all address ranges.
-    const address_range_descriptions &descriptions() const {
+    const address_range_descriptions &descriptions_view() const {
         return m_descrs;
     }
 
+    /// \brief Marks as dirty the pages of address ranges assumed dirty
+    void mark_always_dirty_pages();
+
 private:
     ///< Where to register an address range
     struct register_where {
-        bool merkle;    //< Register with Merkle tree, so it appears in the root hash
-        bool interpret; //< Register so interpret can see (and it also appears as a PMA entries in memory)
+        bool hash_tree; //< Register with hash tree, so it appears in the root hash
+        bool pmas;      //< Register as a PMA, so the interpreter can see it
     };
 
     /// \brief Checks if address range can be registered.
@@ -154,11 +170,12 @@ class machine_address_ranges {
     /// This means the index into the container that owns all address ranges will always refer to same address range
     /// after subsequent calls to register() and  calls to replace() as well.
     /// \details Besides the container that stores the address ranges, the machine maintains three subsets.
-    /// The "merkle" subset lists the indices of the address ranges that will be considered by the Merkle
-    /// tree during the computation of the state hash.
-    /// The "interpret" subset lists the indices of the address ranges visible from within the interpreter (PMAs).
-    /// When registering an address range with the machine, one must specify \p where to register it.
-    /// The "virtio" subset lists every VirtIO address range that has been registered.
+    /// The "hash_tree" subset lists the indices of the address ranges that will be considered by the hash tree
+    /// during the computation of the state hash.
+    /// The "pmas" subset lists the indices of the address ranges registered as PMAs, and therefore visible
+    /// from within the interpreter.
+    /// The \p where parameter tells whether to register the address range with the hash tree and/or as a PMA.
+    /// Finally, the "virtio" subset lists every VirtIO address range that has been registered.
     template <typename AR>
         requires std::is_rvalue_reference_v<AR &&> && std::derived_from<AR, address_range>
     AR &push_back(AR &&ar, register_where where);
diff --git a/src/machine-c-api.cpp b/src/machine-c-api.cpp
index 2b32586c4..4248ff89c 100644
--- a/src/machine-c-api.cpp
+++ b/src/machine-c-api.cpp
@@ -41,7 +41,7 @@
 #include "local-machine.h"
 #include "machine-c-api-internal.h"
 #include "machine-config.h"
-#include "machine-merkle-tree.h"
+#include "machine-hash.h"
 #include "machine-reg.h"
 #include "machine-runtime-config.h"
 #include "machine.h"
@@ -77,53 +77,53 @@ const char *cm_set_temp_string(const std::string &s) {
     return temp_string.c_str();
 }
 
-cm_error cm_result_failure() try { throw; } catch (std::exception &e) {
+cm_error cm_result_failure() try { throw; } catch (const std::exception &e) {
     try {
         get_last_err_msg_storage() = e.what();
         throw;
-    } catch (std::invalid_argument &ex) {
+    } catch (const std::invalid_argument &ex) {
         return CM_ERROR_INVALID_ARGUMENT;
-    } catch (std::domain_error &ex) {
+    } catch (const std::domain_error &ex) {
         return CM_ERROR_DOMAIN_ERROR;
-    } catch (std::length_error &ex) {
+    } catch (const std::length_error &ex) {
         return CM_ERROR_LENGTH_ERROR;
-    } catch (std::out_of_range &ex) {
+    } catch (const std::out_of_range &ex) {
         return CM_ERROR_OUT_OF_RANGE;
-    } catch (std::logic_error &ex) {
+    } catch (const std::logic_error &ex) {
         return CM_ERROR_LOGIC_ERROR;
-    } catch (std::bad_optional_access &ex) {
+    } catch (const std::bad_optional_access &ex) {
         return CM_ERROR_BAD_OPTIONAL_ACCESS;
-    } catch (std::range_error &ex) {
+    } catch (const std::range_error &ex) {
         return CM_ERROR_RANGE_ERROR;
-    } catch (std::overflow_error &ex) {
+    } catch (const std::overflow_error &ex) {
         return CM_ERROR_OVERFLOW_ERROR;
-    } catch (std::underflow_error &ex) {
+    } catch (const std::underflow_error &ex) {
         return CM_ERROR_UNDERFLOW_ERROR;
-    } catch (std::regex_error &ex) {
+    } catch (const std::regex_error &ex) {
         return CM_ERROR_REGEX_ERROR;
-    } catch (std::system_error &ex) {
+    } catch (const std::system_error &ex) {
         return CM_ERROR_SYSTEM_ERROR;
-    } catch (std::runtime_error &ex) {
+    } catch (const std::runtime_error &ex) {
         return CM_ERROR_RUNTIME_ERROR;
-    } catch (std::bad_typeid &ex) {
+    } catch (const std::bad_typeid &ex) {
         return CM_ERROR_BAD_TYPEID;
-    } catch (std::bad_any_cast &ex) {
+    } catch (const std::bad_any_cast &ex) {
         return CM_ERROR_BAD_ANY_CAST;
-    } catch (std::bad_cast &ex) {
+    } catch (const std::bad_cast &ex) {
         return CM_ERROR_BAD_CAST;
-    } catch (std::bad_weak_ptr &ex) {
+    } catch (const std::bad_weak_ptr &ex) {
         return CM_ERROR_BAD_WEAK_PTR;
-    } catch (std::bad_function_call &ex) {
+    } catch (const std::bad_function_call &ex) {
         return CM_ERROR_BAD_FUNCTION_CALL;
-    } catch (std::bad_array_new_length &ex) {
+    } catch (const std::bad_array_new_length &ex) {
         return CM_ERROR_BAD_ARRAY_NEW_LENGTH;
-    } catch (std::bad_alloc &ex) {
+    } catch (const std::bad_alloc &ex) {
         return CM_ERROR_BAD_ALLOC;
-    } catch (std::bad_exception &ex) {
+    } catch (const std::bad_exception &ex) {
         return CM_ERROR_BAD_EXCEPTION;
-    } catch (std::bad_variant_access &ex) {
+    } catch (const std::bad_variant_access &ex) {
         return CM_ERROR_BAD_VARIANT_ACCESS;
-    } catch (std::exception &e) {
+    } catch (const std::exception &e) {
         return CM_ERROR_EXCEPTION;
     }
 } catch (...) {
@@ -473,11 +473,11 @@ static cm_machine *convert_to_c(cartesi::i_machine *cpp_m) {
     return reinterpret_cast<cm_machine *>(cpp_m);
 }
 
-static cartesi::machine_merkle_tree::hash_type convert_from_c(const cm_hash *c_hash) {
+static cartesi::machine_hash convert_from_c(const cm_hash *c_hash) {
     if (c_hash == nullptr) {
         throw std::invalid_argument("invalid hash");
     }
-    cartesi::machine_merkle_tree::hash_type cpp_hash; // In emulator this is std::array<unsigned char, hash_size>;
+    cartesi::machine_hash cpp_hash; // In emulator this is std::array<unsigned char, hash_size>;
     memcpy(cpp_hash.data(), c_hash, sizeof(cm_hash));
     return cpp_hash;
 }
@@ -683,8 +683,8 @@ cm_error cm_verify_step(const cm_machine *m, const cm_hash *root_hash_before, co
     if (log_filename == nullptr) {
         throw std::invalid_argument("invalid log_filename");
     }
-    const cartesi::machine::hash_type cpp_root_hash_before = convert_from_c(root_hash_before);
-    const cartesi::machine::hash_type cpp_root_hash_after = convert_from_c(root_hash_after);
+    const cartesi::machine_hash cpp_root_hash_before = convert_from_c(root_hash_before);
+    const cartesi::machine_hash cpp_root_hash_after = convert_from_c(root_hash_after);
     cartesi::interpreter_break_reason status{};
     if (m != nullptr) {
         const auto *cpp_m = convert_from_c(m);
@@ -710,8 +710,8 @@ cm_error cm_verify_step_uarch(const cm_machine *m, const cm_hash *root_hash_befo
     }
     const auto cpp_log = // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
         cartesi::from_json<cartesi::not_default_constructible<cartesi::access_log>>(log, "log").value();
-    const cartesi::machine::hash_type cpp_root_hash_before = convert_from_c(root_hash_before);
-    const cartesi::machine::hash_type cpp_root_hash_after = convert_from_c(root_hash_after);
+    const cartesi::machine_hash cpp_root_hash_before = convert_from_c(root_hash_before);
+    const cartesi::machine_hash cpp_root_hash_after = convert_from_c(root_hash_after);
     if (m != nullptr) {
         const auto *cpp_m = convert_from_c(m);
         cpp_m->verify_step_uarch(cpp_root_hash_before, cpp_log, cpp_root_hash_after);
@@ -730,8 +730,8 @@ cm_error cm_verify_reset_uarch(const cm_machine *m, const cm_hash *root_hash_bef
     }
     const auto cpp_log = // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
         cartesi::from_json<cartesi::not_default_constructible<cartesi::access_log>>(log, "log").value();
-    const cartesi::machine::hash_type cpp_root_hash_before = convert_from_c(root_hash_before);
-    const cartesi::machine::hash_type cpp_root_hash_after = convert_from_c(root_hash_after);
+    const cartesi::machine_hash cpp_root_hash_before = convert_from_c(root_hash_before);
+    const cartesi::machine_hash cpp_root_hash_after = convert_from_c(root_hash_after);
     if (m != nullptr) {
         const auto *cpp_m = convert_from_c(m);
         cpp_m->verify_reset_uarch(cpp_root_hash_before, cpp_log, cpp_root_hash_after);
@@ -748,7 +748,7 @@ cm_error cm_get_proof(const cm_machine *m, uint64_t address, int32_t log2_size,
         throw std::invalid_argument("invalid proof output");
     }
     const auto *cpp_m = convert_from_c(m);
-    const cartesi::machine_merkle_tree::proof_type cpp_proof = cpp_m->get_proof(address, log2_size);
+    const cartesi::i_machine::proof_type cpp_proof = cpp_m->get_proof(address, log2_size);
     *proof = cm_set_temp_string(cartesi::to_json(cpp_proof).dump());
     return cm_result_success();
 } catch (...) {
@@ -763,20 +763,37 @@ cm_error cm_get_root_hash(const cm_machine *m, cm_hash *hash) try {
         throw std::invalid_argument("invalid hash output");
     }
     const auto *cpp_m = convert_from_c(m);
-    cartesi::machine_merkle_tree::hash_type cpp_hash;
-    cpp_m->get_root_hash(cpp_hash);
-    memcpy(hash, static_cast<const uint8_t *>(cpp_hash.data()), sizeof(cm_hash));
+    cartesi::machine_hash cpp_hash = cpp_m->get_root_hash();
+    using elem_t = std::ranges::range_value_t<cm_hash>;
+    constexpr auto elem_n = std::extent_v<cm_hash>;
+    static_assert(std::ranges::size(cpp_hash) == elem_n);
+    std::ranges::copy(cpp_hash | cartesi::views::cast_to<elem_t>, std::ranges::data(*hash));
     return cm_result_success();
 } catch (...) {
     return cm_result_failure();
 }
 
-cm_error cm_verify_merkle_tree(cm_machine *m, bool *result) try {
+cm_error cm_get_node_hash(const cm_machine *m, uint64_t address, int log2_size, cm_hash *hash) try {
+    if (hash == nullptr) {
+        throw std::invalid_argument("invalid hash output");
+    }
+    const auto *cpp_m = convert_from_c(m);
+    cartesi::machine_hash cpp_hash = cpp_m->get_node_hash(address, log2_size);
+    using elem_t = std::ranges::range_value_t<cm_hash>;
+    constexpr auto elem_n = std::extent_v<cm_hash>;
+    static_assert(std::ranges::size(cpp_hash) == elem_n);
+    std::ranges::copy(cpp_hash | cartesi::views::cast_to<elem_t>, std::ranges::data(*hash));
+    return cm_result_success();
+} catch (...) {
+    return cm_result_failure();
+}
+
+cm_error cm_verify_hash_tree(cm_machine *m, bool *result) try {
     if (result == nullptr) {
         throw std::invalid_argument("invalid result output");
     }
     auto *cpp_m = convert_from_c(m);
-    *result = cpp_m->verify_merkle_tree();
+    *result = cpp_m->verify_hash_tree();
     return cm_result_success();
 } catch (...) {
     if (result != nullptr) {
@@ -885,20 +902,6 @@ cm_error cm_translate_virtual_address(cm_machine *m, uint64_t vaddr, uint64_t *p
     return cm_result_failure();
 }
 
-cm_error cm_verify_dirty_page_maps(cm_machine *m, bool *result) try {
-    if (result == nullptr) {
-        throw std::invalid_argument("invalid result output");
-    }
-    auto *cpp_m = convert_from_c(m);
-    *result = cpp_m->verify_dirty_page_maps();
-    return cm_result_success();
-} catch (...) {
-    if (result != nullptr) {
-        *result = false;
-    }
-    return cm_result_failure();
-}
-
 cm_error cm_get_initial_config(const cm_machine *m, const char **config) try {
     if (config == nullptr) {
         throw std::invalid_argument("invalid config output");
@@ -1094,8 +1097,8 @@ cm_error cm_verify_send_cmio_response(const cm_machine *m, uint16_t reason, cons
     }
     const auto cpp_log = // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
         cartesi::from_json<cartesi::not_default_constructible<cartesi::access_log>>(log, "log").value();
-    const cartesi::machine::hash_type cpp_root_hash_before = convert_from_c(root_hash_before);
-    const cartesi::machine::hash_type cpp_root_hash_after = convert_from_c(root_hash_after);
+    const cartesi::machine_hash cpp_root_hash_before = convert_from_c(root_hash_before);
+    const cartesi::machine_hash cpp_root_hash_after = convert_from_c(root_hash_after);
     if (m != nullptr) {
         const auto *cpp_m = convert_from_c(m);
         cpp_m->verify_send_cmio_response(reason, data, length, cpp_root_hash_before, cpp_log, cpp_root_hash_after);
diff --git a/src/machine-c-api.h b/src/machine-c-api.h
index 7c46dc703..560f79409 100644
--- a/src/machine-c-api.h
+++ b/src/machine-c-api.h
@@ -467,6 +467,7 @@ CM_API cm_error cm_get_runtime_config(const cm_machine *m, const char **runtime_
 ///     "backing_store": {
 ///         "data_filename": "linux.bin"
 ///         "dht_filename": "linux.dht"
+///         "dpt_filename": "linux.dpt"
 ///         "shared": false
 ///     }
 /// }
@@ -497,6 +498,14 @@ CM_API cm_error cm_get_address_ranges(const cm_machine *m, const char **ranges);
 /// \returns 0 for success, non zero code for error.
 CM_API cm_error cm_get_root_hash(const cm_machine *m, cm_hash *hash);
 
+/// \brief Obtains the hash of a node in the Merkle tree.
+/// \param m Pointer to a non-empty machine object (holds a machine instance).
+/// \param address Address of node.
+/// \param log2_size Log<sub>2</sub> of node size.
+/// \param hash Valid pointer to cm_hash structure that receives the hash.
+/// \returns 0 for success, non zero code for error.
+CM_API cm_error cm_get_node_hash(const cm_machine *m, uint64_t address, int log2_size, cm_hash *hash);
+
 /// \brief Obtains the proof for a node in the machine state Merkle tree.
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
 /// \param address Address of target node. Must be aligned to a 2^log2_size boundary.
@@ -719,19 +728,12 @@ CM_API cm_error cm_verify_send_cmio_response(const cm_machine *m, uint16_t reaso
 // Integrity checking
 // ------------------------------------
 
-/// \brief Verifies integrity of Merkle tree against current machine state.
+/// \brief Verifies integrity of hash-tree tree against current machine state.
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
 /// \param result True if tree is self-consistent, false otherwise.
 /// \returns 0 for success, non zero code for error.
 /// \details This method is used only for emulator internal tests.
-CM_API cm_error cm_verify_merkle_tree(cm_machine *m, bool *result);
-
-/// \brief Verifies integrity of dirty page maps.
-/// \param m Pointer to a non-empty machine object (holds a machine instance).
-/// \param result True if dirty page maps are consistent, false otherwise.
-/// \returns 0 for success, non zero code for error.
-/// \details This method is used only for emulator internal tests.
-CM_API cm_error cm_verify_dirty_page_maps(cm_machine *m, bool *result);
+CM_API cm_error cm_verify_hash_tree(cm_machine *m, bool *result);
 
 #ifdef __cplusplus
 }
diff --git a/src/machine-config.cpp b/src/machine-config.cpp
index 486ed8c9d..439382aef 100644
--- a/src/machine-config.cpp
+++ b/src/machine-config.cpp
@@ -49,6 +49,13 @@ std::string machine_config::get_dht_filename(const std::string &dir, uint64_t st
     return sout.str();
 }
 
+std::string machine_config::get_dpt_filename(const std::string &dir, uint64_t start, uint64_t length) {
+    std::ostringstream sout;
+    // dense hash tree
+    sout << dir << "/" << std::hex << std::setw(16) << std::setfill('0') << start << "-" << length << ".dpt";
+    return sout.str();
+}
+
 std::string machine_config::get_sht_filename(const std::string &dir) {
     // sparse hash tree
     return dir + "/global.sht";
@@ -70,6 +77,7 @@ void machine_config::adjust_backing_store_config(uint64_t start, uint64_t length
     c.truncate = false;
     c.data_filename = machine_config::get_data_filename(dir, start, length);
     c.dht_filename = machine_config::get_dht_filename(dir, start, length);
+    c.dpt_filename = machine_config::get_dpt_filename(dir, start, length);
 }
 
 void machine_config::adjust_hash_tree_config(const std::string &dir, hash_tree_config &c) {
@@ -115,7 +123,7 @@ machine_config machine_config::load(const std::string &dir) {
         }
         ju_get_field(j, std::string("config"), c, "");
         c.adjust_backing_stores(dir);
-    } catch (std::exception &e) {
+    } catch (const std::exception &e) {
         throw std::runtime_error{e.what()};
     }
     return c;
diff --git a/src/machine-config.h b/src/machine-config.h
index 687171ca6..285bc3156 100644
--- a/src/machine-config.h
+++ b/src/machine-config.h
@@ -43,6 +43,7 @@ struct backing_store_config final {
     bool truncate{false};      ///< Should backing store be truncated to correct size?
     std::string data_filename; ///< Backing store for associated memory address range
     std::string dht_filename;  ///< Backing store for corresponding dense hash-tree
+    std::string dpt_filename;  ///< Backing store for corresponding dirty-page tree
 };
 
 /// \brief Processor state config
@@ -76,7 +77,7 @@ struct dtb_config final {
 struct memory_range_config final {
     uint64_t start{0xffffffffffffffffUL};  ///< Memory range start position, default is to auto detect
     uint64_t length{0xffffffffffffffffUL}; ///< Memory range length, default is to auto detect
-    bool read_only{false};                 ///< Make memory range read-only
+    bool read_only{false};                 ///< Make memory range read-only to host
     backing_store_config backing_store;    ///< Backing store
 };
 
@@ -150,13 +151,12 @@ struct uarch_config final {
 
 /// \brief Hash tree config
 struct hash_tree_config final {
-    std::string hasher{"keccak"}; ///< What hashing function to use?
-    bool shared{false};           ///< Should changes be reflected in backing store?
-    bool create{false};           ///< Should backing store be created to correct size?
-    bool truncate{false};         ///< Should backing store be truncated to correct size?
-    std::string sht_filename;     ///< Backing storage for sparse hash-tree
-    std::string phtc_filename;    ///< Backing storage for page hash-tree cache
-    uint64_t phtc_size{2046};     ///< Max number of pages in page hash-tree cache
+    bool shared{false};        ///< Should changes be reflected in backing store?
+    bool create{false};        ///< Should backing store be created?
+    bool truncate{false};      ///< Should backing store be truncated to correct size?
+    std::string sht_filename;  ///< Backing storage for sparse hash-tree
+    std::string phtc_filename; ///< Backing storage for page hash-tree cache
+    uint64_t phtc_size{2048};  ///< Max number of pages in page hash-tree cache
 };
 
 /// \brief Machine state config
@@ -180,6 +180,9 @@ struct machine_config final {
     /// \brief Get the name where dense hash-tree for an address range will be stored in a directory
     static std::string get_dht_filename(const std::string &dir, uint64_t start, uint64_t length);
 
+    /// \brief Get the name where dirty-page -tree for an address range will be stored in a directory
+    static std::string get_dpt_filename(const std::string &dir, uint64_t start, uint64_t length);
+
     /// \brief Get the name where global sparse hash-tree will be stored in a directory
     static std::string get_sht_filename(const std::string &dir);
 
diff --git a/src/machine-hash.h b/src/machine-hash.h
new file mode 100644
index 000000000..fb68820b5
--- /dev/null
+++ b/src/machine-hash.h
@@ -0,0 +1,35 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef MACHINE_HASH_H
+#define MACHINE_HASH_H
+
+/// \file
+/// \brief Storage for a hash
+
+#include <array>
+#include <span>
+
+namespace cartesi {
+
+static constexpr size_t machine_hash_size = 32;
+using machine_hash = std::array<unsigned char, machine_hash_size>;
+using machine_hash_view = std::span<unsigned char, machine_hash_size>;
+using const_machine_hash_view = std::span<const unsigned char, machine_hash_size>;
+
+} // namespace cartesi
+
+#endif
diff --git a/src/machine-merkle-tree.cpp b/src/machine-merkle-tree.cpp
deleted file mode 100644
index 28e0740d6..000000000
--- a/src/machine-merkle-tree.cpp
+++ /dev/null
@@ -1,471 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#include "machine-merkle-tree.h"
-
-#include <algorithm>
-#include <cassert>
-#include <cstdint>
-#include <cstring>
-#include <iomanip>
-#include <iostream>
-#include <tuple>
-
-#include "i-hasher.h"
-#include "pristine-merkle-tree.h"
-
-/// \file
-/// \brief Merkle tree implementation.
-
-namespace cartesi {
-
-// Initialize static pristine hashes
-const cartesi::pristine_merkle_tree &machine_merkle_tree::pristine_hashes() {
-    static const cartesi::pristine_merkle_tree tree{machine_merkle_tree::get_log2_root_size(),
-        machine_merkle_tree::get_log2_word_size()};
-    return tree;
-}
-
-constexpr machine_merkle_tree::address_type machine_merkle_tree::get_page_index(address_type address) {
-    return address & m_page_index_mask;
-}
-
-machine_merkle_tree::tree_node *machine_merkle_tree::get_page_node(address_type page_index) const {
-    // Look for entry in page map hash table
-    auto it = m_page_node_map.find(page_index);
-    if (it != m_page_node_map.end()) {
-        return it->second;
-    }
-    return nullptr;
-}
-
-constexpr machine_merkle_tree::address_type machine_merkle_tree::get_offset_in_page(address_type address) {
-    return address & m_page_offset_mask;
-}
-
-int machine_merkle_tree::set_page_node_map(address_type page_index, tree_node *node) {
-    m_page_node_map[page_index] = node;
-    return 1;
-}
-
-// NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-machine_merkle_tree::tree_node *machine_merkle_tree::create_node() const {
-#ifdef MERKLE_DUMP_STATS
-    m_num_nodes++;
-#endif
-    return new tree_node{};
-}
-
-// NOLINTNEXTLINE(readability-convert-member-functions-to-static)
-void machine_merkle_tree::destroy_node(tree_node *node) const {
-#ifdef MERKLE_DUMP_STATS
-    --m_num_nodes;
-#endif
-    delete node;
-}
-
-machine_merkle_tree::tree_node *machine_merkle_tree::new_page_node(address_type page_index) {
-    // Start with the first bit in the address space
-    address_type bit_mask = UINT64_C(1) << (get_log2_root_size() - 1);
-    tree_node *node = m_root;
-    // Descend tree until we reach the node at the end of the
-    // path determined by the page index,
-    // creating the needed nodes along the way
-    while (true) {
-        const int bit = static_cast<int>((page_index & bit_mask) != 0);
-        tree_node *child = node->child[bit];
-        if (child == nullptr) {
-            child = create_node();
-            if (child == nullptr) {
-                return nullptr;
-            }
-            child->parent = node;
-            node->child[bit] = child;
-        }
-        node = child;
-        bit_mask >>= 1;
-        if ((bit_mask & m_page_index_mask) == 0) {
-            break;
-        }
-    }
-    // Finally associate page node to page index
-    if (set_page_node_map(page_index, node) == 0) {
-        return nullptr;
-    }
-    // Only if all previous steps succeeded, do we return the node
-    return node;
-}
-
-void machine_merkle_tree::get_page_node_hash(hasher_type &h, const unsigned char *start, int log2_size,
-    hash_type &hash) const {
-    if (log2_size > get_log2_word_size()) {
-        hash_type child0;
-        hash_type child1;
-        --log2_size;
-        const address_type size = UINT64_C(1) << log2_size;
-        get_page_node_hash(h, start, log2_size, child0);
-        get_page_node_hash(h, start + size, log2_size, child1);
-        get_concat_hash(h, child0, child1, hash);
-    } else {
-        h.begin();
-        h.add_data(start, get_word_size());
-        h.end(hash);
-    }
-}
-
-void machine_merkle_tree::get_page_node_hash(hasher_type &h, const unsigned char *page_data, hash_type &hash) const {
-    if (page_data != nullptr) {
-        get_page_node_hash(h, page_data, get_log2_page_size(), hash);
-    } else {
-        hash = get_pristine_hash(get_log2_page_size());
-    }
-}
-
-void machine_merkle_tree::get_page_node_hash(address_type page_index, hash_type &hash) const {
-    assert(page_index == get_page_index(page_index));
-    tree_node *node = get_page_node(page_index);
-    if (node == nullptr) {
-        hash = get_pristine_hash(get_log2_page_size());
-    } else {
-        hash = node->hash;
-    }
-}
-
-const machine_merkle_tree::hash_type &machine_merkle_tree::get_child_hash(int child_log2_size, const tree_node *node,
-    int bit) {
-    const tree_node *child = node->child[bit];
-    return (child != nullptr) ? child->hash : get_pristine_hash(child_log2_size);
-}
-
-void machine_merkle_tree::update_inner_node_hash(hasher_type &h, int log2_size, tree_node *node) {
-    get_concat_hash(h, get_child_hash(log2_size - 1, node, 0), get_child_hash(log2_size - 1, node, 1), node->hash);
-}
-
-void machine_merkle_tree::dump_hash(const hash_type &hash) {
-    auto f = std::cerr.flags();
-    for (const auto &b : hash) {
-        std::cerr << std::hex << std::setfill('0') << std::setw(2) << static_cast<int>(b);
-    }
-    std::cerr << '\n';
-    std::cerr.flags(f);
-}
-
-const machine_merkle_tree::hash_type &machine_merkle_tree::get_pristine_hash(int log2_size) {
-    return pristine_hashes().get_hash(log2_size);
-}
-
-void machine_merkle_tree::dump_merkle_tree(tree_node *node, uint64_t address, int log2_size) const {
-    for (int i = 0; i < get_log2_root_size() - log2_size; i++) {
-        std::cerr << ' ';
-    }
-    std::cerr << "0x" << std::setfill('0') << std::setw(16) << std::hex << address << ":" << std::setfill('0')
-              << std::setw(2) << std::dec << log2_size << ' ';
-    if (node != nullptr) {
-        dump_hash(node->hash);
-        if (log2_size > get_log2_page_size()) {
-            dump_merkle_tree(node->child[0], address, log2_size - 1);
-            dump_merkle_tree(node->child[1], address + (UINT64_C(1) << (log2_size - 1)), log2_size - 1);
-        }
-    } else {
-        std::cerr << "nullptr\n";
-    }
-}
-
-void machine_merkle_tree::destroy_merkle_tree(tree_node *node, int log2_size) {
-    if (node != nullptr) {
-        // If this is an inner node, invoke recursively
-        if (log2_size > get_log2_page_size()) {
-            destroy_merkle_tree(node->child[0], log2_size - 1);
-            destroy_merkle_tree(node->child[1], log2_size - 1);
-        }
-        destroy_node(node);
-    }
-}
-
-void machine_merkle_tree::destroy_merkle_tree() {
-    destroy_merkle_tree(m_root_storage.child[0], get_log2_root_size() - 1);
-    destroy_merkle_tree(m_root_storage.child[1], get_log2_root_size() - 1);
-    memset(&m_root_storage, 0, sizeof(m_root_storage));
-}
-
-void machine_merkle_tree::get_inside_page_sibling_hashes(hasher_type &h, address_type address, int log2_size,
-    hash_type &hash, const unsigned char *curr_data, int log2_curr_size, hash_type &curr_hash, int parent_diverged,
-    int curr_diverged, proof_type &proof) const {
-    // If node currently being visited is larger than a
-    // word, invoke recursively
-    if (log2_curr_size > get_log2_word_size()) {
-        const int log2_child_size = log2_curr_size - 1;
-        const address_type child_size = UINT64_C(1) << log2_child_size;
-        hash_type first_hash;
-        hash_type second_hash;
-        const int child_bit = static_cast<int>((address & child_size) != 0);
-        get_inside_page_sibling_hashes(h, address, log2_size, hash, curr_data, log2_child_size, first_hash,
-            static_cast<int>((parent_diverged != 0) || (curr_diverged) != 0), static_cast<int>(child_bit != 0), proof);
-        get_inside_page_sibling_hashes(h, address, log2_size, hash, curr_data + child_size, log2_child_size,
-            second_hash, static_cast<int>((parent_diverged != 0) || (curr_diverged) != 0),
-            static_cast<int>(child_bit != 1), proof);
-        // Compute curr_hash from hashes of its children
-        get_concat_hash(h, first_hash, second_hash, curr_hash);
-        // Otherwise directly compute hash of word
-    } else {
-        h.begin();
-        h.add_data(curr_data, get_word_size());
-        h.end(curr_hash);
-    }
-    if (parent_diverged == 0) {
-        // So if the parent belongs to the path, but the node currently being
-        // visited doesn't, it is a sibling and we store its hash.
-        if ((curr_diverged != 0) && log2_curr_size >= proof.get_log2_target_size()) {
-            proof.set_sibling_hash(curr_hash, log2_curr_size);
-            // Otherwise, if the node hasn't diverged either and
-            // it is has the same size as the target node, then it *is*
-            // the target node
-        } else if (log2_curr_size == log2_size) {
-            hash = curr_hash;
-        }
-    }
-}
-
-void machine_merkle_tree::get_inside_page_sibling_hashes(address_type address, int log2_size, hash_type &hash,
-    const unsigned char *page_data, hash_type &page_hash, proof_type &proof) const {
-    hasher_type h;
-    get_inside_page_sibling_hashes(h, address, log2_size, hash, page_data, get_log2_page_size(), page_hash,
-        0 /* parent hasn't diverted */, 0 /* curr node hasn't diverged */, proof);
-}
-
-void machine_merkle_tree::dump_merkle_tree() const {
-    dump_merkle_tree(m_root, 0, get_log2_root_size());
-}
-
-bool machine_merkle_tree::begin_update() {
-    m_merkle_update_fifo.clear();
-    return true;
-}
-
-bool machine_merkle_tree::update_page_node_hash(address_type page_index, const hash_type &hash) {
-    assert(get_page_index(page_index) == page_index);
-    tree_node *node = get_page_node(page_index);
-    // If there is no page node for this page index, allocate a fresh one
-    if (node == nullptr) {
-        node = new_page_node(page_index);
-    }
-    // If allocation failed, we fail
-    if (node == nullptr) {
-        return false;
-    }
-    // Copy new hash value to node
-    node->hash = hash;
-    // Add parent to fifo so we propagate changes
-    if ((node->parent != nullptr) && node->parent->mark != m_merkle_update_nonce) {
-        m_merkle_update_fifo.emplace_back(get_log2_page_size() + 1, node->parent);
-        node->parent->mark = m_merkle_update_nonce;
-    }
-    return true;
-}
-
-bool machine_merkle_tree::end_update(hasher_type &h) {
-    // Now go over the queue of inner nodes updating their hashes and
-    // enqueueing their parents until the queue is empty
-    while (!m_merkle_update_fifo.empty()) {
-        int log2_size{};
-        tree_node *node{};
-        std::tie(log2_size, node) = m_merkle_update_fifo.front();
-        update_inner_node_hash(h, log2_size, node);
-        m_merkle_update_fifo.pop_front();
-        if ((node->parent != nullptr) && node->parent->mark != m_merkle_update_nonce) {
-            m_merkle_update_fifo.emplace_back(log2_size + 1, node->parent);
-            node->parent->mark = m_merkle_update_nonce;
-        }
-    }
-    ++m_merkle_update_nonce;
-    return true;
-}
-
-machine_merkle_tree::machine_merkle_tree() : m_root_storage{}, m_root{&m_root_storage} {
-    m_root->hash = get_pristine_hash(get_log2_root_size());
-#ifdef MERKLE_DUMP_STATS
-    m_num_nodes = 0;
-#endif
-}
-
-machine_merkle_tree::~machine_merkle_tree() {
-#ifdef MERKLE_DUMP_STATS
-    std::cerr << "before destruction\n";
-    std::cerr << "  number of tree nodes:     " << m_num_nodes << '\n';
-#endif
-    destroy_merkle_tree();
-#ifdef MERKLE_DUMP_STATS
-    std::cerr << "after destruction\n";
-    std::cerr << "  number of tree nodes:     " << m_num_nodes << '\n';
-#endif
-}
-
-void machine_merkle_tree::get_root_hash(hash_type &hash) const {
-    hash = m_root->hash;
-}
-
-bool machine_merkle_tree::verify_tree() const {
-    hasher_type h;
-    return verify_tree(h, m_root, get_log2_root_size());
-}
-
-bool machine_merkle_tree::verify_tree(hasher_type &h, tree_node *node, int log2_size) const {
-    // pristine node is always correct
-    if (node == nullptr) {
-        return true;
-    }
-    // verify inner node
-    if (log2_size > get_log2_page_size()) {
-        const int child_log2_size = log2_size - 1;
-        auto first_ok = verify_tree(h, node->child[0], child_log2_size);
-        auto second_ok = verify_tree(h, node->child[1], child_log2_size);
-        if (!first_ok || !second_ok) {
-            return false;
-        }
-        hash_type hash;
-        get_concat_hash(h, get_child_hash(child_log2_size, node, 0), get_child_hash(child_log2_size, node, 1), hash);
-        return hash == node->hash;
-        // Assume page nodes are correct
-    }
-    return true;
-}
-
-machine_merkle_tree::proof_type machine_merkle_tree::get_proof(address_type target_address, int log2_target_size,
-    const unsigned char *page_data) const {
-    // Check for valid target node size
-    if (log2_target_size > get_log2_root_size() || log2_target_size < get_log2_word_size()) {
-        throw std::runtime_error{"log2_target_size is out of bounds"};
-    }
-
-    // Check target address alignment
-    if ((target_address & ((~UINT64_C(0)) >> (get_log2_root_size() - log2_target_size))) != 0) {
-        throw std::runtime_error{"misaligned target address"};
-    }
-
-    proof_type proof{get_log2_root_size(), log2_target_size};
-
-    // Copy hashes for nodes larger than or equal to the page size
-    const int log2_stop_size = std::max(log2_target_size, get_log2_page_size());
-    int log2_node_size = get_log2_root_size();
-    const tree_node *node = m_root;
-    // Copy non-pristine siblings hashes directly from tree nodes
-    while ((node != nullptr) && log2_node_size > log2_stop_size) {
-        const int log2_child_size = log2_node_size - 1;
-        const int path_bit = static_cast<int>((target_address & (UINT64_C(1) << (log2_child_size))) != 0);
-        proof.set_sibling_hash(get_child_hash(log2_child_size, node, static_cast<int>(static_cast<int>(path_bit) == 0)),
-            log2_child_size);
-        node = node->child[path_bit];
-        log2_node_size = log2_child_size;
-    }
-    // At this point, there are three alternatives
-    // Case 1
-    // We hit a pristine node along the path to the target node
-    if (node == nullptr) {
-        if (page_data != nullptr) {
-            throw std::runtime_error{"inconsistent merkle tree"};
-        }
-        // All remaining siblings along the path are pristine
-        for (int i = log2_node_size - 1; i >= log2_target_size; --i) {
-            proof.set_sibling_hash(get_pristine_hash(i), i);
-        }
-        // Copy pristine hash into target
-        proof.set_target_hash(get_pristine_hash(log2_target_size));
-        // Case 2
-        // We hit a page node along the path to the target node
-    } else if (log2_node_size == get_log2_page_size()) {
-        assert(node);
-        hash_type page_hash;
-        // If target node is smaller than page size
-        if (log2_target_size < get_log2_page_size()) {
-            // If we were given the page data, compute from it
-            if (page_data != nullptr) {
-                get_inside_page_sibling_hashes(target_address, log2_target_size, proof.get_target_hash(), page_data,
-                    page_hash, proof);
-                // Otherwise, if page is pristine
-            } else {
-                page_hash = get_pristine_hash(get_log2_page_size());
-                for (int i = get_log2_page_size() - 1; i >= log2_target_size; --i) {
-                    proof.set_sibling_hash(get_pristine_hash(i), i);
-                }
-                proof.set_target_hash(get_pristine_hash(log2_target_size));
-            }
-            // Check if hash stored in node matches what we just computed
-            if (node->hash != page_hash) {
-                // Caller probably forgot to update the Merkle tree
-                throw std::runtime_error{"inconsistent merkle tree"};
-            }
-            // If target node is the page itself
-        } else {
-            // Simply copy hash
-            proof.set_target_hash(node->hash);
-        }
-        // Case 3
-        // We hit the target node itself
-    } else {
-        assert(node && (log2_node_size == log2_target_size));
-        // Copy target node hash and nothing else to do
-        proof.set_target_hash(node->hash);
-    }
-    // Copy remaining proof values
-    proof.set_target_address(target_address);
-    proof.set_root_hash(m_root->hash); // NOLINT: m_root can't be nullptr
-#ifndef NDEBUG
-    // Return proof only if it passes verification
-    hasher_type h;
-    if (!proof.verify(h)) {
-        throw std::runtime_error{"proof failed verification"};
-    }
-#endif
-    return proof;
-}
-
-machine_merkle_tree::hash_type machine_merkle_tree::get_node_hash(address_type target_address,
-    int log2_target_size) const {
-    if (log2_target_size > get_log2_root_size() || log2_target_size < get_log2_word_size()) {
-        throw std::runtime_error{"log2_target_size is out of bounds"};
-    }
-    if (log2_target_size < get_log2_page_size()) {
-        throw std::runtime_error{"log2_target_size is smaller than page size"};
-    }
-    if ((target_address & ((static_cast<address_type>(1) << log2_target_size) - 1)) != 0) {
-        throw std::invalid_argument{"address is not page-aligned"};
-    }
-    int log2_node_size = get_log2_root_size();
-    const tree_node *node = m_root;
-    // walk down the tree until we reach the target node
-    while (node != nullptr && log2_node_size > log2_target_size) {
-        const int log2_child_size = log2_node_size - 1;
-        const int path_bit = static_cast<int>((target_address & (UINT64_C(1) << (log2_child_size))) != 0);
-        node = node->child[path_bit];
-        log2_node_size = log2_child_size;
-    }
-    if (node == nullptr) {
-        // We hit a pristine node along the path to the target node
-        return get_pristine_hash(log2_target_size);
-    }
-    return node->hash;
-}
-
-std::ostream &operator<<(std::ostream &out, const machine_merkle_tree::hash_type &hash) {
-    auto f = out.flags();
-    for (const unsigned b : hash) {
-        out << std::hex << std::setfill('0') << std::setw(2) << b;
-    }
-    out.flags(f);
-    return out;
-}
-
-} // namespace cartesi
diff --git a/src/machine-merkle-tree.h b/src/machine-merkle-tree.h
deleted file mode 100644
index 71293fed5..000000000
--- a/src/machine-merkle-tree.h
+++ /dev/null
@@ -1,368 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef MERKLE_TREE_H
-#define MERKLE_TREE_H
-
-/// \file
-/// \brief Merkle tree interface.
-
-#include <array>
-#include <cstddef>
-#include <cstdint>
-#include <deque>
-#include <iosfwd>
-#include <unordered_map>
-#include <utility>
-
-#include "keccak-256-hasher.h"
-#include "merkle-tree-proof.h"
-#include "pristine-merkle-tree.h"
-
-namespace cartesi {
-
-/// \class machine_merkle_tree
-/// \brief Merkle tree implementation.
-///
-/// \details The machine_merkle_tree class implements a Merkle tree
-/// covering LOG2_ROOT_SIZE bits of address space.
-///
-/// Upon creation, the memory is *pristine*, i.e., completely
-/// filled with zeros.
-///
-/// To optimize for space, subtrees corresponding to pristine
-/// memory are represented by <tt>nullptr</tt> nodes.
-/// Additionally, the tree is truncated below *page* nodes
-/// subintending LOG2_PAGE_SIZE bits of address space.
-/// The trees corresponding to pages are rebuilt from the
-/// original data whenever needed and never stored.
-/// Pages are divided into *words* that cover LOG2_WORD_SIZE
-/// bits of address space.
-/// Tree leaves contain Keccak-256 hashes of individual words.
-///
-/// Tree contents are updated page-by-page using calls to
-/// machine_merkle_tree#begin_update, machine_merkle_tree#update_page, ...,
-/// machine_merkle_tree#update_page, machine_merkle_tree#end_update.
-class machine_merkle_tree final {
-public:
-    using word_type = uint64_t;
-
-    using address_type = uint64_t;
-
-private:
-    /// \brief LOG2_ROOT_SIZE Number of bits covered by the address space.
-    /// I.e., log<sub>2</sub> of number of bytes subintended by the tree root.
-    static constexpr int LOG2_ROOT_SIZE = 64;
-    /// \brief LOG2_PAGE_SIZE Number of bits covered by a page.
-    /// I.e., log<sub>2</sub> of number of bytes subintended by the
-    /// the deepest explicitly represented nodes.
-    static constexpr int LOG2_PAGE_SIZE = 12;
-    /// \brief LOG2_WORD_SIZE Number of bits covered by a word.
-    /// I.e., log<sub>2</sub> of number of bytes subintended by the
-    /// the deepest tree nodes.
-    static constexpr int LOG2_WORD_SIZE = 5;
-    /// \brief DEPTH Depth of Merkle tree.
-    static constexpr int DEPTH = LOG2_ROOT_SIZE - LOG2_WORD_SIZE;
-
-    static constexpr size_t m_word_size = static_cast<size_t>(1) << LOG2_WORD_SIZE;
-
-    static constexpr address_type m_page_index_mask = ((~UINT64_C(0)) >> (64 - LOG2_ROOT_SIZE)) << LOG2_PAGE_SIZE;
-
-    static constexpr address_type m_page_offset_mask = ~m_page_index_mask;
-
-    static constexpr size_t m_page_size = static_cast<size_t>(1) << LOG2_PAGE_SIZE;
-
-public:
-    /// \brief Returns the LOG2_ROOT_SIZE parameter.
-    static constexpr int get_log2_root_size() {
-        return LOG2_ROOT_SIZE;
-    }
-    /// \brief Returns the LOG2_PAGE_SIZE parameter.
-    static constexpr int get_log2_page_size() {
-        return LOG2_PAGE_SIZE;
-    }
-    /// \brief Returns the LOG2_WORD_SIZE parameter.
-    static constexpr int get_log2_word_size() {
-        return LOG2_WORD_SIZE;
-    }
-    /// \brief Returns the tree DEPTH.
-    static constexpr int get_depth() {
-        return DEPTH;
-    }
-    /// \brief Returns the page size.
-    static constexpr size_t get_page_size() {
-        return m_page_size;
-    }
-    /// \brief Returns the word size.
-    static constexpr size_t get_word_size() {
-        return m_word_size;
-    }
-
-    /// \brief Hasher class.
-    using hasher_type = keccak_256_hasher;
-
-    /// \brief Storage for a hash.
-    using hash_type = hasher_type::hash_type;
-
-    /// \brief Storage for the proof of a word value.
-    using proof_type = merkle_tree_proof<hash_type, address_type>;
-
-    /// \brief Storage for the hashes of the siblings of all nodes along
-    /// the path from the root to target node.
-    using siblings_type = proof_type::sibling_hashes_type;
-
-private:
-    /// \brief Merkle tree node structure.
-    /// \details A node is known to be an inner-node or a page-node implicitly
-    /// based on its height in the tree.
-    //??D This is assumed to be a POD type in the implementation
-    struct tree_node {
-        hash_type hash;                   ///< Hash of subintended data.
-        tree_node *parent;                ///< Pointer to parent node (nullptr for root).
-        std::array<tree_node *, 2> child; ///< Children nodes.
-        uint64_t mark;                    ///< Helper for traversal algorithms.
-    };
-
-    // Sparse map from virtual page index to the
-    // corresponding page node in the Merkle tree.
-    std::unordered_map<address_type, tree_node *> m_page_node_map;
-
-    // Root of the Merkle tree.
-    tree_node m_root_storage;
-    tree_node *m_root;
-
-    // Used to mark visited nodes when traversing the tree
-    // bottom up in breadth to propagate changes from dirty
-    // pages all the way up to the tree root.
-    uint64_t m_merkle_update_nonce{1};
-    // FIFO to process pages in bottom-up order.
-    std::deque<std::pair<int, tree_node *>> m_merkle_update_fifo;
-
-    // For statistics.
-#ifdef MERKLE_DUMP_STATS
-    mutable uint64_t m_num_nodes;
-#endif
-
-    /// \brief Maps a page_index to a node.
-    /// \param page_index Page index.
-    /// \param node Node subintending page.
-    /// \return 1 if succeeded, 0 otherwise.
-    int set_page_node_map(address_type page_index, tree_node *node);
-
-    /// \brief Creates and returns a new tree node.
-    /// \return Newly created node or nullptr if out-of-memory.
-    tree_node *create_node() const;
-
-    /// \brief Deallocates node.
-    /// \param node Node to be deallocated.
-    void destroy_node(tree_node *node) const;
-
-    /// \brief Creates a new page node and insert it into the Merkle tree.
-    /// \param page_index Page index for node.
-    /// \return Newly created node.
-    /// \details Does *not* check if a node already exists for that page index.
-    /// Maps new node to the page index.
-    tree_node *new_page_node(address_type page_index);
-
-    /// \brief Updates an inner node hash from its children.
-    /// \param h Hasher object.
-    /// \param log2_size log<sub>2</sub> of size subintended by node.
-    /// \param node Node to be updated.
-    static void update_inner_node_hash(hasher_type &h, int log2_size, tree_node *node);
-
-    /// \brief Dumps a hash to std::cerr.
-    /// \param hash Hash to be dumped.
-    static void dump_hash(const hash_type &hash);
-
-    /// \brief Returns the hash for a child of a given node.
-    /// \param child_log2_size log2_size of child node.
-    /// \param node Node from which to obtain child.
-    /// \param bit Bit corresponding to child_log2_size in child node address.
-    /// \return Reference to child hash. If child pointer is null,
-    /// returns a pristine hash.
-    static const hash_type &get_child_hash(int child_log2_size, const tree_node *node, int bit);
-
-    /// \brief Dumps tree rooted at node to std::cerr.
-    /// \param node Root of subtree.
-    /// \param address start of range subintended by \p node.
-    /// \param log2_size log<sub>2</sub> of size of range subintended by \p node.
-    void dump_merkle_tree(tree_node *node, uint64_t address, int log2_size) const;
-
-    /// \brief Dumps the entire tree rooted to std::cerr.
-    void dump_merkle_tree() const;
-
-    /// \brief Destroys tree rooted at node.
-    /// \param node Root of subtree.
-    /// \param  log2_size log<sub>2</sub> of size subintended by \p node.
-    void destroy_merkle_tree(tree_node *node, int log2_size);
-
-    /// \brief Destroys entire Merkle tree.
-    void destroy_merkle_tree();
-
-    /// \brief Verifies tree rooted at node.
-    /// \param h Hasher object.
-    /// \param node Root of subtree.
-    /// \param  log2_size log<sub>2</sub> of size subintended by \p node.
-    /// \returns True if tree is consistent, false otherwise.
-    bool verify_tree(hasher_type &h, tree_node *node, int log2_size) const;
-
-    /// \brief Computes the page index for a memory address.
-    /// \param address Memory address.
-    /// \return The page index.
-    static constexpr address_type get_page_index(address_type address);
-
-    /// \brief Computes the offset of a memory address within its page.
-    /// \param address Memory address.
-    /// \return The offset.
-    static constexpr address_type get_offset_in_page(address_type address);
-
-    /// \brief Computes the offset of a memory address within its page.
-    /// \param page_index Page index associated to node.
-    /// \return The node, if found, or nullptr otherwise.
-    tree_node *get_page_node(address_type page_index) const;
-
-    /// \brief Recursively builds hash for log2_size node
-    /// from contiguous memory.
-    /// \param h Hasher object.
-    /// \param start Start of contiguous memory subintended by node.
-    /// \param log2_size log<sub>2</sub> of size subintended by node.
-    /// \param hash Receives the hash.
-    void get_page_node_hash(hasher_type &h, const unsigned char *start, int log2_size, hash_type &hash) const;
-
-    /// \brief Gets the sibling hashes along the path from
-    /// the node currently being visited and a target node.
-    /// \param h Hasher object.
-    /// \param address Address of target node.
-    /// \param log2_size log<sub>2</sub> of size subintended by target node.
-    /// \param hash Receives the target node hash if it is a
-    /// subnode of the node currently being visited.
-    /// \param curr_data Pointer to contiguous data for node currently
-    /// being visited.
-    /// \param log2_curr_size log<sub>2</sub> of size subintended by node
-    /// currently being visited.
-    /// \param curr_hash Receives the hash for node currently being visited.
-    /// \param parent_diverged True if parent of node currently being visited
-    /// is not in path from root to target node.
-    /// \param curr_diverged True if node currently being visited is
-    /// itself not in path from root to target node.
-    /// \param proof Proof to receive sibling hashes.
-    void get_inside_page_sibling_hashes(hasher_type &h, address_type address, int log2_size, hash_type &hash,
-        const unsigned char *curr_data, int log2_curr_size, hash_type &curr_hash, int parent_diverged,
-        int curr_diverged, proof_type &proof) const;
-
-    /// \brief Gets the sibling hashes along the path from a
-    /// page node towards a target node.
-    /// \param address Address of target node.
-    /// \param log2_size log<sub>2</sub> of size subintended by target node.
-    /// \param hash Receives target node hash.
-    /// \param page_data Pointer to start of contiguous page data.
-    /// \param page_hash Receives the hash for the page.
-    /// \param proof Proof to receive sibling hashes.
-    void get_inside_page_sibling_hashes(address_type address, int log2_size, hash_type &hash,
-        const unsigned char *page_data, hash_type &page_hash, proof_type &proof) const;
-
-    // Precomputed hashes of spans of zero bytes with
-    // increasing power-of-two sizes, from 2^LOG2_WORD_SIZE
-    // to 2^LOG2_ROOT_SIZE bytes.
-    static const pristine_merkle_tree &pristine_hashes();
-
-public:
-    /// \brief Verifies the entire Merkle tree.
-    /// \return True if tree is consistent, false otherwise.
-    bool verify_tree() const;
-
-    /// \brief Default constructor.
-    /// \details Initializes memory to zero.
-    machine_merkle_tree();
-
-    /// \brief No copy constructor
-    machine_merkle_tree(const machine_merkle_tree &) = delete;
-    /// \brief No copy assignment
-    machine_merkle_tree &operator=(const machine_merkle_tree &) = delete;
-    /// \brief No move constructor
-    machine_merkle_tree(machine_merkle_tree &&) = delete;
-    /// \brief No move assignment
-    machine_merkle_tree &operator=(machine_merkle_tree &&) = delete;
-
-    /// \brief Destructor
-    /// \details Releases all used memory
-    ~machine_merkle_tree();
-
-    /// \brief Returns the root hash.
-    /// \param hash Receives the hash.
-    void get_root_hash(hash_type &hash) const;
-
-    /// \brief Start tree update.
-    /// \returns True.
-    /// \details This method is not thread safe, so be careful when using
-    /// parallelization to compute Merkle trees
-    bool begin_update();
-
-    /// \brief Update tree with new hash for a page node.
-    /// \param page_index Page index for node.
-    /// \param hash New hash for node.
-    /// \returns True if succeeded, false otherwise.
-    /// \details This method is not thread safe, so be careful when using
-    /// parallelization to compute Merkle trees
-    bool update_page_node_hash(address_type page_index, const hash_type &hash);
-
-    /// \brief End tree update.
-    /// \param h Hasher object.
-    /// \returns True if succeeded, false otherwise.
-    /// \details This method is not thread safe, so be careful when using
-    /// parallelization to compute Merkle trees
-    bool end_update(hasher_type &h);
-
-    /// \brief Returns the proof for a node in the tree.
-    /// \param target_address Address of target node. Must be aligned
-    /// to a 2<sup>log2_target_size</sup> boundary.
-    /// \param log2_target_size log<sub>2</sub> of size subintended by
-    /// target node. Must be between LOG2_WORD_SIZE and LOG2_ROOT_SIZE,
-    /// inclusive.
-    /// \param page_data When log2_target_size smaller than LOG2_PAGE_SIZE,
-    /// \p page_data must point to start of contiguous page containing
-    /// the node, or nullptr if the page is pristine (i.e., filled with zeros).
-    /// \returns Proof if successful, otherwise throws exception.
-    proof_type get_proof(address_type target_address, int log2_target_size, const unsigned char *page_data) const;
-
-    /// \brief Recursively builds hash for page node from contiguous memory.
-    /// \param h Hasher object.
-    /// \param page_data Pointer to start of contiguous page data.
-    /// \param hash Receives the hash.
-    void get_page_node_hash(hasher_type &h, const unsigned char *page_data, hash_type &hash) const;
-
-    /// \brief Gets currently stored hash for page node.
-    /// \param page_index Page index for node.
-    /// \param hash Receives the hash.
-    void get_page_node_hash(address_type page_index, hash_type &hash) const;
-
-    /// \brief Get the hash of a node in the Merkle tree.
-    /// \param target_address Address of target node.
-    /// \param log2_target_size log2 of the node size.
-    /// \return Hash of the node.
-    hash_type get_node_hash(address_type target_address, int log2_target_size) const;
-
-    /// \brief Returns the hash for a log2_size pristine node.
-    /// \param log2_size log<sub>2</sub> of size subintended by node.
-    /// \return Reference to precomputed hash.
-    static const hash_type &get_pristine_hash(int log2_size);
-};
-
-std::ostream &operator<<(std::ostream &out, const machine_merkle_tree::hash_type &hash);
-
-} // namespace cartesi
-
-#endif
diff --git a/src/machine-runtime-config.h b/src/machine-runtime-config.h
index 649ea4aaf..f89170086 100644
--- a/src/machine-runtime-config.h
+++ b/src/machine-runtime-config.h
@@ -26,7 +26,7 @@ namespace cartesi {
 
 /// \brief Concurrency runtime configuration
 struct concurrency_runtime_config {
-    uint64_t update_merkle_tree{};
+    uint64_t update_hash_tree{};
 };
 
 /// \brief HTIF runtime configuration
diff --git a/src/machine.cpp b/src/machine.cpp
index 8110594fe..86ff4b7ba 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -40,6 +40,7 @@
 #include "compiler-defines.h"
 #include "device-state-access.h"
 #include "dtb.h"
+#include "hash-tree.h"
 #include "host-addr.h"
 #include "hot-tlb.h"
 #include "htif-constants.h"
@@ -48,10 +49,11 @@
 #include "interpret.h"
 #include "is-pristine.h"
 #include "machine-config.h"
+#include "machine-hash.h"
 #include "machine-reg.h"
 #include "machine-runtime-config.h"
-#include "os.h"
-#include "pmas-constants.h"
+#include "merkle-tree-proof.h"
+#include "page-hash-tree-cache.h"
 #include "pmas.h"
 #include "processor-state.h"
 #include "record-send-cmio-state-access.h"
@@ -81,6 +83,11 @@
 
 namespace cartesi {
 
+static_assert(static_cast<int>(AR_LOG2_PAGE_SIZE) == static_cast<int>(LOG2_PAGE_SIZE),
+    "address range page size must match RISC-V page size");
+static_assert(static_cast<int>(AR_LOG2_PAGE_SIZE) == static_cast<int>(HASH_TREE_LOG2_PAGE_SIZE),
+    "address range page size must match hash-tree page size");
+
 using namespace std::string_literals;
 
 void machine::init_uarch_processor(const uarch_processor_config &p) {
@@ -198,7 +205,7 @@ void machine::init_pmas_contents(const pmas_config &config) {
         }
         // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
         auto &dest = *reinterpret_cast<pmas_state *>(pmas.get_host_memory());
-        std::ranges::transform(m_ars.interpret(), dest.begin(),
+        std::ranges::transform(m_ars.pmas_view(), dest.begin(),
             [](const auto &ar) { return pmas_entry{.istart = ar.get_istart(), .ilength = ar.get_ilength()}; });
     }
 }
@@ -257,6 +264,7 @@ machine::machine(machine_config c, machine_runtime_config r) :
     m_c{std::move(c)}, // NOLINT(hicpp-move-const-arg,performance-move-const-arg)
     m_r{std::move(r)}, // NOLINT(hicpp-move-const-arg,performance-move-const-arg)
     m_ars{m_c},
+    m_ht{m_c.hash_tree, m_r.concurrency.update_hash_tree, m_ars},
     m_s{std::bit_cast<processor_state *>(m_ars.find(AR_SHADOW_STATE_START, AR_SHADOW_STATE_LENGTH).get_host_memory())},
     m_us{std::bit_cast<uarch_processor_state *>(
         m_ars.find(AR_SHADOW_UARCH_STATE_START, AR_SHADOW_UARCH_STATE_LENGTH).get_host_memory())} {
@@ -283,12 +291,14 @@ void machine::init_tty() {
     }
 }
 
-static void load_hash(const std::string &dir, machine::hash_type &h) {
+static machine_hash load_hash(const std::string &dir) {
     auto name = dir + "/hash";
     auto fp = make_unique_fopen(name.c_str(), "rb");
+    machine_hash h;
     if (fread(h.data(), 1, h.size(), fp.get()) != h.size()) {
         throw std::runtime_error{"error reading from '" + name + "'"};
     }
+    return h;
 }
 
 // ??D It is best to leave the std::move() on r because it may one day be necessary!
@@ -297,20 +307,13 @@ machine::machine(const std::string &dir, machine_runtime_config r) : machine{mac
     if (m_r.skip_root_hash_check) {
         return;
     }
-    hash_type hstored;
-    hash_type hrestored;
-    load_hash(dir, hstored);
-    if (!update_merkle_tree()) {
-        throw std::runtime_error{"error updating Merkle tree"};
-    }
-    m_t.get_root_hash(hrestored);
-    if (hstored != hrestored) {
+    if (load_hash(dir) != get_root_hash()) {
         throw std::runtime_error{"stored and restored hashes do not match"};
     }
 }
 
 void machine::prepare_virtio_devices_select(select_fd_sets *fds, uint64_t *timeout_us) {
-    for (auto &v : m_ars.virtio()) {
+    for (auto &v : m_ars.virtio_view()) {
         v.prepare_select(fds, timeout_us);
     }
 }
@@ -318,7 +321,7 @@ void machine::prepare_virtio_devices_select(select_fd_sets *fds, uint64_t *timeo
 // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
 bool machine::poll_selected_virtio_devices(int select_ret, select_fd_sets *fds, i_device_state_access *da) {
     bool interrupt_requested = false; // NOLINT(misc-const-correctness)
-    for (auto &v : m_ars.virtio()) {
+    for (auto &v : m_ars.virtio_view()) {
         interrupt_requested |= v.poll_selected(select_ret, fds, da);
     }
     return interrupt_requested;
@@ -333,13 +336,13 @@ bool machine::poll_virtio_devices(uint64_t *timeout_us, i_device_state_access *d
 }
 
 bool machine::has_virtio_devices() const {
-    return !m_ars.virtio().empty();
+    return !m_ars.virtio_view().empty();
 }
 
 bool machine::has_virtio_console() const {
     // When present, the console device is guaranteed to be the first VirtIO device,
     // therefore we only need to check the first device.
-    return has_virtio_devices() && m_ars.virtio().front().get_device_id() == VIRTIO_DEVICE_CONSOLE;
+    return has_virtio_devices() && m_ars.virtio_view().front().get_device_id() == VIRTIO_DEVICE_CONSOLE;
 }
 
 bool machine::has_htif_console() const {
@@ -371,7 +374,7 @@ host_addr machine::get_host_addr(uint64_t paddr, uint64_t pma_index) const {
 
 void machine::mark_dirty_page(uint64_t paddr, uint64_t pma_index) {
     auto &ar = read_pma(pma_index);
-    ar.mark_dirty_page(paddr - ar.get_start());
+    ar.get_dirty_page_tree().mark_dirty_page_and_up(paddr - ar.get_start());
 }
 
 void machine::mark_dirty_page(host_addr haddr, uint64_t pma_index) {
@@ -429,7 +432,7 @@ host_addr machine::get_hp_offset(uint64_t pma_index) const {
     return paddr - haddr;
 }
 
-static void store_hash(const machine::hash_type &h, const std::string &dir) {
+static void store_hash(const machine_hash &h, const std::string &dir) {
     auto name = dir + "/hash";
     auto fp = make_unique_fopen(name.c_str(), "wb");
     if (fwrite(h.data(), 1, h.size(), fp.get()) != h.size()) {
@@ -458,7 +461,7 @@ void machine::store_address_range(const address_range &ar, const std::string &di
     auto name = machine_config::get_data_filename(dir, ar.get_start(), ar.get_length());
     auto fp = make_unique_fopen(name.c_str(), "wb"); // will throw if it fails
     if (!ar.is_memory() || ar.get_host_memory() == nullptr) {
-        throw std::runtime_error{"attempt to store non memory address range "s.append(ar.get_description())};
+        throw std::runtime_error{"attempt to store non-memory address range "s.append(ar.get_description())};
     }
     if (fwrite(ar.get_host_memory(), 1, ar.get_length(), fp.get()) != ar.get_length()) {
         throw std::runtime_error{"error writing to '" + name + "'"};
@@ -473,12 +476,7 @@ void machine::store(const std::string &dir) const {
         throw std::system_error{errno, std::generic_category(), "error creating directory '"s + dir + "'"s};
     }
     if (!m_r.skip_root_hash_store) {
-        if (!update_merkle_tree()) {
-            throw std::runtime_error{"error updating Merkle tree"};
-        }
-        hash_type h;
-        m_t.get_root_hash(h);
-        store_hash(h, dir);
+        store_hash(get_root_hash(), dir);
     }
     machine_config c = m_c;
     c.adjust_backing_stores(".");
@@ -1334,192 +1332,30 @@ void machine::mark_write_tlb_dirty_pages() const {
             if (!ar.contains_absolute(paddr_page, AR_PAGE_SIZE)) {
                 throw std::runtime_error{"could not mark dirty page for a TLB entry: TLB is corrupt"};
             }
-            ar.mark_dirty_page(paddr_page - ar.get_start());
+            ar.get_dirty_page_tree().mark_dirty_page_and_up(paddr_page - ar.get_start());
         }
     }
 }
 
-bool machine::verify_dirty_page_maps() const {
-    static_assert(AR_PAGE_SIZE == machine_merkle_tree::get_page_size(),
-        "PMA and machine_merkle_tree page sizes must match");
-    machine_merkle_tree::hasher_type h;
-    auto scratch = make_unique_calloc<unsigned char>(AR_PAGE_SIZE, std::nothrow_t{});
-    if (!scratch) {
-        return false;
-    }
-    bool broken = false;
-    // Go over the write TLB and mark as dirty all pages currently there
+bool machine::update_hash_tree() const {
     mark_write_tlb_dirty_pages();
-    // Now go over all memory PMAs verifying that all dirty pages are marked
-    for (const auto &ar : m_ars.all()) {
-        for (uint64_t page_address = ar.get_start(); page_address < ar.get_end(); page_address += AR_PAGE_SIZE) {
-            const auto offset = page_address - ar.get_start();
-            if (ar.is_memory()) {
-                const unsigned char *page_data = nullptr;
-                ar.peek(*this, offset, AR_PAGE_SIZE, &page_data, scratch.get());
-                hash_type stored;
-                hash_type real;
-                m_t.get_page_node_hash(page_address, stored);
-                m_t.get_page_node_hash(h, page_data, real);
-                const bool marked_dirty = ar.is_page_marked_dirty(offset);
-                const bool is_dirty = (real != stored);
-                if (is_dirty && !marked_dirty) {
-                    broken = true;
-                    std::cerr << std::setfill('0') << std::setw(8) << std::hex << page_address
-                              << " should have been dirty\n";
-                    std::cerr << "  expected " << stored << '\n';
-                    std::cerr << "  got " << real << '\n';
-                    break;
-                }
-            } else if (ar.is_device()) {
-                if (!ar.is_page_marked_dirty(offset)) {
-                    broken = true;
-                    std::cerr << std::setfill('0') << std::setw(8) << std::hex << page_address
-                              << " should have been dirty\n";
-                    std::cerr << "  all pages in IO PMAs must be set to dirty\n";
-                    break;
-                }
-            }
-        }
-    }
-    return !broken;
+    m_ars.mark_always_dirty_pages();
+    return m_ht.update(m_ars);
 }
 
-static uint64_t get_task_concurrency(uint64_t value) {
-    const uint64_t concurrency = value > 0 ? value : std::max(os_get_concurrency(), UINT64_C(1));
-    return std::min(concurrency, static_cast<uint64_t>(THREADS_MAX));
+bool machine::update_hash_tree_page(uint64_t address) {
+    return m_ht.update_page(m_ars, address);
 }
 
-bool machine::update_merkle_tree() const {
-    machine_merkle_tree::hasher_type gh;
-    static_assert(AR_PAGE_SIZE == machine_merkle_tree::get_page_size(),
-        "PMA and machine_merkle_tree page sizes must match");
-    // Go over the write TLB and mark as dirty all pages currently there
-    mark_write_tlb_dirty_pages();
-    // Now go over all PMAs and updating the Merkle tree
-    m_t.begin_update();
-    for (auto &ar : m_ars.merkle()) {
-        // Each PMA has a number of pages
-        auto pages_in_range = (ar.get_length() + AR_PAGE_SIZE - 1) / AR_PAGE_SIZE;
-        // For each PMA, we launch as many threads (n) as defined on concurrency
-        // runtime config or as the hardware supports.
-        const uint64_t n = get_task_concurrency(m_r.concurrency.update_merkle_tree);
-        const bool succeeded = os_parallel_for(n, [&](int j, const parallel_for_mutex &mutex) -> bool {
-            auto scratch = make_unique_calloc<unsigned char>(AR_PAGE_SIZE, std::nothrow_t{});
-            if (!scratch) {
-                return false;
-            }
-            machine_merkle_tree::hasher_type h;
-            // Thread j is responsible for page i if i % n == j.
-            for (uint64_t i = j; i < pages_in_range; i += n) {
-                const uint64_t page_start_in_range = i * AR_PAGE_SIZE;
-                const uint64_t page_address = ar.get_start() + page_start_in_range;
-                const unsigned char *page_data = nullptr;
-                // Skip any clean pages
-                if (!ar.is_page_marked_dirty(page_start_in_range)) {
-                    continue;
-                }
-                // If the peek failed, or if it returned a page for update but
-                // we failed updating it, the entire process failed
-                if (!ar.peek(*this, page_start_in_range, AR_PAGE_SIZE, &page_data, scratch.get())) {
-                    return false;
-                }
-                if (page_data != nullptr) {
-                    if (is_pristine(page_data, AR_PAGE_SIZE)) {
-                        // The update_page_node_hash function in the machine_merkle_tree is not thread
-                        // safe, so we protect it with a mutex
-                        const parallel_for_mutex_guard lock(mutex);
-                        if (!m_t.update_page_node_hash(page_address,
-                                machine_merkle_tree::get_pristine_hash(machine_merkle_tree::get_log2_page_size()))) {
-                            return false;
-                        }
-                    } else {
-                        hash_type hash;
-                        m_t.get_page_node_hash(h, page_data, hash);
-                        {
-                            // The update_page_node_hash function in the machine_merkle_tree is not thread
-                            // safe, so we protect it with a mutex
-                            const parallel_for_mutex_guard lock(mutex);
-                            if (!m_t.update_page_node_hash(page_address, hash)) {
-                                return false;
-                            }
-                        }
-                    }
-                }
-            }
-            return true;
-        });
-        // If any thread failed, we also failed
-        if (!succeeded) {
-            m_t.end_update(gh);
-            return false;
-        }
-        // Otherwise, mark all pages in PMA as clean and move on to next
-        ar.mark_pages_clean();
-    }
-    const bool ret = m_t.end_update(gh);
-    return ret;
-}
-
-bool machine::update_merkle_tree_page(uint64_t address) {
-    static_assert(AR_PAGE_SIZE == machine_merkle_tree::get_page_size(),
-        "PMA and machine_merkle_tree page sizes must match");
-    // Align address to beginning of page
-    address &= ~(AR_PAGE_SIZE - 1);
-    auto &ar = m_ars.find<uint8_t>(address);
-    const uint64_t page_start_in_range = address - ar.get_start();
-    machine_merkle_tree::hasher_type h;
-    auto scratch = make_unique_calloc<unsigned char>(AR_PAGE_SIZE, std::nothrow_t{});
-    if (!scratch) {
-        return false;
-    }
-    m_t.begin_update();
-    const unsigned char *page_data = nullptr;
-    if (!ar.peek(*this, page_start_in_range, AR_PAGE_SIZE, &page_data, scratch.get())) {
-        m_t.end_update(h);
-        return false;
-    }
-    if (page_data != nullptr) {
-        const uint64_t page_address = ar.get_start() + page_start_in_range;
-        hash_type hash;
-        m_t.get_page_node_hash(h, page_data, hash);
-        if (!m_t.update_page_node_hash(page_address, hash)) {
-            m_t.end_update(h);
-            return false;
-        }
+machine_hash machine::get_root_hash() const {
+    if (!update_hash_tree()) {
+        throw std::runtime_error{"update hash-tree failed"};
     }
-    ar.mark_clean_page(page_start_in_range);
-    return m_t.end_update(h);
+    return m_ht.get_root_hash();
 }
 
-void machine::get_root_hash(hash_type &hash) const {
-    if (read_reg(reg::iunrep) != 0) {
-        throw std::runtime_error("cannot compute root hash of unreproducible machines");
-    }
-    if (!update_merkle_tree()) {
-        throw std::runtime_error{"error updating Merkle tree"};
-    }
-    m_t.get_root_hash(hash);
-}
-
-machine::hash_type machine::get_merkle_tree_node_hash(uint64_t address, int log2_size,
-    skip_merkle_tree_update_t /* unused */) const {
-    if (log2_size < 0 || log2_size >= machine_merkle_tree::get_log2_root_size()) {
-        throw std::domain_error{"log2_size is out of bounds"};
-    }
-    if (log2_size >= machine_merkle_tree::get_log2_page_size()) {
-        return m_t.get_node_hash(address, log2_size);
-    }
-    if ((address >> log2_size) << log2_size != address) {
-        throw std::domain_error{"address not aligned to log2_size"};
-    }
-    const auto size = UINT64_C(1) << log2_size;
-    auto scratch = make_unique_calloc<unsigned char>(size);
-    read_memory(address, scratch.get(), size);
-    machine_merkle_tree::hasher_type h;
-    machine_merkle_tree::hash_type hash;
-    get_merkle_tree_hash(h, scratch.get(), size, machine_merkle_tree::get_word_size(), hash);
-    return hash;
+machine_hash machine::get_node_hash(uint64_t address, int log2_size, skip_hash_tree_update_t /* unused */) const {
+    return m_ht.get_node_hash(m_ars, address, log2_size);
 }
 
 const char *machine::get_what_name(uint64_t paddr) {
@@ -1544,61 +1380,28 @@ const char *machine::get_what_name(uint64_t paddr) {
     return "memory";
 }
 
-machine::hash_type machine::get_merkle_tree_node_hash(uint64_t address, int log2_size) const {
-    if (!update_merkle_tree()) {
-        throw std::runtime_error{"error updating Merkle tree"};
-    }
-    return get_merkle_tree_node_hash(address, log2_size, skip_merkle_tree_update);
-}
-
-bool machine::verify_merkle_tree() const {
-    return m_t.verify_tree();
-}
-
-machine_merkle_tree::proof_type machine::get_proof(uint64_t address, int log2_size,
-    skip_merkle_tree_update_t /*unused*/) const {
-    static_assert(AR_PAGE_SIZE == machine_merkle_tree::get_page_size(),
-        "PMA and machine_merkle_tree page sizes must match");
-    // Check for valid target node size
-    if (log2_size > machine_merkle_tree::get_log2_root_size() ||
-        log2_size < machine_merkle_tree::get_log2_word_size()) {
-        throw std::invalid_argument{"invalid log2_size"};
-    }
-    // Check target address alignment
-    if ((address & ((~UINT64_C(0)) >> (64 - log2_size))) != 0) {
-        throw std::domain_error{"address not aligned to log2_size"};
-    }
-    // If proof concerns range smaller than a page, we may need to rebuild part of the proof from
-    // the contents of a page inside some PMA range.
-    // PMA range starts and lengths are multiple of the page size, which is a power of 2.
-    // The size of the desired range is smaller than the page size, but its size is a power of 2,
-    // and it is aligned to its size.
-    // Therefore, it is is either entirely inside a PMA range, or entirely outside it.
-    if (log2_size < machine_merkle_tree::get_log2_page_size()) {
-        const uint64_t length = UINT64_C(1) << log2_size;
-        const auto &ar = m_ars.find(address, length);
-        auto scratch = make_unique_calloc<unsigned char>(AR_PAGE_SIZE);
-        const unsigned char *page_data = nullptr;
-        // If the PMA range is empty, we know the desired range is entirely outside of any non-pristine PMA.
-        // Therefore, the entire page where it lies is also pristine.
-        // Otherwise, the entire desired range is inside it.
-        if (!ar.is_empty()) {
-            const uint64_t page_start_in_range = (address - ar.get_start()) & (~(AR_PAGE_SIZE - 1));
-            if (!ar.peek(*this, page_start_in_range, AR_PAGE_SIZE, &page_data, scratch.get())) {
-                throw std::runtime_error{"PMA peek failed"};
-            }
-        }
-        return m_t.get_proof(address, log2_size, page_data);
-        // If proof concerns range bigger than a page, we already have its hash stored in the tree itself
+machine_hash machine::get_node_hash(uint64_t address, int log2_size) const {
+    if (!update_hash_tree()) {
+        throw std::runtime_error{"update hash-tree failed"};
     }
-    return m_t.get_proof(address, log2_size, nullptr);
+    return get_node_hash(address, log2_size, skip_hash_tree_update);
+}
+
+bool machine::verify_hash_tree() const {
+    mark_write_tlb_dirty_pages();
+    m_ars.mark_always_dirty_pages();
+    return m_ht.verify(m_ars);
+}
+
+machine::proof_type machine::get_proof(uint64_t address, int log2_size, skip_hash_tree_update_t /*unused*/) const {
+    return m_ht.get_proof(m_ars, address, log2_size);
 }
 
-machine_merkle_tree::proof_type machine::get_proof(uint64_t address, int log2_size) const {
-    if (!update_merkle_tree()) {
-        throw std::runtime_error{"error updating Merkle tree"};
+machine::proof_type machine::get_proof(uint64_t address, int log2_size) const {
+    if (!update_hash_tree()) {
+        throw std::runtime_error{"update hash-tree failed"};
     }
-    return get_proof(address, log2_size, skip_merkle_tree_update);
+    return get_proof(address, log2_size, skip_hash_tree_update);
 }
 
 template <typename F>
@@ -1622,6 +1425,24 @@ static inline void foreach_aligned_chunk(uint64_t start, uint64_t length, uint64
     }
 }
 
+//??D I think we should have something like this in the address_range interface
+//??D Something that combines a check with contains and returns an optional view
+static std::optional<std::span<const unsigned char>> ar_host_memory_view(const address_range &ar, uint64_t offset,
+    uint64_t length) {
+    if (!ar.contains_relative(offset, length)) {
+        throw std::logic_error{"invalid access to address range "s.append(ar.get_description())};
+    }
+    if (ar.is_memory()) {
+        if (ar.get_host_memory() == nullptr) {
+            throw std::runtime_error{
+                "memory address range "s.append(ar.get_description()).append("has no host memory")};
+        }
+        return std::span<const unsigned char>{ar.get_host_memory() + offset, length};
+    }
+    return {};
+}
+
+//??D change this to use a span, or perhaps a contiguous_range of byte-like elements
 void machine::read_memory(uint64_t paddr, unsigned char *data, uint64_t length) const {
     if (length == 0) {
         return;
@@ -1630,7 +1451,7 @@ void machine::read_memory(uint64_t paddr, unsigned char *data, uint64_t length)
         throw std::invalid_argument{"invalid data buffer"};
     }
     uint64_t gap_start = 0;
-    auto view = m_ars.merkle() |
+    auto view = m_ars.hash_tree_view() |
         std::views::drop_while([paddr, &gap_start](const address_range &ar) { // Only those that end after paddr
             const auto ar_end = ar.get_end();
             if (paddr >= ar_end) {
@@ -1639,7 +1460,7 @@ void machine::read_memory(uint64_t paddr, unsigned char *data, uint64_t length)
             }
             return false;
         });
-    for (auto &ar : view) {
+    for (const auto &ar : view) {
         const auto ar_start = ar.get_start();
         // Write as much as possible from pristine gap between last address range and current address range
         if (paddr >= gap_start && paddr < ar_start) {
@@ -1653,18 +1474,13 @@ void machine::read_memory(uint64_t paddr, unsigned char *data, uint64_t length)
         // Write as much as possible from current address range
         if (paddr >= ar_start && paddr < gap_start) {
             const auto from_ar = std::min(gap_start - paddr, length);
-            const unsigned char *peek_data = nullptr;
-            if (!ar.peek(*this, paddr - ar_start, from_ar, &peek_data, data)) {
-                throw std::runtime_error{"peek failed"};
+            auto data_view = std::span<unsigned char>{data, from_ar};
+            auto ar_view = ar_host_memory_view(ar, paddr - ar_start, from_ar);
+            if (ar_view) {
+                std::ranges::copy(*ar_view, data_view.begin());
+            } else {
+                std::ranges::fill(data_view, 0);
             }
-            if (peek_data == nullptr) {
-                // If the chunk is pristine, copy zero data to buffer
-                memset(data, 0, from_ar);
-            } else if (peek_data != data) {
-                // If peek returned pointer to internal buffer, copy to data buffer
-                memcpy(data, peek_data, from_ar);
-            }
-            // Otherwise, peek already copied to data buffer
             length -= from_ar;
             if (length == 0) {
                 return;
@@ -1679,6 +1495,7 @@ void machine::read_memory(uint64_t paddr, unsigned char *data, uint64_t length)
     }
 }
 
+//??D change this to use a span, or perhaps a contiguous_range of byte-like elements
 void machine::write_memory(uint64_t paddr, const unsigned char *data, uint64_t length) {
     if (length == 0) {
         return;
@@ -1687,15 +1504,20 @@ void machine::write_memory(uint64_t paddr, const unsigned char *data, uint64_t l
         throw std::invalid_argument{"invalid data buffer"};
     }
     auto &ar = m_ars.find(paddr, length);
+    const auto *ar_descr = ar.get_description();
     if (ar.is_device()) {
-        throw std::invalid_argument{"attempted write to device memory range"};
+        throw std::invalid_argument{"attempted write to device memory range "s.append(ar_descr)};
     }
     if (!ar.is_memory()) {
-        throw std::invalid_argument{"address range to write is not entirely in single memory range"};
+        throw std::invalid_argument{"attempted write is not entirely within single memory range"};
     }
     if (ar.is_host_read_only()) {
-        throw std::invalid_argument{"address range to write is read-only in the host"};
+        throw std::invalid_argument{"attempted write to host-read-only memory range "s.append(ar_descr)};
+    }
+    if (pmas_is_protected(ar.get_driver_id())) {
+        throw std::invalid_argument{"attempted write to protected memory range "s.append(ar_descr)};
     }
+    //??D In C++23, change this to use std::span and std::views::chunk std::views::drop/take and std::views::chain
     foreach_aligned_chunk(paddr, length, AR_PAGE_SIZE, [&ar, paddr, data](auto chunk_start, auto chunk_length) {
         const auto *src = data + (chunk_start - paddr);
         const auto offset = chunk_start - ar.get_start();
@@ -1703,13 +1525,9 @@ void machine::write_memory(uint64_t paddr, const unsigned char *data, uint64_t l
         if (memcmp(dest, src, chunk_length) != 0) {
             // Page is different, we have to copy memory
             memcpy(dest, src, chunk_length);
-            ar.mark_dirty_page(offset);
+            ar.get_dirty_page_tree().mark_dirty_page_and_up(offset);
         }
     });
-    if (pmas_range_overlaps(paddr, length, AR_SHADOW_TLB_START, AR_SHADOW_TLB_LENGTH)) {
-        // Must reinitialize hot TLB again to reflect changes in the shadow TLB
-        init_hot_tlb_contents();
-    }
 }
 
 void machine::fill_memory(uint64_t paddr, uint8_t val, uint64_t length) {
@@ -1717,27 +1535,27 @@ void machine::fill_memory(uint64_t paddr, uint8_t val, uint64_t length) {
         return;
     }
     auto &ar = m_ars.find(paddr, length);
+    const auto *ar_descr = ar.get_description();
     if (ar.is_device()) {
-        throw std::invalid_argument{"attempted fill to device memory range"};
+        throw std::invalid_argument{"attempted fill to device memory range "s.append(ar_descr)};
     }
     if (!ar.is_memory()) {
-        throw std::invalid_argument{"address range to fill is not entirely in memory PMA"};
+        throw std::invalid_argument{"attempted fill is not entirely within single memory range"};
     }
     if (ar.is_host_read_only()) {
-        throw std::invalid_argument{"address range is read-only in the host"};
+        throw std::invalid_argument{"attempted fill to host-read-only memory range "s.append(ar_descr)};
     }
-    if (pmas_range_overlaps(paddr, length, AR_SHADOW_TLB_START, AR_SHADOW_TLB_LENGTH)) {
-        // Filling shadow TLB memory doesn't make sense because it would leave
-        // its state corrupted in most situations.
-        throw std::invalid_argument{"attempted fill to shadow TLB memory range"};
+    if (pmas_is_protected(ar.get_driver_id())) {
+        throw std::invalid_argument{"attempted fill to protected memory range "s.append(ar_descr)};
     }
     // The case of filling a range with zeros is special and optimized for uarch reset
+    //??D In C++23, change this to use std::span and std::views::chunk std::views::drop/take and std::views::chain
     foreach_aligned_chunk(paddr, length, AR_PAGE_SIZE, [&ar, val](auto chunk_start, auto chunk_length) {
         const auto offset = chunk_start - ar.get_start();
         const auto dest = ar.get_host_memory() + offset;
         if (val != 0 || !is_pristine(dest, chunk_length)) {
             memset(dest, val, chunk_length);
-            ar.mark_dirty_page(offset);
+            ar.get_dirty_page_tree().mark_dirty_page_and_up(offset);
         }
     });
 }
@@ -1852,7 +1670,7 @@ void machine::write_word(uint64_t paddr, uint64_t val) {
     }
     const auto offset = paddr - ar.get_start();
     aliased_aligned_write<uint64_t>(ar.get_host_memory() + offset, val);
-    ar.mark_dirty_page(offset);
+    ar.get_dirty_page_tree().mark_dirty_page_and_up(offset);
 }
 
 void machine::send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length) {
@@ -1862,8 +1680,7 @@ void machine::send_cmio_response(uint16_t reason, const unsigned char *data, uin
 
 access_log machine::log_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
     const access_log::type &log_type) {
-    hash_type root_hash_before;
-    get_root_hash(root_hash_before);
+    auto root_hash_before = get_root_hash();
     access_log log(log_type);
     // Call send_cmio_response  with the recording state accessor
     const record_send_cmio_state_access a(*this, log);
@@ -1872,23 +1689,23 @@ access_log machine::log_send_cmio_response(uint16_t reason, const unsigned char
         cartesi::send_cmio_response(a, reason, data, length);
     }
     // Verify access log before returning
-    hash_type root_hash_after;
-    update_merkle_tree();
-    get_root_hash(root_hash_after);
+    if (!update_hash_tree()) {
+        throw std::runtime_error{"update hash-tree failed"};
+    }
+    auto root_hash_after = get_root_hash();
     verify_send_cmio_response(reason, data, length, root_hash_before, log, root_hash_after);
     return log;
 }
 
 void machine::verify_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
-    const hash_type &root_hash_before, const access_log &log, const hash_type &root_hash_after) {
+    const machine_hash &root_hash_before, const access_log &log, const machine_hash &root_hash_after) {
     replay_send_cmio_state_access::context context(log, root_hash_before);
     // Verify all intermediate state transitions
     replay_send_cmio_state_access a(context);
     cartesi::send_cmio_response(a, reason, data, length);
     a.finish();
     // Make sure the access log ends at the same root hash as the state
-    hash_type obtained_root_hash;
-    a.get_root_hash(obtained_root_hash);
+    auto obtained_root_hash = a.get_root_hash();
     if (obtained_root_hash != root_hash_after) {
         throw std::invalid_argument{"mismatch in root hash after replay"};
     }
@@ -1910,8 +1727,7 @@ void machine::reset_uarch() {
 }
 
 access_log machine::log_reset_uarch(const access_log::type &log_type) {
-    hash_type root_hash_before;
-    get_root_hash(root_hash_before);
+    const machine_hash root_hash_before = get_root_hash();
     // Call uarch_reset_state with a uarch_record_state_access object
     access_log log(log_type);
     uarch_record_state_access a(*this, log);
@@ -1920,23 +1736,23 @@ access_log machine::log_reset_uarch(const access_log::type &log_type) {
         uarch_reset_state(a);
     }
     // Verify access log before returning
-    hash_type root_hash_after;
-    update_merkle_tree();
-    get_root_hash(root_hash_after);
+    if (!update_hash_tree()) {
+        throw std::runtime_error{"update hash-tree failed"};
+    }
+    const auto root_hash_after = get_root_hash();
     verify_reset_uarch(root_hash_before, log, root_hash_after);
     return log;
 }
 
-void machine::verify_reset_uarch(const hash_type &root_hash_before, const access_log &log,
-    const hash_type &root_hash_after) {
+void machine::verify_reset_uarch(const machine_hash &root_hash_before, const access_log &log,
+    const machine_hash &root_hash_after) {
     // Verify all intermediate state transitions
     uarch_replay_state_access::context context{log, root_hash_before};
     uarch_replay_state_access a(context);
     uarch_reset_state(a);
     a.finish();
     // Make sure the access log ends at the same root hash as the state
-    hash_type obtained_root_hash;
-    a.get_root_hash(obtained_root_hash);
+    const machine_hash obtained_root_hash = a.get_root_hash();
     if (obtained_root_hash != root_hash_after) {
         throw std::invalid_argument{"mismatch in root hash after replay"};
     }
@@ -1949,8 +1765,7 @@ access_log machine::log_step_uarch(const access_log::type &log_type) {
     if (read_reg(reg::iunrep) != 0) {
         throw std::runtime_error("microarchitecture cannot be used with unreproducible machines");
     }
-    hash_type root_hash_before;
-    get_root_hash(root_hash_before);
+    auto root_hash_before = get_root_hash();
     access_log log(log_type);
     // Call interpret with a logged state access object
     const uarch_record_state_access a(*this, log);
@@ -1959,8 +1774,7 @@ access_log machine::log_step_uarch(const access_log::type &log_type) {
         uarch_step(a);
     }
     // Verify access log before returning
-    hash_type root_hash_after;
-    get_root_hash(root_hash_after);
+    auto root_hash_after = get_root_hash();
     os_silence_putchar(m_r.htif.no_console_putchar);
     verify_step_uarch(root_hash_before, log, root_hash_after);
     return log;
@@ -1969,16 +1783,15 @@ access_log machine::log_step_uarch(const access_log::type &log_type) {
 // Declaration of explicit instantiation in module uarch-step.cpp
 extern template UArchStepStatus uarch_step(uarch_replay_state_access &a);
 
-void machine::verify_step_uarch(const hash_type &root_hash_before, const access_log &log,
-    const hash_type &root_hash_after) {
+void machine::verify_step_uarch(const machine_hash &root_hash_before, const access_log &log,
+    const machine_hash &root_hash_after) {
     // Verify all intermediate state transitions
     uarch_replay_state_access::context context{log, root_hash_before};
     uarch_replay_state_access a(context);
     uarch_step(a);
     a.finish();
     // Make sure the access log ends at the same root hash as the state
-    hash_type obtained_root_hash;
-    a.get_root_hash(obtained_root_hash);
+    auto obtained_root_hash = a.get_root_hash();
     if (obtained_root_hash != root_hash_after) {
         throw std::invalid_argument{"mismatch in root hash after replay"};
     }
@@ -1999,18 +1812,16 @@ uarch_interpreter_break_reason machine::run_uarch(uint64_t uarch_cycle_end) {
 }
 
 interpreter_break_reason machine::log_step(uint64_t mcycle_count, const std::string &filename) {
-    if (!update_merkle_tree()) {
-        throw std::runtime_error{"error updating Merkle tree"};
+    if (!update_hash_tree()) {
+        throw std::runtime_error{"update hash-tree failed"};
     }
     // Ensure that the microarchitecture is reset
     auto current_uarch_state_hash =
-        get_merkle_tree_node_hash(AR_SHADOW_UARCH_STATE_START, UARCH_STATE_LOG2_SIZE, skip_merkle_tree_update);
+        get_node_hash(AR_SHADOW_UARCH_STATE_START, UARCH_STATE_LOG2_SIZE, skip_hash_tree_update);
     if (current_uarch_state_hash != get_uarch_pristine_state_hash()) {
-        get_merkle_tree_node_hash(AR_SHADOW_UARCH_STATE_START, UARCH_STATE_LOG2_SIZE, skip_merkle_tree_update);
         throw std::runtime_error{"microarchitecture is not reset"};
     }
-    hash_type root_hash_before;
-    get_root_hash(root_hash_before);
+    auto root_hash_before = get_root_hash();
     record_step_state_access::context context(filename);
     record_step_state_access a(context, *this);
     uint64_t mcycle_end{};
@@ -2019,15 +1830,14 @@ interpreter_break_reason machine::log_step(uint64_t mcycle_count, const std::str
     }
     auto break_reason = interpret(a, mcycle_end);
     a.finish();
-    hash_type root_hash_after;
-    get_root_hash(root_hash_after);
+    auto root_hash_after = get_root_hash();
     os_silence_putchar(m_r.htif.no_console_putchar);
     verify_step(root_hash_before, filename, mcycle_count, root_hash_after);
     return break_reason;
 }
 
-interpreter_break_reason machine::verify_step(const hash_type &root_hash_before, const std::string &filename,
-    uint64_t mcycle_count, const hash_type &root_hash_after) {
+interpreter_break_reason machine::verify_step(const machine_hash &root_hash_before, const std::string &filename,
+    uint64_t mcycle_count, const machine_hash &root_hash_after) {
     auto data_length = os_get_file_length(filename.c_str(), "step log file");
     auto data = make_unique_mmap<unsigned char>(data_length, os_mmap_flags{}, filename, data_length);
     replay_step_state_access::context context;
diff --git a/src/machine.h b/src/machine.h
index 0b67a6b0d..4f89daa81 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -31,12 +31,12 @@
 #include "access-log.h"
 #include "address-range-description.h"
 #include "address-range.h"
+#include "hash-tree.h"
 #include "host-addr.h"
 #include "i-device-state-access.h"
 #include "interpret.h"
 #include "machine-address-ranges.h"
 #include "machine-config.h"
-#include "machine-merkle-tree.h"
 #include "machine-reg.h"
 #include "machine-runtime-config.h"
 #include "os.h"
@@ -49,13 +49,13 @@
 
 namespace cartesi {
 
-/// \brief Tag type used to indicate that merkle tree updates should be skipped.
-struct skip_merkle_tree_update_t {
-    explicit skip_merkle_tree_update_t() = default;
+/// \brief Tag type used to indicate that hash-tree updates should be skipped.
+struct skip_hash_tree_update_t {
+    explicit skip_hash_tree_update_t() = default;
 };
 
-/// \brief Tag indicating that merkle tree updates should be skipped.
-constexpr skip_merkle_tree_update_t skip_merkle_tree_update;
+/// \brief Tag indicating that hash-tree updates should be skipped.
+constexpr skip_hash_tree_update_t skip_hash_tree_update;
 
 /// \class machine
 /// \brief Cartesi Machine implementation
@@ -64,7 +64,7 @@ class machine final {
     machine_config m_c;                   ///< Copy of initialization config
     machine_runtime_config m_r;           ///< Copy of initialization runtime config
     mutable machine_address_ranges m_ars; ///< Address ranges
-    mutable machine_merkle_tree m_t;      ///< Merkle tree of state
+    mutable hash_tree m_ht;               ///< Top level hash tree
     processor_state *m_s;                 ///< Big machine processor state
     uarch_processor_state *m_us;          ///< Microarchitecture processor state
 
@@ -135,8 +135,8 @@ class machine final {
     bool has_htif_console() const;
 
 public:
-    /// \brief Type of hash
-    using hash_type = machine_merkle_tree::hash_type;
+    /// \brief Type of hash and proof
+    using proof_type = hash_tree::proof_type;
 
     using reg = machine_reg;
 
@@ -195,8 +195,8 @@ class machine final {
     /// \param log_filename Name of the file containing the log.
     /// \param mcycle_count Number of mcycles the machine was run for.
     /// \param root_hash_after Hash of the state after the step.
-    static interpreter_break_reason verify_step(const hash_type &root_hash_before, const std::string &log_filename,
-        uint64_t mcycle_count, const hash_type &root_hash_after);
+    static interpreter_break_reason verify_step(const machine_hash &root_hash_before, const std::string &log_filename,
+        uint64_t mcycle_count, const machine_hash &root_hash_after);
 
     /// \brief Runs the machine in the microarchitecture until the mcycles advances by one unit or the micro cycle
     /// counter (uarch_cycle) reaches uarch_cycle_end
@@ -221,22 +221,22 @@ class machine final {
     /// \param root_hash_before State hash before step.
     /// \param log Step state access log.
     /// \param root_hash_after State hash after step.
-    static void verify_step_uarch(const hash_type &root_hash_before, const access_log &log,
-        const hash_type &root_hash_after);
+    static void verify_step_uarch(const machine_hash &root_hash_before, const access_log &log,
+        const machine_hash &root_hash_after);
 
     /// \brief Checks the validity of a state transition caused by log_reset_uarch.
     /// \param root_hash_before State hash before uarch reset
     /// \param log Step state access log.
     /// \param root_hash_after State hash after uarch reset.
-    static void verify_reset_uarch(const hash_type &root_hash_before, const access_log &log,
-        const hash_type &root_hash_after);
+    static void verify_reset_uarch(const machine_hash &root_hash_before, const access_log &log,
+        const machine_hash &root_hash_after);
 
     /// \brief Returns copy of default machine config
     static machine_config get_default_config();
 
     /// \brief Returns a list of descriptions for all PMA entries registered in the machine, sorted by start
-    const address_range_descriptions &get_address_ranges() const {
-        return m_ars.descriptions();
+    const auto &get_address_ranges() const {
+        return m_ars.descriptions_view();
     }
 
     /// \brief Returns machine state for direct access.
@@ -289,25 +289,25 @@ class machine final {
     /// \returns True if an interrupt was requested, false otherwise.
     bool poll_virtio_devices(uint64_t *timeout_us, i_device_state_access *da);
 
-    /// \brief Update the Merkle tree so it matches the contents of the machine state.
-    /// \returns true if succeeded, false otherwise.
-    bool update_merkle_tree() const;
+    /// \brief Update the hash-tree so it matches the contents of the machine state.
+    /// \returns True if successful, false otherwise.
+    bool update_hash_tree() const;
 
-    /// \brief Update the Merkle tree after a page has been modified in the machine state.
+    /// \brief Update a single page in the hash-tree after it is modified in the machine state.
     /// \param address Any address inside modified page.
     /// \returns true if succeeded, false otherwise.
-    bool update_merkle_tree_page(uint64_t address);
+    bool update_hash_tree_page(uint64_t address);
 
-    /// \brief Obtains the proof for a node in the Merkle tree.
+    /// \brief Obtains the proof for a node in the hash-tree.
     /// \param address Address of target node. Must be aligned to a 2<sup>log2_size</sup> boundary.
     /// \param log2_size log<sub>2</sub> of size subintended by target node.
     /// Must be between 3 (for a word) and 64 (for the entire address space), inclusive.
     /// \param proof Receives the proof.
     /// \details If the node is
     /// smaller than a page size, then it must lie entirely inside the same PMA range.
-    machine_merkle_tree::proof_type get_proof(uint64_t address, int log2_size) const;
+    proof_type get_proof(uint64_t address, int log2_size) const;
 
-    /// \brief Obtains the proof for a node in the Merkle tree without making any modifications to the tree.
+    /// \brief Obtains the proof for a node in the hash-tree without making any modifications to the tree.
     /// \param address Address of target node. Must be aligned to a 2<sup>log2_size</sup> boundary.
     /// \param log2_size log<sub>2</sub> of size subintended by target node.
     /// Must be between 3 (for a word) and 64 (for the entire address space), inclusive.
@@ -315,28 +315,27 @@ class machine final {
     /// \details If the node is smaller than a page size, then it must lie entirely inside the same PMA range.
     /// This overload is used to optimize proof generation when the caller knows that the tree is already up to
     /// date.
-    machine_merkle_tree::proof_type get_proof(uint64_t address, int log2_size,
-        skip_merkle_tree_update_t /*unused*/) const;
+    proof_type get_proof(uint64_t address, int log2_size, skip_hash_tree_update_t /*unused*/) const;
 
-    /// \brief Obtains the root hash of the Merkle tree.
-    /// \param hash Receives the hash.
-    void get_root_hash(hash_type &hash) const;
+    /// \brief Obtains the root hash of the hash-tree.
+    /// \returns The hash.
+    machine_hash get_root_hash() const;
 
-    /// \brief Obtains the hash of a node in the Merkle tree.
+    /// \brief Obtains the hash of a node in the hash-tree.
     /// \param address Address of target node. Must be aligned to a 2<sup>log2_size</sup> boundary.
     /// \param log2_size log<sub>2</sub> of size subintended by target node.
-    /// \returns The hash of the target node.
-    hash_type get_merkle_tree_node_hash(uint64_t address, int log2_size) const;
+    /// \returns The hash.
+    machine_hash get_node_hash(uint64_t address, int log2_size) const;
 
-    /// \brief Obtains the hash of a node in the Merkle tree without making any modifications to the tree.
+    /// \brief Obtains the hash of a node in the hash-tree without making any modifications to it.
     /// \param address Address of target node. Must be aligned to a 2<sup>log2_size</sup> boundary.
     /// \param log2_size log<sub>2</sub> of size subintended by target node.
-    /// \returns The hash of the target node.
-    hash_type get_merkle_tree_node_hash(uint64_t address, int log2_size, skip_merkle_tree_update_t /*unused*/) const;
+    /// \returns The hash.
+    machine_hash get_node_hash(uint64_t address, int log2_size, skip_hash_tree_update_t /*unused*/) const;
 
-    /// \brief Verifies integrity of Merkle tree.
+    /// \brief Verifies integrity of hash tree without making any modifications to it tree.
     /// \returns True if tree is self-consistent, false otherwise.
-    bool verify_merkle_tree() const;
+    bool verify_hash_tree() const;
 
     /// \brief Read the value of any register
     /// \param r Register to read
@@ -424,10 +423,6 @@ class machine final {
     /// \brief Go over the write TLB and mark as dirty all pages currently there.
     void mark_write_tlb_dirty_pages() const;
 
-    /// \brief Verify if dirty page maps are consistent.
-    /// \returns true if they are, false if there is an error.
-    bool verify_dirty_page_maps() const;
-
     /// \brief Returns copy of initialization config.
     const machine_config &get_initial_config() const;
 
@@ -518,7 +513,7 @@ class machine final {
     /// \param log Log containing the state accesses performed by the load operation
     /// \param root_hash_after State hash after response was sent.
     static void verify_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
-        const hash_type &root_hash_before, const access_log &log, const hash_type &root_hash_after);
+        const machine_hash &root_hash_before, const access_log &log, const machine_hash &root_hash_after);
 
     /// \brief Returns a description of what is at a given target physical address
     /// \param paddr Target physical address of interest
@@ -550,7 +545,7 @@ class machine final {
     }
 
     /// \brief Returns whether runtime soft yields are enabled
-    bool is_soft_yield() const {
+    bool get_soft_yield() const {
         return m_r.soft_yield;
     }
 };
diff --git a/src/memory-address-range.cpp b/src/memory-address-range.cpp
index e63236727..bd7c87d54 100644
--- a/src/memory-address-range.cpp
+++ b/src/memory-address-range.cpp
@@ -23,7 +23,6 @@
 #include <system_error>
 
 #include "address-range-constants.h"
-#include "unique-c-ptr.h"
 
 namespace cartesi {
 
@@ -36,13 +35,35 @@ class base_error : public std::invalid_argument {
     }
 };
 
+static bool check_read_only(bool host_read_only, bool flags_W, bool create) {
+    if (host_read_only) {
+        if (create) {
+            throw base_error{"newly-created backing store cannot be read-only"};
+        }
+        if (flags_W) {
+            throw base_error{"backing store for writable memory address range cannot be read-only"};
+        }
+    }
+    return host_read_only;
+}
+
+static const pmas_flags &check_flags(pmas_flags &&) = delete;
+static const pmas_flags &check_flags(const pmas_flags &flags) {
+    if (!flags.M) {
+        throw base_error{"memory address range must be flagged memory"};
+    }
+    return flags;
+}
+
+static const auto throw_base_error = [](const char *err) { throw base_error{err}; };
+
 memory_address_range::memory_address_range(const std::string &description, uint64_t start, uint64_t length,
-    const pmas_flags &flags, const backing_store_config &backing_store, const memory_address_range_flags &ar_flags,
-    uint64_t host_length) try :
-    address_range(description.c_str(), start, length, flags, [](const char *err) { throw base_error{err}; }),
-    m_ptr{make_unique_mmap<unsigned char>(host_length != 0 ? host_length : length,
+    const pmas_flags &flags, const backing_store_config &backing_store,
+    const memory_address_range_config &memory_config) try :
+    address_range(description.c_str(), start, length, check_flags(flags), throw_base_error),
+    m_ptr{make_unique_mmap<unsigned char>(std::max(memory_config.host_length, length),
         os_mmap_flags{
-            .read_only = ar_flags.read_only && !backing_store.create,
+            .read_only = check_read_only(memory_config.host_read_only, flags.W, backing_store.create),
             .shared = backing_store.shared,
             .create = backing_store.create,
             .truncate = backing_store.truncate,
@@ -50,17 +71,15 @@ memory_address_range::memory_address_range(const std::string &description, uint6
         },
         backing_store.data_filename, length)},
     m_host_memory{m_ptr.get()},
-    m_ar_flags{ar_flags} {
-    if (!is_memory()) {
-        throw std::invalid_argument{"memory range must be flagged memory"s};
-    }
-    m_dirty_page_map.resize((get_length() / (8 * AR_PAGE_SIZE)) + 1, 0xff);
-} catch (base_error &b) {
+    m_config{memory_config},
+    m_dpt{get_level_count(length), length >> AR_LOG2_PAGE_SIZE},
+    m_dht{get_level_count(length), length >> AR_LOG2_PAGE_SIZE} {
+} catch (const base_error &b) {
     throw; // already contains the description
-} catch (std::exception &e) {
-    throw std::invalid_argument{e.what() + " when initializing "s + description};
+} catch (const std::exception &e) {
+    throw std::invalid_argument{std::string{e.what()}.append(" when initializing ").append(description)};
 } catch (...) {
-    throw std::invalid_argument{"unknown exception when initializing "s + description};
+    throw std::invalid_argument{"unknown exception when initializing "s.append(description)};
 }
 
 } // namespace cartesi
diff --git a/src/memory-address-range.h b/src/memory-address-range.h
index bf2f12868..fc08b6fca 100644
--- a/src/memory-address-range.h
+++ b/src/memory-address-range.h
@@ -21,44 +21,52 @@
 #include <variant>
 
 #include "address-range.h"
+#include "dense-hash-tree.h"
+#include "dirty-page-tree.h"
 #include "machine-config.h"
 #include "os-mmap.h"
-#include "unique-c-ptr.h"
 
 namespace cartesi {
 
 // Forward declarations
 class machine;
 
+/// \brief Configuration for memory address range
+struct memory_address_range_config {
+    ///< Whether memory is read-only on host. (If set, must be read-only on target as well)
+    bool host_read_only{false};
+    ///< Total amount of memory allocated by host. (Must be larger than what is needed by target)
+    uint64_t host_length{0};
+};
+
 /// \file
 /// \brief An address range occupied by memory
 
-struct memory_address_range_flags final {
-    bool read_only{false};        ///< Whether the memory is read-only on the host
-    bool page_uncleanable{false}; //< Whether the memory page dirty state can be cleaned
-};
-
+/// \brief An address range occupied by memory
 class memory_address_range : public address_range {
-    unique_mmap_ptr<unsigned char> m_ptr;  ///< Pointer to mapped memory
-    unsigned char *m_host_memory;          ///< Start of associated memory region in host.
-    memory_address_range_flags m_ar_flags; ///< Memory address range specific flags.
-    std::vector<uint8_t> m_dirty_page_map; ///< Map of dirty pages.
 
-public:
-    using ptr_type = std::unique_ptr<memory_address_range>;
+    unique_mmap_ptr<unsigned char> m_ptr; ///< Pointer to mapped memory
+    unsigned char *m_host_memory;         ///< Start of associated memory region in host.
+    memory_address_range_config m_config; ///< Configuration passed to constructor.
+    dirty_page_tree m_dpt;                ///< Tree of dirty pages.
+    dense_hash_tree m_dht;                ///< Dense hash tree of pages.
 
-    /// \brief Constructor for mmap'd ranges.
+public:
+    /// \brief Constructor
     /// \param description Description of address range for use in error messages
     /// \param start Start of address range
     /// \param length Length of address range
-    /// \param flags Range flags
-    /// \param image_filename Path to backing file.
-    /// \param host_length Length of host memory to be mapped.
-    /// This value can exceed the specified length, effectively creating an additional region
-    /// of memory that is not associated with the backing files.
+    /// \param flags Address range flags
+    /// \param backing_store Configuration for underlying file backing.
+    /// \param config Additional configuration for memory address range.
+    /// \p config.host_length Length of host memory to be mapped.
+    /// If set to 0, use \p length.
+    /// Otherwise, \p host_length cannot be smaller than \p length.
+    /// The effect is to allocate additional memory past \p length that is not visible by the address range,
+    /// and is not part of the backing storage, but can be used for other purposes.
+    /// \p config.host_read_only Marks memory as read-only on host itself. Requires \p flags.W to be cleared as well.
     memory_address_range(const std::string &description, uint64_t start, uint64_t length, const pmas_flags &flags,
-        const backing_store_config &backing_store = {}, const memory_address_range_flags &ar_flags = {},
-        uint64_t host_length = 0);
+        const backing_store_config &backing_store, const memory_address_range_config &memory_config);
 
     memory_address_range(const memory_address_range &) = delete;
     memory_address_range &operator=(const memory_address_range &) = delete;
@@ -76,58 +84,33 @@ class memory_address_range : public address_range {
         return m_host_memory;
     }
 
-    void do_mark_dirty_page(uint64_t offset) noexcept override {
-        auto page_index = offset >> AR_constants::AR_PAGE_SIZE_LOG2;
-        auto map_index = page_index >> 3;
-        assert(map_index < m_dirty_page_map.size());
-        m_dirty_page_map[map_index] |= (1 << (page_index & 7));
-    }
-
-    void do_mark_clean_page(uint64_t offset) noexcept override {
-        if (m_ar_flags.page_uncleanable) {
-            // Dirty pages on this address range are permanently dirty and cannot be cleaned.
-            return;
-        }
-        auto page_index = offset >> AR_constants::AR_PAGE_SIZE_LOG2;
-        auto map_index = page_index >> 3;
-        assert(map_index < m_dirty_page_map.size());
-        m_dirty_page_map[map_index] &= ~(1 << (page_index & 7));
-    }
-
-    void do_mark_pages_clean() noexcept override {
-        if (m_ar_flags.page_uncleanable) {
-            // Dirty pages on this address range are permanently dirty and cannot be cleaned.
-            return;
-        }
-        std::fill(m_dirty_page_map.begin(), m_dirty_page_map.end(), 0);
+    bool do_is_host_read_only() const noexcept override {
+        return m_config.host_read_only;
     }
 
-    bool do_is_page_marked_dirty(uint64_t offset) const noexcept override {
-        auto page_index = offset >> AR_constants::AR_PAGE_SIZE_LOG2;
-        auto map_index = page_index >> 3;
-        assert(map_index < m_dirty_page_map.size());
-        return (m_dirty_page_map[map_index] & (1 << (page_index & 7))) != 0;
+    dirty_page_tree &do_get_dirty_page_tree() noexcept override {
+        return m_dpt;
     }
 
-    bool do_is_host_read_only() const noexcept override {
-        return m_ar_flags.read_only;
+    const dirty_page_tree &do_get_dirty_page_tree() const noexcept override {
+        return m_dpt;
     }
 
-    bool do_is_page_uncleanable() const noexcept override {
-        return m_ar_flags.page_uncleanable;
+    dense_hash_tree &do_get_dense_hash_tree() noexcept override {
+        return m_dht;
     }
 
-    bool do_peek(const machine & /*m*/, uint64_t offset, uint64_t length, const unsigned char **data,
-        unsigned char * /*scratch*/) const noexcept override {
-        if (contains_relative(offset, length)) {
-            *data = get_host_memory() + offset;
-            return true;
-        }
-        *data = nullptr;
-        return false;
+    const dense_hash_tree &do_get_dense_hash_tree() const noexcept override {
+        return m_dht;
     }
 };
 
+static inline auto make_memory_address_range(const std::string &description, uint64_t start, uint64_t length,
+    const pmas_flags &flags, const backing_store_config &backing_store = {},
+    const memory_address_range_config &config = {}) {
+    return memory_address_range{description, start, length, flags, backing_store, config};
+}
+
 } // namespace cartesi
 
 #endif
diff --git a/src/merkle-tree-hash.cpp b/src/merkle-tree-hash.cpp
index 101235b4c..314917562 100644
--- a/src/merkle-tree-hash.cpp
+++ b/src/merkle-tree-hash.cpp
@@ -31,7 +31,6 @@
 
 using namespace cartesi;
 using hasher_type = keccak_256_hasher;
-using hash_type = hasher_type::hash_type;
 
 /// \brief Checks if string matches prefix and captures remaninder
 /// \param pre Prefix to match in str.
@@ -68,7 +67,7 @@ static bool intval(const char *pre, const char *str, int *val) {
 /// \brief Prints hash in hex to file
 /// \param hash Hash to be printed.
 /// \param f File to print to
-static void print_hash(const hash_type &hash, FILE *f) {
+static void print_hash(const machine_hash &hash, FILE *f) {
     for (auto b : hash) {
         std::ignore = fprintf(f, "%02x", static_cast<int>(b));
     }
@@ -80,12 +79,12 @@ static void print_hash(const hash_type &hash, FILE *f) {
 /// \brief Reads a hash in hex from file
 /// \param f File to read from
 /// \returns Hash if successful, nothing otherwise
-static std::optional<hash_type> read_hash(FILE *f) {
+static std::optional<machine_hash> read_hash(FILE *f) {
     std::array<char, hasher_type::hash_size * 2> hex_hash{};
     if (fread(hex_hash.data(), 1, hex_hash.size(), f) != hex_hash.size()) {
         return {};
     }
-    hash_type h;
+    machine_hash h;
     for (size_t i = 0; i < hasher_type::hash_size; ++i) {
         std::array<char, 3> hex_c{hex_hash[2 * i], hex_hash[2 * i + 1], '\0'};
         unsigned c = 0;
@@ -116,9 +115,9 @@ __attribute__((__format__(__printf__, 1, 2))) static void error(const char *fmt,
 /// \param word Pointer to word data. Must contain 2^log2_word_size bytes
 /// \param log2_word_size Log<sub>2</sub> of word size
 /// \param hash Receives the word hash
-static void get_word_hash(hasher_type &h, const unsigned char *word, int log2_word_size, hash_type &hash) {
+static void get_word_hash(hasher_type &h, const unsigned char *word, int log2_word_size, machine_hash &hash) {
     h.begin();
-    h.add_data(word, 1 << log2_word_size);
+    h.add_data(std::span<const unsigned char>(word, 1 << log2_word_size));
     h.end(hash);
 }
 
@@ -129,17 +128,18 @@ static void get_word_hash(hasher_type &h, const unsigned char *word, int log2_wo
 /// \param log2_leaf_size Log<sub>2</sub> of leaf size
 /// \param log2_word_size Log<sub>2</sub> of word size
 /// \returns Merkle hash of leaf data
-static hash_type get_leaf_hash(hasher_type &h, const unsigned char *leaf_data, int log2_leaf_size, int log2_word_size) {
+static machine_hash get_leaf_hash(hasher_type &h, const unsigned char *leaf_data, int log2_leaf_size,
+    int log2_word_size) {
     assert(log2_word_size >= 1);
     assert(log2_leaf_size >= log2_word_size);
     if (log2_leaf_size > log2_word_size) {
-        hash_type left = get_leaf_hash(h, leaf_data, log2_leaf_size - 1, log2_word_size);
-        const hash_type right =
+        machine_hash left = get_leaf_hash(h, leaf_data, log2_leaf_size - 1, log2_word_size);
+        const machine_hash right =
             get_leaf_hash(h, leaf_data + (1 << (log2_leaf_size - 1)), log2_leaf_size - 1, log2_word_size);
         get_concat_hash(h, left, right, left);
         return left;
     }
-    hash_type leaf;
+    machine_hash leaf;
     get_word_hash(h, leaf_data, log2_word_size, leaf);
     return leaf;
 }
@@ -150,7 +150,7 @@ static hash_type get_leaf_hash(hasher_type &h, const unsigned char *leaf_data, i
 /// \param log2_leaf_size Log<sub>2</sub> of leaf size
 /// \param log2_word_size Log<sub>2</sub> of word size
 /// \returns Merkle hash of leaf data
-static hash_type get_leaf_hash(const unsigned char *leaf_data, int log2_leaf_size, int log2_word_size) {
+static machine_hash get_leaf_hash(const unsigned char *leaf_data, int log2_leaf_size, int log2_word_size) {
     hasher_type h;
     return get_leaf_hash(h, leaf_data, log2_leaf_size, log2_word_size);
 }
diff --git a/src/merkle-tree-proof.h b/src/merkle-tree-proof.h
index 29d7597e5..e7f313b23 100644
--- a/src/merkle-tree-proof.h
+++ b/src/merkle-tree-proof.h
@@ -22,6 +22,7 @@
 
 #include <algorithm>
 #include <cstdint>
+#include <ranges>
 #include <stdexcept>
 #include <type_traits>
 #include <vector>
@@ -36,15 +37,8 @@ namespace cartesi {
 /// This structure holds a proof that the node spanning a log2_target_size
 /// at a given address in the tree has a certain hash.
 /// \}
-/// \tparam HASH_TYPE the type that holds a hash
-/// \tparam ADDRESS_TYPE the type that holds an address
-template <typename HASH_TYPE, typename ADDRESS_TYPE = uint64_t>
 class merkle_tree_proof final {
 public:
-    using hash_type = HASH_TYPE;
-
-    using address_type = ADDRESS_TYPE;
-
     /// \brief Constructs a merkle_tree_proof object and allocates
     /// room for the sibling hashes
     merkle_tree_proof(int log2_root_size, int log2_target_size) :
@@ -70,7 +64,7 @@ class merkle_tree_proof final {
 
     /// \brief Storage for the hashes of the siblings of all nodes along
     /// the path from the root node to the target node.
-    using sibling_hashes_type = std::vector<hash_type>;
+    using sibling_hashes_type = std::vector<machine_hash>;
 
     /// \brief Gets log<sub>2</sub> of size subintended by entire tree.
     /// \returns log<sub>2</sub> of size subintended by entire tree.
@@ -86,61 +80,61 @@ class merkle_tree_proof final {
 
     /// \brief Set target node address
     /// \param target_address New address.
-    void set_target_address(address_type target_address) {
+    void set_target_address(uint64_t target_address) {
         m_target_address = target_address;
     }
 
     /// \brief Gets address of target node
     /// \return Reference to hash.
-    const address_type &get_target_address() const {
+    const uint64_t &get_target_address() const {
         return m_target_address;
     }
-    address_type &get_target_address() {
+    uint64_t &get_target_address() {
         return m_target_address;
     }
 
     /// \brief Set hash of target node
     /// \param hash New hash.
-    void set_target_hash(const hash_type &hash) {
-        m_target_hash = hash;
+    void set_target_hash(const_machine_hash_view hash) {
+        std::ranges::copy(hash, m_target_hash.begin());
     }
 
     /// \brief Gets hash of target node
     /// \return Reference to hash.
-    const hash_type &get_target_hash() const {
+    const machine_hash &get_target_hash() const {
         return m_target_hash;
     }
-    hash_type &get_target_hash() {
+    machine_hash &get_target_hash() {
         return m_target_hash;
     }
 
     /// \brief Set hash of root node
     /// \param hash New hash.
-    void set_root_hash(const hash_type &hash) {
-        m_root_hash = hash;
+    void set_root_hash(const_machine_hash_view hash) {
+        std::ranges::copy(hash, m_root_hash.begin());
     }
 
     /// \brief Gets hash of root node
     /// \return Reference to hash.
-    const hash_type &get_root_hash() const {
+    const machine_hash &get_root_hash() const {
         return m_root_hash;
     }
-    hash_type &get_root_hash() {
+    machine_hash &get_root_hash() {
         return m_root_hash;
     }
 
     /// \brief Get hash corresponding to log2_size from the list of siblings.
     /// \param log2_size log<sub>2</sub> of size subintended by hash.
     /// \return Reference to hash inside list of siblings.
-    const hash_type &get_sibling_hash(int log2_size) const {
+    const machine_hash &get_sibling_hash(int log2_size) const {
         return m_sibling_hashes[log2_size_to_index(log2_size)];
     }
 
     /// \brief Modify hash corresponding to log2_size in the list of siblings.
     /// \param hash New hash.
     /// \param log2_size log<sub>2</sub> of size subintended by hash.
-    void set_sibling_hash(const hash_type &hash, int log2_size) {
-        m_sibling_hashes[log2_size_to_index(log2_size)] = hash;
+    void set_sibling_hash(const_machine_hash_view hash, int log2_size) {
+        std::ranges::copy(hash, m_sibling_hashes[log2_size_to_index(log2_size)].begin());
     }
 
     const sibling_hashes_type &get_sibling_hashes() const {
@@ -171,32 +165,30 @@ class merkle_tree_proof final {
     }
 
     /// \brief Checks if two Merkle proofs are different
-    bool operator!=(const merkle_tree_proof<hash_type, address_type> &other) const {
+    bool operator!=(const merkle_tree_proof &other) const {
         return !(operator==(other));
     }
 
     ///< \brief Verify if proof is valid
-    ///< \tparam HASHER_TYPE Hasher class to use
+    ///< \tparam H Hasher class to use
     ///< \param h Hasher object to use
     ///< \return True if proof is valid, false otherwise
-    template <typename HASHER_TYPE>
-    bool verify(HASHER_TYPE &h) const {
-        return bubble_up(h, get_target_hash()) == get_root_hash();
+    template <IHasher H>
+    bool verify(H &&h) const {
+        return bubble_up(std::forward<H>(h), get_target_hash()) == get_root_hash();
     }
 
     ///< \brief Verify if proof is valid
-    ///< \tparam HASHER_TYPE Hasher class to use
+    ///< \tparam H Hasher class to use
     ///< \param h Hasher object to use
     ///< \param new_target_hash New target hash to replace
     ///< \return New root hash
-    template <typename HASHER_TYPE>
-    hash_type bubble_up(HASHER_TYPE &h, const hash_type &new_target_hash) const {
-        static_assert(is_an_i_hasher_v<HASHER_TYPE>, "not an i_hasher");
-        static_assert(std::is_same_v<typename std::remove_cvref_t<HASHER_TYPE>::hash_type, hash_type>,
-            "incompatible hash types");
-        hash_type hash = new_target_hash;
+    template <IHasher H>
+    // NOLINTNEXTLINE(cppcoreguidelines-missing-std-forward)
+    machine_hash bubble_up(H &&h, const machine_hash &new_target_hash) const {
+        machine_hash hash = new_target_hash;
         for (int log2_size = get_log2_target_size(); log2_size < get_log2_root_size(); ++log2_size) {
-            const int bit = (get_target_address() & (static_cast<address_type>(1) << log2_size)) != 0;
+            const int bit = (get_target_address() & (static_cast<uint64_t>(1) << log2_size)) != 0;
             if (bit) {
                 get_concat_hash(h, get_sibling_hash(log2_size), hash, hash);
             } else {
@@ -206,12 +198,9 @@ class merkle_tree_proof final {
         return hash;
     }
 
-    template <typename HASHER_TYPE>
-    merkle_tree_proof<hash_type, address_type> slice(HASHER_TYPE &h, int new_log2_root_size,
-        int new_log2_target_size) const {
-        static_assert(is_an_i_hasher_v<HASHER_TYPE>, "not an i_hasher");
-        static_assert(std::is_same_v<typename std::remove_cvref_t<HASHER_TYPE>::hash_type, hash_type>,
-            "incompatible hash types");
+    template <IHasher H>
+    // NOLINTNEXTLINE(cppcoreguidelines-missing-std-forward)
+    merkle_tree_proof slice(H &&h, int new_log2_root_size, int new_log2_target_size) const {
         if (new_log2_root_size <= 0) {
             throw std::out_of_range{"log2_root_size is not positive"};
         }
@@ -227,10 +216,10 @@ class merkle_tree_proof final {
         if (new_log2_target_size < get_log2_target_size()) {
             throw std::out_of_range{"log2_target_size is too small"};
         }
-        merkle_tree_proof<HASH_TYPE, ADDRESS_TYPE> sliced(new_log2_root_size, new_log2_target_size);
-        hash_type hash = get_target_hash();
+        merkle_tree_proof sliced(new_log2_root_size, new_log2_target_size);
+        machine_hash hash = get_target_hash();
         for (int log2_size = get_log2_target_size(); log2_size < new_log2_target_size; ++log2_size) {
-            int bit = (get_target_address() & (static_cast<address_type>(1) << log2_size)) != 0;
+            const auto bit = (get_target_address() & (static_cast<uint64_t>(1) << log2_size)) != 0;
             if (bit) {
                 get_concat_hash(h, get_sibling_hash(log2_size), hash, hash);
             } else {
@@ -239,8 +228,8 @@ class merkle_tree_proof final {
         }
         sliced.set_target_hash(hash);
         for (int log2_size = new_log2_target_size; log2_size < new_log2_root_size; ++log2_size) {
-            int bit = (get_target_address() & (static_cast<address_type>(1) << log2_size)) != 0;
-            const hash_type &sibling_hash = get_sibling_hash(log2_size);
+            const auto bit = (get_target_address() & (static_cast<uint64_t>(1) << log2_size)) != 0;
+            const machine_hash &sibling_hash = get_sibling_hash(log2_size);
             if (bit) {
                 get_concat_hash(h, sibling_hash, hash, hash);
             } else {
@@ -267,11 +256,11 @@ class merkle_tree_proof final {
         return index;
     }
 
-    address_type m_target_address{0};     ///< Address of target node
+    uint64_t m_target_address{0};         ///< Address of target node
     int m_log2_target_size{0};            ///< log<sub>2</sub> of size subintended by target node
-    hash_type m_target_hash{};            ///< Hash of target node
+    machine_hash m_target_hash{};         ///< Hash of target node
     int m_log2_root_size{0};              ///< log<sub>2</sub> of size subintended by tree
-    hash_type m_root_hash{};              ///< Hash of root node
+    machine_hash m_root_hash{};           ///< Hash of root node
     sibling_hashes_type m_sibling_hashes; ///< Hashes of siblings in path from target to root
 };
 
diff --git a/src/meta.h b/src/meta.h
index 1bf94a03c..cea033337 100644
--- a/src/meta.h
+++ b/src/meta.h
@@ -92,6 +92,9 @@ struct overloads : Ts... {
 };
 
 /// \endcond
+///
+///
+///
 
 } // namespace cartesi
 
diff --git a/src/page-hash-tree-cache.h b/src/page-hash-tree-cache.h
new file mode 100644
index 000000000..16fb8b1a9
--- /dev/null
+++ b/src/page-hash-tree-cache.h
@@ -0,0 +1,435 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef PAGE_HASH_TREE_CACHE_H
+#define PAGE_HASH_TREE_CACHE_H
+
+#include <atomic>
+#include <functional>
+#include <iomanip>
+#include <iostream>
+#include <optional>
+#include <ranges>
+#include <span>
+#include <unordered_map>
+
+#include <boost/intrusive/list.hpp>
+
+#include "address-range-constants.h"
+#include "circular-buffer.h"
+#include "hash-tree-constants.h"
+#include "i-hasher.h"
+#include "is-pristine.h"
+#include "machine-hash.h"
+#include "meta.h"
+#include "ranges.h"
+#include "strict-aliasing.h"
+
+namespace cartesi {
+
+class page_hash_tree_cache {
+
+    static constexpr int m_page_size = HASH_TREE_PAGE_SIZE;
+    static constexpr int m_word_size = HASH_TREE_WORD_SIZE;
+    static constexpr int m_page_word_count = m_page_size / m_word_size;
+    static constexpr int m_page_hash_tree_size = 2 * m_page_word_count;
+
+    using address_type = uint64_t;
+
+public:
+    using page = std::array<unsigned char, m_page_size>;
+    using page_view = std::span<unsigned char, m_page_size>;
+    using const_page_view = std::span<const unsigned char, m_page_size>;
+
+    using page_hash_tree = std::array<machine_hash, m_page_hash_tree_size>;
+    static_assert(POD<page>, "hash_tree must be trivially copyable and standard layout");
+    static_assert(POD<machine_hash>, "machine_hash must be trivially copyable and standard layout");
+    static_assert(POD<page_hash_tree>, "page_hash_tree must be trivially copyable and standard layout");
+
+    class entry : public boost::intrusive::list_base_hook<> {
+
+        page m_page{};
+        page_hash_tree m_hash_tree{};
+
+        static constexpr uint64_t m_paddr_page_offset = 0;
+        static constexpr uint64_t m_borrowed_offset = sizeof(uint64_t);
+
+        friend page_hash_tree_cache;
+
+        entry &set_paddr_page(uint64_t paddr_page) noexcept {
+            aliased_aligned_write<uint64_t>(&m_hash_tree[0][m_paddr_page_offset], paddr_page);
+            return *this;
+        }
+
+        entry &set_borrowed(uint64_t borrowed) noexcept {
+            aliased_aligned_write<uint64_t>(&m_hash_tree[0][m_borrowed_offset], borrowed);
+            return *this;
+        }
+
+        uint64_t get_borrowed() const noexcept {
+            return aliased_aligned_read<uint64_t>(&m_hash_tree[0][m_borrowed_offset]);
+        }
+
+        void clear_page() noexcept {
+            std::ranges::fill(m_page, 0);
+        }
+
+        void clear_hash_tree(const page_hash_tree &pristine) noexcept {
+            auto paddr_page = get_paddr_page();
+            auto borrowed = get_borrowed();
+            m_hash_tree = pristine;
+            set_paddr_page(paddr_page);
+            set_borrowed(borrowed);
+        }
+
+        void clear(const page_hash_tree &pristine) noexcept {
+            clear_hash_tree(pristine);
+            clear_page();
+            set_borrowed(0);
+            set_paddr_page(0);
+        }
+
+        static int left_child(int i) {
+            return 2 * i;
+        }
+
+        static int right_child(int i) {
+            return (2 * i) + 1;
+        }
+
+        static int parent(int i) {
+            return i / 2;
+        }
+
+    public:
+        explicit entry(const page_hash_tree &pristine) : m_hash_tree{pristine} {}
+
+        entry(const entry &other) = default;
+        entry(entry &&other) = default;
+        entry &operator=(const entry &other) = default;
+        entry &operator=(entry &&other) = default;
+        ~entry() = default;
+
+        uint64_t get_paddr_page() const noexcept {
+            return aliased_aligned_read<uint64_t>(&m_hash_tree[0][m_paddr_page_offset]);
+        }
+
+#ifdef DUMP_HASH_TREE_STATS
+        static std::atomic<int> m_word_hit;
+        static std::atomic<int> m_word_miss;
+        static std::atomic<int> m_inner_page_node_hashes;
+#endif
+
+        template <IHasher H>
+        // NOLINTNEXTLINE(cppcoreguidelines-missing-std-forward)
+        static page_hash_tree get_pristine_page_hash_tree(H &&h) noexcept {
+            page_hash_tree tree{};
+            std::array<unsigned char, m_word_size> zero{};
+            machine_hash hash = get_hash(h, zero);
+            auto start = m_page_word_count;
+            while (start > 0) {
+                for (auto i = start; i < 2 * start; ++i) {
+                    tree[i] = hash;
+                }
+                start /= 2;
+                get_concat_hash(h, hash, hash, hash);
+            }
+            return tree;
+        }
+
+        const auto &get_page() const noexcept {
+            return m_page;
+        }
+
+        const_machine_hash_view root_hash_view() const noexcept {
+            return m_hash_tree[1];
+        }
+
+        const_machine_hash_view node_hash_view(uint64_t address, int log2_size) const noexcept {
+            static constexpr machine_hash no_hash{};
+            if (log2_size < HASH_TREE_LOG2_WORD_SIZE || log2_size > HASH_TREE_LOG2_PAGE_SIZE) {
+                assert(false && "log2_size is out of range");
+                return no_hash;
+            }
+            auto start = UINT64_C(1) << (HASH_TREE_LOG2_PAGE_SIZE - log2_size);
+            auto index = address >> log2_size;
+            if (index > start || (index << log2_size) != address) {
+                assert(false && "address is out of range");
+                return no_hash;
+            }
+            return m_hash_tree[start + index];
+        }
+
+        template <IHasher H, ContiguousRangeOfByteLike D>
+        // NOLINTNEXTLINE(cppcoreguidelines-missing-std-forward)
+        bool update(H &&h, D &&d, const page_hash_tree &pristine) noexcept {
+            if (std::ranges::size(d) != m_page_size) {
+                return false;
+            }
+            if (is_pristine(d)) {
+                clear_hash_tree(pristine);
+                clear_page();
+                return true;
+            }
+            const const_page_view page{std::ranges::data(d), std::ranges::size(d)};
+            circular_buffer<int, m_page_word_count / 2> dirty_nodes;
+            // Go over all words in the entry page, comparing with updated page,
+            // and updating the hashes for the modified words
+            //??D In C++23, we would use std::views::slide and std::views::zip to write this in declarative style.
+            const page_view entry_page{m_page};
+#ifdef DUMP_HASH_TREE_STATS
+            int hit = 0;
+            int miss = 0;
+#endif
+            for (int offset = 0, index = m_page_word_count; offset < m_page_size; offset += m_word_size, ++index) {
+                const auto entry_word = entry_page.subspan(offset, m_word_size);
+                const auto page_word = page.subspan(offset, m_word_size);
+                if (!std::ranges::equal(entry_word, page_word)) {
+                    get_hash(h, page_word, m_hash_tree[index]);
+                    std::ranges::copy(page_word, entry_word.begin());
+                    dirty_nodes.try_push_back(parent(index));
+#ifdef DUMP_HASH_TREE_STATS
+                    ++miss;
+#endif
+                } else {
+#ifdef DUMP_HASH_TREE_STATS
+                    ++hit;
+#endif
+                }
+            }
+#ifdef DUMP_HASH_TREE_STATS
+            m_word_hit += hit;
+            m_word_miss += miss;
+#endif
+            // Now go over fifo, taking a node, updating its from its children, and enqueueing its parent for update
+#ifdef DUMP_HASH_TREE_STATS
+            int inner_page_node_hashes = 0;
+#endif
+            while (!dirty_nodes.empty()) {
+                const int index = dirty_nodes.front();
+                dirty_nodes.pop_front();
+#ifdef DUMP_HASH_TREE_STATS
+                ++inner_page_node_hashes;
+#endif
+                get_concat_hash(h, m_hash_tree[left_child(index)], m_hash_tree[right_child(index)], m_hash_tree[index]);
+                if (index != 1) {
+                    dirty_nodes.try_push_back(parent(index));
+                }
+            }
+#ifdef DUMP_HASH_TREE_STATS
+            m_inner_page_node_hashes += inner_page_node_hashes;
+#endif
+            return true;
+        }
+
+        template <IHasher H>
+        // NOLINTNEXTLINE(cppcoreguidelines-missing-std-forward)
+        bool verify(H &&h) noexcept {
+            std::cerr << "verifying entry\n";
+            const page_view entry_page{m_page};
+            for (int offset = 0, index = m_page_word_count; offset < m_page_size; offset += m_word_size, ++index) {
+                const auto page_word = entry_page.subspan(offset, m_word_size);
+                const auto page_word_hash = get_hash(h, page_word);
+                if (page_word_hash != m_hash_tree[index]) {
+                    const int log2_size = HASH_TREE_LOG2_WORD_SIZE;
+                    std::cerr << "hash mismatch in index " << std::dec << index << ":" << log2_size << '\n';
+                    return false;
+                }
+            }
+            int start = m_page_word_count / 2;
+            const int log2_size = HASH_TREE_LOG2_WORD_SIZE + 1;
+            while (start != 0) {
+                for (int index = start; index < 2 * start; ++index) {
+                    const auto node_hash =
+                        get_concat_hash(h, m_hash_tree[left_child(index)], m_hash_tree[right_child(index)]);
+                    if (node_hash != m_hash_tree[index]) {
+                        std::cerr << "hash mismatch in index " << std::dec << index << ":" << log2_size << '\n';
+                        return false;
+                    }
+                }
+                start /= 2;
+            }
+            return true;
+        }
+    };
+
+    // static_assert(POD<entry>, "entry must be trivially copyable and standard layout");
+
+    template <IHasher H>
+    page_hash_tree_cache(H &&h, size_t num_entries) :
+        m_pristine_page_hash_tree{entry::get_pristine_page_hash_tree(std::forward<H>(h))},
+        m_entries{num_entries, entry{m_pristine_page_hash_tree}} {
+        m_map.reserve(num_entries);
+    }
+
+    page_hash_tree_cache(const page_hash_tree_cache &other) = delete;
+    page_hash_tree_cache(page_hash_tree_cache &&other) = delete;
+    page_hash_tree_cache &operator=(const page_hash_tree_cache &other) = delete;
+    page_hash_tree_cache &operator=(page_hash_tree_cache &&other) = delete;
+
+    const page_hash_tree &get_pristine_page_hash_tree() const {
+        return m_pristine_page_hash_tree;
+    }
+
+    void dump_lru() const {
+        std::cerr << "lru: " << std::hex;
+        for (const auto &p : m_lru) {
+            std::cerr << "0x" << p.get_paddr_page() << " ";
+        }
+        std::cerr << "\n";
+    }
+
+    template <RangeOfByteLike D>
+    // NOLINTNEXTLINE(cppcoreguidelines-missing-std-forward)
+    void dump_hex(D &&bytes, std::ostream &out, size_t limit = -1) {
+        out << std::hex << std::setw(2) << std::setfill('0') << std::uppercase;
+        for (auto b :
+            bytes | views::cast_to<unsigned int> | std::views::take(std::min(limit, std::ranges::size(bytes)))) {
+            out << b;
+        }
+    }
+
+    void dump_map() const {
+        std::cerr << "map: " << std::hex;
+        for (const auto &[key, val] : m_map) {
+            std::cerr << "0x" << key << " ";
+        }
+        std::cerr << "\n";
+    }
+
+    std::optional<std::reference_wrapper<entry>> borrow_entry(uint64_t paddr_page, bool &hit) {
+        // Found entry for page in map?
+        if (auto it = m_map.find(paddr_page); it != m_map.end()) {
+            entry &e = it->second.second;
+            if (e.get_borrowed() != 0) {
+                throw std::runtime_error{"page hash-tree cache entry already borrowed"};
+            }
+            // Make it most recently used
+            m_lru.splice(m_lru.begin(), m_lru, it->second.first);
+            hit = true;
+#ifdef DUMP_HASH_TREE_STATS
+            ++m_page_hit;
+#endif
+            // Return borrowed entry
+            return std::ref(e.set_borrowed(1));
+        }
+        hit = false;
+        // Not in map, but we still have unused entries to lend
+        if (m_used < m_entries.size()) {
+#ifdef DUMP_HASH_TREE_STATS
+            ++m_page_miss;
+#endif
+            entry &e = m_entries[m_used++];
+            if (e.get_borrowed() != 0) {
+                throw std::runtime_error{"page hash-tree cache entry already borrowed"};
+            }
+            m_lru.push_front(e);
+            m_map.emplace(paddr_page, map_value{m_lru.begin(), e});
+            // Return borrowed
+            return std::ref(e.set_borrowed(1).set_paddr_page(paddr_page));
+        }
+        // Evict least recently used
+        auto &e = m_lru.back();
+        // If even that has been borrowed, we are out of entries to lend
+        if (e.get_borrowed() != 0) {
+            return {};
+        }
+        m_map.erase(e.get_paddr_page());
+        m_lru.pop_back();
+        m_lru.push_front(e);
+        m_map.emplace(paddr_page, map_value{m_lru.begin(), e});
+        return std::ref(e.set_borrowed(1).set_paddr_page(paddr_page));
+    }
+
+    auto borrow_entry(uint64_t paddr_page) {
+        bool hit = false;
+        return borrow_entry(paddr_page, hit);
+    }
+
+    static bool return_entry(entry &e) {
+        if (e.get_borrowed() == 0) {
+            throw std::runtime_error{"returning page hash-tree cache entry that is not borrowed"};
+        }
+        e.set_borrowed(0);
+        return true;
+    }
+
+    constexpr auto capacity() const noexcept {
+        return m_entries.size();
+    }
+
+    void clear() noexcept {
+        m_lru.clear();
+        m_map.clear();
+        for (auto &e : m_entries) {
+            e.clear(m_pristine_page_hash_tree);
+        }
+        m_used = 0;
+    }
+
+    void clear_stats() noexcept {
+#ifdef DUMP_HASH_TREE_STATS
+        m_page_hit = 0;
+        m_page_miss = 0;
+        entry::m_inner_page_node_hashes = 0;
+        entry::m_word_hit = 0;
+        entry::m_word_miss = 0;
+#endif
+    }
+
+    ~page_hash_tree_cache() {
+#ifdef DUMP_HASH_TREE_STATS
+        auto all = m_page_hit + m_page_miss;
+        if (all > 0) {
+            std::cerr << "page hits: " << m_page_hit << '\n';
+            std::cerr << "page misses: " << m_page_miss << '\n';
+            std::cerr << "page hit rate: " << 100.0 * static_cast<double>(m_page_hit) / static_cast<double>(all)
+                      << '\n';
+        }
+        auto word_hit = entry::m_word_hit.load();
+        auto word_miss = entry::m_word_miss.load();
+        auto word_all = word_hit + word_miss;
+        if (word_all > 0) {
+            std::cerr << "word hits: " << word_hit << '\n';
+            std::cerr << "word misses: " << word_miss << '\n';
+            std::cerr << "word hit rate: " << 100.0 * static_cast<double>(word_hit) / static_cast<double>(word_all)
+                      << '\n';
+        }
+        std::cerr << "inner page node hashes: " << entry::m_inner_page_node_hashes.load() << '\n';
+#endif
+    }
+
+private:
+    using lru = boost::intrusive::list<entry>;
+    using map_value = std::pair<lru::iterator, entry &>;
+    const page_hash_tree m_pristine_page_hash_tree;
+    //??D Replace std::vector so entries can live on disk
+    std::vector<entry> m_entries;
+    //??D Replace the boost intrusive list with index-based implementation so list can live on disk as well
+    lru m_lru;
+    //??D Only the map will be reloaded from disk
+    //??D We *could* also replace the implementation, but I think this would be overkill
+    std::unordered_map<address_type, map_value> m_map;
+    size_t m_used{0};
+#ifdef DUMP_HASH_TREE_STATS
+    size_t m_page_hit;
+    size_t m_page_miss;
+#endif
+};
+
+} // namespace cartesi
+
+#endif // PAGE_HASH_TREE_CACHE_H
diff --git a/src/plic-address-range.h b/src/plic-address-range.h
index 19b36a9bb..ed1a8a7b1 100644
--- a/src/plic-address-range.h
+++ b/src/plic-address-range.h
@@ -20,9 +20,9 @@
 #include <cstdint>
 
 #include "address-range-constants.h"
+#include "address-range.h"
 #include "i-device-state-access.h"
 #include "plic-constants.h"
-#include "pristine-address-range.h"
 
 /// \file
 /// \brief Platform-Level Interrupt Controller address range.
@@ -37,7 +37,7 @@ void plic_set_pending_irq(i_device_state_access *a, uint32_t irq_id);
 /// \details This is called only by devices to remove an external interrupt notification.
 void plic_reset_pending_irq(i_device_state_access *a, uint32_t irq_id);
 
-class plic_address_range final : public pristine_address_range {
+class plic_address_range final : public address_range {
 
     static constexpr pmas_flags m_plic_flags{
         .M = false,
@@ -53,7 +53,7 @@ class plic_address_range final : public pristine_address_range {
 public:
     template <typename ABRT>
     explicit plic_address_range(ABRT abrt) :
-        pristine_address_range("PLIC device", AR_PLIC_START, AR_PLIC_LENGTH, m_plic_flags, abrt) {
+        address_range("PLIC device", AR_PLIC_START, AR_PLIC_LENGTH, m_plic_flags, abrt) {
         ;
     }
 
diff --git a/src/pristine-address-range.h b/src/pristine-address-range.h
deleted file mode 100644
index cd763f8c3..000000000
--- a/src/pristine-address-range.h
+++ /dev/null
@@ -1,59 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef PRISTINE_ADDRESS_RANGE_H
-#define PRISTINE_ADDRESS_RANGE_H
-
-#include "address-range.h"
-
-namespace cartesi {
-
-// Forward declarations
-class machine;
-
-/// \file
-/// \brief An address range that appears pristine in the state
-
-class pristine_address_range : public address_range {
-public:
-    /// \brief Constructor
-    /// \param description Description of address range for use in error messages
-    /// \param start Target physical address where range starts
-    /// \param length Length of range, in bytes
-    /// \param f Physical memory attribute flags for range
-    template <typename ABRT>
-    pristine_address_range(const char *description, uint64_t start, uint64_t length, pmas_flags f, ABRT abrt) :
-        address_range{description, start, length, f, abrt} {
-        ;
-    }
-
-    pristine_address_range(const pristine_address_range &other) = default;
-    pristine_address_range &operator=(const pristine_address_range &other) = default;
-    pristine_address_range(pristine_address_range &&other) = default;
-    pristine_address_range &operator=(pristine_address_range &&other) = default;
-    ~pristine_address_range() override = default;
-
-private:
-    bool do_peek(const machine & /*m*/, uint64_t offset, uint64_t length, const unsigned char **data,
-        unsigned char * /*scratch*/) const noexcept override {
-        *data = nullptr;
-        return contains_relative(offset, length);
-    }
-};
-
-} // namespace cartesi
-
-#endif
diff --git a/src/pristine-merkle-tree.cpp b/src/pristine-merkle-tree.cpp
index 08b65b823..ef31d26b4 100644
--- a/src/pristine-merkle-tree.cpp
+++ b/src/pristine-merkle-tree.cpp
@@ -46,14 +46,14 @@ pristine_merkle_tree::pristine_merkle_tree(int log2_root_size, int log2_word_siz
     assert(word.size() == (UINT64_C(1) << log2_word_size));
     hasher_type h;
     h.begin();
-    h.add_data(word.data(), word.size());
+    h.add_data(word);
     h.end(m_hashes[0]);
     for (unsigned i = 1; i < m_hashes.size(); ++i) {
         get_concat_hash(h, m_hashes[i - 1], m_hashes[i - 1], m_hashes[i]);
     }
 }
 
-const pristine_merkle_tree::hash_type &pristine_merkle_tree::get_hash(int log2_size) const {
+const machine_hash &pristine_merkle_tree::get_hash(int log2_size) const {
     if (log2_size < m_log2_word_size || log2_size > m_log2_root_size) {
         throw std::out_of_range{"log2_size is out of range"};
     }
diff --git a/src/pristine-merkle-tree.h b/src/pristine-merkle-tree.h
index d3230f600..f40b289fb 100644
--- a/src/pristine-merkle-tree.h
+++ b/src/pristine-merkle-tree.h
@@ -21,6 +21,7 @@
 #include <vector>
 
 #include "keccak-256-hasher.h"
+#include "machine-hash.h"
 
 /// \file
 /// \brief Pristine Merkle tree interface.
@@ -33,11 +34,6 @@ class pristine_merkle_tree {
     /// \brief Hasher class.
     using hasher_type = keccak_256_hasher;
 
-    /// \brief Storage for a hash.
-    using hash_type = hasher_type::hash_type;
-
-    using address_type = uint64_t;
-
     /// \brief Constructor
     /// \param log2_root_size Log<sub>2</sub> of root node
     /// \param log2_word_size Log<sub>2</sub> of word
@@ -47,12 +43,12 @@ class pristine_merkle_tree {
     /// \param log2_size Log<sub>2</sub> of subtree size. Must be between
     /// log2_word_size (inclusive) and log2_root_size (inclusive) passed
     /// to constructor.
-    const hash_type &get_hash(int log2_size) const;
+    const machine_hash &get_hash(int log2_size) const;
 
 private:
-    int m_log2_root_size;            ///< Log<sub>2</sub> of tree size
-    int m_log2_word_size;            ///< Log<sub>2</sub> of word size
-    std::vector<hash_type> m_hashes; ///< Vector with hashes
+    int m_log2_root_size;               ///< Log<sub>2</sub> of tree size
+    int m_log2_word_size;               ///< Log<sub>2</sub> of word size
+    std::vector<machine_hash> m_hashes; ///< Vector with hashes
 };
 
 } // namespace cartesi
diff --git a/src/ranges.h b/src/ranges.h
new file mode 100644
index 000000000..7707d594e
--- /dev/null
+++ b/src/ranges.h
@@ -0,0 +1,47 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef RANGES_H
+#define RANGES_H
+
+#include <ranges>
+
+/// \file
+/// \brief Range helper functions.
+
+namespace cartesi::views {
+
+/// \brief View that allows a range-based for bind to iterator values, instead of dereferenced values
+template <std::ranges::range R>
+    requires(std::ranges::borrowed_range<R> || std::is_lvalue_reference_v<R>)
+constexpr auto iterators(R &&r) { // NOLINT(cppcoreguidelines-missing-std-forward)
+    return std::views::iota(r.begin(), r.end());
+}
+
+/// \brief View that casts to another type
+template <typename T>
+constexpr auto cast_to = std::views::transform([](auto x) -> T { return static_cast<T>(x); });
+
+/// \brief Implementation of C++23 slice
+template <std::ranges::viewable_range R>
+constexpr auto slice(R &&r, std::ranges::range_difference_t<R> from, std::ranges::range_difference_t<R> to) {
+    auto count = std::max(to - from, std::ranges::range_difference_t<R>(0));
+    return std::forward<R>(r) | std::views::drop(from) | std::views::take(count);
+}
+
+} // namespace cartesi::views
+
+#endif
diff --git a/src/record-send-cmio-state-access.h b/src/record-send-cmio-state-access.h
index ef732603c..55fdeda38 100644
--- a/src/record-send-cmio-state-access.h
+++ b/src/record-send-cmio-state-access.h
@@ -27,11 +27,11 @@
 #include <utility>
 
 #include "access-log.h"
+#include "hash-tree-constants.h"
 #include "host-addr.h"
 #include "i-accept-scoped-notes.h"
-#include "i-hasher.h"
 #include "i-state-access.h"
-#include "machine-merkle-tree.h"
+#include "machine-hash.h"
 #include "machine.h"
 #include "meta.h"
 #include "processor-state.h"
@@ -53,16 +53,16 @@ struct i_state_access_fast_addr<record_send_cmio_state_access> {
 class record_send_cmio_state_access :
     public i_state_access<record_send_cmio_state_access>,
     public i_accept_scoped_notes<record_send_cmio_state_access> {
-    using hasher_type = machine_merkle_tree::hasher_type;
-    using hash_type = machine_merkle_tree::hash_type;
+    using hasher_type = hash_tree::hasher_type;
     // NOLINTBEGIN(cppcoreguidelines-avoid-const-or-ref-data-members)
     machine &m_m;      ///< Associated machine
     access_log &m_log; ///< Pointer to access log
     // NOLINTEND(cppcoreguidelines-avoid-const-or-ref-data-members)
 
-    static void get_hash(const access_data &data, hash_type &hash) {
+    static void get_hash(const access_data &data, machine_hash &hash) {
         hasher_type hasher;
-        get_merkle_tree_hash(hasher, data.data(), data.size(), machine_merkle_tree::get_word_size(), hash);
+        get_merkle_tree_hash(hasher, std::span<const access_data::value_type>{data.data(), data.size()},
+            HASH_TREE_WORD_SIZE, hash);
     }
 
 public:
@@ -78,19 +78,18 @@ class record_send_cmio_state_access :
     /// \param paligned Physical address in the machine state, aligned to a 64-bit word.
     /// \param text Textual description of the access.
     void log_read(uint64_t paligned, const char *text) const {
-        static_assert(machine_merkle_tree::get_log2_word_size() >= log2_size_v<uint64_t>,
-            "Merkle tree word size must be at least as large as a machine word");
+        static_assert(HASH_TREE_LOG2_WORD_SIZE >= log2_size_v<uint64_t>,
+            "hash tree word size cannot be narrower than machine word");
         if ((paligned & (sizeof(uint64_t) - 1)) != 0) {
             throw std::invalid_argument{"paligned is not aligned to word size"};
         }
-        const uint64_t pleaf_aligned = paligned & ~(machine_merkle_tree::get_word_size() - 1);
+        const uint64_t pleaf_aligned = paligned & ~(HASH_TREE_WORD_SIZE - 1);
         access a;
 
         // We can skip updating the merkle tree while getting the proof because we assume that:
         // 1) A full merkle tree update was called at the beginning of machine::log_load_cmio_input()
-        // 2) We called update_merkle_tree_page on all write accesses
-        const auto proof =
-            m_m.get_proof(pleaf_aligned, machine_merkle_tree::get_log2_word_size(), skip_merkle_tree_update);
+        // 2) We called update_hash_tree_page on all write accesses
+        const auto proof = m_m.get_proof(pleaf_aligned, HASH_TREE_LOG2_WORD_SIZE, skip_hash_tree_update);
         // We just store the sibling hashes in the access because this is the only missing piece of data needed to
         // reconstruct the proof
         a.set_sibling_hashes(proof.get_sibling_hashes());
@@ -101,9 +100,9 @@ class record_send_cmio_state_access :
         // NOLINTBEGIN(bugprone-unchecked-optional-access)
         // we log the leaf data at pleaf_aligned that contains the word at paligned
         a.get_read().emplace();
-        a.get_read().value().resize(machine_merkle_tree::get_word_size());
+        a.get_read().value().resize(HASH_TREE_WORD_SIZE);
         // read the entire leaf where the word is located
-        m_m.read_memory(pleaf_aligned, a.get_read().value().data(), machine_merkle_tree::get_word_size());
+        m_m.read_memory(pleaf_aligned, a.get_read().value().data(), HASH_TREE_WORD_SIZE);
         get_hash(a.get_read().value(), a.get_read_hash());
         // NOLINTEND(bugprone-unchecked-optional-access)
         m_log.push_access(std::move(a), text);
@@ -114,20 +113,19 @@ class record_send_cmio_state_access :
     /// \param val Value to write.
     /// \param text Textual description of the access.
     void log_before_write(uint64_t paligned, uint64_t val, const char *text) const {
-        static_assert(machine_merkle_tree::get_log2_word_size() >= log2_size_v<uint64_t>,
+        static_assert(HASH_TREE_LOG2_WORD_SIZE >= log2_size_v<uint64_t>,
             "Merkle tree word size must be at least as large as a machine word");
         if ((paligned & (sizeof(uint64_t) - 1)) != 0) {
             throw std::invalid_argument{"paligned is not aligned to word size"};
         }
         // address of the leaf that contains the word at paligned
-        const uint64_t pleaf_aligned = paligned & ~(machine_merkle_tree::get_word_size() - 1);
+        const uint64_t pleaf_aligned = paligned & ~(HASH_TREE_WORD_SIZE - 1);
         access a;
 
         // We can skip updating the merkle tree while getting the proof because we assume that:
         // 1) A full merkle tree update was called at the beginning of machine::log_load_cmio_input()
-        // 2) We called update_merkle_tree_page on all write accesses
-        const auto proof =
-            m_m.get_proof(pleaf_aligned, machine_merkle_tree::get_log2_word_size(), skip_merkle_tree_update);
+        // 2) We called update_hash_tree_page on all write accesses
+        const auto proof = m_m.get_proof(pleaf_aligned, HASH_TREE_LOG2_WORD_SIZE, skip_hash_tree_update);
         // We just store the sibling hashes in the access because this is the only missing piece of data needed to
         // reconstruct the proof
         a.set_sibling_hashes(proof.get_sibling_hashes());
@@ -138,8 +136,8 @@ class record_send_cmio_state_access :
         // NOLINTBEGIN(bugprone-unchecked-optional-access)
         // we log the entire leaf where the word is located
         a.get_read().emplace();
-        a.get_read().value().resize(machine_merkle_tree::get_word_size());
-        m_m.read_memory(pleaf_aligned, a.get_read().value().data(), machine_merkle_tree::get_word_size());
+        a.get_read().value().resize(HASH_TREE_WORD_SIZE);
+        m_m.read_memory(pleaf_aligned, a.get_read().value().data(), HASH_TREE_WORD_SIZE);
         get_hash(a.get_read().value(), a.get_read_hash());
         // the logged written data is the same as the read data, but with the word at paligned replaced by word
         a.set_written(access_data(a.get_read().value()));                    // copy the read data
@@ -156,7 +154,7 @@ class record_send_cmio_state_access :
     /// \param paligned Physical address in the machine state, aligned to a 64-bit word.
     void update_after_write(uint64_t paligned) const {
         assert((paligned & (sizeof(uint64_t) - 1)) == 0);
-        [[maybe_unused]] const bool updated = m_m.update_merkle_tree_page(paligned);
+        [[maybe_unused]] const bool updated = m_m.update_hash_tree_page(paligned);
         assert(updated);
     }
 
@@ -201,7 +199,7 @@ class record_send_cmio_state_access :
 
     void do_write_memory_with_padding(uint64_t paddr, const unsigned char *data, uint64_t data_length,
         int write_length_log2_size) const {
-        if ((paddr & (machine_merkle_tree::get_word_size() - 1)) != 0) {
+        if ((paddr & (HASH_TREE_WORD_SIZE - 1)) != 0) {
             throw std::invalid_argument("paddr is not aligned to tree leaf size");
         }
         if (data == nullptr) {
@@ -244,15 +242,15 @@ class record_send_cmio_state_access :
             m_m.fill_memory(paddr + data_length, 0, write_length - data_length);
         }
         // we have to update the merkle tree after every write
-        m_m.update_merkle_tree();
+        m_m.update_hash_tree();
 
         // log hash and written data
         // NOLINTBEGIN(bugprone-unchecked-optional-access)
         a.get_written_hash().emplace();
         hasher_type hasher{};
         const auto offset = paddr - ar.get_start();
-        get_merkle_tree_hash(hasher, ar.get_host_memory() + offset, write_length, machine_merkle_tree::get_word_size(),
-            a.get_written_hash().value());
+        get_merkle_tree_hash(hasher, std::span<const unsigned char>{ar.get_host_memory() + offset, write_length},
+            HASH_TREE_WORD_SIZE, a.get_written_hash().value());
         if (m_log.get_log_type().has_large_data()) {
             access_data &data = a.get_written().emplace(write_length);
             memcpy(data.data(), ar.get_host_memory() + offset, write_length);
diff --git a/src/record-step-state-access.h b/src/record-step-state-access.h
index e0c4395fc..58c90a7fd 100644
--- a/src/record-step-state-access.h
+++ b/src/record-step-state-access.h
@@ -23,6 +23,7 @@
 #include <vector>
 
 #include "compiler-defines.h"
+#include "hash-tree.h"
 #include "i-accept-scoped-notes.h"
 #include "i-prefer-shadow-state.h"
 #include "i-state-access.h"
@@ -47,16 +48,11 @@ class record_step_state_access :
     public i_state_access<record_step_state_access>,
     public i_accept_scoped_notes<record_step_state_access>,
     public i_prefer_shadow_state<record_step_state_access> {
-    constexpr static int TREE_LOG2_ROOT_SIZE = machine_merkle_tree::get_log2_root_size();
-    constexpr static int TREE_LOG2_PAGE_SIZE = machine_merkle_tree::get_log2_page_size();
-    constexpr static uint64_t TREE_PAGE_SIZE = UINT64_C(1) << LOG2_PAGE_SIZE;
 
-    using address_type = machine_merkle_tree::address_type;
-    using page_data_type = std::array<uint8_t, TREE_PAGE_SIZE>;
-    using pages_type = std::map<address_type, page_data_type>;
-    using hash_type = machine_merkle_tree::hash_type;
-    using sibling_hashes_type = std::vector<hash_type>;
-    using page_indices_type = std::vector<address_type>;
+    using page_data_type = std::array<uint8_t, HASH_TREE_PAGE_SIZE>;
+    using pages_type = std::map<uint64_t, page_data_type>;
+    using sibling_hashes_type = hash_tree::sibling_hashes_type;
+    using page_indices_type = std::vector<uint64_t>;
 
 public:
     struct context {
@@ -104,14 +100,14 @@ class record_step_state_access :
             throw std::runtime_error("Could not write page count to log file");
         }
         for (auto &[address, data] : m_context.touched_pages) {
-            const auto page_index = address >> TREE_LOG2_PAGE_SIZE;
+            const auto page_index = address >> HASH_TREE_LOG2_PAGE_SIZE;
             if (fwrite(&page_index, sizeof(page_index), 1, fp.get()) != 1) {
                 throw std::runtime_error("Could not write page index to log file");
             }
             if (fwrite(data.data(), data.size(), 1, fp.get()) != 1) {
                 throw std::runtime_error("Could not write page data to log file");
             }
-            static const hash_type all_zeros{};
+            static const machine_hash all_zeros{};
             if (fwrite(all_zeros.data(), sizeof(all_zeros), 1, fp.get()) != 1) {
                 throw std::runtime_error("Could not write page hash scratch to log file");
             }
@@ -131,7 +127,7 @@ class record_step_state_access :
 
     /// \brief Mark a page as touched and save its contents
     /// \param address address of the page
-    void touch_page(address_type address) const {
+    void touch_page(uint64_t address) const {
         auto page = address & ~PAGE_OFFSET_MASK;
         if (m_context.touched_pages.find(page) != m_context.touched_pages.end()) {
             return; // already saved
@@ -147,10 +143,10 @@ class record_step_state_access :
         page_indices_type page_indices{};
         // iterate in ascending order of page addresses (the container is ordered by key)
         for (const auto &[address, _] : m_context.touched_pages) {
-            page_indices.push_back(address >> TREE_LOG2_PAGE_SIZE);
+            page_indices.push_back(address >> HASH_TREE_LOG2_PAGE_SIZE);
         }
         auto next_page_index = page_indices.cbegin();
-        get_sibling_hashes_impl(0, TREE_LOG2_ROOT_SIZE - TREE_LOG2_PAGE_SIZE, page_indices, next_page_index,
+        get_sibling_hashes_impl(0, HASH_TREE_LOG2_ROOT_SIZE - HASH_TREE_LOG2_PAGE_SIZE, page_indices, next_page_index,
             sibling_hashes);
         if (next_page_index != page_indices.cend()) {
             throw std::runtime_error("get_sibling_hashes failed to consume all pages");
@@ -164,13 +160,13 @@ class record_step_state_access :
     /// \param page_indices indices of all pages
     /// \param next_page_index smallest page index not visited yet
     /// \param sibling_hashes stores the collected sibling hashes during the recursion
-    void get_sibling_hashes_impl(address_type page_index, int page_count_log2_size, page_indices_type &page_indices,
+    void get_sibling_hashes_impl(uint64_t page_index, int page_count_log2_size, page_indices_type &page_indices,
         page_indices_type::const_iterator &next_page_index, sibling_hashes_type &sibling_hashes) {
         auto page_count = UINT64_C(1) << page_count_log2_size;
         if (next_page_index == page_indices.cend() || page_index + page_count <= *next_page_index) {
             // we can skip the merkle tree update, because a full update was done before the recording started
-            sibling_hashes.push_back(m_m.get_merkle_tree_node_hash(page_index << TREE_LOG2_PAGE_SIZE,
-                page_count_log2_size + TREE_LOG2_PAGE_SIZE, skip_merkle_tree_update));
+            sibling_hashes.push_back(m_m.get_node_hash(page_index << HASH_TREE_LOG2_PAGE_SIZE,
+                page_count_log2_size + HASH_TREE_LOG2_PAGE_SIZE, skip_hash_tree_update));
         } else if (page_count_log2_size > 0) {
             get_sibling_hashes_impl(page_index, page_count_log2_size - 1, page_indices, next_page_index,
                 sibling_hashes);
diff --git a/src/replay-send-cmio-state-access.h b/src/replay-send-cmio-state-access.h
index 42688f143..ffa8ae46b 100644
--- a/src/replay-send-cmio-state-access.h
+++ b/src/replay-send-cmio-state-access.h
@@ -29,9 +29,9 @@
 #include <vector>
 
 #include "access-log.h"
+#include "hash-tree.h"
 #include "i-hasher.h"
 #include "i-state-access.h"
-#include "machine-merkle-tree.h"
 #include "meta.h"
 #include "riscv-constants.h"
 #include "shadow-registers.h"
@@ -49,17 +49,14 @@ struct i_state_access_fast_addr<replay_send_cmio_state_access> {
 
 /// \brief Allows replaying a machine::send_cmio_response() from an access log.
 class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_state_access> {
-    using tree_type = machine_merkle_tree;
-    using hash_type = tree_type::hash_type;
-    using hasher_type = tree_type::hasher_type;
-    using proof_type = tree_type::proof_type;
-
 public:
+    using hasher_type = hash_tree::hasher_type;
+
     struct context {
         /// \brief Constructor replay_send_cmio_state_access context
         /// \param log Access log to be replayed
         /// \param initial_hash Initial root hash
-        context(const access_log &log, machine_merkle_tree::hash_type initial_hash) :
+        context(const access_log &log, const machine_hash &initial_hash) :
             accesses(log.get_accesses()),
             root_hash(initial_hash) {
             ;
@@ -68,9 +65,9 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
         ///< Index of next access to ne consumed
         unsigned int next_access{};
         ///< Root hash before next access
-        machine_merkle_tree::hash_type root_hash;
+        machine_hash root_hash;
         ///< Hasher needed to verify proofs
-        machine_merkle_tree::hasher_type hasher;
+        hasher_type hasher;
     };
 
 private:
@@ -85,8 +82,8 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
         }
     }
 
-    void get_root_hash(machine_merkle_tree::hash_type &hash) const {
-        hash = m_context.root_hash;
+    machine_hash get_root_hash() const {
+        return m_context.root_hash;
     }
 
     /// \brief Checks if access log was fully consumed after reset operation is finished
@@ -113,9 +110,9 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
         }
     }
 
-    static void get_hash(machine_merkle_tree::hasher_type &hasher, const access_data &data,
-        machine_merkle_tree::hash_type &hash) {
-        get_merkle_tree_hash(hasher, data.data(), data.size(), machine_merkle_tree::get_word_size(), hash);
+    template <typename H>
+    static void get_hash(H &h, const access_data &data, machine_hash &hash) {
+        get_merkle_tree_hash(h, std::span<const unsigned char>{data.data(), data.size()}, HASH_TREE_WORD_SIZE, hash);
     }
 
     /// \brief Checks a logged read and advances log.
@@ -125,7 +122,7 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
     /// \param text Textual description of the access.
     /// \returns Value read.
     uint64_t check_read(uint64_t paligned, const char *text) const {
-        static_assert(machine_merkle_tree::get_log2_word_size() >= log2_size_v<uint64_t>,
+        static_assert(HASH_TREE_LOG2_WORD_SIZE >= log2_size_v<uint64_t>,
             "Merkle tree word size must be at least as large as a machine word");
         if ((paligned & (sizeof(uint64_t) - 1)) != 0) {
             throw std::invalid_argument{"address not aligned to word size"};
@@ -145,19 +142,19 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
         }
         if (access.get_log2_size() != log2_size_v<uint64_t>) {
             throw std::invalid_argument{"expected " + access_to_report() + " to read 2^" +
-                std::to_string(machine_merkle_tree::get_log2_word_size()) + " bytes from " + text};
+                std::to_string(HASH_TREE_LOG2_WORD_SIZE) + " bytes from " + text};
         }
         if (!access.get_read().has_value()) {
             throw std::invalid_argument{"missing read " + std::string(text) + " data at " + access_to_report()};
         }
         // NOLINTBEGIN(bugprone-unchecked-optional-access)
         const auto &read_data = access.get_read().value();
-        if (read_data.size() != machine_merkle_tree::get_word_size()) {
+        if (read_data.size() != HASH_TREE_WORD_SIZE) {
             throw std::invalid_argument{"expected read " + std::string(text) + " data to contain 2^" +
-                std::to_string(machine_merkle_tree::get_log2_word_size()) + " bytes at " + access_to_report()};
+                std::to_string(HASH_TREE_LOG2_WORD_SIZE) + " bytes at " + access_to_report()};
         }
         // check if logged read data hashes to the logged read hash
-        hash_type computed_read_hash{};
+        machine_hash computed_read_hash{};
         get_hash(m_context.hasher, read_data, computed_read_hash);
         if (access.get_read_hash() != computed_read_hash) {
             throw std::invalid_argument{"logged read data of " + std::string(text) +
@@ -170,7 +167,7 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
             throw std::invalid_argument{"Mismatch in root hash of " + access_to_report()};
         }
         m_context.next_access++;
-        const uint64_t pleaf_aligned = paligned & ~(machine_merkle_tree::get_word_size() - 1);
+        const uint64_t pleaf_aligned = paligned & ~(HASH_TREE_WORD_SIZE - 1);
         const int word_offset = static_cast<int>(paligned - pleaf_aligned);
         return get_word_access_data(read_data, word_offset);
     }
@@ -181,7 +178,7 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
     /// \param word Word value to write.
     /// \param text Textual description of the access.
     void check_write(uint64_t paligned, uint64_t word, const char *text) const {
-        static_assert(machine_merkle_tree::get_log2_word_size() >= log2_size_v<uint64_t>,
+        static_assert(HASH_TREE_LOG2_WORD_SIZE >= log2_size_v<uint64_t>,
             "Merkle tree word size must be at least as large as a machine word");
         if ((paligned & (sizeof(uint64_t) - 1)) != 0) {
             throw std::invalid_argument{"paligned not aligned to word size"};
@@ -201,7 +198,7 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
         }
         if (access.get_log2_size() != log2_size_v<uint64_t>) {
             throw std::invalid_argument{"expected " + access_to_report() + " to write 2^" +
-                std::to_string(machine_merkle_tree::get_log2_word_size()) + " bytes to " + text};
+                std::to_string(HASH_TREE_LOG2_WORD_SIZE) + " bytes to " + text};
         }
         // NOLINTBEGIN(bugprone-unchecked-optional-access)
         // check read
@@ -209,12 +206,12 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
             throw std::invalid_argument{"missing read " + std::string(text) + " data at " + access_to_report()};
         }
         const auto &read_data = access.get_read().value();
-        if (read_data.size() != machine_merkle_tree::get_word_size()) {
+        if (read_data.size() != HASH_TREE_WORD_SIZE) {
             throw std::invalid_argument{"expected overwritten data from " + std::string(text) + " to contain 2^" +
                 std::to_string(access.get_log2_size()) + " bytes at " + access_to_report()};
         }
         // check if read data hashes to the logged read hash
-        hash_type computed_read_hash{};
+        machine_hash computed_read_hash{};
         get_hash(m_context.hasher, read_data, computed_read_hash);
         if (access.get_read_hash() != computed_read_hash) {
             throw std::invalid_argument{"logged read data of " + std::string(text) +
@@ -234,14 +231,14 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
                 std::to_string(access.get_log2_size()) + " bytes at " + access_to_report()};
         }
         // check if written data hashes to the logged written hash
-        hash_type computed_written_hash{};
+        machine_hash computed_written_hash{};
         get_hash(m_context.hasher, written_data, computed_written_hash);
         if (written_hash != computed_written_hash) {
             throw std::invalid_argument{"logged written data of " + std::string(text) +
                 " does not hash to the logged written hash at " + access_to_report()};
         }
         // check if word being written matches the logged data
-        const uint64_t pleaf_aligned = paligned & ~(machine_merkle_tree::get_word_size() - 1);
+        const uint64_t pleaf_aligned = paligned & ~(HASH_TREE_WORD_SIZE - 1);
         const int word_offset = static_cast<int>(paligned - pleaf_aligned);
         const uint64_t logged_word = get_word_access_data(written_data, word_offset);
         if (word != logged_word) {
@@ -306,7 +303,7 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
         // NOLINTBEGIN(bugprone-unchecked-optional-access)
         // if read data is available then its hash and the logged read hash must match
         if (access.get_read().has_value()) {
-            hash_type computed_logged_data_hash{};
+            machine_hash computed_logged_data_hash{};
             get_hash(hasher, access.get_read().value(), computed_logged_data_hash);
             if (computed_logged_data_hash != access.get_read_hash()) {
                 throw std::invalid_argument{
@@ -318,7 +315,7 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
         }
         const auto &written_hash = access.get_written_hash().value();
         // compute hash of data argument padded with zeroes
-        hash_type computed_data_hash{};
+        machine_hash computed_data_hash{};
         auto scratch = make_unique_calloc<unsigned char>(write_length, std::nothrow_t{});
         if (!scratch) {
             throw std::runtime_error("Could not allocate scratch memory");
@@ -327,7 +324,7 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
         if (write_length > data_length) {
             memset(scratch.get() + data_length, 0, write_length - data_length);
         }
-        get_merkle_tree_hash(hasher, scratch.get(), write_length, machine_merkle_tree::get_word_size(),
+        get_merkle_tree_hash(hasher, std::span<const unsigned char>{scratch.get(), write_length}, HASH_TREE_WORD_SIZE,
             computed_data_hash);
         // check if logged written hash matches the computed data hash
         if (written_hash != computed_data_hash) {
@@ -336,7 +333,7 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
         }
         if (access.get_written().has_value()) {
             // if written data is available then its hash and the logged written hash must match
-            hash_type computed_hash;
+            machine_hash computed_hash;
             get_hash(hasher, access.get_written().value(), computed_hash);
             if (computed_hash != written_hash) {
                 throw std::invalid_argument{"written hash and written data mismatch at " + access_to_report()};
diff --git a/src/replay-step-state-access-interop.cpp b/src/replay-step-state-access-interop.cpp
index 5485c841e..8d2eaafad 100644
--- a/src/replay-step-state-access-interop.cpp
+++ b/src/replay-step-state-access-interop.cpp
@@ -17,31 +17,30 @@
 #include "replay-step-state-access-interop.h"
 
 #include <cstddef>
+#include <span>
 #include <type_traits>
 
+#include "hash-tree.h"
 #include "i-hasher.h"
-#include "machine-merkle-tree.h"
 
 using namespace cartesi;
 
-static_assert(interop_log2_root_size == machine_merkle_tree::get_log2_root_size(),
-    "interop_log2_root_size must match machine_merkle_tree::get_log2_root_size()");
-static_assert(sizeof(cartesi::machine_merkle_tree::hash_type) == sizeof(std::remove_pointer_t<interop_hash_type>),
+static_assert(interop_log2_root_size == HASH_TREE_LOG2_ROOT_SIZE,
+    "interop_log2_root_size must match HASH_TREE_LOG2_ROOT_SIZE");
+static_assert(sizeof(cartesi::machine_hash) == sizeof(std::remove_pointer_t<interop_hash_type>),
     "hash_type size mismatch");
 
 extern "C" void interop_merkle_tree_hash(const unsigned char *data, size_t size, interop_hash_type hash) {
-    machine_merkle_tree::hasher_type hasher{};
-    get_merkle_tree_hash(hasher, data, size, machine_merkle_tree::get_word_size(),
-        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        *reinterpret_cast<machine_merkle_tree::hash_type *>(hash));
+    hash_tree::hasher_type hasher{};
+    get_merkle_tree_hash(hasher, std::span<const unsigned char>{data, size}, HASH_TREE_WORD_SIZE,
+        machine_hash_view{*hash, interop_machine_hash_byte_size});
 }
 
 extern "C" void interop_concat_hash(interop_const_hash_type left, interop_const_hash_type right,
     interop_hash_type result) {
-    machine_merkle_tree::hasher_type hasher{};
+    hash_tree::hasher_type hasher{};
     // NOLINTBEGIN(cppcoreguidelines-pro-type-reinterpret-cast)
-    get_concat_hash(hasher, *reinterpret_cast<const machine_merkle_tree::hash_type *>(left),
-        *reinterpret_cast<const machine_merkle_tree::hash_type *>(right),
-        *reinterpret_cast<machine_merkle_tree::hash_type *>(result));
+    get_concat_hash(hasher, *reinterpret_cast<const machine_hash *>(left),
+        *reinterpret_cast<const machine_hash *>(right), *reinterpret_cast<machine_hash *>(result));
     // NOLINTEND(cppcoreguidelines-pro-type-reinterpret-cast)
 }
diff --git a/src/replay-step-state-access.h b/src/replay-step-state-access.h
index f7986d8a2..e8219924c 100644
--- a/src/replay-step-state-access.h
+++ b/src/replay-step-state-access.h
@@ -199,7 +199,7 @@ class replay_step_state_access :
     /// \param paddr The physical address of the page
     /// \return A pointer to the page_type structure if found, nullptr otherwise
     page_type *try_find_page(uint64_t paddr_page) const {
-        const auto page_index = paddr_page >> AR_PAGE_SIZE_LOG2;
+        const auto page_index = paddr_page >> AR_LOG2_PAGE_SIZE;
         auto pages = std::ranges::views::counted(m_context.pages, static_cast<int64_t>(m_context.page_count));
         auto it = std::ranges::lower_bound(pages, page_index, std::ranges::less{},
             [](const auto &page) { return page.index; });
@@ -290,7 +290,7 @@ class replay_step_state_access :
                 if (page_log == nullptr) {
                     continue;
                 }
-                const auto paddr_page = page_log->index << AR_PAGE_SIZE_LOG2;
+                const auto paddr_page = page_log->index << AR_LOG2_PAGE_SIZE;
                 const auto vp_offset = paddr_page - vaddr_page;
                 aliased_aligned_write<uint64_t>(vp_offset_field_haddr, vp_offset);
             }
@@ -326,7 +326,7 @@ class replay_step_state_access :
         }
         size_t next_page = 0;
         size_t next_sibling = 0;
-        auto root_hash = compute_root_hash_impl(0, interop_log2_root_size - AR_PAGE_SIZE_LOG2, next_page, next_sibling);
+        auto root_hash = compute_root_hash_impl(0, interop_log2_root_size - AR_LOG2_PAGE_SIZE, next_page, next_sibling);
         if (next_page != m_context.page_count) {
             interop_throw_runtime_error("too many pages in log");
         }
diff --git a/src/send-cmio-response.cpp b/src/send-cmio-response.cpp
index 058640687..6c129b443 100644
--- a/src/send-cmio-response.cpp
+++ b/src/send-cmio-response.cpp
@@ -21,7 +21,7 @@
 
 #include "send-cmio-response.h"
 
-#include "machine-merkle-tree.h"
+#include "hash-tree-constants.h"
 #include "pmas-constants.h"
 #include "record-send-cmio-state-access.h"
 #include "replay-send-cmio-state-access.h"
@@ -39,8 +39,8 @@ void send_cmio_response(STATE_ACCESS a, uint16 reason, bytes data, uint32 dataLe
     if (dataLength > 0) {
         // Find the write length: the smallest power of 2 that is >= dataLength and >= tree leaf size
         uint32 writeLengthLog2Size = uint32Log2(dataLength);
-        if (writeLengthLog2Size < machine_merkle_tree::get_log2_word_size()) {
-            writeLengthLog2Size = machine_merkle_tree::get_log2_word_size(); // minimum write size is the tree leaf size
+        if (writeLengthLog2Size < HASH_TREE_LOG2_WORD_SIZE) {
+            writeLengthLog2Size = HASH_TREE_LOG2_WORD_SIZE; // minimum write size is the tree leaf size
         }
         if (uint32ShiftLeft(1, writeLengthLog2Size) < dataLength) {
             writeLengthLog2Size += 1;
diff --git a/src/state-access.h b/src/state-access.h
index 927b77d26..e417d7611 100644
--- a/src/state-access.h
+++ b/src/state-access.h
@@ -504,7 +504,7 @@ class state_access :
     }
 
     bool do_get_soft_yield() const {
-        return m_m.is_soft_yield();
+        return m_m.get_soft_yield();
     }
 
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
diff --git a/src/uarch-pristine-state-hash.cpp b/src/uarch-pristine-state-hash.cpp
index 3f97941cf..6caebdf99 100644
--- a/src/uarch-pristine-state-hash.cpp
+++ b/src/uarch-pristine-state-hash.cpp
@@ -18,21 +18,21 @@
 
 #include <cstddef>
 
-#include "machine-merkle-tree.h"
+#include "machine-hash.h"
 #include "uarch-pristine.h"
 
 namespace cartesi {
 
-static machine_merkle_tree::hash_type make_uarch_pristine_state_hash() noexcept {
-    machine_merkle_tree::hash_type h;
+static machine_hash make_uarch_pristine_state_hash() noexcept {
+    machine_hash h;
     for (std::size_t i = 0; i < h.size(); ++i) {
         h[i] = uarch_pristine_hash[i];
     }
     return h;
 }
 
-const machine_merkle_tree::hash_type &get_uarch_pristine_state_hash() {
-    static const machine_merkle_tree::hash_type uarch_pristine_state_hash = make_uarch_pristine_state_hash();
+const machine_hash &get_uarch_pristine_state_hash() noexcept {
+    static const machine_hash uarch_pristine_state_hash = make_uarch_pristine_state_hash();
     return uarch_pristine_state_hash;
 }
 
diff --git a/src/uarch-pristine-state-hash.h b/src/uarch-pristine-state-hash.h
index 618ee65e6..a6278eaaf 100644
--- a/src/uarch-pristine-state-hash.h
+++ b/src/uarch-pristine-state-hash.h
@@ -17,13 +17,13 @@
 #ifndef UARCH_STATE_HASH_H
 #define UARCH_STATE_HASH_H
 
-#include "machine-merkle-tree.h"
+#include "machine-hash.h"
 
 namespace cartesi {
 
 /// \brief Gets the hash of the pristine uarch state.
 /// \details This hash is computed at compile time by the program compute-uarch-pristine-hash.cpp
-const machine_merkle_tree::hash_type &get_uarch_pristine_state_hash();
+const machine_hash &get_uarch_pristine_state_hash() noexcept;
 
 } // namespace cartesi
 
diff --git a/src/uarch-processor-state.h b/src/uarch-processor-state.h
index f23374a37..b1bfc601e 100644
--- a/src/uarch-processor-state.h
+++ b/src/uarch-processor-state.h
@@ -35,7 +35,7 @@ struct uarch_processor_state final {
     uint64_t registers_padding_[477]{}; ///< Padding to align next field to a page boundary
 };
 
-static_assert(sizeof(uarch_processor_state) % 4096 == 0, "machine state size must be multiple of a page size");
+static_assert(sizeof(uarch_processor_state) % 4096 == 0, "uarch processor state size must be multiple of a page size");
 
 } // namespace cartesi
 
diff --git a/src/uarch-record-state-access.h b/src/uarch-record-state-access.h
index d56c07e4b..2e2785851 100644
--- a/src/uarch-record-state-access.h
+++ b/src/uarch-record-state-access.h
@@ -31,7 +31,6 @@
 #include "i-hasher.h"
 #include "i-prefer-shadow-uarch-state.h"
 #include "i-uarch-state-access.h"
-#include "machine-merkle-tree.h"
 #include "machine.h"
 #include "meta.h"
 #include "riscv-constants.h"
@@ -53,17 +52,17 @@ class uarch_record_state_access :
     public i_accept_scoped_notes<uarch_record_state_access>,
     public i_prefer_shadow_uarch_state<uarch_record_state_access> {
 
-    using hasher_type = machine_merkle_tree::hasher_type;
-    using hash_type = machine_merkle_tree::hash_type;
+    using hasher_type = hash_tree::hasher_type;
 
     // NOLINTBEGIN(cppcoreguidelines-avoid-const-or-ref-data-members)
     machine &m_m;      ///< Macro machine
     access_log &m_log; ///< Access log
     // NOLINTEND(cppcoreguidelines-avoid-const-or-ref-data-members)
 
-    static auto get_hash(hasher_type &hasher, const access_data &data) {
-        hash_type hash{};
-        get_merkle_tree_hash(hasher, data.data(), data.size(), machine_merkle_tree::get_word_size(), hash);
+    template <typename H>
+    static auto get_hash(H &h, const access_data &data) {
+        machine_hash hash{};
+        get_merkle_tree_hash(h, data.data(), data.size(), HASH_TREE_WORD_SIZE, hash);
         return hash;
     }
 
@@ -77,12 +76,12 @@ class uarch_record_state_access :
 
 private:
     static std::pair<uint64_t, int> adjust_access(uint64_t paddr, int log2_size) {
-        static_assert(cartesi::log2_size_v<uint64_t> <= machine_merkle_tree::get_log2_word_size(),
+        static_assert(cartesi::log2_size_v<uint64_t> <= HASH_TREE_LOG2_WORD_SIZE,
             "Merkle tree word size must not be smaller than machine word size");
         if (((paddr >> log2_size) << log2_size) != paddr) {
             throw std::invalid_argument{"misaligned access"};
         }
-        const auto log2_word_size = machine_merkle_tree::get_log2_word_size();
+        const auto log2_word_size = HASH_TREE_LOG2_WORD_SIZE;
         const auto log2_access_size = std::max(log2_size, log2_word_size);
         const auto access_paddr = (paddr >> log2_access_size) << log2_access_size;
         return {access_paddr, log2_access_size};
@@ -103,13 +102,13 @@ class uarch_record_state_access :
 
     void log_access_siblings_and_read_hash(access &a, uint64_t paddr, int log2_size) const {
         // Since the tree was updated before we started collecting the log, we only update after writes
-        const auto proof = m_m.get_proof(paddr, log2_size, skip_merkle_tree_update);
+        const auto proof = m_m.get_proof(paddr, log2_size, skip_hash_tree_update);
         // The only pieces of data we use from the proof are the target hash and the siblings
         a.set_sibling_hashes(proof.get_sibling_hashes());
         a.set_read_hash(proof.get_target_hash());
     }
 
-    static void log_written_hash(access &a, const hash_type &written_hash) {
+    static void log_written_hash(access &a, const machine_hash &written_hash) {
         a.get_written_hash().emplace(written_hash);
     }
 
@@ -170,7 +169,7 @@ class uarch_record_state_access :
         const auto [access_paddr, access_log2_size] = adjust_access(paddr, log2_size);
         log_access_siblings_and_read_hash(a, access_paddr, access_log2_size);
         // We *need* the read data for small writes, because we splice the written into it
-        if (log2_size < machine_merkle_tree::get_log2_word_size()) {
+        if (log2_size < HASH_TREE_LOG2_WORD_SIZE) {
             std::ignore = log_read_data(a, access_paddr, access_log2_size);
         } else {
             log_read_data_if_requested(a, access_paddr, access_log2_size);
@@ -178,9 +177,9 @@ class uarch_record_state_access :
         // Call functor to perform the write and update the tree
         write_and_update();
         // The functor updated the tree, so we don't do it again
-        log_written_hash(a, m_m.get_merkle_tree_node_hash(access_paddr, access_log2_size, skip_merkle_tree_update));
+        log_written_hash(a, m_m.get_node_hash(access_paddr, access_log2_size, skip_hash_tree_update));
         // We don't *need* the written for small writes, but it is convenient to always have it (for debugging purposes)
-        if (log2_size < machine_merkle_tree::get_log2_word_size()) {
+        if (log2_size < HASH_TREE_LOG2_WORD_SIZE) {
             log_written_data(a, access_paddr, access_log2_size);
         } else {
             log_written_data_if_requested(a, access_paddr, access_log2_size);
@@ -193,7 +192,7 @@ class uarch_record_state_access :
             machine_reg_address(reg), log2_size_v<uint64_t>,
             [this, reg, val]() {
                 m_m.write_reg(reg, val);
-                if (!m_m.update_merkle_tree_page(machine_reg_address(reg))) {
+                if (!m_m.update_hash_tree_page(machine_reg_address(reg))) {
                     throw std::invalid_argument{"error updating Merkle tree"};
                 };
             },
@@ -227,7 +226,7 @@ class uarch_record_state_access :
             paddr, log2_size_v<uint64_t>,
             [this, paddr, val]() {
                 m_m.write_word(paddr, val);
-                if (!m_m.update_merkle_tree_page(paddr)) {
+                if (!m_m.update_hash_tree_page(paddr)) {
                     throw std::invalid_argument{"error updating Merkle tree"};
                 };
             },
@@ -242,7 +241,7 @@ class uarch_record_state_access :
             [this, set_index, slot_index, vaddr_page, vp_offset, pma_index]() {
                 m_m.write_shadow_tlb(set_index, slot_index, vaddr_page, vp_offset, pma_index);
                 // Entire slot is in a single page
-                if (!m_m.update_merkle_tree_page(shadow_tlb_get_abs_addr(set_index, slot_index))) {
+                if (!m_m.update_hash_tree_page(shadow_tlb_get_abs_addr(set_index, slot_index))) {
                     throw std::invalid_argument{"error updating Merkle tree"};
                 };
             },
@@ -253,7 +252,7 @@ class uarch_record_state_access :
         static_assert(SHADOW_TLB_SLOT_SIZE == sizeof(shadow_tlb_slot), "shadow TLB slot size is wrong");
         static_assert((UINT64_C(1) << SHADOW_TLB_SLOT_LOG2_SIZE) == SHADOW_TLB_SLOT_SIZE,
             "shadow TLB slot log2 size is wrong");
-        static_assert(SHADOW_TLB_SLOT_LOG2_SIZE >= machine_merkle_tree::get_log2_word_size(),
+        static_assert(SHADOW_TLB_SLOT_LOG2_SIZE >= HASH_TREE_LOG2_WORD_SIZE,
             "shadow TLB slot must fill at least an entire Merkle tree word");
     }
 
@@ -266,7 +265,7 @@ class uarch_record_state_access :
             [this]() {
                 m_m.reset_uarch();
                 // reset_uarch() marks all modified pages as dirty
-                if (!m_m.update_merkle_tree()) {
+                if (!m_m.update_hash_tree()) {
                     throw std::invalid_argument{"error updating Merkle tree"};
                 }
             },
diff --git a/src/uarch-replay-state-access.h b/src/uarch-replay-state-access.h
index b651b3170..faa72d128 100644
--- a/src/uarch-replay-state-access.h
+++ b/src/uarch-replay-state-access.h
@@ -28,11 +28,11 @@
 #include <vector>
 
 #include "access-log.h"
+#include "hash-tree.h"
 #include "i-accept-scoped-notes.h"
 #include "i-hasher.h"
 #include "i-prefer-shadow-uarch-state.h"
 #include "i-uarch-state-access.h"
-#include "machine-merkle-tree.h"
 #include "meta.h"
 #include "shadow-tlb.h"
 #include "shadow-uarch-state.h"
@@ -45,17 +45,17 @@ class uarch_replay_state_access :
     public i_uarch_state_access<uarch_replay_state_access>,
     public i_accept_scoped_notes<uarch_replay_state_access>,
     public i_prefer_shadow_uarch_state<uarch_replay_state_access> {
-    using tree_type = machine_merkle_tree;
-    using hash_type = tree_type::hash_type;
-    using hasher_type = tree_type::hasher_type;
-    using proof_type = tree_type::proof_type;
+
+    using proof_type = hash_tree::proof_type;
 
 public:
+    using hasher_type = hash_tree::hasher_type;
+
     struct context {
         /// \brief Constructor replay_send_cmio_state_access context
         /// \param log Access log to be replayed
         /// \param initial_hash Initial root hash
-        context(const access_log &log, machine_merkle_tree::hash_type initial_hash) :
+        context(const access_log &log, const machine_hash &initial_hash) :
             accesses(log.get_accesses()),
             root_hash(initial_hash) {
             ;
@@ -64,9 +64,9 @@ class uarch_replay_state_access :
         ///< Index of next access to ne consumed
         unsigned int next_access{};
         ///< Root hash before next access
-        machine_merkle_tree::hash_type root_hash;
+        machine_hash root_hash;
         ///< Hasher needed to verify proofs
-        machine_merkle_tree::hasher_type hasher;
+        hasher_type hasher;
     };
 
 private:
@@ -84,14 +84,15 @@ class uarch_replay_state_access :
         }
     }
 
-    void get_root_hash(hash_type &hash) const {
-        hash = m_context.root_hash;
+    machine_hash get_root_hash() const {
+        return m_context.root_hash;
     }
 
 private:
     static auto get_hash(hasher_type &hasher, const access_data &data) {
-        hash_type hash{};
-        get_merkle_tree_hash(hasher, data.data(), data.size(), machine_merkle_tree::get_word_size(), hash);
+        machine_hash hash{};
+        get_merkle_tree_hash(hasher, std::span<const unsigned char>{data.data(), data.size()}, HASH_TREE_WORD_SIZE,
+            hash);
         return hash;
     }
 
@@ -127,9 +128,9 @@ class uarch_replay_state_access :
     }
 
     static std::pair<uint64_t, int> adjust_access(uint64_t paddr, int log2_size) {
-        static_assert(cartesi::log2_size_v<uint64_t> <= machine_merkle_tree::get_log2_word_size(),
+        static_assert(cartesi::log2_size_v<uint64_t> <= HASH_TREE_LOG2_WORD_SIZE,
             "Merkle tree word size must not be smaller than machine word size");
-        const auto log2_word_size = machine_merkle_tree::get_log2_word_size();
+        const auto log2_word_size = HASH_TREE_LOG2_WORD_SIZE;
         const auto log2_access_size = std::max(log2_size, log2_word_size);
         const auto access_paddr = (paddr >> log2_access_size) << log2_access_size;
         return {access_paddr, log2_access_size};
@@ -182,7 +183,7 @@ class uarch_replay_state_access :
         return proof;
     }
 
-    const auto &check_written_hash(const access &a, const hash_type &expected_hash, const char *text) const {
+    const auto &check_written_hash(const access &a, const machine_hash &expected_hash, const char *text) const {
         if (!a.get_written_hash().has_value()) {
             throw std::invalid_argument{"missing written hash of " + std::string(text) + " in " + access_to_report()};
         }
@@ -210,7 +211,7 @@ class uarch_replay_state_access :
         // NOLINTEND(bugprone-unchecked-optional-access)
     }
 
-    void check_written_data_if_there(const access &a, const hash_type &written_hash, const char *text) const {
+    void check_written_data_if_there(const access &a, const machine_hash &written_hash, const char *text) const {
         if (!a.get_written().has_value()) {
             return;
         }
@@ -234,11 +235,11 @@ class uarch_replay_state_access :
         // NOLINTEND(bugprone-unchecked-optional-access)
     }
 
-    void update_root_hash(const proof_type &proof, const hash_type &written_hash) const {
+    void update_root_hash(const proof_type &proof, const machine_hash &written_hash) const {
         m_context.root_hash = proof.bubble_up(m_context.hasher, written_hash);
     }
 
-    void check_write_access(uint64_t paddr, uint64_t log2_size, const hash_type &expected_hash,
+    void check_write_access(uint64_t paddr, uint64_t log2_size, const machine_hash &expected_hash,
         const char *text) const {
         const auto &a = check_access(text);
         check_access_type(a, access_type::write, text);
@@ -296,15 +297,13 @@ class uarch_replay_state_access :
         static_assert(SHADOW_TLB_SLOT_SIZE == sizeof(shadow_tlb_slot), "shadow TLB slot size is wrong");
         static_assert((UINT64_C(1) << SHADOW_TLB_SLOT_LOG2_SIZE) == SHADOW_TLB_SLOT_SIZE,
             "shadow TLB slot log2 size is wrong");
-        static_assert(SHADOW_TLB_SLOT_LOG2_SIZE >= machine_merkle_tree::get_log2_word_size(),
+        static_assert(SHADOW_TLB_SLOT_LOG2_SIZE >= HASH_TREE_LOG2_WORD_SIZE,
             "shadow TLB slot must fill at least an entire Merkle tree word");
         shadow_tlb_slot slot_data{};
         shadow_tlb_fill_slot(vaddr_page, vp_offset, pma_index, slot_data);
-        hash_type slot_hash{};
         // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        get_merkle_tree_hash(m_context.hasher, reinterpret_cast<uint8_t *>(&slot_data), sizeof(slot_data),
-            machine_merkle_tree::get_word_size(), slot_hash);
-        return slot_hash;
+        const std::span<const unsigned char> slot_data_span{reinterpret_cast<uint8_t *>(&slot_data), sizeof(slot_data)};
+        return get_merkle_tree_hash(m_context.hasher, slot_data_span, HASH_TREE_WORD_SIZE);
     }
 
     // -----
diff --git a/src/virtio-address-range.cpp b/src/virtio-address-range.cpp
index 25e196889..1450c7ec7 100644
--- a/src/virtio-address-range.cpp
+++ b/src/virtio-address-range.cpp
@@ -305,7 +305,7 @@ bool virtq::consume_desc(i_device_state_access *a, uint16_t desc_idx, uint32_t w
 
 virtio_address_range::virtio_address_range(const char *description, uint64_t start, uint64_t length,
     uint32_t virtio_idx, uint32_t device_id, uint64_t device_features, uint32_t config_space_size) :
-    pristine_address_range(description, start, length, m_virtio_flags,
+    address_range(description, start, length, m_virtio_flags,
         [](const char *err) { throw std::invalid_argument{err}; }),
     virtio_idx(virtio_idx),
     device_id(device_id),
diff --git a/src/virtio-address-range.h b/src/virtio-address-range.h
index 1126df5f6..22f0c736a 100644
--- a/src/virtio-address-range.h
+++ b/src/virtio-address-range.h
@@ -21,8 +21,8 @@
 #include <cstdint>
 #include <cstring>
 
+#include "address-range.h"
 #include "os.h"
-#include "pristine-address-range.h"
 
 namespace cartesi {
 
@@ -243,7 +243,7 @@ struct virtq {
 };
 
 /// \brief VirtIO device common interface
-class virtio_address_range : public pristine_address_range {
+class virtio_address_range : public address_range {
     uint32_t virtio_idx = 0;          ///< VirtIO device index
     uint32_t int_status = 0;          ///< Interrupt status mask (see virtio_status)
     uint32_t device_id = 0;           ///< Device id (see virtio_devices)
diff --git a/src/virtio-p9fs-address-range.cpp b/src/virtio-p9fs-address-range.cpp
index 7719af652..447317b45 100644
--- a/src/virtio-p9fs-address-range.cpp
+++ b/src/virtio-p9fs-address-range.cpp
@@ -1186,7 +1186,7 @@ bool virtio_p9fs_address_range::do_on_device_queue_available(i_device_state_acce
 #endif
                 return send_error(msg, tag, P9_EPROTO);
         }
-    } catch (std::bad_alloc &e) {
+    } catch (const std::bad_alloc &e) {
         // Both std::string and std::unordered_map may throw std::bad_alloc when out of memory
         return send_error(msg, tag, P9_EOPNOTSUPP);
     } catch (...) {
diff --git a/tests/Makefile b/tests/Makefile
index fadc12612..07d006819 100644
--- a/tests/Makefile
+++ b/tests/Makefile
@@ -190,6 +190,9 @@ test-machine-with-log-step:
 test-uarch:
 	$(LUA) ./lua/cartesi-machine-tests.lua --jobs=$(NUM_JOBS) run_uarch
 
+test-hash-tree:
+	$(LUA) ./lua/hash-tree.lua
+
 test-uarch-compare:
 	$(LUA) ./lua/cartesi-machine-tests.lua --test="^rv64ui.*$$" --concurrency=update_merkle_tree:1 --jobs=$(NUM_JOBS) run_host_and_uarch
 
@@ -257,7 +260,7 @@ coverage-report: $(COVERAGE_OUTPUT_DIR)
 export LLVM_PROFILE_FILE=coverage-%p.profraw
 endif
 
-test: test-save-and-load test-yield-and-save test-machine test-uarch test-uarch-rv64ui test-uarch-interpreter test-lua test-jsonrpc test-c-api test-hash test-cmio test-machine-with-log-step
+test: test-save-and-load test-yield-and-save test-machine test-uarch test-uarch-rv64ui test-uarch-interpreter test-hash-tree test-lua test-jsonrpc test-c-api test-hash test-cmio test-machine-with-log-step
 
 lint format check-format:
 	@$(MAKE) -C misc $@
diff --git a/tests/lua/cartesi-machine-tests.lua b/tests/lua/cartesi-machine-tests.lua
index ebae54fc0..11ee32934 100755
--- a/tests/lua/cartesi-machine-tests.lua
+++ b/tests/lua/cartesi-machine-tests.lua
@@ -395,7 +395,7 @@ local json_list = false
 local periodic_action = false
 local periodic_action_period = math.maxinteger
 local periodic_action_start = 0
-local concurrency_update_merkle_tree = util.parse_number(os.getenv("CARTESI_CONCURRENCY_UPDATE_MERKLE_TREE")) or 0
+local concurrency_update_hash_tree = util.parse_number(os.getenv("CARTESI_CONCURRENCY_UPDATE_HASH_TREE")) or 0
 
 -- List of supported options
 -- Options are processed in order
@@ -520,11 +520,11 @@ local options = {
                 return false
             end
             local c = util.parse_options(opts, {
-                update_merkle_tree = true,
+                update_hash_tree = true,
             })
-            c.update_merkle_tree =
-                assert(util.parse_number(c.update_merkle_tree), "invalid update_merkle_tree number in " .. all)
-            concurrency_update_merkle_tree = c.update_merkle_tree
+            c.update_hash_tree =
+                assert(util.parse_number(c.update_hash_tree), "invalid update_hash_tree number in " .. all)
+            concurrency_update_hash_tree = c.update_hash_tree
             return true
         end,
     },
@@ -618,7 +618,7 @@ local function build_machine(ram_image)
     end
     local runtime = {
         concurrency = {
-            update_merkle_tree = concurrency_update_merkle_tree,
+            update_hash_tree = concurrency_update_hash_tree,
         },
     }
     if remote_address then
diff --git a/tests/lua/cmio-test.lua b/tests/lua/cmio-test.lua
index 399f4181a..f89f2def8 100755
--- a/tests/lua/cmio-test.lua
+++ b/tests/lua/cmio-test.lua
@@ -114,7 +114,7 @@ local MAX_MCYCLE = -1
 local function load_machine(name)
     local runtime = {
         concurrency = {
-            update_merkle_tree = 0,
+            update_hash_tree = 0,
         },
         skip_root_hash_check = true,
         skip_root_hash_store = true,
@@ -263,7 +263,7 @@ for _, dapp in pairs({ "ioctl", "http" }) do
     local suffix = "-" .. dapp
     local desc = " (" .. machine_type .. "," .. dapp .. ")"
     do_test(
-        "merkle tree state must match and not reset for each advance" .. desc,
+        "hash tree state must match and not reset for each advance" .. desc,
         "advance-state-machine" .. suffix,
         function(machine)
             local hashes = {}
diff --git a/tests/lua/hash-tree.lua b/tests/lua/hash-tree.lua
new file mode 100755
index 000000000..55ac01f95
--- /dev/null
+++ b/tests/lua/hash-tree.lua
@@ -0,0 +1,272 @@
+#!/usr/bin/env lua5.4
+
+-- Copyright Cartesi and individual authors (see AUTHORS)
+-- SPDX-License-Identifier: LGPL-3.0-or-later
+--
+-- This program is free software: you can redistribute it and/or modify it under
+-- the terms of the GNU Lesser General Public License as published by the Free
+-- Software Foundation, either version 3 of the License, or (at your option) any
+-- later version.
+--
+-- This program is distributed in the hope that it will be useful, but WITHOUT ANY
+-- WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+-- PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+--
+-- You should have received a copy of the GNU Lesser General Public License along
+-- with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+--
+local cartesi = require("cartesi")
+local test_util = require("cartesi.tests.util")
+local tohex = test_util.tohex
+
+local function stderr(...)
+    io.stderr:write((string.format(...)))
+end
+
+local function bit_ceil(n)
+    if n == 0 then
+        return 0
+    end
+    n = n - 1
+    n = n | (n >> 1)
+    n = n | (n >> 2)
+    n = n | (n >> 4)
+    n = n | (n >> 8)
+    n = n | (n >> 16)
+    n = n | (n >> 32)
+    return n + 1
+end
+
+local LOG2_ROOT_SIZE = 64
+local LOG2_PAGE_SIZE = 12
+local PAGE_SIZE = 1 << LOG2_PAGE_SIZE
+local LOG2_WORD_SIZE = 5
+local WORD_SIZE = 1 << LOG2_WORD_SIZE
+
+local function get_sibling_address(address, log2_size)
+    local bit = 1 << log2_size
+    local mask = ~(bit - 1)
+    return (address ~ bit) & mask
+end
+
+local function get_aligned_address(address, log2_size)
+    local bit = 1 << log2_size
+    local mask = ~(bit - 1)
+    return address & mask
+end
+
+local function get_proof(m, target_address, log2_target_size)
+    local proof = {
+        log2_root_size = LOG2_ROOT_SIZE,
+        log2_target_size = log2_target_size,
+        root_hash = m:get_root_hash(),
+        target_address = target_address,
+        target_hash = m:get_node_hash(target_address, log2_target_size),
+        sibling_hashes = {},
+    }
+    for log2_size = log2_target_size, 63 do
+        table.insert(proof.sibling_hashes, m:get_node_hash(get_sibling_address(target_address, log2_size), log2_size))
+    end
+    return proof
+end
+
+local function compare_proofs(p1, p2, padding)
+    padding = padding or ""
+    if p1.target_address ~= p2.target_address then
+        stderr("%starget address mismatch\n", padding)
+        return false
+    end
+    if p1.log2_target_size ~= p2.log2_target_size then
+        stderr("%slog2_size mismatch\n", padding)
+        return false
+    end
+    if p1.root_hash ~= p2.root_hash then
+        stderr("%sroot hash mismatch\n", padding)
+        return false
+    end
+    if p1.target_hash ~= p2.target_hash then
+        stderr("%starget hash mismatch\n", padding)
+        return false
+    end
+    if #p1.sibling_hashes ~= #p2.sibling_hashes then
+        stderr("%starget hash mismatch\n", padding)
+        return false
+    end
+    for i = 1, #p1.sibling_hashes do
+        if p1.sibling_hashes[i] ~= p2.sibling_hashes[i] then
+            stderr("%ssibling hash mismatch (%d)\n", padding, i + p1.log2_target_size - 1)
+            return false
+        end
+    end
+    return true
+end
+
+local function check_proof(proof)
+    local hash = proof.target_hash
+    for log2_size = proof.log2_target_size, proof.log2_root_size - 1 do
+        local bit = 1 << log2_size
+        local first, second
+        local sibling_hash = proof.sibling_hashes[log2_size - proof.log2_target_size + 1]
+        if (proof.target_address & bit) ~= 0 then
+            first, second = sibling_hash, hash
+        else
+            first, second = hash, sibling_hash
+        end
+        hash = cartesi.keccak(first, second)
+    end
+    return hash == proof.root_hash
+end
+
+local config = {
+    hash_tree = {
+        phtc_size = 0x800, -- default
+    },
+    ram = {
+        backing_store = {
+            data_filename = test_util.tests_path .. "rv64ui-p-addi.bin",
+        },
+        length = 0x10000,
+    },
+    flash_drive = {
+        { start = 0x90000000, length = 0x100000 },
+        { start = 0xa0000000, length = 0x100000 },
+    },
+}
+
+local function check_root_hash(m)
+    local sh = test_util.calculate_emulator_hash(m)
+    local rh = m:get_root_hash()
+    local nh = m:get_node_hash(0, LOG2_ROOT_SIZE)
+    if sh ~= nh or sh ~= rh then
+        stderr("    0x%.16s state hash \n", tohex(sh))
+        stderr("    0x%.16s root hash \n", tohex(rh))
+        stderr("    0x%.16s node hash \n", tohex(nh))
+        os.exit(1)
+    end
+end
+
+local machine = cartesi.machine(config)
+check_root_hash(machine)
+machine:run(math.maxinteger)
+check_root_hash(machine)
+
+local interesting_pages = {}
+-- add first, middle, and last page of each range and gap
+local last_end = 0
+for _, v in ipairs(machine:get_address_ranges()) do
+    if math.ult(v.start, last_end) then
+        stderr("range %s, when rounded up to power of two length, overlaps with previous range", v.description)
+        os.exit(1)
+    end
+    if last_end < v.start then
+        local gap = { start = last_end, length = v.start - last_end, description = "gap" }
+        local s = last_end
+        local e = v.start - PAGE_SIZE
+        local m = (((s + e) / 2) >> LOG2_PAGE_SIZE) << LOG2_PAGE_SIZE
+        table.insert(interesting_pages, { s, gap })
+        if not math.ult(s + PAGE_SIZE, m) then
+            table.insert(interesting_pages, { m, gap })
+        end
+        if not math.ult(m + PAGE_SIZE, e) then
+            table.insert(interesting_pages, { e, gap })
+        end
+    end
+    local s = v.start
+    local e = s + v.length - PAGE_SIZE
+    local m = (((s + e) / 2) >> LOG2_PAGE_SIZE) << LOG2_PAGE_SIZE
+    if not math.ult(s + PAGE_SIZE, m) then
+        table.insert(interesting_pages, { m, v })
+    end
+    if not math.ult(m + PAGE_SIZE, e) then
+        table.insert(interesting_pages, { e, v })
+    end
+    table.insert(interesting_pages, { s, v })
+    last_end = v.start + bit_ceil(v.length)
+end
+table.insert(interesting_pages, { last_end, { start = last_end, length = -last_end, description = "pad" } })
+table.insert(interesting_pages, { -PAGE_SIZE, { start = last_end, length = -last_end, description = "pad" } })
+
+-- check all page hashes
+print("checking all page hashes")
+for _, v in ipairs(machine:get_address_ranges()) do
+    for address = v.start, v.start + v.length - 1, PAGE_SIZE do
+        local h1 = machine:get_node_hash(address, LOG2_PAGE_SIZE)
+        local h2 = test_util.merkle_hash(machine:read_memory(address, PAGE_SIZE), 0, LOG2_PAGE_SIZE)
+        if h1 ~= h2 then
+            stderr("hash mismatch on page 0x%016x (offset 0x%016x in %s)\n", address, address - v.start, v.description)
+            stderr("    0x%.16s... vs 0x%.16s...\n", tohex(h1), tohex(h2))
+            os.exit(1)
+        end
+    end
+end
+
+stderr("checking all hashes in the page hash tree for a few pages\n")
+for _, p in ipairs(interesting_pages) do
+    local page, v = table.unpack(p)
+    stderr("    page 0x%016x is in %s 0x%016x:0x%x\n", page, v.description, v.start, v.length)
+    local hashes = {}
+    for address = page, page + PAGE_SIZE - 1, WORD_SIZE do
+        local h1 = machine:get_node_hash(address, LOG2_WORD_SIZE)
+        local word = machine:read_memory(address, WORD_SIZE)
+        local h2 = cartesi.keccak(word)
+        if h1 ~= h2 then
+            stderr("        hash mismatch on word 0x%016x (%u)\n", address, address)
+            stderr("            0x%.16s... vs 0x%.16s...\n", tohex(h1), tohex(h2))
+            os.exit(1)
+        end
+        hashes[#hashes + 1] = h2
+    end
+    for log2_size = LOG2_WORD_SIZE + 1, LOG2_PAGE_SIZE do
+        local new_hashes = {}
+        for i = 1, #hashes - 1, 2 do
+            new_hashes[#new_hashes + 1] = cartesi.keccak(hashes[i], hashes[i + 1])
+        end
+        hashes = new_hashes
+        for i = 1, #hashes do
+            local address = page + (i - 1) * (1 << log2_size)
+            local h1 = machine:get_node_hash(address, log2_size)
+            local h2 = hashes[i]
+            if h1 ~= h2 then
+                stderr("        hash mismatch on 0x%016x:%d\n", address, log2_size)
+                stderr("            0x%.16s... vs 0x%.16s...\n", tohex(h1), tohex(h2))
+                os.exit(1)
+            end
+        end
+    end
+end
+
+stderr("checking proofs for all words (and up) in a few pages\n")
+for log2_size = LOG2_WORD_SIZE, LOG2_ROOT_SIZE - 1 do
+    stderr("  checking log2 size %u ---\n", log2_size)
+    local size = 1 << log2_size
+    local last_address = -1
+    for _, p in ipairs(interesting_pages) do
+        local page = table.unpack(p)
+        local base = get_aligned_address(page, log2_size)
+        if math.ult(last_address, base) or last_address == -1 then
+            if base ~= last_address then
+                for address = base, base + size - 1, size do
+                    if address ~= last_address then
+                        local mproof = machine:get_proof(address, log2_size)
+                        local oproof = get_proof(machine, address, log2_size)
+                        if not compare_proofs(mproof, oproof, "        ") then
+                            stderr("    proof mismatch for offset 0x%016x (%u)\n", address, address)
+                        end
+                        if not check_proof(oproof) then
+                            stderr("    test proof for offset 0x%016x (%u) failed\n", address, address)
+                            os.exit(1)
+                        end
+                        if not check_proof(mproof) then
+                            stderr("    machine proof for offset 0x%016x (%u) failed\n", address, address)
+                            os.exit(1)
+                        end
+                    end
+                    last_address = address
+                end
+            end
+            last_address = get_aligned_address(base + size - 1, log2_size)
+        end
+    end
+end
+
+stderr("ok\n")
diff --git a/tests/lua/machine-bind.lua b/tests/lua/machine-bind.lua
index 9889c7037..c37609128 100755
--- a/tests/lua/machine-bind.lua
+++ b/tests/lua/machine-bind.lua
@@ -23,7 +23,7 @@ local jsonrpc
 
 local remote_address
 local test_path = "./"
-local concurrency_update_merkle_tree = util.parse_number(os.getenv("CARTESI_CONCURRENCY_UPDATE_MERKLE_TREE")) or 0
+local concurrency_update_hash_tree = util.parse_number(os.getenv("CARTESI_CONCURRENCY_UPDATE_MERKLE_TREE")) or 0
 
 local lua_cmd = arg[-1] .. " -e "
 
@@ -53,10 +53,10 @@ where options are:
     configures the number of threads used in some implementation parts.
 
     <key>:<value> is one of
-        update_merkle_tree:<number>
+        update_hash_tree:<number>
 
-        update_merkle_tree (optional)
-        defines the number of threads to use while calculating the merkle tree.
+        update_hash_tree (optional)
+        defines the number of threads to use while calculating the hash tree.
         when omitted or defined as 0, the number of hardware threads is used if
         it can be identified or else a single thread is used.
 
@@ -115,11 +115,11 @@ local options = {
                 return false
             end
             local c = util.parse_options(opts, {
-                update_merkle_tree = true,
+                update_hash_tree = true,
             })
-            c.update_merkle_tree =
-                assert(util.parse_number(c.update_merkle_tree), "invalid update_merkle_tree number in " .. all)
-            concurrency_update_merkle_tree = c.update_merkle_tree
+            c.update_hash_tree =
+                assert(util.parse_number(c.update_hash_tree), "invalid update_hash_tree number in " .. all)
+            concurrency_update_hash_tree = c.update_hash_tree
             return true
         end,
     },
@@ -241,7 +241,7 @@ local function build_machine_config(config_options)
     }
     local runtime = {
         concurrency = {
-            update_merkle_tree = concurrency_update_merkle_tree,
+            update_hash_tree = concurrency_update_hash_tree,
         },
     }
     return config, runtime
@@ -286,7 +286,7 @@ do_test("machine should have default config shadow register values", function(ma
     end
 end)
 
-print("\n\ntesting merkle tree get_proof for values for registers")
+print("\n\ntesting hash tree get_proof for values for registers")
 do_test("should provide proof for values in registers", function(machine)
     local initial_reg_values = get_cpu_reg_test_values()
     initial_reg_values.mvendorid = nil
@@ -462,10 +462,10 @@ do_test("should return default machine config", function(machine)
     test_config(machine:get_default_config())
 end)
 
-print("\n\n test verifying integrity of the merkle tree")
-do_test("verify_merkle_tree should return true", function(machine)
-    -- Verify starting merkle tree
-    assert(machine:verify_merkle_tree(), "error, non consistent merkle tree")
+print("\n\n test verifying integrity of the hash tree")
+do_test("verify_hash_tree should return true", function(machine)
+    -- Verify starting hash tree
+    assert(machine:verify_hash_tree(), "error, non consistent hash tree")
 end)
 
 print("\n\n test calculation of initial root hash")
@@ -773,7 +773,7 @@ test_util.make_do_test(build_machine, machine_type, {
     uarch = {
         ram = { backing_store = { data_filename = test_util.create_test_uarch_program(uarch_proof_step_program) } },
     },
-})("merkle tree must be consistent when stepping alternating with and without proofs", function(machine)
+})("hash tree must be consistent when stepping alternating with and without proofs", function(machine)
     local t0 = 5
     local t1 = 6
     local t2 = 7
@@ -1463,7 +1463,7 @@ test_util.make_do_test(build_machine, machine_type, {
             backing_store = { data_filename = test_util.create_test_uarch_program(uarch_store_double_in_t0_to_t1) },
         },
     },
-})("Log of word access unaligned to merkle tree leaf ", function(machine)
+})("Log of word access unaligned to hash tree leaf ", function(machine)
     local leaf_size = 1 << cartesi.TREE_LOG2_WORD_SIZE
     local word_size = 8
     local t0 = 5 -- x5 register
diff --git a/tests/lua/machine-test.lua b/tests/lua/machine-test.lua
index a39490169..3a54b927e 100755
--- a/tests/lua/machine-test.lua
+++ b/tests/lua/machine-test.lua
@@ -134,7 +134,7 @@ local function build_machine(type, config, runtime_config)
     }
     runtime_config = runtime_config or {
         concurrency = {
-            update_merkle_tree = 0,
+            update_hash_tree = 0,
         },
     }
     if type ~= "local" then
@@ -309,8 +309,8 @@ do_test("proof  and root hash should match", function(machine)
 
     machine:write_memory(0x8000000F, "mydataol12345678", 0x10)
 
-    local verify = machine:verify_merkle_tree()
-    assert(verify, "verify merkle tree failed")
+    local verify = machine:verify_hash_tree()
+    assert(verify, "verify hash tree failed")
 
     -- Find proof for first KB of ram
     local ram_proof = machine:get_proof(ram_address_start, 10)
@@ -332,12 +332,6 @@ do_test("proof  and root hash should match", function(machine)
     assert(ram_proof.target_hash == calculated_hash, "hash does not match after memory is written")
 end)
 
-print("\n\n check dirty page maps")
-do_test("dirty page maps should be consistent", function(machine)
-    -- Verify dirty page maps
-    assert(machine:verify_dirty_page_maps(), "error verifying dirty page maps")
-end)
-
 print("\n\n check replace flash drives")
 test_util.make_do_test(build_machine, machine_type, {
     ram = { length = 1 << 20 },
diff --git a/tests/misc/Makefile b/tests/misc/Makefile
index 60cc84fa8..f7e66a5fe 100644
--- a/tests/misc/Makefile
+++ b/tests/misc/Makefile
@@ -45,6 +45,7 @@ PORT_PREFIX = /opt/local
 BOOST_LIB_DIR=-L$(PORT_PREFIX)/libexec/boost/1.87/lib
 BOOST_INC=-I$(PORT_PREFIX)/libexec/boost/1.87/include
 SLIRP_LIB=-L$(PORT_PREFIX)/lib -lslirp
+OMP_LIB=-fopenmp -L$(PORT_PREFIX)/lib/libomp -lgomp
 else
 $(error Neither Homebrew nor MacPorts is installed)
 endif
@@ -97,7 +98,7 @@ CLANG_FORMAT_FILES:=$(wildcard *.cpp) $(wildcard *.h)
 INCS=-I../../src -I../../third-party/tiny_sha3 -I../../third-party/nlohmann-json -I../../third-party/downloads
 WARNS=-Wall -Wpedantic $(BOOST_INC)
 
-CXXFLAGS+=-O2 -g -std=gnu++20 -fvisibility=hidden $(INCS) $(UBFLAGS) $(WARNS)
+CXXFLAGS+=-O2 -g -std=gnu++20 -fopenmp -fvisibility=hidden $(INCS) $(UBFLAGS) $(WARNS)
 
 ifeq ($(slirp),yes)
 LIBCARTESI_LIBS+=$(SLIRP_LIB)
@@ -113,7 +114,7 @@ $(BUILDDIR)/test-merkle-tree-hash: test-merkle-tree-hash.o ../../src/libcartesi.
 	$(CXX) -o $@ $^ $(CXXFLAGS)
 
 $(BUILDDIR)/test-machine-c-api: test-machine-c-api.o ../../src/libcartesi.a ../../src/libcartesi_merkle_tree.a
-	$(CXX) -o $@ $^ $(CXXFLAGS) $(LIBCARTESI_LIBS)
+	$(CXX) -o $@ $^ $(CXXFLAGS) $(LIBCARTESI_LIBS) $(OMP_LIB)
 
 %.o: %.cpp
 	$(CXX) $(CXXFLAGS) -c -o $@ $<
diff --git a/tests/misc/test-machine-c-api.cpp b/tests/misc/test-machine-c-api.cpp
index 710f03e02..0380bbb78 100644
--- a/tests/misc/test-machine-c-api.cpp
+++ b/tests/misc/test-machine-c-api.cpp
@@ -163,8 +163,8 @@ class machine_flash_simple_fixture : public incomplete_machine_fixture {
     machine_flash_simple_fixture() {
         _machine_config["flash_drive"] = {{{"start", 0x80000000000000}, {"length", 0x3c00000}, {"read_only", false},
             {"backing_store",
-                {{"shared", false}, {"create", false}, {"truncate", false}, {"data_filename", ""},
-                    {"dht_filename", ""}}}}};
+                {{"shared", false}, {"create", false}, {"truncate", false}, {"data_filename", ""}, {"dht_filename", ""},
+                    {"dpt_filename", ""}}}}};
     }
 
     machine_flash_simple_fixture(const machine_flash_simple_fixture &other) = delete;
@@ -407,14 +407,14 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(get_proof_invalid_log2_test, ordinary_machine_fix
 
     // log2_root_size = 64
     cm_error error_code = cm_get_proof(_machine, 0, 65, &proof);
-    BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
+    BOOST_CHECK_EQUAL(error_code, CM_ERROR_DOMAIN_ERROR);
     std::string result = cm_get_last_error_message();
     std::string origin("invalid log2_size");
     BOOST_CHECK_EQUAL(origin, result);
 
-    // log2_word_size = 3
+    // log2_word_size = 5
     error_code = cm_get_proof(_machine, 0, 2, &proof);
-    BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
+    BOOST_CHECK_EQUAL(error_code, CM_ERROR_DOMAIN_ERROR);
     result = cm_get_last_error_message();
     BOOST_CHECK_EQUAL(origin, result);
 }
@@ -441,9 +441,8 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(get_proof_machine_hash_test, ordinary_machine_fix
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_OK);
     BOOST_CHECK_EQUAL(std::string(""), std::string(cm_get_last_error_message()));
 
-    const auto proof = cartesi::from_json<cartesi::not_default_constructible<cartesi::machine_merkle_tree::proof_type>>(
-        proof_str, "proof")
-                           .value();
+    const auto proof =
+        cartesi::from_json<cartesi::not_default_constructible<cartesi::merkle_tree_proof>>(proof_str, "proof").value();
     auto proof_root_hash = proof.get_root_hash();
     auto verification = calculate_proof_root_hash(proof);
     BOOST_CHECK_EQUAL_COLLECTIONS(verification.begin(), verification.end(), proof_root_hash.begin(),
@@ -543,7 +542,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(write_memory_invalid_address_range_test, ordinary
     cm_error error_code = cm_write_memory(_machine, address, write_data.data(), write_data.size());
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
     std::string result = cm_get_last_error_message();
-    std::string origin("attempted write to device memory range");
+    std::string origin("attempted write to device memory range HTIF device");
     BOOST_CHECK_EQUAL(origin, result);
 }
 
@@ -636,7 +635,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(write_virtual_memory_invalid_address_range_test,
     cm_error error_code = cm_write_virtual_memory(_machine, address, write_data.data(), write_data.size());
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
     std::string result = cm_get_last_error_message();
-    std::string origin("attempted write to device memory range");
+    std::string origin("attempted write to device memory range HTIF device");
     BOOST_CHECK_EQUAL(origin, result);
 }
 
@@ -809,25 +808,6 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(get_initial_config_basic_test, ordinary_machine_f
     BOOST_CHECK_EQUAL(std::string(cfg), _machine_config.dump());
 }
 
-BOOST_AUTO_TEST_CASE_NOLINT(verify_dirty_page_maps_null_machine_test) {
-    bool result{};
-    cm_error error_code = cm_verify_dirty_page_maps(nullptr, &result);
-    BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
-}
-
-BOOST_FIXTURE_TEST_CASE_NOLINT(verify_dirty_page_maps_null_output_test, ordinary_machine_fixture) {
-    cm_error error_code = cm_verify_dirty_page_maps(_machine, nullptr);
-    BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
-}
-
-BOOST_FIXTURE_TEST_CASE_NOLINT(verify_dirty_page_maps_success_test, ordinary_machine_fixture) {
-    bool result{};
-    cm_error error_code = cm_verify_dirty_page_maps(_machine, &result);
-    BOOST_CHECK_EQUAL(error_code, CM_ERROR_OK);
-    BOOST_CHECK_EQUAL(std::string(""), std::string(cm_get_last_error_message()));
-    BOOST_CHECK(result);
-}
-
 BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_null_flash_config_test, ordinary_machine_fixture) {
     const auto dumped_range =
         nlohmann::json{{"start", 0}, {"length", 0}, {"backing_store", {{"shared", false}}}}.dump();
@@ -835,7 +815,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_null_flash_config_test, ordi
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 
     std::string result = cm_get_last_error_message();
-    std::string origin("attempt to replace inexistent memory range");
+    std::string origin("attempted replace of inexistent memory range");
     BOOST_CHECK_EQUAL(origin, result);
 }
 
@@ -914,7 +894,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_invalid_pma_test, flash_driv
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 
     std::string result = cm_get_last_error_message();
-    std::string origin = "attempt to replace inexistent memory range";
+    std::string origin = "attempted replace of inexistent memory range";
     BOOST_CHECK_EQUAL(origin, result);
 }
 
@@ -929,7 +909,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_invalid_length_test, flash_d
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 
     std::string result = cm_get_last_error_message();
-    std::string origin = "attempt to replace inexistent memory range";
+    std::string origin = "attempted replace of inexistent memory range";
     BOOST_CHECK_EQUAL(origin, result);
 }
 
@@ -942,7 +922,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_file_length_mismatch_test, f
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 
     std::string result = cm_get_last_error_message();
-    std::string origin = "attempt to replace inexistent memory range";
+    std::string origin = "attempted replace of inexistent memory range";
     BOOST_CHECK_EQUAL(origin, result);
 }
 
@@ -956,7 +936,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_zero_length_test, flash_driv
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 
     std::string result = cm_get_last_error_message();
-    std::string origin = "attempt to replace inexistent memory range";
+    std::string origin = "attempted replace of inexistent memory range";
     BOOST_CHECK_EQUAL(origin, result);
 }
 
@@ -1072,20 +1052,20 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(read_write_reg_basic_test, ordinary_machine_fixtu
     BOOST_CHECK_EQUAL(static_cast<uint64_t>(0x108), pc_addr);
 }
 
-BOOST_AUTO_TEST_CASE_NOLINT(verify_merkle_tree_null_machine_test) {
+BOOST_AUTO_TEST_CASE_NOLINT(verify_hash_tree_null_machine_test) {
     bool ret{};
-    cm_error error_code = cm_verify_merkle_tree(nullptr, &ret);
+    cm_error error_code = cm_verify_hash_tree(nullptr, &ret);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 }
 
-BOOST_FIXTURE_TEST_CASE_NOLINT(verify_merkle_tree_null_output_test, ordinary_machine_fixture) {
-    cm_error error_code = cm_verify_merkle_tree(_machine, nullptr);
+BOOST_FIXTURE_TEST_CASE_NOLINT(verify_hash_tree_null_output_test, ordinary_machine_fixture) {
+    cm_error error_code = cm_verify_hash_tree(_machine, nullptr);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 }
 
-BOOST_FIXTURE_TEST_CASE_NOLINT(verify_merkle_tree_basic_test, ordinary_machine_fixture) {
+BOOST_FIXTURE_TEST_CASE_NOLINT(verify_hash_tree_basic_test, ordinary_machine_fixture) {
     bool ret{};
-    cm_error error_code = cm_verify_merkle_tree(_machine, &ret);
+    cm_error error_code = cm_verify_hash_tree(_machine, &ret);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_OK);
     BOOST_CHECK_EQUAL(std::string(""), std::string(cm_get_last_error_message()));
     BOOST_CHECK(ret);
@@ -1540,7 +1520,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(machine_reset_uarch, ordinary_machine_fixture) {
     BOOST_REQUIRE(initial_uarch_ram == reset_uarch_ram);
 }
 
-BOOST_FIXTURE_TEST_CASE_NOLINT(machine_verify_merkle_tree_root_updates_test, ordinary_machine_fixture) {
+BOOST_FIXTURE_TEST_CASE_NOLINT(machine_verify_hash_tree_root_updates_test, ordinary_machine_fixture) {
 
     cm_hash start_hash;
     cm_error error_code = cm_get_root_hash(_machine, &start_hash);
@@ -1561,14 +1541,13 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(machine_verify_merkle_tree_root_updates_test, ord
     BOOST_CHECK_EQUAL_COLLECTIONS(verification.begin(), verification.end(), end_hash, end_hash + sizeof(cm_hash));
 }
 
-BOOST_FIXTURE_TEST_CASE_NOLINT(machine_verify_merkle_tree_proof_updates_test, ordinary_machine_fixture) {
+BOOST_FIXTURE_TEST_CASE_NOLINT(machine_verify_hash_tree_proof_updates_test, ordinary_machine_fixture) {
     const char *proof_str{};
     cm_error error_code = cm_get_proof(_machine, 0, 12, &proof_str);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_OK);
     BOOST_CHECK_EQUAL(std::string(""), std::string(cm_get_last_error_message()));
-    auto proof = cartesi::from_json<cartesi::not_default_constructible<cartesi::machine_merkle_tree::proof_type>>(
-        proof_str, "proof")
-                     .value();
+    auto proof =
+        cartesi::from_json<cartesi::not_default_constructible<cartesi::merkle_tree_proof>>(proof_str, "proof").value();
     auto proof_root_hash = proof.get_root_hash();
     auto verification = calculate_proof_root_hash(proof);
     BOOST_CHECK_EQUAL_COLLECTIONS(verification.begin(), verification.end(), proof_root_hash.begin(),
@@ -1584,9 +1563,8 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(machine_verify_merkle_tree_proof_updates_test, or
     error_code = cm_get_proof(_machine, 0, 12, &proof_str);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_OK);
     BOOST_CHECK_EQUAL(std::string(""), std::string(cm_get_last_error_message()));
-    proof = cartesi::from_json<cartesi::not_default_constructible<cartesi::machine_merkle_tree::proof_type>>(proof_str,
-        "proof")
-                .value();
+    proof =
+        cartesi::from_json<cartesi::not_default_constructible<cartesi::merkle_tree_proof>>(proof_str, "proof").value();
     proof_root_hash = proof.get_root_hash();
     verification = calculate_proof_root_hash(proof);
     BOOST_CHECK_EQUAL_COLLECTIONS(verification.begin(), verification.end(), proof_root_hash.begin(),
diff --git a/tests/misc/test-merkle-tree-hash.cpp b/tests/misc/test-merkle-tree-hash.cpp
index 1989deff9..80c565ccd 100644
--- a/tests/misc/test-merkle-tree-hash.cpp
+++ b/tests/misc/test-merkle-tree-hash.cpp
@@ -23,6 +23,7 @@
 #include <exception>
 #include <iostream>
 #include <new>
+#include <span>
 #include <tuple>
 #include <vector>
 
@@ -36,7 +37,7 @@
 
 using namespace cartesi;
 using hasher_type = keccak_256_hasher;
-using hash_type = hasher_type::hash_type;
+using hash_type = machine_hash;
 
 namespace {
 /// \brief Checks if string matches prefix and captures remaninder
@@ -124,7 +125,7 @@ __attribute__((format(printf, 1, 2))) void error(const char *fmt, ...) {
 /// \param hash Receives the leaf hash
 void get_word_hash(hasher_type &h, const unsigned char *word, int log2_word_size, hash_type &hash) {
     h.begin();
-    h.add_data(word, 1 << log2_word_size);
+    h.add_data(std::span<const unsigned char>(word, 1 << log2_word_size));
     h.end(hash);
 }
 
diff --git a/tests/misc/test-utils.h b/tests/misc/test-utils.h
index 4d72cb1fd..ba9ec2ca7 100644
--- a/tests/misc/test-utils.h
+++ b/tests/misc/test-utils.h
@@ -16,13 +16,14 @@
 
 #include <string>
 
-#include "json-util.h"
 #include <back-merkle-tree.h>
+#include <json-util.h>
 #include <keccak-256-hasher.h>
 #include <machine-c-api.h>
+#include <machine-hash.h>
 #include <merkle-tree-proof.h>
 
-using hash_type = cartesi::keccak_256_hasher::hash_type;
+using hash_type = cartesi::machine_hash;
 
 // Calculate root hash for data buffer of log2_size
 namespace detail {
@@ -42,7 +43,7 @@ static hash_type merkle_hash(cartesi::keccak_256_hasher &h, const std::string_vi
     } else {
         h.begin();
         // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        h.add_data(reinterpret_cast<const unsigned char *>(data.data()), data.size());
+        h.add_data(data);
         h.end(result);
     }
     return result;
@@ -64,7 +65,7 @@ static hash_type merkle_hash(const std::string_view &data, int log2_size) {
     return detail::merkle_hash(h, data, log2_size);
 }
 
-static hash_type calculate_proof_root_hash(const cartesi::machine_merkle_tree::proof_type &proof) {
+static hash_type calculate_proof_root_hash(const cartesi::merkle_tree_proof &proof) {
     hash_type hash;
     memcpy(hash.data(), proof.get_target_hash().data(), sizeof(cm_hash));
     for (int log2_size = static_cast<int>(proof.get_log2_target_size());
diff --git a/tools/template/control.template b/tools/template/control.template
index 7a5ae7c99..837c44398 100644
--- a/tools/template/control.template
+++ b/tools/template/control.template
@@ -5,7 +5,7 @@ Homepage: https://github.com/cartesi/machine-emulator
 Architecture: ARG_ARCH
 Maintainer: Cartesi Machine Reference Unit
 Provides: cartesi-machine-emulator
-Depends: lua5.4, libslirp0
+Depends: lua5.4, libslirp0, libgomp1
 Section: devel
 Priority: optional
 Multi-Arch: foreign
diff --git a/uarch/Makefile b/uarch/Makefile
index 43aef034b..c8ce13112 100644
--- a/uarch/Makefile
+++ b/uarch/Makefile
@@ -76,7 +76,6 @@ EMULATOR_SOURCES=\
 
 COMPUTE_SOURCES=\
 	compute-uarch-pristine-hash.cpp \
-	$(EMULATOR_SRC_DIR)/machine-merkle-tree.cpp \
 	$(EMULATOR_SRC_DIR)/back-merkle-tree.cpp \
 	$(EMULATOR_SRC_DIR)/pristine-merkle-tree.cpp \
 	$(EMULATOR_SRC_DIR)/complete-merkle-tree.cpp \
diff --git a/uarch/compute-uarch-pristine-hash.cpp b/uarch/compute-uarch-pristine-hash.cpp
index d3d0edca9..68aecbda6 100644
--- a/uarch/compute-uarch-pristine-hash.cpp
+++ b/uarch/compute-uarch-pristine-hash.cpp
@@ -18,7 +18,8 @@
 #include <iomanip>
 #include <iostream>
 
-#include <machine-merkle-tree.h>
+#include <back-merkle-tree.h>
+#include <hash-tree-constants.h>
 #include <shadow-uarch-state.h>
 #include <uarch-constants.h>
 #include <uarch-pristine.h>
@@ -30,13 +31,25 @@
 
 using namespace cartesi;
 
-using tree_type = machine_merkle_tree;
+using tree_type = back_merkle_tree;
 using hash_type = tree_type::hash_type;
-using hashertype = tree_type::hasher_type;
-using proof_type = tree_type::proof_type;
-
-static_assert(AR_PAGE_SIZE == tree_type::get_page_size(), "PMA and machine_merkle_tree page sizes must match");
-static_assert(sizeof(shadow_uarch_state) <= AR_PAGE_SIZE, "shadow_uarch_state must fit in one page");
+using hasher_type = tree_type::hasher_type;
+
+static constexpr auto word_size = HASH_TREE_WORD_SIZE;
+static constexpr auto log2_word_size = HASH_TREE_LOG2_WORD_SIZE;
+static constexpr auto page_size = HASH_TREE_PAGE_SIZE;
+static constexpr auto log2_page_size = HASH_TREE_LOG2_PAGE_SIZE;
+
+static_assert(AR_PAGE_SIZE == page_size, "address-range and hash-tree page sizes must match");
+static_assert(sizeof(shadow_uarch_state) <= page_size, "shadow_uarch_state must fit in one page");
+static_assert(AR_SHADOW_UARCH_STATE_LENGTH >= sizeof(shadow_uarch_state),
+    "shadow uarch state must fit in its address range");
+static_assert(AR_SHADOW_UARCH_STATE_LENGTH >= page_size,
+    "shadow uarch state address range must be a least one page long");
+static_assert(AR_UARCH_RAM_START % page_size == 0, "uarch ram start must be aligned to page size");
+static_assert(AR_SHADOW_UARCH_STATE_START % page_size == 0, "shadow uarch state start must be aligned to page size");
+static_assert(AR_UARCH_RAM_START >= AR_SHADOW_UARCH_STATE_START + AR_SHADOW_UARCH_STATE_LENGTH,
+    "shadow ram must start after shadow uarch state");
 
 /// \brief Prints help message
 static void help(const char *name) {
@@ -55,8 +68,8 @@ Computes the hash of the pristine uarch state.
 }
 
 int main(int argc, char *argv[]) try {
-    tree_type tree{};
-    hashertype hasher{};
+    tree_type tree{UARCH_STATE_LOG2_SIZE, log2_page_size, log2_word_size};
+    hasher_type hasher{};
     hash_type hash{};
 
     // Process command line arguments
@@ -70,53 +83,47 @@ int main(int argc, char *argv[]) try {
     }
 
     // Allocate scratch page buffer
-    auto scratch = make_unique_calloc<unsigned char>(AR_PAGE_SIZE, std::nothrow_t{});
+    auto scratch = make_unique_calloc<unsigned char>(page_size, std::nothrow_t{});
     if (!scratch) {
         throw std::runtime_error("Could not allocate scratch memory");
     }
+    auto scratch_span = std::span<unsigned char>{scratch.get(), page_size};
+    hash_type pristine_hash;
+    get_merkle_tree_hash(hasher, scratch_span, word_size, pristine_hash);
 
     // Build pristine shadow uarch state
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
     auto *shadow = reinterpret_cast<shadow_uarch_state *>(scratch.get());
-    memset(scratch.get(), 0, AR_PAGE_SIZE);
+    memset(scratch.get(), 0, page_size);
     shadow->halt_flag = UARCH_HALT_FLAG_INIT;
     shadow->pc = UARCH_PC_INIT;
     shadow->cycle = UARCH_CYCLE_INIT;
     for (int i = 1; i < UARCH_X_REG_COUNT; i++) {
         shadow->x[i] = UARCH_X_INIT;
     }
-
-    // Start updating merkle tree
-    tree.begin_update();
     // Add shadow uarch state to merkle tree
-    tree.get_page_node_hash(hasher, scratch.get(), hash);
-    if (!tree.update_page_node_hash(UARCH_SHADOW_START_ADDRESS, hash)) {
-        throw std::runtime_error("Could not update uarch shadow tree node hash");
+    get_merkle_tree_hash(hasher, scratch_span, word_size, hash);
+    tree.push_back(hash);
+    // Add pristine gap between shadow uarch state and uarch RAM
+    if (auto gap = (AR_UARCH_RAM_START - page_size - AR_SHADOW_UARCH_STATE_START) / page_size; gap != 0) {
+        tree.pad_back(gap);
     }
     // Add all pages of uarch ram to merkle tree
-    for (uint32_t p = 0; p < uarch_pristine_ram_len; p += AR_PAGE_SIZE) {
+    for (uint32_t p = 0; p < uarch_pristine_ram_len; p += page_size) {
         const auto *page_data = uarch_pristine_ram + p;
-        if (p + AR_PAGE_SIZE > uarch_pristine_ram_len) {
-            memset(scratch.get(), 0, AR_PAGE_SIZE);
+        if (p + page_size > uarch_pristine_ram_len) {
+            memset(scratch.get(), 0, page_size);
             memcpy(scratch.get(), uarch_pristine_ram + p, uarch_pristine_ram_len - p);
             page_data = scratch.get();
         }
-        tree.get_page_node_hash(hasher, page_data, hash);
-        if (!tree.update_page_node_hash(UARCH_RAM_START_ADDRESS + p, hash)) {
-            throw std::runtime_error("Could not update uarch ram tree node hash");
-        }
-    }
-
-    // Get uarch root hash
-    if (!tree.end_update(hasher)) {
-        throw std::runtime_error("end_update merkle tree failed");
+        std::span<const unsigned char, page_size> page_data_span(page_data, page_size);
+        get_merkle_tree_hash(hasher, page_data_span, word_size, hash);
+        tree.push_back(hash);
     }
-    proof_type proof = tree.get_proof(UARCH_STATE_START_ADDRESS, UARCH_STATE_LOG2_SIZE, nullptr);
-    auto &uarch_state_hash = proof.get_target_hash();
-
+    // Get uarch state hash
+    auto uarch_state_hash = tree.get_root_hash();
     // Print header
     std::cout << "// This file is auto-generated and should not be modified" << std::endl;
-
     // Print hash
     std::cout << "unsigned char uarch_pristine_hash[] = {\n  ";
     int i = 0;
@@ -131,7 +138,6 @@ int main(int argc, char *argv[]) try {
     }
     std::cout << "\n};\nunsigned int uarch_pristine_hash_len = " << std::dec << uarch_state_hash.size() << ";"
               << std::endl;
-
     return 0;
 } catch (std::exception &e) {
     std::cerr << "Caught exception: " << e.what() << '\n';

From e14f0640adb9a25a02175466e1118683e675f760 Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Wed, 28 May 2025 22:45:54 +0100
Subject: [PATCH 37/82] refactor: add hash-tree stats API

---
 src/back-merkle-tree.h                        |   4 +-
 src/clua-i-machine.cpp                        |  15 +
 src/complete-merkle-tree.h                    |   4 +-
 src/full-merkle-tree.h                        |   4 +-
 ...{merkle-tree-proof.h => hash-tree-proof.h} |  36 +-
 src/hash-tree-stats.h                         |  36 ++
 src/hash-tree.cpp                             |  37 +-
 src/hash-tree.h                               |  14 +-
 src/i-dirty-page-tree.h                       |   7 +-
 src/i-machine.h                               |  18 +-
 src/json-util.cpp                             | 111 +++-
 src/json-util.h                               |  54 +-
 src/jsonrpc-discover.json                     |  72 ++-
 src/jsonrpc-machine.cpp                       |  10 +-
 src/jsonrpc-machine.h                         |   5 +-
 src/jsonrpc-remote-machine.cpp                |  16 +-
 src/local-machine.cpp                         |   6 +-
 src/local-machine.h                           |   3 +-
 src/machine-c-api.cpp                         |  17 +-
 src/machine-c-api.h                           |  10 +-
 src/machine.cpp                               |   6 +-
 src/machine.h                                 |   9 +-
 src/page-hash-tree-cache-stats.h              |  36 ++
 src/page-hash-tree-cache.h                    | 486 +++++++++++-------
 src/uarch-solidity-compat.h                   |   2 +
 tests/misc/test-machine-c-api.cpp             |   6 +-
 tests/misc/test-merkle-tree-hash.cpp          |   2 +-
 tests/misc/test-utils.h                       |   4 +-
 28 files changed, 723 insertions(+), 307 deletions(-)
 rename src/{merkle-tree-proof.h => hash-tree-proof.h} (90%)
 create mode 100644 src/hash-tree-stats.h
 create mode 100644 src/page-hash-tree-cache-stats.h

diff --git a/src/back-merkle-tree.h b/src/back-merkle-tree.h
index e7eaf6bb4..4b887fcc6 100644
--- a/src/back-merkle-tree.h
+++ b/src/back-merkle-tree.h
@@ -20,9 +20,9 @@
 #include <cstdint>
 #include <vector>
 
+#include "hash-tree-proof.h"
 #include "keccak-256-hasher.h"
 #include "machine-hash.h"
-#include "merkle-tree-proof.h"
 #include "pristine-merkle-tree.h"
 
 /// \file
@@ -47,7 +47,7 @@ class back_merkle_tree {
     using hash_type = machine_hash;
 
     /// \brief Storage for the proof of a word value.
-    using proof_type = merkle_tree_proof;
+    using proof_type = hash_tree_proof;
 
     /// \brief Constructor
     /// \param log2_root_size Log<sub>2</sub> of root node
diff --git a/src/clua-i-machine.cpp b/src/clua-i-machine.cpp
index b1b064979..982187aca 100644
--- a/src/clua-i-machine.cpp
+++ b/src/clua-i-machine.cpp
@@ -532,6 +532,20 @@ static int machine_obj_index_get_proof(lua_State *L) {
     return 1;
 }
 
+/// \brief This is the machine:get_hash_tree_stats() method implementation.
+/// \param L Lua state.
+static int machine_obj_index_get_hash_tree_stats(lua_State *L) {
+    lua_settop(L, 2);
+    auto &m = clua_check<clua_managed_cm_ptr<cm_machine>>(L, 1);
+    const bool clear = lua_toboolean(L, 2) != 0;
+    const char *stats = nullptr;
+    if (cm_get_hash_tree_stats(m.get(), clear, &stats) != 0) {
+        return luaL_error(L, "%s", cm_get_last_error_message());
+    }
+    clua_push_json_table(L, stats);
+    return 1;
+}
+
 static int machine_obj_index_get_initial_config(lua_State *L) {
     auto &m = clua_check<clua_managed_cm_ptr<cm_machine>>(L, 1);
     const char *config = nullptr;
@@ -1048,6 +1062,7 @@ static const auto machine_obj_index = cartesi::clua_make_luaL_Reg_array({
     {"get_initial_config", machine_obj_index_get_initial_config},
     {"get_address_ranges", machine_obj_index_get_address_ranges},
     {"get_proof", machine_obj_index_get_proof},
+    {"get_hash_tree_stats", machine_obj_index_get_hash_tree_stats},
     {"get_reg_address", machine_obj_index_get_reg_address},
     {"get_root_hash", machine_obj_index_get_root_hash},
     {"get_node_hash", machine_obj_index_get_node_hash},
diff --git a/src/complete-merkle-tree.h b/src/complete-merkle-tree.h
index b9205d1bf..24950d927 100644
--- a/src/complete-merkle-tree.h
+++ b/src/complete-merkle-tree.h
@@ -21,9 +21,9 @@
 #include <type_traits>
 #include <vector>
 
+#include "hash-tree-proof.h"
 #include "keccak-256-hasher.h"
 #include "machine-hash.h"
-#include "merkle-tree-proof.h"
 #include "meta.h"
 #include "pristine-merkle-tree.h"
 
@@ -43,7 +43,7 @@ class complete_merkle_tree {
     using hasher_type = keccak_256_hasher;
 
     /// \brief Storage for a proof.
-    using proof_type = merkle_tree_proof;
+    using proof_type = hash_tree_proof;
 
     /// \brief Storage for a level in the tree.
     using level_type = std::vector<machine_hash>;
diff --git a/src/full-merkle-tree.h b/src/full-merkle-tree.h
index 2c460b24f..2f063642d 100644
--- a/src/full-merkle-tree.h
+++ b/src/full-merkle-tree.h
@@ -20,9 +20,9 @@
 #include <cstdint>
 #include <vector>
 
+#include "hash-tree-proof.h"
 #include "keccak-256-hasher.h"
 #include "machine-hash.h"
-#include "merkle-tree-proof.h"
 #include "pristine-merkle-tree.h"
 
 /// \file
@@ -38,7 +38,7 @@ class full_merkle_tree {
     using hasher_type = keccak_256_hasher;
 
     /// \brief Storage for a proof.
-    using proof_type = merkle_tree_proof;
+    using proof_type = hash_tree_proof;
 
     /// \brief Constructor for a pristine tree
     /// \param log2_root_size Log<sub>2</sub> of root node
diff --git a/src/merkle-tree-proof.h b/src/hash-tree-proof.h
similarity index 90%
rename from src/merkle-tree-proof.h
rename to src/hash-tree-proof.h
index e7f313b23..0d5b76b5e 100644
--- a/src/merkle-tree-proof.h
+++ b/src/hash-tree-proof.h
@@ -14,11 +14,11 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#ifndef MERKLE_TREE_PROOF_H
-#define MERKLE_TREE_PROOF_H
+#ifndef HASH_TREE_PROOF_H
+#define HASH_TREE_PROOF_H
 
 /// \file
-/// \brief Merkle tree proof structure
+/// \brief Hash-tree proof structure
 
 #include <algorithm>
 #include <cstdint>
@@ -32,16 +32,16 @@
 
 namespace cartesi {
 
-/// \brief Merkle tree proof structure
+/// \brief Hash-tree proof structure
 /// \details \{
 /// This structure holds a proof that the node spanning a log2_target_size
 /// at a given address in the tree has a certain hash.
 /// \}
-class merkle_tree_proof final {
+class hash_tree_proof final {
 public:
-    /// \brief Constructs a merkle_tree_proof object and allocates
+    /// \brief Constructs a hash_tree_proof object and allocates
     /// room for the sibling hashes
-    merkle_tree_proof(int log2_root_size, int log2_target_size) :
+    hash_tree_proof(int log2_root_size, int log2_target_size) :
         m_log2_target_size{log2_target_size},
         m_log2_root_size{log2_root_size},
         m_sibling_hashes(std::max(0, log2_root_size - log2_target_size)) {
@@ -56,11 +56,11 @@ class merkle_tree_proof final {
         }
     }
 
-    merkle_tree_proof(const merkle_tree_proof &other) = default;
-    merkle_tree_proof(merkle_tree_proof &&other) noexcept = default;
-    merkle_tree_proof &operator=(const merkle_tree_proof &other) = default;
-    merkle_tree_proof &operator=(merkle_tree_proof &&other) noexcept = default;
-    ~merkle_tree_proof() = default;
+    hash_tree_proof(const hash_tree_proof &other) = default;
+    hash_tree_proof(hash_tree_proof &&other) noexcept = default;
+    hash_tree_proof &operator=(const hash_tree_proof &other) = default;
+    hash_tree_proof &operator=(hash_tree_proof &&other) noexcept = default;
+    ~hash_tree_proof() = default;
 
     /// \brief Storage for the hashes of the siblings of all nodes along
     /// the path from the root node to the target node.
@@ -141,8 +141,8 @@ class merkle_tree_proof final {
         return m_sibling_hashes;
     }
 
-    /// \brief Checks if two Merkle proofs are equal
-    bool operator==(const merkle_tree_proof &other) const {
+    /// \brief Checks if two hash-tree proofs are equal
+    bool operator==(const hash_tree_proof &other) const {
         if (get_log2_target_size() != other.get_log2_target_size()) {
             return false;
         }
@@ -164,8 +164,8 @@ class merkle_tree_proof final {
         return true;
     }
 
-    /// \brief Checks if two Merkle proofs are different
-    bool operator!=(const merkle_tree_proof &other) const {
+    /// \brief Checks if two hash-tree proofs are different
+    bool operator!=(const hash_tree_proof &other) const {
         return !(operator==(other));
     }
 
@@ -200,7 +200,7 @@ class merkle_tree_proof final {
 
     template <IHasher H>
     // NOLINTNEXTLINE(cppcoreguidelines-missing-std-forward)
-    merkle_tree_proof slice(H &&h, int new_log2_root_size, int new_log2_target_size) const {
+    hash_tree_proof slice(H &&h, int new_log2_root_size, int new_log2_target_size) const {
         if (new_log2_root_size <= 0) {
             throw std::out_of_range{"log2_root_size is not positive"};
         }
@@ -216,7 +216,7 @@ class merkle_tree_proof final {
         if (new_log2_target_size < get_log2_target_size()) {
             throw std::out_of_range{"log2_target_size is too small"};
         }
-        merkle_tree_proof sliced(new_log2_root_size, new_log2_target_size);
+        hash_tree_proof sliced(new_log2_root_size, new_log2_target_size);
         machine_hash hash = get_target_hash();
         for (int log2_size = get_log2_target_size(); log2_size < new_log2_target_size; ++log2_size) {
             const auto bit = (get_target_address() & (static_cast<uint64_t>(1) << log2_size)) != 0;
diff --git a/src/hash-tree-stats.h b/src/hash-tree-stats.h
new file mode 100644
index 000000000..c439abc5f
--- /dev/null
+++ b/src/hash-tree-stats.h
@@ -0,0 +1,36 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef HASH_TREE_STATS_H
+#define HASH_TREE_STATS_H
+
+#include "hash-tree-constants.h"
+#include "page-hash-tree-cache-stats.h"
+
+#include <array>
+#include <cstdint>
+
+namespace cartesi {
+
+struct hash_tree_stats {
+    page_hash_tree_cache_stats phtc;
+    uint64_t sparse_node_hashes;
+    std::array<uint64_t, HASH_TREE_LOG2_ROOT_SIZE> dense_node_hashes;
+};
+
+} // namespace cartesi
+
+#endif // HASH_TREE_STATS_H
diff --git a/src/hash-tree.cpp b/src/hash-tree.cpp
index abb050214..65989bee2 100644
--- a/src/hash-tree.cpp
+++ b/src/hash-tree.cpp
@@ -172,14 +172,26 @@ hash_tree::proof_type hash_tree::get_proof(address_ranges ars, uint64_t address,
     }
 }
 
-void hash_tree::clear_stats() {
-    m_page_cache.clear_stats();
-#ifdef DUMP_HASH_TREE_STATS
-    m_sparse_node_hashes = 0;
-    for (auto &a : m_dense_node_hashes) {
-        a = 0;
-    }
-#endif
+hash_tree_stats hash_tree::get_stats(bool clear) noexcept {
+    auto s = hash_tree_stats{
+        .phtc = m_page_cache.get_stats(clear),
+        .sparse_node_hashes = m_sparse_node_hashes.load(),
+    };
+    std::ranges::copy(m_dense_node_hashes | std::views::transform([](auto &a) {
+        std::cerr << "ha " << a.load() << '\n';
+        return a.load();
+    }),
+        s.dense_node_hashes.begin());
+    for (auto i : s.dense_node_hashes) {
+        std::cerr << "hi " << i << '\n';
+    }
+    if (clear) {
+        m_sparse_node_hashes = 0;
+        for (auto &a : m_dense_node_hashes) {
+            a = 0;
+        }
+    }
+    return s;
 }
 
 bool hash_tree::update_dirty_page(hasher_type &h, address_range &ar, page_hash_tree_cache::entry &entry,
@@ -191,7 +203,7 @@ bool hash_tree::update_dirty_page(hasher_type &h, address_range &ar, page_hash_t
     }
     const auto offset = paddr_page - ar.get_start();
     const auto page_view = std::span<const unsigned char, HASH_TREE_PAGE_SIZE>{base + offset, HASH_TREE_PAGE_SIZE};
-    auto ret = entry.update(h, page_view, m_page_cache.get_pristine_page_hash_tree());
+    auto ret = m_page_cache.update_entry(h, page_view, entry);
     auto node_hash_view = ar.get_dense_hash_tree().node_hash_view(offset, HASH_TREE_LOG2_PAGE_SIZE);
     changed = !std::ranges::equal(entry.root_hash_view(), node_hash_view);
     if (changed) {
@@ -835,11 +847,4 @@ void hash_tree::dump(const_address_ranges ars, std::ostream &out) {
     out << "}\n";
 }
 
-#ifdef DUMP_HASH_TREE_STATS
-std::atomic<int> page_hash_tree_cache::entry::m_word_hit{0};
-std::atomic<int> page_hash_tree_cache::entry::m_word_miss{0};
-std::atomic<int> page_hash_tree_cache::entry::m_inner_page_node_hashes{0};
-std::array<std::atomic<int>, 64> hash_tree::m_dense_node_hashes{};
-#endif
-
 } // namespace cartesi
diff --git a/src/hash-tree.h b/src/hash-tree.h
index 127f6ddb5..c7d40e990 100644
--- a/src/hash-tree.h
+++ b/src/hash-tree.h
@@ -22,11 +22,12 @@
 
 #include "address-range.h"
 #include "hash-tree-constants.h"
+#include "hash-tree-proof.h"
+#include "hash-tree-stats.h"
 #include "keccak-256-hasher.h"
 #include "machine-address-ranges.h"
 #include "machine-config.h"
 #include "machine-hash.h"
-#include "merkle-tree-proof.h"
 #include "page-hash-tree-cache.h"
 #include "unique-c-ptr.h"
 
@@ -110,7 +111,7 @@ class hash_tree {
 
 public:
     using hasher_type = keccak_256_hasher;
-    using proof_type = merkle_tree_proof;
+    using proof_type = hash_tree_proof;
 
     using nodes_type = std::vector<node_type>;
     using sibling_hashes_type = std::vector<machine_hash>;
@@ -136,7 +137,7 @@ class hash_tree {
 
     void dump(const_address_ranges ars, std::ostream &out);
 
-    void clear_stats();
+    hash_tree_stats get_stats(bool clear = false) noexcept;
 
 private:
     using changed_address_ranges = std::vector<int>;
@@ -180,10 +181,9 @@ class hash_tree {
     os_signpost_id_t m_spid_update_dense_trees;
     os_signpost_id_t m_spid_update_sparse_tree;
 #endif
-#ifdef DUMP_HASH_TREE_STATS
-    int m_sparse_node_hashes{0};
-    static std::array<std::atomic<int>, 64> m_dense_node_hashes;
-#endif
+
+    std::atomic<uint64_t> m_sparse_node_hashes{0};
+    std::array<std::atomic<uint64_t>, HASH_TREE_LOG2_ROOT_SIZE> m_dense_node_hashes{};
 };
 
 } // namespace cartesi
diff --git a/src/i-dirty-page-tree.h b/src/i-dirty-page-tree.h
index 0082e14fa..d54f78bd0 100644
--- a/src/i-dirty-page-tree.h
+++ b/src/i-dirty-page-tree.h
@@ -299,10 +299,9 @@ class i_dirty_page_tree {
     /// \param offset Start of range of interest, relative to start of this range
     /// \param length Length of range of interest, in bytes
     void mark_dirty_pages_and_up(uint64_t offset, uint64_t length) noexcept {
-        auto offset_aligned = offset & ~(AR_PAGE_SIZE - 1);
-        const auto length_aligned = length + (offset - offset_aligned);
-        for (; offset_aligned < length_aligned; offset_aligned += AR_PAGE_SIZE) {
-            mark_dirty_page_and_up(offset_aligned);
+        const auto end = offset + length;
+        for (offset &= ~(AR_PAGE_SIZE - 1); offset < end; offset += AR_PAGE_SIZE) {
+            mark_dirty_page_and_up(offset);
         }
     }
 
diff --git a/src/i-machine.h b/src/i-machine.h
index 4a2da1142..7478ca074 100644
--- a/src/i-machine.h
+++ b/src/i-machine.h
@@ -22,11 +22,12 @@
 
 #include "access-log.h"
 #include "address-range-description.h"
-#include "hash-tree.h"
+#include "hash-tree-proof.h"
+#include "hash-tree-stats.h"
 #include "interpret.h"
 #include "machine-config.h"
 #include "machine-hash.h"
-#include "machine.h"
+#include "machine-reg.h"
 #include "uarch-interpret.h"
 
 namespace cartesi {
@@ -45,7 +46,6 @@ namespace cartesi {
 /// \}
 class i_machine {
 public:
-    using proof_type = hash_tree::proof_type;
     using reg = machine_reg;
 
     /// \brief Constructor
@@ -100,7 +100,7 @@ class i_machine {
     }
 
     /// \brief Obtains the proof for a node in the Merkle tree.
-    proof_type get_proof(uint64_t address, int log2_size) const {
+    hash_tree_proof get_proof(uint64_t address, int log2_size) const {
         return do_get_proof(address, log2_size);
     }
 
@@ -164,6 +164,13 @@ class i_machine {
         return do_read_word(address);
     }
 
+    /// \brief Returns hash-tree statistics
+    /// \param clear Clear all statistics after collecting them
+    /// \returns Structure containing all statistics
+    hash_tree_stats get_hash_tree_stats(bool clear = false) {
+        return do_get_hash_tree_stats(clear);
+    }
+
     /// \brief Returns copy of initialization config.
     machine_config get_initial_config() const {
         return do_get_initial_config();
@@ -264,7 +271,7 @@ class i_machine {
     virtual void do_store(const std::string &dir) const = 0;
     virtual interpreter_break_reason do_log_step(uint64_t mcycle_count, const std::string &filename) = 0;
     virtual access_log do_log_step_uarch(const access_log::type &log_type) = 0;
-    virtual proof_type do_get_proof(uint64_t address, int log2_size) const = 0;
+    virtual hash_tree_proof do_get_proof(uint64_t address, int log2_size) const = 0;
     virtual machine_hash do_get_root_hash() const = 0;
     virtual machine_hash do_get_node_hash(uint64_t address, int log2_size) const = 0;
     virtual uint64_t do_read_reg(reg r) const = 0;
@@ -277,6 +284,7 @@ class i_machine {
     virtual void do_replace_memory_range(const memory_range_config &new_range) = 0;
     virtual uint64_t do_read_word(uint64_t address) const = 0;
     virtual machine_config do_get_initial_config() const = 0;
+    virtual hash_tree_stats do_get_hash_tree_stats(bool clear) = 0;
     virtual machine_runtime_config do_get_runtime_config() const = 0;
     virtual void do_set_runtime_config(const machine_runtime_config &r) = 0;
     virtual void do_destroy() = 0;
diff --git a/src/json-util.cpp b/src/json-util.cpp
index 0dde7f9db..f1607b496 100644
--- a/src/json-util.cpp
+++ b/src/json-util.cpp
@@ -22,6 +22,7 @@
 #include <cstdint>
 #include <iterator>
 #include <optional>
+#include <ranges>
 #include <stdexcept>
 #include <string>
 #include <type_traits>
@@ -61,7 +62,7 @@ std::string to_string(const char *s) {
 /// \param name Register name
 /// \returns The register index
 static auto reg_from_name(const std::string &name) {
-    using reg = machine::reg;
+    using reg = machine_reg;
     const static std::unordered_map<std::string, reg> g_reg_name = {
         {"x0", reg::x0},
         {"x1", reg::x1},
@@ -220,8 +221,8 @@ static auto reg_from_name(const std::string &name) {
     return got->second;
 }
 
-static auto reg_to_name(machine::reg r) {
-    using reg = machine::reg;
+static auto reg_to_name(machine_reg r) {
+    using reg = machine_reg;
     switch (r) {
         case reg::x0:
             return "x0";
@@ -701,7 +702,7 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
     const std::string &path);
 
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, machine::reg &value, const std::string &path) {
+void ju_get_opt_field(const nlohmann::json &j, const K &key, machine_reg &value, const std::string &path) {
     if (!contains(j, key, path)) {
         return;
     }
@@ -712,10 +713,10 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, machine::reg &value
     value = reg_from_name(jk.template get<std::string>());
 }
 
-template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, machine::reg &value,
+template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, machine_reg &value,
     const std::string &path);
 
-template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key, machine::reg &value,
+template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key, machine_reg &value,
     const std::string &path);
 
 template <typename K>
@@ -845,7 +846,7 @@ template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::
     const std::string &path);
 
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, not_default_constructible<hash_tree::proof_type> &value,
+void ju_get_opt_field(const nlohmann::json &j, const K &key, not_default_constructible<hash_tree_proof> &value,
     const std::string &path) {
     value = {};
     if (!contains(j, key, path)) {
@@ -891,10 +892,58 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, not_default_constru
 }
 
 template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key,
-    not_default_constructible<hash_tree::proof_type> &value, const std::string &path);
+    not_default_constructible<hash_tree_proof> &value, const std::string &path);
 
 template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key,
-    not_default_constructible<hash_tree::proof_type> &value, const std::string &path);
+    not_default_constructible<hash_tree_proof> &value, const std::string &path);
+
+template <typename K>
+void ju_get_opt_field(const nlohmann::json &j, const K &key, page_hash_tree_cache_stats &value,
+    const std::string &path) {
+    if (!contains(j, key, path)) {
+        return;
+    }
+    const auto &jstats = j[key];
+    const auto new_path = path + to_string(key) + "/";
+    ju_get_opt_field(jstats, "page_hits"s, value.page_hits, new_path);
+    ju_get_opt_field(jstats, "page_misses"s, value.page_misses, new_path);
+    ju_get_opt_field(jstats, "word_hits"s, value.word_hits, new_path);
+    ju_get_opt_field(jstats, "word_misses"s, value.word_misses, new_path);
+    ju_get_opt_field(jstats, "inner_page_hashes"s, value.inner_page_hashes, new_path);
+    ju_get_opt_field(jstats, "pristine_pages"s, value.pristine_pages, new_path);
+    ju_get_opt_field(jstats, "non_pristine_pages"s, value.non_pristine_pages, new_path);
+}
+
+template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key,
+    page_hash_tree_cache_stats &value, const std::string &path);
+
+template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key,
+    page_hash_tree_cache_stats &value, const std::string &path);
+
+template <typename K>
+void ju_get_opt_field(const nlohmann::json &j, const K &key, hash_tree_stats &value, const std::string &path) {
+    if (!contains(j, key, path)) {
+        return;
+    }
+    const auto &jstats = j[key];
+    const auto new_path = path + to_string(key) + "/";
+    ju_get_opt_field(jstats, "phtc"s, value.phtc, new_path);
+    ju_get_opt_field(jstats, "sparse_node_hashes"s, value.sparse_node_hashes, new_path);
+    const auto &jdnh = jstats["dense_node_hashes"];
+    if (!jdnh.is_array()) {
+        throw std::invalid_argument("\""s + new_path + "dense_node_hashes\" not an array"s);
+    }
+    const auto dense_node_hashes_base = path + "dense_node_hashes/";
+    for (uint64_t log2_size = 0; log2_size < value.dense_node_hashes.size(); ++log2_size) {
+        ju_get_field(jdnh, log2_size, value.dense_node_hashes[log2_size], dense_node_hashes_base);
+    }
+}
+
+template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, hash_tree_stats &value,
+    const std::string &path);
+
+template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key, hash_tree_stats &value,
+    const std::string &path);
 
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, access_type &value, const std::string &path) {
@@ -1730,7 +1779,7 @@ template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t
 template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key, fork_result &value,
     const std::string &path);
 
-void to_json(nlohmann::json &j, const machine::reg &reg) {
+void to_json(nlohmann::json &j, const machine_reg &reg) {
     j = reg_to_name(reg);
 }
 
@@ -1740,11 +1789,10 @@ void to_json(nlohmann::json &j, const machine_hash &h) {
 
 void to_json(nlohmann::json &j, const std::vector<machine_hash> &hs) {
     j = nlohmann::json::array();
-    std::transform(hs.cbegin(), hs.cend(), std::back_inserter(j),
-        [](const machine_hash &h) -> nlohmann::json { return h; });
+    std::ranges::transform(hs, std::back_inserter(j), [](const machine_hash &h) -> nlohmann::json { return h; });
 }
 
-void to_json(nlohmann::json &j, const hash_tree::proof_type &p) {
+void to_json(nlohmann::json &j, const hash_tree_proof &p) {
     nlohmann::json s = nlohmann::json::array();
     for (int log2_size = p.get_log2_target_size(); log2_size < p.get_log2_root_size(); ++log2_size) {
         s.push_back(encode_base64(p.get_sibling_hash(log2_size)));
@@ -1797,13 +1845,12 @@ void to_json(nlohmann::json &j, const bracket_note &b) {
 
 void to_json(nlohmann::json &j, const std::vector<bracket_note> &bs) {
     j = nlohmann::json::array();
-    std::transform(bs.cbegin(), bs.cend(), std::back_inserter(j),
-        [](const bracket_note &b) -> nlohmann::json { return b; });
+    std::ranges::transform(bs, std::back_inserter(j), [](const bracket_note &b) -> nlohmann::json { return b; });
 }
 
 void to_json(nlohmann::json &j, const std::vector<access> &as) {
     j = nlohmann::json::array();
-    std::transform(as.cbegin(), as.cend(), std::back_inserter(j), [](const access &a) -> nlohmann::json { return a; });
+    std::ranges::transform(as, std::back_inserter(j), [](const access &a) -> nlohmann::json { return a; });
 }
 
 void to_json(nlohmann::json &j, const access_log::type &log_type) {
@@ -1872,8 +1919,7 @@ void to_json(nlohmann::json &j, const processor_config &config) {
 
 void to_json(nlohmann::json &j, const flash_drive_configs &fs) {
     j = nlohmann::json::array();
-    std::transform(fs.cbegin(), fs.cend(), std::back_inserter(j),
-        [](const memory_range_config &m) -> nlohmann::json { return m; });
+    std::ranges::transform(fs, std::back_inserter(j), [](const memory_range_config &m) -> nlohmann::json { return m; });
 }
 
 void to_json(nlohmann::json &j, const virtio_device_config &config) {
@@ -1887,7 +1933,7 @@ void to_json(nlohmann::json &j, const virtio_device_config &config) {
                     {"host_directory", vdev_config.host_directory}};
             } else if constexpr (std::is_same_v<T, cartesi::virtio_net_user_config>) {
                 nlohmann::json jhostfwd = nlohmann::json::array();
-                std::transform(vdev_config.hostfwd.cbegin(), vdev_config.hostfwd.cend(), std::back_inserter(jhostfwd),
+                std::ranges::transform(vdev_config.hostfwd, std::back_inserter(jhostfwd),
                     [](const virtio_hostfwd_config &h) -> nlohmann::json {
                         return nlohmann::json{
                             {"is_udp", h.is_udp},
@@ -1909,7 +1955,7 @@ void to_json(nlohmann::json &j, const virtio_device_config &config) {
 
 void to_json(nlohmann::json &j, const virtio_configs &vs) {
     j = nlohmann::json::array();
-    std::transform(vs.cbegin(), vs.cend(), std::back_inserter(j),
+    std::ranges::transform(vs, std::back_inserter(j),
         [](const virtio_device_config &v) -> nlohmann::json { return v; });
 }
 
@@ -2061,8 +2107,7 @@ void to_json(nlohmann::json &j, const address_range_description &mrd) {
 
 void to_json(nlohmann::json &j, const address_range_descriptions &mrds) {
     j = nlohmann::json::array();
-    std::transform(mrds.cbegin(), mrds.cend(), std::back_inserter(j),
-        [](const auto &a) -> nlohmann::json { return a; });
+    std::ranges::transform(mrds, std::back_inserter(j), [](const auto &a) -> nlohmann::json { return a; });
 }
 
 void to_json(nlohmann::json &j, const fork_result &fork_result) {
@@ -2079,4 +2124,26 @@ void to_json(nlohmann::json &j, const semantic_version &version) {
     };
 }
 
+void to_json(nlohmann::json &j, const hash_tree_stats &stats) {
+    auto jdnh = nlohmann::json::array();
+    std::ranges::copy(stats.dense_node_hashes, std::back_inserter(jdnh));
+    j = nlohmann::json{
+        {"sparse_node_hashes", stats.sparse_node_hashes},
+        {"dense_node_hashes", jdnh},
+        {"phtc", stats.phtc},
+    };
+}
+
+void to_json(nlohmann::json &j, const page_hash_tree_cache_stats &stats) {
+    j = nlohmann::json{
+        {"page_hits", stats.page_hits},
+        {"page_misses", stats.page_misses},
+        {"word_hits", stats.word_hits},
+        {"word_misses", stats.word_misses},
+        {"inner_page_hashes", stats.inner_page_hashes},
+        {"pristine_pages", stats.pristine_pages},
+        {"non_pristine_pages", stats.non_pristine_pages},
+    };
+}
+
 } // namespace cartesi
diff --git a/src/json-util.h b/src/json-util.h
index cc6469f69..c8aa9bb1c 100644
--- a/src/json-util.h
+++ b/src/json-util.h
@@ -30,13 +30,15 @@
 #include "access-log.h"
 #include "address-range-description.h"
 #include "bracket-note.h"
-#include "hash-tree.h"
+#include "hash-tree-proof.h"
+#include "hash-tree-stats.h"
 #include "interpret.h"
 #include "jsonrpc-fork-result.h"
 #include "machine-config.h"
 #include "machine-hash.h"
+#include "machine-reg.h"
 #include "machine-runtime-config.h"
-#include "machine.h"
+#include "page-hash-tree-cache-stats.h"
 #include "semantic-version.h"
 #include "uarch-interpret.h"
 
@@ -151,7 +153,7 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, semantic_version &v
 /// \param value Object to store value
 /// \param path Path to j
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, machine::reg &value, const std::string &path = "params/");
+void ju_get_opt_field(const nlohmann::json &j, const K &key, machine_reg &value, const std::string &path = "params/");
 
 /// \brief Attempts to load an interpreter_break_reason name from a field in a JSON object
 /// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
@@ -222,14 +224,34 @@ template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, std::optional<machine_hash> &optional,
     const std::string &path = "params/");
 
-/// \brief Attempts to load an Merkle tree proof object from a field in a JSON object
+/// \brief Attempts to load a hash-tree proof object from a field in a JSON object
 /// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
 /// \param j JSON object to load from
 /// \param key Key to load value from
 /// \param value Object to store value
 /// \param path Path to j
 template <typename K>
-void ju_get_opt_field(const nlohmann::json &j, const K &key, not_default_constructible<hash_tree::proof_type> &value,
+void ju_get_opt_field(const nlohmann::json &j, const K &key, not_default_constructible<hash_tree_proof> &value,
+    const std::string &path = "params/");
+
+/// \brief Attempts to load a page_hash_tree_cache_stats object from a field in a JSON object
+/// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
+/// \param j JSON object to load from
+/// \param key Key to load value from
+/// \param value Object to store value
+/// \param path Path to j
+template <typename K>
+void ju_get_opt_field(const nlohmann::json &j, const K &key, page_hash_tree_cache_stats &value,
+    const std::string &path = "params/");
+
+/// \brief Attempts to load a hash_tree_stats object from a field in a JSON object
+/// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
+/// \param j JSON object to load from
+/// \param key Key to load value from
+/// \param value Object to store value
+/// \param path Path to j
+template <typename K>
+void ju_get_opt_field(const nlohmann::json &j, const K &key, hash_tree_stats &value,
     const std::string &path = "params/");
 
 /// \brief Attempts to load an access_type name from a field in a JSON object
@@ -617,7 +639,9 @@ void ju_get_field(const nlohmann::json &j, const K &key, T &value, const std::st
 void to_json(nlohmann::json &j, const access_log::type &log_type);
 void to_json(nlohmann::json &j, const machine_hash &h);
 void to_json(nlohmann::json &j, const std::vector<machine_hash> &hs);
-void to_json(nlohmann::json &j, const hash_tree::proof_type &p);
+void to_json(nlohmann::json &j, const hash_tree_proof &p);
+void to_json(nlohmann::json &j, const page_hash_tree_cache_stats &s);
+void to_json(nlohmann::json &j, const hash_tree_stats &s);
 void to_json(nlohmann::json &j, const access &a);
 void to_json(nlohmann::json &j, const bracket_note &b);
 void to_json(nlohmann::json &j, const std::vector<bracket_note> &bs);
@@ -646,7 +670,7 @@ void to_json(nlohmann::json &j, const machine_config &config);
 void to_json(nlohmann::json &j, const concurrency_runtime_config &config);
 void to_json(nlohmann::json &j, const htif_runtime_config &config);
 void to_json(nlohmann::json &j, const machine_runtime_config &runtime);
-void to_json(nlohmann::json &j, const machine::reg &reg);
+void to_json(nlohmann::json &j, const machine_reg &reg);
 void to_json(nlohmann::json &j, const address_range_description &mrd);
 void to_json(nlohmann::json &j, const address_range_descriptions &mrds);
 void to_json(nlohmann::json &j, const fork_result &fork_result);
@@ -673,9 +697,9 @@ extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &k
     const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, semantic_version &value,
     const std::string &base = "params/");
-extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, machine::reg &value,
+extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, machine_reg &value,
     const std::string &base = "params/");
-extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, machine::reg &value,
+extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, machine_reg &value,
     const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, interpreter_break_reason &value,
     const std::string &base = "params/");
@@ -702,9 +726,17 @@ extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &k
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, machine_hash &value,
     const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key,
-    not_default_constructible<hash_tree::proof_type> &value, const std::string &base = "params/");
+    not_default_constructible<hash_tree_proof> &value, const std::string &base = "params/");
+extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key,
+    not_default_constructible<hash_tree_proof> &value, const std::string &base = "params/");
+extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, page_hash_tree_cache_stats &value,
+    const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key,
-    not_default_constructible<hash_tree::proof_type> &value, const std::string &base = "params/");
+    page_hash_tree_cache_stats &value, const std::string &base = "params/");
+extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, hash_tree_stats &value,
+    const std::string &base = "params/");
+extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, hash_tree_stats &value,
+    const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, access_type &value,
     const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, access_type &value,
diff --git a/src/jsonrpc-discover.json b/src/jsonrpc-discover.json
index 60de86bb9..40c9a4a93 100644
--- a/src/jsonrpc-discover.json
+++ b/src/jsonrpc-discover.json
@@ -353,7 +353,7 @@
     },
     {
       "name": "machine.get_proof",
-      "summary": "Obtains a Merkle proof for a range in the machine state",
+      "summary": "Obtains a hash-tree proof for a range in the machine state",
       "params": [
         {
           "name": "address",
@@ -380,6 +380,27 @@
         }
       }
     },
+    {
+      "name": "machine.get_hash_tree_stats",
+      "summary": "Returns statistics for the hash tree",
+      "params": [
+        {
+          "name": "clear",
+          "description": "Whether to clear the stats after retrieving them",
+          "required": true,
+          "schema": {
+              "type": "boolean"
+          }
+        }
+      ],
+      "result": {
+        "name": "stats",
+        "description": "Statistics for the hash tre",
+        "schema": {
+          "$ref": "#/components/schemas/HashTreeStats"
+        }
+      }
+    },
     {
       "name": "machine.read_word",
       "summary": "Reads a 64-bit word from memory (must be aligned)",
@@ -964,6 +985,55 @@
           }
         }
       },
+      "HashTreeStats": {
+        "title": "HashTreeStats",
+        "type": "object",
+        "properties": {
+          "phtc": {
+            "$ref": "#/components/schemas/PageHashTreeCacheStats"
+          },
+          "sparse_node_hashes": {
+            "$ref": "#/components/schemas/UnsignedInteger"
+          },
+          "dense_node_hashes": {
+            "$ref": "#/components/schemas/UnsignedIntegerArray"
+          }
+        }
+      },
+      "UnsignedIntegerArray": {
+        "title": "UnsignedIntegerArray",
+        "type": "array",
+        "items": {
+          "$ref": "#/components/schemas/UnsignedInteger"
+        }
+      },
+      "PageHashTreeCacheStats": {
+        "title": "PageHashTreeCacheStats",
+        "type": "object",
+        "properties": {
+          "page_hits": {
+            "$ref": "#/components/schemas/UnsignedInteger"
+          },
+          "page_misses": {
+            "$ref": "#/components/schemas/UnsignedInteger"
+          },
+          "word_hits": {
+            "$ref": "#/components/schemas/UnsignedInteger"
+          },
+          "word_misses": {
+            "$ref": "#/components/schemas/UnsignedInteger"
+          },
+          "inner_page_hashes": {
+            "$ref": "#/components/schemas/UnsignedInteger"
+          },
+          "pristine_pages": {
+            "$ref": "#/components/schemas/UnsignedInteger"
+          },
+          "non_pristine_pages": {
+            "$ref": "#/components/schemas/UnsignedInteger"
+          }
+        }
+      },
       "MachineRuntimeConfig": {
         "title": "MachineRuntimeConfig",
         "type": "object",
diff --git a/src/jsonrpc-machine.cpp b/src/jsonrpc-machine.cpp
index b6231ca09..0b97415af 100644
--- a/src/jsonrpc-machine.cpp
+++ b/src/jsonrpc-machine.cpp
@@ -747,8 +747,8 @@ machine_hash jsonrpc_machine::do_get_node_hash(uint64_t address, int log2_size)
     return hash;
 }
 
-i_machine::proof_type jsonrpc_machine::do_get_proof(uint64_t address, int log2_size) const {
-    not_default_constructible<proof_type> result;
+hash_tree_proof jsonrpc_machine::do_get_proof(uint64_t address, int log2_size) const {
+    not_default_constructible<hash_tree_proof> result;
     request("machine.get_proof", std::tie(address, log2_size), result);
     if (!result.has_value()) {
         throw std::runtime_error("jsonrpc server error: missing result");
@@ -781,6 +781,12 @@ uint64_t jsonrpc_machine::do_read_word(uint64_t address) const {
     return result;
 }
 
+hash_tree_stats jsonrpc_machine::do_get_hash_tree_stats(bool clear) {
+    hash_tree_stats result{};
+    request("machine.get_hash_tree_stats", std::tie(clear), result);
+    return result;
+}
+
 bool jsonrpc_machine::do_verify_hash_tree() const {
     bool result = false;
     request("machine.verify_hash_tree", std::tie(), result);
diff --git a/src/jsonrpc-machine.h b/src/jsonrpc-machine.h
index b13b16caa..70f28917f 100644
--- a/src/jsonrpc-machine.h
+++ b/src/jsonrpc-machine.h
@@ -102,7 +102,6 @@ class jsonrpc_machine final : public i_machine {
     const std::string &get_server_address() const;
 
 private:
-    machine_config do_get_initial_config() const override;
     i_machine *do_clone_empty() const override;
     bool do_is_empty() const override;
     void do_create(const machine_config &config, const machine_runtime_config &runtime) override;
@@ -121,13 +120,15 @@ class jsonrpc_machine final : public i_machine {
     access_log do_log_reset_uarch(const access_log::type &log_type) override;
     machine_hash do_get_root_hash() const override;
     machine_hash do_get_node_hash(uint64_t address, int log2_size) const override;
-    proof_type do_get_proof(uint64_t address, int log2_size) const override;
+    hash_tree_proof do_get_proof(uint64_t address, int log2_size) const override;
     void do_replace_memory_range(const memory_range_config &new_range) override;
     access_log do_log_step_uarch(const access_log::type &log_type) override;
     machine_runtime_config do_get_runtime_config() const override;
     void do_set_runtime_config(const machine_runtime_config &r) override;
     void do_destroy() override;
     uint64_t do_read_word(uint64_t address) const override;
+    machine_config do_get_initial_config() const override;
+    hash_tree_stats do_get_hash_tree_stats(bool clear) override;
     bool do_verify_hash_tree() const override;
     uarch_interpreter_break_reason do_run_uarch(uint64_t uarch_cycle_end) override;
     address_range_descriptions do_get_address_ranges() const override;
diff --git a/src/jsonrpc-remote-machine.cpp b/src/jsonrpc-remote-machine.cpp
index 4ac1cd69f..3cbdcfa40 100644
--- a/src/jsonrpc-remote-machine.cpp
+++ b/src/jsonrpc-remote-machine.cpp
@@ -1107,6 +1107,19 @@ static json jsonrpc_machine_get_proof_handler(const json &j, const std::shared_p
         session->handler->machine->get_proof(std::get<0>(args), static_cast<int>(std::get<1>(args))));
 }
 
+/// \brief JSONRPC handler for the machine.get_hash_tree_stats method
+/// \param j JSON request object
+/// \param session HTTP session
+/// \returns JSON response object
+static json jsonrpc_machine_get_hash_tree_stats_handler(const json &j, const std::shared_ptr<http_session> &session) {
+    if (!session->handler->machine) {
+        return jsonrpc_response_invalid_request(j, "no machine");
+    }
+    static const char *param_name[] = {"clear"};
+    auto args = parse_args<bool>(j, param_name);
+    return jsonrpc_response_ok(j, session->handler->machine->get_hash_tree_stats(std::get<0>(args)));
+}
+
 /// \brief JSONRPC handler for the machine.verify_hash_tree method
 /// \param j JSON request object
 /// \param session HTTP session
@@ -1488,9 +1501,10 @@ static json jsonrpc_dispatch_method(const json &j, const std::shared_ptr<http_se
         {"machine.log_reset_uarch", jsonrpc_machine_log_reset_uarch_handler},
         {"machine.verify_reset_uarch", jsonrpc_machine_verify_reset_uarch_handler},
         {"machine.verify_step_uarch", jsonrpc_machine_verify_step_uarch_handler},
+        {"machine.get_hash_tree_stats", jsonrpc_machine_get_hash_tree_stats_handler},
+        {"machine.get_node_hash", jsonrpc_machine_get_node_hash_handler},
         {"machine.get_proof", jsonrpc_machine_get_proof_handler},
         {"machine.get_root_hash", jsonrpc_machine_get_root_hash_handler},
-        {"machine.get_node_hash", jsonrpc_machine_get_node_hash_handler},
         {"machine.read_word", jsonrpc_machine_read_word_handler},
         {"machine.read_memory", jsonrpc_machine_read_memory_handler},
         {"machine.write_memory", jsonrpc_machine_write_memory_handler},
diff --git a/src/local-machine.cpp b/src/local-machine.cpp
index 51b21de16..4b858adb8 100644
--- a/src/local-machine.cpp
+++ b/src/local-machine.cpp
@@ -81,7 +81,7 @@ access_log local_machine::do_log_step_uarch(const access_log::type &log_type) {
     return get_machine()->log_step_uarch(log_type);
 }
 
-i_machine::proof_type local_machine::do_get_proof(uint64_t address, int log2_size) const {
+hash_tree_proof local_machine::do_get_proof(uint64_t address, int log2_size) const {
     return get_machine()->get_proof(address, log2_size);
 }
 
@@ -133,6 +133,10 @@ uint64_t local_machine::do_read_word(uint64_t address) const {
     return get_machine()->read_word(address);
 }
 
+hash_tree_stats local_machine::do_get_hash_tree_stats(bool clear) {
+    return get_machine()->get_hash_tree_stats(clear);
+}
+
 machine_config local_machine::do_get_initial_config() const {
     return get_machine()->get_initial_config();
 }
diff --git a/src/local-machine.h b/src/local-machine.h
index 350146492..93fccc583 100644
--- a/src/local-machine.h
+++ b/src/local-machine.h
@@ -52,7 +52,7 @@ class local_machine : public i_machine {
     interpreter_break_reason do_log_step(uint64_t mcycle_count, const std::string &filename) override;
     void do_store(const std::string &directory) const override;
     access_log do_log_step_uarch(const access_log::type &log_type) override;
-    proof_type do_get_proof(uint64_t address, int log2_size) const override;
+    hash_tree_proof do_get_proof(uint64_t address, int log2_size) const override;
     machine_hash do_get_root_hash() const override;
     machine_hash do_get_node_hash(uint64_t address, int log2_size) const override;
     bool do_verify_hash_tree() const override;
@@ -66,6 +66,7 @@ class local_machine : public i_machine {
     void do_replace_memory_range(const memory_range_config &new_range) override;
     uint64_t do_read_word(uint64_t address) const override;
     machine_config do_get_initial_config() const override;
+    hash_tree_stats do_get_hash_tree_stats(bool clear) override;
     machine_runtime_config do_get_runtime_config() const override;
     void do_set_runtime_config(const machine_runtime_config &r) override;
     void do_destroy() override;
diff --git a/src/machine-c-api.cpp b/src/machine-c-api.cpp
index 4248ff89c..de25eece0 100644
--- a/src/machine-c-api.cpp
+++ b/src/machine-c-api.cpp
@@ -743,12 +743,27 @@ cm_error cm_verify_reset_uarch(const cm_machine *m, const cm_hash *root_hash_bef
     return cm_result_failure();
 }
 
+cm_error cm_get_hash_tree_stats(cm_machine *m, bool clear, const char **stats) try {
+    if (stats == nullptr) {
+        throw std::invalid_argument("invalid stats output");
+    }
+    auto *cpp_m = convert_from_c(m);
+    const auto cpp_stats = cpp_m->get_hash_tree_stats(clear);
+    *stats = cm_set_temp_string(cartesi::to_json(cpp_stats).dump());
+    return cm_result_success();
+} catch (...) {
+    if (stats != nullptr) {
+        *stats = nullptr;
+    }
+    return cm_result_failure();
+}
+
 cm_error cm_get_proof(const cm_machine *m, uint64_t address, int32_t log2_size, const char **proof) try {
     if (proof == nullptr) {
         throw std::invalid_argument("invalid proof output");
     }
     const auto *cpp_m = convert_from_c(m);
-    const cartesi::i_machine::proof_type cpp_proof = cpp_m->get_proof(address, log2_size);
+    const auto cpp_proof = cpp_m->get_proof(address, log2_size);
     *proof = cm_set_temp_string(cartesi::to_json(cpp_proof).dump());
     return cm_result_success();
 } catch (...) {
diff --git a/src/machine-c-api.h b/src/machine-c-api.h
index 560f79409..c2928766c 100644
--- a/src/machine-c-api.h
+++ b/src/machine-c-api.h
@@ -728,13 +728,21 @@ CM_API cm_error cm_verify_send_cmio_response(const cm_machine *m, uint16_t reaso
 // Integrity checking
 // ------------------------------------
 
-/// \brief Verifies integrity of hash-tree tree against current machine state.
+/// \brief Verifies integrity of hash tree against current machine state.
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
 /// \param result True if tree is self-consistent, false otherwise.
 /// \returns 0 for success, non zero code for error.
 /// \details This method is used only for emulator internal tests.
 CM_API cm_error cm_verify_hash_tree(cm_machine *m, bool *result);
 
+/// \brief Obtains hash tree statistics
+/// \param m Pointer to a non-empty machine object (holds a machine instance).
+/// \param clear Whether to clear the statistics after retrieving them.
+/// \param stats Receives the statistics as a JSON object in a string,
+/// guaranteed to remain valid only until the next CM_API function is called from the same thread.
+/// \returns 0 for success, non zero code for error.
+CM_API cm_error cm_get_hash_tree_stats(cm_machine *m, bool clear, const char **stats);
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/src/machine.cpp b/src/machine.cpp
index 86ff4b7ba..2ac5de47b 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -40,6 +40,7 @@
 #include "compiler-defines.h"
 #include "device-state-access.h"
 #include "dtb.h"
+#include "hash-tree-proof.h"
 #include "hash-tree.h"
 #include "host-addr.h"
 #include "hot-tlb.h"
@@ -52,7 +53,6 @@
 #include "machine-hash.h"
 #include "machine-reg.h"
 #include "machine-runtime-config.h"
-#include "merkle-tree-proof.h"
 #include "page-hash-tree-cache.h"
 #include "pmas.h"
 #include "processor-state.h"
@@ -90,6 +90,10 @@ static_assert(static_cast<int>(AR_LOG2_PAGE_SIZE) == static_cast<int>(HASH_TREE_
 
 using namespace std::string_literals;
 
+hash_tree_stats machine::get_hash_tree_stats(bool clear) noexcept {
+    return m_ht.get_stats(clear);
+}
+
 void machine::init_uarch_processor(const uarch_processor_config &p) {
     if (p.backing_store.data_filename.empty() || p.backing_store.create) {
         // Initialize to default values first
diff --git a/src/machine.h b/src/machine.h
index 4f89daa81..8d1b56049 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -23,14 +23,14 @@
 #include <cstdint>
 #include <memory>
 #include <string>
+#include <unordered_map>
 #include <utility>
 #include <vector>
 
-#include <unordered_map>
-
 #include "access-log.h"
 #include "address-range-description.h"
 #include "address-range.h"
+#include "hash-tree-stats.h"
 #include "hash-tree.h"
 #include "host-addr.h"
 #include "i-device-state-access.h"
@@ -176,6 +176,11 @@ class machine final {
     /// \brief Destructor.
     ~machine();
 
+    /// \brief Returns hash-tree statistics
+    /// \param clear Clear all statistics after collecting them
+    /// \returns Structure containing all statistics
+    hash_tree_stats get_hash_tree_stats(bool clear = false) noexcept;
+
     /// \brief Runs the machine until mcycle reaches mcycle_end, the machine halts or yields.
     /// \param mcycle_end Maximum value of mcycle before function returns.
     /// \returns The reason the machine was interrupted.
diff --git a/src/page-hash-tree-cache-stats.h b/src/page-hash-tree-cache-stats.h
new file mode 100644
index 000000000..8d2977f5e
--- /dev/null
+++ b/src/page-hash-tree-cache-stats.h
@@ -0,0 +1,36 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef PAGE_HASH_TREE_CACHE_STATS_H
+#define PAGE_HASH_TREE_CACHE_STATS_H
+
+#include <cstdint>
+
+namespace cartesi {
+
+struct page_hash_tree_cache_stats {
+    uint64_t page_hits;          ///\< Number of pages looked up and found in cache
+    uint64_t page_misses;        ///\< Number of pages looked up but missing from cache
+    uint64_t word_hits;          ///\< Number of words equal to corresponding word in cache entry
+    uint64_t word_misses;        ///\< Number of words differing from corresponding word in cache entry
+    uint64_t inner_page_hashes;  ///\< Number of inner page hashing operations performed
+    uint64_t pristine_pages;     ///\< Number of pages found to be pristine during updates
+    uint64_t non_pristine_pages; ///\< Number of pages found not to be pristine during updates
+};
+
+} // namespace cartesi
+
+#endif // PAGE_HASH_TREE_CACHE_STATS_H
diff --git a/src/page-hash-tree-cache.h b/src/page-hash-tree-cache.h
index 16fb8b1a9..c95e2ac5e 100644
--- a/src/page-hash-tree-cache.h
+++ b/src/page-hash-tree-cache.h
@@ -17,6 +17,9 @@
 #ifndef PAGE_HASH_TREE_CACHE_H
 #define PAGE_HASH_TREE_CACHE_H
 
+/// \file
+/// \brief Page hash-tree cache interface
+
 #include <atomic>
 #include <functional>
 #include <iomanip>
@@ -35,17 +38,20 @@
 #include "is-pristine.h"
 #include "machine-hash.h"
 #include "meta.h"
+#include "page-hash-tree-cache-stats.h"
 #include "ranges.h"
 #include "strict-aliasing.h"
 
 namespace cartesi {
 
+/// \class page_hash_tree_cache
+/// \brief Page hash-tree cache implementation
 class page_hash_tree_cache {
 
     static constexpr int m_page_size = HASH_TREE_PAGE_SIZE;
     static constexpr int m_word_size = HASH_TREE_WORD_SIZE;
-    static constexpr int m_page_word_count = m_page_size / m_word_size;
-    static constexpr int m_page_hash_tree_size = 2 * m_page_word_count;
+    static constexpr int m_page_word_count = m_page_size / m_word_size; ///< Number of words in a page
+    static constexpr int m_page_hash_tree_size = 2 * m_page_word_count; ///< Number of words in a page hash-tree
 
     using address_type = uint64_t;
 
@@ -59,34 +65,48 @@ class page_hash_tree_cache {
     static_assert(POD<machine_hash>, "machine_hash must be trivially copyable and standard layout");
     static_assert(POD<page_hash_tree>, "page_hash_tree must be trivially copyable and standard layout");
 
+    /// \class entry
+    /// \brief Page hash-tree cache entry implementation
     class entry : public boost::intrusive::list_base_hook<> {
 
-        page m_page{};
-        page_hash_tree m_hash_tree{};
+        page m_page{};                ///< Page data for entry
+        page_hash_tree m_hash_tree{}; ///< Hash-tree of data
 
-        static constexpr uint64_t m_paddr_page_offset = 0;
-        static constexpr uint64_t m_borrowed_offset = sizeof(uint64_t);
+        // First hash is not used, so we use its storage for some fields
+        static constexpr uint64_t m_paddr_page_offset = 0;              ///< Offset where paddr_page is stored
+        static constexpr uint64_t m_borrowed_offset = sizeof(uint64_t); ///< Offset where borrowee flag is stored
 
         friend page_hash_tree_cache;
 
-        entry &set_paddr_page(uint64_t paddr_page) noexcept {
-            aliased_aligned_write<uint64_t>(&m_hash_tree[0][m_paddr_page_offset], paddr_page);
+        /// \brief Sets page address for entry
+        /// \param paddr_page Target physical address of page
+        /// \returns Reference to entry (for composition of operations)
+        entry &set_paddr_page(address_type paddr_page) noexcept {
+            aliased_aligned_write<uint64_t>(&m_hash_tree[0][m_paddr_page_offset], static_cast<uint64_t>(paddr_page));
             return *this;
         }
 
-        entry &set_borrowed(uint64_t borrowed) noexcept {
-            aliased_aligned_write<uint64_t>(&m_hash_tree[0][m_borrowed_offset], borrowed);
+        /// \brief Sets borrowed flag for entry
+        /// \param borrowed True if entry was borrowed
+        /// \returns Reference to entry (for composition of operations)
+        entry &set_borrowed(bool borrowed) noexcept {
+            aliased_aligned_write<uint64_t>(&m_hash_tree[0][m_borrowed_offset], static_cast<uint64_t>(borrowed));
             return *this;
         }
 
-        uint64_t get_borrowed() const noexcept {
-            return aliased_aligned_read<uint64_t>(&m_hash_tree[0][m_borrowed_offset]);
+        /// \brief Gets borrowed flag for entry
+        /// \returns Reference true if entry is borrowed
+        bool get_borrowed() const noexcept {
+            return static_cast<bool>(aliased_aligned_read<uint64_t>(&m_hash_tree[0][m_borrowed_offset]));
         }
 
+        /// \brief Make entry's page pristine
         void clear_page() noexcept {
             std::ranges::fill(m_page, 0);
         }
 
+        /// \brief Make entry's hash tree pristine
+        /// \param pristine Pristine hash tree
         void clear_hash_tree(const page_hash_tree &pristine) noexcept {
             auto paddr_page = get_paddr_page();
             auto borrowed = get_borrowed();
@@ -95,44 +115,40 @@ class page_hash_tree_cache {
             set_borrowed(borrowed);
         }
 
+        /// \brief Make entry's page and hash tree pristine, clear page address and borrowed flag
+        /// \param pristine Pristine hash tree
         void clear(const page_hash_tree &pristine) noexcept {
             clear_hash_tree(pristine);
             clear_page();
-            set_borrowed(0);
+            set_borrowed(false);
             set_paddr_page(0);
         }
 
+        /// \brief Returns index of left child of node in page hash tree
+        /// \param i Node index
+        /// \returns Index of node's left child
         static int left_child(int i) {
             return 2 * i;
         }
 
+        /// \brief Returns index of right child of node in page hash tree
+        /// \param i Node index
+        /// \returns Index of node's right child
         static int right_child(int i) {
             return (2 * i) + 1;
         }
 
+        /// \brief Returns index of parent of node in page hash tree
+        /// \param i Node index
+        /// \returns Index of node's parent
         static int parent(int i) {
             return i / 2;
         }
 
-    public:
-        explicit entry(const page_hash_tree &pristine) : m_hash_tree{pristine} {}
-
-        entry(const entry &other) = default;
-        entry(entry &&other) = default;
-        entry &operator=(const entry &other) = default;
-        entry &operator=(entry &&other) = default;
-        ~entry() = default;
-
-        uint64_t get_paddr_page() const noexcept {
-            return aliased_aligned_read<uint64_t>(&m_hash_tree[0][m_paddr_page_offset]);
-        }
-
-#ifdef DUMP_HASH_TREE_STATS
-        static std::atomic<int> m_word_hit;
-        static std::atomic<int> m_word_miss;
-        static std::atomic<int> m_inner_page_node_hashes;
-#endif
-
+        /// \brief Returns a pristine page tree for a given hasher
+        /// \tparam H Hasher type
+        /// \param h Hasher object
+        /// \returns Pristine page hash tree
         template <IHasher H>
         // NOLINTNEXTLINE(cppcoreguidelines-missing-std-forward)
         static page_hash_tree get_pristine_page_hash_tree(H &&h) noexcept {
@@ -150,124 +166,166 @@ class page_hash_tree_cache {
             return tree;
         }
 
+        /// \brief Returns entry's page
+        /// \returns Reference to entry's page
         const auto &get_page() const noexcept {
             return m_page;
         }
 
+        /// \brief Returns entry's page
+        /// \returns Reference to entry's page
+        auto &get_page() noexcept {
+            return m_page;
+        }
+
+        /// \brief Returns entry's page hash tree
+        /// \returns Reference to entry's page hash tree
+        const auto &get_page_hash_tree() const noexcept {
+            return m_hash_tree;
+        }
+
+        /// \brief Returns entry's page hash tree
+        /// \returns Reference to entry's page hash tree
+        auto &get_page_hash_tree() noexcept {
+            return m_hash_tree;
+        }
+
+    public:
+        /// \brief Constructor from pristine page
+        /// \param pristine Pristine page hash tree for hasher in use
+        explicit entry(const page_hash_tree &pristine) : m_hash_tree{pristine} {}
+
+        entry(const entry &other) = default;
+        entry(entry &&other) = default;
+        entry &operator=(const entry &other) = default;
+        entry &operator=(entry &&other) = default;
+        ~entry() = default;
+
+        /// \brief Returns page address for entry
+        /// \returns Target physical address of page
+        address_type get_paddr_page() const noexcept {
+            return static_cast<address_type>(aliased_aligned_read<uint64_t>(&m_hash_tree[0][m_paddr_page_offset]));
+        }
+
+        /// \brief Returns view to root hash from entry's page hash tree
+        /// \returns View to root hash
         const_machine_hash_view root_hash_view() const noexcept {
             return m_hash_tree[1];
         }
 
-        const_machine_hash_view node_hash_view(uint64_t address, int log2_size) const noexcept {
+        /// \brief Returns view to node hash from entry's page hash tree
+        /// \param offset Node offset within page
+        /// \param log2_size Log<sub>2</sub> of node size. Must be between log<sub>2</sub> of word and page sizes
+        /// \returns View to node hash
+        const_machine_hash_view node_hash_view(address_type offset, int log2_size) const noexcept {
             static constexpr machine_hash no_hash{};
             if (log2_size < HASH_TREE_LOG2_WORD_SIZE || log2_size > HASH_TREE_LOG2_PAGE_SIZE) {
                 assert(false && "log2_size is out of range");
                 return no_hash;
             }
-            auto start = UINT64_C(1) << (HASH_TREE_LOG2_PAGE_SIZE - log2_size);
-            auto index = address >> log2_size;
-            if (index > start || (index << log2_size) != address) {
-                assert(false && "address is out of range");
+            auto start = address_type{1} << (HASH_TREE_LOG2_PAGE_SIZE - log2_size);
+            auto index = offset >> log2_size;
+            if (index > start || (index << log2_size) != offset) {
+                assert(false && "offset is out of range");
                 return no_hash;
             }
             return m_hash_tree[start + index];
         }
+    };
 
-        template <IHasher H, ContiguousRangeOfByteLike D>
-        // NOLINTNEXTLINE(cppcoreguidelines-missing-std-forward)
-        bool update(H &&h, D &&d, const page_hash_tree &pristine) noexcept {
-            if (std::ranges::size(d) != m_page_size) {
-                return false;
-            }
-            if (is_pristine(d)) {
-                clear_hash_tree(pristine);
-                clear_page();
-                return true;
-            }
-            const const_page_view page{std::ranges::data(d), std::ranges::size(d)};
-            circular_buffer<int, m_page_word_count / 2> dirty_nodes;
-            // Go over all words in the entry page, comparing with updated page,
-            // and updating the hashes for the modified words
-            //??D In C++23, we would use std::views::slide and std::views::zip to write this in declarative style.
-            const page_view entry_page{m_page};
-#ifdef DUMP_HASH_TREE_STATS
-            int hit = 0;
-            int miss = 0;
-#endif
-            for (int offset = 0, index = m_page_word_count; offset < m_page_size; offset += m_word_size, ++index) {
-                const auto entry_word = entry_page.subspan(offset, m_word_size);
-                const auto page_word = page.subspan(offset, m_word_size);
-                if (!std::ranges::equal(entry_word, page_word)) {
-                    get_hash(h, page_word, m_hash_tree[index]);
-                    std::ranges::copy(page_word, entry_word.begin());
-                    dirty_nodes.try_push_back(parent(index));
-#ifdef DUMP_HASH_TREE_STATS
-                    ++miss;
-#endif
-                } else {
-#ifdef DUMP_HASH_TREE_STATS
-                    ++hit;
-#endif
-                }
+    /// \brief Updates and entry with new page data
+    /// \tparam H Hasher type
+    /// \tparam D Data range type
+    /// \param h Hasher object
+    /// \param d Contiguous range with new page data
+    /// \param e Entry to update
+    /// \returns True if update succeeded, false otherwise
+    template <IHasher H, ContiguousRangeOfByteLike D>
+    // NOLINTNEXTLINE(cppcoreguidelines-missing-std-forward)
+    bool update_entry(H &&h, D &&d, entry &e) noexcept {
+        if (std::ranges::size(d) != m_page_size) {
+            return false;
+        }
+        if (is_pristine(d)) {
+            e.clear_hash_tree(m_pristine_page_hash_tree);
+            e.clear_page();
+            ++m_pristine_pages;
+            return true;
+        }
+        ++m_non_pristine_pages;
+        const const_page_view page{std::ranges::data(d), std::ranges::size(d)};
+        circular_buffer<int, m_page_word_count / 2> dirty_nodes;
+        // Go over all words in the entry page, comparing with updated page,
+        // and updating the hashes for the modified words
+        //??D In C++23, we would use std::views::slide and std::views::zip to write this in declarative style.
+        const page_view entry_page{e.get_page()};
+        int hit = 0;
+        int miss = 0;
+        auto &page_tree = e.get_page_hash_tree();
+        for (int offset = 0, index = m_page_word_count; offset < m_page_size; offset += m_word_size, ++index) {
+            const auto entry_word = entry_page.subspan(offset, m_word_size);
+            const auto page_word = page.subspan(offset, m_word_size);
+            if (!std::ranges::equal(entry_word, page_word)) {
+                get_hash(h, page_word, page_tree[index]);
+                std::ranges::copy(page_word, entry_word.begin());
+                dirty_nodes.try_push_back(e.parent(index));
+                ++miss;
+            } else {
+                ++hit;
             }
-#ifdef DUMP_HASH_TREE_STATS
-            m_word_hit += hit;
-            m_word_miss += miss;
-#endif
-            // Now go over fifo, taking a node, updating its from its children, and enqueueing its parent for update
-#ifdef DUMP_HASH_TREE_STATS
-            int inner_page_node_hashes = 0;
-#endif
-            while (!dirty_nodes.empty()) {
-                const int index = dirty_nodes.front();
-                dirty_nodes.pop_front();
-#ifdef DUMP_HASH_TREE_STATS
-                ++inner_page_node_hashes;
-#endif
-                get_concat_hash(h, m_hash_tree[left_child(index)], m_hash_tree[right_child(index)], m_hash_tree[index]);
-                if (index != 1) {
-                    dirty_nodes.try_push_back(parent(index));
-                }
+        }
+        m_word_hits += hit;
+        m_word_misses += miss;
+        // Now go over fifo, taking a node, updating its from its children, and enqueueing its parent for update
+        int inner_page_hashes = 0;
+        while (!dirty_nodes.empty()) {
+            const int index = dirty_nodes.front();
+            dirty_nodes.pop_front();
+            ++inner_page_hashes;
+            get_concat_hash(h, page_tree[e.left_child(index)], page_tree[e.right_child(index)], page_tree[index]);
+            if (index != 1) {
+                dirty_nodes.try_push_back(e.parent(index));
             }
-#ifdef DUMP_HASH_TREE_STATS
-            m_inner_page_node_hashes += inner_page_node_hashes;
-#endif
-            return true;
         }
+        m_inner_page_hashes += inner_page_hashes;
+        return true;
+    }
 
-        template <IHasher H>
-        // NOLINTNEXTLINE(cppcoreguidelines-missing-std-forward)
-        bool verify(H &&h) noexcept {
-            std::cerr << "verifying entry\n";
-            const page_view entry_page{m_page};
-            for (int offset = 0, index = m_page_word_count; offset < m_page_size; offset += m_word_size, ++index) {
-                const auto page_word = entry_page.subspan(offset, m_word_size);
-                const auto page_word_hash = get_hash(h, page_word);
-                if (page_word_hash != m_hash_tree[index]) {
-                    const int log2_size = HASH_TREE_LOG2_WORD_SIZE;
+    template <IHasher H>
+    // NOLINTNEXTLINE(cppcoreguidelines-missing-std-forward)
+    bool verify_entry(H &&h, entry &e) noexcept {
+        std::cerr << "verifying entry\n";
+        const page_view entry_page{e.get_page()};
+        auto &page_tree = e.get_page_hash_tree();
+        for (int offset = 0, index = m_page_word_count; offset < m_page_size; offset += m_word_size, ++index) {
+            const auto page_word = entry_page.subspan(offset, m_word_size);
+            const auto page_word_hash = get_hash(h, page_word);
+            if (page_word_hash != page_tree[index]) {
+                const int log2_size = HASH_TREE_LOG2_WORD_SIZE;
+                std::cerr << "hash mismatch in index " << std::dec << index << ":" << log2_size << '\n';
+                return false;
+            }
+        }
+        int start = m_page_word_count / 2;
+        const int log2_size = HASH_TREE_LOG2_WORD_SIZE + 1;
+        while (start != 0) {
+            for (int index = start; index < 2 * start; ++index) {
+                const auto node_hash =
+                    get_concat_hash(h, page_tree[e.left_child(index)], page_tree[e.right_child(index)]);
+                if (node_hash != page_tree[index]) {
                     std::cerr << "hash mismatch in index " << std::dec << index << ":" << log2_size << '\n';
                     return false;
                 }
             }
-            int start = m_page_word_count / 2;
-            const int log2_size = HASH_TREE_LOG2_WORD_SIZE + 1;
-            while (start != 0) {
-                for (int index = start; index < 2 * start; ++index) {
-                    const auto node_hash =
-                        get_concat_hash(h, m_hash_tree[left_child(index)], m_hash_tree[right_child(index)]);
-                    if (node_hash != m_hash_tree[index]) {
-                        std::cerr << "hash mismatch in index " << std::dec << index << ":" << log2_size << '\n';
-                        return false;
-                    }
-                }
-                start /= 2;
-            }
-            return true;
+            start /= 2;
         }
-    };
-
-    // static_assert(POD<entry>, "entry must be trivially copyable and standard layout");
+        return true;
+    }
 
+    /// \brief Constructor from hasher and number of entries
+    /// \tparam H Hasher type
+    /// \param h Hasher object
+    /// \param num_entries Number of entries in cache
     template <IHasher H>
     page_hash_tree_cache(H &&h, size_t num_entries) :
         m_pristine_page_hash_tree{entry::get_pristine_page_hash_tree(std::forward<H>(h))},
@@ -280,97 +338,74 @@ class page_hash_tree_cache {
     page_hash_tree_cache &operator=(const page_hash_tree_cache &other) = delete;
     page_hash_tree_cache &operator=(page_hash_tree_cache &&other) = delete;
 
-    const page_hash_tree &get_pristine_page_hash_tree() const {
-        return m_pristine_page_hash_tree;
-    }
-
-    void dump_lru() const {
-        std::cerr << "lru: " << std::hex;
-        for (const auto &p : m_lru) {
-            std::cerr << "0x" << p.get_paddr_page() << " ";
-        }
-        std::cerr << "\n";
-    }
-
-    template <RangeOfByteLike D>
-    // NOLINTNEXTLINE(cppcoreguidelines-missing-std-forward)
-    void dump_hex(D &&bytes, std::ostream &out, size_t limit = -1) {
-        out << std::hex << std::setw(2) << std::setfill('0') << std::uppercase;
-        for (auto b :
-            bytes | views::cast_to<unsigned int> | std::views::take(std::min(limit, std::ranges::size(bytes)))) {
-            out << b;
-        }
-    }
-
-    void dump_map() const {
-        std::cerr << "map: " << std::hex;
-        for (const auto &[key, val] : m_map) {
-            std::cerr << "0x" << key << " ";
-        }
-        std::cerr << "\n";
-    }
-
-    std::optional<std::reference_wrapper<entry>> borrow_entry(uint64_t paddr_page, bool &hit) {
+    /// \brief Tries to borrow a cache entry
+    /// \param paddr_page Target physical address of page to borrow
+    /// \param hit Receives true if page was found in cache, false if another page was evicted and its entry returned
+    /// \returns Entry for page, nothing if all pages have already been borrowed
+    std::optional<std::reference_wrapper<entry>> borrow_entry(address_type paddr_page, bool &hit) {
         // Found entry for page in map?
         if (auto it = m_map.find(paddr_page); it != m_map.end()) {
             entry &e = it->second.second;
-            if (e.get_borrowed() != 0) {
+            if (e.get_borrowed()) {
                 throw std::runtime_error{"page hash-tree cache entry already borrowed"};
             }
             // Make it most recently used
             m_lru.splice(m_lru.begin(), m_lru, it->second.first);
             hit = true;
-#ifdef DUMP_HASH_TREE_STATS
-            ++m_page_hit;
-#endif
+            ++m_page_hits;
             // Return borrowed entry
-            return std::ref(e.set_borrowed(1));
+            return std::ref(e.set_borrowed(true));
         }
         hit = false;
         // Not in map, but we still have unused entries to lend
         if (m_used < m_entries.size()) {
-#ifdef DUMP_HASH_TREE_STATS
-            ++m_page_miss;
-#endif
+            ++m_page_misses;
             entry &e = m_entries[m_used++];
-            if (e.get_borrowed() != 0) {
+            if (e.get_borrowed()) {
                 throw std::runtime_error{"page hash-tree cache entry already borrowed"};
             }
             m_lru.push_front(e);
             m_map.emplace(paddr_page, map_value{m_lru.begin(), e});
             // Return borrowed
-            return std::ref(e.set_borrowed(1).set_paddr_page(paddr_page));
+            return std::ref(e.set_borrowed(true).set_paddr_page(paddr_page));
         }
         // Evict least recently used
         auto &e = m_lru.back();
         // If even that has been borrowed, we are out of entries to lend
-        if (e.get_borrowed() != 0) {
+        if (e.get_borrowed()) {
             return {};
         }
         m_map.erase(e.get_paddr_page());
         m_lru.pop_back();
         m_lru.push_front(e);
         m_map.emplace(paddr_page, map_value{m_lru.begin(), e});
-        return std::ref(e.set_borrowed(1).set_paddr_page(paddr_page));
+        return std::ref(e.set_borrowed(true).set_paddr_page(paddr_page));
     }
 
-    auto borrow_entry(uint64_t paddr_page) {
+    /// \brief Tries to borrow a cache entry
+    /// \param paddr_page Target physical address of page to borrow
+    /// \returns Entry for page, nothing if all pages have already been borrowed
+    auto borrow_entry(address_type paddr_page) {
         bool hit = false;
         return borrow_entry(paddr_page, hit);
     }
 
+    /// \brief Returns entry that has been borrowed
+    /// \param e Entry to return
     static bool return_entry(entry &e) {
-        if (e.get_borrowed() == 0) {
+        if (!e.get_borrowed()) {
             throw std::runtime_error{"returning page hash-tree cache entry that is not borrowed"};
         }
-        e.set_borrowed(0);
+        e.set_borrowed(false);
         return true;
     }
 
+    /// \brief Returns maximum number of entries in cache
     constexpr auto capacity() const noexcept {
         return m_entries.size();
     }
 
+    /// \brief Clear entire cache
     void clear() noexcept {
         m_lru.clear();
         m_map.clear();
@@ -380,54 +415,107 @@ class page_hash_tree_cache {
         m_used = 0;
     }
 
-    void clear_stats() noexcept {
-#ifdef DUMP_HASH_TREE_STATS
-        m_page_hit = 0;
-        m_page_miss = 0;
-        entry::m_inner_page_node_hashes = 0;
-        entry::m_word_hit = 0;
-        entry::m_word_miss = 0;
-#endif
+    /// \brief Returns current statistics
+    /// \param clear Whether to clear statistics after retrieving them
+    /// \returns Statistics
+    page_hash_tree_cache_stats get_stats(bool clear = false) noexcept {
+        auto s = page_hash_tree_cache_stats{
+            .page_hits = m_page_hits.load(),
+            .page_misses = m_page_misses.load(),
+            .word_hits = m_word_hits.load(),
+            .word_misses = m_word_misses.load(),
+            .inner_page_hashes = m_inner_page_hashes.load(),
+            .pristine_pages = m_pristine_pages.load(),
+            .non_pristine_pages = m_non_pristine_pages.load(),
+        };
+        if (clear) {
+            m_page_hits = 0;
+            m_page_misses = 0;
+            m_word_hits = 0;
+            m_word_misses = 0;
+            m_inner_page_hashes = 0;
+            m_pristine_pages = 0;
+            m_non_pristine_pages = 0;
+        }
+        return s;
     }
 
+    /// \brief Destructor
     ~page_hash_tree_cache() {
 #ifdef DUMP_HASH_TREE_STATS
-        auto all = m_page_hit + m_page_miss;
-        if (all > 0) {
-            std::cerr << "page hits: " << m_page_hit << '\n';
-            std::cerr << "page misses: " << m_page_miss << '\n';
-            std::cerr << "page hit rate: " << 100.0 * static_cast<double>(m_page_hit) / static_cast<double>(all)
+        auto s = get_stats();
+        auto pages_all = s.page_hits + s.page_misses;
+        if (pages_all > 0) {
+            std::cerr << "page hits: " << s.page_hits << '\n';
+            std::cerr << "page misses: " << s.page_misses << '\n';
+            std::cerr << "page hit rate: " << 100.0 * static_cast<double>(s.page_hits) / static_cast<double>(pages_all)
                       << '\n';
         }
-        auto word_hit = entry::m_word_hit.load();
-        auto word_miss = entry::m_word_miss.load();
-        auto word_all = word_hit + word_miss;
+        auto word_all = s.word_hits + s.word_misses;
         if (word_all > 0) {
-            std::cerr << "word hits: " << word_hit << '\n';
-            std::cerr << "word misses: " << word_miss << '\n';
-            std::cerr << "word hit rate: " << 100.0 * static_cast<double>(word_hit) / static_cast<double>(word_all)
+            std::cerr << "word hits: " << s.word_hits << '\n';
+            std::cerr << "word misses: " << s.word_misses << '\n';
+            std::cerr << "word hit rate: " << 100.0 * static_cast<double>(s.word_hits) / static_cast<double>(word_all)
                       << '\n';
         }
-        std::cerr << "inner page node hashes: " << entry::m_inner_page_node_hashes.load() << '\n';
+        std::cerr << "inner page hashes: " << s.inner_page_hashes << '\n';
+        auto pristine_all = s.pristine_pages + s.non_pristine_pages;
+        if (pristine_all > 0) {
+            std::cerr << "pristine pages: " << s.inner_page_hashes << '\n';
+            std::cerr << "non-pristine pages: " << s.inner_page_hashes << '\n';
+            std::cerr << "pristine page ratio: "
+                      << 100.0 * static_cast<double>(s.pristine_pages) / static_cast<double>(pristine_all) << '\n';
+        }
 #endif
     }
 
 private:
-    using lru = boost::intrusive::list<entry>;
-    using map_value = std::pair<lru::iterator, entry &>;
-    const page_hash_tree m_pristine_page_hash_tree;
+    void dump_lru() const {
+        std::cerr << "lru: " << std::hex;
+        for (const auto &p : m_lru) {
+            std::cerr << "0x" << p.get_paddr_page() << " ";
+        }
+        std::cerr << "\n";
+    }
+
+    template <RangeOfByteLike D>
+    // NOLINTNEXTLINE(cppcoreguidelines-missing-std-forward)
+    void dump_hex(D &&bytes, std::ostream &out, size_t limit = -1) {
+        out << std::hex << std::setw(2) << std::setfill('0') << std::uppercase;
+        for (auto b :
+            bytes | views::cast_to<unsigned int> | std::views::take(std::min(limit, std::ranges::size(bytes)))) {
+            out << b;
+        }
+    }
+
+    void dump_map() const {
+        std::cerr << "map: " << std::hex;
+        for (const auto &[key, val] : m_map) {
+            std::cerr << "0x" << key << " ";
+        }
+        std::cerr << "\n";
+    }
+
+    using lru = boost::intrusive::list<entry>;           ///< Least-recently-used container type
+    using map_value = std::pair<lru::iterator, entry &>; ///< Value type for map
+    const page_hash_tree m_pristine_page_hash_tree;      ///< Pristine page hash tree for hasher in use
     //??D Replace std::vector so entries can live on disk
-    std::vector<entry> m_entries;
+    std::vector<entry> m_entries; ///< Array of page hash-tree cache entries
     //??D Replace the boost intrusive list with index-based implementation so list can live on disk as well
-    lru m_lru;
+    lru m_lru; ///< Least-recently-used list of entries
     //??D Only the map will be reloaded from disk
     //??D We *could* also replace the implementation, but I think this would be overkill
-    std::unordered_map<address_type, map_value> m_map;
-    size_t m_used{0};
-#ifdef DUMP_HASH_TREE_STATS
-    size_t m_page_hit;
-    size_t m_page_miss;
-#endif
+    std::unordered_map<address_type, map_value> m_map; ///< Map from page addresses to corresponding entries
+    size_t m_used{0};                                  ///< How many entries have already been used
+
+    // Statistics
+    std::atomic<uint64_t> m_page_hits{0};         ///\< Number of pages looked up and found in cache
+    std::atomic<uint64_t> m_page_misses{0};       ///\< Number of pages looked up but missing from cache
+    std::atomic<uint64_t> m_word_hits{0};         ///\< Number of words equal to corresponding word in cache entry
+    std::atomic<uint64_t> m_word_misses{0};       ///\< Number of words differing from corresponding word in cache entry
+    std::atomic<uint64_t> m_inner_page_hashes{0}; ///\< Number of inner page hashing operations performed
+    std::atomic<uint64_t> m_pristine_pages{0};    ///\< Number of pages found to be pristine
+    std::atomic<uint64_t> m_non_pristine_pages{0}; ///\< Number of pages found not to be pristine
 };
 
 } // namespace cartesi
diff --git a/src/uarch-solidity-compat.h b/src/uarch-solidity-compat.h
index 3cd66e0b4..9e621b95f 100644
--- a/src/uarch-solidity-compat.h
+++ b/src/uarch-solidity-compat.h
@@ -27,6 +27,8 @@
 #include <cinttypes>
 #endif
 
+#include "shadow-tlb.h"
+
 /// \file
 /// \brief Solidity Compatibility Layer
 /// \brief The purpose of this file is to facilitate porting the uarch instruction interpreter to Solidity.
diff --git a/tests/misc/test-machine-c-api.cpp b/tests/misc/test-machine-c-api.cpp
index 0380bbb78..0dcd116e4 100644
--- a/tests/misc/test-machine-c-api.cpp
+++ b/tests/misc/test-machine-c-api.cpp
@@ -442,7 +442,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(get_proof_machine_hash_test, ordinary_machine_fix
     BOOST_CHECK_EQUAL(std::string(""), std::string(cm_get_last_error_message()));
 
     const auto proof =
-        cartesi::from_json<cartesi::not_default_constructible<cartesi::merkle_tree_proof>>(proof_str, "proof").value();
+        cartesi::from_json<cartesi::not_default_constructible<cartesi::hash_tree_proof>>(proof_str, "proof").value();
     auto proof_root_hash = proof.get_root_hash();
     auto verification = calculate_proof_root_hash(proof);
     BOOST_CHECK_EQUAL_COLLECTIONS(verification.begin(), verification.end(), proof_root_hash.begin(),
@@ -1547,7 +1547,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(machine_verify_hash_tree_proof_updates_test, ordi
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_OK);
     BOOST_CHECK_EQUAL(std::string(""), std::string(cm_get_last_error_message()));
     auto proof =
-        cartesi::from_json<cartesi::not_default_constructible<cartesi::merkle_tree_proof>>(proof_str, "proof").value();
+        cartesi::from_json<cartesi::not_default_constructible<cartesi::hash_tree_proof>>(proof_str, "proof").value();
     auto proof_root_hash = proof.get_root_hash();
     auto verification = calculate_proof_root_hash(proof);
     BOOST_CHECK_EQUAL_COLLECTIONS(verification.begin(), verification.end(), proof_root_hash.begin(),
@@ -1564,7 +1564,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(machine_verify_hash_tree_proof_updates_test, ordi
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_OK);
     BOOST_CHECK_EQUAL(std::string(""), std::string(cm_get_last_error_message()));
     proof =
-        cartesi::from_json<cartesi::not_default_constructible<cartesi::merkle_tree_proof>>(proof_str, "proof").value();
+        cartesi::from_json<cartesi::not_default_constructible<cartesi::hash_tree_proof>>(proof_str, "proof").value();
     proof_root_hash = proof.get_root_hash();
     verification = calculate_proof_root_hash(proof);
     BOOST_CHECK_EQUAL_COLLECTIONS(verification.begin(), verification.end(), proof_root_hash.begin(),
diff --git a/tests/misc/test-merkle-tree-hash.cpp b/tests/misc/test-merkle-tree-hash.cpp
index 80c565ccd..863a2ca13 100644
--- a/tests/misc/test-merkle-tree-hash.cpp
+++ b/tests/misc/test-merkle-tree-hash.cpp
@@ -30,9 +30,9 @@
 #include <back-merkle-tree.h>
 #include <complete-merkle-tree.h>
 #include <full-merkle-tree.h>
+#include <hash-tree-proof.h>
 #include <i-hasher.h>
 #include <keccak-256-hasher.h>
-#include <merkle-tree-proof.h>
 #include <unique-c-ptr.h>
 
 using namespace cartesi;
diff --git a/tests/misc/test-utils.h b/tests/misc/test-utils.h
index ba9ec2ca7..31e869201 100644
--- a/tests/misc/test-utils.h
+++ b/tests/misc/test-utils.h
@@ -17,11 +17,11 @@
 #include <string>
 
 #include <back-merkle-tree.h>
+#include <hash-tree-proof.h>
 #include <json-util.h>
 #include <keccak-256-hasher.h>
 #include <machine-c-api.h>
 #include <machine-hash.h>
-#include <merkle-tree-proof.h>
 
 using hash_type = cartesi::machine_hash;
 
@@ -65,7 +65,7 @@ static hash_type merkle_hash(const std::string_view &data, int log2_size) {
     return detail::merkle_hash(h, data, log2_size);
 }
 
-static hash_type calculate_proof_root_hash(const cartesi::merkle_tree_proof &proof) {
+static hash_type calculate_proof_root_hash(const cartesi::hash_tree_proof &proof) {
     hash_type hash;
     memcpy(hash.data(), proof.get_target_hash().data(), sizeof(cm_hash));
     for (int log2_size = static_cast<int>(proof.get_log2_target_size());

From 7d06e0ca587356dba63a3c5528af0526025095da Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Fri, 30 May 2025 17:30:43 +0100
Subject: [PATCH 38/82] refactor: cleanup os_signpost code

---
 src/hash-tree.cpp          | 53 +++++++++++++++-----------------------
 src/hash-tree.h            | 19 ++++++--------
 src/page-hash-tree-cache.h | 34 ++++++++++++++++++++----
 src/signposts.h            | 51 ++++++++++++++++++++++++++++++++++++
 4 files changed, 109 insertions(+), 48 deletions(-)
 create mode 100644 src/signposts.h

diff --git a/src/hash-tree.cpp b/src/hash-tree.cpp
index 65989bee2..a751cc679 100644
--- a/src/hash-tree.cpp
+++ b/src/hash-tree.cpp
@@ -27,26 +27,7 @@
 #include <omp.h>
 
 #include "machine-address-ranges.h"
-
-#ifdef __APPLE__
-#define CONCAT(x, y) x##y
-
-#define SCOPED_SIGNPOST_IMPL(log, id, name, line, ...)                                                                 \
-    struct CONCAT(scoped_signpost_, line) {                                                                            \
-        os_log_t m_log;                                                                                                \
-        os_signpost_id_t m_id;                                                                                         \
-        CONCAT(scoped_signpost_, line)(os_log_t l, os_signpost_id_t i) : m_log(l), m_id(i) {                           \
-            os_signpost_interval_begin(l, i, name, __VA_ARGS__);                                                       \
-        }                                                                                                              \
-        ~CONCAT(scoped_signpost_, line)() {                                                                            \
-            os_signpost_interval_end(m_log, m_id, name, __VA_ARGS__);                                                  \
-        }                                                                                                              \
-    } CONCAT(signpost_instance_, line)(log, id)
-
-#define SCOPED_SIGNPOST(log, id, name, ...) SCOPED_SIGNPOST_IMPL(log, id, name, __LINE__, __VA_ARGS__)
-#else
-#define SCOPED_SIGNPOST(log, id, name, ...)
-#endif
+#include "signposts.h"
 
 namespace cartesi {
 
@@ -216,9 +197,12 @@ bool hash_tree::return_updated_dirty_pages(address_ranges ars, dirty_pages &batc
     changed_address_ranges &changed_ars) {
     std::atomic<int> update_failed{0}; // NOLINT(misc-const-correctness)
 //??D The batch size past which we switch to parallel updates needs to be tuned empirically
+// constexpr auto chunk_size = 1;
+// #pragma omp parallel if (static_cast<int>(batch.size()) > chunk_size)
 #pragma omp parallel if (static_cast<int>(batch.size()) > omp_get_max_threads() * 4)
     {
         hasher_type h; // NOLINT(misc-const-correctness)
+// #pragma omp for schedule(static, chunk_size)
 #pragma omp for
         // NOLINTNEXTLINE(modernize-loop-convert)
         for (decltype(batch.size()) i = 0; i < batch.size(); ++i) {
@@ -275,7 +259,7 @@ hash_tree::~hash_tree() {
 }
 
 bool hash_tree::update_dirty_pages(address_ranges ars, changed_address_ranges &changed_ars) {
-    SCOPED_SIGNPOST(m_log, m_spid_update_page_hashes, "update page hashes", "");
+    SCOPED_SIGNPOST(m_log, m_spid_update_page_hashes, "hash-tree: update page hashes", "");
     bool update_failed = false;
     dirty_pages batch;
     batch.reserve(m_page_cache.capacity());
@@ -329,12 +313,15 @@ void hash_tree::update_and_clear_dense_node_entries(dense_node_entries &batch, i
         return;
     }
 //??D The batch size past which we switch to parallel updates needs to be tuned empirically
+// constexpr auto chunk_size = 2;
+// #pragma omp parallel if (static_cast<int>(batch.size()) > chunk_size)
 #pragma omp parallel if (static_cast<int>(batch.size()) > omp_get_max_threads() * 32)
     {
         hasher_type h; // NOLINT(misc-const-correctness)
 #ifdef DUMP_HASH_TREE_STATS
         int updates = 0;
 #endif
+// #pragma omp for schedule(static, chunk_size)
 #pragma omp for
         // NOLINTNEXTLINE(modernize-loop-convert)
         for (decltype(batch.size()) i = 0; i < batch.size(); ++i) {
@@ -356,7 +343,7 @@ void hash_tree::update_and_clear_dense_node_entries(dense_node_entries &batch, i
 }
 
 bool hash_tree::update_dense_trees(address_ranges ars, const changed_address_ranges &changed_ars) {
-    SCOPED_SIGNPOST(m_log, m_spid_update_dense_trees, "update dense trees", "");
+    SCOPED_SIGNPOST(m_log, m_spid_update_dense_trees, "hash-tree: update dense trees", "");
     if (changed_ars.empty()) {
         return true;
     }
@@ -391,7 +378,7 @@ bool hash_tree::update_dense_trees(address_ranges ars, const changed_address_ran
 }
 
 bool hash_tree::update_sparse_tree(address_ranges ars, const changed_address_ranges &changed_ars) {
-    SCOPED_SIGNPOST(m_log, m_spid_update_sparse_tree, "update sparse tree", "");
+    SCOPED_SIGNPOST(m_log, m_spid_update_sparse_tree, "hash-tree: update sparse tree", "");
     // If there no changed address ranges, we are done
     // Otherwise, allocate a fifo that holds at most one entry per changed address-range leaf-node
     // For each changed address-range leaf-node,
@@ -558,7 +545,7 @@ bool hash_tree::verify(address_ranges ars) const {
 }
 
 bool hash_tree::update(address_ranges ars) {
-    SCOPED_SIGNPOST(m_log, m_spid_update, "update hash tree", "");
+    SCOPED_SIGNPOST(m_log, m_spid_update, "hash-tree: update", "");
     omp_set_num_threads(m_concurrency);
     changed_address_ranges changed_ars;
     auto update_succeeded = update_dirty_pages(ars, changed_ars) && update_dense_trees(ars, changed_ars) &&
@@ -648,17 +635,19 @@ static int get_concurrency(int value) {
 }
 
 hash_tree::hash_tree(const hash_tree_config &config, uint64_t concurrency, const_address_ranges ars) :
-    m_sparse_nodes{create_nodes(ars)},
+#ifdef HAS_SIGNPOSTS
+    m_log{os_log_create("io.cartesi.machine-emulator", "hash-tree")},
+    m_spid_update{os_signpost_id_generate(m_log)},
+    m_spid_update_page_hashes{os_signpost_id_generate(m_log)},
+    m_spid_update_dense_trees{os_signpost_id_generate(m_log)},
+    m_spid_update_sparse_tree{os_signpost_id_generate(m_log)},
+    m_page_cache{m_log, hasher_type{}, config.phtc_size},
+#else
     m_page_cache{hasher_type{}, config.phtc_size},
+#endif
+    m_sparse_nodes{create_nodes(ars)},
     m_pristine_hashes{get_pristine_hashes()},
     m_concurrency{get_concurrency(static_cast<int>(concurrency))} {
-#ifdef __APPLE__
-    m_log = os_log_create("io.cartesi.machine-emulator", "hash-tree");
-    m_spid_update = os_signpost_id_generate(m_log);
-    m_spid_update_page_hashes = os_signpost_id_generate(m_log);
-    m_spid_update_dense_trees = os_signpost_id_generate(m_log);
-    m_spid_update_sparse_tree = os_signpost_id_generate(m_log);
-#endif
 }
 
 void hash_tree::check_address_ranges(const_address_ranges ars) {
diff --git a/src/hash-tree.h b/src/hash-tree.h
index c7d40e990..6c02a4cda 100644
--- a/src/hash-tree.h
+++ b/src/hash-tree.h
@@ -29,13 +29,9 @@
 #include "machine-config.h"
 #include "machine-hash.h"
 #include "page-hash-tree-cache.h"
+#include "signposts.h"
 #include "unique-c-ptr.h"
 
-#ifdef __APPLE__
-#include <os/log.h>
-#include <os/signpost.h>
-#endif
-
 namespace cartesi {
 
 class hash_tree {
@@ -169,12 +165,7 @@ class hash_tree {
     static nodes_type create_nodes(const_address_ranges ars);
     static void check_address_ranges(const_address_ranges ars);
 
-    //??D Replace std::vector so entries can live on disk
-    nodes_type m_sparse_nodes;
-    mutable page_hash_tree_cache m_page_cache;
-    const pristine_hashes m_pristine_hashes;
-    int m_concurrency;
-#ifdef __APPLE__
+#ifdef HAS_SIGNPOSTS
     os_log_t m_log;
     os_signpost_id_t m_spid_update;
     os_signpost_id_t m_spid_update_page_hashes;
@@ -182,6 +173,12 @@ class hash_tree {
     os_signpost_id_t m_spid_update_sparse_tree;
 #endif
 
+    mutable page_hash_tree_cache m_page_cache;
+    //??D Replace std::vector so entries can live on disk
+    nodes_type m_sparse_nodes;
+    const pristine_hashes m_pristine_hashes;
+    int m_concurrency;
+
     std::atomic<uint64_t> m_sparse_node_hashes{0};
     std::array<std::atomic<uint64_t>, HASH_TREE_LOG2_ROOT_SIZE> m_dense_node_hashes{};
 };
diff --git a/src/page-hash-tree-cache.h b/src/page-hash-tree-cache.h
index c95e2ac5e..a97212ea8 100644
--- a/src/page-hash-tree-cache.h
+++ b/src/page-hash-tree-cache.h
@@ -40,6 +40,7 @@
 #include "meta.h"
 #include "page-hash-tree-cache-stats.h"
 #include "ranges.h"
+#include "signposts.h"
 #include "strict-aliasing.h"
 
 namespace cartesi {
@@ -246,12 +247,17 @@ class page_hash_tree_cache {
         if (std::ranges::size(d) != m_page_size) {
             return false;
         }
-        if (is_pristine(d)) {
-            e.clear_hash_tree(m_pristine_page_hash_tree);
-            e.clear_page();
-            ++m_pristine_pages;
-            return true;
+        {
+            SCOPED_SIGNPOST(m_log, m_spid_pristine_check_and_update, "phtc: pristine check and update", "");
+            if (is_pristine(d)) {
+                SCOPED_SIGNPOST(m_log, m_spid_pristine_update, "phtc: pristine update", "");
+                e.clear_hash_tree(m_pristine_page_hash_tree);
+                e.clear_page();
+                ++m_pristine_pages;
+                return true;
+            }
         }
+        SCOPED_SIGNPOST(m_log, m_spid_non_pristine_update, "phtc: non-pristine update", "");
         ++m_non_pristine_pages;
         const const_page_view page{std::ranges::data(d), std::ranges::size(d)};
         circular_buffer<int, m_page_word_count / 2> dirty_nodes;
@@ -327,7 +333,16 @@ class page_hash_tree_cache {
     /// \param h Hasher object
     /// \param num_entries Number of entries in cache
     template <IHasher H>
+#ifndef HAS_SIGNPOSTS
     page_hash_tree_cache(H &&h, size_t num_entries) :
+#else
+    page_hash_tree_cache(os_log_t log, H &&h, size_t num_entries) :
+        m_log{log},
+        m_spid_borrow{os_signpost_id_generate(m_log)},
+        m_spid_pristine_check_and_update{os_signpost_id_generate(m_log)},
+        m_spid_pristine_update{os_signpost_id_generate(m_log)},
+        m_spid_non_pristine_update{os_signpost_id_generate(m_log)},
+#endif
         m_pristine_page_hash_tree{entry::get_pristine_page_hash_tree(std::forward<H>(h))},
         m_entries{num_entries, entry{m_pristine_page_hash_tree}} {
         m_map.reserve(num_entries);
@@ -343,6 +358,7 @@ class page_hash_tree_cache {
     /// \param hit Receives true if page was found in cache, false if another page was evicted and its entry returned
     /// \returns Entry for page, nothing if all pages have already been borrowed
     std::optional<std::reference_wrapper<entry>> borrow_entry(address_type paddr_page, bool &hit) {
+        SCOPED_SIGNPOST(m_log, m_spid_borrow, "phtc: borrow", "");
         // Found entry for page in map?
         if (auto it = m_map.find(paddr_page); it != m_map.end()) {
             entry &e = it->second.second;
@@ -496,6 +512,14 @@ class page_hash_tree_cache {
         std::cerr << "\n";
     }
 
+#ifdef HAS_SIGNPOSTS
+    os_log_t m_log;
+    os_signpost_id_t m_spid_borrow;
+    os_signpost_id_t m_spid_pristine_check_and_update;
+    os_signpost_id_t m_spid_pristine_update;
+    os_signpost_id_t m_spid_non_pristine_update;
+#endif
+
     using lru = boost::intrusive::list<entry>;           ///< Least-recently-used container type
     using map_value = std::pair<lru::iterator, entry &>; ///< Value type for map
     const page_hash_tree m_pristine_page_hash_tree;      ///< Pristine page hash tree for hasher in use
diff --git a/src/signposts.h b/src/signposts.h
new file mode 100644
index 000000000..ac38c7830
--- /dev/null
+++ b/src/signposts.h
@@ -0,0 +1,51 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef SIGNPOSTS_H
+#define SIGNPOSTS_H
+
+#if defined(__APPLE__) && defined(ISSUE_SIGNPOSTS)
+#define HAS_SIGNPOSTS
+#endif
+
+#ifdef HAS_SIGNPOSTS
+
+#include <os/log.h>
+#include <os/signpost.h>
+
+#define CONCAT(x, y) x##y
+
+#define SCOPED_SIGNPOST_IMPL(log, id, name, line, ...)                                                                 \
+    struct CONCAT(scoped_signpost_, line) {                                                                            \
+        os_log_t m_log;                                                                                                \
+        os_signpost_id_t m_id;                                                                                         \
+        CONCAT(scoped_signpost_, line)(os_log_t l, os_signpost_id_t i) : m_log(l), m_id(i) {                           \
+            os_signpost_interval_begin(l, i, name, __VA_ARGS__);                                                       \
+        }                                                                                                              \
+        ~CONCAT(scoped_signpost_, line)() {                                                                            \
+            os_signpost_interval_end(m_log, m_id, name, __VA_ARGS__);                                                  \
+        }                                                                                                              \
+    } CONCAT(signpost_instance_, line)(log, id)
+
+#define SCOPED_SIGNPOST(log, id, name, ...) SCOPED_SIGNPOST_IMPL(log, id, name, __LINE__, __VA_ARGS__)
+
+#else // HAS_SIGNPOSTS
+
+#define SCOPED_SIGNPOST(log, id, name, ...)
+
+#endif // HAS_SIGNPOSTS
+
+#endif // SIGNPOSTS_H

From b4adefb29fdd43e70d62a95bdb8cf6b09882dccb Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Tue, 3 Jun 2025 14:05:24 +0100
Subject: [PATCH 39/82] refactor: reduce number of openmp barriers

---
 src/hash-tree.cpp | 73 ++++++++++++++++++-----------------------------
 1 file changed, 28 insertions(+), 45 deletions(-)

diff --git a/src/hash-tree.cpp b/src/hash-tree.cpp
index a751cc679..36db258f1 100644
--- a/src/hash-tree.cpp
+++ b/src/hash-tree.cpp
@@ -195,24 +195,20 @@ bool hash_tree::update_dirty_page(hasher_type &h, address_range &ar, page_hash_t
 
 bool hash_tree::return_updated_dirty_pages(address_ranges ars, dirty_pages &batch,
     changed_address_ranges &changed_ars) {
+    if (batch.empty()) {
+        return true;
+    }
+    const int batch_size = static_cast<int>(batch.size());
     std::atomic<int> update_failed{0}; // NOLINT(misc-const-correctness)
-//??D The batch size past which we switch to parallel updates needs to be tuned empirically
-// constexpr auto chunk_size = 1;
-// #pragma omp parallel if (static_cast<int>(batch.size()) > chunk_size)
-#pragma omp parallel if (static_cast<int>(batch.size()) > omp_get_max_threads() * 4)
-    {
-        hasher_type h; // NOLINT(misc-const-correctness)
-// #pragma omp for schedule(static, chunk_size)
-#pragma omp for
-        // NOLINTNEXTLINE(modernize-loop-convert)
-        for (decltype(batch.size()) i = 0; i < batch.size(); ++i) {
-            auto &[ar_index, br, changed] = batch[i];
-            auto &ar = ars[ar_index];
-            if (!update_dirty_page(h, ar, br, changed)) {
-                update_failed.store(1, std::memory_order_relaxed);
-#pragma omp cancel for
-            }
-#pragma omp cancellation point for
+    //??D The batch size past which we switch to parallel updates needs to be tuned empirically
+    hasher_type h; // NOLINT(misc-const-correctness)
+#pragma omp parallel for private(h) if (batch_size > m_concurrency * 4)
+    // NOLINTNEXTLINE(modernize-loop-convert)
+    for (int i = 0; i < batch_size; ++i) {
+        auto &[ar_index, br, changed] = batch[i];
+        auto &ar = ars[ar_index];
+        if (!update_dirty_page(h, ar, br, changed)) {
+            update_failed.store(1, std::memory_order_relaxed);
         }
     }
     // Return all entries and collect address ranges that were actually changed by update
@@ -312,33 +308,22 @@ void hash_tree::update_and_clear_dense_node_entries(dense_node_entries &batch, i
     if (batch.empty()) {
         return;
     }
-//??D The batch size past which we switch to parallel updates needs to be tuned empirically
-// constexpr auto chunk_size = 2;
-// #pragma omp parallel if (static_cast<int>(batch.size()) > chunk_size)
-#pragma omp parallel if (static_cast<int>(batch.size()) > omp_get_max_threads() * 32)
-    {
-        hasher_type h; // NOLINT(misc-const-correctness)
-#ifdef DUMP_HASH_TREE_STATS
-        int updates = 0;
-#endif
-// #pragma omp for schedule(static, chunk_size)
-#pragma omp for
-        // NOLINTNEXTLINE(modernize-loop-convert)
-        for (decltype(batch.size()) i = 0; i < batch.size(); ++i) {
-            auto &[dht, offset] = batch[i];
-            auto child_size = UINT64_C(1) << (log2_size - 1);
-            auto parent = dht.node_hash_view(offset, log2_size);
-            auto left = dht.node_hash_view(offset, log2_size - 1);
-            auto right = dht.node_hash_view(offset + child_size, log2_size - 1);
-            get_concat_hash(h, left, right, parent);
-#ifdef DUMP_HASH_TREE_STATS
-            ++updates;
-#endif
-        }
-#ifdef DUMP_HASH_TREE_STATS
-        m_dense_node_hashes[log2_size] += updates;
-#endif
+    const int batch_size = static_cast<int>(batch.size());
+    //??D The batch size past which we switch to parallel updates needs to be tuned empirically
+    int updates = 0;
+    hasher_type h; // NOLINT(misc-const-correctness)
+#pragma omp parallel for private(h, updates) if (batch_size > m_concurrency * 32)
+    // NOLINTNEXTLINE(modernize-loop-convert)
+    for (decltype(batch.size()) i = 0; i < batch.size(); ++i) {
+        auto &[dht, offset] = batch[i];
+        auto child_size = UINT64_C(1) << (log2_size - 1);
+        auto parent = dht.node_hash_view(offset, log2_size);
+        auto left = dht.node_hash_view(offset, log2_size - 1);
+        auto right = dht.node_hash_view(offset + child_size, log2_size - 1);
+        get_concat_hash(h, left, right, parent);
+        ++updates;
     }
+    m_dense_node_hashes[log2_size] += updates;
     batch.clear();
 }
 
@@ -418,9 +403,7 @@ bool hash_tree::update_sparse_tree(address_ranges ars, const changed_address_ran
         auto left_hash_view = get_sparse_node_hash_view(inner_node.left, log2_size - 1);
         auto right_hash_view = get_sparse_node_hash_view(inner_node.right, log2_size - 1);
         get_concat_hash(h, left_hash_view, right_hash_view, inner_node.hash);
-#ifdef DUMP_HASH_TREE_STATS
         ++m_sparse_node_hashes;
-#endif
         if (!is_pristine(inner_node.parent)) {
             auto &parent_node = m_sparse_nodes[inner_node.parent];
             if (parent_node.marked == 0) {

From 95cf95ee6e338985866282297c41ebeac4af1779 Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Tue, 10 Jun 2025 11:14:33 +0100
Subject: [PATCH 40/82] feat: change omp schedule to dynamic

---
 src/hash-tree.cpp | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/hash-tree.cpp b/src/hash-tree.cpp
index 36db258f1..d349fb2ce 100644
--- a/src/hash-tree.cpp
+++ b/src/hash-tree.cpp
@@ -202,7 +202,7 @@ bool hash_tree::return_updated_dirty_pages(address_ranges ars, dirty_pages &batc
     std::atomic<int> update_failed{0}; // NOLINT(misc-const-correctness)
     //??D The batch size past which we switch to parallel updates needs to be tuned empirically
     hasher_type h; // NOLINT(misc-const-correctness)
-#pragma omp parallel for private(h) if (batch_size > m_concurrency * 4)
+#pragma omp parallel for private(h) schedule(dynamic) if (batch_size > m_concurrency * 4)
     // NOLINTNEXTLINE(modernize-loop-convert)
     for (int i = 0; i < batch_size; ++i) {
         auto &[ar_index, br, changed] = batch[i];
@@ -312,7 +312,7 @@ void hash_tree::update_and_clear_dense_node_entries(dense_node_entries &batch, i
     //??D The batch size past which we switch to parallel updates needs to be tuned empirically
     int updates = 0;
     hasher_type h; // NOLINT(misc-const-correctness)
-#pragma omp parallel for private(h, updates) if (batch_size > m_concurrency * 32)
+#pragma omp parallel for private(h, updates) schedule(dynamic) if (batch_size > m_concurrency * 32)
     // NOLINTNEXTLINE(modernize-loop-convert)
     for (decltype(batch.size()) i = 0; i < batch.size(); ++i) {
         auto &[dht, offset] = batch[i];
@@ -529,6 +529,7 @@ bool hash_tree::verify(address_ranges ars) const {
 
 bool hash_tree::update(address_ranges ars) {
     SCOPED_SIGNPOST(m_log, m_spid_update, "hash-tree: update", "");
+    auto old_concurrency = omp_get_num_threads();
     omp_set_num_threads(m_concurrency);
     changed_address_ranges changed_ars;
     auto update_succeeded = update_dirty_pages(ars, changed_ars) && update_dense_trees(ars, changed_ars) &&
@@ -538,6 +539,7 @@ bool hash_tree::update(address_ranges ars) {
             ars[ar_index].get_dirty_page_tree().clean();
         }
     }
+    omp_set_num_threads(old_concurrency);
     return update_succeeded;
 }
 

From ac4caa36fdc1ea746ff17226a4dcfef6e99645d3 Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Mon, 2 Jun 2025 17:38:46 -0300
Subject: [PATCH 41/82] feat: add `--dense-uarch-hashes` command line option

---
 src/cartesi-machine.lua | 59 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/src/cartesi-machine.lua b/src/cartesi-machine.lua
index 20d912bfb..73e1b6d78 100755
--- a/src/cartesi-machine.lua
+++ b/src/cartesi-machine.lua
@@ -499,6 +499,10 @@ where options are:
     this option implies --initial-hash and --final-hash.
     (default: none)
 
+  --dense-uarch-hashes=<number-length>[,<number-start>]
+    prints root hash every uarch cycle for <number-length> mcycles.
+    if <number-start> is given, the dense hashing will start at that mcycle.
+
   --log-step=<mcycle-count>,<filename>
     log and save a step of <mcycle-count> mcycles to <filename>.
 
@@ -690,6 +694,8 @@ local initial_proof = {}
 local final_proof = {}
 local periodic_hashes_period = math.maxinteger
 local periodic_hashes_start = 0
+local dense_uarch_hashes_start
+local dense_uarch_hashes_end
 local dump_memory_ranges = false
 local max_mcycle = math.maxinteger
 local max_uarch_cycle = 0
@@ -1561,6 +1567,23 @@ local options = {
             return true
         end,
     },
+    {
+        "^(%-%-dense%-uarch%-hashes%=(.*))$",
+        function(all, v)
+            if not v then return false end
+            string.gsub(v, "^([^%,]+),(.+)$", function(l, s)
+                dense_uarch_hashes_start = assert(util.parse_number(s), "invalid start " .. all)
+                dense_uarch_hashes_end = dense_uarch_hashes_start
+                    + assert(util.parse_number(l), "invalid length " .. all)
+            end)
+            if not dense_uarch_hashes_start then
+                dense_uarch_hashes_start = 0
+                dense_uarch_hashes_end = dense_uarch_hashes_start
+                    + assert(util.parse_number(v), "invalid length " .. all)
+            end
+            return true
+        end,
+    },
     {
         "^%-%-store%-config(%=?)(%g*)$",
         function(opts, v)
@@ -1745,6 +1768,10 @@ local function print_root_hash(machine, print)
     (print or stderr)("%u: %s\n", machine:read_reg("mcycle"), util.hexhash(machine:get_root_hash()))
 end
 
+local function print_uarch_root_hash(machine, mcycle, uarch_cycle, print)
+    (print or stderr)("%u,%u: %s\n", mcycle, uarch_cycle, util.hexhash(machine:get_root_hash()))
+end
+
 local function dump_value_proofs(machine, desired_proofs, config)
     if #desired_proofs > 0 then
         assert(config.processor.registers.iunrep == 0, "proofs are meaningless in unreproducible mode")
@@ -2215,6 +2242,38 @@ while math.ult(machine:read_reg("mcycle"), max_mcycle) do
     local next_mcycle = math.min(next_hash_mcycle, max_mcycle)
     if gdb_stub and gdb_stub:is_connected() then
         gdb_stub:run(next_mcycle)
+    elseif dense_uarch_hashes_start then
+        local current_mcycle = machine:read_reg("mcycle")
+        if
+            current_mcycle >= dense_uarch_hashes_start
+            and current_mcycle < dense_uarch_hashes_end
+            and current_mcycle < next_mcycle
+        then
+            if current_mcycle == dense_uarch_hashes_start then print_root_hash(machine) end
+            for step = 1, math.max(math.min(next_mcycle, dense_uarch_hashes_end) - current_mcycle, 0) do
+                for uarch_cycle = 1, math.maxinteger do
+                    local break_reason = machine:run_uarch(uarch_cycle)
+                    print_uarch_root_hash(machine, current_mcycle + step - 1, uarch_cycle)
+                    if machine:read_reg("uarch_halt_flag") ~= 0 then
+                        machine:reset_uarch()
+                        print_root_hash(machine)
+                        break
+                    end
+                    assert(break_reason == cartesi.UARCH_BREAK_REASON_REACHED_TARGET_CYCLE)
+                end
+                if
+                    machine:read_reg("iflags_H") ~= 0
+                    or machine:read_reg("iflags_X") ~= 0
+                    or machine:read_reg("iflags_Y") ~= 0
+                then
+                    break
+                end
+            end
+        elseif current_mcycle < dense_uarch_hashes_start then
+            machine:run(math.min(next_mcycle, dense_uarch_hashes_start))
+        else
+            machine:run(next_mcycle)
+        end
     else
         machine:run(next_mcycle)
     end

From 46013800ec28a6054708087faf9ee6edc66a7fb6 Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Thu, 3 Jul 2025 16:27:38 +0100
Subject: [PATCH 42/82] fix: fix hash-tree of non-power-of-two ranges

When a memory-range's length was not a power of two, the part past
the length was not assumed pristine as it should be. It was simply
ignored and the dense hash tree was trashed. This fixes the problem.
---
 src/dirty-page-tree.h | 64 +++++++++++++++++++++++--------------------
 src/hash-tree.cpp     | 14 +++++++---
 2 files changed, 44 insertions(+), 34 deletions(-)

diff --git a/src/dirty-page-tree.h b/src/dirty-page-tree.h
index 85d5de0e9..d79bbc1a3 100644
--- a/src/dirty-page-tree.h
+++ b/src/dirty-page-tree.h
@@ -64,6 +64,17 @@ class dirty_page_tree : public i_dirty_page_tree {
         return level_count;
     }
 
+    void build_from_leaves() {
+        for (auto level : levels_view() | std::views::drop(1)) {
+            for (auto pos : views::iterators(level_positions_view(level))) {
+                if (do_is_dirty_position(get_left_child_position(pos)) ||
+                    do_is_dirty_position(get_right_child_position(pos))) {
+                    m_tree[*pos] = status_type::dirty;
+                }
+            }
+        }
+    }
+
 public:
     /// \brief Constructor for leaves marked the same way
     /// \param leaf_count Number of leaves in tree. This is rounded up to the next power of 2.
@@ -72,28 +83,27 @@ class dirty_page_tree : public i_dirty_page_tree {
         i_dirty_page_tree{check_level_count(level_count, leaf_count)},
         m_leaf_positions{level_positions_view(0)},
         m_valid_positions{position_iterator(1), position_iterator(position_iterator::value_type{1} << level_count)},
-        m_tree{typename container_type::size_type{1} << level_count, init} {
-        // Leaves past leaf_count start clean because they don't really exist
-        if (init != status_type::clean) {
-            auto past_leaf_count = m_tree | std::views::drop(leaf_positions_view().front() + leaf_count);
-            std::ranges::fill(past_leaf_count, status_type::clean);
-        }
+        m_tree{typename container_type::size_type{1} << level_count, status_type::clean} {
+        const auto lp = m_leaf_positions;
+        const auto first_leaf = *lp.begin();
+        const auto first_pad = first_leaf + leaf_count;
+        const auto pad_count = *lp.end() - first_pad;
+        std::ranges::fill(std::span(m_tree).subspan(first_leaf, leaf_count), init);
+        std::ranges::fill(std::span(m_tree).subspan(first_pad, pad_count), status_type::dirty);
+        build_from_leaves();
     }
 
     /// \brief Constructor from initializer list
     /// \param leaves Status of first few leaves in tree.
     /// \details This is a constructor mostly used in simple tests
     explicit dirty_page_tree(int level_count, std::initializer_list<status_type> leaves) :
-        dirty_page_tree{level_count, leaves.size(), status_type::clean} {
-        std::ranges::copy(leaves, &m_tree[leaf_positions_view().front()]);
-        for (auto level : levels_view() | std::views::drop(1)) {
-            for (auto pos : views::iterators(level_positions_view(level))) {
-                if (is_dirty_position(get_left_child_position(pos)) ||
-                    is_dirty_position(get_right_child_position(pos))) {
-                    m_tree[*pos] = status_type::dirty;
-                }
-            }
-        }
+        i_dirty_page_tree{check_level_count(level_count, leaves.size())},
+        m_leaf_positions{level_positions_view(0)},
+        m_valid_positions{position_iterator(1), position_iterator(position_iterator::value_type{1} << level_count)},
+        m_tree{typename container_type::size_type{1} << level_count, status_type::clean} {
+        const auto lp = m_leaf_positions;
+        std::ranges::copy(leaves, &m_tree[*lp.begin()]);
+        build_from_leaves();
     }
 
     // Dump tree in DOT format
@@ -102,7 +112,7 @@ class dirty_page_tree : public i_dirty_page_tree {
         std::cout << "    node [shape=circle, width=0.5, height=0.5, fixedsize=true, style=filled];\n";
         std::cout << "  subgraph Dirty {\n";
         for (auto pos : views::iterators(valid_positions_view())) {
-            if (is_dirty_position(pos)) {
+            if (do_is_dirty_position(pos)) {
                 std::cout << "    A" << *pos << "[fillcolor=gray, label=\"" << *pos << "\"];\n";
             }
         }
@@ -217,7 +227,7 @@ class dirty_page_tree : public i_dirty_page_tree {
         while (pos != get_root_position()) {
             if (pos == get_left_sibling_position(pos)) {
                 const auto r = get_right_sibling_position(pos);
-                if (is_dirty_position(r)) {
+                if (do_is_dirty_position(r)) {
                     pos = r;
                     down(pos, level);
                     return;
@@ -231,9 +241,9 @@ class dirty_page_tree : public i_dirty_page_tree {
     void down(position_iterator &pos, positions_range level) const {
         while (!is_position_in(pos, level)) {
             auto el = get_left_child_position(pos);
-            if (!is_dirty_position(el)) {
+            if (!do_is_dirty_position(el)) {
                 auto r = get_right_child_position(pos);
-                if (!is_dirty_position(r)) {
+                if (!do_is_dirty_position(r)) {
                     // no more dirty entries
                     pos = invalid_position;
                     return;
@@ -245,13 +255,6 @@ class dirty_page_tree : public i_dirty_page_tree {
         }
     }
 
-    /// \brief Checks if node at valid position is dirty
-    /// \param node Position of node
-    /// \returns True if dirty, false otherwise
-    bool is_dirty_position(position_iterator pos) const {
-        return m_tree[*pos] == status_type::dirty;
-    }
-
     /// \brief Checks if node at valid position is clean
     /// \param node Position of node
     /// \returns True if clean, false otherwise
@@ -286,7 +289,7 @@ class dirty_page_tree : public i_dirty_page_tree {
     void do_mark_clean_leaf_position_and_up([[maybe_unused]] position_iterator pos) noexcept override {
         while (pos != get_root_position()) {
             m_tree[*pos] = status_type::clean;
-            if (m_tree[*get_sibling_position(pos)] != status_type::clean) {
+            if (do_is_dirty_position(get_sibling_position(pos))) {
                 return;
             }
             pos = get_parent_position(pos);
@@ -299,7 +302,7 @@ class dirty_page_tree : public i_dirty_page_tree {
     /// \details Assumes \p pos points to a leaf position
     void do_mark_dirty_leaf_position_and_up(position_iterator pos) noexcept override {
         while (pos != get_root_position()) {
-            if (m_tree[*pos] == status_type::dirty) {
+            if (do_is_dirty_position(pos)) {
                 return;
             }
             m_tree[*pos] = status_type::dirty;
@@ -310,7 +313,7 @@ class dirty_page_tree : public i_dirty_page_tree {
 
     /// \brief Tells if the node at given position is dirty
     bool do_is_dirty_position(position_iterator pos) const noexcept override {
-        return is_dirty_position(pos);
+        return m_tree[*pos] == status_type::dirty;
     }
 
     /// \brief Clean entire tree
@@ -318,6 +321,7 @@ class dirty_page_tree : public i_dirty_page_tree {
         for (auto pos : dirty_positions_view(leaf_positions_view())) {
             do_mark_clean_leaf_position_and_up(pos);
         }
+        assert(m_tree[*get_root_position()] == status_type::clean);
     }
 
     // -----
diff --git a/src/hash-tree.cpp b/src/hash-tree.cpp
index d349fb2ce..cd75eaae8 100644
--- a/src/hash-tree.cpp
+++ b/src/hash-tree.cpp
@@ -224,7 +224,7 @@ bool hash_tree::return_updated_dirty_pages(address_ranges ars, dirty_pages &batc
                 }
                 // If page was marked dirty but was not in fact dirty
             } else {
-                // We can safely mark the page clean because its contents already matched its
+                // We can safely mark the page clean because its contents already matched its hash
                 // So we won't need to "bubble-up" any hash changes based on it
                 ar.get_dirty_page_tree().mark_clean_page_and_up(offset);
             }
@@ -271,9 +271,15 @@ bool hash_tree::update_dirty_pages(address_ranges ars, changed_address_ranges &c
             break;
         }
         const auto start = ar.get_start();
-        auto view = ar.get_dirty_page_tree().dirty_offsets_view(HASH_TREE_LOG2_PAGE_SIZE) |
-            std::views::filter([length = ar.get_length()](auto offset) { return offset < length; });
-        for (auto offset : view) {
+        const auto length = ar.get_length();
+        auto &dht = ar.get_dense_hash_tree();
+        auto &dpt = ar.get_dirty_page_tree();
+        for (auto offset : dpt.dirty_offsets_view(HASH_TREE_LOG2_PAGE_SIZE)) {
+            if (offset >= length) {
+                auto hash_view = dht.node_hash_view(offset, HASH_TREE_LOG2_PAGE_SIZE);
+                std::ranges::copy(m_pristine_hashes[HASH_TREE_LOG2_PAGE_SIZE], hash_view.begin());
+                continue;
+            }
             const auto paddr_page = start + offset;
             auto opt_br = m_page_cache.borrow_entry(paddr_page);
             // If we have no entry, the cache ran out of entries to lend

From 4176588ec07973ab4ac88f11e8fef8e5e1b227cc Mon Sep 17 00:00:00 2001
From: Diego Nehab <1635557+diegonehab@users.noreply.github.com>
Date: Wed, 2 Jul 2025 13:36:59 +0100
Subject: [PATCH 43/82] feat: add collect hashes APIs

---
 src/cartesi/calldata.lua                      | 825 ++++++++++++++++++
 src/clua-i-machine.cpp                        |  58 +-
 src/collect-mcycle-hashes-state-access.h      | 171 ++++
 src/collect-uarch-cycle-hashes-state-access.h | 127 +++
 src/hash-tree.cpp                             | 179 +++-
 src/hash-tree.h                               |  13 +-
 src/i-machine.h                               |  18 +
 src/interpret.cpp                             |   3 +
 src/json-util.cpp                             | 127 ++-
 src/json-util.h                               |  53 +-
 src/jsonrpc-discover.json                     | 104 ++-
 src/jsonrpc-machine.cpp                       |   9 +
 src/jsonrpc-machine.h                         |   3 +
 src/jsonrpc-remote-machine.cpp                |  85 +-
 src/jsonrpc-version.h                         |   2 +-
 src/local-machine.cpp                         |   9 +
 src/local-machine.h                           |   3 +
 src/machine-c-api.cpp                         |  35 +-
 src/machine-c-api.h                           |  48 +
 src/machine-hash.h                            |   2 +
 src/machine.cpp                               | 134 ++-
 src/machine.h                                 |  28 +-
 src/mcycle-root-hashes.h                      |  36 +
 src/page-hash-tree-cache.h                    |  62 +-
 src/record-step-state-access.h                |   1 -
 src/test-calldata.lua                         | 751 ++++++++++++++++
 src/test-collect-hashes.lua                   | 217 +++++
 src/uarch-cycle-root-hashes.h                 |  36 +
 src/uarch-interpret.cpp                       |  14 +-
 src/uarch-interpret.h                         |  15 +-
 src/uarch-step.cpp                            |   4 +
 src/uarch-step.h                              |  12 +
 32 files changed, 3066 insertions(+), 118 deletions(-)
 create mode 100644 src/cartesi/calldata.lua
 create mode 100644 src/collect-mcycle-hashes-state-access.h
 create mode 100644 src/collect-uarch-cycle-hashes-state-access.h
 create mode 100644 src/mcycle-root-hashes.h
 create mode 100644 src/test-calldata.lua
 create mode 100755 src/test-collect-hashes.lua
 create mode 100644 src/uarch-cycle-root-hashes.h

diff --git a/src/cartesi/calldata.lua b/src/cartesi/calldata.lua
new file mode 100644
index 000000000..7f58f40cb
--- /dev/null
+++ b/src/cartesi/calldata.lua
@@ -0,0 +1,825 @@
+-- Copyright Cartesi and individual authors (see AUTHORS)
+-- SPDX-License-Identifier: LGPL-3.0-or-later
+--
+-- This program is free software: you can redistribute it and/or modify it under
+-- the terms of the GNU Lesser General Public License as published by the Free
+-- Software Foundation, either version 3 of the License, or (at your option) any
+-- later version.
+--
+-- This program is distributed in the hope that it will be useful, but WITHOUT ANY
+-- WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+-- PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+--
+-- You should have received a copy of the GNU Lesser General Public License along
+-- with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+--
+
+local lpeg = require("lpeg")
+local bint_extra = 256
+local bint = require("bint")(256 + bint_extra)
+
+local P, R, S, C, Ct, V, Cmt, Carg = lpeg.P, lpeg.R, lpeg.S, lpeg.C, lpeg.Ct, lpeg.V, lpeg.Cmt, lpeg.Carg
+local cartesi = require("cartesi")
+local keccak = cartesi.keccak
+
+local tinsert = table.insert
+
+local _M = {}
+
+_M.bint = bint
+
+-- Appends to 'output' the entire contents of 'more'
+local function tappend(output, more)
+    for _, v in ipairs(more) do
+        tinsert(output, v)
+    end
+end
+
+-- Throws formatted error
+local function errorf(fmt, ...) error(string.format(fmt, ...)) end
+
+-- Converts 'value' (a bint) to a its 256-bit big-endian represantation as a string
+local function tobe(value) return bint.tobe(value):sub(bint_extra / 8 + 1) end
+
+-- Converts 'hex' (an hex-encoded sequence of bytes) to the corresponding decoded string
+local function fromhex(hex)
+    if not hex then return nil, "missing hex string" end
+    if type(hex) ~= "string" then return nil, "hex not a string" end
+    if string.lower(hex:sub(1, 2)) ~= "0x" then return nil, 'hex string must start with "0x"' end
+    if #hex % 2 ~= 0 then return nil, "hex string length must be even" end
+    local invalid
+    local data = string.gsub(hex:sub(3), "(..)", function(c)
+        local n = tonumber(c, 16)
+        if not n then
+            invalid = c
+            n = 0
+        end
+        return string.char(n)
+    end)
+    if invalid then
+        return nil, string.format("hex string cannot contain %q", invalid)
+    else
+        return data
+    end
+end
+
+-- Converts 's' to an hex-encoded string
+local function tohex(s)
+    if type(s) ~= "string" then return nil, "expected string, got " .. type(s) end
+    return "0x" .. (string.gsub(s, ".", function(c) return string.format("%02x", string.byte(c)) end))
+end
+
+-- Returns a pattern that saves the current position and an associated message before trying to match 'pat'
+-- This is used for error reporting, should the matching fail later on
+local function expect(what, pat)
+    return Cmt(Carg(1), function(_s, pos, err)
+        if pos >= err.pos then
+            err.pos = pos
+            err.what = what
+        end
+    end) + pat
+end
+
+local opsp = S(" \t\n\r") ^ 0 -- optional spaces
+local leadit = R("19") -- non-zero leading digit
+local digit = R("09") -- following digits
+local idfirst = R("az", "AZ", "__") -- first identifier character
+local idrest = R("az", "AZ", "__", "09") -- remaining identifier character
+local idnot = -idrest -- the end of an identifier
+
+local identifier = expect("identifier", idfirst * idrest ^ 0)
+
+-- an int or uint size
+local int_size_idnot = expect(
+    "integer size",
+    Cmt((leadit * digit ^ 0) ^ -1 * idnot, function(_s, pos, size)
+        if size == "" then return pos, 256 end
+        local n = tonumber(size)
+        return n >= 8 and n <= 256 and n % 8 == 0 and pos, n
+    end)
+)
+
+local bytes_size_idnot = expect(
+    "bytes size",
+    Cmt((leadit * digit ^ 0) ^ -1 * idnot, function(_s, pos, size)
+        if size == "" then return pos, nil end
+        local n = tonumber(size)
+        return n >= 1 and n <= 32 and pos, n
+    end)
+)
+
+-- grammar to parse a type
+local type_spec = P({
+    "type_spec",
+
+    data_location = P("memory") + P("calldata") + P("storage"),
+
+    type_spec = V("elementary_type_spec") * opsp * V("array_brackets") * opsp * C(V("data_location") ^ -1) * opsp * C(
+        identifier ^ -1
+    ) / function(elem, brackets, location, name)
+        for _, size in ipairs(brackets) do
+            elem = {
+                type_name = "array",
+                element_type = elem,
+                size = size ~= "" and tonumber(size) or nil,
+            }
+        end
+        elem.name = name ~= "" and name or nil
+        elem.data_location = location ~= "" and location or nil
+        return elem
+    end,
+
+    elementary_type_spec = V("int") + V("uint") + V("bytes") + V("address") + V("string") + V("bool") + V("tuple"),
+
+    sized_array_bracket = P("[") * opsp * C(leadit * digit ^ 0) * opsp * expect("closing bracket", P("]")),
+
+    empty_array_bracket = P("[") * opsp * C("") * expect("closing bracket or array size", P("]")),
+
+    array_bracket = V("empty_array_bracket") + V("sized_array_bracket"),
+
+    array_brackets = Ct(V("array_bracket") ^ 0),
+
+    non_empty_component_list = V("type_spec") * opsp * (P(",") * opsp * expect("type spec", V("type_spec"))) ^ 0,
+
+    tuple = P("(")
+        * opsp
+        * Ct(V("non_empty_component_list") ^ -1)
+        * opsp
+        * expect("closing parenthesis", P(")"))
+        / function(components) return { type_name = "tuple", components = components or {} } end,
+
+    uint = P("uint") * int_size_idnot / function(size) return { type_name = "uint", size = size } end,
+
+    int = P("int") * int_size_idnot / function(size) return { type_name = "int", size = size } end,
+
+    bytes = P("bytes") * bytes_size_idnot / function(size) return { type_name = "bytes", size = size } end,
+
+    address = P("address") * idnot / function() return { type_name = "address" } end,
+
+    bool = P("bool") * idnot / function() return { type_name = "bool" } end,
+
+    string = P("string") * idnot / function() return { type_name = "string" } end,
+})
+
+local non_empty_component_list = type_spec * opsp * (P(",") * opsp * expect("type spec", type_spec)) ^ 0
+
+local tuple = P("(")
+    * opsp
+    * Ct(non_empty_component_list ^ -1)
+    * opsp
+    * expect("closing parenthesis", P(")"))
+    / function(components) return { type_name = "tuple", components = components or {} } end
+
+-- grammar for a function signature
+local func_sig = opsp
+    * Ct(
+        (P("function") * idnot * opsp) ^ -1
+            * C(expect("identifier", identifier * opsp))
+            * expect("parameters", tuple)
+            * opsp
+            * (P("returns") * idnot * opsp * expect("return parameters", tuple)) ^ -1
+    )
+    / function(parts)
+        return {
+            name = parts[1],
+            params = parts[2],
+            returns = parts[3] or { type_name = "tuple", components = {} },
+        }
+    end
+    * opsp
+    * -1
+
+-- check if the return 'ret' of a call to match() succeeded, otherwise use the 'err' table and the
+-- original input 's' to create an error message and throw
+local function check_match_error(s, ret, err)
+    if not ret then
+        local pos = assert(err.pos, "expected error position")
+        local line, line_pos = 1, 0
+        string.gsub(s:sub(1, pos - 1), "()\n", function(lp)
+            line = line + 1
+            line_pos = lp
+        end)
+        local col = pos - line_pos
+        local ctx = s:sub(pos, pos + 8)
+        if #s - pos > 8 then ctx = ctx .. "..." end
+        errorf("expected %s at line %d, column %d (got %q)", err.what, line, col, ctx)
+    end
+    return ret
+end
+
+-- append to 'output' table string pieces of the canonic type signature for 'parsed_type_spec'
+local function append_canonic_type_sig(output, parsed_type_spec)
+    local tn = parsed_type_spec.type_name
+    if tn == "uint" then
+        tinsert(output, "uint")
+        tinsert(output, parsed_type_spec.size)
+    elseif tn == "int" then
+        tinsert(output, "int")
+        tinsert(output, parsed_type_spec.size)
+    elseif tn == "address" then
+        tinsert(output, "address")
+    elseif tn == "bool" then
+        tinsert(output, "bool")
+    elseif tn == "string" then
+        tinsert(output, "string")
+    elseif tn == "bytes" then
+        tinsert(output, "bytes")
+        if parsed_type_spec.size then tinsert(output, parsed_type_spec.size) end
+    elseif tn == "array" then
+        append_canonic_type_sig(output, parsed_type_spec.element_type)
+        tinsert(output, "[")
+        if parsed_type_spec.size then tinsert(output, parsed_type_spec.size) end
+        tinsert(output, "]")
+    elseif tn == "tuple" then
+        tinsert(output, "(")
+        for i, comp in ipairs(parsed_type_spec.components) do
+            append_canonic_type_sig(output, comp)
+            if parsed_type_spec.components[i + 1] then tinsert(output, ",") end
+        end
+        tinsert(output, ")")
+    else
+        -- luacov: disable
+        error("unknown type name: " .. tostring(tn))
+        -- luacov: enable
+    end
+end
+
+-- returns the canonic type signature for 'parsed_type_spec'
+local function canonic_func_sig(parsed_func_sig)
+    local output = {}
+    tinsert(output, parsed_func_sig.name)
+    tinsert(output, "(")
+    local ps = parsed_func_sig.params.components
+    for i, p in ipairs(ps) do
+        append_canonic_type_sig(output, p)
+        if ps[i + 1] then tinsert(output, ",") end
+    end
+    tinsert(output, ")")
+    return table.concat(output)
+end
+
+-- parsed function signature cache
+-- this avoids repeated parsing of the same function signature
+-- a parsed function signature will remain in cache at least as long as a string with that signature exists in Lua
+-- once the string is collected, the corresponding parsed signature may be collected too
+local parsed_func_sig_cache = setmetatable({}, { __mode = "k" })
+
+-- returns a parsed function signature and the corresponding canonic signature
+function _M.parse_func_sig(sig)
+    assert(type(sig) == "string", "expected string")
+    local cached = parsed_func_sig_cache[sig]
+    if cached then return cached.parsed_func_sig, cached.func_sel, cached.canonic_func_sig end
+    local err = { pos = 0, what = "unknown error" }
+    local parsed_sig = check_match_error(sig, func_sig:match(sig, 1, err), err)
+    local canonic_sig = canonic_func_sig(parsed_sig)
+    local func_sel = keccak(canonic_sig):sub(1, 4)
+    parsed_func_sig_cache[sig] = {
+        parsed_func_sig = parsed_sig,
+        func_sel = func_sel,
+        canonic_func_sig = canonic_sig,
+    }
+    return parsed_sig, func_sel, canonic_sig
+end
+
+local type_spec_only = opsp * type_spec * opsp * -1
+
+-- returns a parsed type
+function _M.parse_type_spec(s)
+    local err = { pos = 0, what = "unknown error" }
+    return check_match_error(s, type_spec_only:match(s, 1, err), err)
+end
+
+-- traverses a 'parsed_type_spec' marking all types that are dynamic and otherwise computing the static sizes
+local function mark_dynamic_types(parsed_type_spec)
+    local tn = parsed_type_spec.type_name
+    if tn == "string" then
+        parsed_type_spec.is_dynamic = true
+    elseif tn == "bytes" then
+        if parsed_type_spec.size then
+            parsed_type_spec.is_dynamic = false
+            parsed_type_spec.static_size = 32
+        else
+            parsed_type_spec.is_dynamic = true
+        end
+        parsed_type_spec.is_dynamic = not parsed_type_spec.size
+    elseif tn == "array" then
+        mark_dynamic_types(parsed_type_spec.element_type)
+        parsed_type_spec.is_dynamic = parsed_type_spec.element_type.is_dynamic or not parsed_type_spec.size
+        if not parsed_type_spec.is_dynamic then
+            parsed_type_spec.static_size = parsed_type_spec.size * parsed_type_spec.element_type.static_size
+        end
+    elseif tn == "tuple" then
+        -- Tuple is dynamic if any of its components is dynamic
+        local is_dynamic = false
+        local static_size = 0
+        for _, component in ipairs(parsed_type_spec.components) do
+            mark_dynamic_types(component)
+            if component.is_dynamic then
+                is_dynamic = true
+                static_size = static_size + 32
+            else
+                static_size = static_size + component.static_size
+            end
+        end
+        parsed_type_spec.is_dynamic = is_dynamic
+        parsed_type_spec.static_size = static_size
+    else -- "uint", "int", "address", "bool"
+        parsed_type_spec.static_size = 32
+        parsed_type_spec.is_dynamic = false
+    end
+end
+
+-- returns true if a 'parsed_type_spec' is a dynamic type, else, returns false and the static size.
+-- uses memoization to avoid recomputation.
+local function is_dynamic_type(parsed_type_spec)
+    if parsed_type_spec.is_dynamic == nil then mark_dynamic_types(parsed_type_spec) end
+    return parsed_type_spec.is_dynamic, parsed_type_spec.static_size
+end
+
+local append_encoded_value -- forward declaration
+
+-- address and bytes are supposed to be hex-encoded into strings, which are then converted to binary
+-- if the content is already binary, we provide a simple wrapper that avoids the round-trip conversion
+local raw_meta = { __tostring = function(self) return string.format("raw(%q)", self[1]) end }
+
+-- strings are supposed to be raw strings
+-- if the content hex-encoded, we provide a simple wrapper forces conversion to raw before use
+local hex_meta = { __tostring = function(self) return string.format("hex(%q)", self[1]) end }
+
+-- returns true if the data is a wrapped binary string
+local function is_raw(b) return getmetatable(b) == raw_meta end
+_M.is_raw = is_raw
+
+-- returns true if the data is a wrapped hex string
+local function is_hex(b) return getmetatable(b) == hex_meta end
+_M.is_hex = is_hex
+
+-- wraps a string to tell us it is raw data when we might expect hex-encoded
+function _M.raw(s)
+    if is_raw(s) then return s end
+    assert(type(s) == "string")
+    return setmetatable({ s }, raw_meta)
+end
+
+-- wraps a string to tell us it is encoded in hex when we might expect raw data
+function _M.hex(s)
+    if is_hex(s) then return s end
+    assert(type(s) == "string")
+    return setmetatable({ s }, hex_meta)
+end
+
+-- gets the underlying binary data
+local function get_raw(b) return b[1] end
+_M.get_raw = get_raw
+
+-- gets the underlying hex data
+local function get_hex(b) return b[1] end
+
+_M.get_hex = get_hex
+
+-- return binary data when hex is expected
+local function get_raw_expect_hex(s)
+    if is_raw(s) then return get_raw(s) end
+    if is_hex(s) then s = get_hex(s) end
+    assert(type(s) == "string", "expected hex-encoded string value")
+    return assert(fromhex(s))
+end
+
+-- return binary data when binary data is expected
+local function get_raw_expect_raw(s)
+    if is_raw(s) then return get_raw(s) end
+    if is_hex(s) then return assert(fromhex(get_hex(s))) end
+    assert(type(s) == "string", "expected raw string value")
+    return s
+end
+
+-- returns the calldata encoding of an uint 'value'
+local function encoded_uint(value, size)
+    size = size or 256
+    value = assert(bint.new(value), "value not an integer")
+    assert(bint.eq(value >> size, 0), "integer value does not fit in target type")
+    return tobe(value)
+end
+
+-- appends the calldata parts of an uint 'value' into the 'output' table
+local function append_encoded_uint(output, value, size) tinsert(output, encoded_uint(value, size)) end
+
+-- appends the calldata parts of an int 'value' into the 'output' table
+local function append_encoded_int(output, value, size)
+    size = size or 256
+    value = assert(bint.new(value), "value not an integer")
+    local m1 = bint.one() << (size - 1)
+    if value < 0 then
+        assert(bint.ule(m1, value), "integer value does not fit in target type")
+    else
+        assert(bint.ult(value, m1), "integer value does not fit in target type")
+    end
+    tinsert(output, tobe(value))
+end
+
+-- appends the calldata parts of an address 'value' into the 'output' table
+local function append_encoded_address(output, value)
+    local raw = get_raw_expect_hex(value)
+    if #raw ~= 20 then errorf("invalid address length (expected 20 bytes, got %d bytes)", #raw) end
+    tinsert(output, "\0\0\0\0\0\0\0\0\0\0\0\0")
+    tinsert(output, raw)
+end
+
+-- converts bool to 0 or 1
+local function check_bool(value)
+    if type(value) == "boolean" then
+        if value then
+            return 1
+        else
+            return 0
+        end
+    end
+    errorf("expected boolean (got %s)", type(value))
+end
+
+-- appends the calldata parts of a bool 'value' into the 'output' table
+local function append_encoded_bool(output, value) append_encoded_uint(output, check_bool(value)) end
+
+-- appends 0-padding to the 'output' table
+local function append_padding(output, len)
+    local padded_len = 32 * ((len + 31) // 32)
+    if padded_len > len then tinsert(output, string.rep("\0", padded_len - len)) end
+end
+
+-- appends the calldata parts of a string 'value' into the 'output' table
+local function append_encoded_string(output, value)
+    local raw = get_raw_expect_raw(value)
+    local len = #raw
+    append_encoded_uint(output, len)
+    tinsert(output, raw)
+    append_padding(output, len)
+end
+
+-- appends the calldata parts of a bytes 'value' into the 'output' table
+local function append_encoded_bytes(output, value, size)
+    local raw = get_raw_expect_hex(value)
+    if not size then return append_encoded_string(output, raw) end
+    local len = #raw
+    if len ~= size then errorf("bytes has wrong size (expected %d, got %d)", size, len) end
+    tinsert(output, raw)
+    append_padding(output, len)
+end
+
+-- appends the calldata parts of an array 'value' into the 'output' table, tiven its type name 'tn'
+local function append_encoded_array(output, values, tn)
+    assert(type(values) == "table" and not bint.isbint(values), "array values not in table")
+    local dynamic_size = not tn.size
+    if not dynamic_size and tn.size ~= #values then
+        errorf("invalid value count (expected %u, got %u)", tn.size, #values)
+    end
+    -- For dynamic arrays, encode length first
+    if dynamic_size then append_encoded_uint(output, #values) end
+    -- Static elements: encode directly
+    if not is_dynamic_type(tn.element_type) then
+        for _, value in ipairs(values) do
+            append_encoded_value(output, value, tn.element_type)
+        end
+        return
+    end
+    -- Dynamic elements: encode offsets first, then data
+    local offset = #values * 32 -- Each offset is 32 bytes
+    local value_parts = {}
+    for _, value in ipairs(values) do
+        append_encoded_uint(output, offset)
+        local first_part = #value_parts + 1
+        append_encoded_value(value_parts, value, tn.element_type)
+        for i = first_part, #value_parts do
+            offset = offset + #value_parts[i]
+        end
+    end
+    tappend(output, value_parts)
+end
+
+-- check that all tuple values are available
+local function check_tuple_values(values, parsed_type_spec)
+    local comps = parsed_type_spec.components
+    local names = parsed_type_spec.component_names
+    if not names then
+        names = {}
+        for i, comp_type in ipairs(comps) do
+            local name = comp_type.name
+            if name then
+                if names[name] then errorf("tuple has repeated component name %q", name) end
+                names[name] = i
+            end
+        end
+        parsed_type_spec.component_names = names
+    end
+    local count = #comps
+    for i in pairs(values) do
+        if math.type(i) == "integer" and (i > count or i < 1) then
+            errorf("unexpected tuple component at index %u", i)
+        end
+        if type(i) == "string" and not names[i] then errorf("unexpected tuple component with name %q", i) end
+    end
+    for i, comp_type in ipairs(comps) do
+        if values[i] == nil then
+            local name = comp_type.name
+            if not name then errorf("missing tuple component at index %u", i) end
+            if values[name] == nil then errorf("missing tuple component at index %u (or with name %q)", i, name) end
+        end
+    end
+end
+
+-- returns tuple component (assumes it exists)
+local function tuple_value(values, i, name)
+    local v = values[i]
+    if v ~= nil then return v end
+    return values[name]
+end
+
+-- appends the calldata parts of a tuple 'value' into the 'output' table, given its 'parsed_type_spec'
+local function append_encoded_tuple(output, values, parsed_type_spec)
+    assert(type(values) == "table" and not bint.isbint(values), "tuple values not in table")
+    check_tuple_values(values, parsed_type_spec)
+    local comps = parsed_type_spec.components
+    local offset = 0
+    local dynamic_offset = {} -- index of each dynamic offset in output
+    -- For each static value, add encoded data to output
+    -- For each dynamic value, add add only a placeholder for yet-unknown offset
+    for i, comp_type in ipairs(comps) do
+        local is_dynamic, static_size = is_dynamic_type(comp_type)
+        if is_dynamic then
+            tinsert(output, "") -- placeholder for offset to start of dynamic value
+            tinsert(dynamic_offset, #output)
+            offset = offset + 32
+        else
+            append_encoded_value(output, tuple_value(values, i, comp_type.name), comp_type)
+            offset = offset + static_size
+        end
+    end
+    -- For each dynamic element, replace its offset and append its parts to output
+    local dynamic_index = 1
+    for i, comp_type in ipairs(comps) do
+        if is_dynamic_type(comp_type) then
+            -- replace offset placeholder with correct value
+            output[dynamic_offset[dynamic_index]] = encoded_uint(offset)
+            dynamic_index = dynamic_index + 1
+            local first_part = #output + 1
+            append_encoded_value(output, tuple_value(values, i, comp_type.name), comp_type)
+            for j = first_part, #output do -- advance offset by size of encoded value
+                offset = offset + #output[j]
+            end
+        end
+    end
+end
+
+-- appends the calldata parts of 'value' into the 'output' table, assuming a given its 'parsed_type_spec'
+function append_encoded_value(output, value, parsed_type_spec)
+    local tn = parsed_type_spec.type_name
+    if tn == "uint" then
+        append_encoded_uint(output, value, parsed_type_spec.size)
+    elseif tn == "int" then
+        append_encoded_int(output, value, parsed_type_spec.size)
+    elseif tn == "address" then
+        append_encoded_address(output, value)
+    elseif tn == "bool" then
+        append_encoded_bool(output, value)
+    elseif tn == "string" then
+        append_encoded_string(output, value)
+    elseif tn == "bytes" then
+        append_encoded_bytes(output, value, parsed_type_spec.size)
+    elseif tn == "array" then
+        append_encoded_array(output, value, parsed_type_spec)
+    elseif tn == "tuple" then
+        append_encoded_tuple(output, value, parsed_type_spec)
+    else
+        -- luacov: disable
+        error("unknown type name: " .. tostring(tn))
+        -- luacov: enable
+    end
+end
+
+-- returns the binary encoded calldata for a function signature 'func_sig_str' and the corresponpding 'args' table
+-- bool values are expected as booleans
+-- as in solidity, address and bytes values are expected as hex-encoded strings
+-- if you want to pass raw data in a string instead, wrap the value with calldata.raw()
+-- as in solidity, string values are expected as raw data
+-- if you want to pass them as hex-encoded strings, wrap the value with calldata.hex()
+-- int/uint values are expected in any format bint.new accepts
+-- tuples and arrays are expected as tables with the corresponding values
+function _M.encode_calldata(func_sig_str, args)
+    assert(type(func_sig_str) == "string", "expected function signature string")
+    assert(type(args) == "table", "expected arguments table")
+    local parsed_sig, func_sel = _M.parse_func_sig(func_sig_str)
+    -- Start with selector
+    local output = { func_sel }
+    -- Encode arguments as a tuple
+    append_encoded_tuple(output, args, parsed_sig.params)
+    return table.concat(output)
+end
+
+-- returns the hex-encoded calldata for a 'func_sig' and the corresponpding 'args' table
+function _M.encode_calldata_hex(sig, args) return tohex(_M.encode_calldata(sig, args)) end
+
+_M.encode_hex = tohex
+_M.decode_hex = fromhex
+
+local decode_value -- forward declaration
+
+-- reads a 32-byte word from 'calldata' at 'offset' and returns it as a bint
+local word_padding = string.rep("\0", bint_extra / 8)
+local function read_word(calldata, offset)
+    if offset + 32 > #calldata then errorf("insufficient calldata for 256-bit word at offset %d", offset) end
+    local word = calldata:sub(offset + 1, offset + 32)
+    return bint.frombe(word_padding .. word)
+end
+
+-- reads a uint value from 'calldata' at 'offset'
+local function decode_uint(calldata, offset, size)
+    size = size or 256
+    local value = read_word(calldata, offset)
+    assert(bint.eq(value >> size, 0), "integer value does not fit in target type")
+    return value, offset + 32
+end
+
+-- reads an int value from 'calldata' at 'offset'
+local sign_ext = (-bint.one()) << 256
+local function decode_int(calldata, offset, size)
+    size = size or 256
+    local value = read_word(calldata, offset)
+    -- sign-extend to bin_extra bits
+    if bint.eq(value >> 255, 1) then value = value | sign_ext end
+    local intmax = bint.one() << (size - 1)
+    local intmin = (-bint.one()) << (size - 1)
+    if value < intmin or value >= intmax then error("integer value does not fit in target type") end
+    return value, offset + 32
+end
+
+-- reads an address value from 'calldata' at 'offset'
+local function decode_address(calldata, offset, prefer)
+    local word = read_word(calldata, offset)
+    -- Address is stored in the last 20 bytes of the 32-byte word
+    local addr_data = tobe(word):sub(-20)
+    if prefer ~= "raw" then addr_data = tohex(addr_data) end
+    return addr_data, offset + 32
+end
+
+-- reads a bool value from 'calldata' at 'offset'
+local function decode_bool(calldata, offset)
+    local value = read_word(calldata, offset)
+    if bint.eq(value, bint.zero()) then
+        return false, offset + 32
+    elseif bint.eq(value, bint.one()) then
+        return true, offset + 32
+    else
+        error("invalid bool value in calldata (must be 0 or 1)")
+    end
+end
+
+-- reads a string value from 'calldata' at 'offset'
+local function decode_string(calldata, offset, prefer)
+    local length, new_offset = decode_uint(calldata, offset)
+    local len = bint.tonumber(length)
+    local padded_len = 32 * ((len + 31) // 32)
+    if new_offset + padded_len > #calldata then errorf("insufficient calldata for string of length %d", len) end
+    local str_data = calldata:sub(new_offset + 1, new_offset + len)
+    if prefer == "hex" then str_data = tohex(str_data) end
+    -- Skip padding
+    return str_data, new_offset + padded_len
+end
+
+local function decode_bytes_sized(calldata, offset, size, prefer)
+    -- Fixed-size bytes
+    local padded_len = 32 * ((size + 31) // 32)
+    if offset + padded_len > #calldata then errorf("insufficient calldata for bytes%d", size) end
+    local bytes_data = calldata:sub(offset + 1, offset + size)
+    if prefer ~= "raw" then bytes_data = tohex(bytes_data) end
+    return bytes_data, offset + padded_len
+end
+
+-- reads a bytes value from 'calldata' at 'offset'
+local function decode_bytes(calldata, offset, size, prefer)
+    if not size then
+        -- Dynamic bytes (same as string but return as hex by default)
+        local length, new_offset = decode_uint(calldata, offset)
+        local len = bint.tonumber(length)
+        local padded_len = 32 * ((len + 31) // 32)
+        if new_offset + padded_len > #calldata then errorf("insufficient calldata for bytes of length %d", len) end
+        local bytes_data = calldata:sub(new_offset + 1, new_offset + len)
+        if prefer ~= "raw" then bytes_data = tohex(bytes_data) end
+        return bytes_data, new_offset + padded_len
+    end
+    return decode_bytes_sized(calldata, offset, size, prefer)
+end
+
+-- reads an array value from 'calldata' at 'offset'
+local function decode_array(calldata, offset, parsed_type_spec, prefer)
+    local element_type = parsed_type_spec.element_type
+    local size = parsed_type_spec.size
+    local new_offset = offset
+    local array_data_start = offset -- Start of the array data section
+    if not size then
+        -- Dynamic array - read length first
+        local size_val
+        size_val, new_offset = decode_uint(calldata, new_offset)
+        size = bint.touinteger(size_val)
+        array_data_start = new_offset -- Array data starts after the length field
+    end
+    local result = {}
+    local is_dynamic_element = is_dynamic_type(element_type)
+    if is_dynamic_element then
+        -- Dynamic elements: read offset and decode immediately
+        for i = 1, size do
+            local offset_val = decode_uint(calldata, new_offset + (i - 1) * 32)
+            -- Offsets are relative to the start of the array data section
+            local element_offset = array_data_start + bint.touinteger(offset_val)
+            result[i] = decode_value(calldata, element_offset, element_type, prefer)
+        end
+        -- Set new_offset to after all the offset fields
+        new_offset = new_offset + (size * 32)
+        return result, new_offset
+    else
+        -- Static elements: read sequentially
+        for i = 1, size do
+            result[i], new_offset = decode_value(calldata, new_offset, element_type, prefer)
+        end
+        return result, new_offset
+    end
+end
+
+-- Reads a tuple value from 'calldata' at 'offset'
+local function decode_tuple(calldata, offset, parsed_type_spec, prefer)
+    local components = parsed_type_spec.components
+    local result = {}
+    local static_offset = offset -- Position within the static portion
+    local tuple_start = offset -- Start of the tuple data
+    local _, static_size = is_dynamic_type(parsed_type_spec)
+    local new_offset = tuple_start + static_size -- Position to return (end of data)
+    -- Process components
+    for i, comp_type in ipairs(components) do
+        local is_dynamic_component = is_dynamic_type(comp_type)
+        if is_dynamic_component then
+            local offset_val
+            offset_val, static_offset = decode_uint(calldata, static_offset)
+            -- Offsets are relative to the start of the tuple
+            local dynamic_offset = tuple_start + bint.touinteger(offset_val)
+            result[i], new_offset = decode_value(calldata, dynamic_offset, comp_type, prefer)
+        else
+            result[i], static_offset = decode_value(calldata, static_offset, comp_type, prefer)
+        end
+        local name = comp_type.name
+        if name then result[name] = result[i] end
+    end
+    return result, new_offset
+end
+
+-- Reads a value of the specified type from 'calldata' at 'offset'
+function decode_value(calldata, offset, parsed_type_spec, prefer)
+    local tn = parsed_type_spec.type_name
+    if tn == "uint" then
+        return decode_uint(calldata, offset, parsed_type_spec.size)
+    elseif tn == "int" then
+        return decode_int(calldata, offset, parsed_type_spec.size)
+    elseif tn == "address" then
+        return decode_address(calldata, offset, prefer)
+    elseif tn == "bool" then
+        return decode_bool(calldata, offset)
+    elseif tn == "string" then
+        return decode_string(calldata, offset, prefer)
+    elseif tn == "bytes" then
+        return decode_bytes(calldata, offset, parsed_type_spec.size, prefer)
+    elseif tn == "array" then
+        return decode_array(calldata, offset, parsed_type_spec, prefer)
+    elseif tn == "tuple" then
+        return decode_tuple(calldata, offset, parsed_type_spec, prefer)
+    else
+        -- luacov: disable
+        error("unknown type name: " .. tostring(tn))
+        -- luacov: enable
+    end
+end
+
+-- returns the decoded arguments table for a function signature and calldata
+-- tuples and arrays are returned as tables with the corresponding values
+-- int/uint are returned as bint numbers
+-- bool values are returned as booleans
+-- as in solidity, strings values are returned as raw data
+-- as in solidity, address and bytes values are returned as hex-encoded strings
+-- if you prefer all strings, address, and bytes values returned as hex-encoded strings, set prefer = 'hex'
+-- if you prefer all strings, address, and bytes values returned as raw data, set prefer = 'raw'
+function _M.decode_calldata(func_sig_str, calldata_raw, prefer)
+    assert(type(func_sig_str) == "string", "expected function signature string")
+    assert(type(calldata_raw) == "string", "expected calldata string")
+    if #calldata_raw < 4 then error("calldata too short (missing function selector)") end
+    local calldata_func_sel = calldata_raw:sub(1, 4)
+    local parsed_sig, func_sel = _M.parse_func_sig(func_sig_str)
+    if func_sel ~= calldata_func_sel then
+        errorf("function selector mismatch (expected %s, got %s)", tohex(func_sel), tohex(calldata_func_sel))
+    end
+    assert(#parsed_sig.params.components ~= 0 or #calldata_raw == 4, "calldata too long")
+    return decode_value(calldata_raw, 4, parsed_sig.params, prefer)
+end
+
+-- Returns the decoded arguments table for a function signature and hex-encoded calldata
+function _M.decode_calldata_hex(func_sig_str, calldata_hex, prefer)
+    local calldata_raw = assert(fromhex(calldata_hex))
+    return _M.decode_calldata(func_sig_str, calldata_raw, prefer)
+end
+
+return _M
diff --git a/src/clua-i-machine.cpp b/src/clua-i-machine.cpp
index 982187aca..3cf9ee43c 100644
--- a/src/clua-i-machine.cpp
+++ b/src/clua-i-machine.cpp
@@ -399,6 +399,9 @@ static void clua_push_json_value(lua_State *L, const nlohmann::json &j, int ctxi
                 lua_pushlstring(L, binary_data.data(), binary_data.length());
                 lua_replace(L, -3); // move into the placeholder slot
                 lua_pop(L, 1);      // pop binary_data reference
+            } else if (schema.is_object() && schema.contains(data)) {
+                static const nlohmann::json empty_schema;
+                clua_push_json_value(L, schema.at(data), ctxidx, empty_schema, schema_dict);
             } else {
                 lua_pushlstring(L, data.data(), data.length());
             }
@@ -451,15 +454,26 @@ void clua_push_json_table(lua_State *L, const char *s, int ctxidx, const nlohman
 static const nlohmann::json &clua_get_machine_schema_dict(lua_State *L) try {
     // In order to convert Lua tables <-> JSON objects we have to define a schema
     // to transform some special fields, we only care about:
-    // - Binary strings (translate Base64 strings in JSON to binary strings in Lua)
+    // - Binary strings (translate Base64 strings in JSON to binary strings in Lua
+    //   or convert to integers of an enumeration)
     // - Array indexes (translate 0 based index in JSON to 1 based index in Lua)
     static const nlohmann::json machine_schema_dict = {
         {"Base64", "Base64"},
+        {"InterpreterBreakReason",
+            {{"failed", CM_BREAK_REASON_FAILED}, {"halted", CM_BREAK_REASON_HALTED},
+                {"yielded_manually", CM_BREAK_REASON_YIELDED_MANUALLY},
+                {"yielded_automatically", CM_BREAK_REASON_YIELDED_AUTOMATICALLY},
+                {"yielded_softly", CM_BREAK_REASON_YIELDED_SOFTLY},
+                {"reached_target_mcycle", CM_BREAK_REASON_REACHED_TARGET_MCYCLE}}},
         {"ArrayIndex", "ArrayIndex"},
         {"Base64Array",
             {
                 {"items", "Base64"},
             }},
+        {"ArrayArrayIndex",
+            {
+                {"items", "ArrayIndex"},
+            }},
         {"Proof",
             {
                 {"target_hash", "Base64"},
@@ -491,6 +505,16 @@ static const nlohmann::json &clua_get_machine_schema_dict(lua_State *L) try {
                 {"accesses", "AccessArray"},
                 {"brackets", "BracketArray"},
             }},
+        {"McycleRootHashes",
+            {
+                {"hashes", "Base64Array"},
+                {"break_reason", "InterpreterBreakReason"},
+            }},
+        {"UarchCycleRootHashes",
+            {
+                {"hashes", "Base64Array"},
+                {"reset_indices", "ArrayArrayIndex"},
+            }},
     };
     return machine_schema_dict;
 } catch (const std::exception &e) {
@@ -937,6 +961,36 @@ static int machine_obj_index_create(lua_State *L) {
     return 1;
 }
 
+/// \brief This is the machine:collect_mcycle_root_hashes() method implementation.
+/// \param L Lua state.
+static int machine_obj_index_collect_mcycle_root_hashes(lua_State *L) {
+    lua_settop(L, 4);
+    auto &m = clua_check<clua_managed_cm_ptr<cm_machine>>(L, 1);
+    const uint64_t mcycle_phase = luaL_checkinteger(L, 2);
+    const uint64_t mcycle_period = luaL_checkinteger(L, 3);
+    const uint64_t period_count = luaL_checkinteger(L, 4);
+    const char *result = nullptr;
+    if (cm_collect_mcycle_root_hashes(m.get(), mcycle_phase, mcycle_period, period_count, &result) != 0) {
+        return luaL_error(L, "%s", cm_get_last_error_message());
+    }
+    clua_push_schemed_json_table(L, result, "McycleRootHashes");
+    return 1;
+}
+
+/// \brief This is the machine:collect_uarch_cycle_root_hashes() method implementation.
+/// \param L Lua state.
+static int machine_obj_index_collect_uarch_cycle_root_hashes(lua_State *L) {
+    lua_settop(L, 2);
+    auto &m = clua_check<clua_managed_cm_ptr<cm_machine>>(L, 1);
+    const uint64_t mcycle_count = luaL_checkinteger(L, 2);
+    const char *result = nullptr;
+    if (cm_collect_uarch_cycle_root_hashes(m.get(), mcycle_count, &result) != 0) {
+        return luaL_error(L, "%s", cm_get_last_error_message());
+    }
+    clua_push_schemed_json_table(L, result, "UarchCycleRootHashes");
+    return 1;
+}
+
 /// \brief This is the machine:load() method implementation.
 /// \param L Lua state.
 static int machine_obj_index_load(lua_State *L) {
@@ -1057,6 +1111,8 @@ static int machine_obj_index_swap(lua_State *L) {
 /// \brief Contents of the machine object metatable __index table.
 static const auto machine_obj_index = cartesi::clua_make_luaL_Reg_array({
     {"create", machine_obj_index_create},
+    {"collect_mcycle_root_hashes", machine_obj_index_collect_mcycle_root_hashes},
+    {"collect_uarch_cycle_root_hashes", machine_obj_index_collect_uarch_cycle_root_hashes},
     {"destroy", machine_obj_index_destroy},
     {"get_default_config", machine_obj_index_get_default_config},
     {"get_initial_config", machine_obj_index_get_initial_config},
diff --git a/src/collect-mcycle-hashes-state-access.h b/src/collect-mcycle-hashes-state-access.h
new file mode 100644
index 000000000..c0c9a6223
--- /dev/null
+++ b/src/collect-mcycle-hashes-state-access.h
@@ -0,0 +1,171 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef COLLECT_MCYCLE_HASHES_STATE_ACCESS_H
+#define COLLECT_MCYCLE_HASHES_STATE_ACCESS_H
+
+#include <cassert>
+#include <stdexcept>
+#include <unordered_set>
+
+#include "hash-tree.h"
+#include "i-accept-scoped-notes.h"
+#include "i-prefer-shadow-state.h"
+#include "i-state-access.h"
+#include "machine.h"
+#include "pmas.h"
+#include "shadow-tlb.h"
+#include "strict-aliasing.h"
+
+namespace cartesi {
+
+class collect_mcycle_hashes_state_access;
+
+// Type trait that should return the fast_addr type for a state access class
+template <>
+struct i_state_access_fast_addr<collect_mcycle_hashes_state_access> {
+    using type = host_addr;
+};
+
+/// \class collect_mcycle_hashes_state_access
+/// \brief Records machine state access into a step log file
+class collect_mcycle_hashes_state_access :
+    public i_state_access<collect_mcycle_hashes_state_access>,
+    public i_prefer_shadow_state<collect_mcycle_hashes_state_access>,
+    public i_accept_scoped_notes<collect_mcycle_hashes_state_access> {
+
+public:
+    struct context {
+        hash_tree::dirty_words_type dirty_words;
+    };
+
+private:
+    // NOLINTBEGIN(cppcoreguidelines-avoid-const-or-ref-data-members)
+    context &m_c; ///< context for dirty words
+    machine &m_m; ///< reference to machine
+    // NOLINTEND(cppcoreguidelines-avoid-const-or-ref-data-members)
+
+public:
+    /// \brief Constructor of record step state access
+    /// \param context Context for the recording with the log filename
+    /// \param m reference to machine
+    /// \details The log file is saved when finish() is called
+    collect_mcycle_hashes_state_access(context &c, machine &m) : m_c(c), m_m(m) {}
+
+private:
+    using fast_addr_type = host_addr;
+
+    void mark_dirty_word(uint64_t address) const {
+        constexpr uint64_t word_mask = ~UINT64_C(HASH_TREE_WORD_SIZE - 1);
+        m_c.dirty_words.insert(address & word_mask);
+    }
+
+    // -----
+    // i_prefer_shadow_state interface implementation
+    // -----
+    friend i_prefer_shadow_state<collect_mcycle_hashes_state_access>;
+
+    uint64_t do_read_shadow_register(shadow_registers_what what) const {
+        return m_m.read_reg(machine_reg_enum(what));
+    }
+
+    void do_write_shadow_register(shadow_registers_what what, uint64_t val) const {
+        auto reg = machine_reg_enum(what);
+        mark_dirty_word(machine_reg_address(reg));
+        m_m.write_reg(reg, val);
+    }
+
+    // -----
+    // i_state_access interface implementation
+    // -----
+    friend i_state_access<collect_mcycle_hashes_state_access>;
+
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    bool do_read_memory(uint64_t paddr, const unsigned char *data, uint64_t length) const {
+        (void) paddr;
+        (void) data;
+        (void) length;
+        throw std::runtime_error("unexpected call to collect_mcycle_hashes_state_access::read_memory");
+    }
+
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    bool do_write_memory(uint64_t paddr, const unsigned char *data, uint64_t length) const {
+        (void) paddr;
+        (void) data;
+        (void) length;
+        throw std::runtime_error("unexpected call to collect_mcycle_hashes_state_access::write_memory");
+    }
+
+    address_range &do_read_pma(uint64_t index) const {
+        assert(index < PMA_MAX);
+        return m_m.read_pma(index);
+    }
+
+    template <typename T, typename A>
+    void do_read_memory_word(host_addr haddr, uint64_t pma_index, T *pval) const {
+        (void) pma_index;
+        *pval = aliased_aligned_read<T, A>(haddr);
+    }
+
+    template <typename T, typename A>
+    void do_write_memory_word(host_addr haddr, uint64_t pma_index, T val) const {
+        mark_dirty_word(m_m.get_paddr(haddr, pma_index));
+        aliased_aligned_write<T, A>(haddr, val);
+    }
+
+    template <TLB_set_index SET>
+    uint64_t do_read_tlb_vaddr_page(uint64_t slot_index) const {
+        return m_m.get_state().penumbra.tlb[SET][slot_index].vaddr_page;
+    }
+
+    template <TLB_set_index SET>
+    uint64_t do_read_tlb_pma_index(uint64_t slot_index) const {
+        return m_m.get_state().shadow.tlb[SET][slot_index].pma_index;
+    }
+
+    //??D This is still a bit too complicated for my taste
+    template <TLB_set_index SET>
+    host_addr do_read_tlb_vf_offset(uint64_t slot_index) const {
+        return m_m.get_state().penumbra.tlb[SET][slot_index].vh_offset;
+    }
+
+    //??D This is still a bit too complicated for my taste
+    template <TLB_set_index SET>
+    void do_write_tlb(uint64_t slot_index, uint64_t vaddr_page, host_addr vh_offset, uint64_t pma_index) const {
+        mark_dirty_word(shadow_tlb_get_abs_addr(SET, slot_index, shadow_tlb_what::vaddr_page));
+        mark_dirty_word(shadow_tlb_get_abs_addr(SET, slot_index, shadow_tlb_what::vp_offset));
+        mark_dirty_word(shadow_tlb_get_abs_addr(SET, slot_index, shadow_tlb_what::pma_index));
+        m_m.write_tlb(SET, slot_index, vaddr_page, vh_offset, pma_index);
+    }
+
+    fast_addr do_get_faddr(uint64_t paddr, uint64_t pma_index) const {
+        return m_m.get_host_addr(paddr, pma_index);
+    }
+
+    void do_mark_dirty_page(host_addr /* haddr */, uint64_t /* pma_index */) const {}
+
+    void do_putchar(uint8_t c) const { // NOLINT(readability-convert-member-functions-to-static)
+        os_putchar(c);
+    }
+
+    constexpr const char *do_get_name() const { // NOLINT(readability-convert-member-functions-to-static)
+        return "collect_mcycle_hashes_state_access";
+    }
+};
+
+} // namespace cartesi
+
+#endif
diff --git a/src/collect-uarch-cycle-hashes-state-access.h b/src/collect-uarch-cycle-hashes-state-access.h
new file mode 100644
index 000000000..097dfbb8f
--- /dev/null
+++ b/src/collect-uarch-cycle-hashes-state-access.h
@@ -0,0 +1,127 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef COLLECT_UARCH_CYCLE_HASHES_STATE_ACCESS_H
+#define COLLECT_UARCH_CYCLE_HASHES_STATE_ACCESS_H
+
+/// \file
+/// \brief State access implementation that record and logs all accesses
+#include <cstdint>
+#include <stdexcept>
+#include <unordered_set>
+
+#include "hash-tree.h"
+#include "i-accept-scoped-notes.h"
+#include "i-prefer-shadow-uarch-state.h"
+#include "i-uarch-state-access.h"
+#include "machine.h"
+#include "shadow-tlb.h"
+#include "shadow-uarch-state.h"
+#include "strict-aliasing.h"
+
+namespace cartesi {
+
+/// \details The collect_uarch_cycle_hashes_state_access logs all access to the machine state.
+class collect_uarch_cycle_hashes_state_access :
+    public i_uarch_state_access<collect_uarch_cycle_hashes_state_access>,
+    public i_prefer_shadow_uarch_state<collect_uarch_cycle_hashes_state_access>,
+    public i_accept_scoped_notes<collect_uarch_cycle_hashes_state_access> {
+
+public:
+    struct context {
+        hash_tree::dirty_words_type dirty_words;
+    };
+
+private:
+    // NOLINTBEGIN(cppcoreguidelines-avoid-const-or-ref-data-members)
+    context &m_c; ///< context for dirty words
+    machine &m_m; ///< reference to machine
+    // NOLINTEND(cppcoreguidelines-avoid-const-or-ref-data-members)
+
+public:
+    /// \brief Constructor from machine and uarch states.
+    /// \param m Reference to machine state.
+    /// \param log Reference to log.
+    collect_uarch_cycle_hashes_state_access(context &c, machine &m) : m_c(c), m_m(m) {}
+
+private:
+    void mark_dirty_word(uint64_t address) const {
+        constexpr uint64_t word_mask = ~UINT64_C(HASH_TREE_WORD_SIZE - 1);
+        m_c.dirty_words.insert(address & word_mask);
+    }
+
+    // -----
+    // i_prefer_shadow_uarch_state interface implementation
+    // -----
+    friend i_prefer_shadow_uarch_state<collect_uarch_cycle_hashes_state_access>;
+
+    uint64_t do_read_shadow_uarch_state(shadow_uarch_state_what what) const {
+        return m_m.read_reg(machine_reg_enum(what));
+    }
+
+    void do_write_shadow_uarch_state(shadow_uarch_state_what what, uint64_t val) const {
+        auto reg = machine_reg_enum(what);
+        mark_dirty_word(machine_reg_address(reg));
+        m_m.write_reg(reg, val);
+    }
+
+    // -----
+    // i_uarch_state_access interface implementation
+    // -----
+    friend i_uarch_state_access<collect_uarch_cycle_hashes_state_access>;
+
+    uint64_t do_read_word(uint64_t paddr) const {
+        return m_m.read_word(paddr);
+    }
+
+    void do_write_word(uint64_t paddr, uint64_t val) const {
+        m_m.write_word(paddr, val);
+        mark_dirty_word(paddr);
+    }
+
+    void do_write_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset,
+        uint64_t pma_index) const {
+        mark_dirty_word(shadow_tlb_get_abs_addr(set_index, slot_index, shadow_tlb_what::vaddr_page));
+        mark_dirty_word(shadow_tlb_get_abs_addr(set_index, slot_index, shadow_tlb_what::vp_offset));
+        mark_dirty_word(shadow_tlb_get_abs_addr(set_index, slot_index, shadow_tlb_what::pma_index));
+        m_m.write_shadow_tlb(set_index, slot_index, vaddr_page, vp_offset, pma_index);
+    }
+
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    void do_reset_uarch() const {
+        throw std::runtime_error("unexpected call to collect_uarch_cycle_hashes_state_access::reset_uarch");
+    }
+
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    void do_putchar(uint8_t c) const {
+        os_putchar(c);
+    }
+
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    void do_mark_dirty_page(uint64_t paddr, uint64_t pma_index) const {
+        (void) paddr;
+        (void) pma_index;
+    }
+
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
+    constexpr const char *do_get_name() const {
+        return "collect_uarch_cycle_hashes_state_access";
+    }
+};
+
+} // namespace cartesi
+
+#endif
diff --git a/src/hash-tree.cpp b/src/hash-tree.cpp
index cd75eaae8..4d368d86f 100644
--- a/src/hash-tree.cpp
+++ b/src/hash-tree.cpp
@@ -27,6 +27,7 @@
 #include <omp.h>
 
 #include "machine-address-ranges.h"
+#include "scope-exit.h"
 #include "signposts.h"
 
 namespace cartesi {
@@ -183,8 +184,8 @@ bool hash_tree::update_dirty_page(hasher_type &h, address_range &ar, page_hash_t
         return false;
     }
     const auto offset = paddr_page - ar.get_start();
-    const auto page_view = std::span<const unsigned char, HASH_TREE_PAGE_SIZE>{base + offset, HASH_TREE_PAGE_SIZE};
-    auto ret = m_page_cache.update_entry(h, page_view, entry);
+    const auto page = std::span<const unsigned char, HASH_TREE_PAGE_SIZE>{base + offset, HASH_TREE_PAGE_SIZE};
+    auto ret = m_page_cache.update_entry(h, page, entry);
     auto node_hash_view = ar.get_dense_hash_tree().node_hash_view(offset, HASH_TREE_LOG2_PAGE_SIZE);
     changed = !std::ranges::equal(entry.root_hash_view(), node_hash_view);
     if (changed) {
@@ -497,6 +498,7 @@ bool hash_tree::verify(address_ranges ars) const {
         const auto &dpt = ar.get_dirty_page_tree();
         auto ar_actually_dirty = false;
         for (uint64_t offset = 0; offset < ar.get_length(); offset += HASH_TREE_PAGE_SIZE) {
+            auto paddr_page = ar.get_start() + offset;
             auto page = mem.subspan(offset, HASH_TREE_PAGE_SIZE);
             auto page_hash = get_merkle_tree_hash(h, page, HASH_TREE_WORD_SIZE);
             auto actually_dirty = !std::ranges::equal(page_hash, dht.node_hash_view(offset, HASH_TREE_LOG2_PAGE_SIZE));
@@ -504,25 +506,43 @@ bool hash_tree::verify(address_ranges ars) const {
             auto marked_dirty = dpt.is_node_dirty(offset, HASH_TREE_LOG2_PAGE_SIZE);
             if (actually_dirty != marked_dirty) {
                 if (!marked_dirty) {
-                    std::cerr << "page 0x" << std::hex << std::uppercase << offset << " of " << ar.get_description()
-                              << " is " << (marked_dirty ? "" : "not ") << "marked dirty but is "
-                              << (actually_dirty ? "" : "not ") << "dirty";
                     ret = false;
-                    std::cerr << "! FAILED!";
+                    std::cerr << "page 0x" << std::hex << std::uppercase << paddr_page << " (in "
+                              << ar.get_description() << ") is " << (marked_dirty ? "" : "not ")
+                              << "marked dirty but is " << (actually_dirty ? "" : "not ") << "dirty\n";
+                    // check page in cache it is there
+                    auto opt_br = m_page_cache.borrow_entry_if_hit(paddr_page);
+                    if (opt_br) {
+                        auto &cache_entry = opt_br->get();
+
+                        if (!std::ranges::equal(page_hash, cache_entry.root_hash_view())) {
+                            std::cerr << "    cached page root hash mismatch\n";
+                        }
+                        const page_hash_tree_cache::page_view entry_page{cache_entry.get_page()};
+                        for (auto word_offset = 0UL; word_offset < HASH_TREE_PAGE_SIZE;
+                            word_offset += HASH_TREE_WORD_SIZE) {
+                            const auto page_word = page.subspan(word_offset, HASH_TREE_WORD_SIZE);
+                            const auto entry_word = entry_page.subspan(word_offset, HASH_TREE_WORD_SIZE);
+                            if (!std::ranges::equal(page_word, entry_word)) {
+                                std::cerr << "    word 0x" << std::hex << std::uppercase << (paddr_page + word_offset)
+                                          << " differs\n";
+                            }
+                        }
+                        m_page_cache.return_entry(cache_entry);
+                    }
+                    std::cerr << "! FAILED!\n";
                 }
-                std::cerr << "\n";
             }
         }
         const int ar_log2_size = HASH_TREE_LOG2_PAGE_SIZE + ar.get_level_count() - 1;
         auto ar_marked_dirty = dpt.is_node_dirty(0, ar_log2_size);
         if (ar_actually_dirty != ar_marked_dirty) {
             if (!ar_marked_dirty) {
+                ret = false;
                 std::cerr << ar.get_description() << " is " << (ar_marked_dirty ? "" : "not ") << "marked dirty but is "
                           << (ar_actually_dirty ? "" : "not ") << "dirty";
-                ret = false;
-                std::cerr << "! FAILED!";
+                std::cerr << "! FAILED!\n";
             }
-            std::cerr << "\n";
         }
         const auto &ar_node = m_sparse_nodes[ar_node_index];
         if (!std::ranges::equal(ar_node.hash, dht.node_hash_view(0, ar_log2_size))) {
@@ -549,6 +569,145 @@ bool hash_tree::update(address_ranges ars) {
     return update_succeeded;
 }
 
+bool hash_tree::update_words(address_ranges ars, dirty_words_type dirty_words) {
+    constexpr auto page_mask = ~UINT64_C(HASH_TREE_PAGE_SIZE - 1);
+    auto old_concurrency = omp_get_num_threads();
+    omp_set_num_threads(m_concurrency);
+    const scope_exit num_threads{[old_concurrency]() { omp_set_num_threads(old_concurrency); }};
+    // Dirty_words contains an unordered set of the address of all words that became dirty since last update
+    // We copy these to a sorted vector "words"
+    // Every word in the same page must be updated by the same thread
+    // So we compute a vector "page_starts" with the indices into "words" of the first word in each page
+    // It is over this "page_starts" vector that we iterate over using threads
+    if (dirty_words.empty()) {
+        return true;
+    }
+    std::vector<uint64_t> words;
+    words.reserve(dirty_words.size());
+    std::ranges::copy(dirty_words, std::back_inserter(words));
+    std::ranges::sort(words);
+    std::vector<uint64_t> page_starts;
+    uint64_t last_paddr_page = -1;
+    //??D change to std::views::enumerate on C++23
+    for (uint64_t start = 0; auto word : words) {
+        auto paddr_page = word & page_mask;
+        if (paddr_page != last_paddr_page) {
+            page_starts.push_back(start);
+            last_paddr_page = paddr_page;
+        }
+        ++start;
+    }
+    page_starts.push_back(words.size()); // last entry
+    //??D I'll assume here that we do not have more threads than the cache size,
+    // so we don't need to process in batches, and will fail if this assumption if false
+    std::atomic<int> update_failed{0}; // NOLINT(misc-const-correctness)
+    int ar_index = 0;
+    int max_level_count = 0;
+    hasher_type h;
+    std::vector<uint64_t> curr_page_node;
+    std::vector<uint64_t> next_page_node;
+    dense_node_entries curr_dense_node;
+    dense_node_entries next_dense_node;
+    changed_address_ranges changed_ars;
+    for (unsigned i = 0; i < page_starts.size() - 1; ++i) {
+        auto begin = page_starts[i];
+        auto end = page_starts[i + 1];
+        auto paddr_page = words[begin] & page_mask;
+        bool hit = false;
+        auto opt_br = m_page_cache.borrow_entry(paddr_page, hit);
+        if (!opt_br) {
+            update_failed.store(1, std::memory_order_relaxed);
+            continue;
+        }
+        auto &cache_entry = opt_br->get();
+        while (!ars[ar_index].contains_absolute(paddr_page, HASH_TREE_PAGE_SIZE)) {
+            if (ar_index >= static_cast<int>(ars.size())) {
+                update_failed.store(1, std::memory_order_relaxed);
+                m_page_cache.return_entry(cache_entry);
+                continue;
+            }
+            ++ar_index;
+        }
+        auto &ar = ars[ar_index];
+        if (changed_ars.empty() || changed_ars.back() != ar_index) {
+            changed_ars.push_back(ar_index);
+        }
+        max_level_count = std::max(max_level_count, ar.get_level_count());
+        const auto *base = ar.get_host_memory();
+        if (!ar.is_memory() || base == nullptr) {
+            update_failed.store(1, std::memory_order_relaxed);
+            m_page_cache.return_entry(cache_entry);
+            continue;
+        }
+        const auto page_offset = paddr_page - ar.get_start();
+        // if we had a cache hit, update only the words that changed in the cache
+        if (hit) {
+            auto page = std::span<const unsigned char, HASH_TREE_PAGE_SIZE>{base + page_offset, HASH_TREE_PAGE_SIZE};
+            auto &page_tree = cache_entry.get_page_hash_tree();
+            const page_hash_tree_cache::page_view entry_page{cache_entry.get_page()};
+            curr_page_node.clear();
+            for (auto word_address : std::span(words).subspan(begin, end - begin)) {
+                const auto word_offset = word_address - paddr_page;
+                const auto page_word = page.subspan(word_offset, HASH_TREE_WORD_SIZE);
+                const auto entry_word = entry_page.subspan(word_offset, HASH_TREE_WORD_SIZE);
+                auto index = (HASH_TREE_PAGE_SIZE + word_offset) / HASH_TREE_WORD_SIZE;
+                get_hash(h, page_word, page_tree[index]);
+                std::ranges::copy(page_word, entry_word.begin());
+                auto parent = index / 2;
+                if (curr_page_node.empty() || curr_page_node.back() != parent) {
+                    curr_page_node.push_back(parent);
+                }
+            }
+            for (int log2_size = HASH_TREE_LOG2_WORD_SIZE + 1; log2_size <= HASH_TREE_LOG2_PAGE_SIZE; ++log2_size) {
+                next_page_node.clear();
+                for (auto index : curr_page_node) {
+                    auto left = index * 2;
+                    auto right = (index * 2) + 1;
+                    get_concat_hash(h, page_tree[left], page_tree[right], page_tree[index]);
+                    auto parent = index / 2;
+                    if (next_page_node.empty() || next_page_node.back() != parent) { // We know parent != 0
+                        next_page_node.push_back(parent);
+                    }
+                }
+                std::swap(curr_page_node, next_page_node);
+            }
+            // otherwise, the update from scratch
+        } else {
+            bool changed = false;
+            if (!update_dirty_page(h, ar, cache_entry, changed)) {
+                update_failed.store(1, std::memory_order_relaxed);
+                m_page_cache.return_entry(cache_entry);
+            }
+        }
+        auto &dht = ar.get_dense_hash_tree();
+        auto node_hash_view = dht.node_hash_view(page_offset, HASH_TREE_LOG2_PAGE_SIZE);
+        std::ranges::copy(cache_entry.root_hash_view(), node_hash_view.begin());
+        m_page_cache.return_entry(cache_entry);
+        auto dense_node =
+            dense_node_entry{.dht = dht, .offset = get_aligned_address(page_offset, HASH_TREE_LOG2_PAGE_SIZE + 1)};
+        if (curr_dense_node.empty() || curr_dense_node.back() != dense_node) {
+            curr_dense_node.push_back(dense_node);
+        }
+    }
+    for (int level = 1; level < max_level_count; ++level) {
+        auto log2_size = HASH_TREE_LOG2_PAGE_SIZE + level;
+        next_dense_node.clear();
+        for (auto &[dht, offset] : curr_dense_node) {
+            auto child_size = UINT64_C(1) << (log2_size - 1);
+            auto parent = dht.node_hash_view(offset, log2_size);
+            auto left = dht.node_hash_view(offset, log2_size - 1);
+            auto right = dht.node_hash_view(offset + child_size, log2_size - 1);
+            get_concat_hash(h, left, right, parent);
+            auto dense_node = dense_node_entry{.dht = dht, .offset = get_aligned_address(offset, log2_size + 1)};
+            if (next_dense_node.empty() || next_dense_node.back() != dense_node) {
+                next_dense_node.push_back(dense_node);
+            }
+        }
+        std::swap(curr_dense_node, next_dense_node);
+    }
+    return !static_cast<bool>(update_failed.load(std::memory_order_relaxed)) && update_sparse_tree(ars, changed_ars);
+}
+
 bool hash_tree::update_page(address_ranges ars, uint64_t paddr_page) {
     paddr_page >>= HASH_TREE_LOG2_PAGE_SIZE;
     paddr_page <<= HASH_TREE_LOG2_PAGE_SIZE;
diff --git a/src/hash-tree.h b/src/hash-tree.h
index 6c02a4cda..192074daa 100644
--- a/src/hash-tree.h
+++ b/src/hash-tree.h
@@ -18,6 +18,7 @@
 #define HASH_TREE_H
 
 #include <iosfwd>
+#include <unordered_set>
 #include <vector>
 
 #include "address-range.h"
@@ -44,7 +45,14 @@ class hash_tree {
     };
 
     using dirty_pages = std::vector<dirty_page>;
-    using dense_node_entry = std::pair<i_dense_hash_tree &, uint64_t>;
+    struct dense_node_entry {
+        // NOLINTNEXTLINE(cppcoreguidelines-avoid-const-or-ref-data-members)
+        i_dense_hash_tree &dht;
+        uint64_t offset;
+        bool operator==(const dense_node_entry &other) const {
+            return &dht == &other.dht && offset == other.offset;
+        }
+    };
     using dense_node_entries = std::vector<dense_node_entry>;
     using pristine_hashes = std::array<machine_hash, HASH_TREE_LOG2_ROOT_SIZE + 1>;
 
@@ -109,6 +117,7 @@ class hash_tree {
     using hasher_type = keccak_256_hasher;
     using proof_type = hash_tree_proof;
 
+    using dirty_words_type = std::unordered_set<uint64_t>;
     using nodes_type = std::vector<node_type>;
     using sibling_hashes_type = std::vector<machine_hash>;
 
@@ -123,6 +132,8 @@ class hash_tree {
 
     bool update(address_ranges ars);
 
+    bool update_words(address_ranges ars, dirty_words_type dirty_words);
+
     bool update_page(address_ranges ars, uint64_t paddr_page);
 
     bool verify(address_ranges ars) const;
diff --git a/src/i-machine.h b/src/i-machine.h
index 7478ca074..5303ae239 100644
--- a/src/i-machine.h
+++ b/src/i-machine.h
@@ -28,6 +28,8 @@
 #include "machine-config.h"
 #include "machine-hash.h"
 #include "machine-reg.h"
+#include "mcycle-root-hashes.h"
+#include "uarch-cycle-root-hashes.h"
 #include "uarch-interpret.h"
 
 namespace cartesi {
@@ -84,6 +86,13 @@ class i_machine {
         return do_run(mcycle_end);
     }
 
+    /// \brief Collects the root hashes after every \p mcycle_period machine cycles, for \p period_count periods.
+    /// Returns when done, or if the machine halts or yields.
+    void collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_period, uint64_t period_count,
+        mcycle_root_hashes &result) {
+        do_collect_mcycle_root_hashes(mcycle_phase, mcycle_period, period_count, result);
+    }
+
     /// \brief Serialize entire state to directory
     void store(const std::string &dir) const {
         do_store(dir);
@@ -207,6 +216,12 @@ class i_machine {
         return do_run_uarch(uarch_cycle_end);
     }
 
+    /// \brief Collects the root hashes after every \p uarch_cycle, for \p mcycle_count machine cycles, implicitly
+    /// resetting the uarch between mcycles.
+    void collect_uarch_cycle_root_hashes(uint64_t mcycle_count, uarch_cycle_root_hashes &result) {
+        do_collect_uarch_cycle_root_hashes(mcycle_count, result);
+    }
+
     /// \brief Returns a list of descriptions for all PMA entries registered in the machine, sorted by start
     virtual address_range_descriptions get_address_ranges() const {
         return do_get_address_ranges();
@@ -268,6 +283,8 @@ class i_machine {
     virtual void do_create(const machine_config &config, const machine_runtime_config &runtime) = 0;
     virtual void do_load(const std::string &directory, const machine_runtime_config &runtime) = 0;
     virtual interpreter_break_reason do_run(uint64_t mcycle_end) = 0;
+    virtual void do_collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_period, uint64_t period_count,
+        mcycle_root_hashes &result) = 0;
     virtual void do_store(const std::string &dir) const = 0;
     virtual interpreter_break_reason do_log_step(uint64_t mcycle_count, const std::string &filename) = 0;
     virtual access_log do_log_step_uarch(const access_log::type &log_type) = 0;
@@ -291,6 +308,7 @@ class i_machine {
     virtual void do_reset_uarch() = 0;
     virtual access_log do_log_reset_uarch(const access_log::type &log_type) = 0;
     virtual uarch_interpreter_break_reason do_run_uarch(uint64_t uarch_cycle_end) = 0;
+    virtual void do_collect_uarch_cycle_root_hashes(uint64_t mcycle_count, uarch_cycle_root_hashes &result) = 0;
     virtual address_range_descriptions do_get_address_ranges() const = 0;
     virtual void do_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length) = 0;
     virtual access_log do_log_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
diff --git a/src/interpret.cpp b/src/interpret.cpp
index d3ebc3c44..0f3837e70 100644
--- a/src/interpret.cpp
+++ b/src/interpret.cpp
@@ -93,6 +93,7 @@
 #ifdef MICROARCHITECTURE
 #include "machine-uarch-bridge-state-access.h"
 #else
+#include "collect-mcycle-hashes-state-access.h"
 #include "record-step-state-access.h"
 #include "replay-step-state-access.h"
 #include "state-access.h"
@@ -6128,6 +6129,8 @@ template interpreter_break_reason interpret(state_access a, uint64_t mcycle_end)
 template interpreter_break_reason interpret(record_step_state_access a, uint64_t mcycle_end);
 // Explicit instantiation for replay_step_state_access
 template interpreter_break_reason interpret(replay_step_state_access a, uint64_t mcycle_end);
+// Explicit instantiation for collect_mcycle_hashes_state_access
+template interpreter_break_reason interpret(collect_mcycle_hashes_state_access a, uint64_t mcycle_end);
 #endif // MICROARCHITECTURE
 
 } // namespace cartesi
diff --git a/src/json-util.cpp b/src/json-util.cpp
index f1607b496..7bae4e758 100644
--- a/src/json-util.cpp
+++ b/src/json-util.cpp
@@ -529,6 +529,36 @@ static auto reg_to_name(machine_reg r) {
     return "";
 }
 
+static std::string uarch_interpreter_break_reason_to_name(uarch_interpreter_break_reason reason) {
+    using R = uarch_interpreter_break_reason;
+    switch (reason) {
+        case R::uarch_halted:
+            return "uarch_halted";
+        case R::reached_target_cycle:
+            return "reached_target_cycle";
+    }
+    throw std::domain_error{"invalid uarch interpreter break reason"};
+}
+
+static std::string interpreter_break_reason_to_name(interpreter_break_reason reason) {
+    using R = interpreter_break_reason;
+    switch (reason) {
+        case R::failed:
+            return "failed";
+        case R::halted:
+            return "halted";
+        case R::yielded_manually:
+            return "yielded_manually";
+        case R::yielded_automatically:
+            return "yielded_automatically";
+        case R::yielded_softly:
+            return "yielded_softly";
+        case R::reached_target_mcycle:
+            return "reached_target_mcycle";
+    }
+    throw std::domain_error{"invalid interpreter break reason"};
+}
+
 static interpreter_break_reason interpreter_break_reason_from_name(const std::string &name) {
     using ibr = interpreter_break_reason;
     const static std::unordered_map<std::string, ibr> g_ibr_name = {{"failed", ibr::failed}, {"halted", ibr::halted},
@@ -552,7 +582,7 @@ static uarch_interpreter_break_reason uarch_interpreter_break_reason_from_name(c
     throw std::domain_error{"invalid uarch interpreter break reason"};
 }
 
-static std::string access_type_name(access_type at) {
+static std::string access_type_to_name(access_type at) {
     switch (at) {
         case access_type::read:
             return "read";
@@ -562,7 +592,7 @@ static std::string access_type_name(access_type at) {
     throw std::domain_error{"invalid access type"};
 }
 
-static std::string bracket_type_name(bracket_type bt) {
+static std::string bracket_type_to_name(bracket_type bt) {
     switch (bt) {
         case bracket_type::begin:
             return "begin";
@@ -572,6 +602,16 @@ static std::string bracket_type_name(bracket_type bt) {
     throw std::domain_error{"invalid bracket type"};
 }
 
+static bracket_type bracket_type_from_name(const std::string &name) {
+    if (name == "begin") {
+        return bracket_type::begin;
+    }
+    if (name == "end") {
+        return bracket_type::end;
+    }
+    throw std::domain_error{"invalid bracket type"};
+}
+
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, std::string &value, const std::string &path) {
     if (!contains(j, key, path)) {
@@ -1087,16 +1127,7 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, bracket_type &value
     if (!jk.is_string()) {
         throw std::invalid_argument("\""s + path + to_string(key) + "\" not a string");
     }
-    const auto &v = jk.template get<std::string>();
-    if (v == "begin") {
-        value = bracket_type::begin;
-        return;
-    }
-    if (v == "end") {
-        value = bracket_type::end;
-        return;
-    }
-    throw std::invalid_argument("\""s + path + to_string(key) + "\" not a bracket type");
+    value = bracket_type_from_name(jk.template get<std::string>());
 }
 
 template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, bracket_type &value,
@@ -1779,17 +1810,54 @@ template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t
 template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key, fork_result &value,
     const std::string &path);
 
+template <typename K>
+void ju_get_opt_field(const nlohmann::json &j, const K &key, mcycle_root_hashes &value, const std::string &path) {
+    if (!contains(j, key, path)) {
+        return;
+    }
+    const auto &jconfig = j[key];
+    const auto new_path = path + to_string(key) + "/";
+    ju_get_vector_like_field(jconfig, "hashes"s, value.hashes, new_path);
+    ju_get_field(jconfig, "mcycle_phase"s, value.mcycle_phase, new_path);
+    ju_get_field(jconfig, "break_reason"s, value.break_reason, new_path);
+}
+
+template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, mcycle_root_hashes &value,
+    const std::string &path);
+
+template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key, mcycle_root_hashes &value,
+    const std::string &path);
+
+template <typename K>
+void ju_get_opt_field(const nlohmann::json &j, const K &key, uarch_cycle_root_hashes &value, const std::string &path) {
+    if (!contains(j, key, path)) {
+        return;
+    }
+    const auto &jconfig = j[key];
+    const auto new_path = path + to_string(key) + "/";
+    ju_get_vector_like_field(jconfig, "hashes"s, value.hashes, new_path);
+    ju_get_vector_like_field(jconfig, "reset_indices"s, value.hashes, new_path);
+    ju_get_field(jconfig, "break_reason"s, value.break_reason, new_path);
+}
+
+template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, uarch_cycle_root_hashes &value,
+    const std::string &path);
+
+template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key,
+    uarch_cycle_root_hashes &value, const std::string &path);
+
 void to_json(nlohmann::json &j, const machine_reg &reg) {
     j = reg_to_name(reg);
 }
 
-void to_json(nlohmann::json &j, const machine_hash &h) {
-    j = encode_base64(h);
+void to_json(nlohmann::json &j, const base64_machine_hash &h) {
+    j = encode_base64(h.get());
 }
 
-void to_json(nlohmann::json &j, const std::vector<machine_hash> &hs) {
+void to_json(nlohmann::json &j, const base64_machine_hashes &hs) {
     j = nlohmann::json::array();
-    std::ranges::transform(hs, std::back_inserter(j), [](const machine_hash &h) -> nlohmann::json { return h; });
+    std::ranges::transform(hs.get(), std::back_inserter(j),
+        [](const machine_hash &h) -> nlohmann::json { return base64_machine_hash(h); });
 }
 
 void to_json(nlohmann::json &j, const hash_tree_proof &p) {
@@ -1804,7 +1872,7 @@ void to_json(nlohmann::json &j, const hash_tree_proof &p) {
 
 void to_json(nlohmann::json &j, const access &a) {
     j = nlohmann::json{
-        {"type", access_type_name(a.get_type())},
+        {"type", access_type_to_name(a.get_type())},
         {"address", a.get_address()},
         {"log2_size", a.get_log2_size()},
     };
@@ -1840,7 +1908,15 @@ void to_json(nlohmann::json &j, const access &a) {
 }
 
 void to_json(nlohmann::json &j, const bracket_note &b) {
-    j = nlohmann::json{{"type", bracket_type_name(b.type)}, {"where", b.where}, {"text", b.text}};
+    j = nlohmann::json{{"type", bracket_type_to_name(b.type)}, {"where", b.where}, {"text", b.text}};
+}
+
+void to_json(nlohmann::json &j, const uarch_interpreter_break_reason &break_reason) {
+    j = uarch_interpreter_break_reason_to_name(break_reason);
+}
+
+void to_json(nlohmann::json &j, const interpreter_break_reason &break_reason) {
+    j = interpreter_break_reason_to_name(break_reason);
 }
 
 void to_json(nlohmann::json &j, const std::vector<bracket_note> &bs) {
@@ -2146,4 +2222,19 @@ void to_json(nlohmann::json &j, const page_hash_tree_cache_stats &stats) {
     };
 }
 
+void to_json(nlohmann::json &j, const std::vector<uint64_t> &ints) {
+    j = nlohmann::json::array();
+    std::ranges::copy(ints, std::back_inserter(j));
+}
+
+void to_json(nlohmann::json &j, const mcycle_root_hashes &result) {
+    j = nlohmann::json{{"hashes", base64_machine_hashes(result.hashes)}, {"mcycle_phase", result.mcycle_phase},
+        {"break_reason", result.break_reason}};
+}
+
+void to_json(nlohmann::json &j, const uarch_cycle_root_hashes &result) {
+    j = nlohmann::json{{"hashes", base64_machine_hashes(result.hashes)}, {"reset_indices", result.reset_indices},
+        {"break_reason", result.break_reason}};
+}
+
 } // namespace cartesi
diff --git a/src/json-util.h b/src/json-util.h
index c8aa9bb1c..9d259640f 100644
--- a/src/json-util.h
+++ b/src/json-util.h
@@ -38,8 +38,10 @@
 #include "machine-hash.h"
 #include "machine-reg.h"
 #include "machine-runtime-config.h"
+#include "mcycle-root-hashes.h"
 #include "page-hash-tree-cache-stats.h"
 #include "semantic-version.h"
+#include "uarch-cycle-root-hashes.h"
 #include "uarch-interpret.h"
 
 namespace cartesi {
@@ -560,6 +562,26 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, address_range_descr
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, fork_result &value, const std::string &path = "params/");
 
+/// \brief Attempts to load an mcycle_root_hashes object from a field in a JSON object
+/// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
+/// \param j JSON object to load from
+/// \param key Key to load value from
+/// \param value Object to store value
+/// \param path Path to j
+template <typename K>
+void ju_get_opt_field(const nlohmann::json &j, const K &key, mcycle_root_hashes &value,
+    const std::string &path = "params/");
+
+/// \brief Attempts to load an uarch_cycle_root_hashes object from a field in a JSON object
+/// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
+/// \param j JSON object to load from
+/// \param key Key to load value from
+/// \param value Object to store value
+/// \param path Path to j
+template <typename K>
+void ju_get_opt_field(const nlohmann::json &j, const K &key, uarch_cycle_root_hashes &value,
+    const std::string &path = "params/");
+
 /// \brief Attempts to load a vector from a field in a JSON object
 /// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
 /// \param j JSON object to load from
@@ -635,10 +657,24 @@ void ju_get_field(const nlohmann::json &j, const K &key, T &value, const std::st
     ju_get_opt_field(j, key, value, path);
 }
 
+template <typename T>
+class override_to_json {
+    const T &m_t; // NOLINT(cppcoreguidelines-avoid-const-or-ref-data-members)
+
+public:
+    explicit override_to_json(const T &t) : m_t(t) {};
+    const T &get() const {
+        return m_t;
+    }
+};
+
+using base64_machine_hash = override_to_json<machine_hash>;
+using base64_machine_hashes = override_to_json<machine_hashes>;
+
 // Automatic conversion functions from Cartesi types to nlohmann::json
 void to_json(nlohmann::json &j, const access_log::type &log_type);
-void to_json(nlohmann::json &j, const machine_hash &h);
-void to_json(nlohmann::json &j, const std::vector<machine_hash> &hs);
+void to_json(nlohmann::json &j, const base64_machine_hash &h);
+void to_json(nlohmann::json &j, const base64_machine_hashes &hs);
 void to_json(nlohmann::json &j, const hash_tree_proof &p);
 void to_json(nlohmann::json &j, const page_hash_tree_cache_stats &s);
 void to_json(nlohmann::json &j, const hash_tree_stats &s);
@@ -647,6 +683,8 @@ void to_json(nlohmann::json &j, const bracket_note &b);
 void to_json(nlohmann::json &j, const std::vector<bracket_note> &bs);
 void to_json(nlohmann::json &j, const std::vector<access> &as);
 void to_json(nlohmann::json &j, const access_log &log);
+void to_json(nlohmann::json &j, const interpreter_break_reason &break_reason);
+void to_json(nlohmann::json &j, const uarch_interpreter_break_reason &break_reason);
 void to_json(nlohmann::json &j, const backing_store_config &config);
 void to_json(nlohmann::json &j, const backing_store_config_only &config);
 void to_json(nlohmann::json &j, const memory_range_config &config);
@@ -675,6 +713,9 @@ void to_json(nlohmann::json &j, const address_range_description &mrd);
 void to_json(nlohmann::json &j, const address_range_descriptions &mrds);
 void to_json(nlohmann::json &j, const fork_result &fork_result);
 void to_json(nlohmann::json &j, const semantic_version &version);
+void to_json(nlohmann::json &j, const std::vector<uint64_t> &uints);
+void to_json(nlohmann::json &j, const mcycle_root_hashes &result);
+void to_json(nlohmann::json &j, const uarch_cycle_root_hashes &result);
 
 // Extern template declarations
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, std::string &value,
@@ -865,6 +906,14 @@ extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &k
     const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, fork_result &value,
     const std::string &base = "params/");
+extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, mcycle_root_hashes &value,
+    const std::string &base = "params/");
+extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, mcycle_root_hashes &value,
+    const std::string &base = "params/");
+extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, uarch_cycle_root_hashes &value,
+    const std::string &base = "params/");
+extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, uarch_cycle_root_hashes &value,
+    const std::string &base = "params/");
 
 template <typename T>
 nlohmann::json to_json(const T &v) {
diff --git a/src/jsonrpc-discover.json b/src/jsonrpc-discover.json
index 40c9a4a93..af27763da 100644
--- a/src/jsonrpc-discover.json
+++ b/src/jsonrpc-discover.json
@@ -2,7 +2,7 @@
   "openrpc": "1.0.0-rc1",
   "info": {
     "title": "Remote Cartesi Machine",
-    "version": "0.5.0",
+    "version": "0.6.0",
     "description": "API for controlling a remote Cartesi Machine server",
     "license": {
       "name": "MIT"
@@ -223,6 +223,43 @@
         }
       }
     },
+    {
+      "name": "machine.collect_mcycle_root_hashes",
+      "summary": "Collect root hashes periodically while running the emulator",
+      "params": [
+        {
+          "name": "mcycle_phase",
+          "description": "Number of machine cycles elapsed since last root hash collected",
+          "required": true,
+          "schema": {
+            "$ref": "#/components/schemas/UnsignedInteger"
+          }
+        },
+        {
+          "name": "mcycle_period",
+          "description": "Number of machine cycles between root hashes to collect",
+          "required": true,
+          "schema": {
+            "$ref": "#/components/schemas/UnsignedInteger"
+          }
+        },
+        {
+          "name": "period_count",
+          "description": "Number of hashes to collect",
+          "required": true,
+          "schema": {
+            "$ref": "#/components/schemas/UnsignedInteger"
+          }
+        }
+      ],
+      "result": {
+        "name": "result",
+        "description": "Collected hashes",
+        "schema": {
+          "$ref": "#/components/schemas/McycleRootHashes"
+        }
+      }
+    },
     {
       "name": "machine.run_uarch",
       "summary": "Runs the small emulator until a given cycle",
@@ -244,6 +281,27 @@
         }
       }
     },
+    {
+      "name": "machine.collect_uarch_cycle_root_hashes",
+      "summary": "Collect root hashes while running the emulator's uarch",
+      "params": [
+        {
+          "name": "mcycle_count",
+          "description": "Number of machine cycles to execute, uarch cycle by uarch cycle",
+          "required": true,
+          "schema": {
+            "$ref": "#/components/schemas/UnsignedInteger"
+          }
+        }
+      ],
+      "result": {
+        "name": "result",
+        "description": "Collected hashes",
+        "schema": {
+          "$ref": "#/components/schemas/UarchCycleRootHashes"
+        }
+      }
+    },
     {
       "name": "machine.log_step_uarch",
       "summary": "Runs the small emulator for one cycle and return a log of state accesses",
@@ -341,11 +399,11 @@
     },
     {
       "name": "machine.get_root_hash",
-      "summary": "Obtains the Merkle hash of the current machine state",
+      "summary": "Obtains the hash-tree root hash of the current machine state",
       "params": [],
       "result": {
         "name": "hash",
-        "description": "Merkle hash",
+        "description": "Root hash",
         "schema": {
           "$ref": "#/components/schemas/Base64Hash"
         }
@@ -2147,6 +2205,46 @@
         "items": {
           "$ref": "#/components/schemas/AddressRangeDescription"
         }
+      },
+      "McycleRootHashes": {
+        "title": "McycleRootHashes",
+        "type": "object",
+        "properties": {
+          "hashes": {
+            "$ref": "#/components/schemas/Base64HashArray"
+          },
+          "mcycle_phase": {
+            "$ref": "#/components/schemas/UnsignedInteger"
+          },
+          "break_reason": {
+            "$ref": "#/components/schemas/InterpreterBreakReason"
+          }
+        },
+        "required": [
+          "hashes",
+          "mcycle_phase",
+          "break_reason"
+        ]
+      },
+      "UarchCycleRootHashes": {
+        "title": "UarchCycleRootHashes",
+        "type": "object",
+        "properties": {
+          "hashes": {
+            "$ref": "#/components/schemas/Base64HashArray"
+          },
+          "reset_indices": {
+            "$ref": "#/components/schemas/UnsignedIntegerArray"
+          },
+          "break_reason": {
+            "$ref": "#/components/schemas/InterpreterBreakReason"
+          }
+        },
+        "required": [
+          "hashes",
+          "reset_indices",
+          "break_reason"
+        ]
       }
     }
   }
diff --git a/src/jsonrpc-machine.cpp b/src/jsonrpc-machine.cpp
index 0b97415af..f92e377d6 100644
--- a/src/jsonrpc-machine.cpp
+++ b/src/jsonrpc-machine.cpp
@@ -643,6 +643,11 @@ interpreter_break_reason jsonrpc_machine::do_run(uint64_t mcycle_end) {
     return result;
 }
 
+void jsonrpc_machine::do_collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_period,
+    uint64_t period_count, mcycle_root_hashes &result) {
+    request("machine.collect_mcycle_root_hashes", std::tie(mcycle_phase, mcycle_period, period_count), result);
+}
+
 interpreter_break_reason jsonrpc_machine::do_log_step(uint64_t mcycle_count, const std::string &filename) {
     interpreter_break_reason result = interpreter_break_reason::failed;
     request("machine.log_step", std::tie(mcycle_count, filename), result);
@@ -799,6 +804,10 @@ uarch_interpreter_break_reason jsonrpc_machine::do_run_uarch(uint64_t uarch_cycl
     return result;
 }
 
+void jsonrpc_machine::do_collect_uarch_cycle_root_hashes(uint64_t mcycle_count, uarch_cycle_root_hashes &result) {
+    request("machine.collect_uarch_cycle_root_hashes", std::tie(mcycle_count), result);
+}
+
 address_range_descriptions jsonrpc_machine::do_get_address_ranges() const {
     address_range_descriptions result;
     request("machine.get_address_ranges", std::tie(), result);
diff --git a/src/jsonrpc-machine.h b/src/jsonrpc-machine.h
index 70f28917f..aeb94d944 100644
--- a/src/jsonrpc-machine.h
+++ b/src/jsonrpc-machine.h
@@ -107,6 +107,8 @@ class jsonrpc_machine final : public i_machine {
     void do_create(const machine_config &config, const machine_runtime_config &runtime) override;
     void do_load(const std::string &directory, const machine_runtime_config &runtime) override;
     interpreter_break_reason do_run(uint64_t mcycle_end) override;
+    void do_collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_period, uint64_t period_count,
+        mcycle_root_hashes &result) override;
     interpreter_break_reason do_log_step(uint64_t mcycle_count, const std::string &filename) override;
     void do_store(const std::string &dir) const override;
     uint64_t do_read_reg(reg r) const override;
@@ -131,6 +133,7 @@ class jsonrpc_machine final : public i_machine {
     hash_tree_stats do_get_hash_tree_stats(bool clear) override;
     bool do_verify_hash_tree() const override;
     uarch_interpreter_break_reason do_run_uarch(uint64_t uarch_cycle_end) override;
+    void do_collect_uarch_cycle_root_hashes(uint64_t mcycle_count, uarch_cycle_root_hashes &result) override;
     address_range_descriptions do_get_address_ranges() const override;
     void do_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length) override;
     access_log do_log_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
diff --git a/src/jsonrpc-remote-machine.cpp b/src/jsonrpc-remote-machine.cpp
index 3cbdcfa40..69d490785 100644
--- a/src/jsonrpc-remote-machine.cpp
+++ b/src/jsonrpc-remote-machine.cpp
@@ -887,6 +887,41 @@ static json jsonrpc_machine_create_handler(const json &j, const std::shared_ptr<
     return jsonrpc_response_ok(j);
 }
 
+/// \brief JSONRPC handler for the machine.collect_mcycle_root_hashes method
+/// \param j JSON request object
+/// \param session HTTP session
+/// \returns JSON response object
+static json jsonrpc_machine_collect_mcycle_root_hashes(const json &j, const std::shared_ptr<http_session> &session) {
+    if (!session->handler->machine) {
+        return jsonrpc_response_invalid_request(j, "no machine");
+    }
+    static const char *param_name[] = {"mcycle_phase", "mcycle_period", "period_count"};
+    auto args = parse_args<uint64_t, uint64_t, uint64_t>(j, param_name);
+    auto mcycle_phase = std::get<0>(args);
+    auto mcycle_period = std::get<1>(args);
+    auto period_count = std::get<2>(args);
+    cartesi::mcycle_root_hashes result;
+    session->handler->machine->collect_mcycle_root_hashes(mcycle_phase, mcycle_period, period_count, result);
+    return jsonrpc_response_ok(j, result);
+}
+
+/// \brief JSONRPC handler for the machine.collect_uarch_cycle_root_hashes method
+/// \param j JSON request object
+/// \param session HTTP session
+/// \returns JSON response object
+static json jsonrpc_machine_collect_uarch_cycle_root_hashes(const json &j,
+    const std::shared_ptr<http_session> &session) {
+    if (!session->handler->machine) {
+        return jsonrpc_response_invalid_request(j, "no machine");
+    }
+    static const char *param_name[] = {"mcycle_count"};
+    auto args = parse_args<uint64_t>(j, param_name);
+    auto mcycle_count = std::get<0>(args);
+    cartesi::uarch_cycle_root_hashes result;
+    session->handler->machine->collect_uarch_cycle_root_hashes(mcycle_count, result);
+    return jsonrpc_response_ok(j, result);
+}
+
 /// \brief JSONRPC handler for the machine.destroy method
 /// \param j JSON request object
 /// \param session HTTP session
@@ -942,28 +977,6 @@ static json jsonrpc_machine_store_handler(const json &j, const std::shared_ptr<h
     return jsonrpc_response_ok(j);
 }
 
-/// \brief Translate an interpret_break_reason value to string
-/// \param reason interpret_break_reason value to translate
-/// \returns String representation of value
-static std::string interpreter_break_reason_name(cartesi::interpreter_break_reason reason) {
-    using R = cartesi::interpreter_break_reason;
-    switch (reason) {
-        case R::failed:
-            return "failed";
-        case R::halted:
-            return "halted";
-        case R::yielded_manually:
-            return "yielded_manually";
-        case R::yielded_automatically:
-            return "yielded_automatically";
-        case R::yielded_softly:
-            return "yielded_softly";
-        case R::reached_target_mcycle:
-            return "reached_target_mcycle";
-    }
-    throw std::domain_error{"invalid interpreter break reason"};
-}
-
 /// \brief JSONRPC handler for the machine.run method
 /// \param j JSON request object
 /// \param session HTTP session
@@ -975,7 +988,7 @@ static json jsonrpc_machine_run_handler(const json &j, const std::shared_ptr<htt
     static const char *param_name[] = {"mcycle_end"};
     auto args = parse_args<uint64_t>(j, param_name);
     auto reason = session->handler->machine->run(std::get<0>(args));
-    return jsonrpc_response_ok(j, interpreter_break_reason_name(reason));
+    return jsonrpc_response_ok(j, reason);
 }
 
 /// \brief JSONRPC handler for the machine.log_step method
@@ -989,21 +1002,7 @@ static json jsonrpc_machine_log_step_handler(const json &j, const std::shared_pt
     static const char *param_name[] = {"mcycle_count", "filename"};
     auto args = parse_args<uint64_t, std::string>(j, param_name);
     auto reason = session->handler->machine->log_step(std::get<0>(args), std::get<1>(args));
-    return jsonrpc_response_ok(j, interpreter_break_reason_name(reason));
-}
-
-/// \brief Translate an uarch_interpret_break_reason value to string
-/// \param reason uarch_interpret_break_reason value to translate
-/// \returns String representation of value
-static std::string uarch_interpreter_break_reason_name(cartesi::uarch_interpreter_break_reason reason) {
-    using R = cartesi::uarch_interpreter_break_reason;
-    switch (reason) {
-        case R::uarch_halted:
-            return "uarch_halted";
-        case R::reached_target_cycle:
-            return "reached_target_cycle";
-    }
-    throw std::domain_error{"invalid uarch interpreter break reason"};
+    return jsonrpc_response_ok(j, reason);
 }
 
 /// \brief JSONRPC handler for the machine.run_uarch method
@@ -1017,7 +1016,7 @@ static json jsonrpc_machine_run_uarch_handler(const json &j, const std::shared_p
     static const char *param_name[] = {"uarch_cycle_end"};
     auto args = parse_args<uint64_t>(j, param_name);
     auto reason = session->handler->machine->run_uarch(std::get<0>(args));
-    return jsonrpc_response_ok(j, uarch_interpreter_break_reason_name(reason));
+    return jsonrpc_response_ok(j, reason);
 }
 
 /// \brief JSONRPC handler for the machine.log_step_uarch method
@@ -1059,7 +1058,7 @@ static json jsonrpc_machine_verify_step_handler(const json &j, const std::shared
     // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
     auto reason =
         cartesi::machine::verify_step(std::get<0>(args), std::get<1>(args), std::get<2>(args), std::get<3>(args));
-    return jsonrpc_response_ok(j, interpreter_break_reason_name(reason));
+    return jsonrpc_response_ok(j, reason);
 }
 
 /// \brief JSONRPC handler for the machine.verify_step_uarch method
@@ -1142,7 +1141,7 @@ static json jsonrpc_machine_get_root_hash_handler(const json &j, const std::shar
     }
     jsonrpc_check_no_params(j);
     auto hash = session->handler->machine->get_root_hash();
-    return jsonrpc_response_ok(j, cartesi::encode_base64(hash));
+    return jsonrpc_response_ok(j, cartesi::base64_machine_hash(hash));
 }
 
 /// \brief JSONRPC handler for the machine.get_node_hash method
@@ -1159,7 +1158,7 @@ static json jsonrpc_machine_get_node_hash_handler(const json &j, const std::shar
         throw std::domain_error("log2_size is out of range");
     }
     auto hash = session->handler->machine->get_node_hash(std::get<0>(args), static_cast<int>(std::get<1>(args)));
-    return jsonrpc_response_ok(j, cartesi::encode_base64(hash));
+    return jsonrpc_response_ok(j, cartesi::base64_machine_hash(hash));
 }
 
 /// \brief JSONRPC handler for the machine.read_word method
@@ -1488,6 +1487,8 @@ static json jsonrpc_dispatch_method(const json &j, const std::shared_ptr<http_se
         {"get_version", jsonrpc_get_version_handler},
         {"delay_next_request", jsonrpc_delay_next_request_handler},
         {"rpc.discover", jsonrpc_rpc_discover_handler},
+        {"machine.collect_mcycle_root_hashes", jsonrpc_machine_collect_mcycle_root_hashes},
+        {"machine.collect_uarch_cycle_root_hashes", jsonrpc_machine_collect_uarch_cycle_root_hashes},
         {"machine.create", jsonrpc_machine_create_handler},
         {"machine.is_empty", jsonrpc_machine_is_empty_handler},
         {"machine.load", jsonrpc_machine_load_handler},
diff --git a/src/jsonrpc-version.h b/src/jsonrpc-version.h
index 436af16fd..fe7c03142 100644
--- a/src/jsonrpc-version.h
+++ b/src/jsonrpc-version.h
@@ -22,7 +22,7 @@
 namespace cartesi {
 
 constexpr uint32_t JSONRPC_VERSION_MAJOR = 0;
-constexpr uint32_t JSONRPC_VERSION_MINOR = 5;
+constexpr uint32_t JSONRPC_VERSION_MINOR = 6;
 constexpr uint32_t JSONRPC_VERSION_PATCH = 0;
 constexpr const char *JSONRPC_VERSION_PRE_RELEASE = "";
 constexpr const char *JSONRPC_VERSION_BUILD = "";
diff --git a/src/local-machine.cpp b/src/local-machine.cpp
index 4b858adb8..00d95d1b2 100644
--- a/src/local-machine.cpp
+++ b/src/local-machine.cpp
@@ -73,6 +73,11 @@ interpreter_break_reason local_machine::do_run(uint64_t mcycle_end) {
     return get_machine()->run(mcycle_end);
 }
 
+void local_machine::do_collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_period, uint64_t period_count,
+    mcycle_root_hashes &result) {
+    get_machine()->collect_mcycle_root_hashes(mcycle_phase, mcycle_period, period_count, result);
+}
+
 interpreter_break_reason local_machine::do_log_step(uint64_t mcycle_count, const std::string &filename) {
     return m_machine->log_step(mcycle_count, filename);
 }
@@ -166,6 +171,10 @@ uarch_interpreter_break_reason local_machine::do_run_uarch(uint64_t uarch_cycle_
     return get_machine()->run_uarch(uarch_cycle_end);
 }
 
+void local_machine::do_collect_uarch_cycle_root_hashes(uint64_t mcycle_count, uarch_cycle_root_hashes &result) {
+    get_machine()->collect_uarch_cycle_root_hashes(mcycle_count, result);
+}
+
 address_range_descriptions local_machine::do_get_address_ranges() const {
     return get_machine()->get_address_ranges();
 }
diff --git a/src/local-machine.h b/src/local-machine.h
index 93fccc583..ced33649a 100644
--- a/src/local-machine.h
+++ b/src/local-machine.h
@@ -49,6 +49,8 @@ class local_machine : public i_machine {
     void do_create(const machine_config &config, const machine_runtime_config &runtime) override;
     void do_load(const std::string &directory, const machine_runtime_config &runtime) override;
     interpreter_break_reason do_run(uint64_t mcycle_end) override;
+    void do_collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_period, uint64_t period_count,
+        mcycle_root_hashes &result) override;
     interpreter_break_reason do_log_step(uint64_t mcycle_count, const std::string &filename) override;
     void do_store(const std::string &directory) const override;
     access_log do_log_step_uarch(const access_log::type &log_type) override;
@@ -73,6 +75,7 @@ class local_machine : public i_machine {
     void do_reset_uarch() override;
     access_log do_log_reset_uarch(const access_log::type &log_type) override;
     uarch_interpreter_break_reason do_run_uarch(uint64_t uarch_cycle_end) override;
+    void do_collect_uarch_cycle_root_hashes(uint64_t mcycle_count, uarch_cycle_root_hashes &result) override;
     address_range_descriptions do_get_address_ranges() const override;
     void do_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length) override;
     access_log do_log_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
diff --git a/src/machine-c-api.cpp b/src/machine-c-api.cpp
index de25eece0..3a2fa4382 100644
--- a/src/machine-c-api.cpp
+++ b/src/machine-c-api.cpp
@@ -606,6 +606,39 @@ cm_error cm_run(cm_machine *m, uint64_t mcycle_end, cm_break_reason *break_reaso
     return cm_result_failure();
 }
 
+cm_error cm_collect_mcycle_root_hashes(cm_machine *m, uint64_t mcycle_phase, uint64_t mcycle_period,
+    uint64_t period_count, const char **result) try {
+    if (result == nullptr) {
+        throw std::invalid_argument("invalid result output");
+    }
+    auto *cpp_m = convert_from_c(m);
+    cartesi::mcycle_root_hashes cpp_res;
+    cpp_m->collect_mcycle_root_hashes(mcycle_phase, mcycle_period, period_count, cpp_res);
+    *result = cm_set_temp_string(cartesi::to_json(cpp_res).dump());
+    return cm_result_success();
+} catch (...) {
+    if (result != nullptr) {
+        *result = nullptr;
+    }
+    return cm_result_failure();
+}
+
+cm_error cm_collect_uarch_cycle_root_hashes(cm_machine *m, uint64_t mcycle_count, const char **result) try {
+    if (result == nullptr) {
+        throw std::invalid_argument("invalid result output");
+    }
+    auto *cpp_m = convert_from_c(m);
+    cartesi::uarch_cycle_root_hashes cpp_res;
+    cpp_m->collect_uarch_cycle_root_hashes(mcycle_count, cpp_res);
+    *result = cm_set_temp_string(cartesi::to_json(cpp_res).dump());
+    return cm_result_success();
+} catch (...) {
+    if (result != nullptr) {
+        *result = nullptr;
+    }
+    return cm_result_failure();
+}
+
 cm_error cm_reset_uarch(cm_machine *m) try {
     auto *cpp_m = convert_from_c(m);
     cpp_m->reset_uarch();
@@ -644,7 +677,7 @@ cm_error cm_run_uarch(cm_machine *m, uint64_t uarch_cycle_end, cm_uarch_break_re
     return cm_result_failure();
 }
 
-CM_API cm_error cm_log_step(cm_machine *m, uint64_t mcycle_count, const char *log_filename,
+cm_error cm_log_step(cm_machine *m, uint64_t mcycle_count, const char *log_filename,
     cm_break_reason *break_reason) try {
     if (log_filename == nullptr) {
         throw std::invalid_argument("invalid log_filename");
diff --git a/src/machine-c-api.h b/src/machine-c-api.h
index c2928766c..ee779f9c7 100644
--- a/src/machine-c-api.h
+++ b/src/machine-c-api.h
@@ -600,6 +600,31 @@ CM_API cm_error cm_translate_virtual_address(cm_machine *m, uint64_t vaddr, uint
 /// \details You may want to receive cmio requests depending on the run break reason.
 CM_API cm_error cm_run(cm_machine *m, uint64_t mcycle_end, cm_break_reason *break_reason);
 
+/// \brief Collects the root hashes after every \p mcycle_period machine cycles, for \p period_count periods.
+/// Returns when done, or if the machine halts or yields.
+/// \param mcycle_phase Number of machine cycles elapsed since last root hash collected.
+/// \param mcycle_period Number of machine cycles between root hashes to collect.
+/// \param period_count Number of hashes to collect.
+/// \param result Receives an JSON object as a string, guaranteed to remain valid only until
+/// the next CM_API function is called from the same thread.
+/// The field "hashes" is an array (of hashes as base64-encoded strings) with the root hashes after each period.
+/// The field "mcycle_phase" is the number of machine cycles elapsed since last root hash collected.
+/// The field "break_reason" is an integer with the reason why the function returned.
+/// (Set to CM_BREAK_REASON_FAILED on failure.)
+/// For example:
+/// ```json
+/// {
+///     "hashes": ["2av44Q3TaHKREgULA/iMoNe+btxCr+ja+hHGtXxaGjM=", ..., "FMAHn7mc2f+I30UjiywbAtOkw99iOa3NWS6fWql3UNU="],
+///     "mcycle_phase": 1278,
+///     "break_reason": CM_BREAK_REASON_YIELDED_AUTOMATICALLY
+/// }
+/// ```
+/// \returns 0 for success, non zero code for error.
+/// \detail The first hash added to \p result.hashes is the root hash after (\p mcycle_period - \p mcycle_phase)
+/// machine cycles (if the function managed to get that far before returning).
+CM_API cm_error cm_collect_mcycle_root_hashes(cm_machine *m, uint64_t mcycle_countdown, uint64_t mcycle_period,
+    uint64_t period_count, const char **result);
+
 /// \brief Runs the machine microarchitecture until CM_REG_UARCH_CYCLE reaches uarch_cycle_end or it halts.
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
 /// \param uarch_cycle_end End micro cycle value.
@@ -607,6 +632,29 @@ CM_API cm_error cm_run(cm_machine *m, uint64_t mcycle_end, cm_break_reason *brea
 /// \returns 0 for success, non zero code for error.
 CM_API cm_error cm_run_uarch(cm_machine *m, uint64_t uarch_cycle_end, cm_uarch_break_reason *uarch_break_reason);
 
+/// \brief Collects the root hashes after every uarch cycle, for \p mcycle_count machine cycles, implicitly
+/// resetting the uarch between each machine cycle. Returns when done, or if the machine halts or yields.
+/// \param mcycle_count Number of machine cycles to execute, uarch cycle by uarch cycle.
+/// \param hashes Receives an JSON object as a string, guaranteed to remain valid only until
+/// the next CM_API function is called from the same thread.
+/// The field "hashes" is an array (of hashes as base64-encoded strings) with the root hashes after each uarch cycle.
+/// The field "reset_indices" is an array with indices of the root hashes after each implicit uarch reset
+/// (i.e., after each machine cycle).
+/// The field "break_reason" is an integer with the reason why the function returned.
+/// (Set to CM_BREAK_REASON_FAILED on failure.)
+/// For example:
+/// ```json
+/// {
+///     "hashes": ["2av44Q3TaHKREgULA/iMoNe+btxCr+ja+hHGtXxaGjM=", ..., "FMAHn7mc2f+I30UjiywbAtOkw99iOa3NWS6fWql3UNU="],
+///     "reset_indices": [712, ..., 2293768],
+///     "break_reason": CM_BREAK_REASON_YIELDED_MANUALLY
+/// }
+/// ```
+/// \returns 0 for success, non zero code for error.
+/// \detail The first hash added to \p hashes is the root hash after the first uarch cycle, the last is the
+/// root hash at the time function returns (for whatever reason), which always happens right after an uarch reset.
+CM_API cm_error cm_collect_uarch_cycle_root_hashes(cm_machine *m, uint64_t mcycle_count, const char **result);
+
 /// \brief Resets the entire microarchitecture state to pristine values.
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
 /// \returns 0 for success, non zero code for error.
diff --git a/src/machine-hash.h b/src/machine-hash.h
index fb68820b5..28d921704 100644
--- a/src/machine-hash.h
+++ b/src/machine-hash.h
@@ -22,6 +22,7 @@
 
 #include <array>
 #include <span>
+#include <vector>
 
 namespace cartesi {
 
@@ -29,6 +30,7 @@ static constexpr size_t machine_hash_size = 32;
 using machine_hash = std::array<unsigned char, machine_hash_size>;
 using machine_hash_view = std::span<unsigned char, machine_hash_size>;
 using const_machine_hash_view = std::span<const unsigned char, machine_hash_size>;
+using machine_hashes = std::vector<machine_hash>;
 
 } // namespace cartesi
 
diff --git a/src/machine.cpp b/src/machine.cpp
index 2ac5de47b..b7cb9374b 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -26,6 +26,7 @@
 #include <cstring>
 #include <iomanip>
 #include <iostream>
+#include <iterator>
 #include <memory>
 #include <ranges>
 #include <sstream>
@@ -37,6 +38,8 @@
 #include "access-log.h"
 #include "address-range-constants.h"
 #include "address-range.h"
+#include "collect-mcycle-hashes-state-access.h"
+#include "collect-uarch-cycle-hashes-state-access.h"
 #include "compiler-defines.h"
 #include "device-state-access.h"
 #include "dtb.h"
@@ -1353,7 +1356,7 @@ bool machine::update_hash_tree_page(uint64_t address) {
 
 machine_hash machine::get_root_hash() const {
     if (!update_hash_tree()) {
-        throw std::runtime_error{"update hash-tree failed"};
+        throw std::runtime_error{"update hash tree failed"};
     }
     return m_ht.get_root_hash();
 }
@@ -1386,7 +1389,7 @@ const char *machine::get_what_name(uint64_t paddr) {
 
 machine_hash machine::get_node_hash(uint64_t address, int log2_size) const {
     if (!update_hash_tree()) {
-        throw std::runtime_error{"update hash-tree failed"};
+        throw std::runtime_error{"update hash tree failed"};
     }
     return get_node_hash(address, log2_size, skip_hash_tree_update);
 }
@@ -1403,7 +1406,7 @@ machine::proof_type machine::get_proof(uint64_t address, int log2_size, skip_has
 
 machine::proof_type machine::get_proof(uint64_t address, int log2_size) const {
     if (!update_hash_tree()) {
-        throw std::runtime_error{"update hash-tree failed"};
+        throw std::runtime_error{"update hash tree failed"};
     }
     return get_proof(address, log2_size, skip_hash_tree_update);
 }
@@ -1694,7 +1697,7 @@ access_log machine::log_send_cmio_response(uint16_t reason, const unsigned char
     }
     // Verify access log before returning
     if (!update_hash_tree()) {
-        throw std::runtime_error{"update hash-tree failed"};
+        throw std::runtime_error{"update hash tree failed"};
     }
     auto root_hash_after = get_root_hash();
     verify_send_cmio_response(reason, data, length, root_hash_before, log, root_hash_after);
@@ -1741,7 +1744,7 @@ access_log machine::log_reset_uarch(const access_log::type &log_type) {
     }
     // Verify access log before returning
     if (!update_hash_tree()) {
-        throw std::runtime_error{"update hash-tree failed"};
+        throw std::runtime_error{"update hash tree failed"};
     }
     const auto root_hash_after = get_root_hash();
     verify_reset_uarch(root_hash_before, log, root_hash_after);
@@ -1817,7 +1820,7 @@ uarch_interpreter_break_reason machine::run_uarch(uint64_t uarch_cycle_end) {
 
 interpreter_break_reason machine::log_step(uint64_t mcycle_count, const std::string &filename) {
     if (!update_hash_tree()) {
-        throw std::runtime_error{"update hash-tree failed"};
+        throw std::runtime_error{"update hash tree failed"};
     }
     // Ensure that the microarchitecture is reset
     auto current_uarch_state_hash =
@@ -1860,6 +1863,10 @@ interpreter_break_reason machine::run(uint64_t mcycle_end) {
     if (mcycle_end < mcycle) {
         throw std::invalid_argument{"mcycle is past"};
     }
+    const auto uarch_cycle = read_reg(reg::uarch_cycle);
+    if (uarch_cycle != 0) {
+        throw std::invalid_argument{"microarchitecture is not reset"};
+    }
     const state_access a(*this);
     os_silence_putchar(m_r.htif.no_console_putchar);
     return interpret(a, mcycle_end);
@@ -1928,4 +1935,119 @@ void machine::write_counter(uint64_t val, const char *name, const char *domain)
     m_counters[get_counter_key(name, domain)] = val;
 }
 
+void machine::collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_period, uint64_t period_count,
+    mcycle_root_hashes &result) {
+    result.hashes.clear();
+    if (mcycle_period == 0) {
+        throw std::runtime_error{"mcycle_period cannot be 0"};
+    }
+    if (mcycle_phase >= mcycle_period) {
+        throw std::runtime_error{"mcycle_phase must be in {0, ..., mcycle_period-1}"};
+    }
+    if (read_reg(reg::iunrep) != 0) {
+        throw std::runtime_error{"cannot collect hashes from unreproducible machines"};
+    }
+    if (m_r.soft_yield) {
+        throw std::runtime_error{"cannot collect hashes when soft yield is enabled"};
+    }
+    if (!update_hash_tree()) {
+        throw std::runtime_error{"update hash tree failed"};
+    }
+    auto current_uarch_state_hash =
+        get_node_hash(AR_SHADOW_UARCH_STATE_START, UARCH_STATE_LOG2_SIZE, skip_hash_tree_update);
+    if (current_uarch_state_hash != get_uarch_pristine_state_hash()) {
+        throw std::runtime_error{"microarchitecture is not reset"};
+    }
+    collect_mcycle_hashes_state_access::context context{};
+    context.dirty_words.reserve(mcycle_period * 3);
+    const collect_mcycle_hashes_state_access a(context, *this);
+    os_silence_putchar(m_r.htif.no_console_putchar);
+    auto mcycle_start = read_reg(reg::mcycle);
+    for (uint64_t period = 0; period < period_count; ++period) {
+        uint64_t mcycle_target{};
+        context.dirty_words.clear();
+        if (__builtin_add_overflow(mcycle_start, mcycle_period - mcycle_phase, &mcycle_target)) {
+            mcycle_target = UINT64_MAX;
+        }
+        mcycle_phase = 0;
+        result.break_reason = interpret(a, mcycle_target);
+        const auto mcycle_end = read_reg(reg::mcycle);
+        if (!m_ht.update_words(m_ars, context.dirty_words)) {
+            throw std::runtime_error{"update hash tree failed"};
+        }
+        context.dirty_words.clear();
+        // If the machine stopped before we asked, we are done
+        if (mcycle_end != mcycle_target) {
+            break;
+        }
+        result.hashes.emplace_back(m_ht.get_root_hash());
+        mcycle_start = mcycle_end;
+    }
+    result.mcycle_phase = read_reg(reg::mcycle) - mcycle_start;
+}
+
+void machine::collect_uarch_cycle_root_hashes(uint64_t mcycle_count, uarch_cycle_root_hashes &result) {
+    result.hashes.clear();
+    result.reset_indices.clear();
+    if (read_reg(reg::iunrep) != 0) {
+        throw std::runtime_error{"cannot collect hashes from unreproducible machines"};
+    }
+    if (m_r.soft_yield) {
+        throw std::runtime_error{"cannot collect hashes when soft yield is enabled"};
+    }
+    if (!update_hash_tree()) {
+        throw std::runtime_error{"update hash tree failed"};
+    }
+    auto current_uarch_state_hash =
+        get_node_hash(AR_SHADOW_UARCH_STATE_START, UARCH_STATE_LOG2_SIZE, skip_hash_tree_update);
+    if (current_uarch_state_hash != get_uarch_pristine_state_hash()) {
+        throw std::runtime_error{"microarchitecture is not reset"};
+    }
+    collect_uarch_cycle_hashes_state_access::context context{};
+    context.dirty_words.reserve(mcycle_count);
+    const collect_uarch_cycle_hashes_state_access a(context, *this);
+    os_silence_putchar(m_r.htif.no_console_putchar);
+    auto mcycle_start = read_reg(reg::mcycle);
+    for (uint64_t mcycles = 0; mcycles < mcycle_count; ++mcycles) {
+        auto uarch_cycle_start = read_reg(reg::uarch_cycle);
+        // Add one hash after each uarch cycle
+        for (;;) {
+            uint64_t uarch_cycle_target = 0;
+            if (__builtin_add_overflow(uarch_cycle_start, 1, &uarch_cycle_target)) {
+                break;
+            }
+            uarch_interpret(a, uarch_cycle_target);
+            const auto uarch_cycle_end = read_reg(reg::uarch_cycle);
+            if (!m_ht.update_words(m_ars, context.dirty_words)) {
+                throw std::runtime_error{"update hash tree failed"};
+            }
+            context.dirty_words.clear();
+            if (uarch_cycle_end != uarch_cycle_target) {
+                break;
+            }
+            result.hashes.emplace_back(m_ht.get_root_hash());
+            uarch_cycle_start = uarch_cycle_end;
+        }
+        // Add one hash after the uarch reset, and the index where it happened
+        //??D maybe optimize this?
+        reset_uarch();
+        if (!update_hash_tree()) {
+            throw std::runtime_error{"update hash tree failed"};
+        }
+        result.reset_indices.emplace_back(result.hashes.size());
+        result.hashes.emplace_back(m_ht.get_root_hash());
+    }
+    // Now check why we stopped
+    auto mcycle_end = read_reg(reg::mcycle);
+    if (mcycle_end - mcycle_start == mcycle_count) {
+        result.break_reason = interpreter_break_reason::reached_target_mcycle;
+    } else if (read_reg(reg::iflags_H) != 0) {
+        result.break_reason = interpreter_break_reason::halted;
+    } else if (read_reg(reg::iflags_Y) != 0) {
+        result.break_reason = interpreter_break_reason::yielded_manually;
+    } else if (read_reg(reg::iflags_X) != 0) {
+        result.break_reason = interpreter_break_reason::yielded_automatically;
+    }
+}
+
 } // namespace cartesi
diff --git a/src/machine.h b/src/machine.h
index 8d1b56049..8e0c1e75a 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -39,10 +39,12 @@
 #include "machine-config.h"
 #include "machine-reg.h"
 #include "machine-runtime-config.h"
+#include "mcycle-root-hashes.h"
 #include "os.h"
 #include "pmas-constants.h"
 #include "processor-state.h"
 #include "shadow-tlb.h"
+#include "uarch-cycle-root-hashes.h"
 #include "uarch-interpret.h"
 #include "uarch-processor-state.h"
 #include "virtio-address-range.h"
@@ -135,9 +137,10 @@ class machine final {
     bool has_htif_console() const;
 
 public:
-    /// \brief Type of hash and proof
+    /// \brief Shorthand for the proof type
     using proof_type = hash_tree::proof_type;
 
+    /// \brief Shorthand for machine register type
     using reg = machine_reg;
 
     /// \brief Constructor from machine configuration
@@ -189,6 +192,19 @@ class machine final {
     ///  halts.
     interpreter_break_reason run(uint64_t mcycle_end);
 
+    /// \brief Collects the root hashes after every \p mcycle_period machine cycles, for \p period_count periods.
+    /// Returns when done, or if the machine halts or yields.
+    /// \param mcycle_phase Number of machine cycles elapsed since last root hash collected.
+    /// \param mcycle_period Number of machine cycles between root hashes to collect.
+    /// \param period_count Number of hashes to collect.
+    /// \param result Stores into result.hashes the root hashes after each period.
+    /// Stores into result.mcycle_phase the number of machine cycles after last root hash collected.
+    /// Stores into result.break_reason the reason the function returned.
+    /// \detail The first hash added to \p result.hashes is the root hash after (\p mcycle_period - \p mcycle_phase)
+    /// machine cycles (if the function managed to get that far before returning).
+    void collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_period, uint64_t period_count,
+        mcycle_root_hashes &result);
+
     /// \brief Runs the machine for the given mcycle count and generates a log of accessed pages and proof data.
     /// \param mcycle_count Number of mcycles to run the machine for.
     /// \param filename Name of the file to store the log.
@@ -208,6 +224,16 @@ class machine final {
     /// \param uarch_cycle_end uarch_cycle limit
     uarch_interpreter_break_reason run_uarch(uint64_t uarch_cycle_end);
 
+    /// \brief Collects the root hashes after every uarch cycle, for \p mcycle_count machine cycles, implicitly
+    /// resetting the uarch between each machine cycle. Returns when done, or if the machine halts or yields.
+    /// \param mcycle_count Number of machine cycles to execute, uarch cycle by uarch cycle.
+    /// \param result Stores into result.hashes the root hashes after each uarch cycle.
+    /// Stores into result.reset_indices the indices of the root hashes after each implicit uarch reset (i.e., after
+    /// each machine cycle). Stores into result.break_reason the reason why the function returned.
+    /// \detail The first hash added to \p result.hashes is the root hash after the first uarch cycle, the last is the
+    /// root hash at the time function returns (for whatever reason), which always happens right after an uarch reset.
+    void collect_uarch_cycle_root_hashes(uint64_t mcycle_count, uarch_cycle_root_hashes &result);
+
     /// \brief Advances one micro step and returns a state access log.
     /// \param log_type Type of access log to generate.
     /// \returns The state access log.
diff --git a/src/mcycle-root-hashes.h b/src/mcycle-root-hashes.h
new file mode 100644
index 000000000..f1a6dc222
--- /dev/null
+++ b/src/mcycle-root-hashes.h
@@ -0,0 +1,36 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef MCYCLE_ROOT_HASHES_H
+#define MCYCLE_ROOT_HASHES_H
+
+#include <cstdint>
+
+#include "interpret.h"
+#include "machine-hash.h"
+
+namespace cartesi {
+
+/// \brief Collected mcycle root hashes
+struct mcycle_root_hashes {
+    machine_hashes hashes;                   ///< Root hashes collected after each machine cycle period
+    uint64_t mcycle_phase{};                 ///< Machine cycles elapsed since last collected root hash
+    interpreter_break_reason break_reason{}; ///< Reason why function returned
+};
+
+} // namespace cartesi
+
+#endif
diff --git a/src/page-hash-tree-cache.h b/src/page-hash-tree-cache.h
index a97212ea8..5b5b2634c 100644
--- a/src/page-hash-tree-cache.h
+++ b/src/page-hash-tree-cache.h
@@ -167,16 +167,21 @@ class page_hash_tree_cache {
             return tree;
         }
 
-        /// \brief Returns entry's page
-        /// \returns Reference to entry's page
-        const auto &get_page() const noexcept {
-            return m_page;
-        }
+    public:
+        /// \brief Constructor from pristine page
+        /// \param pristine Pristine page hash tree for hasher in use
+        explicit entry(const page_hash_tree &pristine) : m_hash_tree{pristine} {}
 
-        /// \brief Returns entry's page
-        /// \returns Reference to entry's page
-        auto &get_page() noexcept {
-            return m_page;
+        entry(const entry &other) = default;
+        entry(entry &&other) = default;
+        entry &operator=(const entry &other) = default;
+        entry &operator=(entry &&other) = default;
+        ~entry() = default;
+
+        /// \brief Returns page address for entry
+        /// \returns Target physical address of page
+        address_type get_paddr_page() const noexcept {
+            return static_cast<address_type>(aliased_aligned_read<uint64_t>(&m_hash_tree[0][m_paddr_page_offset]));
         }
 
         /// \brief Returns entry's page hash tree
@@ -191,21 +196,16 @@ class page_hash_tree_cache {
             return m_hash_tree;
         }
 
-    public:
-        /// \brief Constructor from pristine page
-        /// \param pristine Pristine page hash tree for hasher in use
-        explicit entry(const page_hash_tree &pristine) : m_hash_tree{pristine} {}
-
-        entry(const entry &other) = default;
-        entry(entry &&other) = default;
-        entry &operator=(const entry &other) = default;
-        entry &operator=(entry &&other) = default;
-        ~entry() = default;
+        /// \brief Returns entry's page
+        /// \returns Reference to entry's page
+        const auto &get_page() const noexcept {
+            return m_page;
+        }
 
-        /// \brief Returns page address for entry
-        /// \returns Target physical address of page
-        address_type get_paddr_page() const noexcept {
-            return static_cast<address_type>(aliased_aligned_read<uint64_t>(&m_hash_tree[0][m_paddr_page_offset]));
+        /// \brief Returns entry's page
+        /// \returns Reference to entry's page
+        auto &get_page() noexcept {
+            return m_page;
         }
 
         /// \brief Returns view to root hash from entry's page hash tree
@@ -353,6 +353,22 @@ class page_hash_tree_cache {
     page_hash_tree_cache &operator=(const page_hash_tree_cache &other) = delete;
     page_hash_tree_cache &operator=(page_hash_tree_cache &&other) = delete;
 
+    /// \brief Tries to borrow a cache entry
+    /// \param paddr_page Target physical address of page to borrow
+    /// \returns Entry for page if in cache, nothing otherwise
+    std::optional<std::reference_wrapper<entry>> borrow_entry_if_hit(address_type paddr_page) {
+        // Found entry for page in map?
+        if (auto it = m_map.find(paddr_page); it != m_map.end()) {
+            entry &e = it->second.second;
+            if (e.get_borrowed()) {
+                throw std::runtime_error{"page hash-tree cache entry already borrowed"};
+            }
+            // Return borrowed entry
+            return std::ref(e.set_borrowed(true));
+        }
+        return {};
+    }
+
     /// \brief Tries to borrow a cache entry
     /// \param paddr_page Target physical address of page to borrow
     /// \param hit Receives true if page was found in cache, false if another page was evicted and its entry returned
diff --git a/src/record-step-state-access.h b/src/record-step-state-access.h
index 58c90a7fd..c03b90708 100644
--- a/src/record-step-state-access.h
+++ b/src/record-step-state-access.h
@@ -316,7 +316,6 @@ class record_step_state_access :
         os_putchar(c);
     }
 
-    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
     constexpr const char *do_get_name() const { // NOLINT(readability-convert-member-functions-to-static)
         return "record_step_state_access";
     }
diff --git a/src/test-calldata.lua b/src/test-calldata.lua
new file mode 100644
index 000000000..07d7ffc12
--- /dev/null
+++ b/src/test-calldata.lua
@@ -0,0 +1,751 @@
+local calldata = require("cartesi.calldata")
+
+local function ptab(output, indent)
+    indent = indent or 0
+    local spaces = string.rep("  ", indent)
+    if type(output) ~= "table" then
+        print(spaces .. tostring(output))
+        return
+    end
+    print(spaces .. "{")
+    for k, v in pairs(output) do
+        local key_str
+        if type(k) == "string" then
+            key_str = string.format("[%q]", k)
+        else
+            key_str = "[" .. tostring(k) .. "]"
+        end
+        if calldata.is_raw(v) or calldata.is_hex(v) then v = tostring(v) end
+        if type(v) == "table" and not calldata.bint.isintegral(v) then
+            print(spaces .. "  " .. key_str .. " = ")
+            ptab(v, indent + 1)
+        else
+            local value_str
+            if type(v) == "string" then
+                value_str = string.format("%q", v)
+            else
+                value_str = tostring(v)
+            end
+            print(spaces .. "  " .. key_str .. " = " .. value_str .. ",")
+        end
+    end
+    print(spaces .. "}")
+end
+
+local function tv(a)
+    if a == nil then return "nil" end
+    return string.format("%s %s", type(a), tostring(a))
+end
+
+-- checks that table a is a subset of table b
+local function subtab(a, b, path)
+    path = path or "/"
+    if calldata.bint.isintegral(a) or calldata.bint.isintegral(b) then
+        local ai = calldata.bint.new(a)
+        local bi = b and calldata.bint.new(b)
+        if not calldata.bint.eq(ai, bi) then
+            return nil, string.format("%s value differs (%s vs %s)", path, tostring(a), tostring(b))
+        end
+        return 1
+    end
+    if calldata.is_raw(a) then a = calldata.get_raw(a) end
+    if calldata.is_hex(a) then a = calldata.get_hex(a) end
+    if calldata.is_raw(b) then b = calldata.get_raw(b) end
+    if calldata.is_hex(b) then a = calldata.get_hex(b) end
+    local ta, tb = type(a), type(b)
+    if ta ~= tb then return nil, string.format("%s type differs (%s vs %s)", path, tv(a), tv(b)) end
+    if ta ~= "table" then
+        if a ~= b then return nil, string.format("%s value differs (%s vs %s)", path, tostring(a), tostring(b)) end
+        return 1
+    end
+    for i, va in pairs(a) do
+        local ev, err = subtab(va, b[i], string.format(path .. tostring(i) .. "/"))
+        if not ev then return nil, err end
+    end
+    return 1
+end
+
+local function check_parse_type_spec(s, output) assert(subtab(calldata.parse_type_spec(s), output)) end
+
+local function check_parse_func_sig(s, expected_output)
+    local output = calldata.parse_func_sig(s)
+    local ret, err = subtab(expected_output, output)
+    if not ret then
+        ptab(expected_output)
+        ptab(output)
+        assert(ret, err)
+    end
+end
+
+local function is_suffix(suffix, s) return s:sub(-#suffix) == suffix end
+
+local function check_parse_func_sig_error(s, expected_err)
+    local ret, err = pcall(calldata.parse_func_sig, s)
+    assert(not ret, "expected function to fail")
+    assert(
+        is_suffix(expected_err, err),
+        string.format("error message mismatch (expected %s, got %s)", expected_err, tostring(err))
+    )
+end
+
+local function check_parse_type_spec_error(s, expected_err)
+    local ret, err = pcall(calldata.parse_type_spec, s)
+    assert(not ret, "expected error")
+    assert(is_suffix(expected_err, err), string.format("expected sufix '%s' in '%s'", expected_err, tostring(err)))
+end
+
+local function strdiff(a, b)
+    local i = 1
+    local a_len = #a
+    local b_len = #a
+    local min_len = math.min(a_len, b_len)
+    while i <= min_len and a:byte(i) == b:byte(i) do
+        i = i + 1
+    end
+    if i <= math.max(a_len, b_len) then return i, a:sub(i), b:sub(i) end
+    return nil
+end
+
+local function check_encode_decode_calldata_hex(s, args, expected_cd, prefer)
+    local cd = assert(calldata.encode_calldata_hex(s, args))
+    if cd ~= expected_cd then
+        local i, rest_cd, rest_expected_cd = strdiff(cd, expected_cd)
+        error(string.format("calldata differs starting at %d (expected '%s', got '%s')", i, rest_expected_cd, rest_cd))
+    end
+    local decoded_args = assert(calldata.decode_calldata_hex(s, cd, prefer))
+    local ret, err = subtab(args, decoded_args)
+    if not ret then
+        ptab(args)
+        ptab(decoded_args)
+        error(err)
+    end
+end
+
+local function check_encode_calldata_hex_error(s, args, expected_err)
+    local ret, err = pcall(calldata.encode_calldata_hex, s, args)
+    assert(not ret, "expected error")
+    assert(is_suffix(expected_err, err), string.format("expected sufix '%s' in '%s'", expected_err, tostring(err)))
+end
+
+local function check_decode_calldata_hex_error(s, cd, expected_err)
+    local ret, err = pcall(calldata.decode_calldata_hex, s, cd)
+    assert(not ret, "expected error")
+    assert(is_suffix(expected_err, err), string.format("expected sufix '%s' in '%s'", expected_err, tostring(err)))
+end
+
+local function check_encode_hex(s, expected_hex)
+    local hex = assert(calldata.encode_hex(s))
+    if hex ~= expected_hex then
+        local i, rest_hex, rest_expected_hex = strdiff(hex, expected_hex)
+        error(
+            string.format(
+                "hex encoding differs starting at %d (expected '%s', got '%s')",
+                i,
+                rest_expected_hex,
+                rest_hex
+            )
+        )
+    end
+end
+
+local function check_decode_hex(hex, expected_s)
+    local s = assert(calldata.decode_hex(hex))
+    if s ~= expected_s then
+        local i, rest_s, rest_expected_s = strdiff(s, expected_s)
+        error(string.format("hex decoding differs starting at %d (expected %q, got %q)", i, rest_expected_s, rest_s))
+    end
+end
+
+local function check_decode_hex_error(s, expected_err)
+    local ret, err = calldata.decode_hex(s)
+    assert(not ret, "expected error")
+    assert(is_suffix(expected_err, err), string.format("expected sufix '%s' in '%s'", expected_err, tostring(err)))
+end
+
+-- check hex encoding/decoding
+check_encode_hex("", "0x")
+check_encode_hex("\x00", "0x00")
+check_encode_hex("\x00\x01", "0x0001")
+check_encode_hex("\x00\x01\x02", "0x000102")
+check_encode_hex("\x00\x01\x02\x03", "0x00010203")
+local all = {}
+local all_hex = { "0x" }
+for i = 0, 255 do
+    all[i + 1] = string.char(i)
+    all_hex[i + 2] = string.format("%02x", i)
+end
+all = table.concat(all)
+all_hex = table.concat(all_hex)
+check_encode_hex(all, all_hex)
+check_decode_hex("0x", "")
+check_decode_hex("0X00", "\x00")
+check_decode_hex("0x0001", "\x00\x01")
+check_decode_hex("0X000102", "\x00\x01\x02")
+check_decode_hex("0x00010203", "\x00\x01\x02\x03")
+check_decode_hex(all_hex, all)
+check_decode_hex_error("", 'hex string must start with "0x"')
+check_decode_hex_error("0", 'hex string must start with "0x"')
+check_decode_hex_error("0x0", "hex string length must be even")
+check_decode_hex_error("0x0m", 'hex string cannot contain "0m"')
+-- check int types
+check_parse_type_spec("int", { type_name = "int", size = 256 })
+check_parse_type_spec("uint", { type_name = "uint", size = 256 })
+for w = 0, 264 do
+    if w % 8 == 0 and w >= 8 and w <= 256 then
+        check_parse_type_spec(string.format("int%d", w), { type_name = "int", size = w })
+        check_parse_type_spec(string.format("uint%d", w), { type_name = "uint", size = w })
+    else
+        check_parse_type_spec_error(
+            string.format("int%d", w),
+            string.format('expected integer size at line 1, column 4 (got "%d")', w)
+        )
+        check_parse_type_spec_error(
+            string.format("uint%d", w),
+            string.format('expected integer size at line 1, column 5 (got "%d")', w)
+        )
+    end
+end
+-- check bytes types
+check_parse_type_spec("bytes", { type_name = "bytes" })
+check_parse_type_spec_error("bytes0", 'expected bytes size at line 1, column 6 (got "0")')
+check_parse_type_spec_error("bytes33", 'expected bytes size at line 1, column 6 (got "33")')
+for w = 1, 32 do
+    check_parse_type_spec(string.format("bytes%d", w), { type_name = "bytes", size = w })
+end
+-- check other simple types
+check_parse_type_spec("address", { type_name = "address" })
+check_parse_type_spec("string", { type_name = "string" })
+check_parse_type_spec("bool", { type_name = "bool" })
+-- check array
+check_parse_type_spec("int[]", { type_name = "array", element_type = { type_name = "int", size = 256 } })
+check_parse_type_spec("string[2]", { type_name = "array", element_type = { type_name = "string" }, size = 2 })
+check_parse_type_spec("bytes16[2][]", {
+    type_name = "array",
+    element_type = {
+        type_name = "array",
+        element_type = {
+            type_name = "bytes",
+            size = 16,
+        },
+        size = 2,
+    },
+})
+check_parse_type_spec(
+    "address[][2]",
+    { type_name = "array", element_type = { type_name = "array", element_type = { type_name = "address" } }, size = 2 }
+)
+check_parse_type_spec_error("int[0]", 'expected closing bracket or array size at line 1, column 5 (got "0]")')
+check_parse_type_spec_error("int[-1]", 'expected closing bracket or array size at line 1, column 5 (got "-1]")')
+check_parse_type_spec_error("int[", 'expected closing bracket or array size at line 1, column 5 (got "")')
+check_parse_type_spec_error("int[10", 'expected closing bracket at line 1, column 7 (got "")')
+check_parse_type_spec_error("int[10][a", 'expected closing bracket or array size at line 1, column 9 (got "a")')
+-- check tuple
+check_parse_type_spec("()", { type_name = "tuple", components = {} })
+check_parse_type_spec("(int)", { type_name = "tuple", components = { { type_name = "int", size = 256 } } })
+check_parse_type_spec(
+    "(int,string)",
+    { type_name = "tuple", components = { { type_name = "int", size = 256 }, {
+        type_name = "string",
+    } } }
+)
+check_parse_type_spec_error("(,)", 'expected closing parenthesis at line 1, column 2 (got ",)")')
+check_parse_type_spec_error("(int,)", 'expected type spec at line 1, column 6 (got ")")')
+-- check nesting
+check_parse_type_spec(
+    "(int[])",
+    { type_name = "tuple", components = { { type_name = "array", element_type = { size = 256, type_name = "int" } } } }
+)
+check_parse_type_spec("(int[])[]", {
+    type_name = "array",
+    element_type = {
+        type_name = "tuple",
+        components = { { type_name = "array", element_type = { size = 256, type_name = "int" } } },
+    },
+})
+check_parse_type_spec("((int[])[])", {
+    type_name = "tuple",
+    components = {
+        {
+            type_name = "array",
+            element_type = {
+                type_name = "tuple",
+                components = { { type_name = "array", element_type = { size = 256, type_name = "int" } } },
+            },
+        },
+    },
+})
+
+local function make_int(size, data_location, name)
+    return { type_name = "int", size = size or 256, name = name, data_location = data_location }
+end
+local function make_uint(size, data_location, name)
+    return { type_name = "int", size = size or 256, name = name, data_location = data_location }
+end
+local function make_tuple(components, data_location, name)
+    return { type_name = "tuple", components = components, name = name, data_location = data_location }
+end
+local empty_tuple = make_tuple({})
+local function make_address(data_location, name)
+    return { type_name = "address", name = name, data_location = data_location }
+end
+local function make_bool(data_location, name) return { type_name = "bool", name = name, data_location = data_location } end
+
+-- check
+check_parse_func_sig("_()", { name = "_", params = empty_tuple, returns = empty_tuple })
+check_parse_func_sig("_() returns ()", { name = "_", params = empty_tuple, returns = empty_tuple })
+check_parse_func_sig("function _() returns ()", { name = "_", params = empty_tuple, returns = empty_tuple })
+check_parse_func_sig("a()", { name = "a", params = empty_tuple, returns = empty_tuple })
+check_parse_func_sig("_a()", { name = "_a", params = empty_tuple, returns = empty_tuple })
+check_parse_func_sig("_a0()", { name = "_a0", params = empty_tuple, returns = empty_tuple })
+check_parse_func_sig("_a0a()", { name = "_a0a", params = empty_tuple, returns = empty_tuple })
+check_parse_func_sig("_(int)", { name = "_", params = make_tuple({ make_int() }), returns = empty_tuple })
+check_parse_func_sig(
+    "_(int a)",
+    { name = "_", params = make_tuple({ make_int(nil, nil, "a") }), returns = empty_tuple }
+)
+check_parse_func_sig(
+    "_(int memory)",
+    { name = "_", params = make_tuple({ make_int(nil, "memory") }), returns = empty_tuple }
+)
+check_parse_func_sig(
+    "_(int storage)",
+    { name = "_", params = make_tuple({ make_int(nil, "storage") }), returns = empty_tuple }
+)
+check_parse_func_sig(
+    "_(int calldata)",
+    { name = "_", params = make_tuple({ make_int(nil, "calldata") }), returns = empty_tuple }
+)
+check_parse_func_sig(
+    "_(int memory a)",
+    { name = "_", params = make_tuple({ make_int(nil, "memory", "a") }), returns = empty_tuple }
+)
+check_parse_func_sig(
+    "_(int storage a)",
+    { name = "_", params = make_tuple({ make_int(nil, "storage", "a") }), returns = empty_tuple }
+)
+check_parse_func_sig(
+    "_(int calldata a)",
+    { name = "_", params = make_tuple({ make_int(nil, "calldata", "a") }), returns = empty_tuple }
+)
+check_parse_func_sig(
+    "_(int, address)",
+    { name = "_", params = make_tuple({ make_int(), make_address() }), returns = empty_tuple }
+)
+check_parse_func_sig("_(int, address memory)", {
+    name = "_",
+    params = make_tuple({ make_int(), make_address("memory") }),
+    returns = empty_tuple,
+})
+check_parse_func_sig(
+    "_(int a, address)",
+    { name = "_", params = make_tuple({ make_int(nil, nil, "a"), make_address() }), returns = empty_tuple }
+)
+check_parse_func_sig(
+    "_(int, address a)",
+    { name = "_", params = make_tuple({ make_int(), make_address(nil, "a") }), returns = empty_tuple }
+)
+check_parse_func_sig(
+    "_() returns (address) ",
+    { name = "_", params = empty_tuple, returns = make_tuple({ make_address() }) }
+)
+check_parse_func_sig(
+    "_() returns (address a) ",
+    { name = "_", params = empty_tuple, returns = make_tuple({ make_address(nil, "a") }) }
+)
+check_parse_func_sig(
+    "_() returns (address memory a) ",
+    { name = "_", params = empty_tuple, returns = make_tuple({ make_address("memory", "a") }) }
+)
+check_parse_func_sig(
+    "_() returns (address, bool) ",
+    { name = "_", params = empty_tuple, returns = make_tuple({ make_address(), make_bool() }) }
+)
+check_parse_func_sig_error("()", 'expected identifier at line 1, column 1 (got "()")')
+check_parse_func_sig_error("\n()", 'expected identifier at line 2, column 1 (got "()")')
+check_parse_func_sig_error("int", 'expected parameters at line 1, column 4 (got "")')
+check_parse_func_sig_error("_(", 'expected closing parenthesis at line 1, column 3 (got "")')
+check_parse_func_sig_error("_(int", 'expected closing parenthesis at line 1, column 6 (got "")')
+check_parse_func_sig_error("_(int, ", 'expected type spec at line 1, column 8 (got "")')
+check_parse_func_sig_error("_() returns ", 'expected return parameters at line 1, column 13 (got "")')
+check_parse_func_sig_error("_() returns (", 'expected closing parenthesis at line 1, column 14 (got "")')
+check_parse_func_sig_error("_() returns (int", 'expected closing parenthesis at line 1, column 17 (got "")')
+check_parse_func_sig_error("_() returns (int, ", 'expected type spec at line 1, column 19 (got "")')
+-- check calldata encoding
+check_encode_decode_calldata_hex("_()", {}, "0xb7ba4583")
+check_encode_decode_calldata_hex(
+    "_(int)",
+    { 1 },
+    "0x9e5758430000000000000000000000000000000000000000000000000000000000000001"
+)
+check_encode_decode_calldata_hex(
+    "f(int)",
+    { 1 },
+    "0x1c008df90000000000000000000000000000000000000000000000000000000000000001"
+)
+check_encode_decode_calldata_hex(
+    "f(int, uint)",
+    { 1, 2 },
+    "0x711a885400000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000002"
+)
+check_encode_calldata_hex_error("f(int, uint)", { 1 }, "missing tuple component at index 2")
+check_encode_decode_calldata_hex(
+    "g(int)",
+    { "0x10000000000000000000000000" },
+    "0x7877b8030000000000000000000000000000000000000010000000000000000000000000"
+)
+-- check overflows
+check_encode_decode_calldata_hex(
+    "_(uint8)",
+    { 0xff },
+    "0x1bf62fa700000000000000000000000000000000000000000000000000000000000000ff"
+)
+check_encode_decode_calldata_hex(
+    "_(int8)",
+    { -128 },
+    "0x6a2b4692ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff80"
+)
+check_encode_calldata_hex_error("_(int8)", { 0xff }, "integer value does not fit in target type")
+check_encode_calldata_hex_error("_(uint8)", { 0x100 }, "integer value does not fit in target type")
+check_encode_calldata_hex_error("_(uint8)", { -1 }, "integer value does not fit in target type")
+check_encode_decode_calldata_hex(
+    "_(uint16)",
+    { 0xffff },
+    "0x5c4b5213000000000000000000000000000000000000000000000000000000000000ffff"
+)
+check_encode_decode_calldata_hex(
+    "_(int16)",
+    { -32768 },
+    "0x69ebd716ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff8000"
+)
+check_encode_calldata_hex_error("_(int16)", { 0xffff }, "integer value does not fit in target type")
+check_encode_calldata_hex_error("_(uint16)", { 0x10000 }, "integer value does not fit in target type")
+check_encode_calldata_hex_error("_(uint16)", { -1 }, "integer value does not fit in target type")
+check_encode_decode_calldata_hex(
+    "_(uint)",
+    { "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff" },
+    "0xa29f3781ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
+)
+check_encode_calldata_hex_error(
+    "_(int)",
+    { "0x8000000000000000000000000000000000000000000000000000000000000000" },
+    "integer value does not fit in target type"
+)
+check_encode_decode_calldata_hex(
+    "_(int)",
+    { "-0x8000000000000000000000000000000000000000000000000000000000000000" },
+    "0x9e5758438000000000000000000000000000000000000000000000000000000000000000"
+)
+check_encode_calldata_hex_error("_(uint)", { -1 }, "integer value does not fit in target type")
+check_encode_calldata_hex_error(
+    "_(uint)",
+    { "0x10000000000000000000000000000000000000000000000000000000000000000" },
+    "integer value does not fit in target type"
+)
+check_encode_decode_calldata_hex(
+    "_(int)",
+    { "0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff" },
+    "0x9e5758437fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
+)
+-- check complex types
+check_encode_decode_calldata_hex(
+    "_(int[1])",
+    { { 1 } },
+    "0xe80da2d00000000000000000000000000000000000000000000000000000000000000001"
+)
+check_encode_decode_calldata_hex(
+    "_(int[2])",
+    { { 1, 2 } },
+    "0x2472621500000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000002"
+)
+check_encode_decode_calldata_hex(
+    "_(uint, int[1])",
+    { 1, { 2 } },
+    "0xb1c2ae4d00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000002"
+)
+check_encode_decode_calldata_hex(
+    "_(uint, int[1], uint)",
+    { 1, { 2 }, 3 },
+    "0x1bc702b7000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000003"
+)
+check_encode_decode_calldata_hex(
+    "_(int[])",
+    { {} },
+    "0x8b546acb00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000000"
+)
+check_encode_decode_calldata_hex(
+    "_(int[])",
+    { { 1 } },
+    "0x8b546acb000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000001"
+)
+check_encode_decode_calldata_hex(
+    "_(int[])",
+    { { 1, 2 } },
+    "0x8b546acb0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000002"
+)
+check_encode_decode_calldata_hex(
+    "_(uint, int[])",
+    { 1, { 2 } },
+    "0x2ae197ed0000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000002"
+)
+check_encode_decode_calldata_hex(
+    "_(uint, int[], uint)",
+    { 1, { 2 }, 3 },
+    "0xb9f5d30400000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000060000000000000000000000000000000000000000000000000000000000000000300000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000002"
+)
+check_encode_decode_calldata_hex(
+    "_(int[], uint[1])",
+    { {}, { 1 } },
+    "0x81d0480b000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000000"
+)
+check_encode_decode_calldata_hex(
+    "_(int[], uint[1])",
+    { { 1 }, { 2 } },
+    "0x81d0480b0000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000001"
+)
+check_encode_decode_calldata_hex(
+    "_(int[], uint[1])",
+    { { 1, 2 }, { 3 } },
+    "0x81d0480b00000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000003000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000002"
+)
+check_encode_decode_calldata_hex(
+    "_(int8[2], int[], uint[1])",
+    { { 1, 2 }, {}, { 3 } },
+    "0xf536915700000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000030000000000000000000000000000000000000000000000000000000000000000"
+)
+check_encode_decode_calldata_hex(
+    "_(int8[2], int[], uint[1])",
+    { { 1, 2 }, { 3 }, { 4 } },
+    "0xf5369157000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000003"
+)
+check_encode_decode_calldata_hex(
+    "_(int, int8[], int, int[], uint[1])",
+    { 1, {}, 2, {}, { 3 } },
+    "0x00dee871000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000c0000000000000000000000000000000000000000000000000000000000000000300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
+)
+check_encode_decode_calldata_hex(
+    "_(int, int8[], (int, int)[], uint[1])",
+    { 1, { 2 }, { { 3, 4 }, { 5, 6 } }, { 7 } },
+    "0xc7af7b760000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000c000000000000000000000000000000000000000000000000000000000000000070000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000003000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000050000000000000000000000000000000000000000000000000000000000000006"
+)
+check_encode_decode_calldata_hex(
+    "_(int, (int8[], (int, int)[2])[], uint[1])",
+    { 1, { { { 2, 3 }, { { 4, 5 }, { 6, 7 } } }, { {}, { { 8, 9 }, { 10, 11 } } } }, { 1 } },
+    "0x18e7bd6500000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000060000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000014000000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000050000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000700000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000300000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000009000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000b0000000000000000000000000000000000000000000000000000000000000000"
+)
+-- check strings and bytes
+check_encode_decode_calldata_hex(
+    "_(string)",
+    { "hello world" },
+    "0x6aedeb130000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000b68656c6c6f20776f726c64000000000000000000000000000000000000000000"
+)
+check_encode_decode_calldata_hex(
+    "_(string)",
+    { calldata.hex(calldata.encode_hex("hello world")) },
+    "0x6aedeb130000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000b68656c6c6f20776f726c64000000000000000000000000000000000000000000",
+    "hex"
+)
+check_encode_decode_calldata_hex(
+    "_(bytes5)",
+    { calldata.raw("hello") },
+    "0x63fa429c68656c6c6f000000000000000000000000000000000000000000000000000000",
+    "raw"
+)
+
+check_encode_decode_calldata_hex(
+    "_(bytes)",
+    { calldata.raw("hello") },
+    "0x9366a78b0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000568656c6c6f000000000000000000000000000000000000000000000000000000",
+    "raw"
+)
+
+check_encode_decode_calldata_hex(
+    "_(bytes)",
+    { calldata.encode_hex("hello") },
+    "0x9366a78b0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000568656c6c6f000000000000000000000000000000000000000000000000000000"
+)
+
+check_encode_decode_calldata_hex(
+    "_(string,bytes8)",
+    { "hello world", "0x0102030405060708" },
+    "0x6360493500000000000000000000000000000000000000000000000000000000000000400102030405060708000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000b68656c6c6f20776f726c64000000000000000000000000000000000000000000"
+)
+check_encode_calldata_hex_error(
+    "_(string,bytes8)",
+    { "hello world", "0x01020304050607" },
+    "bytes has wrong size (expected 8, got 7)"
+)
+check_encode_calldata_hex_error(
+    "_(string,bytes8)",
+    { "hello world", "0x010203040506070809" },
+    "bytes has wrong size (expected 8, got 9)"
+)
+check_encode_decode_calldata_hex(
+    "_(address)",
+    { "0x491604c0fdf08347dd1fa4ee062a822a5dd06b5d" },
+    "0xd4aa26ba000000000000000000000000491604c0fdf08347dd1fa4ee062a822a5dd06b5d"
+)
+check_encode_decode_calldata_hex(
+    "_(address)",
+    { calldata.raw(calldata.decode_hex("0x491604c0fdf08347dd1fa4ee062a822a5dd06b5d")) },
+    "0xd4aa26ba000000000000000000000000491604c0fdf08347dd1fa4ee062a822a5dd06b5d",
+    "raw"
+)
+check_encode_calldata_hex_error(
+    "_(address)",
+    { calldata.decode_hex("0x491604c0fdf08347dd1fa4ee062a822a5dd06b5d") },
+    'hex string must start with "0x"'
+)
+check_encode_calldata_hex_error(
+    "_(address)",
+    { "0x491604c0fdf08347dd1fa4ee062a822a5dd06b" },
+    "invalid address length (expected 20 bytes, got 19 bytes)"
+)
+check_encode_calldata_hex_error(
+    "_(address)",
+    { calldata.raw(calldata.decode_hex("0x491604c0fdf08347dd1fa4ee062a822a5dd06b")) },
+    "invalid address length (expected 20 bytes, got 19 bytes)"
+)
+check_encode_calldata_hex_error(
+    "_(address)",
+    { calldata.decode_hex("0x491604c0fdf08347dd1fa4ee062a822a5dd06b") },
+    'hex string must start with "0x"'
+)
+-- check bool
+check_encode_decode_calldata_hex(
+    "_(bool)",
+    { true },
+    "0x099660c90000000000000000000000000000000000000000000000000000000000000001"
+)
+check_encode_decode_calldata_hex(
+    "_(bool)",
+    { false },
+    "0x099660c90000000000000000000000000000000000000000000000000000000000000000"
+)
+check_encode_calldata_hex_error("_(bool)", { 0 }, "expected boolean (got number)")
+check_encode_calldata_hex_error("_(bool)", { 1 }, "expected boolean (got number)")
+check_encode_calldata_hex_error("_(bool)", { "true" }, "expected boolean (got string)")
+check_encode_calldata_hex_error("_(bool)", { "false" }, "expected boolean (got string)")
+
+-- check arg type errors
+check_encode_calldata_hex_error(1, nil, "expected function signature string")
+check_encode_calldata_hex_error({}, nil, "expected function signature string")
+check_encode_calldata_hex_error(nil, nil, "expected function signature string")
+
+check_encode_calldata_hex_error("_(int[])", nil, "expected arguments table")
+check_encode_calldata_hex_error("_(int)", {}, "missing tuple component at index 1")
+check_encode_calldata_hex_error("_(int[])", { 1 }, "array values not in table")
+check_encode_calldata_hex_error("_(int[])", { calldata.bint.new(1) }, "array values not in table")
+check_encode_calldata_hex_error("_(int[2])", { 1 }, "array values not in table")
+check_encode_calldata_hex_error("_(int[2])", { calldata.bint.new(1) }, "array values not in table")
+check_encode_calldata_hex_error("_((int,int))", { 1 }, "tuple values not in table")
+check_encode_calldata_hex_error("_((int,int))", { calldata.bint.new(1) }, "tuple values not in table")
+
+check_decode_calldata_hex_error(1, "0x", "expected function signature string")
+check_decode_calldata_hex_error({}, "0x", "expected function signature string")
+check_decode_calldata_hex_error(nil, "0x", "expected function signature string")
+
+check_decode_calldata_hex_error("_()", nil, "missing hex string")
+check_decode_calldata_hex_error("_()", "0x0", "hex string length must be even")
+check_decode_calldata_hex_error("_()", {}, "hex not a string")
+check_decode_calldata_hex_error(
+    "_()",
+    "0xb7ba45830000000000000000000000000000000000000000000000000000000000000001",
+    "calldata too long"
+)
+
+check_encode_calldata_hex_error("_(address)", { 1 }, "expected hex-encoded string value")
+check_encode_calldata_hex_error("_(address)", { {} }, "expected hex-encoded string value")
+check_encode_calldata_hex_error("_(bytes)", { 1 }, "expected hex-encoded string value")
+check_encode_calldata_hex_error("_(bytes8)", { 1 }, "expected hex-encoded string value")
+check_encode_calldata_hex_error("_(bytes)", { {} }, "expected hex-encoded string value")
+
+check_encode_calldata_hex_error("_(string)", { 1 }, "expected raw string value")
+check_encode_calldata_hex_error("_(string)", { {} }, "expected raw string value")
+
+check_encode_calldata_hex_error("_(bool)", { 1 }, "expected boolean (got number)")
+check_encode_calldata_hex_error("_(bool)", { {} }, "expected boolean (got table)")
+
+check_encode_calldata_hex_error("_(int[3])", { { 1, 2 } }, "invalid value count (expected 3, got 2)")
+check_encode_calldata_hex_error("_(int[3])", { { 1, 2, 3, 4 } }, "invalid value count (expected 3, got 4)")
+
+check_encode_calldata_hex_error("_(int,int,int)", { 1, 2 }, "missing tuple component at index 3")
+check_encode_calldata_hex_error("_(int,int,int a)", { 1, 2 }, 'missing tuple component at index 3 (or with name "a")')
+
+check_encode_decode_calldata_hex(
+    "_(int, int, int a)",
+    { [1] = 1, [2] = 2, a = 3 },
+    "0xacd77784000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000003"
+)
+check_encode_decode_calldata_hex(
+    "_(int, int a, int)",
+    { [1] = 1, [3] = 3, a = 2 },
+    "0xacd77784000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000003"
+)
+check_encode_decode_calldata_hex(
+    "_(int a, int, int)",
+    { [2] = 2, [3] = 3, a = 1 },
+    "0xacd77784000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000003"
+)
+
+check_encode_calldata_hex_error("_(int,int,int)", { 1, 2, 3, 4 }, "unexpected tuple component at index 4")
+check_encode_calldata_hex_error("_(int,int,int)", { 1, 2, 3, a = 4 }, 'unexpected tuple component with name "a"')
+
+check_encode_calldata_hex_error("_((int,int,int))", { { 1, 2 } }, "missing tuple component at index 3")
+check_encode_calldata_hex_error("_((int,int,int))", { { 1, 2, 3, 4 } }, "unexpected tuple component at index 4")
+
+check_decode_calldata_hex_error(
+    "_(bool)",
+    "0x099660c9000000000000000000000000000000",
+    "insufficient calldata for 256-bit word at offset 4"
+)
+check_decode_calldata_hex_error(
+    "_(bool)",
+    "0x099660c90000000000000000000000000000000000000000000000000000000000000003",
+    "invalid bool value in calldata (must be 0 or 1)"
+)
+
+check_decode_calldata_hex_error(
+    "_(uint8)",
+    "0x1bf62fa7ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff", -- -1
+    "integer value does not fit in target type"
+)
+
+check_decode_calldata_hex_error(
+    "_(uint8)",
+    "0x1bf62fa70000000000000000000000000000000000000000000000000000000000000100", -- 256
+    "integer value does not fit in target type"
+)
+
+check_decode_calldata_hex_error(
+    "_(int8)",
+    "0x6a2b46920000000000000000000000000000000000000000000000000000000000000100", -- 256
+    "integer value does not fit in target type"
+)
+
+check_decode_calldata_hex_error(
+    "_(int8)",
+    "0x6a2b4692ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f", -- -129
+    "integer value does not fit in target type"
+)
+
+check_decode_calldata_hex_error(
+    "_(uint8)",
+    "0x6a2b46920000000000000000000000000000000000000000000000000000000000000100",
+    "function selector mismatch (expected 0x1bf62fa7, got 0x6a2b4692)"
+)
+
+check_decode_calldata_hex_error(
+    "_(string)",
+    "0x6aedeb130000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000b68656c6c6f20776f726c",
+    "insufficient calldata for string of length 11"
+)
+
+check_decode_calldata_hex_error(
+    "_(bytes)",
+    "0x9366a78b000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000083031323334353637",
+    "insufficient calldata for bytes of length 8"
+)
+
+check_decode_calldata_hex_error("_(bytes7)", "0x155cf58f", "insufficient calldata for bytes7")
+
+check_decode_calldata_hex_error("_(bytes7)", "0x155cf5", "calldata too short (missing function selector)")
diff --git a/src/test-collect-hashes.lua b/src/test-collect-hashes.lua
new file mode 100755
index 000000000..6eb66b457
--- /dev/null
+++ b/src/test-collect-hashes.lua
@@ -0,0 +1,217 @@
+#!/usr/bin/env lua5.4
+
+-- Copyright Cartesi and individual authors (see AUTHORS)
+-- SPDX-License-Identifier: LGPL-3.0-or-later
+--
+-- This program is free software: you can redistribute it and/or modify it under
+-- the terms of the GNU Lesser General Public License as published by the Free
+-- Software Foundation, either version 3 of the License, or (at your option) any
+-- later version.
+--
+-- This program is distributed in the hope that it will be useful, but WITHOUT ANY
+-- WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+-- PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+--
+-- You should have received a copy of the GNU Lesser General Public License along
+-- with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+--
+local cartesi = require("cartesi")
+--local jsonrpc = require("cartesi.jsonrpc")
+local calldata = require("cartesi.calldata")
+local socket = require("socket")
+
+local function stderr(...) io.stderr:write((string.format(...))) end
+
+local tinsert = table.insert
+
+local function tappend(t, elems)
+    local n = #t
+    for i, v in ipairs(elems) do
+        t[n + i] = v
+    end
+end
+
+local function errorf(fmt, ...) error(string.format(fmt, ...)) end
+
+local config = {
+    dtb = {
+        entrypoint = "while true; do rollup accept; done",
+        init = 'echo "\
+         .\
+        / \\\\\
+      /    \\\\\
+\\\\---/---\\\\  /----\\\\\
+ \\\\       X       \\\\\
+  \\\\----/  \\\\---/---\\\\\
+       \\\\    / CARTESI\
+        \\\\ /   MACHINE\
+         \'\
+"\
+busybox mkdir -p /run/drive-label && echo "root" > /run/drive-label/pmem0\
+',
+    },
+    flash_drive = {
+        {
+            backing_store = {
+                data_filename = "rootfs.ext2",
+            },
+            start = 0x80000000000000,
+        },
+    },
+    ram = {
+        backing_store = {
+            data_filename = "linux.bin",
+        },
+        length = 0x8000000,
+    },
+    virtio = {},
+}
+
+local INPUT_COUNT = 10
+local LOG2_MCYCLE_PERIOD = 15
+local MCYCLE_PERIOD = 1 << LOG2_MCYCLE_PERIOD
+
+local function encode_input(index)
+    local chain_id = "0x0000000000000000000000000000000000000001"
+    local app_contract = "0x0000000000000000000000000000000000000002"
+    local msg_sender = "0x0000000000000000000000000000000000000003"
+    local block_number = 4
+    local block_timestamp = 5
+    local prev_randao = 6
+    local payload = string.rep("Hello world!", index + 1)
+    local advance_sig = [[
+        EvmAdvance(
+            uint256 chainId,
+            address appContract,
+            address msgSender,
+            uint256 blockNumber,
+            uint256 blockTimestamp,
+            uint256 prevRandao,
+            uint256 index,
+            bytes payload
+        )
+    ]]
+    local args = {
+        chainId = chain_id,
+        appContract = app_contract,
+        msgSender = msg_sender,
+        blockNumber = block_number,
+        blockTimestamp = block_timestamp,
+        prevRandao = prev_randao,
+        index = index,
+        payload = calldata.raw(payload),
+    }
+    return assert(calldata.encode_calldata(advance_sig, args))
+end
+
+local failed = cartesi.BREAK_REASON_FAILED
+local halted = cartesi.BREAK_REASON_HALTED
+local yielded_manually = cartesi.BREAK_REASON_YIELDED_MANUALLY
+--local yielded_softly = cartesi.BREAK_REASON_YIELDED_SOFTLY
+--local yielded_automatically = cartesi.BREAK_REASON_YIELDED_AUTOMATICALLY
+--local reached_target_mcycle = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE
+
+local function create_machine()
+    --local machine = arg[1] and assert(jsonrpc.connect_server(arg[1])) or assert(jsonrpc.spawn_server("127.0.0.1:0"))
+    local machine = cartesi.machine
+    -- create from template
+    local m = machine(config)
+    -- run until first yield
+    local break_reason = m:run(math.maxinteger)
+    assert(break_reason == yielded_manually, "machine did not yield manually")
+    return m, break_reason
+end
+
+local function get_root_hashes_directly(input_count)
+    local inputs = {}
+    local hashes
+    local m, break_reason = create_machine()
+    local mcycle = m:read_reg("mcycle")
+    local target_mcycle
+    local index = 0
+    while index < input_count and break_reason ~= halted and break_reason ~= failed do
+        if break_reason == yielded_manually then
+            if hashes then tinsert(inputs, hashes) end
+            hashes = {}
+            local input = encode_input(index)
+            m:send_cmio_response(cartesi.CMIO_YIELD_REASON_ADVANCE_STATE, input)
+            index = index + 1
+            target_mcycle = mcycle + MCYCLE_PERIOD
+        end
+        break_reason = m:run(target_mcycle)
+        mcycle = m:read_reg("mcycle")
+        if mcycle == target_mcycle then
+            target_mcycle = mcycle + MCYCLE_PERIOD
+            tinsert(hashes, m:get_root_hash())
+        end
+    end
+    print("Halted")
+    return inputs
+end
+
+--[[
+local break_reason_name = {
+    [halted] = "halted",
+    [failed] = "failed",
+    [yielded_manually] = "yielded_manually",
+    [yielded_automatically] = "yielded_automatically",
+    [yielded_softly] = "yielded_softly",
+    [reached_target_mcycle] = "reached_target_mcycle",
+}
+]]
+
+local function get_root_hashes_with_collect(input_count)
+    local inputs = {}
+    local hashes
+    local m, break_reason = create_machine()
+    local mcycle_phase
+    local index = 0
+    local period_count = 7
+    while index < input_count and break_reason ~= halted and break_reason ~= failed do
+        if break_reason == yielded_manually then
+            if hashes then tinsert(inputs, hashes) end
+            hashes = {}
+            mcycle_phase = 0
+            local input = encode_input(index)
+            m:send_cmio_response(cartesi.CMIO_YIELD_REASON_ADVANCE_STATE, input)
+            index = index + 1
+        end
+        local collected = m:collect_mcycle_root_hashes(mcycle_phase, MCYCLE_PERIOD, period_count)
+        break_reason, mcycle_phase = collected.break_reason, collected.mcycle_phase
+        tappend(hashes, collected.hashes)
+    end
+    print("Halted")
+    return inputs
+end
+
+collectgarbage()
+collectgarbage()
+
+local t = socket.gettime()
+local inputs_collected = get_root_hashes_with_collect(INPUT_COUNT)
+local collect_time = socket.gettime() - t
+
+collectgarbage()
+collectgarbage()
+
+t = socket.gettime()
+local inputs_directly = get_root_hashes_directly(INPUT_COUNT)
+local directly_time = socket.gettime() - t
+
+stderr("collect in %.2gs, direct in %.2g", collect_time, directly_time)
+
+if #inputs_collected ~= #inputs_directly then
+    errorf("number of inputs do not match (%u vs %u)", #inputs_collected, #inputs_directly)
+end
+for i, c in ipairs(inputs_collected) do
+    local d = inputs_directly[i]
+    if #c ~= #d then errorf("number of hashes in input %u do not match (%u vs %u)", i - 1, #c, #d) end
+    for j, hc in ipairs(c) do
+        local hd = d[j]
+        if hc ~= hd then
+            local hex_hc = calldata.encode_hex(hc:sub(1, 8))
+            local hex_hd = calldata.encode_hex(hd:sub(1, 8))
+            errorf("hashes %u of input %u do not match (%s vs %s)", i - 1, j - 1, hex_hc, hex_hd)
+        end
+    end
+end
diff --git a/src/uarch-cycle-root-hashes.h b/src/uarch-cycle-root-hashes.h
new file mode 100644
index 000000000..edf23f86f
--- /dev/null
+++ b/src/uarch-cycle-root-hashes.h
@@ -0,0 +1,36 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef UARCH_CYCLE_ROOT_HASHES_H
+#define UARCH_CYCLE_ROOT_HASHES_H
+
+#include <cstdint>
+
+#include "interpret.h"
+#include "machine-hash.h"
+
+namespace cartesi {
+
+/// \brief Collected uarch cycle root hashes
+struct uarch_cycle_root_hashes {
+    machine_hashes hashes;                   ///< Root hashes after each uarch cycle
+    std::vector<uint64_t> reset_indices;     ///< Indices into hashes[] after each uarch reset
+    interpreter_break_reason break_reason{}; ///< Reason why function returned
+};
+
+} // namespace cartesi
+
+#endif
diff --git a/src/uarch-interpret.cpp b/src/uarch-interpret.cpp
index 8f9e77308..3ccf7dcba 100644
--- a/src/uarch-interpret.cpp
+++ b/src/uarch-interpret.cpp
@@ -18,15 +18,14 @@
 
 #include <cstdint>
 
+#include "collect-uarch-cycle-hashes-state-access.h"
 #include "uarch-state-access.h"
 #include "uarch-step.h"
 
 namespace cartesi {
 
-// Declaration of explicit instantiation in module uarch-step.cpp
-extern template UArchStepStatus uarch_step(const uarch_state_access a);
-
-uarch_interpreter_break_reason uarch_interpret(const uarch_state_access a, uint64_t cycle_end) {
+template <typename STATE_ACCESS>
+uarch_interpreter_break_reason uarch_interpret(const STATE_ACCESS a, uint64_t cycle_end) {
     uint64_t cycle = a.read_uarch_cycle();
     if (cycle_end < cycle) {
         throw std::invalid_argument{"uarch_cycle is past"};
@@ -49,4 +48,11 @@ uarch_interpreter_break_reason uarch_interpret(const uarch_state_access a, uint6
     return uarch_interpreter_break_reason::reached_target_cycle;
 }
 
+// Explicit instantiation for uarch_state_access
+template uarch_interpreter_break_reason uarch_interpret(const uarch_state_access a, uint64_t uarch_cycle_end);
+
+// Explicit instantiation for collect_uarch_cycle_hashes_state_access
+template uarch_interpreter_break_reason uarch_interpret(const collect_uarch_cycle_hashes_state_access a,
+    uint64_t uarch_cycle_end);
+
 } // namespace cartesi
diff --git a/src/uarch-interpret.h b/src/uarch-interpret.h
index 03abd1050..5e835c993 100644
--- a/src/uarch-interpret.h
+++ b/src/uarch-interpret.h
@@ -21,13 +21,20 @@
 
 namespace cartesi {
 
-// Forward declaration
-class uarch_state_access;
-
 enum class uarch_interpreter_break_reason : int { reached_target_cycle, uarch_halted };
 
 // Run the microarchitecture interpreter until cycle hits a target or a fixed point is reached
-uarch_interpreter_break_reason uarch_interpret(uarch_state_access a, uint64_t uarch_cycle_end);
+template <typename STATE_ACCESS>
+uarch_interpreter_break_reason uarch_interpret(STATE_ACCESS a, uint64_t uarch_cycle_end);
+
+// Forward declarations
+class uarch_state_access;
+class collect_uarch_cycle_hashes_state_access;
+
+// Declaration of explicit instantiations in module uarch-interpret.cpp
+extern template uarch_interpreter_break_reason uarch_interpret(uarch_state_access a, uint64_t uarch_cycle_end);
+extern template uarch_interpreter_break_reason uarch_interpret(collect_uarch_cycle_hashes_state_access a,
+    uint64_t uarch_cycle_end);
 
 } // namespace cartesi
 
diff --git a/src/uarch-step.cpp b/src/uarch-step.cpp
index 8243a2dc6..28636bab1 100644
--- a/src/uarch-step.cpp
+++ b/src/uarch-step.cpp
@@ -21,6 +21,7 @@
 
 #include "uarch-step.h"
 
+#include "collect-uarch-cycle-hashes-state-access.h"
 #include "uarch-record-state-access.h"
 #include "uarch-replay-state-access.h"
 #include "uarch-state-access.h"
@@ -1120,5 +1121,8 @@ template UArchStepStatus uarch_step(const uarch_record_state_access a);
 // Explicit instantiation for uarch_replay_state_access
 template UArchStepStatus uarch_step(const uarch_replay_state_access a);
 
+// Explicit instantiation for uarch_replay_state_access
+template UArchStepStatus uarch_step(const collect_uarch_cycle_hashes_state_access a);
+
 } // namespace cartesi
 // NOLINTEND(google-readability-casting,misc-const-correctness,modernize-use-auto,hicpp-use-auto)
diff --git a/src/uarch-step.h b/src/uarch-step.h
index 45a82d3fb..55d9d5c2c 100644
--- a/src/uarch-step.h
+++ b/src/uarch-step.h
@@ -33,6 +33,18 @@ enum class UArchStepStatus : int {
 template <typename STATE_ACCESS>
 UArchStepStatus uarch_step(STATE_ACCESS a);
 
+// Forward declarations
+class uarch_state_access;
+class collect_uarch_cycle_hashes_state_access;
+class uarch_record_state_access;
+class uarch_replay_state_access;
+
+// Declaration of explicit instantiations in module uarch-step.cpp
+extern template UArchStepStatus uarch_step(uarch_state_access a);
+extern template UArchStepStatus uarch_step(collect_uarch_cycle_hashes_state_access a);
+extern template UArchStepStatus uarch_step(uarch_record_state_access a);
+extern template UArchStepStatus uarch_step(uarch_replay_state_access a);
+
 } // namespace cartesi
 
 #endif

From 2787498222f291cec78c6f148a847388940ece8e Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Mon, 11 Aug 2025 18:15:11 -0300
Subject: [PATCH 44/82] fix: fix typos and warnings with recent clang

---
 .clang-tidy                               | 14 ++--------
 .gitignore                                |  1 +
 .typos.toml                               |  1 +
 src/address-range.h                       |  4 +--
 src/cartesi/calldata.lua                  |  2 +-
 src/circular-buffer.h                     |  6 ++++-
 src/clint-address-range.cpp               |  1 +
 src/compiler-defines.h                    |  6 -----
 src/dense-hash-tree.h                     |  3 +++
 src/dirty-page-tree.h                     |  2 ++
 src/fdt-builder.h                         |  1 +
 src/i-dirty-page-tree.h                   |  4 +--
 src/is-pristine.h                         |  1 +
 src/jsonrpc-discover.json                 | 16 +++--------
 src/jsonrpc-fork-result.h                 |  3 +++
 src/jsonrpc-remote-machine.cpp            |  2 +-
 src/machine-c-api.cpp                     |  8 +++---
 src/machine-c-api.h                       |  2 +-
 src/machine-reg.h                         |  1 +
 src/machine.cpp                           |  7 +++--
 src/os-mmap.cpp                           |  4 ++-
 src/poor-type-name.h                      |  2 ++
 src/record-step-state-access.h            |  2 +-
 src/replay-send-cmio-state-access.h       |  1 +
 src/replay-step-state-access.h            |  2 ++
 src/riscv-constants.h                     |  2 +-
 src/test-calldata.lua                     | 33 ++++++++++++++---------
 src/uarch-replay-state-access.h           |  2 ++
 src/virtio-net-user-address-range.cpp     |  2 +-
 tests/lua/machine-bind.lua                |  7 +++--
 tests/misc/test-machine-c-api.cpp         | 31 ++++++++++++---------
 tests/misc/test-utils.h                   |  9 +++----
 tools/gen-interpret-jump-table.lua        |  1 +
 uarch/Makefile                            | 12 +++++----
 uarch/compute-uarch-pristine-hash.cpp     |  7 +++--
 uarch/machine-uarch-bridge-state-access.h | 15 +++++++----
 uarch/uarch-run.cpp                       |  8 +++---
 uarch/uarch-runtime.cpp                   |  6 ++---
 uarch/uarch-runtime.h                     |  4 +--
 uarch/uarch-strict-aliasing.h             |  2 ++
 40 files changed, 131 insertions(+), 106 deletions(-)

diff --git a/.clang-tidy b/.clang-tidy
index fdcbda1dd..f676fd523 100644
--- a/.clang-tidy
+++ b/.clang-tidy
@@ -34,6 +34,7 @@ Checks: >-
   -modernize-use-trailing-return-type,
   -modernize-avoid-c-arrays,
   -modernize-use-ranges,
+  -modernize-use-integer-sign-comparison,
   performance*,
   -performance-enum-size,
   portability*,
@@ -44,15 +45,4 @@ Checks: >-
   -readability-enum-initial-value,
   -readability-static-accessed-through-instance,
 WarningsAsErrors: >-
-  boost*,
-  bugprone*,
-  cert*,
-  clang-analyzer*,
-  cppcoreguidelines*,
-  google*,
-  hicpp*,
-  misc*,
-  modernize*,
-  performance*,
-  portability*,
-  readability*,
+  *
diff --git a/.gitignore b/.gitignore
index 80b58149a..f77446c75 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,6 +7,7 @@
 *.lib
 *.wasm
 *.TODO
+*.tmp
 
 build
 pkg
diff --git a/.typos.toml b/.typos.toml
index ccb29e1e3..66118197f 100644
--- a/.typos.toml
+++ b/.typos.toml
@@ -9,3 +9,4 @@ stap = "stap"
 wronly = "wronly"
 optin = "optin"
 sxl = "sxl"
+nd = "nd"
diff --git a/src/address-range.h b/src/address-range.h
index 0865f0617..2750ba23e 100644
--- a/src/address-range.h
+++ b/src/address-range.h
@@ -352,7 +352,7 @@ class address_range {
     }
 
 #ifndef MICROARCHITECTURE
-    // Defaul implemenation returns always dirty tree
+    // Default implemenationt returns always dirty tree
     virtual const i_dirty_page_tree &do_get_dirty_page_tree() const noexcept {
         const static empty_dirty_page_tree no_dirty{};
         return no_dirty;
@@ -363,7 +363,7 @@ class address_range {
         return const_cast<i_dirty_page_tree &>(std::as_const(*this).do_get_dirty_page_tree());
     }
 
-    // Defaul implemenation returns no hashes
+    // Default implemenationt returns no hashes
     virtual const i_dense_hash_tree &do_get_dense_hash_tree() const noexcept {
         const static empty_dense_hash_tree no_hashes{};
         return no_hashes;
diff --git a/src/cartesi/calldata.lua b/src/cartesi/calldata.lua
index 7f58f40cb..f2245d3f8 100644
--- a/src/cartesi/calldata.lua
+++ b/src/cartesi/calldata.lua
@@ -38,7 +38,7 @@ end
 -- Throws formatted error
 local function errorf(fmt, ...) error(string.format(fmt, ...)) end
 
--- Converts 'value' (a bint) to a its 256-bit big-endian represantation as a string
+-- Converts 'value' (a bint) to a its 256-bit big-endian representation as a string
 local function tobe(value) return bint.tobe(value):sub(bint_extra / 8 + 1) end
 
 -- Converts 'hex' (an hex-encoded sequence of bytes) to the corresponding decoded string
diff --git a/src/circular-buffer.h b/src/circular-buffer.h
index 6cffb5755..d5e8021c6 100644
--- a/src/circular-buffer.h
+++ b/src/circular-buffer.h
@@ -23,12 +23,16 @@
 #include <concepts>
 #include <cstddef>
 #include <iterator>
+#include <limits>
 #include <span>
 #include <utility>
+#include <variant>
+#include <vector>
 
 #include <boost/container/static_vector.hpp>
 #include <boost/iterator/iterator_adaptor.hpp>
 
+#include "concepts.h"
 #include "meta.h"
 
 namespace cartesi {
@@ -36,7 +40,7 @@ namespace cartesi {
 /// \brief Circular buffer container.
 /// \tparam T type of entry in container.
 /// \tparam N maximum number of entries container can hold.
-/// \details The circular buffer contianer with a fixed number of entries.
+/// \details The circular buffer container with a fixed number of entries.
 /// The container that be statically allocated, when \p N is passed as a template argument at compile time.
 /// It can be dynamically allocated, with the size is chosen in the constructor at runtime.
 /// \p T does not need to be default-constructible.
diff --git a/src/clint-address-range.cpp b/src/clint-address-range.cpp
index b8992f5c2..9665cd7f5 100644
--- a/src/clint-address-range.cpp
+++ b/src/clint-address-range.cpp
@@ -47,6 +47,7 @@ static constexpr uint64_t base(uint64_t v) {
 }
 
 static bool clint_read_msip(i_device_state_access *a, uint64_t *val, int log2_size) {
+    // NOLINTNEXTLINE(misc-redundant-expression)
     static_assert(__BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__, "code assumes little-endian byte ordering");
     static_assert(base(clint_msip0_rel_addr) != base(clint_mtimecmp_rel_addr) &&
             base(clint_mtimecmp_rel_addr) != base(clint_mtime_rel_addr) &&
diff --git a/src/compiler-defines.h b/src/compiler-defines.h
index b8dda2894..0fb7eb004 100644
--- a/src/compiler-defines.h
+++ b/src/compiler-defines.h
@@ -40,10 +40,4 @@
 
 #define PACKED __attribute__((packed))
 
-#if defined(__GNUC__) && !defined(__clang__)
-#define FORCE_OPTIMIZE_O3 __attribute__((optimize("-O3")))
-#else
-#define FORCE_OPTIMIZE_O3
-#endif
-
 #endif
diff --git a/src/dense-hash-tree.h b/src/dense-hash-tree.h
index 1c0bae7a1..5c7f490fa 100644
--- a/src/dense-hash-tree.h
+++ b/src/dense-hash-tree.h
@@ -17,8 +17,11 @@
 #ifndef DENSE_HASH_TREE_H
 #define DENSE_HASH_TREE_H
 
+#include <limits>
+#include <stdexcept>
 #include <vector>
 
+#include "address-range-constants.h"
 #include "hash-tree-constants.h"
 #include "i-dense-hash-tree.h"
 #include "machine-hash.h"
diff --git a/src/dirty-page-tree.h b/src/dirty-page-tree.h
index d79bbc1a3..a79e1f6dd 100644
--- a/src/dirty-page-tree.h
+++ b/src/dirty-page-tree.h
@@ -21,12 +21,14 @@
 /// \brief Dirty map as a complete tree
 
 #include <algorithm>
+#include <cassert>
 #include <concepts>
 #include <cstdint>
 #include <iostream>
 #include <iterator>
 #include <ranges>
 #include <stdexcept>
+#include <vector>
 
 #include "i-dirty-page-tree.h"
 #include "ranges.h"
diff --git a/src/fdt-builder.h b/src/fdt-builder.h
index 4f8a2d164..3b10d22ce 100644
--- a/src/fdt-builder.h
+++ b/src/fdt-builder.h
@@ -59,6 +59,7 @@ struct fdt_reserve_entry {
 };
 
 static inline uint32_t to_be32(uint32_t v) {
+    // NOLINTNEXTLINE(misc-redundant-expression)
     static_assert(__BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__, "code assumes little-endian byte ordering");
     return __builtin_bswap32(v);
 }
diff --git a/src/i-dirty-page-tree.h b/src/i-dirty-page-tree.h
index d54f78bd0..2d9edb8c7 100644
--- a/src/i-dirty-page-tree.h
+++ b/src/i-dirty-page-tree.h
@@ -42,7 +42,7 @@ namespace cartesi {
 /// The the root is at position 1.
 /// As usual, the left and right children of the node at pos are 2*position and (2*posision+1), respectively.
 /// The tree maintains the following invariants:
-///   1) When a node is dirty, all parent nodes in the path torwards the root are also dirty;
+///   1) When a node is dirty, all parent nodes in the path towards the root are also dirty;
 ///   2) A node is clean only if all its children nodes are also clean.
 /// The leaves (page nodes) are at level 0, and the root is at level log2_leaf_count.
 /// The number level_count of levels in the tree is ceil(log2_page_count)+1.
@@ -158,7 +158,7 @@ class i_dirty_page_tree {
     };
 
     // -----
-    // Private methods that must be overriden by derived class
+    // Private methods that must be overridden by derived class
     // These will only ever be called by the base class, and always with valid arguments
     // -----
 
diff --git a/src/is-pristine.h b/src/is-pristine.h
index f371399ab..0f0bf3f82 100644
--- a/src/is-pristine.h
+++ b/src/is-pristine.h
@@ -21,6 +21,7 @@
 #include <cstdint>
 #include <ranges>
 
+#include "concepts.h"
 #include "meta.h"
 
 namespace cartesi {
diff --git a/src/jsonrpc-discover.json b/src/jsonrpc-discover.json
index af27763da..37611ca58 100644
--- a/src/jsonrpc-discover.json
+++ b/src/jsonrpc-discover.json
@@ -447,13 +447,13 @@
           "description": "Whether to clear the stats after retrieving them",
           "required": true,
           "schema": {
-              "type": "boolean"
+            "type": "boolean"
           }
         }
       ],
       "result": {
         "name": "stats",
-        "description": "Statistics for the hash tre",
+        "description": "Statistics for the hash tree",
         "schema": {
           "$ref": "#/components/schemas/HashTreeStats"
         }
@@ -2220,11 +2220,7 @@
             "$ref": "#/components/schemas/InterpreterBreakReason"
           }
         },
-        "required": [
-          "hashes",
-          "mcycle_phase",
-          "break_reason"
-        ]
+        "required": ["hashes", "mcycle_phase", "break_reason"]
       },
       "UarchCycleRootHashes": {
         "title": "UarchCycleRootHashes",
@@ -2240,11 +2236,7 @@
             "$ref": "#/components/schemas/InterpreterBreakReason"
           }
         },
-        "required": [
-          "hashes",
-          "reset_indices",
-          "break_reason"
-        ]
+        "required": ["hashes", "reset_indices", "break_reason"]
       }
     }
   }
diff --git a/src/jsonrpc-fork-result.h b/src/jsonrpc-fork-result.h
index 26a5ba73c..504ba6604 100644
--- a/src/jsonrpc-fork-result.h
+++ b/src/jsonrpc-fork-result.h
@@ -17,6 +17,9 @@
 #ifndef JSONRPC_FORK_RESULT_H
 #define JSONRPC_FORK_RESULT_H
 
+#include <cstdint>
+#include <string>
+
 namespace cartesi {
 
 struct fork_result final {
diff --git a/src/jsonrpc-remote-machine.cpp b/src/jsonrpc-remote-machine.cpp
index 69d490785..a194716b3 100644
--- a/src/jsonrpc-remote-machine.cpp
+++ b/src/jsonrpc-remote-machine.cpp
@@ -461,7 +461,7 @@ static json jsonrpc_response_invalid_params(const json &j, const std::string &me
 static void jsonrpc_check_allowed_fields(const json &j, const std::unordered_set<std::string> &keys,
     const std::string &base = "params/") {
     for (const auto &[key, val] : j.items()) {
-        if (keys.find(key) == keys.end()) {
+        if (!keys.contains(key)) {
             // NOLINTNEXTLINE(performance-inefficient-string-concatenation)
             throw std::invalid_argument("unexpected field \"/"s + base + key + "\""s);
         }
diff --git a/src/machine-c-api.cpp b/src/machine-c-api.cpp
index 3a2fa4382..23bc9a6b5 100644
--- a/src/machine-c-api.cpp
+++ b/src/machine-c-api.cpp
@@ -907,17 +907,17 @@ cm_error cm_read_word(const cm_machine *m, uint64_t address, uint64_t *val) try
     return cm_result_failure();
 }
 
-cm_error cm_read_memory(const cm_machine *m, uint64_t address, uint8_t *data, uint64_t length) try {
+cm_error cm_read_memory(const cm_machine *m, uint64_t paddr, uint8_t *data, uint64_t length) try {
     const auto *cpp_m = convert_from_c(m);
-    cpp_m->read_memory(address, data, length);
+    cpp_m->read_memory(paddr, data, length);
     return cm_result_success();
 } catch (...) {
     return cm_result_failure();
 }
 
-cm_error cm_write_memory(cm_machine *m, uint64_t address, const uint8_t *data, uint64_t length) try {
+cm_error cm_write_memory(cm_machine *m, uint64_t paddr, const uint8_t *data, uint64_t length) try {
     auto *cpp_m = convert_from_c(m);
-    cpp_m->write_memory(address, data, length);
+    cpp_m->write_memory(paddr, data, length);
     return cm_result_success();
 } catch (...) {
     return cm_result_failure();
diff --git a/src/machine-c-api.h b/src/machine-c-api.h
index ee779f9c7..b59d43a8a 100644
--- a/src/machine-c-api.h
+++ b/src/machine-c-api.h
@@ -622,7 +622,7 @@ CM_API cm_error cm_run(cm_machine *m, uint64_t mcycle_end, cm_break_reason *brea
 /// \returns 0 for success, non zero code for error.
 /// \detail The first hash added to \p result.hashes is the root hash after (\p mcycle_period - \p mcycle_phase)
 /// machine cycles (if the function managed to get that far before returning).
-CM_API cm_error cm_collect_mcycle_root_hashes(cm_machine *m, uint64_t mcycle_countdown, uint64_t mcycle_period,
+CM_API cm_error cm_collect_mcycle_root_hashes(cm_machine *m, uint64_t mcycle_phase, uint64_t mcycle_period,
     uint64_t period_count, const char **result);
 
 /// \brief Runs the machine microarchitecture until CM_REG_UARCH_CYCLE reaches uarch_cycle_end or it halts.
diff --git a/src/machine-reg.h b/src/machine-reg.h
index 277b69bac..277ef2071 100644
--- a/src/machine-reg.h
+++ b/src/machine-reg.h
@@ -17,6 +17,7 @@
 #ifndef MACHINE_REG_H
 #define MACHINE_REG_H
 
+#include "shadow-registers.h"
 #include "shadow-uarch-state.h"
 
 /// \file
diff --git a/src/machine.cpp b/src/machine.cpp
index b7cb9374b..6faad5e5a 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -272,8 +272,11 @@ machine::machine(machine_config c, machine_runtime_config r) :
     m_r{std::move(r)}, // NOLINT(hicpp-move-const-arg,performance-move-const-arg)
     m_ars{m_c},
     m_ht{m_c.hash_tree, m_r.concurrency.update_hash_tree, m_ars},
-    m_s{std::bit_cast<processor_state *>(m_ars.find(AR_SHADOW_STATE_START, AR_SHADOW_STATE_LENGTH).get_host_memory())},
-    m_us{std::bit_cast<uarch_processor_state *>(
+    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+    m_s{reinterpret_cast<processor_state *>(
+        m_ars.find(AR_SHADOW_STATE_START, AR_SHADOW_STATE_LENGTH).get_host_memory())},
+    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+    m_us{reinterpret_cast<uarch_processor_state *>(
         m_ars.find(AR_SHADOW_UARCH_STATE_START, AR_SHADOW_UARCH_STATE_LENGTH).get_host_memory())} {
     init_processor(m_c.processor, m_r);
     init_uarch_processor(m_c.uarch.processor);
diff --git a/src/os-mmap.cpp b/src/os-mmap.cpp
index a49ec013e..74bb92b04 100644
--- a/src/os-mmap.cpp
+++ b/src/os-mmap.cpp
@@ -231,7 +231,9 @@ os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string
                 throw std::system_error{errno, std::generic_category(),
                     "possible non zero partial page when mapping backing file '"s + backing_filename + "' to memory"s};
             }
-            std::memset(std::bit_cast<uint8_t *>(backing_host_memory) + backing_file_length, 0, partial_page_remaining);
+            // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+            std::memset(reinterpret_cast<uint8_t *>(backing_host_memory) + backing_file_length, 0,
+                partial_page_remaining);
         }
     } else { // Can perform a single mmap()
         host_memory = mmap(nullptr, length, mprot, mflags, backing_fd, 0);
diff --git a/src/poor-type-name.h b/src/poor-type-name.h
index 4940b7737..9f743d26e 100644
--- a/src/poor-type-name.h
+++ b/src/poor-type-name.h
@@ -17,6 +17,8 @@
 #ifndef POOR_TYPE_NAME_H
 #define POOR_TYPE_NAME_H
 
+#include <cstdint>
+
 namespace cartesi {
 
 //?DD Poor man's rtti that works in microarchitecture
diff --git a/src/record-step-state-access.h b/src/record-step-state-access.h
index c03b90708..814a703da 100644
--- a/src/record-step-state-access.h
+++ b/src/record-step-state-access.h
@@ -129,7 +129,7 @@ class record_step_state_access :
     /// \param address address of the page
     void touch_page(uint64_t address) const {
         auto page = address & ~PAGE_OFFSET_MASK;
-        if (m_context.touched_pages.find(page) != m_context.touched_pages.end()) {
+        if (m_context.touched_pages.contains(page)) {
             return; // already saved
         }
         auto [it, _] = m_context.touched_pages.emplace(page, page_data_type());
diff --git a/src/replay-send-cmio-state-access.h b/src/replay-send-cmio-state-access.h
index ffa8ae46b..95b383345 100644
--- a/src/replay-send-cmio-state-access.h
+++ b/src/replay-send-cmio-state-access.h
@@ -32,6 +32,7 @@
 #include "hash-tree.h"
 #include "i-hasher.h"
 #include "i-state-access.h"
+#include "machine-reg.h"
 #include "meta.h"
 #include "riscv-constants.h"
 #include "shadow-registers.h"
diff --git a/src/replay-step-state-access.h b/src/replay-step-state-access.h
index e8219924c..59a6d373d 100644
--- a/src/replay-step-state-access.h
+++ b/src/replay-step-state-access.h
@@ -17,6 +17,7 @@
 #ifndef REPLAY_STEP_STATE_ACCESS_H
 #define REPLAY_STEP_STATE_ACCESS_H
 
+#include <algorithm>
 #include <cassert>
 #include <cstdlib>
 #include <optional>
@@ -27,6 +28,7 @@
 #include "i-accept-scoped-notes.h"
 #include "i-prefer-shadow-state.h"
 #include "i-state-access.h"
+#include "machine-reg.h"
 #include "mock-address-range.h"
 #include "pmas.h"
 #include "replay-step-state-access-interop.h"
diff --git a/src/riscv-constants.h b/src/riscv-constants.h
index 1c7644585..2245c7146 100644
--- a/src/riscv-constants.h
+++ b/src/riscv-constants.h
@@ -125,7 +125,7 @@ enum MISA_shifts {
     MISA_EXT_U_SHIFT = ('U' - 'A'),
     MISA_EXT_I_SHIFT = ('I' - 'A'),
     MISA_EXT_M_SHIFT = ('M' - 'A'),
-    MISA_EXT_A_SHIFT = ('A' - 'A'),
+    MISA_EXT_A_SHIFT = ('A' - 'A'), // NOLINT(misc-redundant-expression)
     MISA_EXT_F_SHIFT = ('F' - 'A'),
     MISA_EXT_D_SHIFT = ('D' - 'A'),
     MISA_EXT_C_SHIFT = ('C' - 'A'),
diff --git a/src/test-calldata.lua b/src/test-calldata.lua
index 07d7ffc12..a1c7fbf6f 100644
--- a/src/test-calldata.lua
+++ b/src/test-calldata.lua
@@ -91,7 +91,7 @@ end
 local function check_parse_type_spec_error(s, expected_err)
     local ret, err = pcall(calldata.parse_type_spec, s)
     assert(not ret, "expected error")
-    assert(is_suffix(expected_err, err), string.format("expected sufix '%s' in '%s'", expected_err, tostring(err)))
+    assert(is_suffix(expected_err, err), string.format("expected suffix '%s' in '%s'", expected_err, tostring(err)))
 end
 
 local function strdiff(a, b)
@@ -124,13 +124,13 @@ end
 local function check_encode_calldata_hex_error(s, args, expected_err)
     local ret, err = pcall(calldata.encode_calldata_hex, s, args)
     assert(not ret, "expected error")
-    assert(is_suffix(expected_err, err), string.format("expected sufix '%s' in '%s'", expected_err, tostring(err)))
+    assert(is_suffix(expected_err, err), string.format("expected suffix '%s' in '%s'", expected_err, tostring(err)))
 end
 
 local function check_decode_calldata_hex_error(s, cd, expected_err)
     local ret, err = pcall(calldata.decode_calldata_hex, s, cd)
     assert(not ret, "expected error")
-    assert(is_suffix(expected_err, err), string.format("expected sufix '%s' in '%s'", expected_err, tostring(err)))
+    assert(is_suffix(expected_err, err), string.format("expected suffix '%s' in '%s'", expected_err, tostring(err)))
 end
 
 local function check_encode_hex(s, expected_hex)
@@ -159,23 +159,26 @@ end
 local function check_decode_hex_error(s, expected_err)
     local ret, err = calldata.decode_hex(s)
     assert(not ret, "expected error")
-    assert(is_suffix(expected_err, err), string.format("expected sufix '%s' in '%s'", expected_err, tostring(err)))
+    assert(is_suffix(expected_err, err), string.format("expected suffix '%s' in '%s'", expected_err, tostring(err)))
 end
 
+-- luacheck: push no max line length
+
 -- check hex encoding/decoding
 check_encode_hex("", "0x")
 check_encode_hex("\x00", "0x00")
 check_encode_hex("\x00\x01", "0x0001")
 check_encode_hex("\x00\x01\x02", "0x000102")
 check_encode_hex("\x00\x01\x02\x03", "0x00010203")
-local all = {}
-local all_hex = { "0x" }
-for i = 0, 255 do
-    all[i + 1] = string.char(i)
-    all_hex[i + 2] = string.format("%02x", i)
-end
-all = table.concat(all)
-all_hex = table.concat(all_hex)
+local all, all_hex = (function()
+    local all = {}
+    local all_hex = { "0x" }
+    for i = 0, 255 do
+        all[i + 1] = string.char(i)
+        all_hex[i + 2] = string.format("%02x", i)
+    end
+    return table.concat(all), table.concat(all_hex)
+end)()
 check_encode_hex(all, all_hex)
 check_decode_hex("0x", "")
 check_decode_hex("0X00", "\x00")
@@ -279,7 +282,7 @@ local function make_int(size, data_location, name)
     return { type_name = "int", size = size or 256, name = name, data_location = data_location }
 end
 local function make_uint(size, data_location, name)
-    return { type_name = "int", size = size or 256, name = name, data_location = data_location }
+    return { type_name = "uint", size = size or 256, name = name, data_location = data_location }
 end
 local function make_tuple(components, data_location, name)
     return { type_name = "tuple", components = components, name = name, data_location = data_location }
@@ -288,6 +291,7 @@ local empty_tuple = make_tuple({})
 local function make_address(data_location, name)
     return { type_name = "address", name = name, data_location = data_location }
 end
+
 local function make_bool(data_location, name) return { type_name = "bool", name = name, data_location = data_location } end
 
 -- check
@@ -299,6 +303,7 @@ check_parse_func_sig("_a()", { name = "_a", params = empty_tuple, returns = empt
 check_parse_func_sig("_a0()", { name = "_a0", params = empty_tuple, returns = empty_tuple })
 check_parse_func_sig("_a0a()", { name = "_a0a", params = empty_tuple, returns = empty_tuple })
 check_parse_func_sig("_(int)", { name = "_", params = make_tuple({ make_int() }), returns = empty_tuple })
+check_parse_func_sig("_(uint)", { name = "_", params = make_tuple({ make_uint() }), returns = empty_tuple })
 check_parse_func_sig(
     "_(int a)",
     { name = "_", params = make_tuple({ make_int(nil, nil, "a") }), returns = empty_tuple }
@@ -749,3 +754,5 @@ check_decode_calldata_hex_error(
 check_decode_calldata_hex_error("_(bytes7)", "0x155cf58f", "insufficient calldata for bytes7")
 
 check_decode_calldata_hex_error("_(bytes7)", "0x155cf5", "calldata too short (missing function selector)")
+
+-- luacheck: pop
diff --git a/src/uarch-replay-state-access.h b/src/uarch-replay-state-access.h
index faa72d128..ac58ce67e 100644
--- a/src/uarch-replay-state-access.h
+++ b/src/uarch-replay-state-access.h
@@ -33,6 +33,8 @@
 #include "i-hasher.h"
 #include "i-prefer-shadow-uarch-state.h"
 #include "i-uarch-state-access.h"
+#include "machine-reg.h"
+#include "machine.h"
 #include "meta.h"
 #include "shadow-tlb.h"
 #include "shadow-uarch-state.h"
diff --git a/src/virtio-net-user-address-range.cpp b/src/virtio-net-user-address-range.cpp
index ed3e9fc42..10ac01e86 100644
--- a/src/virtio-net-user-address-range.cpp
+++ b/src/virtio-net-user-address-range.cpp
@@ -160,7 +160,7 @@ static void slirp_timer_mod(void *timer_ptr, int64_t expire_timer_msec, void *op
     auto *carrier = reinterpret_cast<virtio_net_user_address_range *>(opaque);
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
     auto *timer = reinterpret_cast<slirp_timer *>(timer_ptr);
-    if ((timer != nullptr) && carrier->timers.find(timer) != carrier->timers.end()) {
+    if ((timer != nullptr) && carrier->timers.contains(timer)) {
         timer->expire_timer_msec = expire_timer_msec;
     }
 }
diff --git a/tests/lua/machine-bind.lua b/tests/lua/machine-bind.lua
index c37609128..f635265cd 100755
--- a/tests/lua/machine-bind.lua
+++ b/tests/lua/machine-bind.lua
@@ -718,7 +718,7 @@ do_test("machine step should pass verifications", function(machine)
 end)
 
 print("\n\ntesting step and verification")
-do_test("Step log must contain conssitent data hashes", function(machine)
+do_test("Step log must contain consistent data hashes", function(machine)
     local wrong_hash = string.rep("\0", cartesi.HASH_SIZE)
     local initial_hash = machine:get_root_hash()
     local log = machine:log_step_uarch()
@@ -1160,9 +1160,8 @@ do_test("uarch ecall putchar should print char to console", function()
                                  os.remove(uarch_ram_path)
                                  machine:run_uarch(3) -- run 3 instructions
                                  " 2>&1]]
-    local p = io.popen(lua_cmd .. lua_code)
-    local output = p:read(2000)
-    p:close()
+    local p <close> = assert(io.popen(lua_cmd .. lua_code))
+    local output = assert(p:read(2000))
     local expected_output = "X"
     print("Output of uarch ecall putchar:")
     print("--------------------------")
diff --git a/tests/misc/test-machine-c-api.cpp b/tests/misc/test-machine-c-api.cpp
index 0dcd116e4..62f7cbf5a 100644
--- a/tests/misc/test-machine-c-api.cpp
+++ b/tests/misc/test-machine-c-api.cpp
@@ -47,7 +47,7 @@
 #include "test-utils.h"
 #include "uarch-solidity-compat.h"
 
-// NOLINTBEGIN(cppcoreguidelines-avoid-do-while)
+// NOLINTBEGIN(cppcoreguidelines-avoid-do-while,cppcoreguidelines-non-private-member-variables-in-classes)
 
 // NOLINTNEXTLINE
 #define BOOST_AUTO_TEST_CASE_NOLINT(...) BOOST_AUTO_TEST_CASE(__VA_ARGS__)
@@ -74,7 +74,7 @@ class default_machine_fixture {
         _default_machine_config = config;
     }
 
-    ~default_machine_fixture() {}
+    ~default_machine_fixture() = default;
 
     default_machine_fixture(const default_machine_fixture &other) = delete;
     default_machine_fixture(default_machine_fixture &&other) noexcept = delete;
@@ -83,7 +83,7 @@ class default_machine_fixture {
 
 protected:
     cm_machine *_machine{};
-    std::string _default_machine_config{};
+    std::string _default_machine_config;
 };
 
 BOOST_FIXTURE_TEST_CASE_NOLINT(load_machine_unknown_dir_test, default_machine_fixture) {
@@ -119,12 +119,13 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(create_machine_default_machine_test, default_mach
 // NOLINTNEXTLINE(cppcoreguidelines-special-member-functions)
 class incomplete_machine_fixture : public default_machine_fixture {
 public:
-    incomplete_machine_fixture() : _machine_config{} {
+    incomplete_machine_fixture() {
         const char *config{};
         cm_get_default_config(nullptr, &config);
         _machine_config = nlohmann::json::parse(config);
         _machine_config["ram"]["length"] = 1 << 20;
     }
+    ~incomplete_machine_fixture() = default;
 
     incomplete_machine_fixture(const incomplete_machine_fixture &other) = delete;
     incomplete_machine_fixture(incomplete_machine_fixture &&other) noexcept = delete;
@@ -132,7 +133,7 @@ class incomplete_machine_fixture : public default_machine_fixture {
     incomplete_machine_fixture &operator=(incomplete_machine_fixture &&other) noexcept = delete;
 
 protected:
-    nlohmann::json _machine_config{};
+    nlohmann::json _machine_config;
 };
 
 BOOST_FIXTURE_TEST_CASE_NOLINT(create_machine_null_machine_test, incomplete_machine_fixture) {
@@ -166,6 +167,7 @@ class machine_flash_simple_fixture : public incomplete_machine_fixture {
                 {{"shared", false}, {"create", false}, {"truncate", false}, {"data_filename", ""}, {"dht_filename", ""},
                     {"dpt_filename", ""}}}}};
     }
+    ~machine_flash_simple_fixture() = default;
 
     machine_flash_simple_fixture(const machine_flash_simple_fixture &other) = delete;
     machine_flash_simple_fixture(machine_flash_simple_fixture &&other) noexcept = delete;
@@ -232,6 +234,11 @@ class serialized_machine_fixture : public ordinary_machine_fixture {
         std::filesystem::remove_all(_machine_config_path.string());
     }
 
+    serialized_machine_fixture(const serialized_machine_fixture &other) = delete;
+    serialized_machine_fixture(serialized_machine_fixture &&other) noexcept = delete;
+    serialized_machine_fixture &operator=(const serialized_machine_fixture &other) = delete;
+    serialized_machine_fixture &operator=(serialized_machine_fixture &&other) noexcept = delete;
+
 protected:
     std::filesystem::path _machine_config_path;
 
@@ -589,7 +596,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(read_write_memory_scattered_data, ordinary_machin
     // we are going to write data on a page junction:
     // one byte at the end of the third page and one byte
     // at the beginning of the fourth
-    uint64_t address = 0x80004000 - sizeof(write_value) / 2;
+    uint64_t address = 0x80004000 - (sizeof(write_value) / 2);
 
     std::array<uint8_t, sizeof(uint16_t)> write_data{};
     std::array<uint8_t, sizeof(uint16_t)> read_data{};
@@ -671,7 +678,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(read_write_virtual_memory_scattered_data, ordinar
     // we are going to write data on a page junction:
     // one byte at the end of the third page and one byte
     // at the beginning of the fourth
-    uint64_t address = 0x80004000 - sizeof(write_value) / 2;
+    uint64_t address = 0x80004000 - (sizeof(write_value) / 2);
 
     std::array<uint8_t, sizeof(uint16_t)> write_data{};
     std::array<uint8_t, sizeof(uint16_t)> read_data{};
@@ -849,7 +856,7 @@ class flash_drive_machine_fixture : public machine_flash_simple_fixture {
     flash_drive_machine_fixture &operator=(flash_drive_machine_fixture &&other) noexcept = delete;
 
 protected:
-    size_t _flash_size;
+    size_t _flash_size{};
     std::string _flash_file;
     std::string _flash_data;
     std::string _machine_dir_path;
@@ -1082,8 +1089,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(verify_step_uarch_log_null_log_test, default_mach
 
 class access_log_machine_fixture : public incomplete_machine_fixture {
 public:
-    access_log_machine_fixture() {
-        _log_type = CM_ACCESS_LOG_TYPE_ANNOTATIONS;
+    access_log_machine_fixture() : _log_type(CM_ACCESS_LOG_TYPE_ANNOTATIONS) {
         _machine_dir_path = (std::filesystem::temp_directory_path() / "661b6096c377cdc07756df488059f4407c8f4").string();
 
         uint32_t test_uarch_ram[] = {
@@ -1092,7 +1098,8 @@ class access_log_machine_fixture : public incomplete_machine_fixture {
             0x00000073,                                                            // ecall
         };
         std::ofstream of(_uarch_ram_path, std::ios::binary);
-        of.write(static_cast<char *>(static_cast<void *>(&test_uarch_ram)), sizeof(test_uarch_ram));
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        of.write(reinterpret_cast<char *>(&test_uarch_ram), sizeof(test_uarch_ram));
         of.close();
         _machine_config["uarch"]["ram"] = {{"backing_store", {{"data_filename", _uarch_ram_path}}}};
         const auto dumped_config = _machine_config.dump();
@@ -1685,4 +1692,4 @@ BOOST_AUTO_TEST_CASE_NOLINT(uarch_solidity_compatibility_layer) {
     BOOST_CHECK_EQUAL(int8ToUint64(int8(127)), 127);
     BOOST_CHECK_EQUAL(int8ToUint64(int8(-128)), 0xffffffffffffff80ULL);
 }
-// NOLINTEND(cppcoreguidelines-avoid-do-while)
+// NOLINTEND(cppcoreguidelines-avoid-do-while,cppcoreguidelines-non-private-member-variables-in-classes)
diff --git a/tests/misc/test-utils.h b/tests/misc/test-utils.h
index 31e869201..b07356125 100644
--- a/tests/misc/test-utils.h
+++ b/tests/misc/test-utils.h
@@ -37,7 +37,7 @@ static hash_type merkle_hash(cartesi::keccak_256_hasher &h, const std::string_vi
     if (log2_size > WORD_LOG2_SIZE) {
         --log2_size;
         auto half_size = data.size() / 2;
-        auto left = merkle_hash(h, std::string_view{data.data(), half_size}, log2_size);
+        auto left = merkle_hash(h, std::string_view{data.data() + 0, half_size}, log2_size);
         auto right = merkle_hash(h, std::string_view{data.data() + half_size, half_size}, log2_size);
         get_concat_hash(h, left, right, result);
     } else {
@@ -68,13 +68,12 @@ static hash_type merkle_hash(const std::string_view &data, int log2_size) {
 static hash_type calculate_proof_root_hash(const cartesi::hash_tree_proof &proof) {
     hash_type hash;
     memcpy(hash.data(), proof.get_target_hash().data(), sizeof(cm_hash));
-    for (int log2_size = static_cast<int>(proof.get_log2_target_size());
-        log2_size < static_cast<int>(proof.get_log2_root_size()); ++log2_size) {
+    for (int log2_size = proof.get_log2_target_size(); log2_size < proof.get_log2_root_size(); ++log2_size) {
         cartesi::keccak_256_hasher h;
         auto bit = (proof.get_target_address() & (UINT64_C(1) << log2_size));
         hash_type first;
         hash_type second;
-        if (bit) {
+        if (bit != 0) {
             memcpy(first.data(), proof.get_sibling_hashes()[log2_size - proof.get_log2_target_size()].data(),
                 sizeof(cm_hash));
             second = hash;
@@ -98,7 +97,7 @@ static hash_type calculate_emulator_hash(cm_machine *machine) {
     }
     const auto mrds = cartesi::from_json<cartesi::address_range_descriptions>(ranges_jsonstr, "memory_ranges");
     uint64_t last = 0;
-    for (auto m : mrds) {
+    for (const auto &m : mrds) {
         tree.pad_back((m.start - last) >> detail::MERKLE_PAGE_LOG2_SIZE);
         auto end = m.start + m.length;
         for (uint64_t s = m.start; s < end; s += detail::MERKLE_PAGE_SIZE) {
diff --git a/tools/gen-interpret-jump-table.lua b/tools/gen-interpret-jump-table.lua
index 173173d3e..eb88fd34c 100755
--- a/tools/gen-interpret-jump-table.lua
+++ b/tools/gen-interpret-jump-table.lua
@@ -580,6 +580,7 @@ io.write([[};
 ]])
 
 -- Emit the jump table
+io.write("//NOLINTNEXTLINE(cppcoreguidelines-avoid-non-const-global-variables)\n")
 io.write("static const INSN_JUMPTABLE_TYPE insn_jumptable[", #jumptable, "] = {\n")
 io.write("#ifndef CLANG_TIDY_LINT // Disable clang-tidy via an ifdef because it's too slow\n")
 for i, name in ipairs(jumptable) do
diff --git a/uarch/Makefile b/uarch/Makefile
index c8ce13112..06396d509 100644
--- a/uarch/Makefile
+++ b/uarch/Makefile
@@ -87,13 +87,15 @@ UARCH_OBJS = $(patsubst %.c,%.uarch_c.o,$(patsubst %.cpp,%.uarch_cpp.o,$(UARCH_S
 EMULATOR_OBJS = $(patsubst %.c,%.emulator_c.o,$(patsubst %.cpp,%.emulator_cpp.o,$(EMULATOR_SOURCES)))
 COMPUTE_OBJS = $(patsubst %.c,%.compute_c.o,$(patsubst %.cpp,%.compute_cpp.o,$(COMPUTE_SOURCES)))
 
-LINTER_SOURCES=$($(strip $(wildcard uarch-*.cpp) $(wildcard uarch-*.c)))
-LINTER_HEADERS=$($(strip $(wildcard uarch-*.h)))
+LINTER_SOURCES=$(strip $(wildcard uarch-*.cpp))
+LINTER_HEADERS=$(strip $(wildcard uarch-*.h))
 EMPTY:=
 SPACE:=$(EMPTY) $(EMPTY)
 CLANG_TIDY_HEADER_FILTER=$(CURDIR)/($(subst $(SPACE),|,$(LINTER_HEADERS)))
 CLANG_TIDY=clang-tidy
-CLANG_TIDY_TARGETS=$(patsubst %.cpp,%.clang-tidy,$(patsubst %.c,%.clang-tidy,$(LINTER_SOURCES)))
+CLANG_TIDY_TARGETS=$(patsubst %.cpp,%.clang-tidy,$(LINTER_SOURCES))
+CLANG_TIDY_FLAGS=--warnings-as-errors=*
+CLANG_TIDY_WARNS=-Wthread-safety -Wglobal-constructors -Wno-unused-command-line-argument -Wno-format
 
 .PHONY: all clean validate-instruction-set
 
@@ -152,7 +154,7 @@ uarch-ram-entry.o: uarch-ram-entry.S
 	grep -v '^#' $@.tmp > $@
 
 %.clang-tidy: %.cpp
-	$(CLANG_TIDY) --header-filter='$(CLANG_TIDY_HEADER_FILTER)' $(CLANG_TIDY_FLAGS) $< -- -target riscv64-linux-gnu $(CFLAGS) $(CXXFLAGS) -Wno-unused-command-line-argument 2>/dev/null
+	$(CLANG_TIDY) --header-filter='$(CLANG_TIDY_HEADER_FILTER)' $(CLANG_TIDY_FLAGS) $< -- -target riscv64-linux-gnu $(CFLAGS) $(CXXFLAGS) $(CLANG_TIDY_WARNS) 2>/dev/null
 	@touch $@
 
 lint: $(CLANG_TIDY_TARGETS)
@@ -164,4 +166,4 @@ clean-auto-generated:
 	@rm -f uarch-pristine-hash.c uarch-pristine-ram.c
 
 clean: clean-executables clean-auto-generated
-	@rm -f *.ld *.elf *.bin *.tmp link.ld $(UARCH_OBJS) $(EMULATOR_OBJS) $(COMPUTE_OBJS) uarch-ram-entry.o *.clang-tidy *.insn.txt *.objdump
+	@rm -f *.ld *.elf *.bin *.tmp *.o *.clang-tidy *.insn.txt *.objdump $(UARCH_OBJS) $(EMULATOR_OBJS) $(COMPUTE_OBJS)
diff --git a/uarch/compute-uarch-pristine-hash.cpp b/uarch/compute-uarch-pristine-hash.cpp
index 68aecbda6..0998ce2e2 100644
--- a/uarch/compute-uarch-pristine-hash.cpp
+++ b/uarch/compute-uarch-pristine-hash.cpp
@@ -123,9 +123,9 @@ int main(int argc, char *argv[]) try {
     // Get uarch state hash
     auto uarch_state_hash = tree.get_root_hash();
     // Print header
-    std::cout << "// This file is auto-generated and should not be modified" << std::endl;
+    std::cout << "// This file is auto-generated and should not be modified\n";
     // Print hash
-    std::cout << "unsigned char uarch_pristine_hash[] = {\n  ";
+    std::cout << "const unsigned char uarch_pristine_hash[] = {\n  ";
     int i = 0;
     for (auto c : uarch_state_hash) {
         if (i > 0 && i % 12 == 0) {
@@ -136,8 +136,7 @@ int main(int argc, char *argv[]) try {
         std::cout << "0x" << std::setw(2) << std::setfill('0') << std::hex << static_cast<int>(c);
         i++;
     }
-    std::cout << "\n};\nunsigned int uarch_pristine_hash_len = " << std::dec << uarch_state_hash.size() << ";"
-              << std::endl;
+    std::cout << "\n};\nconst unsigned int uarch_pristine_hash_len = " << std::dec << uarch_state_hash.size() << ";\n";
     return 0;
 } catch (std::exception &e) {
     std::cerr << "Caught exception: " << e.what() << '\n';
diff --git a/uarch/machine-uarch-bridge-state-access.h b/uarch/machine-uarch-bridge-state-access.h
index 40adec521..199dddb5a 100644
--- a/uarch/machine-uarch-bridge-state-access.h
+++ b/uarch/machine-uarch-bridge-state-access.h
@@ -55,7 +55,7 @@ class machine_uarch_bridge_state_access :
     mock_address_ranges &m_ars;
 
 public:
-    machine_uarch_bridge_state_access(std::array<mock_address_range, PMA_MAX> &ars) : m_ars(ars) {}
+    explicit machine_uarch_bridge_state_access(std::array<mock_address_range, PMA_MAX> &ars) : m_ars(ars) {}
     machine_uarch_bridge_state_access(const machine_uarch_bridge_state_access &other) = default;
     machine_uarch_bridge_state_access(machine_uarch_bridge_state_access &&other) = default;
     machine_uarch_bridge_state_access &operator=(const machine_uarch_bridge_state_access &other) = delete;
@@ -71,11 +71,11 @@ class machine_uarch_bridge_state_access :
         ua_aliased_aligned_write<uint64_t>(machine_reg_address(reg), val);
     }
 
-    static uint64_t bridge_read_pma_istart(int i) {
+    static uint64_t bridge_read_pma_istart(uint64_t i) {
         return ua_aliased_aligned_read<uint64_t>(pmas_get_abs_addr(i, pmas_what::istart));
     }
 
-    static uint64_t bridge_read_pma_ilength(int i) {
+    static uint64_t bridge_read_pma_ilength(uint64_t i) {
         return ua_aliased_aligned_read<uint64_t>(pmas_get_abs_addr(i, pmas_what::ilength));
     }
 
@@ -88,10 +88,12 @@ class machine_uarch_bridge_state_access :
     // -----
     friend i_prefer_shadow_state<machine_uarch_bridge_state_access>;
 
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
     uint64_t do_read_shadow_register(shadow_registers_what what) const {
         return bridge_read_reg(machine_reg_enum(what));
     }
 
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
     void do_write_shadow_register(shadow_registers_what what, uint64_t val) const {
         bridge_write_reg(machine_reg_enum(what), val);
     }
@@ -111,6 +113,7 @@ class machine_uarch_bridge_state_access :
         ua_aliased_aligned_write<T, A>(paddr, val);
     }
 
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
     bool do_read_memory(uint64_t /*paddr*/, unsigned char * /*data*/, uint64_t /*length*/) const {
         // This is not implemented yet because it's not being used
         assert(false && "read_memory() unexpectedly called");
@@ -118,6 +121,7 @@ class machine_uarch_bridge_state_access :
         return false;
     }
 
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
     bool do_write_memory(uint64_t /*paddr*/, const unsigned char * /*data*/, uint64_t /*length*/) const {
         // This is not implemented yet because it's not being used
         assert(false && "write_memory() unexpectedly called");
@@ -141,6 +145,7 @@ class machine_uarch_bridge_state_access :
         return get_mock_address_range(m_ars[i], throw_abort);
     }
 
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
     uint64_t do_get_faddr(uint64_t paddr, uint64_t /* pma_index */) const {
         return paddr;
     }
@@ -165,10 +170,12 @@ class machine_uarch_bridge_state_access :
         ua_write_tlb_ECALL(SET, slot_index, vaddr_page, vp_offset, pma_index);
     }
 
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
     void do_putchar(uint8_t c) const {
         ua_putchar_ECALL(c);
     }
 
+    // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
     void do_mark_dirty_page(uint64_t paddr, uint64_t pma_index) const {
         ua_mark_dirty_page_ECALL(paddr, pma_index);
     }
@@ -176,8 +183,6 @@ class machine_uarch_bridge_state_access :
     constexpr const char *do_get_name() const { // NOLINT(readability-convert-member-functions-to-static)
         return "machine_uarch_bridge_state_access";
     }
-
-    // NOLINTEND(readability-convert-member-functions-to-static)
 };
 
 } // namespace cartesi
diff --git a/uarch/uarch-run.cpp b/uarch/uarch-run.cpp
index 354a2f069..65aa60f42 100644
--- a/uarch/uarch-run.cpp
+++ b/uarch/uarch-run.cpp
@@ -29,10 +29,6 @@
 
 using namespace cartesi;
 
-// Let the state accessor be on static memory storage to speed up uarch initialization
-// NOLINTNEXTLINE(cppcoreguidelines-avoid-non-const-global-variables)
-mock_address_ranges ars;
-
 namespace cartesi {
 
 // Declaration of explicit instantiation in module interpret.cpp when compiled with microarchitecture
@@ -43,7 +39,9 @@ extern template interpreter_break_reason interpret(machine_uarch_bridge_state_ac
 /// \brief  Advances one mcycle by executing the "big machine interpreter" compiled to the microarchitecture
 /// \return This function never returns
 extern "C" NO_RETURN void interpret_next_mcycle_with_uarch() {
-    machine_uarch_bridge_state_access a(ars);
+    // Let the state accessor be on static memory storage to speed up uarch initialization
+    static mock_address_ranges ars;
+    const machine_uarch_bridge_state_access a(ars);
     const uint64_t mcycle_end = a.read_mcycle() + 1;
     interpret(a, mcycle_end);
     // Finished executing a whole mcycle: halt the microarchitecture
diff --git a/uarch/uarch-runtime.cpp b/uarch/uarch-runtime.cpp
index 0fa655c1e..f8e0d251a 100644
--- a/uarch/uarch-runtime.cpp
+++ b/uarch/uarch-runtime.cpp
@@ -26,15 +26,15 @@ extern "C" void __cxa_pure_virtual() {
     abort();
 }
 
-extern "C" int atexit(void (*)(void)) {
+extern "C" int atexit([[maybe_unused]] void (*f)()) {
     return 0;
 }
 
 // NOLINTNEXTLINE(cert-dcl54-cpp,misc-new-delete-overloads,hicpp-new-delete-operators)
-void operator delete(void * /*ptr*/) {}
+void operator delete(void * /*ptr*/) noexcept {}
 
 // NOLINTNEXTLINE(cert-dcl54-cpp,misc-new-delete-overloads,hicpp-new-delete-operators)
-void operator delete(void * /*ptr*/, size_t /*size*/) {}
+void operator delete(void * /*ptr*/, size_t /*size*/) noexcept {}
 
 // NOLINTNEXTLINE(bugprone-reserved-identifier,cert-dcl37-c,cert-dcl51-cpp)
 extern "C" void __assert_func(const char * /*file*/, int /*line*/, const char * /*func*/, const char * /*e*/) {}
diff --git a/uarch/uarch-runtime.h b/uarch/uarch-runtime.h
index a59b60096..3f83a5b6a 100644
--- a/uarch/uarch-runtime.h
+++ b/uarch/uarch-runtime.h
@@ -20,8 +20,8 @@
 #include "compiler-defines.h"
 #include "third-party/printf/printf.h"
 
-#include <inttypes.h>
-#include <stddef.h>
+#include <cinttypes>
+#include <cstddef>
 
 #ifndef NDEBUG
 // NOLINTNEXTLINE(cppcoreguidelines-macro-usage)
diff --git a/uarch/uarch-strict-aliasing.h b/uarch/uarch-strict-aliasing.h
index c3bfb2ffc..cbdf2e0ff 100644
--- a/uarch/uarch-strict-aliasing.h
+++ b/uarch/uarch-strict-aliasing.h
@@ -46,7 +46,9 @@ static inline void *cast_phys_addr_to_ptr(uint64_t paddr) {
 //??D I don't know why GCC warns about this overflow when there is none.
 //??D The code generated seems to be pretty good as well.
 #pragma GCC diagnostic push
+#ifndef __clang__
 #pragma GCC diagnostic ignored "-Wstringop-overflow"
+#endif
 /// \brief Writes a value to memory.
 /// \tparam T Type of value.
 /// \tparam A Type to which \p paddr is aligned.

From fb1e9ac3222fd307c4dfffa84fbcdf78291246ae Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Wed, 11 Jun 2025 16:57:16 -0300
Subject: [PATCH 45/82] fix: cm_jsonrpc_spawn_server wasn't respecting the
 specific bind address

---
 src/jsonrpc-machine.cpp | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/jsonrpc-machine.cpp b/src/jsonrpc-machine.cpp
index f92e377d6..01960d7f1 100644
--- a/src/jsonrpc-machine.cpp
+++ b/src/jsonrpc-machine.cpp
@@ -538,7 +538,7 @@ jsonrpc_machine::jsonrpc_machine(const std::string &address, int64_t spawn_timeo
 
     // Rebind the forked server to listen on the originally requested address
     std::string rebind_result;
-    request("rebind", std::tie(forked_grand_child.address), rebind_result, timeout_at, false);
+    request("rebind", std::tie(address), rebind_result, timeout_at, false);
     m_address = rebind_result;
 
     // At this point, we've confirmed the remote server is properly initialized and running

From 622f967fb31f941e1786f8349edbdabec9f9373b Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Fri, 25 Apr 2025 10:09:07 -0300
Subject: [PATCH 46/82] fix: make virtio_net_user_address_range moveable

---
 src/virtio-net-user-address-range.cpp | 138 +++++++++++---------------
 src/virtio-net-user-address-range.h   |  29 ++++--
 2 files changed, 78 insertions(+), 89 deletions(-)

diff --git a/src/virtio-net-user-address-range.cpp b/src/virtio-net-user-address-range.cpp
index 10ac01e86..703c4fbb7 100644
--- a/src/virtio-net-user-address-range.cpp
+++ b/src/virtio-net-user-address-range.cpp
@@ -66,6 +66,7 @@
 #include <stdexcept>
 #include <string>
 #include <system_error>
+#include <type_traits>
 
 #include <arpa/inet.h>
 #include <slirp/libslirp.h>
@@ -79,11 +80,12 @@ using namespace std::string_literals;
 
 namespace cartesi {
 
-//??D why ssize_t?
-static ssize_t slirp_send_packet(const void *buf, size_t len, void *opaque) {
+using slirp_callback_size_t = std::invoke_result_t<SlirpWriteCb, const void *, size_t, void *>;
+
+static slirp_callback_size_t slirp_send_packet(const void *buf, size_t len, void *opaque) {
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-    auto *carrier = reinterpret_cast<virtio_net_user_address_range *>(opaque);
-    if (carrier->send_packets.size() >= SLIRP_MAX_PENDING_PACKETS) {
+    auto *context = reinterpret_cast<slirp_context *>(opaque);
+    if (context->send_packets.size() >= SLIRP_MAX_PENDING_PACKETS) {
         // Too many send_packets in the write queue, we can just drop it.
         // Network re-transmission can recover from this.
 #ifdef DEBUG_VIRTIO_ERRORS
@@ -104,8 +106,8 @@ static ssize_t slirp_send_packet(const void *buf, size_t len, void *opaque) {
     slirp_packet packet{.len = len};
     memcpy(packet.buf.data(), buf, len);
     try {
-        carrier->send_packets.emplace_back(packet);
-        return static_cast<ssize_t>(len);
+        context->send_packets.emplace_back(packet);
+        return static_cast<slirp_callback_size_t>(len);
     } catch (...) {
 #ifdef DEBUG_VIRTIO_ERRORS
         std::ignore = fprintf(stderr, "slirp: exception thrown while adding a send packet\n");
@@ -128,39 +130,35 @@ static int64_t slirp_clock_get_ns(void * /*opaque*/) {
 
 static void *slirp_timer_new(SlirpTimerCb cb, void *cb_opaque, void *opaque) {
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-    auto *carrier = reinterpret_cast<virtio_net_user_address_range *>(opaque);
+    auto *context = reinterpret_cast<slirp_context *>(opaque);
     try {
-        auto *timer = new slirp_timer;
+        auto timer = std::make_unique<slirp_timer>();
+        auto *timer_key = timer.get();
         timer->cb = cb;
         timer->cb_opaque = cb_opaque;
         timer->expire_timer_msec = -1;
-        carrier->timers.insert(timer);
-        return timer;
+        context->timers.emplace(timer_key, std::move(timer));
+        return timer_key;
     } catch (...) {
         return nullptr;
     }
 }
 
-static void slirp_timer_free(void *timer_ptr, void *opaque) {
-    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-    auto *carrier = reinterpret_cast<virtio_net_user_address_range *>(opaque);
+static void slirp_timer_free(void *timer_key, void *opaque) {
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-    auto *timer = reinterpret_cast<slirp_timer *>(timer_ptr);
-    if (timer != nullptr) {
-        auto it = carrier->timers.find(timer);
-        if (it != carrier->timers.end()) {
-            carrier->timers.erase(it);
-            delete timer;
-        }
+    auto *context = reinterpret_cast<slirp_context *>(opaque);
+    auto it = context->timers.find(timer_key);
+    if (it != context->timers.end()) {
+        context->timers.erase(it);
     }
 }
 
-static void slirp_timer_mod(void *timer_ptr, int64_t expire_timer_msec, void *opaque) {
-    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-    auto *carrier = reinterpret_cast<virtio_net_user_address_range *>(opaque);
+static void slirp_timer_mod(void *timer_key, int64_t expire_timer_msec, void *opaque) {
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-    auto *timer = reinterpret_cast<slirp_timer *>(timer_ptr);
-    if ((timer != nullptr) && carrier->timers.contains(timer)) {
+    auto *context = reinterpret_cast<slirp_context *>(opaque);
+    const auto it = context->timers.find(timer_key);
+    if (it != context->timers.end()) {
+        auto &timer = it->second;
         timer->expire_timer_msec = expire_timer_msec;
     }
 }
@@ -179,36 +177,38 @@ static void slirp_notify(void * /*opaque*/) {
 
 virtio_net_user_address_range::virtio_net_user_address_range(uint64_t start, uint64_t length, uint32_t virtio_idx,
     const cartesi::virtio_net_user_config &config) :
-    virtio_net_address_range("VirtIO Net User", start, length, virtio_idx) {
+    virtio_net_address_range("VirtIO Net User", start, length, virtio_idx),
+    m_context(std::make_unique<slirp_context>()) {
 
     // Configure slirp
-    slirp_cfg.version = std::min<int>(SLIRP_CONFIG_VERSION_MAX, SLIRP_VERSION);
-    slirp_cfg.restricted = 0;                                             // Don't isolate the guest from the host
-    slirp_cfg.in_enabled = true;                                          // IPv4 is enabled
-    slirp_cfg.vnetwork.s_addr = htonl(SLIRP_DEFAULT_IPV4_VNETWORK);       // Network
-    slirp_cfg.vnetmask.s_addr = htonl(SLIRP_DEFAULT_IPV4_VNETMASK);       // Netmask
-    slirp_cfg.vhost.s_addr = htonl(SLIRP_DEFAULT_IPV4_VHOST);             // Host address/gateway
-    slirp_cfg.vdhcp_start.s_addr = htonl(SLIRP_DEFAULT_IPV4_VDHCP_START); // DHCP start address
-    slirp_cfg.vnameserver.s_addr = htonl(SLIRP_DEFAULT_IPV4_VNAMESERVER); // DNS server address
+    m_context->config.version = std::min<int>(SLIRP_CONFIG_VERSION_MAX, SLIRP_VERSION);
+    m_context->config.restricted = 0;                                       // Don't isolate the guest from the host
+    m_context->config.in_enabled = true;                                    // IPv4 is enabled
+    m_context->config.vnetwork.s_addr = htonl(SLIRP_DEFAULT_IPV4_VNETWORK); // Network
+    m_context->config.vnetmask.s_addr = htonl(SLIRP_DEFAULT_IPV4_VNETMASK); // Netmask
+    m_context->config.vhost.s_addr = htonl(SLIRP_DEFAULT_IPV4_VHOST);       // Host address/gateway
+    m_context->config.vdhcp_start.s_addr = htonl(SLIRP_DEFAULT_IPV4_VDHCP_START); // DHCP start address
+    m_context->config.vnameserver.s_addr = htonl(SLIRP_DEFAULT_IPV4_VNAMESERVER); // DNS server address
     // ??(edubart): Should all the above settings be configurable by the user?
     // ??(edubart): Should we add support for IPv6? It is disabled by default.
     // Configure required slirp callbacks
-    slirp_cbs.send_packet = slirp_send_packet;
-    slirp_cbs.guest_error = slirp_guest_error;
-    slirp_cbs.clock_get_ns = slirp_clock_get_ns;
-    slirp_cbs.timer_new = slirp_timer_new;
-    slirp_cbs.timer_free = slirp_timer_free;
-    slirp_cbs.timer_mod = slirp_timer_mod;
+    m_context->callbacks.send_packet = slirp_send_packet;
+    m_context->callbacks.guest_error = slirp_guest_error;
+    m_context->callbacks.clock_get_ns = slirp_clock_get_ns;
+    m_context->callbacks.timer_new = slirp_timer_new;
+    m_context->callbacks.timer_free = slirp_timer_free;
+    m_context->callbacks.timer_mod = slirp_timer_mod;
 #pragma GCC diagnostic push
 #pragma GCC diagnostic ignored "-Wdeprecated-declarations"
-    slirp_cbs.register_poll_fd = slirp_register_poll_fd;
-    slirp_cbs.unregister_poll_fd = slirp_unregister_poll_fd;
+    m_context->callbacks.register_poll_fd = slirp_register_poll_fd;
+    m_context->callbacks.unregister_poll_fd = slirp_unregister_poll_fd;
 #pragma GCC diagnostic pop
-    slirp_cbs.notify = slirp_notify;
+    m_context->callbacks.notify = slirp_notify;
 
     // Initialize slirp
-    slirp = slirp_new(&slirp_cfg, &slirp_cbs, this);
-    if (slirp == nullptr) {
+    m_context->slirp =
+        decltype(m_context->slirp){slirp_new(&m_context->config, &m_context->callbacks, m_context.get())};
+    if (m_context->slirp == nullptr) {
         throw std::runtime_error("could not configure slirp network device");
     }
 
@@ -218,8 +218,8 @@ virtio_net_user_address_range::virtio_net_user_address_range(uint64_t start, uin
         struct in_addr guest_addr{};
         host_addr.s_addr = htonl(hostfwd.host_ip);
         guest_addr.s_addr = htonl(hostfwd.guest_ip);
-        if (slirp_add_hostfwd(slirp, static_cast<int>(hostfwd.is_udp), host_addr, hostfwd.host_port, guest_addr,
-                hostfwd.guest_port) < 0) {
+        if (slirp_add_hostfwd(m_context->slirp.get(), static_cast<int>(hostfwd.is_udp), host_addr, hostfwd.host_port,
+                guest_addr, hostfwd.guest_port) < 0) {
             throw std::system_error{errno, std::generic_category(),
                 "failed to forward "s + (hostfwd.is_udp ? "UDP" : "TCP") + " host port " +
                     std::to_string(hostfwd.host_port) + " to guest port " + std::to_string(hostfwd.guest_port)};
@@ -227,19 +227,6 @@ virtio_net_user_address_range::virtio_net_user_address_range(uint64_t start, uin
     }
 }
 
-virtio_net_user_address_range::~virtio_net_user_address_range() {
-    // Cleanup slirp
-    if (slirp != nullptr) {
-        slirp_cleanup(slirp);
-        slirp = nullptr;
-    }
-    // Delete remaining timers created by slirp
-    for (slirp_timer *timer : timers) {
-        delete timer;
-    }
-    timers.clear();
-}
-
 void virtio_net_user_address_range::do_net_reset() {
     // Nothing to do, we don't want to reset slirp to not lose network state.
 }
@@ -284,10 +271,6 @@ static int slirp_get_revents_cb(int fd, void *opaque) {
 }
 
 void virtio_net_user_address_range::do_net_prepare_select(select_fd_sets *fds, uint64_t *timeout_us) {
-    // Did device reset and slirp failed to reinitialize?
-    if (slirp == nullptr) {
-        return;
-    }
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
     auto *readfds = reinterpret_cast<fd_set *>(fds->readfds);
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
@@ -299,7 +282,7 @@ void virtio_net_user_address_range::do_net_prepare_select(select_fd_sets *fds, u
     uint32_t timeout_ms = initial_timeout_ms;
 #pragma GCC diagnostic push
 #pragma GCC diagnostic ignored "-Wdeprecated-declarations"
-    slirp_pollfds_fill(slirp, &timeout_ms, slirp_add_poll_cb, &slirp_fds);
+    slirp_pollfds_fill(m_context->slirp.get(), &timeout_ms, slirp_add_poll_cb, &slirp_fds);
 #pragma GCC diagnostic pop
     if (initial_timeout_ms != timeout_ms) {
         *timeout_us = static_cast<uint64_t>(timeout_ms) * 1000;
@@ -307,10 +290,6 @@ void virtio_net_user_address_range::do_net_prepare_select(select_fd_sets *fds, u
 }
 
 bool virtio_net_user_address_range::do_net_poll_selected(int select_ret, select_fd_sets *fds) {
-    // Did device reset and slirp failed to reinitialize?
-    if (slirp == nullptr) {
-        return false;
-    }
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
     auto *readfds = reinterpret_cast<fd_set *>(fds->readfds);
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
@@ -318,10 +297,11 @@ bool virtio_net_user_address_range::do_net_poll_selected(int select_ret, select_
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
     auto *exceptfds = reinterpret_cast<fd_set *>(fds->exceptfds);
     slirp_select_fds slirp_fds{.pmaxfd = nullptr, .readfds = readfds, .writefds = writefds, .exceptfds = exceptfds};
-    slirp_pollfds_poll(slirp, static_cast<int>(select_ret < 0), slirp_get_revents_cb, &slirp_fds);
+    slirp_pollfds_poll(m_context->slirp.get(), static_cast<int>(select_ret < 0), slirp_get_revents_cb, &slirp_fds);
     // Fire expired timers
     const int64_t now_ms = slirp_clock_get_ns(nullptr) / 1000000;
-    for (slirp_timer *timer : timers) {
+    for (auto &it : m_context->timers) {
+        auto &timer = it.second;
         if (timer->expire_timer_msec != -1 && now_ms >= timer->expire_timer_msec) {
             if (timer->cb != nullptr) {
                 timer->cb(timer->cb_opaque);
@@ -330,17 +310,11 @@ bool virtio_net_user_address_range::do_net_poll_selected(int select_ret, select_
             timer->expire_timer_msec = -1;
         }
     }
-    return !send_packets.empty();
+    return !m_context->send_packets.empty();
 }
 
 bool virtio_net_user_address_range::do_net_write_packet_to_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx,
     uint32_t read_avail_len, uint32_t *pread_len) {
-    // Did device reset and slirp failed to reinitialize?
-    if (slirp == nullptr) {
-        // Just drop it.
-        *pread_len = 0;
-        return true;
-    }
     const uint32_t packet_len = read_avail_len - VIRTIO_NET_ETHERNET_FRAME_OFFSET;
     if (packet_len > VIRTIO_NET_ETHERNET_MAX_LENGTH) {
         // This is unexpected, guest is trying to send jumbo Ethernet frames? Just drop it.
@@ -356,7 +330,7 @@ bool virtio_net_user_address_range::do_net_write_packet_to_host(i_device_state_a
         // Failure while accessing guest memory, the driver or guest messed up, return false to reset the device.
         return false;
     }
-    slirp_input(slirp, packet.buf.data(), static_cast<int>(packet.len));
+    slirp_input(m_context->slirp.get(), packet.buf.data(), static_cast<int>(packet.len));
     // Packet was read and the queue is ready to be consumed.
     *pread_len = read_avail_len;
     return true;
@@ -365,13 +339,13 @@ bool virtio_net_user_address_range::do_net_write_packet_to_host(i_device_state_a
 bool virtio_net_user_address_range::do_net_read_packet_from_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx,
     uint32_t write_avail_len, uint32_t *pwritten_len) {
     // If no packet was send by slirp, we can just ignore.
-    if (send_packets.empty()) {
+    if (m_context->send_packets.empty()) {
         *pwritten_len = 0;
         return true;
     }
     // Retrieve the next packet sent by slirp.
-    slirp_packet packet = send_packets.front();
-    send_packets.pop_front();
+    slirp_packet packet = m_context->send_packets.front();
+    m_context->send_packets.pop_front();
     // Is there enough space in the write buffer to write this packet?
     if (VIRTIO_NET_ETHERNET_FRAME_OFFSET + packet.len > write_avail_len) {
 #ifdef DEBUG_VIRTIO_ERRORS
diff --git a/src/virtio-net-user-address-range.h b/src/virtio-net-user-address-range.h
index dcf17fff9..84db6d9c1 100644
--- a/src/virtio-net-user-address-range.h
+++ b/src/virtio-net-user-address-range.h
@@ -25,6 +25,7 @@
 #include <cstddef>
 #include <cstdint>
 #include <list>
+#include <memory>
 #include <unordered_set>
 
 #include <slirp/libslirp.h>
@@ -65,14 +66,26 @@ struct slirp_packet {
     std::array<unsigned char, VIRTIO_NET_ETHERNET_MAX_LENGTH> buf{};
 };
 
-class virtio_net_user_address_range final : public virtio_net_address_range {
-public:
-    Slirp *slirp = nullptr;
-    SlirpConfig slirp_cfg{};
-    SlirpCb slirp_cbs{};
+namespace detail {
+
+struct slirp_deleter {
+    void operator()(Slirp *slirp) const noexcept {
+        slirp_cleanup(slirp);
+    }
+};
+
+} // namespace detail
+
+struct slirp_context {
+    SlirpConfig config{};
+    SlirpCb callbacks{};
+    std::unique_ptr<Slirp, detail::slirp_deleter> slirp;
     std::list<slirp_packet> send_packets;
-    std::unordered_set<slirp_timer *> timers;
+    std::unordered_map<void *, std::unique_ptr<slirp_timer>> timers;
+};
 
+class virtio_net_user_address_range final : public virtio_net_address_range {
+public:
     virtio_net_user_address_range(uint64_t start, uint64_t length, uint32_t virtio_idx,
         const virtio_net_user_config &config);
 
@@ -81,7 +94,7 @@ class virtio_net_user_address_range final : public virtio_net_address_range {
     virtio_net_user_address_range &operator=(virtio_net_user_address_range &&other) = delete;
 
     virtio_net_user_address_range(virtio_net_user_address_range &&other) = default;
-    ~virtio_net_user_address_range() override;
+    ~virtio_net_user_address_range() override = default;
 
 private:
     void do_net_reset() override;
@@ -91,6 +104,8 @@ class virtio_net_user_address_range final : public virtio_net_address_range {
         uint32_t *pread_len) override;
     bool do_net_read_packet_from_host(i_device_state_access *a, virtq &vq, uint16_t desc_idx, uint32_t write_avail_len,
         uint32_t *pwritten_len) override;
+
+    std::unique_ptr<slirp_context> m_context;
 };
 
 static inline auto make_virtio_net_user_address_range(uint64_t start, uint64_t length, uint32_t virtio_idx,

From 0d641ca26399ee11c08f6e98d6bd21401592060c Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Tue, 29 Apr 2025 18:47:12 -0300
Subject: [PATCH 47/82] refactor: make write memory on shadow range more robust

---
 src/machine.cpp       | 114 +++++++++++++++++++++++++++++++++---------
 src/machine.h         |   3 ++
 src/pmas.h            |   6 ---
 src/processor-state.h |   2 +-
 4 files changed, 95 insertions(+), 30 deletions(-)

diff --git a/src/machine.cpp b/src/machine.cpp
index 6faad5e5a..425913216 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -65,8 +65,10 @@
 #include "replay-step-state-access.h"
 #include "riscv-constants.h"
 #include "rtc.h"
+#include "scope-exit.h"
 #include "send-cmio-response.h"
 #include "shadow-tlb.h"
+#include "shadow-uarch-state.h"
 #include "state-access.h"
 #include "strict-aliasing.h"
 #include "translate-virtual-address.h"
@@ -111,6 +113,11 @@ void machine::init_uarch_processor(const uarch_processor_config &p) {
             write_reg(machine_reg_enum(reg::uarch_x0, i), p.registers.x[i]);
         }
     }
+
+    // Ensure uarch x0 is actually zero
+    if (m_us->registers.x[0] != 0) {
+        throw std::invalid_argument{"uarch x0 register is corrupt"};
+    }
 }
 
 void machine::init_processor(processor_config &p, const machine_runtime_config &r) {
@@ -123,26 +130,14 @@ void machine::init_processor(processor_config &p, const machine_runtime_config &
             p.registers.marchid = MARCHID_INIT;
         }
 
-        if (p.registers.marchid != MARCHID_INIT && !r.skip_version_check) {
-            throw std::invalid_argument{"marchid mismatch, emulator version is incompatible"};
-        }
-
         if (p.registers.mvendorid == UINT64_C(-1)) {
             p.registers.mvendorid = MVENDORID_INIT;
         }
 
-        if (p.registers.mvendorid != MVENDORID_INIT && !r.skip_version_check) {
-            throw std::invalid_argument{"mvendorid mismatch, emulator version is incompatible"};
-        }
-
         if (p.registers.mimpid == UINT64_C(-1)) {
             p.registers.mimpid = MIMPID_INIT;
         }
 
-        if (p.registers.mimpid != MIMPID_INIT && !r.skip_version_check) {
-            throw std::invalid_argument{"mimpid mismatch, emulator version is incompatible"};
-        }
-
         // General purpose registers
         for (int i = 1; i < X_REG_COUNT; i++) {
             write_reg(machine_reg_enum(reg::x0, i), p.registers.x[i]);
@@ -200,20 +195,57 @@ void machine::init_processor(processor_config &p, const machine_runtime_config &
         write_reg(reg::plic_girqpend, p.registers.plic.girqpend);
         write_reg(reg::plic_girqsrvd, p.registers.plic.girqsrvd);
     }
+
+    // Check if registers are consistent
+    validate_processor_shadow(r.skip_version_check);
+}
+
+void machine::validate_processor_shadow(bool skip_version_check) const {
+    // Ensure emulator version is compatible
+    if (!skip_version_check) {
+        if (m_s->shadow.registers.marchid != MARCHID_INIT) {
+            throw std::invalid_argument{"marchid mismatch, emulator version is incompatible"};
+        }
+        if (m_s->shadow.registers.mvendorid != MVENDORID_INIT) {
+            throw std::invalid_argument{"mvendorid mismatch, emulator version is incompatible"};
+        }
+        if (m_s->shadow.registers.mimpid != MIMPID_INIT) {
+            throw std::invalid_argument{"mimpid mismatch, emulator version is incompatible"};
+        }
+    }
+    // Ensure x0 is actually zero
+    if (m_s->shadow.registers.x[0] != 0) {
+        throw std::invalid_argument{"x0 register is corrupt"};
+    }
+    // Ensure padding bytes are consistent
+    if ( // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        !is_pristine(reinterpret_cast<unsigned char *>(&m_s->shadow.registers_padding_[0]),
+            sizeof(m_s->shadow.registers_padding_)) ||
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        !is_pristine(reinterpret_cast<unsigned char *>(&m_s->shadow.tlb_padding_[0]),
+            sizeof(m_s->shadow.tlb_padding_))) {
+        throw std::invalid_argument{"shadow padding bytes are corrupt"};
+    }
 }
 
 void machine::init_pmas_contents(const pmas_config &config) {
     static_assert(sizeof(pmas_state) == PMA_MAX * 2 * sizeof(uint64_t), "inconsistent PMAs state length");
     static_assert(AR_PMAS_LENGTH >= sizeof(pmas_state), "PMAs address range too short");
+    auto &pmas = m_ars.find(AR_PMAS_START, AR_PMAS_LENGTH);
+    if (!pmas.is_memory()) {
+        throw std::runtime_error{"initialization error: PMAs memory address range not found"};
+    }
+    pmas_state pmas_state{};
+    std::ranges::transform(m_ars.pmas_view(), pmas_state.begin(),
+        [](const auto &ar) { return pmas_entry{.istart = ar.get_istart(), .ilength = ar.get_ilength()}; });
+
     if (config.backing_store.data_filename.empty() || config.backing_store.create) {
-        auto &pmas = m_ars.find(AR_PMAS_START, AR_PMAS_LENGTH);
-        if (!pmas.is_memory()) {
-            throw std::runtime_error{"initialization error: PMAs memory address range not found"};
+        memcpy(pmas.get_host_memory(), pmas_state.data(), sizeof(pmas_state));
+    } else {
+        // Validate PMAs state is consistent
+        if (memcmp(pmas.get_host_memory(), pmas_state.data(), sizeof(pmas_state)) != 0) {
+            throw std::runtime_error{"PMA state is inconsistent machine address ranges"};
         }
-        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        auto &dest = *reinterpret_cast<pmas_state *>(pmas.get_host_memory());
-        std::ranges::transform(m_ars.pmas_view(), dest.begin(),
-            [](const auto &ar) { return pmas_entry{.istart = ar.get_istart(), .ilength = ar.get_ilength()}; });
     }
 }
 
@@ -1524,6 +1556,23 @@ void machine::write_memory(uint64_t paddr, const unsigned char *data, uint64_t l
     if (ar.is_host_read_only()) {
         throw std::invalid_argument{"attempted write to host-read-only memory range "s.append(ar_descr)};
     }
+    // Handle special case for writing to shadow memory, allowing manual snapshots
+    // for machines with shared layouts via read_memory()/write_memory()
+    if (paddr == AR_SHADOW_STATE_START && length == AR_SHADOW_STATE_LENGTH) {
+        // Save the current processor state for potential rollback
+        static const auto s = *m_s;
+        // Overwrite the processor shadow state with the provided data
+        static_assert(AR_SHADOW_STATE_LENGTH == sizeof(m_s->shadow));
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        memcpy(reinterpret_cast<unsigned char *>(&m_s->shadow), data, sizeof(m_s->shadow));
+        // Ensure processor state rollback in case of failure during subsequent operations
+        auto state_reverter = scope_fail([&] { *m_s = s; });
+        // Ensure the new processor shadow state is consistent
+        validate_processor_shadow(m_r.skip_version_check);
+        // Reinitialize the hot TLB to reflect changes in the shadow TLB and verify consistency
+        init_hot_tlb_contents();
+        return;
+    }
     if (pmas_is_protected(ar.get_driver_id())) {
         throw std::invalid_argument{"attempted write to protected memory range "s.append(ar_descr)};
     }
@@ -1660,6 +1709,24 @@ void machine::write_word(uint64_t paddr, uint64_t val) {
     if ((paddr & (sizeof(uint64_t) - 1)) != 0) {
         throw std::domain_error{"attempted misaligned write to word"};
     }
+    // If in shadow, forward to write_reg
+    if (paddr >= AR_SHADOW_REGISTERS_START && paddr - AR_SHADOW_REGISTERS_START < AR_SHADOW_REGISTERS_LENGTH) {
+        auto reg = shadow_registers_get_what(paddr);
+        if (reg == shadow_registers_what::unknown_) {
+            throw std::runtime_error("unhandled write to shadow state");
+        }
+        write_reg(machine_reg_enum(reg), val);
+        return;
+    }
+    // If in uarch shadow, forward to write_reg
+    if (paddr >= AR_SHADOW_UARCH_STATE_START && paddr - AR_SHADOW_UARCH_STATE_START < AR_SHADOW_UARCH_STATE_LENGTH) {
+        auto reg = shadow_uarch_state_get_what(paddr);
+        if (reg == shadow_uarch_state_what::unknown_) {
+            throw std::runtime_error("unhandled write to shadow uarch state");
+        }
+        write_reg(machine_reg_enum(reg), val);
+        return;
+    }
     auto &ar = m_ars.find(paddr, sizeof(uint64_t));
     if (!ar.is_memory() || ar.get_host_memory() == nullptr) {
         std::ostringstream err;
@@ -1673,10 +1740,11 @@ void machine::write_word(uint64_t paddr, uint64_t val) {
             << "(" << std::dec << paddr << ")";
         throw std::runtime_error{err.str()};
     }
-    if (pmas_range_overlaps(paddr, sizeof(uint64_t), AR_SHADOW_TLB_START, AR_SHADOW_TLB_LENGTH)) {
-        // Writing a single word to shadow TLB memory is not supported,
-        // it would leave corrupt its state in most situations.
-        throw std::invalid_argument{"attempted memory word write to shadow TLB memory range"};
+    if (pmas_is_protected(ar.get_driver_id())) {
+        std::ostringstream err;
+        err << "attempted memory word write to protected memory range " << ar.get_description() << " at address 0x"
+            << std::hex << paddr << "(" << std::dec << paddr << ")";
+        throw std::runtime_error{err.str()};
     }
     const auto offset = paddr - ar.get_start();
     aliased_aligned_write<uint64_t>(ar.get_host_memory() + offset, val);
diff --git a/src/machine.h b/src/machine.h
index 8e0c1e75a..b4b50f602 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -368,6 +368,9 @@ class machine final {
     /// \returns True if tree is self-consistent, false otherwise.
     bool verify_hash_tree() const;
 
+    /// \brief Validate integrity of processor shadow.
+    void validate_processor_shadow(bool skip_version_check) const;
+
     /// \brief Read the value of any register
     /// \param r Register to read
     /// \returns The value of the register
diff --git a/src/pmas.h b/src/pmas.h
index cea24d9c9..c24d5df03 100644
--- a/src/pmas.h
+++ b/src/pmas.h
@@ -70,12 +70,6 @@ static constexpr bool pmas_is_protected(PMA_ISTART_DID DID) {
     }
 }
 
-static constexpr bool pmas_range_overlaps(uint64_t a_start, uint64_t a_length, uint64_t b_start, uint64_t b_length) {
-    const uint64_t a_end = a_start + a_length - 1;
-    const uint64_t b_end = b_start + b_length - 1;
-    return (a_start <= b_end && a_end >= b_start);
-}
-
 ///< Unpacked attribute flags
 struct pmas_flags {
     bool M;             ///< is memory
diff --git a/src/processor-state.h b/src/processor-state.h
index bd4b0ba70..f73d31afa 100644
--- a/src/processor-state.h
+++ b/src/processor-state.h
@@ -39,7 +39,7 @@ struct shadow_state final {
     registers_state registers;          ///< Registers state
     uint64_t registers_padding_[406]{}; ///< Padding to align next field to a page boundary
     shadow_tlb_state tlb;               ///< Shadow TLB state
-    uint64_t shadow_tlb_padding[512]{}; ///< Padding to align next field to a page boundary
+    uint64_t tlb_padding_[512]{};       ///< Padding to align next field to a page boundary
 };
 
 /// \brief Penumbra state.

From 017b9f7a7fc003b074ca3ef037b4ac841c5ec3a2 Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Mon, 5 May 2025 15:43:12 -0300
Subject: [PATCH 48/82] feat: expose machine write_word method in the C API

---
 src/clua-i-machine.cpp            | 11 +++++++++++
 src/i-machine.h                   |  6 ++++++
 src/jsonrpc-discover.json         | 29 +++++++++++++++++++++++++++++
 src/jsonrpc-machine.cpp           |  5 +++++
 src/jsonrpc-machine.h             |  1 +
 src/jsonrpc-remote-machine.cpp    | 17 +++++++++++++++++
 src/local-machine.cpp             |  4 ++++
 src/local-machine.h               |  1 +
 src/machine-c-api.cpp             |  7 +++++++
 src/machine-c-api.h               | 14 +++++++++++---
 tests/lua/machine-bind.lua        |  3 +++
 tests/misc/test-machine-c-api.cpp | 18 +++++++++++++++---
 12 files changed, 110 insertions(+), 6 deletions(-)

diff --git a/src/clua-i-machine.cpp b/src/clua-i-machine.cpp
index 3cf9ee43c..7f99c4d44 100644
--- a/src/clua-i-machine.cpp
+++ b/src/clua-i-machine.cpp
@@ -843,6 +843,16 @@ static int machine_obj_index_write_virtual_memory(lua_State *L) {
     return 0;
 }
 
+/// \brief This is the machine:write_word() method implementation.
+/// \param L Lua state.
+static int machine_obj_index_write_word(lua_State *L) {
+    auto &m = clua_check<clua_managed_cm_ptr<cm_machine>>(L, 1);
+    if (cm_write_word(m.get(), luaL_checkinteger(L, 2), luaL_checkinteger(L, 3)) != 0) {
+        return luaL_error(L, "%s", cm_get_last_error_message());
+    }
+    return 0;
+}
+
 /// \brief This is the machine:translate_virtual_address() method implementation.
 /// \param L Lua state.
 static int machine_obj_index_translate_virtual_address(lua_State *L) {
@@ -1151,6 +1161,7 @@ static const auto machine_obj_index = cartesi::clua_make_luaL_Reg_array({
     {"write_memory", machine_obj_index_write_memory},
     {"write_reg", machine_obj_index_write_reg},
     {"write_virtual_memory", machine_obj_index_write_virtual_memory},
+    {"write_word", machine_obj_index_write_word},
 });
 
 /// \brief This is the class() constructor implementation.
diff --git a/src/i-machine.h b/src/i-machine.h
index 5303ae239..9bc8287a9 100644
--- a/src/i-machine.h
+++ b/src/i-machine.h
@@ -173,6 +173,11 @@ class i_machine {
         return do_read_word(address);
     }
 
+    /// \brief Write the value of a word in the machine state.
+    void write_word(uint64_t address, uint64_t value) {
+        do_write_word(address, value);
+    }
+
     /// \brief Returns hash-tree statistics
     /// \param clear Clear all statistics after collecting them
     /// \returns Structure containing all statistics
@@ -300,6 +305,7 @@ class i_machine {
     virtual uint64_t do_translate_virtual_address(uint64_t vaddr) = 0;
     virtual void do_replace_memory_range(const memory_range_config &new_range) = 0;
     virtual uint64_t do_read_word(uint64_t address) const = 0;
+    virtual void do_write_word(uint64_t address, uint64_t value) = 0;
     virtual machine_config do_get_initial_config() const = 0;
     virtual hash_tree_stats do_get_hash_tree_stats(bool clear) = 0;
     virtual machine_runtime_config do_get_runtime_config() const = 0;
diff --git a/src/jsonrpc-discover.json b/src/jsonrpc-discover.json
index 37611ca58..c8d11396b 100644
--- a/src/jsonrpc-discover.json
+++ b/src/jsonrpc-discover.json
@@ -480,6 +480,35 @@
         }
       }
     },
+    {
+      "name": "machine.write_word",
+      "summary": "Writes a 64-bit word from memory (must be aligned)",
+      "params": [
+        {
+          "name": "address",
+          "description": "Starting physical address of word",
+          "required": true,
+          "schema": {
+            "$ref": "#/components/schemas/UnsignedInteger"
+          }
+        },
+        {
+          "name": "value",
+          "description": "Value of word (little-endian)",
+          "required": true,
+          "schema": {
+            "$ref": "#/components/schemas/UnsignedInteger"
+          }
+        }
+      ],
+      "result": {
+        "name": "status",
+        "description": "True when operation succeeded",
+        "schema": {
+          "type": "boolean"
+        }
+      }
+    },
     {
       "name": "machine.read_memory",
       "summary": "Reads a span of memory from the state (must be contained in the same memory range)",
diff --git a/src/jsonrpc-machine.cpp b/src/jsonrpc-machine.cpp
index 01960d7f1..cd13b10ea 100644
--- a/src/jsonrpc-machine.cpp
+++ b/src/jsonrpc-machine.cpp
@@ -786,6 +786,11 @@ uint64_t jsonrpc_machine::do_read_word(uint64_t address) const {
     return result;
 }
 
+void jsonrpc_machine::do_write_word(uint64_t address, uint64_t value) {
+    bool result = false;
+    request("machine.write_word", std::tie(address, value), result);
+}
+
 hash_tree_stats jsonrpc_machine::do_get_hash_tree_stats(bool clear) {
     hash_tree_stats result{};
     request("machine.get_hash_tree_stats", std::tie(clear), result);
diff --git a/src/jsonrpc-machine.h b/src/jsonrpc-machine.h
index aeb94d944..d6614df1e 100644
--- a/src/jsonrpc-machine.h
+++ b/src/jsonrpc-machine.h
@@ -129,6 +129,7 @@ class jsonrpc_machine final : public i_machine {
     void do_set_runtime_config(const machine_runtime_config &r) override;
     void do_destroy() override;
     uint64_t do_read_word(uint64_t address) const override;
+    void do_write_word(uint64_t address, uint64_t value) override;
     machine_config do_get_initial_config() const override;
     hash_tree_stats do_get_hash_tree_stats(bool clear) override;
     bool do_verify_hash_tree() const override;
diff --git a/src/jsonrpc-remote-machine.cpp b/src/jsonrpc-remote-machine.cpp
index a194716b3..0777ba59d 100644
--- a/src/jsonrpc-remote-machine.cpp
+++ b/src/jsonrpc-remote-machine.cpp
@@ -1175,6 +1175,22 @@ static json jsonrpc_machine_read_word_handler(const json &j, const std::shared_p
     return jsonrpc_response_ok(j, session->handler->machine->read_word(address));
 }
 
+/// \brief JSONRPC handler for the machine.write_word method
+/// \param j JSON request object
+/// \param session HTTP session
+/// \returns JSON response object
+static json jsonrpc_machine_write_word_handler(const json &j, const std::shared_ptr<http_session> &session) {
+    if (!session->handler->machine) {
+        return jsonrpc_response_invalid_request(j, "no machine");
+    }
+    static const char *param_name[] = {"address", "value"};
+    auto args = parse_args<uint64_t, uint64_t>(j, param_name);
+    auto address = std::get<0>(args);
+    auto value = std::get<1>(args);
+    session->handler->machine->write_word(address, value);
+    return jsonrpc_response_ok(j);
+}
+
 /// \brief JSONRPC handler for the machine.read_memory method
 /// \param j JSON request object
 /// \param session HTTP session
@@ -1507,6 +1523,7 @@ static json jsonrpc_dispatch_method(const json &j, const std::shared_ptr<http_se
         {"machine.get_proof", jsonrpc_machine_get_proof_handler},
         {"machine.get_root_hash", jsonrpc_machine_get_root_hash_handler},
         {"machine.read_word", jsonrpc_machine_read_word_handler},
+        {"machine.write_word", jsonrpc_machine_write_word_handler},
         {"machine.read_memory", jsonrpc_machine_read_memory_handler},
         {"machine.write_memory", jsonrpc_machine_write_memory_handler},
         {"machine.read_virtual_memory", jsonrpc_machine_read_virtual_memory_handler},
diff --git a/src/local-machine.cpp b/src/local-machine.cpp
index 00d95d1b2..074f85bab 100644
--- a/src/local-machine.cpp
+++ b/src/local-machine.cpp
@@ -138,6 +138,10 @@ uint64_t local_machine::do_read_word(uint64_t address) const {
     return get_machine()->read_word(address);
 }
 
+void local_machine::do_write_word(uint64_t address, uint64_t value) {
+    get_machine()->write_word(address, value);
+}
+
 hash_tree_stats local_machine::do_get_hash_tree_stats(bool clear) {
     return get_machine()->get_hash_tree_stats(clear);
 }
diff --git a/src/local-machine.h b/src/local-machine.h
index ced33649a..619e2007f 100644
--- a/src/local-machine.h
+++ b/src/local-machine.h
@@ -67,6 +67,7 @@ class local_machine : public i_machine {
     uint64_t do_translate_virtual_address(uint64_t vaddr) override;
     void do_replace_memory_range(const memory_range_config &new_range) override;
     uint64_t do_read_word(uint64_t address) const override;
+    void do_write_word(uint64_t address, uint64_t value) override;
     machine_config do_get_initial_config() const override;
     hash_tree_stats do_get_hash_tree_stats(bool clear) override;
     machine_runtime_config do_get_runtime_config() const override;
diff --git a/src/machine-c-api.cpp b/src/machine-c-api.cpp
index 23bc9a6b5..b62516dcb 100644
--- a/src/machine-c-api.cpp
+++ b/src/machine-c-api.cpp
@@ -906,6 +906,13 @@ cm_error cm_read_word(const cm_machine *m, uint64_t address, uint64_t *val) try
     }
     return cm_result_failure();
 }
+cm_error cm_write_word(cm_machine *m, uint64_t address, uint64_t val) try {
+    auto *cpp_m = convert_from_c(m);
+    cpp_m->write_word(address, val);
+    return cm_result_success();
+} catch (...) {
+    return cm_result_failure();
+}
 
 cm_error cm_read_memory(const cm_machine *m, uint64_t paddr, uint8_t *data, uint64_t length) try {
     const auto *cpp_m = convert_from_c(m);
diff --git a/src/machine-c-api.h b/src/machine-c-api.h
index b59d43a8a..b8ad27c53 100644
--- a/src/machine-c-api.h
+++ b/src/machine-c-api.h
@@ -524,22 +524,30 @@ CM_API cm_error cm_get_proof(const cm_machine *m, uint64_t address, int32_t log2
 /// \brief Reads the value of a word in the machine state, by its physical address.
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
 /// \param address Word address (aligned to 64-bit boundary).
-/// \param val Receives word value.
+/// \param val Receives word value (little-endian).
 /// \returns 0 for success, non zero code for error.
 /// \warning The implementation is slow when the word falls in a memory range mapped to a device.
 CM_API cm_error cm_read_word(const cm_machine *m, uint64_t address, uint64_t *val);
 
+/// \brief Writes the value of a word in the machine state, by its physical address.
+/// \param m Pointer to a non-empty machine object (holds a machine instance).
+/// \param address Word address (aligned to 64-bit boundary).
+/// \param val Word value to write (little-endian).
+/// \returns 0 for success, non zero code for error.
+/// \warning The implementation is slow when the word falls in a memory range mapped to a device.
+CM_API cm_error cm_write_word(cm_machine *m, uint64_t address, uint64_t val);
+
 /// \brief Reads the value of a register.
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
 /// \param reg Register to read.
-/// \param val Receives the value.
+/// \param val Receives the value (little-endian).
 /// \returns 0 for success, non zero code for error.
 CM_API cm_error cm_read_reg(const cm_machine *m, cm_reg reg, uint64_t *val);
 
 /// \brief Writes the value of a register.
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
 /// \param reg Register to write.
-/// \param val Value to write.
+/// \param val Value to write (little-endian).
 /// \returns 0 for success, non zero code for error.
 CM_API cm_error cm_write_reg(cm_machine *m, cm_reg reg, uint64_t val);
 
diff --git a/tests/lua/machine-bind.lua b/tests/lua/machine-bind.lua
index f635265cd..01791c517 100755
--- a/tests/lua/machine-bind.lua
+++ b/tests/lua/machine-bind.lua
@@ -280,9 +280,12 @@ do_test("machine should have default config shadow register values", function(ma
     initial_reg_values.mvendorid = nil
     initial_reg_values.marchid = nil
     initial_reg_values.mimpid = nil
+    initial_reg_values.x0 = nil
     -- Check initialization and shadow reads
     for k, v in pairs(initial_reg_values) do
         assert(v == machine:read_word(machine:get_reg_address(k)))
+        machine:write_word(machine:get_reg_address(k), ~v)
+        assert(~v == machine:read_word(machine:get_reg_address(k)))
     end
 end)
 
diff --git a/tests/misc/test-machine-c-api.cpp b/tests/misc/test-machine-c-api.cpp
index 62f7cbf5a..ab84b48df 100644
--- a/tests/misc/test-machine-c-api.cpp
+++ b/tests/misc/test-machine-c-api.cpp
@@ -468,6 +468,11 @@ BOOST_AUTO_TEST_CASE_NOLINT(read_word_null_machine_test) {
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 }
 
+BOOST_AUTO_TEST_CASE_NOLINT(write_word_null_machine_test) {
+    cm_error error_code = cm_write_word(nullptr, 0x100, 0);
+    BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
+}
+
 BOOST_FIXTURE_TEST_CASE_NOLINT(read_word_invalid_address_test, ordinary_machine_fixture) {
     uint64_t word_value = 0;
     cm_error error_code = cm_read_word(_machine, 0xffffffff, &word_value);
@@ -478,6 +483,15 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(read_word_invalid_address_test, ordinary_machine_
     BOOST_CHECK_EQUAL(origin, result);
 }
 
+BOOST_FIXTURE_TEST_CASE_NOLINT(write_word_invalid_address_test, ordinary_machine_fixture) {
+    cm_error error_code = cm_write_word(_machine, 0xffffffff, 0);
+    BOOST_CHECK_EQUAL(error_code, CM_ERROR_DOMAIN_ERROR);
+
+    std::string result = cm_get_last_error_message();
+    std::string origin("attempted misaligned write to word");
+    BOOST_CHECK_EQUAL(origin, result);
+}
+
 BOOST_FIXTURE_TEST_CASE_NOLINT(read_word_null_output_test, default_machine_fixture) {
     cm_error error_code = cm_read_word(_machine, 0x100, nullptr);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
@@ -557,10 +571,8 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(read_write_word_basic_test, ordinary_machine_fixt
     uint64_t read_value = 0;
     uint64_t write_value = 0x1234;
     uint64_t address = 0x80000000;
-    std::array<uint8_t, sizeof(uint64_t)> write_data{};
-    memcpy(write_data.data(), &write_value, write_data.size());
 
-    cm_error error_code = cm_write_memory(_machine, address, write_data.data(), write_data.size());
+    cm_error error_code = cm_write_word(_machine, address, write_value);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_OK);
     BOOST_CHECK_EQUAL(std::string(""), std::string(cm_get_last_error_message()));
 

From d3136dec4f05c1d3034deb43d73bc07a066b41f9 Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Tue, 29 Apr 2025 18:52:52 -0300
Subject: [PATCH 49/82] feat: support loading processor state in the cli

---
 src/cartesi-machine.lua             | 258 ++++++++++++++--------------
 src/cartesi/util.lua                |  33 +++-
 tests/Makefile                      |   2 +-
 tests/lua/cartesi-machine-tests.lua |   7 +-
 tests/lua/machine-bind.lua          |  10 +-
 5 files changed, 165 insertions(+), 145 deletions(-)

diff --git a/src/cartesi-machine.lua b/src/cartesi-machine.lua
index 73e1b6d78..6a33ed7c5 100755
--- a/src/cartesi-machine.lua
+++ b/src/cartesi-machine.lua
@@ -198,6 +198,8 @@ where options are:
         data_filename:<filename>
         dht_filename:<filename>
         shared
+        create
+        truncate
 
     semantics are the same as for the --flash-drive option.
 
@@ -641,7 +643,6 @@ local flash_mount = {}
 local flash_user = {}
 local flash_start = {}
 local flash_length = {}
-local unreproducible = false
 local virtio = {}
 local virtio_net_user_config
 local virtio_volume_count = 0
@@ -651,7 +652,10 @@ local has_sync_init_date = false
 local memory_range_replace = {}
 local ram = {
     length = 128 << 20, -- 128MB
-    backing_store = { data_filename = images_path .. "linux.bin" },
+    backing_store = {
+        data_filename = images_path .. "linux.bin",
+        dht_filename = "",
+    },
 }
 local init_splash = true
 local append_bootargs = ""
@@ -669,10 +673,27 @@ local cmio = {
 }
 local cmio_advance
 local cmio_inspect
+local processor = {
+    registers = {
+        iunrep = 0,
+        htif = {
+            iconsole = cartesi.HTIF_CONSOLE_CMD_PUTCHAR_MASK,
+            iyield = cartesi.HTIF_YIELD_CMD_AUTOMATIC_MASK | cartesi.HTIF_YIELD_CMD_MANUAL_MASK,
+        },
+    },
+}
 local uarch = {
+    processor = {
+        registers = {},
+        backing_store = {
+            data_filename = "",
+            dht_filename = "",
+        },
+    },
     ram = {
         backing_store = {
             data_filename = "",
+            dht_filename = "",
         },
     },
 }
@@ -685,9 +706,6 @@ local skip_root_hash_check = false
 local skip_root_hash_store = false
 local skip_version_check = false
 local htif_no_console_putchar = false
-local htif_console_getchar = false
-local htif_yield_automatic = true
-local htif_yield_manual = true
 local initial_hash = false
 local final_hash = false
 local initial_proof = {}
@@ -715,43 +733,39 @@ local assert_rolling_template = false
 local log_step_mcycle_count
 local log_step_filename
 
-local function parse_memory_range(opts, what, all)
-    local f = util.parse_options(opts, {
-        data_filename = true,
-        dht_filename = true,
-        shared = true,
-        length = true,
-        start = true,
+local function parse_memory_range(opts, all)
+    local f = util.parse_options(opts, all, {
+        data_filename = "string",
+        dht_filename = "string",
+        shared = "boolean",
+        create = "boolean",
+        truncate = "boolean",
+        length = "number",
+        start = "number",
     })
-    if f.data_filename == true then f.backing_filename = "" end
-    if f.dense_hashdense_tree_filename == true then f.dht_filename = "" end
-    if f.shared == nil or f.shared == "false" then f.shared = false end
-    if f.shared == "true" then f.shared = true end
-    assert(type(f.shared) == "boolean", "invalid " .. what .. " shared value in " .. all)
     f.backing_store = {
-        data_filename = f.data_filename,
-        dht_filename = f.dht_filename,
+        data_filename = f.data_filename or "",
+        dht_filename = f.dht_filename or "",
         shared = f.shared,
+        create = f.create,
+        truncate = f.truncate,
     }
     f.data_filename = nil
     f.dht_filename = nil
     f.shared = nil
-    f.start = assert(util.parse_number(f.start), "invalid " .. what .. " start in " .. all)
-    f.length = assert(util.parse_number(f.length), "invalid " .. what .. " length in " .. all)
+    f.create = nil
+    f.truncate = nil
     return f
 end
 
-local function parse_backing_store(opts, what, all, def)
-    local f = util.parse_options(opts, {
-        data_filename = true,
-        dht_filename = true,
-        shared = true,
+local function parse_backing_store(opts, all, def)
+    local f = util.parse_options(opts, all, {
+        data_filename = "string",
+        dht_filename = "string",
+        shared = "boolean",
+        create = "boolean",
+        truncate = "boolean",
     })
-    if f.data_filename == true then f.data_filename = "" end
-    if f.dht_filename == true then f.dht_filename = "" end
-    if f.shared == nil or f.shared == "false" then f.shared = false end
-    if f.shared == "true" then f.shared = true end
-    assert(type(f.shared) == "boolean", "invalid " .. what .. " shared value in " .. all)
     if def then
         for i, v in pairs(def) do
             if f[i] == nil then f[i] = v end
@@ -762,7 +776,7 @@ end
 
 local function handle_sync_init_date()
     if has_sync_init_date then return true end
-    unreproducible = true
+    processor.registers.iunrep = 1
     has_sync_init_date = true
     -- round up time by 1, to decrease chance of guest time being in the past
     local seconds = os.time() + 1
@@ -771,13 +785,13 @@ local function handle_sync_init_date()
 end
 
 local function handle_virtio_9p(tag, host_directory)
-    unreproducible = true
+    processor.registers.iunrep = 1
     table.insert(virtio, { type = "p9fs", tag = tag, host_directory = host_directory })
     return true
 end
 
 local function handle_volume_option(host_directory, guest_directory)
-    unreproducible = true
+    processor.registers.iunrep = 1
     local tag = "vfs" .. virtio_volume_count
     virtio_volume_count = virtio_volume_count + 1
     table.insert(virtio, { type = "p9fs", tag = tag, host_directory = host_directory })
@@ -789,8 +803,8 @@ local function handle_volume_option(host_directory, guest_directory)
 end
 
 local function handle_htif_console_getchar()
-    htif_console_getchar = true
-    unreproducible = true
+    processor.registers.htif.iconsole = processor.registers.htif.iconsole | cartesi.HTIF_CONSOLE_CMD_GETCHAR_MASK
+    processor.registers.iunrep = 1
     return true
 end
 
@@ -862,7 +876,7 @@ end
 
 local function handle_virtio_net(mode, opts)
     if not mode then return false end
-    unreproducible = true
+    processor.registers.iunrep = 1
     if mode == "user" then
         if not virtio_net_user_config then
             virtio_net_user_config = { type = "net-user" }
@@ -894,7 +908,7 @@ end
 
 local function handle_virtio_console()
     if has_virtio_console then return true end
-    unreproducible = true
+    processor.registers.iunrep = 1
     has_virtio_console = true
     -- Switch from HTIF Console (hvc0) to VirtIO console (hvc1)
     dtb.bootargs = dtb.bootargs:gsub("console=hvc0", "console=hvc1")
@@ -1006,7 +1020,21 @@ local options = {
     {
         "^(%-%-dtb%=(.+))$",
         function(all, opts)
-            dtb.backing_store = parse_backing_store(opts, "dtb", all, dtb.backing_store)
+            dtb.backing_store = parse_backing_store(opts, all, dtb.backing_store)
+            return true
+        end,
+    },
+    {
+        "^(%-%-processor%=(.+))$",
+        function(all, opts)
+            processor.backing_store = parse_backing_store(opts, all, processor.backing_store)
+            return true
+        end,
+    },
+    {
+        "^(%-%-uarch%-processor%=(.+))$",
+        function(all, opts)
+            uarch.processor.backing_store = parse_backing_store(opts, all, uarch.processor.backing_store)
             return true
         end,
     },
@@ -1034,14 +1062,14 @@ local options = {
     {
         "^(%-%-ram%=(.+))$",
         function(all, opts)
-            ram.backing_store = parse_backing_store(opts, "ram", all, ram.backing_store)
+            ram.backing_store = parse_backing_store(opts, all, ram.backing_store)
             return true
         end,
     },
     {
         "^(%-%-pmas%=(.+))$",
         function(all, opts)
-            pmas.backing_store = parse_backing_store(opts, "pmas", all, pmas.backing_store)
+            pmas.backing_store = parse_backing_store(opts, all, pmas.backing_store)
             return true
         end,
     },
@@ -1055,27 +1083,23 @@ local options = {
     {
         "^(%-%-uarch%-ram%=(.+))$",
         function(all, opts)
-            uarch.ram.backing_store = parse_backing_store(opts, "uarch-ram", all, uarch.ram.backing_store)
+            uarch.ram.backing_store = parse_backing_store(opts, all, uarch.ram.backing_store)
             return true
         end,
     },
     {
         "^(%-%-hash%-tree%=(.+))$",
         function(all, opts)
-            local h = util.parse_options(opts, {
-                hasher = true,
-                sht_filename = true,
-                phtc_filename = true,
-                phtc_size = true,
-                shared = true,
+            local h = util.parse_options(opts, all, {
+                hasher = "string",
+                sht_filename = "string",
+                phtc_filename = "string",
+                phtc_size = "number",
+                shared = "boolean",
             })
-            if h.sht_filename == true then h.sht_filename = "" end
-            if h.phtc_filename == true then h.phtc_filename = "" end
-            if h.hasher == true then h.hasher = "keccak" end
-            if h.shared == nil or h.shared == "false" then h.shared = false end
-            if h.shared == "true" then h.shared = true end
-            h.phtc_size = assert(util.parse_number(h.phtc_size), "invalid page hash cache size in " .. all)
-            assert(type(h.shared) == "boolean", "invalid hash tree shared value in " .. all)
+            h.sht_filename = h.sht_filename or ""
+            h.phtc_filename = h.phtc_filename or ""
+            h.hasher = h.hasher or "keccak"
             for i, v in pairs(h) do
                 hash_tree[i] = v
             end
@@ -1085,7 +1109,7 @@ local options = {
     {
         "^%-%-unreproducible$",
         function()
-            unreproducible = true
+            processor.registers.iunrep = 1
             return true
         end,
     },
@@ -1145,7 +1169,7 @@ local options = {
         "^%-%-no%-htif%-yield%-manual$",
         function(all)
             if not all then return false end
-            htif_yield_manual = false
+            processor.registers.htif.iyield = processor.registers.htif.iyield & ~cartesi.HTIF_YIELD_CMD_MANUAL_MASK
             return true
         end,
     },
@@ -1153,33 +1177,29 @@ local options = {
         "^%-%-no%-htif%-yield%-automatic$",
         function(all)
             if not all then return false end
-            htif_yield_automatic = false
+            processor.registers.htif.iyield = processor.registers.htif.iyield & ~cartesi.HTIF_YIELD_CMD_AUTOMATIC_MASK
             return true
         end,
     },
     {
         "^(%-%-flash%-drive%=(.+))$",
         function(all, opts)
-            local f = util.parse_options(opts, {
-                label = true,
-                data_filename = true,
-                dht_filename = true,
-                shared = true,
-                create = true,
-                truncate = true,
-                read_only = true,
-                mount = true,
-                user = true,
-                length = true,
-                start = true,
+            local f = util.parse_options(opts, all, {
+                label = "string",
+                data_filename = "string",
+                dht_filename = "string",
+                shared = "boolean",
+                create = "boolean",
+                truncate = "boolean",
+                read_only = "boolean",
+                mount = "boolean",
+                user = "string",
+                length = "number",
+                start = "number",
             })
             assert(f.label, "missing flash drive label in " .. all)
-            if f.data_filename == true then f.data_filename = "" end
-            if f.dht_filename == true then f.dht_filename = "" end
-            assert(not f.shared or f.shared == true, "invalid flash drive shared value in " .. all)
-            assert(not f.create or f.create == true, "invalid flash drive create value in " .. all)
-            assert(not f.truncate or f.truncate == true, "invalid flash drive read_only value in " .. all)
-            assert(not f.read_only or f.read_only == true, "invalid flash drive truncate value in " .. all)
+            f.data_filename = f.data_filename or ""
+            f.dht_filename = f.dht_filename or ""
             if f.mount == nil then
                 -- mount only if there is a file backing
                 if f.data_filename and f.data_filename ~= "" then
@@ -1187,13 +1207,11 @@ local options = {
                 else
                     f.mount = false
                 end
-            elseif f.mount == "true" then
+            elseif f.mount == true then
                 f.mount = "/mnt/" .. f.label
-            elseif f.mount == "false" then
+            elseif f.mount == false then
                 f.mount = false
             end
-            if f.start then f.start = assert(util.parse_number(f.start), "invalid flash drive start in " .. all) end
-            if f.length then f.length = assert(util.parse_number(f.length), "invalid flash drive length in " .. all) end
             local d = f.label
             if not flash_data_filename[d] then
                 flash_label_order[#flash_label_order + 1] = d
@@ -1218,35 +1236,32 @@ local options = {
     {
         "^(%-%-replace%-flash%-drive%=(.+))$",
         function(all, opts)
-            memory_range_replace[#memory_range_replace + 1] = parse_memory_range(opts, "flash drive", all)
+            memory_range_replace[#memory_range_replace + 1] = parse_memory_range(opts, all)
             return true
         end,
     },
     {
         "^(%-%-replace%-memory%-range%=(.+))$",
         function(all, opts)
-            memory_range_replace[#memory_range_replace + 1] = parse_memory_range(opts, "memory range", all)
+            memory_range_replace[#memory_range_replace + 1] = parse_memory_range(opts, all)
             return true
         end,
     },
     {
         "^(%-%-cmio%-advance%-state%=(.+))$",
         function(all, opts)
-            local r = util.parse_options(opts, {
-                input = true,
-                input_index_begin = true,
-                input_index_end = true,
-                output_hashes_root_hash = true,
-                output = true,
-                report = true,
-                hashes = true,
+            local r = util.parse_options(opts, all, {
+                input = "string",
+                input_index_begin = "number",
+                input_index_end = "number",
+                output_hashes_root_hash = "string",
+                output = "string",
+                report = "string",
+                hashes = "boolean",
             })
-            assert(not r.hashes or r.hashes == true, "invalid hashes value in " .. all)
             r.input = r.input or "input-%i.bin"
             r.input_index_begin = r.input_index_begin or 0
-            r.input_index_begin = assert(util.parse_number(r.input_index_begin), "invalid input index begin in " .. all)
             r.input_index_end = r.input_index_end or 0
-            r.input_index_end = assert(util.parse_number(r.input_index_end), "invalid input index end in " .. all)
             r.output = r.output or "input-%i-output-%o.bin"
             r.report = r.report or "input-%i-report-%o.bin"
             r.output_hashes_root_hash = r.output_hashes_root_hash or "input-%i-output-hahes-root-hash.bin"
@@ -1256,12 +1271,12 @@ local options = {
         end,
     },
     {
-        "^%-%-cmio%-inspect%-state%=(.+)$",
-        function(opts)
-            local r = util.parse_options(opts, {
-                query = true,
-                report = true,
-                hashes = true,
+        "^(%-%-cmio%-inspect%-state%=(.+))$",
+        function(all, opts)
+            local r = util.parse_options(opts, all, {
+                query = "string",
+                report = "string",
+                hashes = "boolean",
             })
             r.query = r.query or "query.bin"
             r.report = r.report or "query-report-%o.bin"
@@ -1283,11 +1298,10 @@ local options = {
     {
         "^(%-%-concurrency%=(.+))$",
         function(all, opts)
-            local c = util.parse_options(opts, {
-                update_hash_tree = true,
+            local c = util.parse_options(opts, all, {
+                update_hash_tree = "number",
             })
-            c.update_hash_tree =
-                assert(util.parse_number(c.update_hash_tree), "invalid update_hash_tree number in " .. all)
+            c.update_hash_tree = assert(c.update_hash_tree, "invalid update_hash_tree number in " .. all)
             concurrency_update_hash_tree = c.update_hash_tree
             return true
         end,
@@ -1327,14 +1341,12 @@ local options = {
     {
         "^(%-%-initial%-proof%=(.+))$",
         function(all, opts)
-            local p = util.parse_options(opts, {
-                address = true,
-                log2_size = true,
-                filename = true,
+            local p = util.parse_options(opts, all, {
+                address = "number",
+                log2_size = "number",
+                filename = "string",
             })
             p.cmdline = all
-            p.address = assert(util.parse_number(p.address), "invalid address in " .. all)
-            p.log2_size = assert(util.parse_number(p.log2_size), "invalid log2_size in " .. all)
             assert(p.log2_size >= 3, "log2_size must be at least 3 in " .. all)
             initial_proof[#initial_proof + 1] = p
             return true
@@ -1344,14 +1356,12 @@ local options = {
         "^(%-%-final%-proof%=(.+))$",
         function(all, opts)
             if not opts then return false end
-            local p = util.parse_options(opts, {
-                address = true,
-                log2_size = true,
-                filename = true,
+            local p = util.parse_options(opts, all, {
+                address = "number",
+                log2_size = "number",
+                filename = "string",
             })
             p.cmdline = all
-            p.address = assert(util.parse_number(p.address), "invalid address in " .. all)
-            p.log2_size = assert(util.parse_number(p.log2_size), "invalid log2_size in " .. all)
             assert(p.log2_size >= 3, "log2_size must be at least 3 in " .. all)
             final_proof[#final_proof + 1] = p
             return true
@@ -1634,8 +1644,7 @@ local options = {
         "^(%-%-cmio%-rx%-buffer%=(.+))$",
         function(all, opts)
             if not opts then return false end
-            cmio.rx_buffer.backing_store =
-                parse_backing_store(opts, "cmio rx buffer", all, cmio.rx_buffer.backing_store)
+            cmio.rx_buffer.backing_store = parse_backing_store(opts, all, cmio.rx_buffer.backing_store)
             return true
         end,
     },
@@ -1643,8 +1652,7 @@ local options = {
         "^(%-%-cmio%-tx%-buffer%=(.+))$",
         function(all, opts)
             if not opts then return false end
-            cmio.tx_buffer.backing_store =
-                parse_backing_store(opts, "cmio tx buffer", all, cmio.tx_buffer.backing_store)
+            cmio.tx_buffer.backing_store = parse_backing_store(opts, all, cmio.tx_buffer.backing_store)
             return true
         end,
     },
@@ -1855,17 +1863,7 @@ elseif load_dir then
 else
     -- Build machine config
     local config = {
-        processor = {
-            registers = {
-                iunrep = unreproducible and 1 or 0,
-                htif = {
-                    iconsole = (htif_console_getchar and cartesi.HTIF_CONSOLE_CMD_GETCHAR_MASK or 0)
-                        | cartesi.HTIF_CONSOLE_CMD_PUTCHAR_MASK,
-                    iyield = (htif_yield_automatic and cartesi.HTIF_YIELD_CMD_AUTOMATIC_MASK or 0)
-                        | (htif_yield_manual and cartesi.HTIF_YIELD_CMD_MANUAL_MASK or 0),
-                },
-            },
-        },
+        processor = processor,
         ram = ram,
         dtb = dtb,
         flash_drive = {},
diff --git a/src/cartesi/util.lua b/src/cartesi/util.lua
index d80d5d0d6..0f820412e 100644
--- a/src/cartesi/util.lua
+++ b/src/cartesi/util.lua
@@ -163,7 +163,16 @@ function _M.parse_number(n)
     return nil
 end
 
-function _M.parse_options(s, keys)
+function _M.parse_boolean(b)
+    if b == "true" or b == true then
+        return true
+    elseif b == "false" or b == false then
+        return false
+    end
+    return nil
+end
+
+function _M.parse_options(s, all, keys)
     local function escape(v)
         -- replace escaped \, :, and , with something "safe"
         v = string.gsub(v, "%\\%\\", "\0")
@@ -184,14 +193,30 @@ function _M.parse_options(s, keys)
             v = unescape(v)
         else
             k = unescape(o)
-            v = true
+            v = nil
         end
-        assert(keys[k], string.format("unknown option '%q'", k))
+        assert(keys[k], string.format("unknown option %q in '%s'", k, all))
         if keys[k] == "array" then
             options[k] = options[k] or {}
             table.insert(options[k], v)
-        else
+        elseif keys[k] == "boolean" then
+            if v == nil then
+                v = true
+            else
+                v = _M.parse_boolean(v)
+                if v == nil then error(string.format("invalid boolean for option %q in '%s'", k, all)) end
+            end
+            options[k] = v
+        elseif keys[k] == "number" then
+            v = _M.parse_number(v)
+            if v == nil then error(string.format("invalid number for option %q in '%s'", k, all)) end
+            options[k] = v
+        elseif keys[k] == "string" then
+            if v == nil then error(string.format("missing string for option %q in '%s'", k, all)) end
             options[k] = v
+        elseif type(keys[k]) == "table" then
+            if not keys[k][v] then error(string.format("invalid value for option %q in '%s'", k, all)) end
+            options[k] = keys[k][v]
         end
     end)
     return options
diff --git a/tests/Makefile b/tests/Makefile
index 07d006819..b731f638f 100644
--- a/tests/Makefile
+++ b/tests/Makefile
@@ -194,7 +194,7 @@ test-hash-tree:
 	$(LUA) ./lua/hash-tree.lua
 
 test-uarch-compare:
-	$(LUA) ./lua/cartesi-machine-tests.lua --test="^rv64ui.*$$" --concurrency=update_merkle_tree:1 --jobs=$(NUM_JOBS) run_host_and_uarch
+	$(LUA) ./lua/cartesi-machine-tests.lua --test="^rv64ui.*$$" --concurrency=update_hash_tree:1 --jobs=$(NUM_JOBS) run_host_and_uarch
 
 test-uarch-rv64ui:
 	$(LUA) ./lua/uarch-riscv-tests.lua --jobs=$(NUM_JOBS) run
diff --git a/tests/lua/cartesi-machine-tests.lua b/tests/lua/cartesi-machine-tests.lua
index 11ee32934..c23f4c7a6 100755
--- a/tests/lua/cartesi-machine-tests.lua
+++ b/tests/lua/cartesi-machine-tests.lua
@@ -519,11 +519,10 @@ local options = {
             if not opts then
                 return false
             end
-            local c = util.parse_options(opts, {
-                update_hash_tree = true,
+            local c = util.parse_options(opts, all, {
+                update_hash_tree = "number",
             })
-            c.update_hash_tree =
-                assert(util.parse_number(c.update_hash_tree), "invalid update_hash_tree number in " .. all)
+            c.update_hash_tree = assert(c.update_hash_tree, "invalid update_hash_tree number in " .. all)
             concurrency_update_hash_tree = c.update_hash_tree
             return true
         end,
diff --git a/tests/lua/machine-bind.lua b/tests/lua/machine-bind.lua
index 01791c517..bae46af1f 100755
--- a/tests/lua/machine-bind.lua
+++ b/tests/lua/machine-bind.lua
@@ -23,7 +23,7 @@ local jsonrpc
 
 local remote_address
 local test_path = "./"
-local concurrency_update_hash_tree = util.parse_number(os.getenv("CARTESI_CONCURRENCY_UPDATE_MERKLE_TREE")) or 0
+local concurrency_update_hash_tree = util.parse_number(os.getenv("CARTESI_CONCURRENCY_UPDATE_HASH_TREE")) or 0
 
 local lua_cmd = arg[-1] .. " -e "
 
@@ -114,12 +114,10 @@ local options = {
             if not opts then
                 return false
             end
-            local c = util.parse_options(opts, {
-                update_hash_tree = true,
+            local c = util.parse_options(opts, all, {
+                update_hash_tree = "number",
             })
-            c.update_hash_tree =
-                assert(util.parse_number(c.update_hash_tree), "invalid update_hash_tree number in " .. all)
-            concurrency_update_hash_tree = c.update_hash_tree
+            c.update_hash_tree = assert(c.update_hash_tree, "invalid update_hash_tree number in " .. all)
             return true
         end,
     },

From c410dbfbf823d82c6140865e8821a9ca690d1b2a Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Thu, 15 May 2025 08:28:32 -0300
Subject: [PATCH 50/82] feat: add possibility to auto format ext2 filesystem on
 init

---
 .typos.toml             |  1 +
 src/cartesi-machine.lua | 38 ++++++++++++++++++++++++++++++--------
 src/cartesi/util.lua    |  2 ++
 3 files changed, 33 insertions(+), 8 deletions(-)

diff --git a/.typos.toml b/.typos.toml
index 66118197f..4f2054dcd 100644
--- a/.typos.toml
+++ b/.typos.toml
@@ -10,3 +10,4 @@ wronly = "wronly"
 optin = "optin"
 sxl = "sxl"
 nd = "nd"
+mke = "mke"
diff --git a/src/cartesi-machine.lua b/src/cartesi-machine.lua
index 6a33ed7c5..b371882e2 100755
--- a/src/cartesi-machine.lua
+++ b/src/cartesi-machine.lua
@@ -110,11 +110,13 @@ where options are:
         create
         truncate
         read_only
+        mke2fs
         mount:<string>
         user:<string>
 
-        label (mandatory)
+        label (optional)
         identifies the flash drive. init attempts to mount it as /mnt/<label>.
+        if omitted, the label is set to "driveX", where X starts at 1.
 
         start (optional)
         sets the starting physical memory offset for flash drive in bytes.
@@ -152,9 +154,14 @@ where options are:
         mark flash drive as read-only, disallowing write attempts from the host or the guest.
         by default, flash drives are not read-only, thus writable.
 
+        mke2fs (optional)
+        whether the flash drive should be formatted as an ext2 filesystem in init.
+        by default, the drive is formatted as ext2 filesystem if there is no backing file,
+        you can use "mke2fs:false" to disables ext2 formatting.
+
         mount (optional)
         whether the flash drive should be mounted automatically in init.
-        by default, the drive is mounted if there is an image file backing it,
+        by default, the drive is mounted if there is an image file backing it or is formatted (mke2fs option),
         you can use "mount:false" to disables auto mounting,
         you can also use "mount:<path>" to choose a custom mount point.
 
@@ -640,6 +647,7 @@ local flash_create = {}
 local flash_truncate = {}
 local flash_read_only = {}
 local flash_mount = {}
+local flash_mke2fs = {}
 local flash_user = {}
 local flash_start = {}
 local flash_length = {}
@@ -1192,24 +1200,26 @@ local options = {
                 create = "boolean",
                 truncate = "boolean",
                 read_only = "boolean",
-                mount = "boolean",
+                mount = "string",
+                mke2fs = "boolean",
                 user = "string",
                 length = "number",
                 start = "number",
             })
-            assert(f.label, "missing flash drive label in " .. all)
+            if f.label == nil then f.label = "drive" .. #flash_label_order end
             f.data_filename = f.data_filename or ""
             f.dht_filename = f.dht_filename or ""
+            if f.mke2fs == nil then f.mke2fs = f.data_filename == "" end
             if f.mount == nil then
                 -- mount only if there is a file backing
-                if f.data_filename and f.data_filename ~= "" then
+                if f.data_filename ~= "" or f.mke2fs then
                     f.mount = "/mnt/" .. f.label
                 else
                     f.mount = false
                 end
-            elseif f.mount == true then
+            elseif f.mount == "true" then
                 f.mount = "/mnt/" .. f.label
-            elseif f.mount == false then
+            elseif f.mount == "false" then
                 f.mount = false
             end
             local d = f.label
@@ -1226,6 +1236,7 @@ local options = {
             flash_truncate[d] = f.truncate or flash_truncate[d]
             flash_read_only[d] = f.read_only or flash_read_only[d]
             flash_mount[d] = f.mount or flash_mount[d]
+            flash_mke2fs[d] = f.mke2fs or flash_mke2fs[d]
             flash_user[d] = f.user or flash_user[d]
             if d == "root" and f.read_only then -- Mount root filesystem as read-only
                 dtb.bootargs = dtb.bootargs:gsub("rw", "ro")
@@ -1908,9 +1919,20 @@ echo "
             length = flash_length[label] or -1,
         }
         -- auto mount
+        local mke2fs = flash_mke2fs[label]
+        if label ~= "root" and mke2fs then -- format filesystem
+            local cmd = table.concat({
+                'busybox mke2fs -F -b 4096 -I 256 -L "',
+                label,
+                '" /dev/',
+                devname,
+                " > /dev/null",
+            })
+            config.dtb.init = config.dtb.init .. cmd .. "\n"
+        end
         local mount = flash_mount[label]
         local chownpath = "/dev/" .. devname
-        if label ~= "root" and mount then
+        if label ~= "root" and mount then -- mount filesystem
             local cmd = table.concat({
                 'busybox mkdir -p "',
                 mount,
diff --git a/src/cartesi/util.lua b/src/cartesi/util.lua
index 0f820412e..d7ed6afb8 100644
--- a/src/cartesi/util.lua
+++ b/src/cartesi/util.lua
@@ -152,6 +152,8 @@ function _M.parse_number(n)
         return base << 20
     elseif rest == "Gi" then
         return base << 30
+    elseif rest == "Ti" then
+        return base << 40
     elseif rest == "" then
         return base
     end

From ec38640e69b6e68a28e3748a014a982455327de4 Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Mon, 2 Jun 2025 13:42:04 -0300
Subject: [PATCH 51/82] feat: vectorized Keccak-256 and SHA-256 hashers

---
 LICENSES.md                          |    1 -
 src/Makefile                         |   24 +-
 src/array2d.h                        |   31 +
 src/cartesi/calldata.lua             |    4 +-
 src/cartesi/proof.lua                |    6 +-
 src/circular-buffer.h                |    2 +
 src/clua-cartesi.cpp                 |   65 +-
 src/compiler-defines.h               |   36 +-
 src/hash-tree-stats.h                |    4 +-
 src/hash-tree.cpp                    |  210 ++-
 src/hash-tree.h                      |    8 +-
 src/i-hasher.h                       |   59 +-
 src/is-pristine.cpp                  |   67 +
 src/is-pristine.h                    |   42 +-
 src/json-util.cpp                    |    2 +
 src/jsonrpc-discover.json            |    3 +
 src/keccak-256-hasher.cpp            |  256 +++
 src/keccak-256-hasher.h              |  292 ++-
 src/keccakf.h                        | 2573 ++++++++++++++++++++++++++
 src/machine-config.h                 |    4 +-
 src/machine-hash.h                   |    8 +-
 src/machine.cpp                      |   25 +-
 src/merkle-tree-hash.cpp             |    4 +-
 src/os-features.h                    |    4 +
 src/page-hash-tree-cache-stats.h     |   15 +-
 src/page-hash-tree-cache.h           |  161 +-
 src/pristine-merkle-tree.cpp         |    4 +-
 src/sha-256-hasher.cpp               |  356 ++++
 src/sha-256-hasher.h                 |  202 ++
 src/simd-hasher.h                    |  357 ++++
 src/simd-vector-type.h               |  114 ++
 tests/lua/cartesi/tests/util.lua     |   18 +-
 tests/lua/cmio-test.lua              |    8 +-
 tests/lua/hash-tree.lua              |    6 +-
 tests/misc/Makefile                  |    2 +-
 tests/misc/test-merkle-tree-hash.cpp |    4 +-
 tests/misc/test-utils.h              |    4 +-
 third-party/tiny_sha3/LICENSE        |   22 -
 third-party/tiny_sha3/sha3.c         |  205 --
 third-party/tiny_sha3/sha3.h         |   39 -
 uarch/Makefile                       |    6 +-
 41 files changed, 4692 insertions(+), 561 deletions(-)
 create mode 100644 src/array2d.h
 create mode 100644 src/is-pristine.cpp
 create mode 100644 src/keccak-256-hasher.cpp
 create mode 100644 src/keccakf.h
 create mode 100644 src/sha-256-hasher.cpp
 create mode 100644 src/sha-256-hasher.h
 create mode 100644 src/simd-hasher.h
 create mode 100644 src/simd-vector-type.h
 delete mode 100644 third-party/tiny_sha3/LICENSE
 delete mode 100644 third-party/tiny_sha3/sha3.c
 delete mode 100644 third-party/tiny_sha3/sha3.h

diff --git a/LICENSES.md b/LICENSES.md
index 0c12e43b3..89a7f8ac4 100644
--- a/LICENSES.md
+++ b/LICENSES.md
@@ -12,7 +12,6 @@ This project includes several submodules and dependencies, each with its own lic
 - `third-party/riscv-arch-test`: Source code licensed under the Apache 2.0 and BSD 3-Clause licenses. Documentation under `CC-BY-4.0`. License information is provided in README.md and other COPYING.* files like [third-party/riscv-arch-test/COPYING.APACHE](third-party/riscv-arch-test/COPYING.APACHE).
 - `third-party/riscv-tests`: Licensed under the BSD 3-Clause "New" or "Revised" License. See [third-party/riscv-tests/LICENSE](third-party/riscv-tests/LICENSE) for license details.
 - `third-party/riscv-tests/env`: Licensed under the BSD 3-Clause "New" or "Revised" License. License details are in [third-party/riscv-tests/env/LICENSE](third-party/riscv-tests/env/LICENSE).
-- `third-party/tiny_sha3`: Licensed under the MIT License. The license can be found at [third-party/tiny_sha3/LICENSE](third-party/tiny_sha3/LICENSE).
 - `third-party/nlohmann-json`: Licensed under the MIT License. The license can be found at [third-party/nlohmann-json/LICENSE.MIT](third-party/nlohmann-json/LICENSE.MIT).
 
 ## Debian Packages
diff --git a/src/Makefile b/src/Makefile
index db2098986..54d232b0d 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -164,7 +164,6 @@ CLANG_TIDY_WARNS=-Wthread-safety -Wglobal-constructors
 # Place our include directories before the system's
 INCS+= \
 	-I../third-party/llvm-flang-uint128 \
-	-I../third-party/tiny_sha3 \
 	-I../third-party/nlohmann-json \
 	-I../third-party/downloads \
 	$(BOOST_INC)
@@ -221,8 +220,8 @@ ifneq ($(git_commit),)
 DEFS+=-DGIT_COMMIT='"$(git_commit)"'
 endif
 
-# The SHA3 is third party library we always want to compile with O3
-SHA3_CFLAGS=-O3
+# Hashing libraries have special optimizations flags
+HASH_CFLAGS=-O3 -DNDEBUG -funroll-loops -fno-stack-protector
 
 # Optimization flags for the interpreter
 ifneq (,$(filter yes,$(relwithdebinfo) $(release)))
@@ -370,7 +369,9 @@ LIBCARTESI_OBJS:= \
 	pristine-merkle-tree.o \
 	replay-step-state-access-interop.o \
 	send-cmio-response.o \
-	sha3.o \
+	keccak-256-hasher.o \
+	sha-256-hasher.o \
+	is-pristine.o \
 	uarch-pristine-hash.o \
 	uarch-pristine-ram.o \
 	uarch-pristine-state-hash.o \
@@ -397,7 +398,9 @@ LUACARTESI_OBJS:= \
 	$(CARTESI_CLUA_OBJS)
 
 LIBCARTESI_MERKLE_TREE_OBJS:= \
-	sha3.o \
+	keccak-256-hasher.o \
+	sha-256-hasher.o \
+	is-pristine.o \
 	back-merkle-tree.o \
 	pristine-merkle-tree.o \
 	complete-merkle-tree.o \
@@ -555,8 +558,6 @@ jsonrpc-discover.cpp: jsonrpc-discover.json
 	@$(CC) $(CFLAGS) $< -MM -MT $@ -MF $@.d > /dev/null 2>&1
 	@touch $@
 
-sha3.o: ../third-party/tiny_sha3/sha3.c
-	$(CC) $(CFLAGS) $(SHA3_CFLAGS) -c -o $@ $<
 
 uarch-pristine-ram.o: $(UARCH_PRISTINE_RAM_C)
 	$(CC) $(CFLAGS) -c -o $@ $<
@@ -570,6 +571,15 @@ interpret-jump-table.h: ../tools/gen-interpret-jump-table.lua
 interpret.o: interpret.cpp machine-c-version.h interpret-jump-table.h
 	$(CXX) $(CXXFLAGS) $(INTERPRET_CXXFLAGS) -c -o $@ $<
 
+keccak-256-hasher.o: keccak-256-hasher.cpp
+	$(CXX) $(CXXFLAGS) $(HASH_CFLAGS) -c -o $@ $<
+
+sha-256-hasher.o: sha-256-hasher.cpp
+	$(CXX) $(CXXFLAGS) $(HASH_CFLAGS) -c -o $@ $<
+
+is-pristine.o: is-pristine.cpp
+	$(CXX) $(CXXFLAGS) $(HASH_CFLAGS) -c -o $@ $<
+
 %.o: %.cpp machine-c-version.h
 	$(CXX) $(CXXFLAGS) -c -o $@ $<
 
diff --git a/src/array2d.h b/src/array2d.h
new file mode 100644
index 000000000..91e67aad2
--- /dev/null
+++ b/src/array2d.h
@@ -0,0 +1,31 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef ARRAY2D_H
+#define ARRAY2D_H
+
+#include <array>
+#include <cstddef>
+
+namespace cartesi {
+
+//??(edubart): In future C++ standards we should switch to `std::mdarray` or `std::mdspan`
+template <class T, std::size_t M, std::size_t N>
+using array2d = std::array<std::array<T, N>, M>;
+
+} // namespace cartesi
+
+#endif // ARRAY2D_H
diff --git a/src/cartesi/calldata.lua b/src/cartesi/calldata.lua
index f2245d3f8..513e8f13d 100644
--- a/src/cartesi/calldata.lua
+++ b/src/cartesi/calldata.lua
@@ -20,7 +20,7 @@ local bint = require("bint")(256 + bint_extra)
 
 local P, R, S, C, Ct, V, Cmt, Carg = lpeg.P, lpeg.R, lpeg.S, lpeg.C, lpeg.Ct, lpeg.V, lpeg.Cmt, lpeg.Carg
 local cartesi = require("cartesi")
-local keccak = cartesi.keccak
+local keccak256 = cartesi.keccak256
 
 local tinsert = table.insert
 
@@ -272,7 +272,7 @@ function _M.parse_func_sig(sig)
     local err = { pos = 0, what = "unknown error" }
     local parsed_sig = check_match_error(sig, func_sig:match(sig, 1, err), err)
     local canonic_sig = canonic_func_sig(parsed_sig)
-    local func_sel = keccak(canonic_sig):sub(1, 4)
+    local func_sel = keccak256(canonic_sig):sub(1, 4)
     parsed_func_sig_cache[sig] = {
         parsed_func_sig = parsed_sig,
         func_sel = func_sel,
diff --git a/src/cartesi/proof.lua b/src/cartesi/proof.lua
index 2e661824b..b5f7fb0d5 100644
--- a/src/cartesi/proof.lua
+++ b/src/cartesi/proof.lua
@@ -13,7 +13,7 @@ function _M.roll_hash_up_tree(proof, target_hash)
         else
             first, second = hash, proof.sibling_hashes[i]
         end
-        hash = cartesi.keccak(first, second)
+        hash = cartesi.keccak256(first, second)
     end
     return hash
 end
@@ -26,7 +26,7 @@ end
 function _M.word_slice_assert(root_hash, proof, word)
     assert(proof.log2_target_size == 3, "not a word proof")
     assert(root_hash == proof.root_hash, "proof root_hash mismatch")
-    assert(cartesi.keccak(word) == proof.target_hash, "proof target_hash mismatch")
+    assert(cartesi.keccak256(word) == proof.target_hash, "proof target_hash mismatch")
     assert(_M.roll_hash_up_tree(proof, proof.target_hash) == root_hash, "node not in tree")
 end
 
@@ -37,7 +37,7 @@ end
 
 function _M.word_splice_assert(root_hash, proof, old_word, new_word, new_root_hash)
     _M.word_slice_assert(root_hash, proof, old_word)
-    assert(_M.roll_hash_up_tree(proof, cartesi.keccak(new_word)) == new_root_hash, "new root hash mismatch")
+    assert(_M.roll_hash_up_tree(proof, cartesi.keccak256(new_word)) == new_root_hash, "new root hash mismatch")
 end
 
 return _M
diff --git a/src/circular-buffer.h b/src/circular-buffer.h
index d5e8021c6..4c59d46b9 100644
--- a/src/circular-buffer.h
+++ b/src/circular-buffer.h
@@ -171,10 +171,12 @@ class circular_buffer {
     /// \brief Adds new entry to back of container, if not already there
     /// \tparam U Type for universal reference to value
     /// \param value Value to insert. L-value references are copied, r-value references are moved.
+    /// \details The container must not be full.
     template <typename U>
         requires std::constructible_from<T, U &&> && std::equality_comparable_with<T, U>
     void try_push_back(U &&value) noexcept {
         if (empty() || back() != value) {
+            assert(!full() && "circular buffer container is full");
             push_back(std::forward<U>(value));
         }
     }
diff --git a/src/clua-cartesi.cpp b/src/clua-cartesi.cpp
index 6ec6923a6..74cbc2ac5 100644
--- a/src/clua-cartesi.cpp
+++ b/src/clua-cartesi.cpp
@@ -34,7 +34,9 @@ extern "C" {
 #include "keccak-256-hasher.h"
 #include "machine-c-api.h"
 #include "machine-c-version.h"
+#include "machine-hash.h"
 #include "riscv-constants.h"
+#include "sha-256-hasher.h"
 #include "uarch-constants.h"
 #include "uarch-pristine.h"
 
@@ -58,46 +60,54 @@ static const auto gperf_meta = clua_make_luaL_Reg_array({
 });
 #endif
 
-/// \brief This is the cartesi.keccak() function implementation.
+/// \brief Generic hasher function implementation.
+/// \tparam Hasher Type of hasher to use.
 /// \param L Lua state.
-static int cartesi_mod_keccak(lua_State *L) {
+template <typename Hasher>
+static int cartesi_mod_hasher(lua_State *L) {
     using namespace cartesi;
-    keccak_256_hasher h;
-    machine_hash hash;
-    if (lua_gettop(L) > 2) {
+    const auto nargs = lua_gettop(L);
+    if (nargs > 2) {
         luaL_argerror(L, 3, "too many arguments");
     }
-    if (lua_gettop(L) < 1) {
+    if (nargs < 1) {
         luaL_argerror(L, 1, "too few arguments");
     }
-    if (lua_isinteger(L, 1) != 0) {
-        if (lua_gettop(L) > 1) {
-            luaL_argerror(L, 2, "too many arguments");
-        }
-        uint64_t word = luaL_checkinteger(L, 1);
-        h.begin();
-        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        h.add_data(std::span<unsigned char>(reinterpret_cast<unsigned char *>(&word), sizeof(word)));
-        h.end(hash);
-        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        lua_pushlstring(L, reinterpret_cast<const char *>(hash.data()), hash.size());
-        return 1;
-    }
-    h.begin();
     size_t len1 = 0;
-    const char *hash1 = luaL_checklstring(L, 1, &len1);
-    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-    h.add_data(std::span<const char>(hash1, len1));
     size_t len2 = 0;
-    const char *hash2 = luaL_optlstring(L, 2, "", &len2);
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-    h.add_data(std::span<const char>(hash2, len2));
-    h.end(hash);
+    const auto *data1 = reinterpret_cast<const unsigned char *>(luaL_checklstring(L, 1, &len1));
+    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+    const auto *data2 = reinterpret_cast<const unsigned char *>(luaL_optlstring(L, 2, "", &len2));
+    Hasher h;
+    machine_hash hash;
+    // Handle special case that may have optimal implementations
+    if (len1 == MACHINE_HASH_SIZE && len2 == MACHINE_HASH_SIZE) { // Special case for hash tree concatenation
+        h.concat_hash(const_machine_hash_view{data1, len1}, const_machine_hash_view{data2, len2}, hash);
+    } else if (len1 == HASH_TREE_WORD_SIZE && len2 == 0) { // Special case for hash tree word
+        h.hash(const_hash_tree_word_view{data1, len1}, hash);
+    } else if (len2 > 0) { // Generic concat hash
+        h.concat_hash(std::span<const unsigned char>{data1, len1}, std::span<const unsigned char>{data2, len2}, hash);
+    } else { // Generic hash
+        h.hash(std::span<const unsigned char>{data1, len1}, hash);
+    }
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
     lua_pushlstring(L, reinterpret_cast<const char *>(hash.data()), hash.size());
     return 1;
 }
 
+/// \brief This is the cartesi.keccak256() function implementation.
+/// \param L Lua state.
+static int cartesi_mod_keccak256(lua_State *L) {
+    return cartesi_mod_hasher<cartesi::keccak_256_hasher>(L);
+}
+
+/// \brief This is the cartesi.sha256() function implementation.
+/// \param L Lua state.
+static int cartesi_mod_sha256(lua_State *L) {
+    return cartesi_mod_hasher<cartesi::sha_256_hasher>(L);
+}
+
 static int cartesi_mod_tobase64(lua_State *L) try {
     size_t size = 0;
     const char *data = luaL_checklstring(L, 1, &size);
@@ -153,7 +163,8 @@ static int cartesi_mod_new(lua_State *L) try {
 
 /// \brief Contents of the cartesi module table.
 static const auto cartesi_mod = clua_make_luaL_Reg_array({
-    {"keccak", cartesi_mod_keccak},
+    {"keccak256", cartesi_mod_keccak256},
+    {"sha256", cartesi_mod_sha256},
     {"tobase64", cartesi_mod_tobase64},
     {"frombase64", cartesi_mod_frombase64},
     {"tojson", cartesi_mod_tojson},
diff --git a/src/compiler-defines.h b/src/compiler-defines.h
index 0fb7eb004..f3e6cd5e4 100644
--- a/src/compiler-defines.h
+++ b/src/compiler-defines.h
@@ -17,6 +17,8 @@
 #ifndef COMPILER_DEFINES_H
 #define COMPILER_DEFINES_H
 
+// NOLINTBEGIN(cppcoreguidelines-macro-usage)
+
 #ifndef CODE_COVERAGE
 #define FORCE_INLINE __attribute__((always_inline)) inline
 #else
@@ -30,14 +32,38 @@
 #define NO_RETURN [[noreturn]]
 
 // These macros are used only in very hot code paths (such as TLB hit checks).
-// NOLINTNEXTLINE(cppcoreguidelines-macro-usage)
 #define likely(x) __builtin_expect((x), 1)
-// NOLINTNEXTLINE(cppcoreguidelines-macro-usage)
 #define unlikely(x) __builtin_expect((x), 0)
-//??E Although using PGO (Profile Guided Optimizations) makes use of these macros unneeded,
-//    using them allows for more performance without the need to compile with PGO,
-//    useful when doing benchmark of code changes.
 
 #define PACKED __attribute__((packed))
 
+// Helper macros for stringification
+#define TO_STRING_HELPER(X) #X
+#define TO_STRING(X) TO_STRING_HELPER(X)
+
+// Define loop unrolling depending on the compiler
+#if defined(__clang__)
+#define UNROLL_LOOP(n) _Pragma(TO_STRING(unroll(n)))
+#define UNROLL_LOOP_FULL(n) _Pragma(TO_STRING(unroll))
+#elif defined(__GNUC__) && !defined(__clang__)
+#define UNROLL_LOOP(n) _Pragma(TO_STRING(GCC unroll(n)))
+#define UNROLL_LOOP_FULL(n) _Pragma(TO_STRING(GCC unroll(65534)))
+#else
+#define UNROLL_LOOP(n)
+#define UNROLL_LOOP_FULL(n)
+#endif
+
+#if defined(__GNUC__) && defined(__linux__) && defined(__amd64__) && !defined(NO_MULTIVERSIONING)
+#define USE_MULTIVERSINING_AMD64
+#define MULTIVERSION_GENERIC __attribute__((target("default")))
+#define MULTIVERSION_AMD64_AVX2_BMI_BMI2 __attribute__((target("avx2,bmi,bmi2")))
+#define MULTIVERSION_AMD64_AVX512_BMI_BMI2 __attribute__((target("avx512f,avx512vl,bmi,bmi2")))
+#define MULTIVERSION_AMD64_AVX2 __attribute__((target("avx2")))
+#define MULTIVERSION_AMD64_AVX512 __attribute__((target("avx512f,avx512vl")))
+#else
+#define MULTIVERSION_GENERIC __attribute__((noinline))
+#endif
+
+// NOLINTEND(cppcoreguidelines-macro-usage)
+
 #endif
diff --git a/src/hash-tree-stats.h b/src/hash-tree-stats.h
index c439abc5f..74be38fae 100644
--- a/src/hash-tree-stats.h
+++ b/src/hash-tree-stats.h
@@ -27,8 +27,8 @@ namespace cartesi {
 
 struct hash_tree_stats {
     page_hash_tree_cache_stats phtc;
-    uint64_t sparse_node_hashes;
-    std::array<uint64_t, HASH_TREE_LOG2_ROOT_SIZE> dense_node_hashes;
+    uint64_t sparse_node_hashes{0};
+    std::array<uint64_t, HASH_TREE_LOG2_ROOT_SIZE> dense_node_hashes{};
 };
 
 } // namespace cartesi
diff --git a/src/hash-tree.cpp b/src/hash-tree.cpp
index 4d368d86f..7ee064777 100644
--- a/src/hash-tree.cpp
+++ b/src/hash-tree.cpp
@@ -16,7 +16,6 @@
 
 #include "hash-tree.h"
 
-#include <atomic>
 #include <bit>
 #include <iostream>
 #include <queue>
@@ -24,11 +23,18 @@
 #include <string>
 #include <utility>
 
+#include "os-features.h"
+
+#ifdef HAVE_OPENMP
 #include <omp.h>
+#endif
 
+#include "i-hasher.h"
 #include "machine-address-ranges.h"
-#include "scope-exit.h"
+#include "machine-hash.h"
+#include "page-hash-tree-cache-stats.h"
 #include "signposts.h"
+#include "simd-hasher.h"
 
 namespace cartesi {
 
@@ -74,9 +80,8 @@ void hash_tree::get_page_proof(address_range &ar, uint64_t address, proof_type &
     auto opt_br = m_page_cache.borrow_entry(paddr_page, hit);
     assert(opt_br && "page hash-tree cache has no entries to lend");
     if (!hit) {
-        hasher_type h;
         [[maybe_unused]] bool changed = false;
-        update_dirty_page(h, ar, opt_br->get(), changed);
+        update_dirty_page(ar, opt_br->get(), changed);
     }
     const auto log2_target_size = proof.get_log2_target_size();
     assert(log2_target_size >= HASH_TREE_LOG2_WORD_SIZE && "log2_size is too small");
@@ -157,16 +162,9 @@ hash_tree::proof_type hash_tree::get_proof(address_ranges ars, uint64_t address,
 hash_tree_stats hash_tree::get_stats(bool clear) noexcept {
     auto s = hash_tree_stats{
         .phtc = m_page_cache.get_stats(clear),
-        .sparse_node_hashes = m_sparse_node_hashes.load(),
+        .sparse_node_hashes = m_sparse_node_hashes,
+        .dense_node_hashes = m_dense_node_hashes,
     };
-    std::ranges::copy(m_dense_node_hashes | std::views::transform([](auto &a) {
-        std::cerr << "ha " << a.load() << '\n';
-        return a.load();
-    }),
-        s.dense_node_hashes.begin());
-    for (auto i : s.dense_node_hashes) {
-        std::cerr << "hi " << i << '\n';
-    }
     if (clear) {
         m_sparse_node_hashes = 0;
         for (auto &a : m_dense_node_hashes) {
@@ -176,42 +174,104 @@ hash_tree_stats hash_tree::get_stats(bool clear) noexcept {
     return s;
 }
 
-bool hash_tree::update_dirty_page(hasher_type &h, address_range &ar, page_hash_tree_cache::entry &entry,
-    bool &changed) {
+bool hash_tree::update_dirty_page(address_range &ar, page_hash_tree_cache::entry &entry, bool &changed) {
     const auto paddr_page = entry.get_paddr_page();
     const auto *base = ar.get_host_memory();
     if (!ar.is_memory() || base == nullptr || !ar.contains_absolute(paddr_page, HASH_TREE_PAGE_SIZE)) {
         return false;
     }
     const auto offset = paddr_page - ar.get_start();
-    const auto page = std::span<const unsigned char, HASH_TREE_PAGE_SIZE>{base + offset, HASH_TREE_PAGE_SIZE};
-    auto ret = m_page_cache.update_entry(h, page, entry);
+    const auto page_view = std::span<const unsigned char, HASH_TREE_PAGE_SIZE>{base + offset, HASH_TREE_PAGE_SIZE};
+    page_hash_tree_cache::simd_hasher<hasher_type> queue;
+    auto &stats = m_page_cache.get_stats_ref();
+    auto ret = m_page_cache.enqueue_hash_entry(queue, page_view, entry, stats);
+    stats.inner_page_hashes += queue.flush();
     auto node_hash_view = ar.get_dense_hash_tree().node_hash_view(offset, HASH_TREE_LOG2_PAGE_SIZE);
     changed = !std::ranges::equal(entry.root_hash_view(), node_hash_view);
     if (changed) {
         std::ranges::copy(entry.root_hash_view(), node_hash_view.begin());
+        ++stats.page_changes;
     }
     return ret;
 }
 
+bool hash_tree::enqueue_hash_dirty_page(page_hash_tree_cache::simd_hasher<hasher_type> &queue, address_range &ar,
+    page_hash_tree_cache::entry &entry, page_hash_tree_cache_stats &stats) {
+    const auto paddr_page = entry.get_paddr_page();
+    const auto *base = ar.get_host_memory();
+    if (!ar.is_memory() || base == nullptr || !ar.contains_absolute(paddr_page, HASH_TREE_PAGE_SIZE)) {
+        return false;
+    }
+    const auto offset = paddr_page - ar.get_start();
+    const auto page_view = std::span<const unsigned char, HASH_TREE_PAGE_SIZE>{base + offset, HASH_TREE_PAGE_SIZE};
+    return m_page_cache.enqueue_hash_entry(queue, page_view, entry, stats);
+}
+
 bool hash_tree::return_updated_dirty_pages(address_ranges ars, dirty_pages &batch,
     changed_address_ranges &changed_ars) {
     if (batch.empty()) {
         return true;
     }
-    const int batch_size = static_cast<int>(batch.size());
-    std::atomic<int> update_failed{0}; // NOLINT(misc-const-correctness)
     //??D The batch size past which we switch to parallel updates needs to be tuned empirically
-    hasher_type h; // NOLINT(misc-const-correctness)
-#pragma omp parallel for private(h) schedule(dynamic) if (batch_size > m_concurrency * 4)
-    // NOLINTNEXTLINE(modernize-loop-convert)
-    for (int i = 0; i < batch_size; ++i) {
-        auto &[ar_index, br, changed] = batch[i];
-        auto &ar = ars[ar_index];
-        if (!update_dirty_page(h, ar, br, changed)) {
-            update_failed.store(1, std::memory_order_relaxed);
+    const int batch_size = static_cast<int>(batch.size());
+    const int threads = (m_concurrency > 1 && batch_size > m_concurrency) ? m_concurrency : 1;
+    // ??(edubart): Using block size > 1 with multi-threading was not beneficial in benchmarks
+    // most likely due to work imbalance between threads leading to less effective OpenMP dynamic scheduling.
+    // However for single-threaded execution, a larger block size should always improve performance by
+    // maximizing SIMD hashing.
+    const int block_size = threads > 1 ? 1 : page_hash_tree_cache::simd_hasher<hasher_type>::QUEUE_MAX_PAGE_COUNT;
+    uint64_t update_failures{0};
+    uint64_t word_hits{0};
+    uint64_t word_misses{0};
+    uint64_t page_changes{0};
+    uint64_t inner_page_hashes{0};
+    uint64_t pristine_pages{0};
+    uint64_t non_pristine_pages{0};
+#pragma omp parallel for schedule(dynamic) if (threads > 1) num_threads(threads) reduction(+ : update_failures,        \
+        word_hits, word_misses, page_changes, inner_page_hashes, pristine_pages, non_pristine_pages)
+    for (int i = 0; i < batch_size; i += block_size) {
+        // Queue entries to be hashed
+        page_hash_tree_cache::simd_hasher<hasher_type> queue;
+        page_hash_tree_cache_stats stats;
+        for (int j = i; j < std::min(batch_size, i + block_size); ++j) {
+            auto &[ar_index, br, changed] = batch[j];
+            auto &ar = ars[ar_index];
+            if (!enqueue_hash_dirty_page(queue, ar, br, stats)) {
+                ++update_failures;
+            }
+        }
+        // Flush SIMD hasher queue
+        stats.inner_page_hashes += queue.flush();
+        // Update changed entries
+        for (int j = i; j < std::min(batch_size, i + block_size); ++j) {
+            auto &[ar_index, br, changed] = batch[j];
+            auto &ar = ars[ar_index];
+            const auto offset = br.get_paddr_page() - ar.get_start();
+            auto root_hash_view = br.root_hash_view();
+            auto node_hash_view = ar.get_dense_hash_tree().node_hash_view(offset, HASH_TREE_LOG2_PAGE_SIZE);
+            changed = !std::ranges::equal(root_hash_view, node_hash_view);
+            if (changed) {
+                std::ranges::copy(root_hash_view, node_hash_view.begin());
+                ++stats.page_changes;
+            }
         }
+        // Increment stats
+        word_hits += stats.word_hits;
+        word_misses += stats.word_misses;
+        page_changes += stats.page_changes;
+        inner_page_hashes += stats.inner_page_hashes;
+        pristine_pages += stats.pristine_pages;
+        non_pristine_pages += stats.non_pristine_pages;
     }
+
+    auto &page_stats = m_page_cache.get_stats_ref();
+    page_stats.word_hits += word_hits;
+    page_stats.word_misses += word_misses;
+    page_stats.page_changes += page_changes;
+    page_stats.inner_page_hashes += inner_page_hashes;
+    page_stats.pristine_pages += pristine_pages;
+    page_stats.non_pristine_pages += non_pristine_pages;
+
     // Return all entries and collect address ranges that were actually changed by update
     for (auto &[ar_index, br, changed] : batch) {
         auto &ar = ars[ar_index];
@@ -230,24 +290,23 @@ bool hash_tree::return_updated_dirty_pages(address_ranges ars, dirty_pages &batc
                 ar.get_dirty_page_tree().mark_clean_page_and_up(offset);
             }
         } else {
-            update_failed.store(1, std::memory_order_relaxed);
+            ++update_failures;
         }
     }
     // Done with batch
     batch.clear();
-    return static_cast<bool>(update_failed.load(std::memory_order_relaxed));
+    return update_failures > 0;
 }
 
 hash_tree::~hash_tree() {
 #ifdef DUMP_HASH_TREE_STATS
     std::cerr << "sparse node hashes: " << std::dec << m_sparse_node_hashes << '\n';
     std::cerr << "dense node hashes: \n";
-    int sum = 0;
-    for (int i = 0; auto &a : m_dense_node_hashes) {
-        auto av = a.load();
-        sum += av;
-        if (av != 0) {
-            std::cerr << "    " << std::dec << i << ": " << av << '\n';
+    uint64_t sum = 0;
+    for (int i = 0; auto a : m_dense_node_hashes) {
+        sum += a;
+        if (a != 0) {
+            std::cerr << "    " << std::dec << i << ": " << a << '\n';
         }
         ++i;
     }
@@ -315,22 +374,26 @@ void hash_tree::update_and_clear_dense_node_entries(dense_node_entries &batch, i
     if (batch.empty()) {
         return;
     }
-    const int batch_size = static_cast<int>(batch.size());
     //??D The batch size past which we switch to parallel updates needs to be tuned empirically
-    int updates = 0;
-    hasher_type h; // NOLINT(misc-const-correctness)
-#pragma omp parallel for private(h, updates) schedule(dynamic) if (batch_size > m_concurrency * 32)
-    // NOLINTNEXTLINE(modernize-loop-convert)
-    for (decltype(batch.size()) i = 0; i < batch.size(); ++i) {
-        auto &[dht, offset] = batch[i];
-        auto child_size = UINT64_C(1) << (log2_size - 1);
-        auto parent = dht.node_hash_view(offset, log2_size);
-        auto left = dht.node_hash_view(offset, log2_size - 1);
-        auto right = dht.node_hash_view(offset + child_size, log2_size - 1);
-        get_concat_hash(h, left, right, parent);
-        ++updates;
+    const int batch_size = static_cast<int>(batch.size());
+    // It's only worth to use multi-threading if we have enough entries to process
+    const int threads =
+        (m_concurrency > 1 && batch_size > m_concurrency * hasher_type::MAX_LANE_COUNT) ? m_concurrency : 1;
+    const int block_size = hasher_type::MAX_LANE_COUNT;
+#pragma omp parallel for schedule(static) if (threads > 1) num_threads(threads)
+    for (int block_start = 0; block_start < batch_size; block_start += block_size) {
+        simd_concat_hasher<hasher_type, const_machine_hash_view> queue;
+        for (int i = block_start; i < std::min(batch_size, block_start + block_size); ++i) {
+            auto &[dht, offset] = batch[i];
+            auto child_size = UINT64_C(1) << (log2_size - 1);
+            auto parent = dht.node_hash_view(offset, log2_size);
+            auto left = dht.node_hash_view(offset, log2_size - 1);
+            auto right = dht.node_hash_view(offset + child_size, log2_size - 1);
+            queue.enqueue(left, right, parent);
+        }
+        queue.flush();
     }
-    m_dense_node_hashes[log2_size] += updates;
+    m_dense_node_hashes[log2_size] += batch_size;
     batch.clear();
 }
 
@@ -339,8 +402,8 @@ bool hash_tree::update_dense_trees(address_ranges ars, const changed_address_ran
     if (changed_ars.empty()) {
         return true;
     }
-    const auto thread_count = 8;
-    const auto batch_size = thread_count << 10;
+    // We can batch more if we have more concurrency, however we need to limit to not run out of memory.
+    const size_t batch_size = std::min(m_concurrency << 10, 16384);
     dense_node_entries batch;
     batch.reserve(batch_size);
     // Get maximum log2_size of all address ranges
@@ -398,7 +461,8 @@ bool hash_tree::update_sparse_tree(address_ranges ars, const changed_address_ran
             changed.emplace(ar_parent_node.log2_size, ar_node.parent);
         }
     }
-    hasher_type h;
+    simd_concat_hasher<hasher_type, const_machine_hash_view> queue;
+    int last_log2_size = -1;
     while (!changed.empty()) {
         auto [log2_size, inner_index] = changed.top();
         changed.pop();
@@ -409,7 +473,12 @@ bool hash_tree::update_sparse_tree(address_ranges ars, const changed_address_ran
         inner_node.marked = 0;
         auto left_hash_view = get_sparse_node_hash_view(inner_node.left, log2_size - 1);
         auto right_hash_view = get_sparse_node_hash_view(inner_node.right, log2_size - 1);
-        get_concat_hash(h, left_hash_view, right_hash_view, inner_node.hash);
+        // When crossing tree height boundary, we need to flush the queue
+        if (last_log2_size != log2_size) {
+            last_log2_size = log2_size;
+            queue.flush();
+        }
+        queue.enqueue(left_hash_view, right_hash_view, inner_node.hash);
         ++m_sparse_node_hashes;
         if (!is_pristine(inner_node.parent)) {
             auto &parent_node = m_sparse_nodes[inner_node.parent];
@@ -419,6 +488,7 @@ bool hash_tree::update_sparse_tree(address_ranges ars, const changed_address_ran
             }
         }
     }
+    queue.flush();
     return true;
 }
 
@@ -435,9 +505,8 @@ machine_hash hash_tree::get_dense_node_hash(address_range &ar, uint64_t address,
         auto opt_br = m_page_cache.borrow_entry(paddr_page, hit);
         assert(opt_br && "page hash-tree cache has no entries to lend");
         if (!hit) {
-            hasher_type h;
             [[maybe_unused]] bool changed = false;
-            update_dirty_page(h, ar, *opt_br, changed);
+            update_dirty_page(ar, *opt_br, changed);
         }
         auto node_offset = address - paddr_page;
         auto hash = to_hash(opt_br->get().node_hash_view(node_offset, log2_size));
@@ -475,7 +544,7 @@ machine_hash hash_tree::get_node_hash(address_ranges ars, uint64_t address, int
         // transition to dense tree
         if (is_ar_node(node)) {
             auto &ar = ars[node.right];
-            const int ar_log2_size = HASH_TREE_LOG2_PAGE_SIZE + ar.get_level_count() - 1;
+            [[maybe_unused]] const int ar_log2_size = HASH_TREE_LOG2_PAGE_SIZE + ar.get_level_count() - 1;
             assert(curr_log2_size == ar_log2_size && "incorrect ar node log2_size");
             return get_dense_node_hash(ar, address, log2_size);
         }
@@ -555,9 +624,8 @@ bool hash_tree::verify(address_ranges ars) const {
 
 bool hash_tree::update(address_ranges ars) {
     SCOPED_SIGNPOST(m_log, m_spid_update, "hash-tree: update", "");
-    auto old_concurrency = omp_get_num_threads();
-    omp_set_num_threads(m_concurrency);
     changed_address_ranges changed_ars;
+    changed_ars.reserve(ars.size());
     auto update_succeeded = update_dirty_pages(ars, changed_ars) && update_dense_trees(ars, changed_ars) &&
         update_sparse_tree(ars, changed_ars);
     if (update_succeeded) {
@@ -565,15 +633,11 @@ bool hash_tree::update(address_ranges ars) {
             ars[ar_index].get_dirty_page_tree().clean();
         }
     }
-    omp_set_num_threads(old_concurrency);
     return update_succeeded;
 }
 
 bool hash_tree::update_words(address_ranges ars, dirty_words_type dirty_words) {
     constexpr auto page_mask = ~UINT64_C(HASH_TREE_PAGE_SIZE - 1);
-    auto old_concurrency = omp_get_num_threads();
-    omp_set_num_threads(m_concurrency);
-    const scope_exit num_threads{[old_concurrency]() { omp_set_num_threads(old_concurrency); }};
     // Dirty_words contains an unordered set of the address of all words that became dirty since last update
     // We copy these to a sorted vector "words"
     // Every word in the same page must be updated by the same thread
@@ -600,7 +664,7 @@ bool hash_tree::update_words(address_ranges ars, dirty_words_type dirty_words) {
     page_starts.push_back(words.size()); // last entry
     //??D I'll assume here that we do not have more threads than the cache size,
     // so we don't need to process in batches, and will fail if this assumption if false
-    std::atomic<int> update_failed{0}; // NOLINT(misc-const-correctness)
+    uint64_t update_failures{0}; // NOLINT(misc-const-correctness)
     int ar_index = 0;
     int max_level_count = 0;
     hasher_type h;
@@ -616,13 +680,13 @@ bool hash_tree::update_words(address_ranges ars, dirty_words_type dirty_words) {
         bool hit = false;
         auto opt_br = m_page_cache.borrow_entry(paddr_page, hit);
         if (!opt_br) {
-            update_failed.store(1, std::memory_order_relaxed);
+            ++update_failures;
             continue;
         }
         auto &cache_entry = opt_br->get();
         while (!ars[ar_index].contains_absolute(paddr_page, HASH_TREE_PAGE_SIZE)) {
             if (ar_index >= static_cast<int>(ars.size())) {
-                update_failed.store(1, std::memory_order_relaxed);
+                ++update_failures;
                 m_page_cache.return_entry(cache_entry);
                 continue;
             }
@@ -635,7 +699,7 @@ bool hash_tree::update_words(address_ranges ars, dirty_words_type dirty_words) {
         max_level_count = std::max(max_level_count, ar.get_level_count());
         const auto *base = ar.get_host_memory();
         if (!ar.is_memory() || base == nullptr) {
-            update_failed.store(1, std::memory_order_relaxed);
+            ++update_failures;
             m_page_cache.return_entry(cache_entry);
             continue;
         }
@@ -674,8 +738,8 @@ bool hash_tree::update_words(address_ranges ars, dirty_words_type dirty_words) {
             // otherwise, the update from scratch
         } else {
             bool changed = false;
-            if (!update_dirty_page(h, ar, cache_entry, changed)) {
-                update_failed.store(1, std::memory_order_relaxed);
+            if (!update_dirty_page(ar, cache_entry, changed)) {
+                ++update_failures;
                 m_page_cache.return_entry(cache_entry);
             }
         }
@@ -705,7 +769,7 @@ bool hash_tree::update_words(address_ranges ars, dirty_words_type dirty_words) {
         }
         std::swap(curr_dense_node, next_dense_node);
     }
-    return !static_cast<bool>(update_failed.load(std::memory_order_relaxed)) && update_sparse_tree(ars, changed_ars);
+    return !static_cast<bool>(update_failures > 0) && update_sparse_tree(ars, changed_ars);
 }
 
 bool hash_tree::update_page(address_ranges ars, uint64_t paddr_page) {
@@ -726,7 +790,7 @@ bool hash_tree::update_page(address_ranges ars, uint64_t paddr_page) {
     auto &entry = opt_br->get();
     bool changed = false;
     // Update page with data from address range
-    update_dirty_page(h, ar, entry, changed);
+    update_dirty_page(ar, entry, changed);
     // If nothing changed, we are done
     if (!changed) {
         m_page_cache.return_entry(entry);
@@ -779,9 +843,13 @@ hash_tree::pristine_hashes hash_tree::get_pristine_hashes() {
     return hashes;
 };
 
-static int get_concurrency(int value) {
+static int get_concurrency([[maybe_unused]] int value) {
+#ifdef HAVE_OPENMP
     const int concurrency = value != 0 ? value : omp_get_max_threads();
     return std::min(concurrency, omp_get_max_threads());
+#else
+    return 1;
+#endif
 }
 
 hash_tree::hash_tree(const hash_tree_config &config, uint64_t concurrency, const_address_ranges ars) :
diff --git a/src/hash-tree.h b/src/hash-tree.h
index 192074daa..dcbdf8770 100644
--- a/src/hash-tree.h
+++ b/src/hash-tree.h
@@ -158,7 +158,9 @@ class hash_tree {
     static pristine_hashes get_pristine_hashes();
 
     bool update_dirty_pages(address_ranges ars, changed_address_ranges &changed_ars);
-    bool update_dirty_page(hasher_type &h, address_range &ar, page_hash_tree_cache::entry &entry, bool &changed);
+    bool update_dirty_page(address_range &ar, page_hash_tree_cache::entry &entry, bool &changed);
+    bool enqueue_hash_dirty_page(page_hash_tree_cache::simd_hasher<hasher_type> &queue, address_range &ar,
+        page_hash_tree_cache::entry &entry, page_hash_tree_cache_stats &stats);
     bool return_updated_dirty_pages(address_ranges ars, dirty_pages &batch, changed_address_ranges &changed_ars);
 
     bool update_dense_trees(address_ranges ars, const changed_address_ranges &changed_ars);
@@ -190,8 +192,8 @@ class hash_tree {
     const pristine_hashes m_pristine_hashes;
     int m_concurrency;
 
-    std::atomic<uint64_t> m_sparse_node_hashes{0};
-    std::array<std::atomic<uint64_t>, HASH_TREE_LOG2_ROOT_SIZE> m_dense_node_hashes{};
+    uint64_t m_sparse_node_hashes{0};
+    std::array<uint64_t, HASH_TREE_LOG2_ROOT_SIZE> m_dense_node_hashes{};
 };
 
 } // namespace cartesi
diff --git a/src/i-hasher.h b/src/i-hasher.h
index ad9429a6a..faaf30b96 100644
--- a/src/i-hasher.h
+++ b/src/i-hasher.h
@@ -27,12 +27,17 @@
 #include <stdexcept>
 #include <type_traits>
 
+#include "array2d.h"
 #include "concepts.h"
+#include "hash-tree-constants.h"
 #include "machine-hash.h"
 #include "meta.h"
 
 namespace cartesi {
 
+using hash_tree_word_view = std::span<unsigned char, HASH_TREE_WORD_SIZE>;
+using const_hash_tree_word_view = std::span<const unsigned char, HASH_TREE_WORD_SIZE>;
+
 /// \brief Hasher interface.
 /// \tparam DERIVED Derived class implementing the interface. (An example of CRTP.)
 template <typename DERIVED>
@@ -48,17 +53,50 @@ class i_hasher { // CRTP
     }
 
 public:
-    void begin() noexcept {
-        return derived().do_begin();
+    template <ContiguousRangeOfByteLike D>
+    void hash(D &&data, machine_hash_view hash) noexcept { // NOLINT(cppcoreguidelines-missing-std-forward)
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        auto data_span = std::span<const unsigned char>{reinterpret_cast<const uint8_t *>(std::ranges::data(data)),
+            std::ranges::size(data)};
+        return derived().do_simd_concat_hash(array2d<std::span<const unsigned char>, 1, 1>{{{data_span}}},
+            std::array<machine_hash_view, 1>{hash});
+    }
+
+    void hash(const_hash_tree_word_view data, machine_hash_view hash) noexcept {
+        return derived().do_simd_concat_hash(array2d<const_hash_tree_word_view, 1, 1>{{{data}}},
+            std::array<machine_hash_view, 1>{hash});
     }
 
     template <ContiguousRangeOfByteLike D>
-    void add_data(D &&data) noexcept {
-        return derived().do_add_data(std::forward<D>(data));
+    void concat_hash(D &&data1, D &&data2, // NOLINT(cppcoreguidelines-missing-std-forward)
+        machine_hash_view hash) noexcept {
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        auto data1_span = std::span<const unsigned char>{reinterpret_cast<const uint8_t *>(std::ranges::data(data1)),
+            std::ranges::size(data1)};
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        auto data2_span = std::span<const unsigned char>{reinterpret_cast<const uint8_t *>(std::ranges::data(data2)),
+            std::ranges::size(data2)};
+        return derived().do_simd_concat_hash(
+            array2d<std::span<const unsigned char>, 2, 1>{{{data1_span}, {data2_span}}},
+            std::array<machine_hash_view, 1>{hash});
+    }
+
+    void concat_hash(const_machine_hash_view data1, const_machine_hash_view data2, machine_hash_view hash) noexcept {
+        return derived().do_simd_concat_hash(array2d<const_machine_hash_view, 2, 1>{{{data1}, {data2}}},
+            std::array<machine_hash_view, 1>{hash});
+    }
+
+    template <size_t ConcatCount, size_t ParallelCount>
+    void simd_concat_hash(const array2d<const_hash_tree_word_view, ConcatCount, ParallelCount> &data,
+        const std::array<machine_hash_view, ParallelCount> &hash) noexcept {
+        return derived().do_simd_concat_hash(data, hash);
     }
 
-    void end(machine_hash_view hash) noexcept {
-        return derived().do_end(hash);
+    // \brief Gets the optimal number of SIMD lanes for hashing.
+    // \returns The optimal number of SIMD lanes for hashing.
+    // \details This value is architecture-dependent and may vary based on the available instruction sets.
+    static size_t get_optimal_lane_count() noexcept {
+        return DERIVED::do_get_optimal_lane_count();
     }
 };
 
@@ -79,9 +117,7 @@ concept IHasher = is_an_i_hasher_v<T>;
 /// \param result Receives the hash of data
 template <IHasher H, ContiguousRangeOfByteLike D>
 inline static void get_hash(H &h, D &&data, machine_hash_view result) noexcept {
-    h.begin();
-    h.add_data(std::forward<D>(data));
-    h.end(result);
+    h.hash(std::forward<D>(data), result);
 }
 
 /// \brief Computes the hash of data
@@ -105,10 +141,7 @@ inline static machine_hash get_hash(H &&h, D &&data) noexcept {
 template <IHasher H>
 inline static void get_concat_hash(H &h, const_machine_hash_view left, const_machine_hash_view right,
     machine_hash_view result) noexcept {
-    h.begin();
-    h.add_data(left);
-    h.add_data(right);
-    h.end(result);
+    h.concat_hash(left, right, result);
 }
 
 /// \brief Computes the hash of concatenated hashes
diff --git a/src/is-pristine.cpp b/src/is-pristine.cpp
new file mode 100644
index 000000000..4daa6d300
--- /dev/null
+++ b/src/is-pristine.cpp
@@ -0,0 +1,67 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#include "is-pristine.h"
+
+#include <cstddef>
+#include <cstdint>
+#include <span>
+
+#include "address-range-constants.h"
+#include "compiler-defines.h"
+
+namespace cartesi {
+
+template <size_t Extent>
+FORCE_INLINE static bool is_pristine_impl(std::span<const unsigned char, Extent> data) noexcept {
+    unsigned char bits = 0;
+    // GCC and Clang are smart enough to use SIMD instructions with large words on this loop,
+    // however it may not unroll the loops, so we unroll it manually.
+    UNROLL_LOOP(64)
+    for (const unsigned char b : data) {
+        bits |= b;
+    }
+    return bits == 0;
+}
+
+// Generic implementations
+
+MULTIVERSION_GENERIC bool is_pristine(std::span<const unsigned char> data) noexcept {
+    return is_pristine_impl(data);
+}
+MULTIVERSION_GENERIC bool is_pristine(std::span<const unsigned char, AR_PAGE_SIZE> data) noexcept {
+    return is_pristine_impl(data);
+}
+
+// x86_64 implementations
+
+#ifdef USE_MULTIVERSINING_AMD64
+MULTIVERSION_AMD64_AVX2 bool is_pristine(std::span<const unsigned char> data) noexcept {
+    return is_pristine_impl(data);
+}
+MULTIVERSION_AMD64_AVX2 bool is_pristine(std::span<const unsigned char, AR_PAGE_SIZE> data) noexcept {
+    return is_pristine_impl(data);
+}
+
+MULTIVERSION_AMD64_AVX512 bool is_pristine(std::span<const unsigned char> data) noexcept {
+    return is_pristine_impl(data);
+}
+MULTIVERSION_AMD64_AVX512 bool is_pristine(std::span<const unsigned char, AR_PAGE_SIZE> data) noexcept {
+    return is_pristine_impl(data);
+}
+#endif
+
+} // namespace cartesi
diff --git a/src/is-pristine.h b/src/is-pristine.h
index 0f0bf3f82..eab0b327e 100644
--- a/src/is-pristine.h
+++ b/src/is-pristine.h
@@ -17,43 +17,41 @@
 #ifndef IS_PRISTINE_H
 #define IS_PRISTINE_H
 
+#include "compiler-defines.h"
+
 #include <cstddef>
 #include <cstdint>
 #include <ranges>
+#include <span>
 
+#include "address-range-constants.h"
 #include "concepts.h"
 #include "meta.h"
 
 namespace cartesi {
 
-/// \brief This is an optimized function for checking if memory page is pristine.
-/// \param data Memory pointer
-/// \param length Memory length
-/// \returns True if all values are 0, false otherwise
+/// \brief This is an optimized function for checking if data is pristine.
+/// \param data Memory data.
+/// \returns True if all values are 0, false otherwise.
 /// \details It's to be used in situations where length is equal or less than a page size.
-static inline bool is_pristine(const unsigned char *data, size_t length) {
-    // This tight for loop has no branches, and is optimized to SIMD instructions in x86_64,
-    // making it very fast to check if a given page is pristine.
-    unsigned char bits = 0;
-    for (size_t i = 0; i < length; ++i) {
-        bits |= data[i];
-    }
-    return bits == 0;
-}
+MULTIVERSION_GENERIC bool is_pristine(std::span<const unsigned char> data) noexcept;
 
 /// \brief This is an optimized function for checking if memory page is pristine.
-/// \param r Contiguous range of byte-like values
-/// \returns True if all values are 0, false otherwise
-/// \details It's to be used in situations where length is equal or less than a page size.
+MULTIVERSION_GENERIC bool is_pristine(std::span<const unsigned char, AR_PAGE_SIZE> data) noexcept;
+
 template <ContiguousRangeOfByteLike R>
-static inline bool is_pristine(R &&r) { // NOLINT(cppcoreguidelines-missing-std-forward)
-    std::ranges::range_value_t<R> bits{0};
-    for (auto b : r) {
-        bits |= b;
-    }
-    return bits == 0;
+bool is_pristine(R &&r) noexcept { // NOLINT(cppcoreguidelines-missing-std-forward)
+    return is_pristine(std::span<const unsigned char>{std::ranges::data(r), std::ranges::size(r)});
 }
 
+#ifdef USE_MULTIVERSINING_AMD64
+MULTIVERSION_AMD64_AVX2 bool is_pristine(std::span<const unsigned char> data) noexcept;
+MULTIVERSION_AMD64_AVX2 bool is_pristine(std::span<const unsigned char, AR_PAGE_SIZE> data) noexcept;
+
+MULTIVERSION_AMD64_AVX512 bool is_pristine(std::span<const unsigned char> data) noexcept;
+MULTIVERSION_AMD64_AVX512 bool is_pristine(std::span<const unsigned char, AR_PAGE_SIZE> data) noexcept;
+#endif
+
 } // namespace cartesi
 
 #endif
diff --git a/src/json-util.cpp b/src/json-util.cpp
index 7bae4e758..5cf6ae232 100644
--- a/src/json-util.cpp
+++ b/src/json-util.cpp
@@ -949,6 +949,7 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, page_hash_tree_cach
     ju_get_opt_field(jstats, "page_misses"s, value.page_misses, new_path);
     ju_get_opt_field(jstats, "word_hits"s, value.word_hits, new_path);
     ju_get_opt_field(jstats, "word_misses"s, value.word_misses, new_path);
+    ju_get_opt_field(jstats, "page_changes"s, value.page_changes, new_path);
     ju_get_opt_field(jstats, "inner_page_hashes"s, value.inner_page_hashes, new_path);
     ju_get_opt_field(jstats, "pristine_pages"s, value.pristine_pages, new_path);
     ju_get_opt_field(jstats, "non_pristine_pages"s, value.non_pristine_pages, new_path);
@@ -2216,6 +2217,7 @@ void to_json(nlohmann::json &j, const page_hash_tree_cache_stats &stats) {
         {"page_misses", stats.page_misses},
         {"word_hits", stats.word_hits},
         {"word_misses", stats.word_misses},
+        {"page_changes", stats.page_changes},
         {"inner_page_hashes", stats.inner_page_hashes},
         {"pristine_pages", stats.pristine_pages},
         {"non_pristine_pages", stats.non_pristine_pages},
diff --git a/src/jsonrpc-discover.json b/src/jsonrpc-discover.json
index c8d11396b..8594bdae5 100644
--- a/src/jsonrpc-discover.json
+++ b/src/jsonrpc-discover.json
@@ -1110,6 +1110,9 @@
           "word_misses": {
             "$ref": "#/components/schemas/UnsignedInteger"
           },
+          "page_changes": {
+            "$ref": "#/components/schemas/UnsignedInteger"
+          },
           "inner_page_hashes": {
             "$ref": "#/components/schemas/UnsignedInteger"
           },
diff --git a/src/keccak-256-hasher.cpp b/src/keccak-256-hasher.cpp
new file mode 100644
index 000000000..2ec108400
--- /dev/null
+++ b/src/keccak-256-hasher.cpp
@@ -0,0 +1,256 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#include "keccak-256-hasher.h"
+#include "compiler-defines.h"
+#include "i-hasher.h"
+#include "keccakf.h"
+#include "machine-hash.h"
+#include "simd-vector-type.h"
+
+#include <bit>
+#include <cstddef>
+#include <cstdint>
+#include <span>
+
+namespace cartesi {
+
+// This code is not portable to big-endian architectures.
+// NOLINTNEXTLINE(misc-redundant-expression)
+static_assert(std::endian::native == std::endian::little, "code assumes little-endian byte ordering");
+
+constexpr size_t KECCAK_WORD_COUNT = 25;
+constexpr size_t KECCAK_RSIZE = (KECCAK_WORD_COUNT * sizeof(uint64_t)) - (static_cast<size_t>(2) * MACHINE_HASH_SIZE);
+
+template <size_t LaneCount, size_t DataExtent = std::dynamic_extent>
+struct alignas(uint64_vector_type<LaneCount>::align) keccak_256_context final {
+    using word_vector_type = uint64_vector_type<LaneCount>::type;
+    using word_bytes_array = uint8_t[KECCAK_WORD_COUNT][LaneCount][sizeof(uint64_t)];
+    using data_span = std::span<const unsigned char, DataExtent>;
+
+    static constexpr size_t word_vector_align = uint64_vector_type<LaneCount>::align; // 64-bit m_words
+
+    word_vector_type m_words[5][5]{}; ///< Buffer for Keccak-256 words, interleaved by lanes
+
+    FORCE_INLINE void update(const std::array<data_span, LaneCount> &data, size_t &pos) noexcept {
+        [[maybe_unused]] auto words_bytes = // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+            reinterpret_cast<word_bytes_array &>(m_words);
+        // Assume all data spans have the same length
+        const size_t data_len = data[0].size();
+        for (size_t i = 0; i < data_len;) {
+            // Interleave data while XORing
+            const size_t step = std::min(KECCAK_RSIZE - pos, data_len - i);
+            if constexpr (DataExtent != std::dynamic_extent && DataExtent % sizeof(uint64_t) == 0) {
+                // If data length is a multiple of word size, process a word at time
+                UNROLL_LOOP(128)
+                for (size_t j = 0; j < step; j += sizeof(uint64_t)) {
+                    word_vector_type data_word;
+                    UNROLL_LOOP_FULL()
+                    for (size_t l = 0; l < LaneCount; ++l) {
+                        uint64_t lane_word{};
+                        __builtin_memcpy(&lane_word, &data[l][i + j], sizeof(lane_word));
+                        data_word[l] = lane_word;
+                    }
+                    m_words[((pos + j) / sizeof(uint64_t)) / 5][((pos + j) / sizeof(uint64_t)) % 5] ^= data_word;
+                }
+            } else { // Otherwise, process a byte at time
+                UNROLL_LOOP(128)
+                for (size_t j = 0; j < step; j++) {
+                    const size_t bi = (pos + j) / sizeof(uint64_t);
+                    const size_t bj = (pos + j) % sizeof(uint64_t);
+                    UNROLL_LOOP_FULL()
+                    for (size_t l = 0; l < LaneCount; ++l) {
+                        words_bytes[bi][l][bj] ^= data[l][i + j];
+                    }
+                }
+            }
+            i += step;
+            pos += step;
+            // Perform Keccak-256 permutation
+            if (pos >= KECCAK_RSIZE) [[unlikely]] {
+                keccakf_1600<word_vector_type, word_vector_align>(m_words);
+                pos = 0;
+            }
+        }
+    }
+
+    FORCE_INLINE void finish(const std::array<machine_hash_view, LaneCount> &hashes, size_t pos) noexcept {
+        // Append delimiter suffix
+        constexpr uint64_t KECCAK_DSUFFIX = 0x01;
+        const size_t dsuffix_word_pos = pos / sizeof(uint64_t);
+        const size_t dsuffix_byte_pos = pos % sizeof(uint64_t);
+        m_words[dsuffix_word_pos / 5][dsuffix_word_pos % 5] ^= KECCAK_DSUFFIX << (dsuffix_byte_pos * 8);
+        // Append last bit
+        constexpr uint64_t KECCAK_LASTBIT = 0x80;
+        constexpr size_t lastbit_word_pos = (KECCAK_RSIZE - 1) / sizeof(uint64_t);
+        constexpr size_t lastbit_byte_pos = (KECCAK_RSIZE - 1) % sizeof(uint64_t);
+        m_words[lastbit_word_pos / 5][lastbit_word_pos % 5] ^= KECCAK_LASTBIT << (lastbit_byte_pos * 8);
+        // Perform last permutation
+        keccakf_1600<word_vector_type, word_vector_align>(m_words);
+        // Deinterleave hash
+        UNROLL_LOOP_FULL()
+        for (size_t l = 0; l < LaneCount; ++l) {
+            UNROLL_LOOP_FULL()
+            for (size_t i = 0; i < MACHINE_HASH_SIZE; i += sizeof(uint64_t)) {
+                const uint64_t word = m_words[0][i / sizeof(uint64_t)][l];
+                __builtin_memcpy(&hashes[l][i], &word, sizeof(uint64_t));
+            }
+        }
+    }
+    template <size_t ConcatCount>
+    FORCE_INLINE static void simd_concat_hash(array2d<data_span, ConcatCount, LaneCount> data,
+        std::array<machine_hash_view, LaneCount> hashes) noexcept {
+        keccak_256_context ctx;
+        // Position is kept local to allow the compiler optimize it out when DataExtent is a compile time constant.
+        size_t pos = 0;
+        UNROLL_LOOP(4)
+        for (size_t i = 0; i < ConcatCount; ++i) {
+            ctx.update(data[i], pos);
+        }
+        ctx.finish(hashes, pos);
+    }
+};
+
+// Generic implementations
+
+MULTIVERSION_GENERIC size_t keccak_256_get_optimal_lane_count() noexcept {
+#if defined(__x86_64__)
+    // On AMD64, SSE2 has 128-bit registers, supporting up to 2 lanes.
+    return 2;
+#elif defined(__aarch64__)
+    // On ARM64, NEON has 128-bit registers, supporting up to 2 lanes.
+    return 2;
+#elif defined(__riscv) && defined(__riscv_v)
+    // RISC-V with Vector extension, we assume 128-bit registers are available, supporting up to 2 lanes.
+    return 2;
+#elif defined(__wasm_simd128__)
+    // WebAssembly with SIMD extension has 128-bit registers, supporting up to 2 lanes.
+    return 2;
+#else
+    // For other architectures, we assume vector instructions are not available and use scalar implementation.
+    return 1;
+#endif
+}
+
+MULTIVERSION_GENERIC void keccak_256_data_1x1(const array2d<std::span<const unsigned char>, 1, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept {
+    keccak_256_context<1>::simd_concat_hash<1>(data, hash);
+}
+MULTIVERSION_GENERIC void keccak_256_word_1x1(const array2d<const_hash_tree_word_view, 1, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept {
+    keccak_256_context<1, const_hash_tree_word_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_GENERIC void keccak_256_word_1x2(const array2d<const_hash_tree_word_view, 1, 2> &data,
+    const std::array<machine_hash_view, 2> &hash) noexcept {
+    keccak_256_context<2, const_hash_tree_word_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_GENERIC void keccak_256_word_1x4(const array2d<const_hash_tree_word_view, 1, 4> &data,
+    const std::array<machine_hash_view, 4> &hash) noexcept {
+    keccak_256_context<4, const_hash_tree_word_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_GENERIC void keccak_256_word_1x8(const array2d<const_hash_tree_word_view, 1, 8> &data,
+    const std::array<machine_hash_view, 8> &hash) noexcept {
+    keccak_256_context<8, const_hash_tree_word_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_GENERIC void keccak_256_data_2x1(const array2d<std::span<const unsigned char>, 2, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept {
+    keccak_256_context<1>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_GENERIC void keccak_256_hash_2x1(const array2d<const_machine_hash_view, 2, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept {
+    keccak_256_context<1, const_machine_hash_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_GENERIC void keccak_256_hash_2x2(const array2d<const_machine_hash_view, 2, 2> &data,
+    const std::array<machine_hash_view, 2> &hash) noexcept {
+    keccak_256_context<2, const_machine_hash_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_GENERIC void keccak_256_hash_2x4(const array2d<const_machine_hash_view, 2, 4> &data,
+    const std::array<machine_hash_view, 4> &hash) noexcept {
+    keccak_256_context<4, const_machine_hash_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_GENERIC void keccak_256_hash_2x8(const array2d<const_machine_hash_view, 2, 8> &data,
+    const std::array<machine_hash_view, 8> &hash) noexcept {
+    keccak_256_context<8, const_machine_hash_view::extent>::simd_concat_hash(data, hash);
+}
+
+// x86_64 implementations
+
+#ifdef USE_MULTIVERSINING_AMD64
+
+// AVX2
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 size_t keccak_256_get_optimal_lane_count() noexcept {
+    // AVX2 has 256-bit registers, supporting up to 4 lanes.
+    return 4;
+}
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void keccak_256_data_1x1(const array2d<std::span<const unsigned char>, 1, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept {
+    keccak_256_context<1>::simd_concat_hash<1>(data, hash);
+}
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void keccak_256_word_1x1(const array2d<const_hash_tree_word_view, 1, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept {
+    keccak_256_context<1, const_hash_tree_word_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void keccak_256_word_1x2(const array2d<const_hash_tree_word_view, 1, 2> &data,
+    const std::array<machine_hash_view, 2> &hash) noexcept {
+    keccak_256_context<2, const_hash_tree_word_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void keccak_256_word_1x4(const array2d<const_hash_tree_word_view, 1, 4> &data,
+    const std::array<machine_hash_view, 4> &hash) noexcept {
+    keccak_256_context<4, const_hash_tree_word_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void keccak_256_word_1x8(const array2d<const_hash_tree_word_view, 1, 8> &data,
+    const std::array<machine_hash_view, 8> &hash) noexcept {
+    keccak_256_context<8, const_hash_tree_word_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void keccak_256_data_2x1(const array2d<std::span<const unsigned char>, 2, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept {
+    keccak_256_context<1>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void keccak_256_hash_2x1(const array2d<const_machine_hash_view, 2, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept {
+    keccak_256_context<1, const_machine_hash_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void keccak_256_hash_2x2(const array2d<const_machine_hash_view, 2, 2> &data,
+    const std::array<machine_hash_view, 2> &hash) noexcept {
+    keccak_256_context<2, const_machine_hash_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void keccak_256_hash_2x4(const array2d<const_machine_hash_view, 2, 4> &data,
+    const std::array<machine_hash_view, 4> &hash) noexcept {
+    keccak_256_context<4, const_machine_hash_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void keccak_256_hash_2x8(const array2d<const_machine_hash_view, 2, 8> &data,
+    const std::array<machine_hash_view, 8> &hash) noexcept {
+    keccak_256_context<8, const_machine_hash_view::extent>::simd_concat_hash(data, hash);
+}
+
+// AVX-512
+
+MULTIVERSION_AMD64_AVX512_BMI_BMI2 size_t keccak_256_get_optimal_lane_count() noexcept {
+    // AVX-512 has 512-bit registers, supporting up to 8 lanes.
+    return 8;
+}
+MULTIVERSION_AMD64_AVX512_BMI_BMI2 void keccak_256_word_1x8(const array2d<const_hash_tree_word_view, 1, 8> &data,
+    const std::array<machine_hash_view, 8> &hash) noexcept {
+    keccak_256_context<8, const_hash_tree_word_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_AMD64_AVX512_BMI_BMI2 void keccak_256_hash_2x8(const array2d<const_machine_hash_view, 2, 8> &data,
+    const std::array<machine_hash_view, 8> &hash) noexcept {
+    keccak_256_context<8, const_machine_hash_view::extent>::simd_concat_hash(data, hash);
+}
+
+#endif // USE_MULTIVERSINING_AMD64
+
+} // namespace cartesi
diff --git a/src/keccak-256-hasher.h b/src/keccak-256-hasher.h
index 89fdf3e7e..16c522139 100644
--- a/src/keccak-256-hasher.h
+++ b/src/keccak-256-hasher.h
@@ -17,48 +17,95 @@
 #ifndef KECCAK_256_HASHER_H
 #define KECCAK_256_HASHER_H
 
+// TODO(edubart): remove this hack
+#if 0 // NOLINT(readability-avoid-unconditional-preprocessor-if)
+#include "sha-256-hasher.h"
+
+namespace cartesi {
+
+using keccak_256_hasher = sha_256_hasher;
+
+} // namespace cartesi
+
+#else
+
+#include <array>
 #include <cstddef>
 #include <cstdint>
+#include <span>
 #include <type_traits>
 
+#include "array2d.h"
+#include "compiler-defines.h"
 #include "i-hasher.h"
 #include "machine-hash.h"
 
-extern "C" {
-#include "sha3.h"
-}
-
 namespace cartesi {
 
-struct keccak_instance final {
-    union {
-        uint8_t b[200];
-        uint64_t q[25];
-    } st;
-    int pt;
-};
+// Generic implementations
+MULTIVERSION_GENERIC size_t keccak_256_get_optimal_lane_count() noexcept;
+MULTIVERSION_GENERIC void keccak_256_data_1x1(const array2d<std::span<const unsigned char>, 1, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept;
+MULTIVERSION_GENERIC void keccak_256_word_1x1(const array2d<const_hash_tree_word_view, 1, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept;
+MULTIVERSION_GENERIC void keccak_256_word_1x2(const array2d<const_hash_tree_word_view, 1, 2> &data,
+    const std::array<machine_hash_view, 2> &hash) noexcept;
+MULTIVERSION_GENERIC void keccak_256_word_1x4(const array2d<const_hash_tree_word_view, 1, 4> &data,
+    const std::array<machine_hash_view, 4> &hash) noexcept;
+MULTIVERSION_GENERIC void keccak_256_word_1x8(const array2d<const_hash_tree_word_view, 1, 8> &data,
+    const std::array<machine_hash_view, 8> &hash) noexcept;
+MULTIVERSION_GENERIC void keccak_256_data_2x1(const array2d<std::span<const unsigned char>, 2, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept;
+MULTIVERSION_GENERIC void keccak_256_hash_2x1(const array2d<const_machine_hash_view, 2, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept;
+MULTIVERSION_GENERIC void keccak_256_hash_2x2(const array2d<const_machine_hash_view, 2, 2> &data,
+    const std::array<machine_hash_view, 2> &hash) noexcept;
+MULTIVERSION_GENERIC void keccak_256_hash_2x4(const array2d<const_machine_hash_view, 2, 4> &data,
+    const std::array<machine_hash_view, 4> &hash) noexcept;
+MULTIVERSION_GENERIC void keccak_256_hash_2x8(const array2d<const_machine_hash_view, 2, 8> &data,
+    const std::array<machine_hash_view, 8> &hash) noexcept;
 
-class keccak_256_hasher final : public i_hasher<keccak_256_hasher> {
-    sha3_ctx_t m_ctx{};
-
-    friend i_hasher<keccak_256_hasher>;
-
-    void do_begin() noexcept {
-        sha3_init(&m_ctx, machine_hash_size, 0x01);
-    }
-
-    template <ContiguousRangeOfByteLike R>
-    void do_add_data(R &&r) noexcept { // NOLINT(cppcoreguidelines-missing-std-forward)
-        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        sha3_update(&m_ctx, reinterpret_cast<const unsigned char *>(std::ranges::data(r)), std::ranges::size(r));
-    }
-
-    void do_end(machine_hash_view hash) noexcept {
-        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        sha3_final(reinterpret_cast<unsigned char *>(hash.data()), &m_ctx);
-    }
+// Optimized implementation for x86_64 architecture leveraging modern CPU instruction sets:
+// - BMI1/BMI2 (Bit Manipulation Instructions) provide specialized bit operations:
+//   * RORX performs optimized bitwise rotation without requiring separate shift operations
+//   * ANDN efficiently computes (~x & y) in a single instruction
+// - AVX2 for x4 SIMD hashing
+// - AVX-512 for x8 SIMD hashing
+#ifdef USE_MULTIVERSINING_AMD64
+// AVX2 implementation for x1, x2, x4, x8 SIMD hashing
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 size_t keccak_256_get_optimal_lane_count() noexcept;
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void keccak_256_data_1x1(const array2d<std::span<const unsigned char>, 1, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept;
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void keccak_256_word_1x1(const array2d<const_hash_tree_word_view, 1, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept;
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void keccak_256_word_1x2(const array2d<const_hash_tree_word_view, 1, 2> &data,
+    const std::array<machine_hash_view, 2> &hash) noexcept;
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void keccak_256_word_1x4(const array2d<const_hash_tree_word_view, 1, 4> &data,
+    const std::array<machine_hash_view, 4> &hash) noexcept;
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void keccak_256_word_1x8(const array2d<const_hash_tree_word_view, 1, 8> &data,
+    const std::array<machine_hash_view, 8> &hash) noexcept;
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void keccak_256_data_2x1(const array2d<std::span<const unsigned char>, 2, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept;
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void keccak_256_hash_2x1(const array2d<const_machine_hash_view, 2, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept;
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void keccak_256_hash_2x2(const array2d<const_machine_hash_view, 2, 2> &data,
+    const std::array<machine_hash_view, 2> &hash) noexcept;
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void keccak_256_hash_2x4(const array2d<const_machine_hash_view, 2, 4> &data,
+    const std::array<machine_hash_view, 4> &hash) noexcept;
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void keccak_256_hash_2x8(const array2d<const_machine_hash_view, 2, 8> &data,
+    const std::array<machine_hash_view, 8> &hash) noexcept;
+// AVX-512 implementation for x8 SIMD hashing
+MULTIVERSION_AMD64_AVX512_BMI_BMI2 size_t keccak_256_get_optimal_lane_count() noexcept;
+MULTIVERSION_AMD64_AVX512_BMI_BMI2 void keccak_256_word_1x8(const array2d<const_hash_tree_word_view, 1, 8> &data,
+    const std::array<machine_hash_view, 8> &hash) noexcept;
+MULTIVERSION_AMD64_AVX512_BMI_BMI2 void keccak_256_hash_2x8(const array2d<const_machine_hash_view, 2, 8> &data,
+    const std::array<machine_hash_view, 8> &hash) noexcept;
+#endif
 
+class keccak_256_hasher final : public i_hasher<keccak_256_hasher> {
 public:
+    static constexpr int MAX_LANE_COUNT = 8; ///< Number of maximum supported SIMD lanes
+
     /// \brief Default constructor
     keccak_256_hasher() = default;
 
@@ -73,8 +120,193 @@ class keccak_256_hasher final : public i_hasher<keccak_256_hasher> {
     keccak_256_hasher &operator=(const keccak_256_hasher &) = delete;
     /// \brief No move assignment
     keccak_256_hasher &operator=(keccak_256_hasher &&) = delete;
+
+    // \brief Hashes the concatenation of data in SIMD using Keccak-256
+    // \tparam LaneCount Number of SIMD lanes
+    // \tparam ConcatCount Number of concatenated data items
+    // \tparam Extent Extent of the data span
+    // \param data Data to hash, as a multi-dimensional array of spans
+    // \param hash Array of machine hashes to store the results
+    // \warning When LaneCount is greater than 1, it is assumed data spans have same size, there is no check for that.
+    template <size_t ConcatCount, size_t LaneCount, size_t Extent>
+    static void do_simd_concat_hash(const array2d<std::span<const unsigned char, Extent>, ConcatCount, LaneCount> &data,
+        const std::array<machine_hash_view, LaneCount> &hash) noexcept;
+
+    // \brief Gets the optimal number of SIMD lanes for SHA-256
+    // \returns The optimal number of SIMD lanes for SHA-256
+    // \details This value is architecture-dependent and may vary based on the available instruction sets.
+    static size_t do_get_optimal_lane_count() noexcept {
+        return keccak_256_get_optimal_lane_count();
+    }
 };
 
+template <>
+inline void keccak_256_hasher::do_simd_concat_hash<1, 1, std::dynamic_extent>(
+    const array2d<std::span<const unsigned char>, 1, 1> &data, const std::array<machine_hash_view, 1> &hash) noexcept {
+    keccak_256_data_1x1(data, hash);
+}
+template <>
+inline void keccak_256_hasher::do_simd_concat_hash<1, 1, HASH_TREE_WORD_SIZE>(
+    const array2d<const_hash_tree_word_view, 1, 1> &data, const std::array<machine_hash_view, 1> &hash) noexcept {
+    keccak_256_word_1x1(data, hash);
+}
+template <>
+inline void keccak_256_hasher::do_simd_concat_hash<1, 2, HASH_TREE_WORD_SIZE>(
+    const array2d<const_hash_tree_word_view, 1, 2> &data, const std::array<machine_hash_view, 2> &hash) noexcept {
+    keccak_256_word_1x2(data, hash);
+}
+template <>
+inline void keccak_256_hasher::do_simd_concat_hash<1, 4, HASH_TREE_WORD_SIZE>(
+    const array2d<const_hash_tree_word_view, 1, 4> &data, const std::array<machine_hash_view, 4> &hash) noexcept {
+    keccak_256_word_1x4(data, hash);
+}
+template <>
+inline void keccak_256_hasher::do_simd_concat_hash<1, 8, HASH_TREE_WORD_SIZE>(
+    const array2d<const_hash_tree_word_view, 1, 8> &data, const std::array<machine_hash_view, 8> &hash) noexcept {
+    keccak_256_word_1x8(data, hash);
+}
+template <>
+inline void keccak_256_hasher::do_simd_concat_hash<1, 16, HASH_TREE_WORD_SIZE>(
+    const array2d<const_hash_tree_word_view, 1, 16> &data, const std::array<machine_hash_view, 16> &hash) noexcept {
+    // Keccak-256 does not support 16-way parallelism, we simulate it by splitting it into two 8-way hashes
+    keccak_256_word_1x8(array2d<const_hash_tree_word_view, 1, 8>{{{
+                            data[0][0],
+                            data[0][1],
+                            data[0][2],
+                            data[0][3],
+                            data[0][4],
+                            data[0][5],
+                            data[0][6],
+                            data[0][7],
+                        }}},
+        std::array<machine_hash_view, 8>{
+            hash[0],
+            hash[1],
+            hash[2],
+            hash[3],
+            hash[4],
+            hash[5],
+            hash[6],
+            hash[7],
+        });
+    keccak_256_word_1x8(array2d<const_hash_tree_word_view, 1, 8>{{{
+                            data[0][8],
+                            data[0][9],
+                            data[0][10],
+                            data[0][11],
+                            data[0][12],
+                            data[0][13],
+                            data[0][14],
+                            data[0][15],
+                        }}},
+        std::array<machine_hash_view, 8>{
+            hash[8],
+            hash[9],
+            hash[10],
+            hash[11],
+            hash[12],
+            hash[13],
+            hash[14],
+            hash[15],
+        });
+}
+template <>
+inline void keccak_256_hasher::do_simd_concat_hash<2, 1, std::dynamic_extent>(
+    const array2d<std::span<const unsigned char>, 2, 1> &data, const std::array<machine_hash_view, 1> &hash) noexcept {
+    keccak_256_data_2x1(data, hash);
+}
+template <>
+inline void keccak_256_hasher::do_simd_concat_hash<2, 1, MACHINE_HASH_SIZE>(
+    const array2d<const_machine_hash_view, 2, 1> &data, const std::array<machine_hash_view, 1> &hash) noexcept {
+    keccak_256_hash_2x1(data, hash);
+}
+template <>
+inline void keccak_256_hasher::do_simd_concat_hash<2, 2, MACHINE_HASH_SIZE>(
+    const array2d<const_machine_hash_view, 2, 2> &data, const std::array<machine_hash_view, 2> &hash) noexcept {
+    keccak_256_hash_2x2(data, hash);
+}
+template <>
+inline void keccak_256_hasher::do_simd_concat_hash<2, 4, MACHINE_HASH_SIZE>(
+    const array2d<const_machine_hash_view, 2, 4> &data, const std::array<machine_hash_view, 4> &hash) noexcept {
+    keccak_256_hash_2x4(data, hash);
+}
+template <>
+inline void keccak_256_hasher::do_simd_concat_hash<2, 8, MACHINE_HASH_SIZE>(
+    const array2d<const_machine_hash_view, 2, 8> &data, const std::array<machine_hash_view, 8> &hash) noexcept {
+    keccak_256_hash_2x8(data, hash);
+}
+template <>
+inline void keccak_256_hasher::do_simd_concat_hash<2, 16, MACHINE_HASH_SIZE>(
+    const array2d<const_machine_hash_view, 2, 16> &data, const std::array<machine_hash_view, 16> &hash) noexcept {
+    // Keccak-256 does not support 16-way parallelism, we simulate it by splitting it into two 8-way hashes
+    keccak_256_hash_2x8(array2d<const_machine_hash_view, 2, 8>{{
+                            {
+                                data[0][0],
+                                data[0][1],
+                                data[0][2],
+                                data[0][3],
+                                data[0][4],
+                                data[0][5],
+                                data[0][6],
+                                data[0][7],
+                            },
+                            {
+                                data[1][0],
+                                data[1][1],
+                                data[1][2],
+                                data[1][3],
+                                data[1][4],
+                                data[1][5],
+                                data[1][6],
+                                data[1][7],
+                            },
+                        }},
+        std::array<machine_hash_view, 8>{
+            hash[0],
+            hash[1],
+            hash[2],
+            hash[3],
+            hash[4],
+            hash[5],
+            hash[6],
+            hash[7],
+        });
+    keccak_256_hash_2x8(array2d<const_machine_hash_view, 2, 8>{{
+                            {
+                                data[0][8],
+                                data[0][9],
+                                data[0][10],
+                                data[0][11],
+                                data[0][12],
+                                data[0][13],
+                                data[0][14],
+                                data[0][15],
+                            },
+                            {
+                                data[1][8],
+                                data[1][9],
+                                data[1][10],
+                                data[1][11],
+                                data[1][12],
+                                data[1][13],
+                                data[1][14],
+                                data[1][15],
+                            },
+                        }},
+        std::array<machine_hash_view, 8>{
+            hash[8],
+            hash[9],
+            hash[10],
+            hash[11],
+            hash[12],
+            hash[13],
+            hash[14],
+            hash[15],
+        });
+}
+
 } // namespace cartesi
 
+#endif // #if
+
 #endif
diff --git a/src/keccakf.h b/src/keccakf.h
new file mode 100644
index 000000000..9a4f41274
--- /dev/null
+++ b/src/keccakf.h
@@ -0,0 +1,2573 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef KECCAKF_H
+#define KECCAKF_H
+
+#include <cstddef>
+#include <cstdint>
+
+#include "compiler-defines.h"
+
+namespace cartesi {
+
+template <typename word_vector_type, size_t word_vector_align>
+// NOLINTNEXTLINE(readability-function-size,hicpp-function-size,google-readability-function-size)
+FORCE_INLINE static void keccakf_1600(word_vector_type A[5][5]) noexcept {
+    // This code is adapted from the XKCP generic64 Keccak implementation (public domain).
+    // Original source:
+    // https://github.com/XKCP/XKCP/blob/master/lib/low/KeccakP-1600/plain-64bits/KeccakP-1600-opt64.c
+    // Selected for its 64-bit optimization, vectorization-friendly structure, branchless design, and efficient
+    // memory bandwidth.
+    alignas(word_vector_align) static constexpr uint64_t KECCAKF1600_ROUND_CONSTANTS[24] = {0x0000000000000001,
+        0x0000000000008082, 0x800000000000808a, 0x8000000080008000, 0x000000000000808b, 0x0000000080000001,
+        0x8000000080008081, 0x8000000000008009, 0x000000000000008a, 0x0000000000000088, 0x0000000080008009,
+        0x000000008000000a, 0x000000008000808b, 0x800000000000008b, 0x8000000000008089, 0x8000000000008003,
+        0x8000000000008002, 0x8000000000000080, 0x000000000000800a, 0x800000008000000a, 0x8000000080008081,
+        0x8000000000008080, 0x0000000080000001, 0x8000000080008008};
+    word_vector_type B[5][5];
+    word_vector_type C[5];
+    word_vector_type D[5];
+    word_vector_type E[5][5];
+    C[0] = A[0][0] ^ A[1][0] ^ A[2][0] ^ A[3][0] ^ A[4][0];
+    C[1] = A[0][1] ^ A[1][1] ^ A[2][1] ^ A[3][1] ^ A[4][1];
+    C[2] = A[0][2] ^ A[1][2] ^ A[2][2] ^ A[3][2] ^ A[4][2];
+    C[3] = A[0][3] ^ A[1][3] ^ A[2][3] ^ A[3][3] ^ A[4][3];
+    C[4] = A[0][4] ^ A[1][4] ^ A[2][4] ^ A[3][4] ^ A[4][4];
+    D[0] = C[4] ^ (((C[1]) << 1) ^ ((C[1]) >> (64 - 1)));
+    D[1] = C[0] ^ (((C[2]) << 1) ^ ((C[2]) >> (64 - 1)));
+    D[2] = C[1] ^ (((C[3]) << 1) ^ ((C[3]) >> (64 - 1)));
+    D[3] = C[2] ^ (((C[4]) << 1) ^ ((C[4]) >> (64 - 1)));
+    D[4] = C[3] ^ (((C[0]) << 1) ^ ((C[0]) >> (64 - 1)));
+    A[0][0] ^= D[0];
+    B[0][0] = A[0][0];
+    A[1][1] ^= D[1];
+    B[0][1] = (((A[1][1]) << 44) ^ ((A[1][1]) >> (64 - 44)));
+    A[2][2] ^= D[2];
+    B[0][2] = (((A[2][2]) << 43) ^ ((A[2][2]) >> (64 - 43)));
+    A[3][3] ^= D[3];
+    B[0][3] = (((A[3][3]) << 21) ^ ((A[3][3]) >> (64 - 21)));
+    A[4][4] ^= D[4];
+    B[0][4] = (((A[4][4]) << 14) ^ ((A[4][4]) >> (64 - 14)));
+    E[0][0] = B[0][0] ^ ((~B[0][1]) & B[0][2]);
+    E[0][0] ^= KECCAKF1600_ROUND_CONSTANTS[0];
+    C[0] = E[0][0];
+    E[0][1] = B[0][1] ^ ((~B[0][2]) & B[0][3]);
+    C[1] = E[0][1];
+    E[0][2] = B[0][2] ^ ((~B[0][3]) & B[0][4]);
+    C[2] = E[0][2];
+    E[0][3] = B[0][3] ^ ((~B[0][4]) & B[0][0]);
+    C[3] = E[0][3];
+    E[0][4] = B[0][4] ^ ((~B[0][0]) & B[0][1]);
+    C[4] = E[0][4];
+    A[0][3] ^= D[3];
+    B[1][0] = (((A[0][3]) << 28) ^ ((A[0][3]) >> (64 - 28)));
+    A[1][4] ^= D[4];
+    B[1][1] = (((A[1][4]) << 20) ^ ((A[1][4]) >> (64 - 20)));
+    A[2][0] ^= D[0];
+    B[1][2] = (((A[2][0]) << 3) ^ ((A[2][0]) >> (64 - 3)));
+    A[3][1] ^= D[1];
+    B[1][3] = (((A[3][1]) << 45) ^ ((A[3][1]) >> (64 - 45)));
+    A[4][2] ^= D[2];
+    B[1][4] = (((A[4][2]) << 61) ^ ((A[4][2]) >> (64 - 61)));
+    E[1][0] = B[1][0] ^ ((~B[1][1]) & B[1][2]);
+    C[0] ^= E[1][0];
+    E[1][1] = B[1][1] ^ ((~B[1][2]) & B[1][3]);
+    C[1] ^= E[1][1];
+    E[1][2] = B[1][2] ^ ((~B[1][3]) & B[1][4]);
+    C[2] ^= E[1][2];
+    E[1][3] = B[1][3] ^ ((~B[1][4]) & B[1][0]);
+    C[3] ^= E[1][3];
+    E[1][4] = B[1][4] ^ ((~B[1][0]) & B[1][1]);
+    C[4] ^= E[1][4];
+    A[0][1] ^= D[1];
+    B[2][0] = (((A[0][1]) << 1) ^ ((A[0][1]) >> (64 - 1)));
+    A[1][2] ^= D[2];
+    B[2][1] = (((A[1][2]) << 6) ^ ((A[1][2]) >> (64 - 6)));
+    A[2][3] ^= D[3];
+    B[2][2] = (((A[2][3]) << 25) ^ ((A[2][3]) >> (64 - 25)));
+    A[3][4] ^= D[4];
+    B[2][3] = (((A[3][4]) << 8) ^ ((A[3][4]) >> (64 - 8)));
+    A[4][0] ^= D[0];
+    B[2][4] = (((A[4][0]) << 18) ^ ((A[4][0]) >> (64 - 18)));
+    E[2][0] = B[2][0] ^ ((~B[2][1]) & B[2][2]);
+    C[0] ^= E[2][0];
+    E[2][1] = B[2][1] ^ ((~B[2][2]) & B[2][3]);
+    C[1] ^= E[2][1];
+    E[2][2] = B[2][2] ^ ((~B[2][3]) & B[2][4]);
+    C[2] ^= E[2][2];
+    E[2][3] = B[2][3] ^ ((~B[2][4]) & B[2][0]);
+    C[3] ^= E[2][3];
+    E[2][4] = B[2][4] ^ ((~B[2][0]) & B[2][1]);
+    C[4] ^= E[2][4];
+    A[0][4] ^= D[4];
+    B[3][0] = (((A[0][4]) << 27) ^ ((A[0][4]) >> (64 - 27)));
+    A[1][0] ^= D[0];
+    B[3][1] = (((A[1][0]) << 36) ^ ((A[1][0]) >> (64 - 36)));
+    A[2][1] ^= D[1];
+    B[3][2] = (((A[2][1]) << 10) ^ ((A[2][1]) >> (64 - 10)));
+    A[3][2] ^= D[2];
+    B[3][3] = (((A[3][2]) << 15) ^ ((A[3][2]) >> (64 - 15)));
+    A[4][3] ^= D[3];
+    B[3][4] = (((A[4][3]) << 56) ^ ((A[4][3]) >> (64 - 56)));
+    E[3][0] = B[3][0] ^ ((~B[3][1]) & B[3][2]);
+    C[0] ^= E[3][0];
+    E[3][1] = B[3][1] ^ ((~B[3][2]) & B[3][3]);
+    C[1] ^= E[3][1];
+    E[3][2] = B[3][2] ^ ((~B[3][3]) & B[3][4]);
+    C[2] ^= E[3][2];
+    E[3][3] = B[3][3] ^ ((~B[3][4]) & B[3][0]);
+    C[3] ^= E[3][3];
+    E[3][4] = B[3][4] ^ ((~B[3][0]) & B[3][1]);
+    C[4] ^= E[3][4];
+    A[0][2] ^= D[2];
+    B[4][0] = (((A[0][2]) << 62) ^ ((A[0][2]) >> (64 - 62)));
+    A[1][3] ^= D[3];
+    B[4][1] = (((A[1][3]) << 55) ^ ((A[1][3]) >> (64 - 55)));
+    A[2][4] ^= D[4];
+    B[4][2] = (((A[2][4]) << 39) ^ ((A[2][4]) >> (64 - 39)));
+    A[3][0] ^= D[0];
+    B[4][3] = (((A[3][0]) << 41) ^ ((A[3][0]) >> (64 - 41)));
+    A[4][1] ^= D[1];
+    B[4][4] = (((A[4][1]) << 2) ^ ((A[4][1]) >> (64 - 2)));
+    E[4][0] = B[4][0] ^ ((~B[4][1]) & B[4][2]);
+    C[0] ^= E[4][0];
+    E[4][1] = B[4][1] ^ ((~B[4][2]) & B[4][3]);
+    C[1] ^= E[4][1];
+    E[4][2] = B[4][2] ^ ((~B[4][3]) & B[4][4]);
+    C[2] ^= E[4][2];
+    E[4][3] = B[4][3] ^ ((~B[4][4]) & B[4][0]);
+    C[3] ^= E[4][3];
+    E[4][4] = B[4][4] ^ ((~B[4][0]) & B[4][1]);
+    C[4] ^= E[4][4];
+    D[0] = C[4] ^ (((C[1]) << 1) ^ ((C[1]) >> (64 - 1)));
+    D[1] = C[0] ^ (((C[2]) << 1) ^ ((C[2]) >> (64 - 1)));
+    D[2] = C[1] ^ (((C[3]) << 1) ^ ((C[3]) >> (64 - 1)));
+    D[3] = C[2] ^ (((C[4]) << 1) ^ ((C[4]) >> (64 - 1)));
+    D[4] = C[3] ^ (((C[0]) << 1) ^ ((C[0]) >> (64 - 1)));
+    E[0][0] ^= D[0];
+    B[0][0] = E[0][0];
+    E[1][1] ^= D[1];
+    B[0][1] = (((E[1][1]) << 44) ^ ((E[1][1]) >> (64 - 44)));
+    E[2][2] ^= D[2];
+    B[0][2] = (((E[2][2]) << 43) ^ ((E[2][2]) >> (64 - 43)));
+    E[3][3] ^= D[3];
+    B[0][3] = (((E[3][3]) << 21) ^ ((E[3][3]) >> (64 - 21)));
+    E[4][4] ^= D[4];
+    B[0][4] = (((E[4][4]) << 14) ^ ((E[4][4]) >> (64 - 14)));
+    A[0][0] = B[0][0] ^ ((~B[0][1]) & B[0][2]);
+    A[0][0] ^= KECCAKF1600_ROUND_CONSTANTS[1];
+    C[0] = A[0][0];
+    A[0][1] = B[0][1] ^ ((~B[0][2]) & B[0][3]);
+    C[1] = A[0][1];
+    A[0][2] = B[0][2] ^ ((~B[0][3]) & B[0][4]);
+    C[2] = A[0][2];
+    A[0][3] = B[0][3] ^ ((~B[0][4]) & B[0][0]);
+    C[3] = A[0][3];
+    A[0][4] = B[0][4] ^ ((~B[0][0]) & B[0][1]);
+    C[4] = A[0][4];
+    E[0][3] ^= D[3];
+    B[1][0] = (((E[0][3]) << 28) ^ ((E[0][3]) >> (64 - 28)));
+    E[1][4] ^= D[4];
+    B[1][1] = (((E[1][4]) << 20) ^ ((E[1][4]) >> (64 - 20)));
+    E[2][0] ^= D[0];
+    B[1][2] = (((E[2][0]) << 3) ^ ((E[2][0]) >> (64 - 3)));
+    E[3][1] ^= D[1];
+    B[1][3] = (((E[3][1]) << 45) ^ ((E[3][1]) >> (64 - 45)));
+    E[4][2] ^= D[2];
+    B[1][4] = (((E[4][2]) << 61) ^ ((E[4][2]) >> (64 - 61)));
+    A[1][0] = B[1][0] ^ ((~B[1][1]) & B[1][2]);
+    C[0] ^= A[1][0];
+    A[1][1] = B[1][1] ^ ((~B[1][2]) & B[1][3]);
+    C[1] ^= A[1][1];
+    A[1][2] = B[1][2] ^ ((~B[1][3]) & B[1][4]);
+    C[2] ^= A[1][2];
+    A[1][3] = B[1][3] ^ ((~B[1][4]) & B[1][0]);
+    C[3] ^= A[1][3];
+    A[1][4] = B[1][4] ^ ((~B[1][0]) & B[1][1]);
+    C[4] ^= A[1][4];
+    E[0][1] ^= D[1];
+    B[2][0] = (((E[0][1]) << 1) ^ ((E[0][1]) >> (64 - 1)));
+    E[1][2] ^= D[2];
+    B[2][1] = (((E[1][2]) << 6) ^ ((E[1][2]) >> (64 - 6)));
+    E[2][3] ^= D[3];
+    B[2][2] = (((E[2][3]) << 25) ^ ((E[2][3]) >> (64 - 25)));
+    E[3][4] ^= D[4];
+    B[2][3] = (((E[3][4]) << 8) ^ ((E[3][4]) >> (64 - 8)));
+    E[4][0] ^= D[0];
+    B[2][4] = (((E[4][0]) << 18) ^ ((E[4][0]) >> (64 - 18)));
+    A[2][0] = B[2][0] ^ ((~B[2][1]) & B[2][2]);
+    C[0] ^= A[2][0];
+    A[2][1] = B[2][1] ^ ((~B[2][2]) & B[2][3]);
+    C[1] ^= A[2][1];
+    A[2][2] = B[2][2] ^ ((~B[2][3]) & B[2][4]);
+    C[2] ^= A[2][2];
+    A[2][3] = B[2][3] ^ ((~B[2][4]) & B[2][0]);
+    C[3] ^= A[2][3];
+    A[2][4] = B[2][4] ^ ((~B[2][0]) & B[2][1]);
+    C[4] ^= A[2][4];
+    E[0][4] ^= D[4];
+    B[3][0] = (((E[0][4]) << 27) ^ ((E[0][4]) >> (64 - 27)));
+    E[1][0] ^= D[0];
+    B[3][1] = (((E[1][0]) << 36) ^ ((E[1][0]) >> (64 - 36)));
+    E[2][1] ^= D[1];
+    B[3][2] = (((E[2][1]) << 10) ^ ((E[2][1]) >> (64 - 10)));
+    E[3][2] ^= D[2];
+    B[3][3] = (((E[3][2]) << 15) ^ ((E[3][2]) >> (64 - 15)));
+    E[4][3] ^= D[3];
+    B[3][4] = (((E[4][3]) << 56) ^ ((E[4][3]) >> (64 - 56)));
+    A[3][0] = B[3][0] ^ ((~B[3][1]) & B[3][2]);
+    C[0] ^= A[3][0];
+    A[3][1] = B[3][1] ^ ((~B[3][2]) & B[3][3]);
+    C[1] ^= A[3][1];
+    A[3][2] = B[3][2] ^ ((~B[3][3]) & B[3][4]);
+    C[2] ^= A[3][2];
+    A[3][3] = B[3][3] ^ ((~B[3][4]) & B[3][0]);
+    C[3] ^= A[3][3];
+    A[3][4] = B[3][4] ^ ((~B[3][0]) & B[3][1]);
+    C[4] ^= A[3][4];
+    E[0][2] ^= D[2];
+    B[4][0] = (((E[0][2]) << 62) ^ ((E[0][2]) >> (64 - 62)));
+    E[1][3] ^= D[3];
+    B[4][1] = (((E[1][3]) << 55) ^ ((E[1][3]) >> (64 - 55)));
+    E[2][4] ^= D[4];
+    B[4][2] = (((E[2][4]) << 39) ^ ((E[2][4]) >> (64 - 39)));
+    E[3][0] ^= D[0];
+    B[4][3] = (((E[3][0]) << 41) ^ ((E[3][0]) >> (64 - 41)));
+    E[4][1] ^= D[1];
+    B[4][4] = (((E[4][1]) << 2) ^ ((E[4][1]) >> (64 - 2)));
+    A[4][0] = B[4][0] ^ ((~B[4][1]) & B[4][2]);
+    C[0] ^= A[4][0];
+    A[4][1] = B[4][1] ^ ((~B[4][2]) & B[4][3]);
+    C[1] ^= A[4][1];
+    A[4][2] = B[4][2] ^ ((~B[4][3]) & B[4][4]);
+    C[2] ^= A[4][2];
+    A[4][3] = B[4][3] ^ ((~B[4][4]) & B[4][0]);
+    C[3] ^= A[4][3];
+    A[4][4] = B[4][4] ^ ((~B[4][0]) & B[4][1]);
+    C[4] ^= A[4][4];
+    D[0] = C[4] ^ (((C[1]) << 1) ^ ((C[1]) >> (64 - 1)));
+    D[1] = C[0] ^ (((C[2]) << 1) ^ ((C[2]) >> (64 - 1)));
+    D[2] = C[1] ^ (((C[3]) << 1) ^ ((C[3]) >> (64 - 1)));
+    D[3] = C[2] ^ (((C[4]) << 1) ^ ((C[4]) >> (64 - 1)));
+    D[4] = C[3] ^ (((C[0]) << 1) ^ ((C[0]) >> (64 - 1)));
+    A[0][0] ^= D[0];
+    B[0][0] = A[0][0];
+    A[1][1] ^= D[1];
+    B[0][1] = (((A[1][1]) << 44) ^ ((A[1][1]) >> (64 - 44)));
+    A[2][2] ^= D[2];
+    B[0][2] = (((A[2][2]) << 43) ^ ((A[2][2]) >> (64 - 43)));
+    A[3][3] ^= D[3];
+    B[0][3] = (((A[3][3]) << 21) ^ ((A[3][3]) >> (64 - 21)));
+    A[4][4] ^= D[4];
+    B[0][4] = (((A[4][4]) << 14) ^ ((A[4][4]) >> (64 - 14)));
+    E[0][0] = B[0][0] ^ ((~B[0][1]) & B[0][2]);
+    E[0][0] ^= KECCAKF1600_ROUND_CONSTANTS[2];
+    C[0] = E[0][0];
+    E[0][1] = B[0][1] ^ ((~B[0][2]) & B[0][3]);
+    C[1] = E[0][1];
+    E[0][2] = B[0][2] ^ ((~B[0][3]) & B[0][4]);
+    C[2] = E[0][2];
+    E[0][3] = B[0][3] ^ ((~B[0][4]) & B[0][0]);
+    C[3] = E[0][3];
+    E[0][4] = B[0][4] ^ ((~B[0][0]) & B[0][1]);
+    C[4] = E[0][4];
+    A[0][3] ^= D[3];
+    B[1][0] = (((A[0][3]) << 28) ^ ((A[0][3]) >> (64 - 28)));
+    A[1][4] ^= D[4];
+    B[1][1] = (((A[1][4]) << 20) ^ ((A[1][4]) >> (64 - 20)));
+    A[2][0] ^= D[0];
+    B[1][2] = (((A[2][0]) << 3) ^ ((A[2][0]) >> (64 - 3)));
+    A[3][1] ^= D[1];
+    B[1][3] = (((A[3][1]) << 45) ^ ((A[3][1]) >> (64 - 45)));
+    A[4][2] ^= D[2];
+    B[1][4] = (((A[4][2]) << 61) ^ ((A[4][2]) >> (64 - 61)));
+    E[1][0] = B[1][0] ^ ((~B[1][1]) & B[1][2]);
+    C[0] ^= E[1][0];
+    E[1][1] = B[1][1] ^ ((~B[1][2]) & B[1][3]);
+    C[1] ^= E[1][1];
+    E[1][2] = B[1][2] ^ ((~B[1][3]) & B[1][4]);
+    C[2] ^= E[1][2];
+    E[1][3] = B[1][3] ^ ((~B[1][4]) & B[1][0]);
+    C[3] ^= E[1][3];
+    E[1][4] = B[1][4] ^ ((~B[1][0]) & B[1][1]);
+    C[4] ^= E[1][4];
+    A[0][1] ^= D[1];
+    B[2][0] = (((A[0][1]) << 1) ^ ((A[0][1]) >> (64 - 1)));
+    A[1][2] ^= D[2];
+    B[2][1] = (((A[1][2]) << 6) ^ ((A[1][2]) >> (64 - 6)));
+    A[2][3] ^= D[3];
+    B[2][2] = (((A[2][3]) << 25) ^ ((A[2][3]) >> (64 - 25)));
+    A[3][4] ^= D[4];
+    B[2][3] = (((A[3][4]) << 8) ^ ((A[3][4]) >> (64 - 8)));
+    A[4][0] ^= D[0];
+    B[2][4] = (((A[4][0]) << 18) ^ ((A[4][0]) >> (64 - 18)));
+    E[2][0] = B[2][0] ^ ((~B[2][1]) & B[2][2]);
+    C[0] ^= E[2][0];
+    E[2][1] = B[2][1] ^ ((~B[2][2]) & B[2][3]);
+    C[1] ^= E[2][1];
+    E[2][2] = B[2][2] ^ ((~B[2][3]) & B[2][4]);
+    C[2] ^= E[2][2];
+    E[2][3] = B[2][3] ^ ((~B[2][4]) & B[2][0]);
+    C[3] ^= E[2][3];
+    E[2][4] = B[2][4] ^ ((~B[2][0]) & B[2][1]);
+    C[4] ^= E[2][4];
+    A[0][4] ^= D[4];
+    B[3][0] = (((A[0][4]) << 27) ^ ((A[0][4]) >> (64 - 27)));
+    A[1][0] ^= D[0];
+    B[3][1] = (((A[1][0]) << 36) ^ ((A[1][0]) >> (64 - 36)));
+    A[2][1] ^= D[1];
+    B[3][2] = (((A[2][1]) << 10) ^ ((A[2][1]) >> (64 - 10)));
+    A[3][2] ^= D[2];
+    B[3][3] = (((A[3][2]) << 15) ^ ((A[3][2]) >> (64 - 15)));
+    A[4][3] ^= D[3];
+    B[3][4] = (((A[4][3]) << 56) ^ ((A[4][3]) >> (64 - 56)));
+    E[3][0] = B[3][0] ^ ((~B[3][1]) & B[3][2]);
+    C[0] ^= E[3][0];
+    E[3][1] = B[3][1] ^ ((~B[3][2]) & B[3][3]);
+    C[1] ^= E[3][1];
+    E[3][2] = B[3][2] ^ ((~B[3][3]) & B[3][4]);
+    C[2] ^= E[3][2];
+    E[3][3] = B[3][3] ^ ((~B[3][4]) & B[3][0]);
+    C[3] ^= E[3][3];
+    E[3][4] = B[3][4] ^ ((~B[3][0]) & B[3][1]);
+    C[4] ^= E[3][4];
+    A[0][2] ^= D[2];
+    B[4][0] = (((A[0][2]) << 62) ^ ((A[0][2]) >> (64 - 62)));
+    A[1][3] ^= D[3];
+    B[4][1] = (((A[1][3]) << 55) ^ ((A[1][3]) >> (64 - 55)));
+    A[2][4] ^= D[4];
+    B[4][2] = (((A[2][4]) << 39) ^ ((A[2][4]) >> (64 - 39)));
+    A[3][0] ^= D[0];
+    B[4][3] = (((A[3][0]) << 41) ^ ((A[3][0]) >> (64 - 41)));
+    A[4][1] ^= D[1];
+    B[4][4] = (((A[4][1]) << 2) ^ ((A[4][1]) >> (64 - 2)));
+    E[4][0] = B[4][0] ^ ((~B[4][1]) & B[4][2]);
+    C[0] ^= E[4][0];
+    E[4][1] = B[4][1] ^ ((~B[4][2]) & B[4][3]);
+    C[1] ^= E[4][1];
+    E[4][2] = B[4][2] ^ ((~B[4][3]) & B[4][4]);
+    C[2] ^= E[4][2];
+    E[4][3] = B[4][3] ^ ((~B[4][4]) & B[4][0]);
+    C[3] ^= E[4][3];
+    E[4][4] = B[4][4] ^ ((~B[4][0]) & B[4][1]);
+    C[4] ^= E[4][4];
+    D[0] = C[4] ^ (((C[1]) << 1) ^ ((C[1]) >> (64 - 1)));
+    D[1] = C[0] ^ (((C[2]) << 1) ^ ((C[2]) >> (64 - 1)));
+    D[2] = C[1] ^ (((C[3]) << 1) ^ ((C[3]) >> (64 - 1)));
+    D[3] = C[2] ^ (((C[4]) << 1) ^ ((C[4]) >> (64 - 1)));
+    D[4] = C[3] ^ (((C[0]) << 1) ^ ((C[0]) >> (64 - 1)));
+    E[0][0] ^= D[0];
+    B[0][0] = E[0][0];
+    E[1][1] ^= D[1];
+    B[0][1] = (((E[1][1]) << 44) ^ ((E[1][1]) >> (64 - 44)));
+    E[2][2] ^= D[2];
+    B[0][2] = (((E[2][2]) << 43) ^ ((E[2][2]) >> (64 - 43)));
+    E[3][3] ^= D[3];
+    B[0][3] = (((E[3][3]) << 21) ^ ((E[3][3]) >> (64 - 21)));
+    E[4][4] ^= D[4];
+    B[0][4] = (((E[4][4]) << 14) ^ ((E[4][4]) >> (64 - 14)));
+    A[0][0] = B[0][0] ^ ((~B[0][1]) & B[0][2]);
+    A[0][0] ^= KECCAKF1600_ROUND_CONSTANTS[3];
+    C[0] = A[0][0];
+    A[0][1] = B[0][1] ^ ((~B[0][2]) & B[0][3]);
+    C[1] = A[0][1];
+    A[0][2] = B[0][2] ^ ((~B[0][3]) & B[0][4]);
+    C[2] = A[0][2];
+    A[0][3] = B[0][3] ^ ((~B[0][4]) & B[0][0]);
+    C[3] = A[0][3];
+    A[0][4] = B[0][4] ^ ((~B[0][0]) & B[0][1]);
+    C[4] = A[0][4];
+    E[0][3] ^= D[3];
+    B[1][0] = (((E[0][3]) << 28) ^ ((E[0][3]) >> (64 - 28)));
+    E[1][4] ^= D[4];
+    B[1][1] = (((E[1][4]) << 20) ^ ((E[1][4]) >> (64 - 20)));
+    E[2][0] ^= D[0];
+    B[1][2] = (((E[2][0]) << 3) ^ ((E[2][0]) >> (64 - 3)));
+    E[3][1] ^= D[1];
+    B[1][3] = (((E[3][1]) << 45) ^ ((E[3][1]) >> (64 - 45)));
+    E[4][2] ^= D[2];
+    B[1][4] = (((E[4][2]) << 61) ^ ((E[4][2]) >> (64 - 61)));
+    A[1][0] = B[1][0] ^ ((~B[1][1]) & B[1][2]);
+    C[0] ^= A[1][0];
+    A[1][1] = B[1][1] ^ ((~B[1][2]) & B[1][3]);
+    C[1] ^= A[1][1];
+    A[1][2] = B[1][2] ^ ((~B[1][3]) & B[1][4]);
+    C[2] ^= A[1][2];
+    A[1][3] = B[1][3] ^ ((~B[1][4]) & B[1][0]);
+    C[3] ^= A[1][3];
+    A[1][4] = B[1][4] ^ ((~B[1][0]) & B[1][1]);
+    C[4] ^= A[1][4];
+    E[0][1] ^= D[1];
+    B[2][0] = (((E[0][1]) << 1) ^ ((E[0][1]) >> (64 - 1)));
+    E[1][2] ^= D[2];
+    B[2][1] = (((E[1][2]) << 6) ^ ((E[1][2]) >> (64 - 6)));
+    E[2][3] ^= D[3];
+    B[2][2] = (((E[2][3]) << 25) ^ ((E[2][3]) >> (64 - 25)));
+    E[3][4] ^= D[4];
+    B[2][3] = (((E[3][4]) << 8) ^ ((E[3][4]) >> (64 - 8)));
+    E[4][0] ^= D[0];
+    B[2][4] = (((E[4][0]) << 18) ^ ((E[4][0]) >> (64 - 18)));
+    A[2][0] = B[2][0] ^ ((~B[2][1]) & B[2][2]);
+    C[0] ^= A[2][0];
+    A[2][1] = B[2][1] ^ ((~B[2][2]) & B[2][3]);
+    C[1] ^= A[2][1];
+    A[2][2] = B[2][2] ^ ((~B[2][3]) & B[2][4]);
+    C[2] ^= A[2][2];
+    A[2][3] = B[2][3] ^ ((~B[2][4]) & B[2][0]);
+    C[3] ^= A[2][3];
+    A[2][4] = B[2][4] ^ ((~B[2][0]) & B[2][1]);
+    C[4] ^= A[2][4];
+    E[0][4] ^= D[4];
+    B[3][0] = (((E[0][4]) << 27) ^ ((E[0][4]) >> (64 - 27)));
+    E[1][0] ^= D[0];
+    B[3][1] = (((E[1][0]) << 36) ^ ((E[1][0]) >> (64 - 36)));
+    E[2][1] ^= D[1];
+    B[3][2] = (((E[2][1]) << 10) ^ ((E[2][1]) >> (64 - 10)));
+    E[3][2] ^= D[2];
+    B[3][3] = (((E[3][2]) << 15) ^ ((E[3][2]) >> (64 - 15)));
+    E[4][3] ^= D[3];
+    B[3][4] = (((E[4][3]) << 56) ^ ((E[4][3]) >> (64 - 56)));
+    A[3][0] = B[3][0] ^ ((~B[3][1]) & B[3][2]);
+    C[0] ^= A[3][0];
+    A[3][1] = B[3][1] ^ ((~B[3][2]) & B[3][3]);
+    C[1] ^= A[3][1];
+    A[3][2] = B[3][2] ^ ((~B[3][3]) & B[3][4]);
+    C[2] ^= A[3][2];
+    A[3][3] = B[3][3] ^ ((~B[3][4]) & B[3][0]);
+    C[3] ^= A[3][3];
+    A[3][4] = B[3][4] ^ ((~B[3][0]) & B[3][1]);
+    C[4] ^= A[3][4];
+    E[0][2] ^= D[2];
+    B[4][0] = (((E[0][2]) << 62) ^ ((E[0][2]) >> (64 - 62)));
+    E[1][3] ^= D[3];
+    B[4][1] = (((E[1][3]) << 55) ^ ((E[1][3]) >> (64 - 55)));
+    E[2][4] ^= D[4];
+    B[4][2] = (((E[2][4]) << 39) ^ ((E[2][4]) >> (64 - 39)));
+    E[3][0] ^= D[0];
+    B[4][3] = (((E[3][0]) << 41) ^ ((E[3][0]) >> (64 - 41)));
+    E[4][1] ^= D[1];
+    B[4][4] = (((E[4][1]) << 2) ^ ((E[4][1]) >> (64 - 2)));
+    A[4][0] = B[4][0] ^ ((~B[4][1]) & B[4][2]);
+    C[0] ^= A[4][0];
+    A[4][1] = B[4][1] ^ ((~B[4][2]) & B[4][3]);
+    C[1] ^= A[4][1];
+    A[4][2] = B[4][2] ^ ((~B[4][3]) & B[4][4]);
+    C[2] ^= A[4][2];
+    A[4][3] = B[4][3] ^ ((~B[4][4]) & B[4][0]);
+    C[3] ^= A[4][3];
+    A[4][4] = B[4][4] ^ ((~B[4][0]) & B[4][1]);
+    C[4] ^= A[4][4];
+    D[0] = C[4] ^ (((C[1]) << 1) ^ ((C[1]) >> (64 - 1)));
+    D[1] = C[0] ^ (((C[2]) << 1) ^ ((C[2]) >> (64 - 1)));
+    D[2] = C[1] ^ (((C[3]) << 1) ^ ((C[3]) >> (64 - 1)));
+    D[3] = C[2] ^ (((C[4]) << 1) ^ ((C[4]) >> (64 - 1)));
+    D[4] = C[3] ^ (((C[0]) << 1) ^ ((C[0]) >> (64 - 1)));
+    A[0][0] ^= D[0];
+    B[0][0] = A[0][0];
+    A[1][1] ^= D[1];
+    B[0][1] = (((A[1][1]) << 44) ^ ((A[1][1]) >> (64 - 44)));
+    A[2][2] ^= D[2];
+    B[0][2] = (((A[2][2]) << 43) ^ ((A[2][2]) >> (64 - 43)));
+    A[3][3] ^= D[3];
+    B[0][3] = (((A[3][3]) << 21) ^ ((A[3][3]) >> (64 - 21)));
+    A[4][4] ^= D[4];
+    B[0][4] = (((A[4][4]) << 14) ^ ((A[4][4]) >> (64 - 14)));
+    E[0][0] = B[0][0] ^ ((~B[0][1]) & B[0][2]);
+    E[0][0] ^= KECCAKF1600_ROUND_CONSTANTS[4];
+    C[0] = E[0][0];
+    E[0][1] = B[0][1] ^ ((~B[0][2]) & B[0][3]);
+    C[1] = E[0][1];
+    E[0][2] = B[0][2] ^ ((~B[0][3]) & B[0][4]);
+    C[2] = E[0][2];
+    E[0][3] = B[0][3] ^ ((~B[0][4]) & B[0][0]);
+    C[3] = E[0][3];
+    E[0][4] = B[0][4] ^ ((~B[0][0]) & B[0][1]);
+    C[4] = E[0][4];
+    A[0][3] ^= D[3];
+    B[1][0] = (((A[0][3]) << 28) ^ ((A[0][3]) >> (64 - 28)));
+    A[1][4] ^= D[4];
+    B[1][1] = (((A[1][4]) << 20) ^ ((A[1][4]) >> (64 - 20)));
+    A[2][0] ^= D[0];
+    B[1][2] = (((A[2][0]) << 3) ^ ((A[2][0]) >> (64 - 3)));
+    A[3][1] ^= D[1];
+    B[1][3] = (((A[3][1]) << 45) ^ ((A[3][1]) >> (64 - 45)));
+    A[4][2] ^= D[2];
+    B[1][4] = (((A[4][2]) << 61) ^ ((A[4][2]) >> (64 - 61)));
+    E[1][0] = B[1][0] ^ ((~B[1][1]) & B[1][2]);
+    C[0] ^= E[1][0];
+    E[1][1] = B[1][1] ^ ((~B[1][2]) & B[1][3]);
+    C[1] ^= E[1][1];
+    E[1][2] = B[1][2] ^ ((~B[1][3]) & B[1][4]);
+    C[2] ^= E[1][2];
+    E[1][3] = B[1][3] ^ ((~B[1][4]) & B[1][0]);
+    C[3] ^= E[1][3];
+    E[1][4] = B[1][4] ^ ((~B[1][0]) & B[1][1]);
+    C[4] ^= E[1][4];
+    A[0][1] ^= D[1];
+    B[2][0] = (((A[0][1]) << 1) ^ ((A[0][1]) >> (64 - 1)));
+    A[1][2] ^= D[2];
+    B[2][1] = (((A[1][2]) << 6) ^ ((A[1][2]) >> (64 - 6)));
+    A[2][3] ^= D[3];
+    B[2][2] = (((A[2][3]) << 25) ^ ((A[2][3]) >> (64 - 25)));
+    A[3][4] ^= D[4];
+    B[2][3] = (((A[3][4]) << 8) ^ ((A[3][4]) >> (64 - 8)));
+    A[4][0] ^= D[0];
+    B[2][4] = (((A[4][0]) << 18) ^ ((A[4][0]) >> (64 - 18)));
+    E[2][0] = B[2][0] ^ ((~B[2][1]) & B[2][2]);
+    C[0] ^= E[2][0];
+    E[2][1] = B[2][1] ^ ((~B[2][2]) & B[2][3]);
+    C[1] ^= E[2][1];
+    E[2][2] = B[2][2] ^ ((~B[2][3]) & B[2][4]);
+    C[2] ^= E[2][2];
+    E[2][3] = B[2][3] ^ ((~B[2][4]) & B[2][0]);
+    C[3] ^= E[2][3];
+    E[2][4] = B[2][4] ^ ((~B[2][0]) & B[2][1]);
+    C[4] ^= E[2][4];
+    A[0][4] ^= D[4];
+    B[3][0] = (((A[0][4]) << 27) ^ ((A[0][4]) >> (64 - 27)));
+    A[1][0] ^= D[0];
+    B[3][1] = (((A[1][0]) << 36) ^ ((A[1][0]) >> (64 - 36)));
+    A[2][1] ^= D[1];
+    B[3][2] = (((A[2][1]) << 10) ^ ((A[2][1]) >> (64 - 10)));
+    A[3][2] ^= D[2];
+    B[3][3] = (((A[3][2]) << 15) ^ ((A[3][2]) >> (64 - 15)));
+    A[4][3] ^= D[3];
+    B[3][4] = (((A[4][3]) << 56) ^ ((A[4][3]) >> (64 - 56)));
+    E[3][0] = B[3][0] ^ ((~B[3][1]) & B[3][2]);
+    C[0] ^= E[3][0];
+    E[3][1] = B[3][1] ^ ((~B[3][2]) & B[3][3]);
+    C[1] ^= E[3][1];
+    E[3][2] = B[3][2] ^ ((~B[3][3]) & B[3][4]);
+    C[2] ^= E[3][2];
+    E[3][3] = B[3][3] ^ ((~B[3][4]) & B[3][0]);
+    C[3] ^= E[3][3];
+    E[3][4] = B[3][4] ^ ((~B[3][0]) & B[3][1]);
+    C[4] ^= E[3][4];
+    A[0][2] ^= D[2];
+    B[4][0] = (((A[0][2]) << 62) ^ ((A[0][2]) >> (64 - 62)));
+    A[1][3] ^= D[3];
+    B[4][1] = (((A[1][3]) << 55) ^ ((A[1][3]) >> (64 - 55)));
+    A[2][4] ^= D[4];
+    B[4][2] = (((A[2][4]) << 39) ^ ((A[2][4]) >> (64 - 39)));
+    A[3][0] ^= D[0];
+    B[4][3] = (((A[3][0]) << 41) ^ ((A[3][0]) >> (64 - 41)));
+    A[4][1] ^= D[1];
+    B[4][4] = (((A[4][1]) << 2) ^ ((A[4][1]) >> (64 - 2)));
+    E[4][0] = B[4][0] ^ ((~B[4][1]) & B[4][2]);
+    C[0] ^= E[4][0];
+    E[4][1] = B[4][1] ^ ((~B[4][2]) & B[4][3]);
+    C[1] ^= E[4][1];
+    E[4][2] = B[4][2] ^ ((~B[4][3]) & B[4][4]);
+    C[2] ^= E[4][2];
+    E[4][3] = B[4][3] ^ ((~B[4][4]) & B[4][0]);
+    C[3] ^= E[4][3];
+    E[4][4] = B[4][4] ^ ((~B[4][0]) & B[4][1]);
+    C[4] ^= E[4][4];
+    D[0] = C[4] ^ (((C[1]) << 1) ^ ((C[1]) >> (64 - 1)));
+    D[1] = C[0] ^ (((C[2]) << 1) ^ ((C[2]) >> (64 - 1)));
+    D[2] = C[1] ^ (((C[3]) << 1) ^ ((C[3]) >> (64 - 1)));
+    D[3] = C[2] ^ (((C[4]) << 1) ^ ((C[4]) >> (64 - 1)));
+    D[4] = C[3] ^ (((C[0]) << 1) ^ ((C[0]) >> (64 - 1)));
+    E[0][0] ^= D[0];
+    B[0][0] = E[0][0];
+    E[1][1] ^= D[1];
+    B[0][1] = (((E[1][1]) << 44) ^ ((E[1][1]) >> (64 - 44)));
+    E[2][2] ^= D[2];
+    B[0][2] = (((E[2][2]) << 43) ^ ((E[2][2]) >> (64 - 43)));
+    E[3][3] ^= D[3];
+    B[0][3] = (((E[3][3]) << 21) ^ ((E[3][3]) >> (64 - 21)));
+    E[4][4] ^= D[4];
+    B[0][4] = (((E[4][4]) << 14) ^ ((E[4][4]) >> (64 - 14)));
+    A[0][0] = B[0][0] ^ ((~B[0][1]) & B[0][2]);
+    A[0][0] ^= KECCAKF1600_ROUND_CONSTANTS[5];
+    C[0] = A[0][0];
+    A[0][1] = B[0][1] ^ ((~B[0][2]) & B[0][3]);
+    C[1] = A[0][1];
+    A[0][2] = B[0][2] ^ ((~B[0][3]) & B[0][4]);
+    C[2] = A[0][2];
+    A[0][3] = B[0][3] ^ ((~B[0][4]) & B[0][0]);
+    C[3] = A[0][3];
+    A[0][4] = B[0][4] ^ ((~B[0][0]) & B[0][1]);
+    C[4] = A[0][4];
+    E[0][3] ^= D[3];
+    B[1][0] = (((E[0][3]) << 28) ^ ((E[0][3]) >> (64 - 28)));
+    E[1][4] ^= D[4];
+    B[1][1] = (((E[1][4]) << 20) ^ ((E[1][4]) >> (64 - 20)));
+    E[2][0] ^= D[0];
+    B[1][2] = (((E[2][0]) << 3) ^ ((E[2][0]) >> (64 - 3)));
+    E[3][1] ^= D[1];
+    B[1][3] = (((E[3][1]) << 45) ^ ((E[3][1]) >> (64 - 45)));
+    E[4][2] ^= D[2];
+    B[1][4] = (((E[4][2]) << 61) ^ ((E[4][2]) >> (64 - 61)));
+    A[1][0] = B[1][0] ^ ((~B[1][1]) & B[1][2]);
+    C[0] ^= A[1][0];
+    A[1][1] = B[1][1] ^ ((~B[1][2]) & B[1][3]);
+    C[1] ^= A[1][1];
+    A[1][2] = B[1][2] ^ ((~B[1][3]) & B[1][4]);
+    C[2] ^= A[1][2];
+    A[1][3] = B[1][3] ^ ((~B[1][4]) & B[1][0]);
+    C[3] ^= A[1][3];
+    A[1][4] = B[1][4] ^ ((~B[1][0]) & B[1][1]);
+    C[4] ^= A[1][4];
+    E[0][1] ^= D[1];
+    B[2][0] = (((E[0][1]) << 1) ^ ((E[0][1]) >> (64 - 1)));
+    E[1][2] ^= D[2];
+    B[2][1] = (((E[1][2]) << 6) ^ ((E[1][2]) >> (64 - 6)));
+    E[2][3] ^= D[3];
+    B[2][2] = (((E[2][3]) << 25) ^ ((E[2][3]) >> (64 - 25)));
+    E[3][4] ^= D[4];
+    B[2][3] = (((E[3][4]) << 8) ^ ((E[3][4]) >> (64 - 8)));
+    E[4][0] ^= D[0];
+    B[2][4] = (((E[4][0]) << 18) ^ ((E[4][0]) >> (64 - 18)));
+    A[2][0] = B[2][0] ^ ((~B[2][1]) & B[2][2]);
+    C[0] ^= A[2][0];
+    A[2][1] = B[2][1] ^ ((~B[2][2]) & B[2][3]);
+    C[1] ^= A[2][1];
+    A[2][2] = B[2][2] ^ ((~B[2][3]) & B[2][4]);
+    C[2] ^= A[2][2];
+    A[2][3] = B[2][3] ^ ((~B[2][4]) & B[2][0]);
+    C[3] ^= A[2][3];
+    A[2][4] = B[2][4] ^ ((~B[2][0]) & B[2][1]);
+    C[4] ^= A[2][4];
+    E[0][4] ^= D[4];
+    B[3][0] = (((E[0][4]) << 27) ^ ((E[0][4]) >> (64 - 27)));
+    E[1][0] ^= D[0];
+    B[3][1] = (((E[1][0]) << 36) ^ ((E[1][0]) >> (64 - 36)));
+    E[2][1] ^= D[1];
+    B[3][2] = (((E[2][1]) << 10) ^ ((E[2][1]) >> (64 - 10)));
+    E[3][2] ^= D[2];
+    B[3][3] = (((E[3][2]) << 15) ^ ((E[3][2]) >> (64 - 15)));
+    E[4][3] ^= D[3];
+    B[3][4] = (((E[4][3]) << 56) ^ ((E[4][3]) >> (64 - 56)));
+    A[3][0] = B[3][0] ^ ((~B[3][1]) & B[3][2]);
+    C[0] ^= A[3][0];
+    A[3][1] = B[3][1] ^ ((~B[3][2]) & B[3][3]);
+    C[1] ^= A[3][1];
+    A[3][2] = B[3][2] ^ ((~B[3][3]) & B[3][4]);
+    C[2] ^= A[3][2];
+    A[3][3] = B[3][3] ^ ((~B[3][4]) & B[3][0]);
+    C[3] ^= A[3][3];
+    A[3][4] = B[3][4] ^ ((~B[3][0]) & B[3][1]);
+    C[4] ^= A[3][4];
+    E[0][2] ^= D[2];
+    B[4][0] = (((E[0][2]) << 62) ^ ((E[0][2]) >> (64 - 62)));
+    E[1][3] ^= D[3];
+    B[4][1] = (((E[1][3]) << 55) ^ ((E[1][3]) >> (64 - 55)));
+    E[2][4] ^= D[4];
+    B[4][2] = (((E[2][4]) << 39) ^ ((E[2][4]) >> (64 - 39)));
+    E[3][0] ^= D[0];
+    B[4][3] = (((E[3][0]) << 41) ^ ((E[3][0]) >> (64 - 41)));
+    E[4][1] ^= D[1];
+    B[4][4] = (((E[4][1]) << 2) ^ ((E[4][1]) >> (64 - 2)));
+    A[4][0] = B[4][0] ^ ((~B[4][1]) & B[4][2]);
+    C[0] ^= A[4][0];
+    A[4][1] = B[4][1] ^ ((~B[4][2]) & B[4][3]);
+    C[1] ^= A[4][1];
+    A[4][2] = B[4][2] ^ ((~B[4][3]) & B[4][4]);
+    C[2] ^= A[4][2];
+    A[4][3] = B[4][3] ^ ((~B[4][4]) & B[4][0]);
+    C[3] ^= A[4][3];
+    A[4][4] = B[4][4] ^ ((~B[4][0]) & B[4][1]);
+    C[4] ^= A[4][4];
+    D[0] = C[4] ^ (((C[1]) << 1) ^ ((C[1]) >> (64 - 1)));
+    D[1] = C[0] ^ (((C[2]) << 1) ^ ((C[2]) >> (64 - 1)));
+    D[2] = C[1] ^ (((C[3]) << 1) ^ ((C[3]) >> (64 - 1)));
+    D[3] = C[2] ^ (((C[4]) << 1) ^ ((C[4]) >> (64 - 1)));
+    D[4] = C[3] ^ (((C[0]) << 1) ^ ((C[0]) >> (64 - 1)));
+    A[0][0] ^= D[0];
+    B[0][0] = A[0][0];
+    A[1][1] ^= D[1];
+    B[0][1] = (((A[1][1]) << 44) ^ ((A[1][1]) >> (64 - 44)));
+    A[2][2] ^= D[2];
+    B[0][2] = (((A[2][2]) << 43) ^ ((A[2][2]) >> (64 - 43)));
+    A[3][3] ^= D[3];
+    B[0][3] = (((A[3][3]) << 21) ^ ((A[3][3]) >> (64 - 21)));
+    A[4][4] ^= D[4];
+    B[0][4] = (((A[4][4]) << 14) ^ ((A[4][4]) >> (64 - 14)));
+    E[0][0] = B[0][0] ^ ((~B[0][1]) & B[0][2]);
+    E[0][0] ^= KECCAKF1600_ROUND_CONSTANTS[6];
+    C[0] = E[0][0];
+    E[0][1] = B[0][1] ^ ((~B[0][2]) & B[0][3]);
+    C[1] = E[0][1];
+    E[0][2] = B[0][2] ^ ((~B[0][3]) & B[0][4]);
+    C[2] = E[0][2];
+    E[0][3] = B[0][3] ^ ((~B[0][4]) & B[0][0]);
+    C[3] = E[0][3];
+    E[0][4] = B[0][4] ^ ((~B[0][0]) & B[0][1]);
+    C[4] = E[0][4];
+    A[0][3] ^= D[3];
+    B[1][0] = (((A[0][3]) << 28) ^ ((A[0][3]) >> (64 - 28)));
+    A[1][4] ^= D[4];
+    B[1][1] = (((A[1][4]) << 20) ^ ((A[1][4]) >> (64 - 20)));
+    A[2][0] ^= D[0];
+    B[1][2] = (((A[2][0]) << 3) ^ ((A[2][0]) >> (64 - 3)));
+    A[3][1] ^= D[1];
+    B[1][3] = (((A[3][1]) << 45) ^ ((A[3][1]) >> (64 - 45)));
+    A[4][2] ^= D[2];
+    B[1][4] = (((A[4][2]) << 61) ^ ((A[4][2]) >> (64 - 61)));
+    E[1][0] = B[1][0] ^ ((~B[1][1]) & B[1][2]);
+    C[0] ^= E[1][0];
+    E[1][1] = B[1][1] ^ ((~B[1][2]) & B[1][3]);
+    C[1] ^= E[1][1];
+    E[1][2] = B[1][2] ^ ((~B[1][3]) & B[1][4]);
+    C[2] ^= E[1][2];
+    E[1][3] = B[1][3] ^ ((~B[1][4]) & B[1][0]);
+    C[3] ^= E[1][3];
+    E[1][4] = B[1][4] ^ ((~B[1][0]) & B[1][1]);
+    C[4] ^= E[1][4];
+    A[0][1] ^= D[1];
+    B[2][0] = (((A[0][1]) << 1) ^ ((A[0][1]) >> (64 - 1)));
+    A[1][2] ^= D[2];
+    B[2][1] = (((A[1][2]) << 6) ^ ((A[1][2]) >> (64 - 6)));
+    A[2][3] ^= D[3];
+    B[2][2] = (((A[2][3]) << 25) ^ ((A[2][3]) >> (64 - 25)));
+    A[3][4] ^= D[4];
+    B[2][3] = (((A[3][4]) << 8) ^ ((A[3][4]) >> (64 - 8)));
+    A[4][0] ^= D[0];
+    B[2][4] = (((A[4][0]) << 18) ^ ((A[4][0]) >> (64 - 18)));
+    E[2][0] = B[2][0] ^ ((~B[2][1]) & B[2][2]);
+    C[0] ^= E[2][0];
+    E[2][1] = B[2][1] ^ ((~B[2][2]) & B[2][3]);
+    C[1] ^= E[2][1];
+    E[2][2] = B[2][2] ^ ((~B[2][3]) & B[2][4]);
+    C[2] ^= E[2][2];
+    E[2][3] = B[2][3] ^ ((~B[2][4]) & B[2][0]);
+    C[3] ^= E[2][3];
+    E[2][4] = B[2][4] ^ ((~B[2][0]) & B[2][1]);
+    C[4] ^= E[2][4];
+    A[0][4] ^= D[4];
+    B[3][0] = (((A[0][4]) << 27) ^ ((A[0][4]) >> (64 - 27)));
+    A[1][0] ^= D[0];
+    B[3][1] = (((A[1][0]) << 36) ^ ((A[1][0]) >> (64 - 36)));
+    A[2][1] ^= D[1];
+    B[3][2] = (((A[2][1]) << 10) ^ ((A[2][1]) >> (64 - 10)));
+    A[3][2] ^= D[2];
+    B[3][3] = (((A[3][2]) << 15) ^ ((A[3][2]) >> (64 - 15)));
+    A[4][3] ^= D[3];
+    B[3][4] = (((A[4][3]) << 56) ^ ((A[4][3]) >> (64 - 56)));
+    E[3][0] = B[3][0] ^ ((~B[3][1]) & B[3][2]);
+    C[0] ^= E[3][0];
+    E[3][1] = B[3][1] ^ ((~B[3][2]) & B[3][3]);
+    C[1] ^= E[3][1];
+    E[3][2] = B[3][2] ^ ((~B[3][3]) & B[3][4]);
+    C[2] ^= E[3][2];
+    E[3][3] = B[3][3] ^ ((~B[3][4]) & B[3][0]);
+    C[3] ^= E[3][3];
+    E[3][4] = B[3][4] ^ ((~B[3][0]) & B[3][1]);
+    C[4] ^= E[3][4];
+    A[0][2] ^= D[2];
+    B[4][0] = (((A[0][2]) << 62) ^ ((A[0][2]) >> (64 - 62)));
+    A[1][3] ^= D[3];
+    B[4][1] = (((A[1][3]) << 55) ^ ((A[1][3]) >> (64 - 55)));
+    A[2][4] ^= D[4];
+    B[4][2] = (((A[2][4]) << 39) ^ ((A[2][4]) >> (64 - 39)));
+    A[3][0] ^= D[0];
+    B[4][3] = (((A[3][0]) << 41) ^ ((A[3][0]) >> (64 - 41)));
+    A[4][1] ^= D[1];
+    B[4][4] = (((A[4][1]) << 2) ^ ((A[4][1]) >> (64 - 2)));
+    E[4][0] = B[4][0] ^ ((~B[4][1]) & B[4][2]);
+    C[0] ^= E[4][0];
+    E[4][1] = B[4][1] ^ ((~B[4][2]) & B[4][3]);
+    C[1] ^= E[4][1];
+    E[4][2] = B[4][2] ^ ((~B[4][3]) & B[4][4]);
+    C[2] ^= E[4][2];
+    E[4][3] = B[4][3] ^ ((~B[4][4]) & B[4][0]);
+    C[3] ^= E[4][3];
+    E[4][4] = B[4][4] ^ ((~B[4][0]) & B[4][1]);
+    C[4] ^= E[4][4];
+    D[0] = C[4] ^ (((C[1]) << 1) ^ ((C[1]) >> (64 - 1)));
+    D[1] = C[0] ^ (((C[2]) << 1) ^ ((C[2]) >> (64 - 1)));
+    D[2] = C[1] ^ (((C[3]) << 1) ^ ((C[3]) >> (64 - 1)));
+    D[3] = C[2] ^ (((C[4]) << 1) ^ ((C[4]) >> (64 - 1)));
+    D[4] = C[3] ^ (((C[0]) << 1) ^ ((C[0]) >> (64 - 1)));
+    E[0][0] ^= D[0];
+    B[0][0] = E[0][0];
+    E[1][1] ^= D[1];
+    B[0][1] = (((E[1][1]) << 44) ^ ((E[1][1]) >> (64 - 44)));
+    E[2][2] ^= D[2];
+    B[0][2] = (((E[2][2]) << 43) ^ ((E[2][2]) >> (64 - 43)));
+    E[3][3] ^= D[3];
+    B[0][3] = (((E[3][3]) << 21) ^ ((E[3][3]) >> (64 - 21)));
+    E[4][4] ^= D[4];
+    B[0][4] = (((E[4][4]) << 14) ^ ((E[4][4]) >> (64 - 14)));
+    A[0][0] = B[0][0] ^ ((~B[0][1]) & B[0][2]);
+    A[0][0] ^= KECCAKF1600_ROUND_CONSTANTS[7];
+    C[0] = A[0][0];
+    A[0][1] = B[0][1] ^ ((~B[0][2]) & B[0][3]);
+    C[1] = A[0][1];
+    A[0][2] = B[0][2] ^ ((~B[0][3]) & B[0][4]);
+    C[2] = A[0][2];
+    A[0][3] = B[0][3] ^ ((~B[0][4]) & B[0][0]);
+    C[3] = A[0][3];
+    A[0][4] = B[0][4] ^ ((~B[0][0]) & B[0][1]);
+    C[4] = A[0][4];
+    E[0][3] ^= D[3];
+    B[1][0] = (((E[0][3]) << 28) ^ ((E[0][3]) >> (64 - 28)));
+    E[1][4] ^= D[4];
+    B[1][1] = (((E[1][4]) << 20) ^ ((E[1][4]) >> (64 - 20)));
+    E[2][0] ^= D[0];
+    B[1][2] = (((E[2][0]) << 3) ^ ((E[2][0]) >> (64 - 3)));
+    E[3][1] ^= D[1];
+    B[1][3] = (((E[3][1]) << 45) ^ ((E[3][1]) >> (64 - 45)));
+    E[4][2] ^= D[2];
+    B[1][4] = (((E[4][2]) << 61) ^ ((E[4][2]) >> (64 - 61)));
+    A[1][0] = B[1][0] ^ ((~B[1][1]) & B[1][2]);
+    C[0] ^= A[1][0];
+    A[1][1] = B[1][1] ^ ((~B[1][2]) & B[1][3]);
+    C[1] ^= A[1][1];
+    A[1][2] = B[1][2] ^ ((~B[1][3]) & B[1][4]);
+    C[2] ^= A[1][2];
+    A[1][3] = B[1][3] ^ ((~B[1][4]) & B[1][0]);
+    C[3] ^= A[1][3];
+    A[1][4] = B[1][4] ^ ((~B[1][0]) & B[1][1]);
+    C[4] ^= A[1][4];
+    E[0][1] ^= D[1];
+    B[2][0] = (((E[0][1]) << 1) ^ ((E[0][1]) >> (64 - 1)));
+    E[1][2] ^= D[2];
+    B[2][1] = (((E[1][2]) << 6) ^ ((E[1][2]) >> (64 - 6)));
+    E[2][3] ^= D[3];
+    B[2][2] = (((E[2][3]) << 25) ^ ((E[2][3]) >> (64 - 25)));
+    E[3][4] ^= D[4];
+    B[2][3] = (((E[3][4]) << 8) ^ ((E[3][4]) >> (64 - 8)));
+    E[4][0] ^= D[0];
+    B[2][4] = (((E[4][0]) << 18) ^ ((E[4][0]) >> (64 - 18)));
+    A[2][0] = B[2][0] ^ ((~B[2][1]) & B[2][2]);
+    C[0] ^= A[2][0];
+    A[2][1] = B[2][1] ^ ((~B[2][2]) & B[2][3]);
+    C[1] ^= A[2][1];
+    A[2][2] = B[2][2] ^ ((~B[2][3]) & B[2][4]);
+    C[2] ^= A[2][2];
+    A[2][3] = B[2][3] ^ ((~B[2][4]) & B[2][0]);
+    C[3] ^= A[2][3];
+    A[2][4] = B[2][4] ^ ((~B[2][0]) & B[2][1]);
+    C[4] ^= A[2][4];
+    E[0][4] ^= D[4];
+    B[3][0] = (((E[0][4]) << 27) ^ ((E[0][4]) >> (64 - 27)));
+    E[1][0] ^= D[0];
+    B[3][1] = (((E[1][0]) << 36) ^ ((E[1][0]) >> (64 - 36)));
+    E[2][1] ^= D[1];
+    B[3][2] = (((E[2][1]) << 10) ^ ((E[2][1]) >> (64 - 10)));
+    E[3][2] ^= D[2];
+    B[3][3] = (((E[3][2]) << 15) ^ ((E[3][2]) >> (64 - 15)));
+    E[4][3] ^= D[3];
+    B[3][4] = (((E[4][3]) << 56) ^ ((E[4][3]) >> (64 - 56)));
+    A[3][0] = B[3][0] ^ ((~B[3][1]) & B[3][2]);
+    C[0] ^= A[3][0];
+    A[3][1] = B[3][1] ^ ((~B[3][2]) & B[3][3]);
+    C[1] ^= A[3][1];
+    A[3][2] = B[3][2] ^ ((~B[3][3]) & B[3][4]);
+    C[2] ^= A[3][2];
+    A[3][3] = B[3][3] ^ ((~B[3][4]) & B[3][0]);
+    C[3] ^= A[3][3];
+    A[3][4] = B[3][4] ^ ((~B[3][0]) & B[3][1]);
+    C[4] ^= A[3][4];
+    E[0][2] ^= D[2];
+    B[4][0] = (((E[0][2]) << 62) ^ ((E[0][2]) >> (64 - 62)));
+    E[1][3] ^= D[3];
+    B[4][1] = (((E[1][3]) << 55) ^ ((E[1][3]) >> (64 - 55)));
+    E[2][4] ^= D[4];
+    B[4][2] = (((E[2][4]) << 39) ^ ((E[2][4]) >> (64 - 39)));
+    E[3][0] ^= D[0];
+    B[4][3] = (((E[3][0]) << 41) ^ ((E[3][0]) >> (64 - 41)));
+    E[4][1] ^= D[1];
+    B[4][4] = (((E[4][1]) << 2) ^ ((E[4][1]) >> (64 - 2)));
+    A[4][0] = B[4][0] ^ ((~B[4][1]) & B[4][2]);
+    C[0] ^= A[4][0];
+    A[4][1] = B[4][1] ^ ((~B[4][2]) & B[4][3]);
+    C[1] ^= A[4][1];
+    A[4][2] = B[4][2] ^ ((~B[4][3]) & B[4][4]);
+    C[2] ^= A[4][2];
+    A[4][3] = B[4][3] ^ ((~B[4][4]) & B[4][0]);
+    C[3] ^= A[4][3];
+    A[4][4] = B[4][4] ^ ((~B[4][0]) & B[4][1]);
+    C[4] ^= A[4][4];
+    D[0] = C[4] ^ (((C[1]) << 1) ^ ((C[1]) >> (64 - 1)));
+    D[1] = C[0] ^ (((C[2]) << 1) ^ ((C[2]) >> (64 - 1)));
+    D[2] = C[1] ^ (((C[3]) << 1) ^ ((C[3]) >> (64 - 1)));
+    D[3] = C[2] ^ (((C[4]) << 1) ^ ((C[4]) >> (64 - 1)));
+    D[4] = C[3] ^ (((C[0]) << 1) ^ ((C[0]) >> (64 - 1)));
+    A[0][0] ^= D[0];
+    B[0][0] = A[0][0];
+    A[1][1] ^= D[1];
+    B[0][1] = (((A[1][1]) << 44) ^ ((A[1][1]) >> (64 - 44)));
+    A[2][2] ^= D[2];
+    B[0][2] = (((A[2][2]) << 43) ^ ((A[2][2]) >> (64 - 43)));
+    A[3][3] ^= D[3];
+    B[0][3] = (((A[3][3]) << 21) ^ ((A[3][3]) >> (64 - 21)));
+    A[4][4] ^= D[4];
+    B[0][4] = (((A[4][4]) << 14) ^ ((A[4][4]) >> (64 - 14)));
+    E[0][0] = B[0][0] ^ ((~B[0][1]) & B[0][2]);
+    E[0][0] ^= KECCAKF1600_ROUND_CONSTANTS[8];
+    C[0] = E[0][0];
+    E[0][1] = B[0][1] ^ ((~B[0][2]) & B[0][3]);
+    C[1] = E[0][1];
+    E[0][2] = B[0][2] ^ ((~B[0][3]) & B[0][4]);
+    C[2] = E[0][2];
+    E[0][3] = B[0][3] ^ ((~B[0][4]) & B[0][0]);
+    C[3] = E[0][3];
+    E[0][4] = B[0][4] ^ ((~B[0][0]) & B[0][1]);
+    C[4] = E[0][4];
+    A[0][3] ^= D[3];
+    B[1][0] = (((A[0][3]) << 28) ^ ((A[0][3]) >> (64 - 28)));
+    A[1][4] ^= D[4];
+    B[1][1] = (((A[1][4]) << 20) ^ ((A[1][4]) >> (64 - 20)));
+    A[2][0] ^= D[0];
+    B[1][2] = (((A[2][0]) << 3) ^ ((A[2][0]) >> (64 - 3)));
+    A[3][1] ^= D[1];
+    B[1][3] = (((A[3][1]) << 45) ^ ((A[3][1]) >> (64 - 45)));
+    A[4][2] ^= D[2];
+    B[1][4] = (((A[4][2]) << 61) ^ ((A[4][2]) >> (64 - 61)));
+    E[1][0] = B[1][0] ^ ((~B[1][1]) & B[1][2]);
+    C[0] ^= E[1][0];
+    E[1][1] = B[1][1] ^ ((~B[1][2]) & B[1][3]);
+    C[1] ^= E[1][1];
+    E[1][2] = B[1][2] ^ ((~B[1][3]) & B[1][4]);
+    C[2] ^= E[1][2];
+    E[1][3] = B[1][3] ^ ((~B[1][4]) & B[1][0]);
+    C[3] ^= E[1][3];
+    E[1][4] = B[1][4] ^ ((~B[1][0]) & B[1][1]);
+    C[4] ^= E[1][4];
+    A[0][1] ^= D[1];
+    B[2][0] = (((A[0][1]) << 1) ^ ((A[0][1]) >> (64 - 1)));
+    A[1][2] ^= D[2];
+    B[2][1] = (((A[1][2]) << 6) ^ ((A[1][2]) >> (64 - 6)));
+    A[2][3] ^= D[3];
+    B[2][2] = (((A[2][3]) << 25) ^ ((A[2][3]) >> (64 - 25)));
+    A[3][4] ^= D[4];
+    B[2][3] = (((A[3][4]) << 8) ^ ((A[3][4]) >> (64 - 8)));
+    A[4][0] ^= D[0];
+    B[2][4] = (((A[4][0]) << 18) ^ ((A[4][0]) >> (64 - 18)));
+    E[2][0] = B[2][0] ^ ((~B[2][1]) & B[2][2]);
+    C[0] ^= E[2][0];
+    E[2][1] = B[2][1] ^ ((~B[2][2]) & B[2][3]);
+    C[1] ^= E[2][1];
+    E[2][2] = B[2][2] ^ ((~B[2][3]) & B[2][4]);
+    C[2] ^= E[2][2];
+    E[2][3] = B[2][3] ^ ((~B[2][4]) & B[2][0]);
+    C[3] ^= E[2][3];
+    E[2][4] = B[2][4] ^ ((~B[2][0]) & B[2][1]);
+    C[4] ^= E[2][4];
+    A[0][4] ^= D[4];
+    B[3][0] = (((A[0][4]) << 27) ^ ((A[0][4]) >> (64 - 27)));
+    A[1][0] ^= D[0];
+    B[3][1] = (((A[1][0]) << 36) ^ ((A[1][0]) >> (64 - 36)));
+    A[2][1] ^= D[1];
+    B[3][2] = (((A[2][1]) << 10) ^ ((A[2][1]) >> (64 - 10)));
+    A[3][2] ^= D[2];
+    B[3][3] = (((A[3][2]) << 15) ^ ((A[3][2]) >> (64 - 15)));
+    A[4][3] ^= D[3];
+    B[3][4] = (((A[4][3]) << 56) ^ ((A[4][3]) >> (64 - 56)));
+    E[3][0] = B[3][0] ^ ((~B[3][1]) & B[3][2]);
+    C[0] ^= E[3][0];
+    E[3][1] = B[3][1] ^ ((~B[3][2]) & B[3][3]);
+    C[1] ^= E[3][1];
+    E[3][2] = B[3][2] ^ ((~B[3][3]) & B[3][4]);
+    C[2] ^= E[3][2];
+    E[3][3] = B[3][3] ^ ((~B[3][4]) & B[3][0]);
+    C[3] ^= E[3][3];
+    E[3][4] = B[3][4] ^ ((~B[3][0]) & B[3][1]);
+    C[4] ^= E[3][4];
+    A[0][2] ^= D[2];
+    B[4][0] = (((A[0][2]) << 62) ^ ((A[0][2]) >> (64 - 62)));
+    A[1][3] ^= D[3];
+    B[4][1] = (((A[1][3]) << 55) ^ ((A[1][3]) >> (64 - 55)));
+    A[2][4] ^= D[4];
+    B[4][2] = (((A[2][4]) << 39) ^ ((A[2][4]) >> (64 - 39)));
+    A[3][0] ^= D[0];
+    B[4][3] = (((A[3][0]) << 41) ^ ((A[3][0]) >> (64 - 41)));
+    A[4][1] ^= D[1];
+    B[4][4] = (((A[4][1]) << 2) ^ ((A[4][1]) >> (64 - 2)));
+    E[4][0] = B[4][0] ^ ((~B[4][1]) & B[4][2]);
+    C[0] ^= E[4][0];
+    E[4][1] = B[4][1] ^ ((~B[4][2]) & B[4][3]);
+    C[1] ^= E[4][1];
+    E[4][2] = B[4][2] ^ ((~B[4][3]) & B[4][4]);
+    C[2] ^= E[4][2];
+    E[4][3] = B[4][3] ^ ((~B[4][4]) & B[4][0]);
+    C[3] ^= E[4][3];
+    E[4][4] = B[4][4] ^ ((~B[4][0]) & B[4][1]);
+    C[4] ^= E[4][4];
+    D[0] = C[4] ^ (((C[1]) << 1) ^ ((C[1]) >> (64 - 1)));
+    D[1] = C[0] ^ (((C[2]) << 1) ^ ((C[2]) >> (64 - 1)));
+    D[2] = C[1] ^ (((C[3]) << 1) ^ ((C[3]) >> (64 - 1)));
+    D[3] = C[2] ^ (((C[4]) << 1) ^ ((C[4]) >> (64 - 1)));
+    D[4] = C[3] ^ (((C[0]) << 1) ^ ((C[0]) >> (64 - 1)));
+    E[0][0] ^= D[0];
+    B[0][0] = E[0][0];
+    E[1][1] ^= D[1];
+    B[0][1] = (((E[1][1]) << 44) ^ ((E[1][1]) >> (64 - 44)));
+    E[2][2] ^= D[2];
+    B[0][2] = (((E[2][2]) << 43) ^ ((E[2][2]) >> (64 - 43)));
+    E[3][3] ^= D[3];
+    B[0][3] = (((E[3][3]) << 21) ^ ((E[3][3]) >> (64 - 21)));
+    E[4][4] ^= D[4];
+    B[0][4] = (((E[4][4]) << 14) ^ ((E[4][4]) >> (64 - 14)));
+    A[0][0] = B[0][0] ^ ((~B[0][1]) & B[0][2]);
+    A[0][0] ^= KECCAKF1600_ROUND_CONSTANTS[9];
+    C[0] = A[0][0];
+    A[0][1] = B[0][1] ^ ((~B[0][2]) & B[0][3]);
+    C[1] = A[0][1];
+    A[0][2] = B[0][2] ^ ((~B[0][3]) & B[0][4]);
+    C[2] = A[0][2];
+    A[0][3] = B[0][3] ^ ((~B[0][4]) & B[0][0]);
+    C[3] = A[0][3];
+    A[0][4] = B[0][4] ^ ((~B[0][0]) & B[0][1]);
+    C[4] = A[0][4];
+    E[0][3] ^= D[3];
+    B[1][0] = (((E[0][3]) << 28) ^ ((E[0][3]) >> (64 - 28)));
+    E[1][4] ^= D[4];
+    B[1][1] = (((E[1][4]) << 20) ^ ((E[1][4]) >> (64 - 20)));
+    E[2][0] ^= D[0];
+    B[1][2] = (((E[2][0]) << 3) ^ ((E[2][0]) >> (64 - 3)));
+    E[3][1] ^= D[1];
+    B[1][3] = (((E[3][1]) << 45) ^ ((E[3][1]) >> (64 - 45)));
+    E[4][2] ^= D[2];
+    B[1][4] = (((E[4][2]) << 61) ^ ((E[4][2]) >> (64 - 61)));
+    A[1][0] = B[1][0] ^ ((~B[1][1]) & B[1][2]);
+    C[0] ^= A[1][0];
+    A[1][1] = B[1][1] ^ ((~B[1][2]) & B[1][3]);
+    C[1] ^= A[1][1];
+    A[1][2] = B[1][2] ^ ((~B[1][3]) & B[1][4]);
+    C[2] ^= A[1][2];
+    A[1][3] = B[1][3] ^ ((~B[1][4]) & B[1][0]);
+    C[3] ^= A[1][3];
+    A[1][4] = B[1][4] ^ ((~B[1][0]) & B[1][1]);
+    C[4] ^= A[1][4];
+    E[0][1] ^= D[1];
+    B[2][0] = (((E[0][1]) << 1) ^ ((E[0][1]) >> (64 - 1)));
+    E[1][2] ^= D[2];
+    B[2][1] = (((E[1][2]) << 6) ^ ((E[1][2]) >> (64 - 6)));
+    E[2][3] ^= D[3];
+    B[2][2] = (((E[2][3]) << 25) ^ ((E[2][3]) >> (64 - 25)));
+    E[3][4] ^= D[4];
+    B[2][3] = (((E[3][4]) << 8) ^ ((E[3][4]) >> (64 - 8)));
+    E[4][0] ^= D[0];
+    B[2][4] = (((E[4][0]) << 18) ^ ((E[4][0]) >> (64 - 18)));
+    A[2][0] = B[2][0] ^ ((~B[2][1]) & B[2][2]);
+    C[0] ^= A[2][0];
+    A[2][1] = B[2][1] ^ ((~B[2][2]) & B[2][3]);
+    C[1] ^= A[2][1];
+    A[2][2] = B[2][2] ^ ((~B[2][3]) & B[2][4]);
+    C[2] ^= A[2][2];
+    A[2][3] = B[2][3] ^ ((~B[2][4]) & B[2][0]);
+    C[3] ^= A[2][3];
+    A[2][4] = B[2][4] ^ ((~B[2][0]) & B[2][1]);
+    C[4] ^= A[2][4];
+    E[0][4] ^= D[4];
+    B[3][0] = (((E[0][4]) << 27) ^ ((E[0][4]) >> (64 - 27)));
+    E[1][0] ^= D[0];
+    B[3][1] = (((E[1][0]) << 36) ^ ((E[1][0]) >> (64 - 36)));
+    E[2][1] ^= D[1];
+    B[3][2] = (((E[2][1]) << 10) ^ ((E[2][1]) >> (64 - 10)));
+    E[3][2] ^= D[2];
+    B[3][3] = (((E[3][2]) << 15) ^ ((E[3][2]) >> (64 - 15)));
+    E[4][3] ^= D[3];
+    B[3][4] = (((E[4][3]) << 56) ^ ((E[4][3]) >> (64 - 56)));
+    A[3][0] = B[3][0] ^ ((~B[3][1]) & B[3][2]);
+    C[0] ^= A[3][0];
+    A[3][1] = B[3][1] ^ ((~B[3][2]) & B[3][3]);
+    C[1] ^= A[3][1];
+    A[3][2] = B[3][2] ^ ((~B[3][3]) & B[3][4]);
+    C[2] ^= A[3][2];
+    A[3][3] = B[3][3] ^ ((~B[3][4]) & B[3][0]);
+    C[3] ^= A[3][3];
+    A[3][4] = B[3][4] ^ ((~B[3][0]) & B[3][1]);
+    C[4] ^= A[3][4];
+    E[0][2] ^= D[2];
+    B[4][0] = (((E[0][2]) << 62) ^ ((E[0][2]) >> (64 - 62)));
+    E[1][3] ^= D[3];
+    B[4][1] = (((E[1][3]) << 55) ^ ((E[1][3]) >> (64 - 55)));
+    E[2][4] ^= D[4];
+    B[4][2] = (((E[2][4]) << 39) ^ ((E[2][4]) >> (64 - 39)));
+    E[3][0] ^= D[0];
+    B[4][3] = (((E[3][0]) << 41) ^ ((E[3][0]) >> (64 - 41)));
+    E[4][1] ^= D[1];
+    B[4][4] = (((E[4][1]) << 2) ^ ((E[4][1]) >> (64 - 2)));
+    A[4][0] = B[4][0] ^ ((~B[4][1]) & B[4][2]);
+    C[0] ^= A[4][0];
+    A[4][1] = B[4][1] ^ ((~B[4][2]) & B[4][3]);
+    C[1] ^= A[4][1];
+    A[4][2] = B[4][2] ^ ((~B[4][3]) & B[4][4]);
+    C[2] ^= A[4][2];
+    A[4][3] = B[4][3] ^ ((~B[4][4]) & B[4][0]);
+    C[3] ^= A[4][3];
+    A[4][4] = B[4][4] ^ ((~B[4][0]) & B[4][1]);
+    C[4] ^= A[4][4];
+    D[0] = C[4] ^ (((C[1]) << 1) ^ ((C[1]) >> (64 - 1)));
+    D[1] = C[0] ^ (((C[2]) << 1) ^ ((C[2]) >> (64 - 1)));
+    D[2] = C[1] ^ (((C[3]) << 1) ^ ((C[3]) >> (64 - 1)));
+    D[3] = C[2] ^ (((C[4]) << 1) ^ ((C[4]) >> (64 - 1)));
+    D[4] = C[3] ^ (((C[0]) << 1) ^ ((C[0]) >> (64 - 1)));
+    A[0][0] ^= D[0];
+    B[0][0] = A[0][0];
+    A[1][1] ^= D[1];
+    B[0][1] = (((A[1][1]) << 44) ^ ((A[1][1]) >> (64 - 44)));
+    A[2][2] ^= D[2];
+    B[0][2] = (((A[2][2]) << 43) ^ ((A[2][2]) >> (64 - 43)));
+    A[3][3] ^= D[3];
+    B[0][3] = (((A[3][3]) << 21) ^ ((A[3][3]) >> (64 - 21)));
+    A[4][4] ^= D[4];
+    B[0][4] = (((A[4][4]) << 14) ^ ((A[4][4]) >> (64 - 14)));
+    E[0][0] = B[0][0] ^ ((~B[0][1]) & B[0][2]);
+    E[0][0] ^= KECCAKF1600_ROUND_CONSTANTS[10];
+    C[0] = E[0][0];
+    E[0][1] = B[0][1] ^ ((~B[0][2]) & B[0][3]);
+    C[1] = E[0][1];
+    E[0][2] = B[0][2] ^ ((~B[0][3]) & B[0][4]);
+    C[2] = E[0][2];
+    E[0][3] = B[0][3] ^ ((~B[0][4]) & B[0][0]);
+    C[3] = E[0][3];
+    E[0][4] = B[0][4] ^ ((~B[0][0]) & B[0][1]);
+    C[4] = E[0][4];
+    A[0][3] ^= D[3];
+    B[1][0] = (((A[0][3]) << 28) ^ ((A[0][3]) >> (64 - 28)));
+    A[1][4] ^= D[4];
+    B[1][1] = (((A[1][4]) << 20) ^ ((A[1][4]) >> (64 - 20)));
+    A[2][0] ^= D[0];
+    B[1][2] = (((A[2][0]) << 3) ^ ((A[2][0]) >> (64 - 3)));
+    A[3][1] ^= D[1];
+    B[1][3] = (((A[3][1]) << 45) ^ ((A[3][1]) >> (64 - 45)));
+    A[4][2] ^= D[2];
+    B[1][4] = (((A[4][2]) << 61) ^ ((A[4][2]) >> (64 - 61)));
+    E[1][0] = B[1][0] ^ ((~B[1][1]) & B[1][2]);
+    C[0] ^= E[1][0];
+    E[1][1] = B[1][1] ^ ((~B[1][2]) & B[1][3]);
+    C[1] ^= E[1][1];
+    E[1][2] = B[1][2] ^ ((~B[1][3]) & B[1][4]);
+    C[2] ^= E[1][2];
+    E[1][3] = B[1][3] ^ ((~B[1][4]) & B[1][0]);
+    C[3] ^= E[1][3];
+    E[1][4] = B[1][4] ^ ((~B[1][0]) & B[1][1]);
+    C[4] ^= E[1][4];
+    A[0][1] ^= D[1];
+    B[2][0] = (((A[0][1]) << 1) ^ ((A[0][1]) >> (64 - 1)));
+    A[1][2] ^= D[2];
+    B[2][1] = (((A[1][2]) << 6) ^ ((A[1][2]) >> (64 - 6)));
+    A[2][3] ^= D[3];
+    B[2][2] = (((A[2][3]) << 25) ^ ((A[2][3]) >> (64 - 25)));
+    A[3][4] ^= D[4];
+    B[2][3] = (((A[3][4]) << 8) ^ ((A[3][4]) >> (64 - 8)));
+    A[4][0] ^= D[0];
+    B[2][4] = (((A[4][0]) << 18) ^ ((A[4][0]) >> (64 - 18)));
+    E[2][0] = B[2][0] ^ ((~B[2][1]) & B[2][2]);
+    C[0] ^= E[2][0];
+    E[2][1] = B[2][1] ^ ((~B[2][2]) & B[2][3]);
+    C[1] ^= E[2][1];
+    E[2][2] = B[2][2] ^ ((~B[2][3]) & B[2][4]);
+    C[2] ^= E[2][2];
+    E[2][3] = B[2][3] ^ ((~B[2][4]) & B[2][0]);
+    C[3] ^= E[2][3];
+    E[2][4] = B[2][4] ^ ((~B[2][0]) & B[2][1]);
+    C[4] ^= E[2][4];
+    A[0][4] ^= D[4];
+    B[3][0] = (((A[0][4]) << 27) ^ ((A[0][4]) >> (64 - 27)));
+    A[1][0] ^= D[0];
+    B[3][1] = (((A[1][0]) << 36) ^ ((A[1][0]) >> (64 - 36)));
+    A[2][1] ^= D[1];
+    B[3][2] = (((A[2][1]) << 10) ^ ((A[2][1]) >> (64 - 10)));
+    A[3][2] ^= D[2];
+    B[3][3] = (((A[3][2]) << 15) ^ ((A[3][2]) >> (64 - 15)));
+    A[4][3] ^= D[3];
+    B[3][4] = (((A[4][3]) << 56) ^ ((A[4][3]) >> (64 - 56)));
+    E[3][0] = B[3][0] ^ ((~B[3][1]) & B[3][2]);
+    C[0] ^= E[3][0];
+    E[3][1] = B[3][1] ^ ((~B[3][2]) & B[3][3]);
+    C[1] ^= E[3][1];
+    E[3][2] = B[3][2] ^ ((~B[3][3]) & B[3][4]);
+    C[2] ^= E[3][2];
+    E[3][3] = B[3][3] ^ ((~B[3][4]) & B[3][0]);
+    C[3] ^= E[3][3];
+    E[3][4] = B[3][4] ^ ((~B[3][0]) & B[3][1]);
+    C[4] ^= E[3][4];
+    A[0][2] ^= D[2];
+    B[4][0] = (((A[0][2]) << 62) ^ ((A[0][2]) >> (64 - 62)));
+    A[1][3] ^= D[3];
+    B[4][1] = (((A[1][3]) << 55) ^ ((A[1][3]) >> (64 - 55)));
+    A[2][4] ^= D[4];
+    B[4][2] = (((A[2][4]) << 39) ^ ((A[2][4]) >> (64 - 39)));
+    A[3][0] ^= D[0];
+    B[4][3] = (((A[3][0]) << 41) ^ ((A[3][0]) >> (64 - 41)));
+    A[4][1] ^= D[1];
+    B[4][4] = (((A[4][1]) << 2) ^ ((A[4][1]) >> (64 - 2)));
+    E[4][0] = B[4][0] ^ ((~B[4][1]) & B[4][2]);
+    C[0] ^= E[4][0];
+    E[4][1] = B[4][1] ^ ((~B[4][2]) & B[4][3]);
+    C[1] ^= E[4][1];
+    E[4][2] = B[4][2] ^ ((~B[4][3]) & B[4][4]);
+    C[2] ^= E[4][2];
+    E[4][3] = B[4][3] ^ ((~B[4][4]) & B[4][0]);
+    C[3] ^= E[4][3];
+    E[4][4] = B[4][4] ^ ((~B[4][0]) & B[4][1]);
+    C[4] ^= E[4][4];
+    D[0] = C[4] ^ (((C[1]) << 1) ^ ((C[1]) >> (64 - 1)));
+    D[1] = C[0] ^ (((C[2]) << 1) ^ ((C[2]) >> (64 - 1)));
+    D[2] = C[1] ^ (((C[3]) << 1) ^ ((C[3]) >> (64 - 1)));
+    D[3] = C[2] ^ (((C[4]) << 1) ^ ((C[4]) >> (64 - 1)));
+    D[4] = C[3] ^ (((C[0]) << 1) ^ ((C[0]) >> (64 - 1)));
+    E[0][0] ^= D[0];
+    B[0][0] = E[0][0];
+    E[1][1] ^= D[1];
+    B[0][1] = (((E[1][1]) << 44) ^ ((E[1][1]) >> (64 - 44)));
+    E[2][2] ^= D[2];
+    B[0][2] = (((E[2][2]) << 43) ^ ((E[2][2]) >> (64 - 43)));
+    E[3][3] ^= D[3];
+    B[0][3] = (((E[3][3]) << 21) ^ ((E[3][3]) >> (64 - 21)));
+    E[4][4] ^= D[4];
+    B[0][4] = (((E[4][4]) << 14) ^ ((E[4][4]) >> (64 - 14)));
+    A[0][0] = B[0][0] ^ ((~B[0][1]) & B[0][2]);
+    A[0][0] ^= KECCAKF1600_ROUND_CONSTANTS[11];
+    C[0] = A[0][0];
+    A[0][1] = B[0][1] ^ ((~B[0][2]) & B[0][3]);
+    C[1] = A[0][1];
+    A[0][2] = B[0][2] ^ ((~B[0][3]) & B[0][4]);
+    C[2] = A[0][2];
+    A[0][3] = B[0][3] ^ ((~B[0][4]) & B[0][0]);
+    C[3] = A[0][3];
+    A[0][4] = B[0][4] ^ ((~B[0][0]) & B[0][1]);
+    C[4] = A[0][4];
+    E[0][3] ^= D[3];
+    B[1][0] = (((E[0][3]) << 28) ^ ((E[0][3]) >> (64 - 28)));
+    E[1][4] ^= D[4];
+    B[1][1] = (((E[1][4]) << 20) ^ ((E[1][4]) >> (64 - 20)));
+    E[2][0] ^= D[0];
+    B[1][2] = (((E[2][0]) << 3) ^ ((E[2][0]) >> (64 - 3)));
+    E[3][1] ^= D[1];
+    B[1][3] = (((E[3][1]) << 45) ^ ((E[3][1]) >> (64 - 45)));
+    E[4][2] ^= D[2];
+    B[1][4] = (((E[4][2]) << 61) ^ ((E[4][2]) >> (64 - 61)));
+    A[1][0] = B[1][0] ^ ((~B[1][1]) & B[1][2]);
+    C[0] ^= A[1][0];
+    A[1][1] = B[1][1] ^ ((~B[1][2]) & B[1][3]);
+    C[1] ^= A[1][1];
+    A[1][2] = B[1][2] ^ ((~B[1][3]) & B[1][4]);
+    C[2] ^= A[1][2];
+    A[1][3] = B[1][3] ^ ((~B[1][4]) & B[1][0]);
+    C[3] ^= A[1][3];
+    A[1][4] = B[1][4] ^ ((~B[1][0]) & B[1][1]);
+    C[4] ^= A[1][4];
+    E[0][1] ^= D[1];
+    B[2][0] = (((E[0][1]) << 1) ^ ((E[0][1]) >> (64 - 1)));
+    E[1][2] ^= D[2];
+    B[2][1] = (((E[1][2]) << 6) ^ ((E[1][2]) >> (64 - 6)));
+    E[2][3] ^= D[3];
+    B[2][2] = (((E[2][3]) << 25) ^ ((E[2][3]) >> (64 - 25)));
+    E[3][4] ^= D[4];
+    B[2][3] = (((E[3][4]) << 8) ^ ((E[3][4]) >> (64 - 8)));
+    E[4][0] ^= D[0];
+    B[2][4] = (((E[4][0]) << 18) ^ ((E[4][0]) >> (64 - 18)));
+    A[2][0] = B[2][0] ^ ((~B[2][1]) & B[2][2]);
+    C[0] ^= A[2][0];
+    A[2][1] = B[2][1] ^ ((~B[2][2]) & B[2][3]);
+    C[1] ^= A[2][1];
+    A[2][2] = B[2][2] ^ ((~B[2][3]) & B[2][4]);
+    C[2] ^= A[2][2];
+    A[2][3] = B[2][3] ^ ((~B[2][4]) & B[2][0]);
+    C[3] ^= A[2][3];
+    A[2][4] = B[2][4] ^ ((~B[2][0]) & B[2][1]);
+    C[4] ^= A[2][4];
+    E[0][4] ^= D[4];
+    B[3][0] = (((E[0][4]) << 27) ^ ((E[0][4]) >> (64 - 27)));
+    E[1][0] ^= D[0];
+    B[3][1] = (((E[1][0]) << 36) ^ ((E[1][0]) >> (64 - 36)));
+    E[2][1] ^= D[1];
+    B[3][2] = (((E[2][1]) << 10) ^ ((E[2][1]) >> (64 - 10)));
+    E[3][2] ^= D[2];
+    B[3][3] = (((E[3][2]) << 15) ^ ((E[3][2]) >> (64 - 15)));
+    E[4][3] ^= D[3];
+    B[3][4] = (((E[4][3]) << 56) ^ ((E[4][3]) >> (64 - 56)));
+    A[3][0] = B[3][0] ^ ((~B[3][1]) & B[3][2]);
+    C[0] ^= A[3][0];
+    A[3][1] = B[3][1] ^ ((~B[3][2]) & B[3][3]);
+    C[1] ^= A[3][1];
+    A[3][2] = B[3][2] ^ ((~B[3][3]) & B[3][4]);
+    C[2] ^= A[3][2];
+    A[3][3] = B[3][3] ^ ((~B[3][4]) & B[3][0]);
+    C[3] ^= A[3][3];
+    A[3][4] = B[3][4] ^ ((~B[3][0]) & B[3][1]);
+    C[4] ^= A[3][4];
+    E[0][2] ^= D[2];
+    B[4][0] = (((E[0][2]) << 62) ^ ((E[0][2]) >> (64 - 62)));
+    E[1][3] ^= D[3];
+    B[4][1] = (((E[1][3]) << 55) ^ ((E[1][3]) >> (64 - 55)));
+    E[2][4] ^= D[4];
+    B[4][2] = (((E[2][4]) << 39) ^ ((E[2][4]) >> (64 - 39)));
+    E[3][0] ^= D[0];
+    B[4][3] = (((E[3][0]) << 41) ^ ((E[3][0]) >> (64 - 41)));
+    E[4][1] ^= D[1];
+    B[4][4] = (((E[4][1]) << 2) ^ ((E[4][1]) >> (64 - 2)));
+    A[4][0] = B[4][0] ^ ((~B[4][1]) & B[4][2]);
+    C[0] ^= A[4][0];
+    A[4][1] = B[4][1] ^ ((~B[4][2]) & B[4][3]);
+    C[1] ^= A[4][1];
+    A[4][2] = B[4][2] ^ ((~B[4][3]) & B[4][4]);
+    C[2] ^= A[4][2];
+    A[4][3] = B[4][3] ^ ((~B[4][4]) & B[4][0]);
+    C[3] ^= A[4][3];
+    A[4][4] = B[4][4] ^ ((~B[4][0]) & B[4][1]);
+    C[4] ^= A[4][4];
+    D[0] = C[4] ^ (((C[1]) << 1) ^ ((C[1]) >> (64 - 1)));
+    D[1] = C[0] ^ (((C[2]) << 1) ^ ((C[2]) >> (64 - 1)));
+    D[2] = C[1] ^ (((C[3]) << 1) ^ ((C[3]) >> (64 - 1)));
+    D[3] = C[2] ^ (((C[4]) << 1) ^ ((C[4]) >> (64 - 1)));
+    D[4] = C[3] ^ (((C[0]) << 1) ^ ((C[0]) >> (64 - 1)));
+    A[0][0] ^= D[0];
+    B[0][0] = A[0][0];
+    A[1][1] ^= D[1];
+    B[0][1] = (((A[1][1]) << 44) ^ ((A[1][1]) >> (64 - 44)));
+    A[2][2] ^= D[2];
+    B[0][2] = (((A[2][2]) << 43) ^ ((A[2][2]) >> (64 - 43)));
+    A[3][3] ^= D[3];
+    B[0][3] = (((A[3][3]) << 21) ^ ((A[3][3]) >> (64 - 21)));
+    A[4][4] ^= D[4];
+    B[0][4] = (((A[4][4]) << 14) ^ ((A[4][4]) >> (64 - 14)));
+    E[0][0] = B[0][0] ^ ((~B[0][1]) & B[0][2]);
+    E[0][0] ^= KECCAKF1600_ROUND_CONSTANTS[12];
+    C[0] = E[0][0];
+    E[0][1] = B[0][1] ^ ((~B[0][2]) & B[0][3]);
+    C[1] = E[0][1];
+    E[0][2] = B[0][2] ^ ((~B[0][3]) & B[0][4]);
+    C[2] = E[0][2];
+    E[0][3] = B[0][3] ^ ((~B[0][4]) & B[0][0]);
+    C[3] = E[0][3];
+    E[0][4] = B[0][4] ^ ((~B[0][0]) & B[0][1]);
+    C[4] = E[0][4];
+    A[0][3] ^= D[3];
+    B[1][0] = (((A[0][3]) << 28) ^ ((A[0][3]) >> (64 - 28)));
+    A[1][4] ^= D[4];
+    B[1][1] = (((A[1][4]) << 20) ^ ((A[1][4]) >> (64 - 20)));
+    A[2][0] ^= D[0];
+    B[1][2] = (((A[2][0]) << 3) ^ ((A[2][0]) >> (64 - 3)));
+    A[3][1] ^= D[1];
+    B[1][3] = (((A[3][1]) << 45) ^ ((A[3][1]) >> (64 - 45)));
+    A[4][2] ^= D[2];
+    B[1][4] = (((A[4][2]) << 61) ^ ((A[4][2]) >> (64 - 61)));
+    E[1][0] = B[1][0] ^ ((~B[1][1]) & B[1][2]);
+    C[0] ^= E[1][0];
+    E[1][1] = B[1][1] ^ ((~B[1][2]) & B[1][3]);
+    C[1] ^= E[1][1];
+    E[1][2] = B[1][2] ^ ((~B[1][3]) & B[1][4]);
+    C[2] ^= E[1][2];
+    E[1][3] = B[1][3] ^ ((~B[1][4]) & B[1][0]);
+    C[3] ^= E[1][3];
+    E[1][4] = B[1][4] ^ ((~B[1][0]) & B[1][1]);
+    C[4] ^= E[1][4];
+    A[0][1] ^= D[1];
+    B[2][0] = (((A[0][1]) << 1) ^ ((A[0][1]) >> (64 - 1)));
+    A[1][2] ^= D[2];
+    B[2][1] = (((A[1][2]) << 6) ^ ((A[1][2]) >> (64 - 6)));
+    A[2][3] ^= D[3];
+    B[2][2] = (((A[2][3]) << 25) ^ ((A[2][3]) >> (64 - 25)));
+    A[3][4] ^= D[4];
+    B[2][3] = (((A[3][4]) << 8) ^ ((A[3][4]) >> (64 - 8)));
+    A[4][0] ^= D[0];
+    B[2][4] = (((A[4][0]) << 18) ^ ((A[4][0]) >> (64 - 18)));
+    E[2][0] = B[2][0] ^ ((~B[2][1]) & B[2][2]);
+    C[0] ^= E[2][0];
+    E[2][1] = B[2][1] ^ ((~B[2][2]) & B[2][3]);
+    C[1] ^= E[2][1];
+    E[2][2] = B[2][2] ^ ((~B[2][3]) & B[2][4]);
+    C[2] ^= E[2][2];
+    E[2][3] = B[2][3] ^ ((~B[2][4]) & B[2][0]);
+    C[3] ^= E[2][3];
+    E[2][4] = B[2][4] ^ ((~B[2][0]) & B[2][1]);
+    C[4] ^= E[2][4];
+    A[0][4] ^= D[4];
+    B[3][0] = (((A[0][4]) << 27) ^ ((A[0][4]) >> (64 - 27)));
+    A[1][0] ^= D[0];
+    B[3][1] = (((A[1][0]) << 36) ^ ((A[1][0]) >> (64 - 36)));
+    A[2][1] ^= D[1];
+    B[3][2] = (((A[2][1]) << 10) ^ ((A[2][1]) >> (64 - 10)));
+    A[3][2] ^= D[2];
+    B[3][3] = (((A[3][2]) << 15) ^ ((A[3][2]) >> (64 - 15)));
+    A[4][3] ^= D[3];
+    B[3][4] = (((A[4][3]) << 56) ^ ((A[4][3]) >> (64 - 56)));
+    E[3][0] = B[3][0] ^ ((~B[3][1]) & B[3][2]);
+    C[0] ^= E[3][0];
+    E[3][1] = B[3][1] ^ ((~B[3][2]) & B[3][3]);
+    C[1] ^= E[3][1];
+    E[3][2] = B[3][2] ^ ((~B[3][3]) & B[3][4]);
+    C[2] ^= E[3][2];
+    E[3][3] = B[3][3] ^ ((~B[3][4]) & B[3][0]);
+    C[3] ^= E[3][3];
+    E[3][4] = B[3][4] ^ ((~B[3][0]) & B[3][1]);
+    C[4] ^= E[3][4];
+    A[0][2] ^= D[2];
+    B[4][0] = (((A[0][2]) << 62) ^ ((A[0][2]) >> (64 - 62)));
+    A[1][3] ^= D[3];
+    B[4][1] = (((A[1][3]) << 55) ^ ((A[1][3]) >> (64 - 55)));
+    A[2][4] ^= D[4];
+    B[4][2] = (((A[2][4]) << 39) ^ ((A[2][4]) >> (64 - 39)));
+    A[3][0] ^= D[0];
+    B[4][3] = (((A[3][0]) << 41) ^ ((A[3][0]) >> (64 - 41)));
+    A[4][1] ^= D[1];
+    B[4][4] = (((A[4][1]) << 2) ^ ((A[4][1]) >> (64 - 2)));
+    E[4][0] = B[4][0] ^ ((~B[4][1]) & B[4][2]);
+    C[0] ^= E[4][0];
+    E[4][1] = B[4][1] ^ ((~B[4][2]) & B[4][3]);
+    C[1] ^= E[4][1];
+    E[4][2] = B[4][2] ^ ((~B[4][3]) & B[4][4]);
+    C[2] ^= E[4][2];
+    E[4][3] = B[4][3] ^ ((~B[4][4]) & B[4][0]);
+    C[3] ^= E[4][3];
+    E[4][4] = B[4][4] ^ ((~B[4][0]) & B[4][1]);
+    C[4] ^= E[4][4];
+    D[0] = C[4] ^ (((C[1]) << 1) ^ ((C[1]) >> (64 - 1)));
+    D[1] = C[0] ^ (((C[2]) << 1) ^ ((C[2]) >> (64 - 1)));
+    D[2] = C[1] ^ (((C[3]) << 1) ^ ((C[3]) >> (64 - 1)));
+    D[3] = C[2] ^ (((C[4]) << 1) ^ ((C[4]) >> (64 - 1)));
+    D[4] = C[3] ^ (((C[0]) << 1) ^ ((C[0]) >> (64 - 1)));
+    E[0][0] ^= D[0];
+    B[0][0] = E[0][0];
+    E[1][1] ^= D[1];
+    B[0][1] = (((E[1][1]) << 44) ^ ((E[1][1]) >> (64 - 44)));
+    E[2][2] ^= D[2];
+    B[0][2] = (((E[2][2]) << 43) ^ ((E[2][2]) >> (64 - 43)));
+    E[3][3] ^= D[3];
+    B[0][3] = (((E[3][3]) << 21) ^ ((E[3][3]) >> (64 - 21)));
+    E[4][4] ^= D[4];
+    B[0][4] = (((E[4][4]) << 14) ^ ((E[4][4]) >> (64 - 14)));
+    A[0][0] = B[0][0] ^ ((~B[0][1]) & B[0][2]);
+    A[0][0] ^= KECCAKF1600_ROUND_CONSTANTS[13];
+    C[0] = A[0][0];
+    A[0][1] = B[0][1] ^ ((~B[0][2]) & B[0][3]);
+    C[1] = A[0][1];
+    A[0][2] = B[0][2] ^ ((~B[0][3]) & B[0][4]);
+    C[2] = A[0][2];
+    A[0][3] = B[0][3] ^ ((~B[0][4]) & B[0][0]);
+    C[3] = A[0][3];
+    A[0][4] = B[0][4] ^ ((~B[0][0]) & B[0][1]);
+    C[4] = A[0][4];
+    E[0][3] ^= D[3];
+    B[1][0] = (((E[0][3]) << 28) ^ ((E[0][3]) >> (64 - 28)));
+    E[1][4] ^= D[4];
+    B[1][1] = (((E[1][4]) << 20) ^ ((E[1][4]) >> (64 - 20)));
+    E[2][0] ^= D[0];
+    B[1][2] = (((E[2][0]) << 3) ^ ((E[2][0]) >> (64 - 3)));
+    E[3][1] ^= D[1];
+    B[1][3] = (((E[3][1]) << 45) ^ ((E[3][1]) >> (64 - 45)));
+    E[4][2] ^= D[2];
+    B[1][4] = (((E[4][2]) << 61) ^ ((E[4][2]) >> (64 - 61)));
+    A[1][0] = B[1][0] ^ ((~B[1][1]) & B[1][2]);
+    C[0] ^= A[1][0];
+    A[1][1] = B[1][1] ^ ((~B[1][2]) & B[1][3]);
+    C[1] ^= A[1][1];
+    A[1][2] = B[1][2] ^ ((~B[1][3]) & B[1][4]);
+    C[2] ^= A[1][2];
+    A[1][3] = B[1][3] ^ ((~B[1][4]) & B[1][0]);
+    C[3] ^= A[1][3];
+    A[1][4] = B[1][4] ^ ((~B[1][0]) & B[1][1]);
+    C[4] ^= A[1][4];
+    E[0][1] ^= D[1];
+    B[2][0] = (((E[0][1]) << 1) ^ ((E[0][1]) >> (64 - 1)));
+    E[1][2] ^= D[2];
+    B[2][1] = (((E[1][2]) << 6) ^ ((E[1][2]) >> (64 - 6)));
+    E[2][3] ^= D[3];
+    B[2][2] = (((E[2][3]) << 25) ^ ((E[2][3]) >> (64 - 25)));
+    E[3][4] ^= D[4];
+    B[2][3] = (((E[3][4]) << 8) ^ ((E[3][4]) >> (64 - 8)));
+    E[4][0] ^= D[0];
+    B[2][4] = (((E[4][0]) << 18) ^ ((E[4][0]) >> (64 - 18)));
+    A[2][0] = B[2][0] ^ ((~B[2][1]) & B[2][2]);
+    C[0] ^= A[2][0];
+    A[2][1] = B[2][1] ^ ((~B[2][2]) & B[2][3]);
+    C[1] ^= A[2][1];
+    A[2][2] = B[2][2] ^ ((~B[2][3]) & B[2][4]);
+    C[2] ^= A[2][2];
+    A[2][3] = B[2][3] ^ ((~B[2][4]) & B[2][0]);
+    C[3] ^= A[2][3];
+    A[2][4] = B[2][4] ^ ((~B[2][0]) & B[2][1]);
+    C[4] ^= A[2][4];
+    E[0][4] ^= D[4];
+    B[3][0] = (((E[0][4]) << 27) ^ ((E[0][4]) >> (64 - 27)));
+    E[1][0] ^= D[0];
+    B[3][1] = (((E[1][0]) << 36) ^ ((E[1][0]) >> (64 - 36)));
+    E[2][1] ^= D[1];
+    B[3][2] = (((E[2][1]) << 10) ^ ((E[2][1]) >> (64 - 10)));
+    E[3][2] ^= D[2];
+    B[3][3] = (((E[3][2]) << 15) ^ ((E[3][2]) >> (64 - 15)));
+    E[4][3] ^= D[3];
+    B[3][4] = (((E[4][3]) << 56) ^ ((E[4][3]) >> (64 - 56)));
+    A[3][0] = B[3][0] ^ ((~B[3][1]) & B[3][2]);
+    C[0] ^= A[3][0];
+    A[3][1] = B[3][1] ^ ((~B[3][2]) & B[3][3]);
+    C[1] ^= A[3][1];
+    A[3][2] = B[3][2] ^ ((~B[3][3]) & B[3][4]);
+    C[2] ^= A[3][2];
+    A[3][3] = B[3][3] ^ ((~B[3][4]) & B[3][0]);
+    C[3] ^= A[3][3];
+    A[3][4] = B[3][4] ^ ((~B[3][0]) & B[3][1]);
+    C[4] ^= A[3][4];
+    E[0][2] ^= D[2];
+    B[4][0] = (((E[0][2]) << 62) ^ ((E[0][2]) >> (64 - 62)));
+    E[1][3] ^= D[3];
+    B[4][1] = (((E[1][3]) << 55) ^ ((E[1][3]) >> (64 - 55)));
+    E[2][4] ^= D[4];
+    B[4][2] = (((E[2][4]) << 39) ^ ((E[2][4]) >> (64 - 39)));
+    E[3][0] ^= D[0];
+    B[4][3] = (((E[3][0]) << 41) ^ ((E[3][0]) >> (64 - 41)));
+    E[4][1] ^= D[1];
+    B[4][4] = (((E[4][1]) << 2) ^ ((E[4][1]) >> (64 - 2)));
+    A[4][0] = B[4][0] ^ ((~B[4][1]) & B[4][2]);
+    C[0] ^= A[4][0];
+    A[4][1] = B[4][1] ^ ((~B[4][2]) & B[4][3]);
+    C[1] ^= A[4][1];
+    A[4][2] = B[4][2] ^ ((~B[4][3]) & B[4][4]);
+    C[2] ^= A[4][2];
+    A[4][3] = B[4][3] ^ ((~B[4][4]) & B[4][0]);
+    C[3] ^= A[4][3];
+    A[4][4] = B[4][4] ^ ((~B[4][0]) & B[4][1]);
+    C[4] ^= A[4][4];
+    D[0] = C[4] ^ (((C[1]) << 1) ^ ((C[1]) >> (64 - 1)));
+    D[1] = C[0] ^ (((C[2]) << 1) ^ ((C[2]) >> (64 - 1)));
+    D[2] = C[1] ^ (((C[3]) << 1) ^ ((C[3]) >> (64 - 1)));
+    D[3] = C[2] ^ (((C[4]) << 1) ^ ((C[4]) >> (64 - 1)));
+    D[4] = C[3] ^ (((C[0]) << 1) ^ ((C[0]) >> (64 - 1)));
+    A[0][0] ^= D[0];
+    B[0][0] = A[0][0];
+    A[1][1] ^= D[1];
+    B[0][1] = (((A[1][1]) << 44) ^ ((A[1][1]) >> (64 - 44)));
+    A[2][2] ^= D[2];
+    B[0][2] = (((A[2][2]) << 43) ^ ((A[2][2]) >> (64 - 43)));
+    A[3][3] ^= D[3];
+    B[0][3] = (((A[3][3]) << 21) ^ ((A[3][3]) >> (64 - 21)));
+    A[4][4] ^= D[4];
+    B[0][4] = (((A[4][4]) << 14) ^ ((A[4][4]) >> (64 - 14)));
+    E[0][0] = B[0][0] ^ ((~B[0][1]) & B[0][2]);
+    E[0][0] ^= KECCAKF1600_ROUND_CONSTANTS[14];
+    C[0] = E[0][0];
+    E[0][1] = B[0][1] ^ ((~B[0][2]) & B[0][3]);
+    C[1] = E[0][1];
+    E[0][2] = B[0][2] ^ ((~B[0][3]) & B[0][4]);
+    C[2] = E[0][2];
+    E[0][3] = B[0][3] ^ ((~B[0][4]) & B[0][0]);
+    C[3] = E[0][3];
+    E[0][4] = B[0][4] ^ ((~B[0][0]) & B[0][1]);
+    C[4] = E[0][4];
+    A[0][3] ^= D[3];
+    B[1][0] = (((A[0][3]) << 28) ^ ((A[0][3]) >> (64 - 28)));
+    A[1][4] ^= D[4];
+    B[1][1] = (((A[1][4]) << 20) ^ ((A[1][4]) >> (64 - 20)));
+    A[2][0] ^= D[0];
+    B[1][2] = (((A[2][0]) << 3) ^ ((A[2][0]) >> (64 - 3)));
+    A[3][1] ^= D[1];
+    B[1][3] = (((A[3][1]) << 45) ^ ((A[3][1]) >> (64 - 45)));
+    A[4][2] ^= D[2];
+    B[1][4] = (((A[4][2]) << 61) ^ ((A[4][2]) >> (64 - 61)));
+    E[1][0] = B[1][0] ^ ((~B[1][1]) & B[1][2]);
+    C[0] ^= E[1][0];
+    E[1][1] = B[1][1] ^ ((~B[1][2]) & B[1][3]);
+    C[1] ^= E[1][1];
+    E[1][2] = B[1][2] ^ ((~B[1][3]) & B[1][4]);
+    C[2] ^= E[1][2];
+    E[1][3] = B[1][3] ^ ((~B[1][4]) & B[1][0]);
+    C[3] ^= E[1][3];
+    E[1][4] = B[1][4] ^ ((~B[1][0]) & B[1][1]);
+    C[4] ^= E[1][4];
+    A[0][1] ^= D[1];
+    B[2][0] = (((A[0][1]) << 1) ^ ((A[0][1]) >> (64 - 1)));
+    A[1][2] ^= D[2];
+    B[2][1] = (((A[1][2]) << 6) ^ ((A[1][2]) >> (64 - 6)));
+    A[2][3] ^= D[3];
+    B[2][2] = (((A[2][3]) << 25) ^ ((A[2][3]) >> (64 - 25)));
+    A[3][4] ^= D[4];
+    B[2][3] = (((A[3][4]) << 8) ^ ((A[3][4]) >> (64 - 8)));
+    A[4][0] ^= D[0];
+    B[2][4] = (((A[4][0]) << 18) ^ ((A[4][0]) >> (64 - 18)));
+    E[2][0] = B[2][0] ^ ((~B[2][1]) & B[2][2]);
+    C[0] ^= E[2][0];
+    E[2][1] = B[2][1] ^ ((~B[2][2]) & B[2][3]);
+    C[1] ^= E[2][1];
+    E[2][2] = B[2][2] ^ ((~B[2][3]) & B[2][4]);
+    C[2] ^= E[2][2];
+    E[2][3] = B[2][3] ^ ((~B[2][4]) & B[2][0]);
+    C[3] ^= E[2][3];
+    E[2][4] = B[2][4] ^ ((~B[2][0]) & B[2][1]);
+    C[4] ^= E[2][4];
+    A[0][4] ^= D[4];
+    B[3][0] = (((A[0][4]) << 27) ^ ((A[0][4]) >> (64 - 27)));
+    A[1][0] ^= D[0];
+    B[3][1] = (((A[1][0]) << 36) ^ ((A[1][0]) >> (64 - 36)));
+    A[2][1] ^= D[1];
+    B[3][2] = (((A[2][1]) << 10) ^ ((A[2][1]) >> (64 - 10)));
+    A[3][2] ^= D[2];
+    B[3][3] = (((A[3][2]) << 15) ^ ((A[3][2]) >> (64 - 15)));
+    A[4][3] ^= D[3];
+    B[3][4] = (((A[4][3]) << 56) ^ ((A[4][3]) >> (64 - 56)));
+    E[3][0] = B[3][0] ^ ((~B[3][1]) & B[3][2]);
+    C[0] ^= E[3][0];
+    E[3][1] = B[3][1] ^ ((~B[3][2]) & B[3][3]);
+    C[1] ^= E[3][1];
+    E[3][2] = B[3][2] ^ ((~B[3][3]) & B[3][4]);
+    C[2] ^= E[3][2];
+    E[3][3] = B[3][3] ^ ((~B[3][4]) & B[3][0]);
+    C[3] ^= E[3][3];
+    E[3][4] = B[3][4] ^ ((~B[3][0]) & B[3][1]);
+    C[4] ^= E[3][4];
+    A[0][2] ^= D[2];
+    B[4][0] = (((A[0][2]) << 62) ^ ((A[0][2]) >> (64 - 62)));
+    A[1][3] ^= D[3];
+    B[4][1] = (((A[1][3]) << 55) ^ ((A[1][3]) >> (64 - 55)));
+    A[2][4] ^= D[4];
+    B[4][2] = (((A[2][4]) << 39) ^ ((A[2][4]) >> (64 - 39)));
+    A[3][0] ^= D[0];
+    B[4][3] = (((A[3][0]) << 41) ^ ((A[3][0]) >> (64 - 41)));
+    A[4][1] ^= D[1];
+    B[4][4] = (((A[4][1]) << 2) ^ ((A[4][1]) >> (64 - 2)));
+    E[4][0] = B[4][0] ^ ((~B[4][1]) & B[4][2]);
+    C[0] ^= E[4][0];
+    E[4][1] = B[4][1] ^ ((~B[4][2]) & B[4][3]);
+    C[1] ^= E[4][1];
+    E[4][2] = B[4][2] ^ ((~B[4][3]) & B[4][4]);
+    C[2] ^= E[4][2];
+    E[4][3] = B[4][3] ^ ((~B[4][4]) & B[4][0]);
+    C[3] ^= E[4][3];
+    E[4][4] = B[4][4] ^ ((~B[4][0]) & B[4][1]);
+    C[4] ^= E[4][4];
+    D[0] = C[4] ^ (((C[1]) << 1) ^ ((C[1]) >> (64 - 1)));
+    D[1] = C[0] ^ (((C[2]) << 1) ^ ((C[2]) >> (64 - 1)));
+    D[2] = C[1] ^ (((C[3]) << 1) ^ ((C[3]) >> (64 - 1)));
+    D[3] = C[2] ^ (((C[4]) << 1) ^ ((C[4]) >> (64 - 1)));
+    D[4] = C[3] ^ (((C[0]) << 1) ^ ((C[0]) >> (64 - 1)));
+    E[0][0] ^= D[0];
+    B[0][0] = E[0][0];
+    E[1][1] ^= D[1];
+    B[0][1] = (((E[1][1]) << 44) ^ ((E[1][1]) >> (64 - 44)));
+    E[2][2] ^= D[2];
+    B[0][2] = (((E[2][2]) << 43) ^ ((E[2][2]) >> (64 - 43)));
+    E[3][3] ^= D[3];
+    B[0][3] = (((E[3][3]) << 21) ^ ((E[3][3]) >> (64 - 21)));
+    E[4][4] ^= D[4];
+    B[0][4] = (((E[4][4]) << 14) ^ ((E[4][4]) >> (64 - 14)));
+    A[0][0] = B[0][0] ^ ((~B[0][1]) & B[0][2]);
+    A[0][0] ^= KECCAKF1600_ROUND_CONSTANTS[15];
+    C[0] = A[0][0];
+    A[0][1] = B[0][1] ^ ((~B[0][2]) & B[0][3]);
+    C[1] = A[0][1];
+    A[0][2] = B[0][2] ^ ((~B[0][3]) & B[0][4]);
+    C[2] = A[0][2];
+    A[0][3] = B[0][3] ^ ((~B[0][4]) & B[0][0]);
+    C[3] = A[0][3];
+    A[0][4] = B[0][4] ^ ((~B[0][0]) & B[0][1]);
+    C[4] = A[0][4];
+    E[0][3] ^= D[3];
+    B[1][0] = (((E[0][3]) << 28) ^ ((E[0][3]) >> (64 - 28)));
+    E[1][4] ^= D[4];
+    B[1][1] = (((E[1][4]) << 20) ^ ((E[1][4]) >> (64 - 20)));
+    E[2][0] ^= D[0];
+    B[1][2] = (((E[2][0]) << 3) ^ ((E[2][0]) >> (64 - 3)));
+    E[3][1] ^= D[1];
+    B[1][3] = (((E[3][1]) << 45) ^ ((E[3][1]) >> (64 - 45)));
+    E[4][2] ^= D[2];
+    B[1][4] = (((E[4][2]) << 61) ^ ((E[4][2]) >> (64 - 61)));
+    A[1][0] = B[1][0] ^ ((~B[1][1]) & B[1][2]);
+    C[0] ^= A[1][0];
+    A[1][1] = B[1][1] ^ ((~B[1][2]) & B[1][3]);
+    C[1] ^= A[1][1];
+    A[1][2] = B[1][2] ^ ((~B[1][3]) & B[1][4]);
+    C[2] ^= A[1][2];
+    A[1][3] = B[1][3] ^ ((~B[1][4]) & B[1][0]);
+    C[3] ^= A[1][3];
+    A[1][4] = B[1][4] ^ ((~B[1][0]) & B[1][1]);
+    C[4] ^= A[1][4];
+    E[0][1] ^= D[1];
+    B[2][0] = (((E[0][1]) << 1) ^ ((E[0][1]) >> (64 - 1)));
+    E[1][2] ^= D[2];
+    B[2][1] = (((E[1][2]) << 6) ^ ((E[1][2]) >> (64 - 6)));
+    E[2][3] ^= D[3];
+    B[2][2] = (((E[2][3]) << 25) ^ ((E[2][3]) >> (64 - 25)));
+    E[3][4] ^= D[4];
+    B[2][3] = (((E[3][4]) << 8) ^ ((E[3][4]) >> (64 - 8)));
+    E[4][0] ^= D[0];
+    B[2][4] = (((E[4][0]) << 18) ^ ((E[4][0]) >> (64 - 18)));
+    A[2][0] = B[2][0] ^ ((~B[2][1]) & B[2][2]);
+    C[0] ^= A[2][0];
+    A[2][1] = B[2][1] ^ ((~B[2][2]) & B[2][3]);
+    C[1] ^= A[2][1];
+    A[2][2] = B[2][2] ^ ((~B[2][3]) & B[2][4]);
+    C[2] ^= A[2][2];
+    A[2][3] = B[2][3] ^ ((~B[2][4]) & B[2][0]);
+    C[3] ^= A[2][3];
+    A[2][4] = B[2][4] ^ ((~B[2][0]) & B[2][1]);
+    C[4] ^= A[2][4];
+    E[0][4] ^= D[4];
+    B[3][0] = (((E[0][4]) << 27) ^ ((E[0][4]) >> (64 - 27)));
+    E[1][0] ^= D[0];
+    B[3][1] = (((E[1][0]) << 36) ^ ((E[1][0]) >> (64 - 36)));
+    E[2][1] ^= D[1];
+    B[3][2] = (((E[2][1]) << 10) ^ ((E[2][1]) >> (64 - 10)));
+    E[3][2] ^= D[2];
+    B[3][3] = (((E[3][2]) << 15) ^ ((E[3][2]) >> (64 - 15)));
+    E[4][3] ^= D[3];
+    B[3][4] = (((E[4][3]) << 56) ^ ((E[4][3]) >> (64 - 56)));
+    A[3][0] = B[3][0] ^ ((~B[3][1]) & B[3][2]);
+    C[0] ^= A[3][0];
+    A[3][1] = B[3][1] ^ ((~B[3][2]) & B[3][3]);
+    C[1] ^= A[3][1];
+    A[3][2] = B[3][2] ^ ((~B[3][3]) & B[3][4]);
+    C[2] ^= A[3][2];
+    A[3][3] = B[3][3] ^ ((~B[3][4]) & B[3][0]);
+    C[3] ^= A[3][3];
+    A[3][4] = B[3][4] ^ ((~B[3][0]) & B[3][1]);
+    C[4] ^= A[3][4];
+    E[0][2] ^= D[2];
+    B[4][0] = (((E[0][2]) << 62) ^ ((E[0][2]) >> (64 - 62)));
+    E[1][3] ^= D[3];
+    B[4][1] = (((E[1][3]) << 55) ^ ((E[1][3]) >> (64 - 55)));
+    E[2][4] ^= D[4];
+    B[4][2] = (((E[2][4]) << 39) ^ ((E[2][4]) >> (64 - 39)));
+    E[3][0] ^= D[0];
+    B[4][3] = (((E[3][0]) << 41) ^ ((E[3][0]) >> (64 - 41)));
+    E[4][1] ^= D[1];
+    B[4][4] = (((E[4][1]) << 2) ^ ((E[4][1]) >> (64 - 2)));
+    A[4][0] = B[4][0] ^ ((~B[4][1]) & B[4][2]);
+    C[0] ^= A[4][0];
+    A[4][1] = B[4][1] ^ ((~B[4][2]) & B[4][3]);
+    C[1] ^= A[4][1];
+    A[4][2] = B[4][2] ^ ((~B[4][3]) & B[4][4]);
+    C[2] ^= A[4][2];
+    A[4][3] = B[4][3] ^ ((~B[4][4]) & B[4][0]);
+    C[3] ^= A[4][3];
+    A[4][4] = B[4][4] ^ ((~B[4][0]) & B[4][1]);
+    C[4] ^= A[4][4];
+    D[0] = C[4] ^ (((C[1]) << 1) ^ ((C[1]) >> (64 - 1)));
+    D[1] = C[0] ^ (((C[2]) << 1) ^ ((C[2]) >> (64 - 1)));
+    D[2] = C[1] ^ (((C[3]) << 1) ^ ((C[3]) >> (64 - 1)));
+    D[3] = C[2] ^ (((C[4]) << 1) ^ ((C[4]) >> (64 - 1)));
+    D[4] = C[3] ^ (((C[0]) << 1) ^ ((C[0]) >> (64 - 1)));
+    A[0][0] ^= D[0];
+    B[0][0] = A[0][0];
+    A[1][1] ^= D[1];
+    B[0][1] = (((A[1][1]) << 44) ^ ((A[1][1]) >> (64 - 44)));
+    A[2][2] ^= D[2];
+    B[0][2] = (((A[2][2]) << 43) ^ ((A[2][2]) >> (64 - 43)));
+    A[3][3] ^= D[3];
+    B[0][3] = (((A[3][3]) << 21) ^ ((A[3][3]) >> (64 - 21)));
+    A[4][4] ^= D[4];
+    B[0][4] = (((A[4][4]) << 14) ^ ((A[4][4]) >> (64 - 14)));
+    E[0][0] = B[0][0] ^ ((~B[0][1]) & B[0][2]);
+    E[0][0] ^= KECCAKF1600_ROUND_CONSTANTS[16];
+    C[0] = E[0][0];
+    E[0][1] = B[0][1] ^ ((~B[0][2]) & B[0][3]);
+    C[1] = E[0][1];
+    E[0][2] = B[0][2] ^ ((~B[0][3]) & B[0][4]);
+    C[2] = E[0][2];
+    E[0][3] = B[0][3] ^ ((~B[0][4]) & B[0][0]);
+    C[3] = E[0][3];
+    E[0][4] = B[0][4] ^ ((~B[0][0]) & B[0][1]);
+    C[4] = E[0][4];
+    A[0][3] ^= D[3];
+    B[1][0] = (((A[0][3]) << 28) ^ ((A[0][3]) >> (64 - 28)));
+    A[1][4] ^= D[4];
+    B[1][1] = (((A[1][4]) << 20) ^ ((A[1][4]) >> (64 - 20)));
+    A[2][0] ^= D[0];
+    B[1][2] = (((A[2][0]) << 3) ^ ((A[2][0]) >> (64 - 3)));
+    A[3][1] ^= D[1];
+    B[1][3] = (((A[3][1]) << 45) ^ ((A[3][1]) >> (64 - 45)));
+    A[4][2] ^= D[2];
+    B[1][4] = (((A[4][2]) << 61) ^ ((A[4][2]) >> (64 - 61)));
+    E[1][0] = B[1][0] ^ ((~B[1][1]) & B[1][2]);
+    C[0] ^= E[1][0];
+    E[1][1] = B[1][1] ^ ((~B[1][2]) & B[1][3]);
+    C[1] ^= E[1][1];
+    E[1][2] = B[1][2] ^ ((~B[1][3]) & B[1][4]);
+    C[2] ^= E[1][2];
+    E[1][3] = B[1][3] ^ ((~B[1][4]) & B[1][0]);
+    C[3] ^= E[1][3];
+    E[1][4] = B[1][4] ^ ((~B[1][0]) & B[1][1]);
+    C[4] ^= E[1][4];
+    A[0][1] ^= D[1];
+    B[2][0] = (((A[0][1]) << 1) ^ ((A[0][1]) >> (64 - 1)));
+    A[1][2] ^= D[2];
+    B[2][1] = (((A[1][2]) << 6) ^ ((A[1][2]) >> (64 - 6)));
+    A[2][3] ^= D[3];
+    B[2][2] = (((A[2][3]) << 25) ^ ((A[2][3]) >> (64 - 25)));
+    A[3][4] ^= D[4];
+    B[2][3] = (((A[3][4]) << 8) ^ ((A[3][4]) >> (64 - 8)));
+    A[4][0] ^= D[0];
+    B[2][4] = (((A[4][0]) << 18) ^ ((A[4][0]) >> (64 - 18)));
+    E[2][0] = B[2][0] ^ ((~B[2][1]) & B[2][2]);
+    C[0] ^= E[2][0];
+    E[2][1] = B[2][1] ^ ((~B[2][2]) & B[2][3]);
+    C[1] ^= E[2][1];
+    E[2][2] = B[2][2] ^ ((~B[2][3]) & B[2][4]);
+    C[2] ^= E[2][2];
+    E[2][3] = B[2][3] ^ ((~B[2][4]) & B[2][0]);
+    C[3] ^= E[2][3];
+    E[2][4] = B[2][4] ^ ((~B[2][0]) & B[2][1]);
+    C[4] ^= E[2][4];
+    A[0][4] ^= D[4];
+    B[3][0] = (((A[0][4]) << 27) ^ ((A[0][4]) >> (64 - 27)));
+    A[1][0] ^= D[0];
+    B[3][1] = (((A[1][0]) << 36) ^ ((A[1][0]) >> (64 - 36)));
+    A[2][1] ^= D[1];
+    B[3][2] = (((A[2][1]) << 10) ^ ((A[2][1]) >> (64 - 10)));
+    A[3][2] ^= D[2];
+    B[3][3] = (((A[3][2]) << 15) ^ ((A[3][2]) >> (64 - 15)));
+    A[4][3] ^= D[3];
+    B[3][4] = (((A[4][3]) << 56) ^ ((A[4][3]) >> (64 - 56)));
+    E[3][0] = B[3][0] ^ ((~B[3][1]) & B[3][2]);
+    C[0] ^= E[3][0];
+    E[3][1] = B[3][1] ^ ((~B[3][2]) & B[3][3]);
+    C[1] ^= E[3][1];
+    E[3][2] = B[3][2] ^ ((~B[3][3]) & B[3][4]);
+    C[2] ^= E[3][2];
+    E[3][3] = B[3][3] ^ ((~B[3][4]) & B[3][0]);
+    C[3] ^= E[3][3];
+    E[3][4] = B[3][4] ^ ((~B[3][0]) & B[3][1]);
+    C[4] ^= E[3][4];
+    A[0][2] ^= D[2];
+    B[4][0] = (((A[0][2]) << 62) ^ ((A[0][2]) >> (64 - 62)));
+    A[1][3] ^= D[3];
+    B[4][1] = (((A[1][3]) << 55) ^ ((A[1][3]) >> (64 - 55)));
+    A[2][4] ^= D[4];
+    B[4][2] = (((A[2][4]) << 39) ^ ((A[2][4]) >> (64 - 39)));
+    A[3][0] ^= D[0];
+    B[4][3] = (((A[3][0]) << 41) ^ ((A[3][0]) >> (64 - 41)));
+    A[4][1] ^= D[1];
+    B[4][4] = (((A[4][1]) << 2) ^ ((A[4][1]) >> (64 - 2)));
+    E[4][0] = B[4][0] ^ ((~B[4][1]) & B[4][2]);
+    C[0] ^= E[4][0];
+    E[4][1] = B[4][1] ^ ((~B[4][2]) & B[4][3]);
+    C[1] ^= E[4][1];
+    E[4][2] = B[4][2] ^ ((~B[4][3]) & B[4][4]);
+    C[2] ^= E[4][2];
+    E[4][3] = B[4][3] ^ ((~B[4][4]) & B[4][0]);
+    C[3] ^= E[4][3];
+    E[4][4] = B[4][4] ^ ((~B[4][0]) & B[4][1]);
+    C[4] ^= E[4][4];
+    D[0] = C[4] ^ (((C[1]) << 1) ^ ((C[1]) >> (64 - 1)));
+    D[1] = C[0] ^ (((C[2]) << 1) ^ ((C[2]) >> (64 - 1)));
+    D[2] = C[1] ^ (((C[3]) << 1) ^ ((C[3]) >> (64 - 1)));
+    D[3] = C[2] ^ (((C[4]) << 1) ^ ((C[4]) >> (64 - 1)));
+    D[4] = C[3] ^ (((C[0]) << 1) ^ ((C[0]) >> (64 - 1)));
+    E[0][0] ^= D[0];
+    B[0][0] = E[0][0];
+    E[1][1] ^= D[1];
+    B[0][1] = (((E[1][1]) << 44) ^ ((E[1][1]) >> (64 - 44)));
+    E[2][2] ^= D[2];
+    B[0][2] = (((E[2][2]) << 43) ^ ((E[2][2]) >> (64 - 43)));
+    E[3][3] ^= D[3];
+    B[0][3] = (((E[3][3]) << 21) ^ ((E[3][3]) >> (64 - 21)));
+    E[4][4] ^= D[4];
+    B[0][4] = (((E[4][4]) << 14) ^ ((E[4][4]) >> (64 - 14)));
+    A[0][0] = B[0][0] ^ ((~B[0][1]) & B[0][2]);
+    A[0][0] ^= KECCAKF1600_ROUND_CONSTANTS[17];
+    C[0] = A[0][0];
+    A[0][1] = B[0][1] ^ ((~B[0][2]) & B[0][3]);
+    C[1] = A[0][1];
+    A[0][2] = B[0][2] ^ ((~B[0][3]) & B[0][4]);
+    C[2] = A[0][2];
+    A[0][3] = B[0][3] ^ ((~B[0][4]) & B[0][0]);
+    C[3] = A[0][3];
+    A[0][4] = B[0][4] ^ ((~B[0][0]) & B[0][1]);
+    C[4] = A[0][4];
+    E[0][3] ^= D[3];
+    B[1][0] = (((E[0][3]) << 28) ^ ((E[0][3]) >> (64 - 28)));
+    E[1][4] ^= D[4];
+    B[1][1] = (((E[1][4]) << 20) ^ ((E[1][4]) >> (64 - 20)));
+    E[2][0] ^= D[0];
+    B[1][2] = (((E[2][0]) << 3) ^ ((E[2][0]) >> (64 - 3)));
+    E[3][1] ^= D[1];
+    B[1][3] = (((E[3][1]) << 45) ^ ((E[3][1]) >> (64 - 45)));
+    E[4][2] ^= D[2];
+    B[1][4] = (((E[4][2]) << 61) ^ ((E[4][2]) >> (64 - 61)));
+    A[1][0] = B[1][0] ^ ((~B[1][1]) & B[1][2]);
+    C[0] ^= A[1][0];
+    A[1][1] = B[1][1] ^ ((~B[1][2]) & B[1][3]);
+    C[1] ^= A[1][1];
+    A[1][2] = B[1][2] ^ ((~B[1][3]) & B[1][4]);
+    C[2] ^= A[1][2];
+    A[1][3] = B[1][3] ^ ((~B[1][4]) & B[1][0]);
+    C[3] ^= A[1][3];
+    A[1][4] = B[1][4] ^ ((~B[1][0]) & B[1][1]);
+    C[4] ^= A[1][4];
+    E[0][1] ^= D[1];
+    B[2][0] = (((E[0][1]) << 1) ^ ((E[0][1]) >> (64 - 1)));
+    E[1][2] ^= D[2];
+    B[2][1] = (((E[1][2]) << 6) ^ ((E[1][2]) >> (64 - 6)));
+    E[2][3] ^= D[3];
+    B[2][2] = (((E[2][3]) << 25) ^ ((E[2][3]) >> (64 - 25)));
+    E[3][4] ^= D[4];
+    B[2][3] = (((E[3][4]) << 8) ^ ((E[3][4]) >> (64 - 8)));
+    E[4][0] ^= D[0];
+    B[2][4] = (((E[4][0]) << 18) ^ ((E[4][0]) >> (64 - 18)));
+    A[2][0] = B[2][0] ^ ((~B[2][1]) & B[2][2]);
+    C[0] ^= A[2][0];
+    A[2][1] = B[2][1] ^ ((~B[2][2]) & B[2][3]);
+    C[1] ^= A[2][1];
+    A[2][2] = B[2][2] ^ ((~B[2][3]) & B[2][4]);
+    C[2] ^= A[2][2];
+    A[2][3] = B[2][3] ^ ((~B[2][4]) & B[2][0]);
+    C[3] ^= A[2][3];
+    A[2][4] = B[2][4] ^ ((~B[2][0]) & B[2][1]);
+    C[4] ^= A[2][4];
+    E[0][4] ^= D[4];
+    B[3][0] = (((E[0][4]) << 27) ^ ((E[0][4]) >> (64 - 27)));
+    E[1][0] ^= D[0];
+    B[3][1] = (((E[1][0]) << 36) ^ ((E[1][0]) >> (64 - 36)));
+    E[2][1] ^= D[1];
+    B[3][2] = (((E[2][1]) << 10) ^ ((E[2][1]) >> (64 - 10)));
+    E[3][2] ^= D[2];
+    B[3][3] = (((E[3][2]) << 15) ^ ((E[3][2]) >> (64 - 15)));
+    E[4][3] ^= D[3];
+    B[3][4] = (((E[4][3]) << 56) ^ ((E[4][3]) >> (64 - 56)));
+    A[3][0] = B[3][0] ^ ((~B[3][1]) & B[3][2]);
+    C[0] ^= A[3][0];
+    A[3][1] = B[3][1] ^ ((~B[3][2]) & B[3][3]);
+    C[1] ^= A[3][1];
+    A[3][2] = B[3][2] ^ ((~B[3][3]) & B[3][4]);
+    C[2] ^= A[3][2];
+    A[3][3] = B[3][3] ^ ((~B[3][4]) & B[3][0]);
+    C[3] ^= A[3][3];
+    A[3][4] = B[3][4] ^ ((~B[3][0]) & B[3][1]);
+    C[4] ^= A[3][4];
+    E[0][2] ^= D[2];
+    B[4][0] = (((E[0][2]) << 62) ^ ((E[0][2]) >> (64 - 62)));
+    E[1][3] ^= D[3];
+    B[4][1] = (((E[1][3]) << 55) ^ ((E[1][3]) >> (64 - 55)));
+    E[2][4] ^= D[4];
+    B[4][2] = (((E[2][4]) << 39) ^ ((E[2][4]) >> (64 - 39)));
+    E[3][0] ^= D[0];
+    B[4][3] = (((E[3][0]) << 41) ^ ((E[3][0]) >> (64 - 41)));
+    E[4][1] ^= D[1];
+    B[4][4] = (((E[4][1]) << 2) ^ ((E[4][1]) >> (64 - 2)));
+    A[4][0] = B[4][0] ^ ((~B[4][1]) & B[4][2]);
+    C[0] ^= A[4][0];
+    A[4][1] = B[4][1] ^ ((~B[4][2]) & B[4][3]);
+    C[1] ^= A[4][1];
+    A[4][2] = B[4][2] ^ ((~B[4][3]) & B[4][4]);
+    C[2] ^= A[4][2];
+    A[4][3] = B[4][3] ^ ((~B[4][4]) & B[4][0]);
+    C[3] ^= A[4][3];
+    A[4][4] = B[4][4] ^ ((~B[4][0]) & B[4][1]);
+    C[4] ^= A[4][4];
+    D[0] = C[4] ^ (((C[1]) << 1) ^ ((C[1]) >> (64 - 1)));
+    D[1] = C[0] ^ (((C[2]) << 1) ^ ((C[2]) >> (64 - 1)));
+    D[2] = C[1] ^ (((C[3]) << 1) ^ ((C[3]) >> (64 - 1)));
+    D[3] = C[2] ^ (((C[4]) << 1) ^ ((C[4]) >> (64 - 1)));
+    D[4] = C[3] ^ (((C[0]) << 1) ^ ((C[0]) >> (64 - 1)));
+    A[0][0] ^= D[0];
+    B[0][0] = A[0][0];
+    A[1][1] ^= D[1];
+    B[0][1] = (((A[1][1]) << 44) ^ ((A[1][1]) >> (64 - 44)));
+    A[2][2] ^= D[2];
+    B[0][2] = (((A[2][2]) << 43) ^ ((A[2][2]) >> (64 - 43)));
+    A[3][3] ^= D[3];
+    B[0][3] = (((A[3][3]) << 21) ^ ((A[3][3]) >> (64 - 21)));
+    A[4][4] ^= D[4];
+    B[0][4] = (((A[4][4]) << 14) ^ ((A[4][4]) >> (64 - 14)));
+    E[0][0] = B[0][0] ^ ((~B[0][1]) & B[0][2]);
+    E[0][0] ^= KECCAKF1600_ROUND_CONSTANTS[18];
+    C[0] = E[0][0];
+    E[0][1] = B[0][1] ^ ((~B[0][2]) & B[0][3]);
+    C[1] = E[0][1];
+    E[0][2] = B[0][2] ^ ((~B[0][3]) & B[0][4]);
+    C[2] = E[0][2];
+    E[0][3] = B[0][3] ^ ((~B[0][4]) & B[0][0]);
+    C[3] = E[0][3];
+    E[0][4] = B[0][4] ^ ((~B[0][0]) & B[0][1]);
+    C[4] = E[0][4];
+    A[0][3] ^= D[3];
+    B[1][0] = (((A[0][3]) << 28) ^ ((A[0][3]) >> (64 - 28)));
+    A[1][4] ^= D[4];
+    B[1][1] = (((A[1][4]) << 20) ^ ((A[1][4]) >> (64 - 20)));
+    A[2][0] ^= D[0];
+    B[1][2] = (((A[2][0]) << 3) ^ ((A[2][0]) >> (64 - 3)));
+    A[3][1] ^= D[1];
+    B[1][3] = (((A[3][1]) << 45) ^ ((A[3][1]) >> (64 - 45)));
+    A[4][2] ^= D[2];
+    B[1][4] = (((A[4][2]) << 61) ^ ((A[4][2]) >> (64 - 61)));
+    E[1][0] = B[1][0] ^ ((~B[1][1]) & B[1][2]);
+    C[0] ^= E[1][0];
+    E[1][1] = B[1][1] ^ ((~B[1][2]) & B[1][3]);
+    C[1] ^= E[1][1];
+    E[1][2] = B[1][2] ^ ((~B[1][3]) & B[1][4]);
+    C[2] ^= E[1][2];
+    E[1][3] = B[1][3] ^ ((~B[1][4]) & B[1][0]);
+    C[3] ^= E[1][3];
+    E[1][4] = B[1][4] ^ ((~B[1][0]) & B[1][1]);
+    C[4] ^= E[1][4];
+    A[0][1] ^= D[1];
+    B[2][0] = (((A[0][1]) << 1) ^ ((A[0][1]) >> (64 - 1)));
+    A[1][2] ^= D[2];
+    B[2][1] = (((A[1][2]) << 6) ^ ((A[1][2]) >> (64 - 6)));
+    A[2][3] ^= D[3];
+    B[2][2] = (((A[2][3]) << 25) ^ ((A[2][3]) >> (64 - 25)));
+    A[3][4] ^= D[4];
+    B[2][3] = (((A[3][4]) << 8) ^ ((A[3][4]) >> (64 - 8)));
+    A[4][0] ^= D[0];
+    B[2][4] = (((A[4][0]) << 18) ^ ((A[4][0]) >> (64 - 18)));
+    E[2][0] = B[2][0] ^ ((~B[2][1]) & B[2][2]);
+    C[0] ^= E[2][0];
+    E[2][1] = B[2][1] ^ ((~B[2][2]) & B[2][3]);
+    C[1] ^= E[2][1];
+    E[2][2] = B[2][2] ^ ((~B[2][3]) & B[2][4]);
+    C[2] ^= E[2][2];
+    E[2][3] = B[2][3] ^ ((~B[2][4]) & B[2][0]);
+    C[3] ^= E[2][3];
+    E[2][4] = B[2][4] ^ ((~B[2][0]) & B[2][1]);
+    C[4] ^= E[2][4];
+    A[0][4] ^= D[4];
+    B[3][0] = (((A[0][4]) << 27) ^ ((A[0][4]) >> (64 - 27)));
+    A[1][0] ^= D[0];
+    B[3][1] = (((A[1][0]) << 36) ^ ((A[1][0]) >> (64 - 36)));
+    A[2][1] ^= D[1];
+    B[3][2] = (((A[2][1]) << 10) ^ ((A[2][1]) >> (64 - 10)));
+    A[3][2] ^= D[2];
+    B[3][3] = (((A[3][2]) << 15) ^ ((A[3][2]) >> (64 - 15)));
+    A[4][3] ^= D[3];
+    B[3][4] = (((A[4][3]) << 56) ^ ((A[4][3]) >> (64 - 56)));
+    E[3][0] = B[3][0] ^ ((~B[3][1]) & B[3][2]);
+    C[0] ^= E[3][0];
+    E[3][1] = B[3][1] ^ ((~B[3][2]) & B[3][3]);
+    C[1] ^= E[3][1];
+    E[3][2] = B[3][2] ^ ((~B[3][3]) & B[3][4]);
+    C[2] ^= E[3][2];
+    E[3][3] = B[3][3] ^ ((~B[3][4]) & B[3][0]);
+    C[3] ^= E[3][3];
+    E[3][4] = B[3][4] ^ ((~B[3][0]) & B[3][1]);
+    C[4] ^= E[3][4];
+    A[0][2] ^= D[2];
+    B[4][0] = (((A[0][2]) << 62) ^ ((A[0][2]) >> (64 - 62)));
+    A[1][3] ^= D[3];
+    B[4][1] = (((A[1][3]) << 55) ^ ((A[1][3]) >> (64 - 55)));
+    A[2][4] ^= D[4];
+    B[4][2] = (((A[2][4]) << 39) ^ ((A[2][4]) >> (64 - 39)));
+    A[3][0] ^= D[0];
+    B[4][3] = (((A[3][0]) << 41) ^ ((A[3][0]) >> (64 - 41)));
+    A[4][1] ^= D[1];
+    B[4][4] = (((A[4][1]) << 2) ^ ((A[4][1]) >> (64 - 2)));
+    E[4][0] = B[4][0] ^ ((~B[4][1]) & B[4][2]);
+    C[0] ^= E[4][0];
+    E[4][1] = B[4][1] ^ ((~B[4][2]) & B[4][3]);
+    C[1] ^= E[4][1];
+    E[4][2] = B[4][2] ^ ((~B[4][3]) & B[4][4]);
+    C[2] ^= E[4][2];
+    E[4][3] = B[4][3] ^ ((~B[4][4]) & B[4][0]);
+    C[3] ^= E[4][3];
+    E[4][4] = B[4][4] ^ ((~B[4][0]) & B[4][1]);
+    C[4] ^= E[4][4];
+    D[0] = C[4] ^ (((C[1]) << 1) ^ ((C[1]) >> (64 - 1)));
+    D[1] = C[0] ^ (((C[2]) << 1) ^ ((C[2]) >> (64 - 1)));
+    D[2] = C[1] ^ (((C[3]) << 1) ^ ((C[3]) >> (64 - 1)));
+    D[3] = C[2] ^ (((C[4]) << 1) ^ ((C[4]) >> (64 - 1)));
+    D[4] = C[3] ^ (((C[0]) << 1) ^ ((C[0]) >> (64 - 1)));
+    E[0][0] ^= D[0];
+    B[0][0] = E[0][0];
+    E[1][1] ^= D[1];
+    B[0][1] = (((E[1][1]) << 44) ^ ((E[1][1]) >> (64 - 44)));
+    E[2][2] ^= D[2];
+    B[0][2] = (((E[2][2]) << 43) ^ ((E[2][2]) >> (64 - 43)));
+    E[3][3] ^= D[3];
+    B[0][3] = (((E[3][3]) << 21) ^ ((E[3][3]) >> (64 - 21)));
+    E[4][4] ^= D[4];
+    B[0][4] = (((E[4][4]) << 14) ^ ((E[4][4]) >> (64 - 14)));
+    A[0][0] = B[0][0] ^ ((~B[0][1]) & B[0][2]);
+    A[0][0] ^= KECCAKF1600_ROUND_CONSTANTS[19];
+    C[0] = A[0][0];
+    A[0][1] = B[0][1] ^ ((~B[0][2]) & B[0][3]);
+    C[1] = A[0][1];
+    A[0][2] = B[0][2] ^ ((~B[0][3]) & B[0][4]);
+    C[2] = A[0][2];
+    A[0][3] = B[0][3] ^ ((~B[0][4]) & B[0][0]);
+    C[3] = A[0][3];
+    A[0][4] = B[0][4] ^ ((~B[0][0]) & B[0][1]);
+    C[4] = A[0][4];
+    E[0][3] ^= D[3];
+    B[1][0] = (((E[0][3]) << 28) ^ ((E[0][3]) >> (64 - 28)));
+    E[1][4] ^= D[4];
+    B[1][1] = (((E[1][4]) << 20) ^ ((E[1][4]) >> (64 - 20)));
+    E[2][0] ^= D[0];
+    B[1][2] = (((E[2][0]) << 3) ^ ((E[2][0]) >> (64 - 3)));
+    E[3][1] ^= D[1];
+    B[1][3] = (((E[3][1]) << 45) ^ ((E[3][1]) >> (64 - 45)));
+    E[4][2] ^= D[2];
+    B[1][4] = (((E[4][2]) << 61) ^ ((E[4][2]) >> (64 - 61)));
+    A[1][0] = B[1][0] ^ ((~B[1][1]) & B[1][2]);
+    C[0] ^= A[1][0];
+    A[1][1] = B[1][1] ^ ((~B[1][2]) & B[1][3]);
+    C[1] ^= A[1][1];
+    A[1][2] = B[1][2] ^ ((~B[1][3]) & B[1][4]);
+    C[2] ^= A[1][2];
+    A[1][3] = B[1][3] ^ ((~B[1][4]) & B[1][0]);
+    C[3] ^= A[1][3];
+    A[1][4] = B[1][4] ^ ((~B[1][0]) & B[1][1]);
+    C[4] ^= A[1][4];
+    E[0][1] ^= D[1];
+    B[2][0] = (((E[0][1]) << 1) ^ ((E[0][1]) >> (64 - 1)));
+    E[1][2] ^= D[2];
+    B[2][1] = (((E[1][2]) << 6) ^ ((E[1][2]) >> (64 - 6)));
+    E[2][3] ^= D[3];
+    B[2][2] = (((E[2][3]) << 25) ^ ((E[2][3]) >> (64 - 25)));
+    E[3][4] ^= D[4];
+    B[2][3] = (((E[3][4]) << 8) ^ ((E[3][4]) >> (64 - 8)));
+    E[4][0] ^= D[0];
+    B[2][4] = (((E[4][0]) << 18) ^ ((E[4][0]) >> (64 - 18)));
+    A[2][0] = B[2][0] ^ ((~B[2][1]) & B[2][2]);
+    C[0] ^= A[2][0];
+    A[2][1] = B[2][1] ^ ((~B[2][2]) & B[2][3]);
+    C[1] ^= A[2][1];
+    A[2][2] = B[2][2] ^ ((~B[2][3]) & B[2][4]);
+    C[2] ^= A[2][2];
+    A[2][3] = B[2][3] ^ ((~B[2][4]) & B[2][0]);
+    C[3] ^= A[2][3];
+    A[2][4] = B[2][4] ^ ((~B[2][0]) & B[2][1]);
+    C[4] ^= A[2][4];
+    E[0][4] ^= D[4];
+    B[3][0] = (((E[0][4]) << 27) ^ ((E[0][4]) >> (64 - 27)));
+    E[1][0] ^= D[0];
+    B[3][1] = (((E[1][0]) << 36) ^ ((E[1][0]) >> (64 - 36)));
+    E[2][1] ^= D[1];
+    B[3][2] = (((E[2][1]) << 10) ^ ((E[2][1]) >> (64 - 10)));
+    E[3][2] ^= D[2];
+    B[3][3] = (((E[3][2]) << 15) ^ ((E[3][2]) >> (64 - 15)));
+    E[4][3] ^= D[3];
+    B[3][4] = (((E[4][3]) << 56) ^ ((E[4][3]) >> (64 - 56)));
+    A[3][0] = B[3][0] ^ ((~B[3][1]) & B[3][2]);
+    C[0] ^= A[3][0];
+    A[3][1] = B[3][1] ^ ((~B[3][2]) & B[3][3]);
+    C[1] ^= A[3][1];
+    A[3][2] = B[3][2] ^ ((~B[3][3]) & B[3][4]);
+    C[2] ^= A[3][2];
+    A[3][3] = B[3][3] ^ ((~B[3][4]) & B[3][0]);
+    C[3] ^= A[3][3];
+    A[3][4] = B[3][4] ^ ((~B[3][0]) & B[3][1]);
+    C[4] ^= A[3][4];
+    E[0][2] ^= D[2];
+    B[4][0] = (((E[0][2]) << 62) ^ ((E[0][2]) >> (64 - 62)));
+    E[1][3] ^= D[3];
+    B[4][1] = (((E[1][3]) << 55) ^ ((E[1][3]) >> (64 - 55)));
+    E[2][4] ^= D[4];
+    B[4][2] = (((E[2][4]) << 39) ^ ((E[2][4]) >> (64 - 39)));
+    E[3][0] ^= D[0];
+    B[4][3] = (((E[3][0]) << 41) ^ ((E[3][0]) >> (64 - 41)));
+    E[4][1] ^= D[1];
+    B[4][4] = (((E[4][1]) << 2) ^ ((E[4][1]) >> (64 - 2)));
+    A[4][0] = B[4][0] ^ ((~B[4][1]) & B[4][2]);
+    C[0] ^= A[4][0];
+    A[4][1] = B[4][1] ^ ((~B[4][2]) & B[4][3]);
+    C[1] ^= A[4][1];
+    A[4][2] = B[4][2] ^ ((~B[4][3]) & B[4][4]);
+    C[2] ^= A[4][2];
+    A[4][3] = B[4][3] ^ ((~B[4][4]) & B[4][0]);
+    C[3] ^= A[4][3];
+    A[4][4] = B[4][4] ^ ((~B[4][0]) & B[4][1]);
+    C[4] ^= A[4][4];
+    D[0] = C[4] ^ (((C[1]) << 1) ^ ((C[1]) >> (64 - 1)));
+    D[1] = C[0] ^ (((C[2]) << 1) ^ ((C[2]) >> (64 - 1)));
+    D[2] = C[1] ^ (((C[3]) << 1) ^ ((C[3]) >> (64 - 1)));
+    D[3] = C[2] ^ (((C[4]) << 1) ^ ((C[4]) >> (64 - 1)));
+    D[4] = C[3] ^ (((C[0]) << 1) ^ ((C[0]) >> (64 - 1)));
+    A[0][0] ^= D[0];
+    B[0][0] = A[0][0];
+    A[1][1] ^= D[1];
+    B[0][1] = (((A[1][1]) << 44) ^ ((A[1][1]) >> (64 - 44)));
+    A[2][2] ^= D[2];
+    B[0][2] = (((A[2][2]) << 43) ^ ((A[2][2]) >> (64 - 43)));
+    A[3][3] ^= D[3];
+    B[0][3] = (((A[3][3]) << 21) ^ ((A[3][3]) >> (64 - 21)));
+    A[4][4] ^= D[4];
+    B[0][4] = (((A[4][4]) << 14) ^ ((A[4][4]) >> (64 - 14)));
+    E[0][0] = B[0][0] ^ ((~B[0][1]) & B[0][2]);
+    E[0][0] ^= KECCAKF1600_ROUND_CONSTANTS[20];
+    C[0] = E[0][0];
+    E[0][1] = B[0][1] ^ ((~B[0][2]) & B[0][3]);
+    C[1] = E[0][1];
+    E[0][2] = B[0][2] ^ ((~B[0][3]) & B[0][4]);
+    C[2] = E[0][2];
+    E[0][3] = B[0][3] ^ ((~B[0][4]) & B[0][0]);
+    C[3] = E[0][3];
+    E[0][4] = B[0][4] ^ ((~B[0][0]) & B[0][1]);
+    C[4] = E[0][4];
+    A[0][3] ^= D[3];
+    B[1][0] = (((A[0][3]) << 28) ^ ((A[0][3]) >> (64 - 28)));
+    A[1][4] ^= D[4];
+    B[1][1] = (((A[1][4]) << 20) ^ ((A[1][4]) >> (64 - 20)));
+    A[2][0] ^= D[0];
+    B[1][2] = (((A[2][0]) << 3) ^ ((A[2][0]) >> (64 - 3)));
+    A[3][1] ^= D[1];
+    B[1][3] = (((A[3][1]) << 45) ^ ((A[3][1]) >> (64 - 45)));
+    A[4][2] ^= D[2];
+    B[1][4] = (((A[4][2]) << 61) ^ ((A[4][2]) >> (64 - 61)));
+    E[1][0] = B[1][0] ^ ((~B[1][1]) & B[1][2]);
+    C[0] ^= E[1][0];
+    E[1][1] = B[1][1] ^ ((~B[1][2]) & B[1][3]);
+    C[1] ^= E[1][1];
+    E[1][2] = B[1][2] ^ ((~B[1][3]) & B[1][4]);
+    C[2] ^= E[1][2];
+    E[1][3] = B[1][3] ^ ((~B[1][4]) & B[1][0]);
+    C[3] ^= E[1][3];
+    E[1][4] = B[1][4] ^ ((~B[1][0]) & B[1][1]);
+    C[4] ^= E[1][4];
+    A[0][1] ^= D[1];
+    B[2][0] = (((A[0][1]) << 1) ^ ((A[0][1]) >> (64 - 1)));
+    A[1][2] ^= D[2];
+    B[2][1] = (((A[1][2]) << 6) ^ ((A[1][2]) >> (64 - 6)));
+    A[2][3] ^= D[3];
+    B[2][2] = (((A[2][3]) << 25) ^ ((A[2][3]) >> (64 - 25)));
+    A[3][4] ^= D[4];
+    B[2][3] = (((A[3][4]) << 8) ^ ((A[3][4]) >> (64 - 8)));
+    A[4][0] ^= D[0];
+    B[2][4] = (((A[4][0]) << 18) ^ ((A[4][0]) >> (64 - 18)));
+    E[2][0] = B[2][0] ^ ((~B[2][1]) & B[2][2]);
+    C[0] ^= E[2][0];
+    E[2][1] = B[2][1] ^ ((~B[2][2]) & B[2][3]);
+    C[1] ^= E[2][1];
+    E[2][2] = B[2][2] ^ ((~B[2][3]) & B[2][4]);
+    C[2] ^= E[2][2];
+    E[2][3] = B[2][3] ^ ((~B[2][4]) & B[2][0]);
+    C[3] ^= E[2][3];
+    E[2][4] = B[2][4] ^ ((~B[2][0]) & B[2][1]);
+    C[4] ^= E[2][4];
+    A[0][4] ^= D[4];
+    B[3][0] = (((A[0][4]) << 27) ^ ((A[0][4]) >> (64 - 27)));
+    A[1][0] ^= D[0];
+    B[3][1] = (((A[1][0]) << 36) ^ ((A[1][0]) >> (64 - 36)));
+    A[2][1] ^= D[1];
+    B[3][2] = (((A[2][1]) << 10) ^ ((A[2][1]) >> (64 - 10)));
+    A[3][2] ^= D[2];
+    B[3][3] = (((A[3][2]) << 15) ^ ((A[3][2]) >> (64 - 15)));
+    A[4][3] ^= D[3];
+    B[3][4] = (((A[4][3]) << 56) ^ ((A[4][3]) >> (64 - 56)));
+    E[3][0] = B[3][0] ^ ((~B[3][1]) & B[3][2]);
+    C[0] ^= E[3][0];
+    E[3][1] = B[3][1] ^ ((~B[3][2]) & B[3][3]);
+    C[1] ^= E[3][1];
+    E[3][2] = B[3][2] ^ ((~B[3][3]) & B[3][4]);
+    C[2] ^= E[3][2];
+    E[3][3] = B[3][3] ^ ((~B[3][4]) & B[3][0]);
+    C[3] ^= E[3][3];
+    E[3][4] = B[3][4] ^ ((~B[3][0]) & B[3][1]);
+    C[4] ^= E[3][4];
+    A[0][2] ^= D[2];
+    B[4][0] = (((A[0][2]) << 62) ^ ((A[0][2]) >> (64 - 62)));
+    A[1][3] ^= D[3];
+    B[4][1] = (((A[1][3]) << 55) ^ ((A[1][3]) >> (64 - 55)));
+    A[2][4] ^= D[4];
+    B[4][2] = (((A[2][4]) << 39) ^ ((A[2][4]) >> (64 - 39)));
+    A[3][0] ^= D[0];
+    B[4][3] = (((A[3][0]) << 41) ^ ((A[3][0]) >> (64 - 41)));
+    A[4][1] ^= D[1];
+    B[4][4] = (((A[4][1]) << 2) ^ ((A[4][1]) >> (64 - 2)));
+    E[4][0] = B[4][0] ^ ((~B[4][1]) & B[4][2]);
+    C[0] ^= E[4][0];
+    E[4][1] = B[4][1] ^ ((~B[4][2]) & B[4][3]);
+    C[1] ^= E[4][1];
+    E[4][2] = B[4][2] ^ ((~B[4][3]) & B[4][4]);
+    C[2] ^= E[4][2];
+    E[4][3] = B[4][3] ^ ((~B[4][4]) & B[4][0]);
+    C[3] ^= E[4][3];
+    E[4][4] = B[4][4] ^ ((~B[4][0]) & B[4][1]);
+    C[4] ^= E[4][4];
+    D[0] = C[4] ^ (((C[1]) << 1) ^ ((C[1]) >> (64 - 1)));
+    D[1] = C[0] ^ (((C[2]) << 1) ^ ((C[2]) >> (64 - 1)));
+    D[2] = C[1] ^ (((C[3]) << 1) ^ ((C[3]) >> (64 - 1)));
+    D[3] = C[2] ^ (((C[4]) << 1) ^ ((C[4]) >> (64 - 1)));
+    D[4] = C[3] ^ (((C[0]) << 1) ^ ((C[0]) >> (64 - 1)));
+    E[0][0] ^= D[0];
+    B[0][0] = E[0][0];
+    E[1][1] ^= D[1];
+    B[0][1] = (((E[1][1]) << 44) ^ ((E[1][1]) >> (64 - 44)));
+    E[2][2] ^= D[2];
+    B[0][2] = (((E[2][2]) << 43) ^ ((E[2][2]) >> (64 - 43)));
+    E[3][3] ^= D[3];
+    B[0][3] = (((E[3][3]) << 21) ^ ((E[3][3]) >> (64 - 21)));
+    E[4][4] ^= D[4];
+    B[0][4] = (((E[4][4]) << 14) ^ ((E[4][4]) >> (64 - 14)));
+    A[0][0] = B[0][0] ^ ((~B[0][1]) & B[0][2]);
+    A[0][0] ^= KECCAKF1600_ROUND_CONSTANTS[21];
+    C[0] = A[0][0];
+    A[0][1] = B[0][1] ^ ((~B[0][2]) & B[0][3]);
+    C[1] = A[0][1];
+    A[0][2] = B[0][2] ^ ((~B[0][3]) & B[0][4]);
+    C[2] = A[0][2];
+    A[0][3] = B[0][3] ^ ((~B[0][4]) & B[0][0]);
+    C[3] = A[0][3];
+    A[0][4] = B[0][4] ^ ((~B[0][0]) & B[0][1]);
+    C[4] = A[0][4];
+    E[0][3] ^= D[3];
+    B[1][0] = (((E[0][3]) << 28) ^ ((E[0][3]) >> (64 - 28)));
+    E[1][4] ^= D[4];
+    B[1][1] = (((E[1][4]) << 20) ^ ((E[1][4]) >> (64 - 20)));
+    E[2][0] ^= D[0];
+    B[1][2] = (((E[2][0]) << 3) ^ ((E[2][0]) >> (64 - 3)));
+    E[3][1] ^= D[1];
+    B[1][3] = (((E[3][1]) << 45) ^ ((E[3][1]) >> (64 - 45)));
+    E[4][2] ^= D[2];
+    B[1][4] = (((E[4][2]) << 61) ^ ((E[4][2]) >> (64 - 61)));
+    A[1][0] = B[1][0] ^ ((~B[1][1]) & B[1][2]);
+    C[0] ^= A[1][0];
+    A[1][1] = B[1][1] ^ ((~B[1][2]) & B[1][3]);
+    C[1] ^= A[1][1];
+    A[1][2] = B[1][2] ^ ((~B[1][3]) & B[1][4]);
+    C[2] ^= A[1][2];
+    A[1][3] = B[1][3] ^ ((~B[1][4]) & B[1][0]);
+    C[3] ^= A[1][3];
+    A[1][4] = B[1][4] ^ ((~B[1][0]) & B[1][1]);
+    C[4] ^= A[1][4];
+    E[0][1] ^= D[1];
+    B[2][0] = (((E[0][1]) << 1) ^ ((E[0][1]) >> (64 - 1)));
+    E[1][2] ^= D[2];
+    B[2][1] = (((E[1][2]) << 6) ^ ((E[1][2]) >> (64 - 6)));
+    E[2][3] ^= D[3];
+    B[2][2] = (((E[2][3]) << 25) ^ ((E[2][3]) >> (64 - 25)));
+    E[3][4] ^= D[4];
+    B[2][3] = (((E[3][4]) << 8) ^ ((E[3][4]) >> (64 - 8)));
+    E[4][0] ^= D[0];
+    B[2][4] = (((E[4][0]) << 18) ^ ((E[4][0]) >> (64 - 18)));
+    A[2][0] = B[2][0] ^ ((~B[2][1]) & B[2][2]);
+    C[0] ^= A[2][0];
+    A[2][1] = B[2][1] ^ ((~B[2][2]) & B[2][3]);
+    C[1] ^= A[2][1];
+    A[2][2] = B[2][2] ^ ((~B[2][3]) & B[2][4]);
+    C[2] ^= A[2][2];
+    A[2][3] = B[2][3] ^ ((~B[2][4]) & B[2][0]);
+    C[3] ^= A[2][3];
+    A[2][4] = B[2][4] ^ ((~B[2][0]) & B[2][1]);
+    C[4] ^= A[2][4];
+    E[0][4] ^= D[4];
+    B[3][0] = (((E[0][4]) << 27) ^ ((E[0][4]) >> (64 - 27)));
+    E[1][0] ^= D[0];
+    B[3][1] = (((E[1][0]) << 36) ^ ((E[1][0]) >> (64 - 36)));
+    E[2][1] ^= D[1];
+    B[3][2] = (((E[2][1]) << 10) ^ ((E[2][1]) >> (64 - 10)));
+    E[3][2] ^= D[2];
+    B[3][3] = (((E[3][2]) << 15) ^ ((E[3][2]) >> (64 - 15)));
+    E[4][3] ^= D[3];
+    B[3][4] = (((E[4][3]) << 56) ^ ((E[4][3]) >> (64 - 56)));
+    A[3][0] = B[3][0] ^ ((~B[3][1]) & B[3][2]);
+    C[0] ^= A[3][0];
+    A[3][1] = B[3][1] ^ ((~B[3][2]) & B[3][3]);
+    C[1] ^= A[3][1];
+    A[3][2] = B[3][2] ^ ((~B[3][3]) & B[3][4]);
+    C[2] ^= A[3][2];
+    A[3][3] = B[3][3] ^ ((~B[3][4]) & B[3][0]);
+    C[3] ^= A[3][3];
+    A[3][4] = B[3][4] ^ ((~B[3][0]) & B[3][1]);
+    C[4] ^= A[3][4];
+    E[0][2] ^= D[2];
+    B[4][0] = (((E[0][2]) << 62) ^ ((E[0][2]) >> (64 - 62)));
+    E[1][3] ^= D[3];
+    B[4][1] = (((E[1][3]) << 55) ^ ((E[1][3]) >> (64 - 55)));
+    E[2][4] ^= D[4];
+    B[4][2] = (((E[2][4]) << 39) ^ ((E[2][4]) >> (64 - 39)));
+    E[3][0] ^= D[0];
+    B[4][3] = (((E[3][0]) << 41) ^ ((E[3][0]) >> (64 - 41)));
+    E[4][1] ^= D[1];
+    B[4][4] = (((E[4][1]) << 2) ^ ((E[4][1]) >> (64 - 2)));
+    A[4][0] = B[4][0] ^ ((~B[4][1]) & B[4][2]);
+    C[0] ^= A[4][0];
+    A[4][1] = B[4][1] ^ ((~B[4][2]) & B[4][3]);
+    C[1] ^= A[4][1];
+    A[4][2] = B[4][2] ^ ((~B[4][3]) & B[4][4]);
+    C[2] ^= A[4][2];
+    A[4][3] = B[4][3] ^ ((~B[4][4]) & B[4][0]);
+    C[3] ^= A[4][3];
+    A[4][4] = B[4][4] ^ ((~B[4][0]) & B[4][1]);
+    C[4] ^= A[4][4];
+    D[0] = C[4] ^ (((C[1]) << 1) ^ ((C[1]) >> (64 - 1)));
+    D[1] = C[0] ^ (((C[2]) << 1) ^ ((C[2]) >> (64 - 1)));
+    D[2] = C[1] ^ (((C[3]) << 1) ^ ((C[3]) >> (64 - 1)));
+    D[3] = C[2] ^ (((C[4]) << 1) ^ ((C[4]) >> (64 - 1)));
+    D[4] = C[3] ^ (((C[0]) << 1) ^ ((C[0]) >> (64 - 1)));
+    A[0][0] ^= D[0];
+    B[0][0] = A[0][0];
+    A[1][1] ^= D[1];
+    B[0][1] = (((A[1][1]) << 44) ^ ((A[1][1]) >> (64 - 44)));
+    A[2][2] ^= D[2];
+    B[0][2] = (((A[2][2]) << 43) ^ ((A[2][2]) >> (64 - 43)));
+    A[3][3] ^= D[3];
+    B[0][3] = (((A[3][3]) << 21) ^ ((A[3][3]) >> (64 - 21)));
+    A[4][4] ^= D[4];
+    B[0][4] = (((A[4][4]) << 14) ^ ((A[4][4]) >> (64 - 14)));
+    E[0][0] = B[0][0] ^ ((~B[0][1]) & B[0][2]);
+    E[0][0] ^= KECCAKF1600_ROUND_CONSTANTS[22];
+    C[0] = E[0][0];
+    E[0][1] = B[0][1] ^ ((~B[0][2]) & B[0][3]);
+    C[1] = E[0][1];
+    E[0][2] = B[0][2] ^ ((~B[0][3]) & B[0][4]);
+    C[2] = E[0][2];
+    E[0][3] = B[0][3] ^ ((~B[0][4]) & B[0][0]);
+    C[3] = E[0][3];
+    E[0][4] = B[0][4] ^ ((~B[0][0]) & B[0][1]);
+    C[4] = E[0][4];
+    A[0][3] ^= D[3];
+    B[1][0] = (((A[0][3]) << 28) ^ ((A[0][3]) >> (64 - 28)));
+    A[1][4] ^= D[4];
+    B[1][1] = (((A[1][4]) << 20) ^ ((A[1][4]) >> (64 - 20)));
+    A[2][0] ^= D[0];
+    B[1][2] = (((A[2][0]) << 3) ^ ((A[2][0]) >> (64 - 3)));
+    A[3][1] ^= D[1];
+    B[1][3] = (((A[3][1]) << 45) ^ ((A[3][1]) >> (64 - 45)));
+    A[4][2] ^= D[2];
+    B[1][4] = (((A[4][2]) << 61) ^ ((A[4][2]) >> (64 - 61)));
+    E[1][0] = B[1][0] ^ ((~B[1][1]) & B[1][2]);
+    C[0] ^= E[1][0];
+    E[1][1] = B[1][1] ^ ((~B[1][2]) & B[1][3]);
+    C[1] ^= E[1][1];
+    E[1][2] = B[1][2] ^ ((~B[1][3]) & B[1][4]);
+    C[2] ^= E[1][2];
+    E[1][3] = B[1][3] ^ ((~B[1][4]) & B[1][0]);
+    C[3] ^= E[1][3];
+    E[1][4] = B[1][4] ^ ((~B[1][0]) & B[1][1]);
+    C[4] ^= E[1][4];
+    A[0][1] ^= D[1];
+    B[2][0] = (((A[0][1]) << 1) ^ ((A[0][1]) >> (64 - 1)));
+    A[1][2] ^= D[2];
+    B[2][1] = (((A[1][2]) << 6) ^ ((A[1][2]) >> (64 - 6)));
+    A[2][3] ^= D[3];
+    B[2][2] = (((A[2][3]) << 25) ^ ((A[2][3]) >> (64 - 25)));
+    A[3][4] ^= D[4];
+    B[2][3] = (((A[3][4]) << 8) ^ ((A[3][4]) >> (64 - 8)));
+    A[4][0] ^= D[0];
+    B[2][4] = (((A[4][0]) << 18) ^ ((A[4][0]) >> (64 - 18)));
+    E[2][0] = B[2][0] ^ ((~B[2][1]) & B[2][2]);
+    C[0] ^= E[2][0];
+    E[2][1] = B[2][1] ^ ((~B[2][2]) & B[2][3]);
+    C[1] ^= E[2][1];
+    E[2][2] = B[2][2] ^ ((~B[2][3]) & B[2][4]);
+    C[2] ^= E[2][2];
+    E[2][3] = B[2][3] ^ ((~B[2][4]) & B[2][0]);
+    C[3] ^= E[2][3];
+    E[2][4] = B[2][4] ^ ((~B[2][0]) & B[2][1]);
+    C[4] ^= E[2][4];
+    A[0][4] ^= D[4];
+    B[3][0] = (((A[0][4]) << 27) ^ ((A[0][4]) >> (64 - 27)));
+    A[1][0] ^= D[0];
+    B[3][1] = (((A[1][0]) << 36) ^ ((A[1][0]) >> (64 - 36)));
+    A[2][1] ^= D[1];
+    B[3][2] = (((A[2][1]) << 10) ^ ((A[2][1]) >> (64 - 10)));
+    A[3][2] ^= D[2];
+    B[3][3] = (((A[3][2]) << 15) ^ ((A[3][2]) >> (64 - 15)));
+    A[4][3] ^= D[3];
+    B[3][4] = (((A[4][3]) << 56) ^ ((A[4][3]) >> (64 - 56)));
+    E[3][0] = B[3][0] ^ ((~B[3][1]) & B[3][2]);
+    C[0] ^= E[3][0];
+    E[3][1] = B[3][1] ^ ((~B[3][2]) & B[3][3]);
+    C[1] ^= E[3][1];
+    E[3][2] = B[3][2] ^ ((~B[3][3]) & B[3][4]);
+    C[2] ^= E[3][2];
+    E[3][3] = B[3][3] ^ ((~B[3][4]) & B[3][0]);
+    C[3] ^= E[3][3];
+    E[3][4] = B[3][4] ^ ((~B[3][0]) & B[3][1]);
+    C[4] ^= E[3][4];
+    A[0][2] ^= D[2];
+    B[4][0] = (((A[0][2]) << 62) ^ ((A[0][2]) >> (64 - 62)));
+    A[1][3] ^= D[3];
+    B[4][1] = (((A[1][3]) << 55) ^ ((A[1][3]) >> (64 - 55)));
+    A[2][4] ^= D[4];
+    B[4][2] = (((A[2][4]) << 39) ^ ((A[2][4]) >> (64 - 39)));
+    A[3][0] ^= D[0];
+    B[4][3] = (((A[3][0]) << 41) ^ ((A[3][0]) >> (64 - 41)));
+    A[4][1] ^= D[1];
+    B[4][4] = (((A[4][1]) << 2) ^ ((A[4][1]) >> (64 - 2)));
+    E[4][0] = B[4][0] ^ ((~B[4][1]) & B[4][2]);
+    C[0] ^= E[4][0];
+    E[4][1] = B[4][1] ^ ((~B[4][2]) & B[4][3]);
+    C[1] ^= E[4][1];
+    E[4][2] = B[4][2] ^ ((~B[4][3]) & B[4][4]);
+    C[2] ^= E[4][2];
+    E[4][3] = B[4][3] ^ ((~B[4][4]) & B[4][0]);
+    C[3] ^= E[4][3];
+    E[4][4] = B[4][4] ^ ((~B[4][0]) & B[4][1]);
+    C[4] ^= E[4][4];
+    D[0] = C[4] ^ (((C[1]) << 1) ^ ((C[1]) >> (64 - 1)));
+    D[1] = C[0] ^ (((C[2]) << 1) ^ ((C[2]) >> (64 - 1)));
+    D[2] = C[1] ^ (((C[3]) << 1) ^ ((C[3]) >> (64 - 1)));
+    D[3] = C[2] ^ (((C[4]) << 1) ^ ((C[4]) >> (64 - 1)));
+    D[4] = C[3] ^ (((C[0]) << 1) ^ ((C[0]) >> (64 - 1)));
+    E[0][0] ^= D[0];
+    B[0][0] = E[0][0];
+    E[1][1] ^= D[1];
+    B[0][1] = (((E[1][1]) << 44) ^ ((E[1][1]) >> (64 - 44)));
+    E[2][2] ^= D[2];
+    B[0][2] = (((E[2][2]) << 43) ^ ((E[2][2]) >> (64 - 43)));
+    E[3][3] ^= D[3];
+    B[0][3] = (((E[3][3]) << 21) ^ ((E[3][3]) >> (64 - 21)));
+    E[4][4] ^= D[4];
+    B[0][4] = (((E[4][4]) << 14) ^ ((E[4][4]) >> (64 - 14)));
+    A[0][0] = B[0][0] ^ ((~B[0][1]) & B[0][2]);
+    A[0][0] ^= KECCAKF1600_ROUND_CONSTANTS[23];
+    A[0][1] = B[0][1] ^ ((~B[0][2]) & B[0][3]);
+    A[0][2] = B[0][2] ^ ((~B[0][3]) & B[0][4]);
+    A[0][3] = B[0][3] ^ ((~B[0][4]) & B[0][0]);
+    A[0][4] = B[0][4] ^ ((~B[0][0]) & B[0][1]);
+    E[0][3] ^= D[3];
+    B[1][0] = (((E[0][3]) << 28) ^ ((E[0][3]) >> (64 - 28)));
+    E[1][4] ^= D[4];
+    B[1][1] = (((E[1][4]) << 20) ^ ((E[1][4]) >> (64 - 20)));
+    E[2][0] ^= D[0];
+    B[1][2] = (((E[2][0]) << 3) ^ ((E[2][0]) >> (64 - 3)));
+    E[3][1] ^= D[1];
+    B[1][3] = (((E[3][1]) << 45) ^ ((E[3][1]) >> (64 - 45)));
+    E[4][2] ^= D[2];
+    B[1][4] = (((E[4][2]) << 61) ^ ((E[4][2]) >> (64 - 61)));
+    A[1][0] = B[1][0] ^ ((~B[1][1]) & B[1][2]);
+    A[1][1] = B[1][1] ^ ((~B[1][2]) & B[1][3]);
+    A[1][2] = B[1][2] ^ ((~B[1][3]) & B[1][4]);
+    A[1][3] = B[1][3] ^ ((~B[1][4]) & B[1][0]);
+    A[1][4] = B[1][4] ^ ((~B[1][0]) & B[1][1]);
+    E[0][1] ^= D[1];
+    B[2][0] = (((E[0][1]) << 1) ^ ((E[0][1]) >> (64 - 1)));
+    E[1][2] ^= D[2];
+    B[2][1] = (((E[1][2]) << 6) ^ ((E[1][2]) >> (64 - 6)));
+    E[2][3] ^= D[3];
+    B[2][2] = (((E[2][3]) << 25) ^ ((E[2][3]) >> (64 - 25)));
+    E[3][4] ^= D[4];
+    B[2][3] = (((E[3][4]) << 8) ^ ((E[3][4]) >> (64 - 8)));
+    E[4][0] ^= D[0];
+    B[2][4] = (((E[4][0]) << 18) ^ ((E[4][0]) >> (64 - 18)));
+    A[2][0] = B[2][0] ^ ((~B[2][1]) & B[2][2]);
+    A[2][1] = B[2][1] ^ ((~B[2][2]) & B[2][3]);
+    A[2][2] = B[2][2] ^ ((~B[2][3]) & B[2][4]);
+    A[2][3] = B[2][3] ^ ((~B[2][4]) & B[2][0]);
+    A[2][4] = B[2][4] ^ ((~B[2][0]) & B[2][1]);
+    E[0][4] ^= D[4];
+    B[3][0] = (((E[0][4]) << 27) ^ ((E[0][4]) >> (64 - 27)));
+    E[1][0] ^= D[0];
+    B[3][1] = (((E[1][0]) << 36) ^ ((E[1][0]) >> (64 - 36)));
+    E[2][1] ^= D[1];
+    B[3][2] = (((E[2][1]) << 10) ^ ((E[2][1]) >> (64 - 10)));
+    E[3][2] ^= D[2];
+    B[3][3] = (((E[3][2]) << 15) ^ ((E[3][2]) >> (64 - 15)));
+    E[4][3] ^= D[3];
+    B[3][4] = (((E[4][3]) << 56) ^ ((E[4][3]) >> (64 - 56)));
+    A[3][0] = B[3][0] ^ ((~B[3][1]) & B[3][2]);
+    A[3][1] = B[3][1] ^ ((~B[3][2]) & B[3][3]);
+    A[3][2] = B[3][2] ^ ((~B[3][3]) & B[3][4]);
+    A[3][3] = B[3][3] ^ ((~B[3][4]) & B[3][0]);
+    A[3][4] = B[3][4] ^ ((~B[3][0]) & B[3][1]);
+    E[0][2] ^= D[2];
+    B[4][0] = (((E[0][2]) << 62) ^ ((E[0][2]) >> (64 - 62)));
+    E[1][3] ^= D[3];
+    B[4][1] = (((E[1][3]) << 55) ^ ((E[1][3]) >> (64 - 55)));
+    E[2][4] ^= D[4];
+    B[4][2] = (((E[2][4]) << 39) ^ ((E[2][4]) >> (64 - 39)));
+    E[3][0] ^= D[0];
+    B[4][3] = (((E[3][0]) << 41) ^ ((E[3][0]) >> (64 - 41)));
+    E[4][1] ^= D[1];
+    B[4][4] = (((E[4][1]) << 2) ^ ((E[4][1]) >> (64 - 2)));
+    A[4][0] = B[4][0] ^ ((~B[4][1]) & B[4][2]);
+    A[4][1] = B[4][1] ^ ((~B[4][2]) & B[4][3]);
+    A[4][2] = B[4][2] ^ ((~B[4][3]) & B[4][4]);
+    A[4][3] = B[4][3] ^ ((~B[4][4]) & B[4][0]);
+    A[4][4] = B[4][4] ^ ((~B[4][0]) & B[4][1]);
+}
+
+} // namespace cartesi
+
+#endif // KECCAKF_H
diff --git a/src/machine-config.h b/src/machine-config.h
index 285bc3156..58754f8b5 100644
--- a/src/machine-config.h
+++ b/src/machine-config.h
@@ -156,7 +156,7 @@ struct hash_tree_config final {
     bool truncate{false};      ///< Should backing store be truncated to correct size?
     std::string sht_filename;  ///< Backing storage for sparse hash-tree
     std::string phtc_filename; ///< Backing storage for page hash-tree cache
-    uint64_t phtc_size{2048};  ///< Max number of pages in page hash-tree cache
+    uint64_t phtc_size{8192};  ///< Max number of pages in page hash-tree cache
 };
 
 /// \brief Machine state config
@@ -168,7 +168,7 @@ struct machine_config final {
     virtio_configs virtio;           ///< VirtIO devices config
     cmio_config cmio{};              ///< Cartesi Machine IO config
     pmas_config pmas{};              ///< Physical Memory Attributes config
-    uarch_config uarch{};            ///< Microarchition config
+    uarch_config uarch{};            ///< Microarchitecture config
     hash_tree_config hash_tree{};    ///< Hash-tree config
 
     /// \brief Get the name where config will be stored in a directory
diff --git a/src/machine-hash.h b/src/machine-hash.h
index 28d921704..3001eec1a 100644
--- a/src/machine-hash.h
+++ b/src/machine-hash.h
@@ -26,10 +26,10 @@
 
 namespace cartesi {
 
-static constexpr size_t machine_hash_size = 32;
-using machine_hash = std::array<unsigned char, machine_hash_size>;
-using machine_hash_view = std::span<unsigned char, machine_hash_size>;
-using const_machine_hash_view = std::span<const unsigned char, machine_hash_size>;
+static constexpr size_t MACHINE_HASH_SIZE = 32;
+using machine_hash = std::array<unsigned char, MACHINE_HASH_SIZE>;
+using machine_hash_view = std::span<unsigned char, MACHINE_HASH_SIZE>;
+using const_machine_hash_view = std::span<const unsigned char, MACHINE_HASH_SIZE>;
 using machine_hashes = std::vector<machine_hash>;
 
 } // namespace cartesi
diff --git a/src/machine.cpp b/src/machine.cpp
index 425913216..450b3772b 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -19,7 +19,6 @@
 
 #include <algorithm>
 #include <array>
-#include <bit>
 #include <cerrno>
 #include <cstdint>
 #include <cstdio>
@@ -218,12 +217,11 @@ void machine::validate_processor_shadow(bool skip_version_check) const {
         throw std::invalid_argument{"x0 register is corrupt"};
     }
     // Ensure padding bytes are consistent
-    if ( // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        !is_pristine(reinterpret_cast<unsigned char *>(&m_s->shadow.registers_padding_[0]),
-            sizeof(m_s->shadow.registers_padding_)) ||
-        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        !is_pristine(reinterpret_cast<unsigned char *>(&m_s->shadow.tlb_padding_[0]),
-            sizeof(m_s->shadow.tlb_padding_))) {
+    if (!is_pristine(std::span<const unsigned char>{// NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+            reinterpret_cast<unsigned char *>(&m_s->shadow.registers_padding_[0]),
+            sizeof(m_s->shadow.registers_padding_)}) ||
+        !is_pristine(std::span<const unsigned char>{// NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+            reinterpret_cast<unsigned char *>(&m_s->shadow.tlb_padding_[0]), sizeof(m_s->shadow.tlb_padding_)})) {
         throw std::invalid_argument{"shadow padding bytes are corrupt"};
     }
 }
@@ -1612,7 +1610,7 @@ void machine::fill_memory(uint64_t paddr, uint8_t val, uint64_t length) {
     foreach_aligned_chunk(paddr, length, AR_PAGE_SIZE, [&ar, val](auto chunk_start, auto chunk_length) {
         const auto offset = chunk_start - ar.get_start();
         const auto dest = ar.get_host_memory() + offset;
-        if (val != 0 || !is_pristine(dest, chunk_length)) {
+        if (val != 0 || !is_pristine(std::span<const unsigned char>{dest, chunk_length})) {
             memset(dest, val, chunk_length);
             ar.get_dirty_page_tree().mark_dirty_page_and_up(offset);
         }
@@ -2024,10 +2022,13 @@ void machine::collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_
     if (!update_hash_tree()) {
         throw std::runtime_error{"update hash tree failed"};
     }
-    auto current_uarch_state_hash =
-        get_node_hash(AR_SHADOW_UARCH_STATE_START, UARCH_STATE_LOG2_SIZE, skip_hash_tree_update);
-    if (current_uarch_state_hash != get_uarch_pristine_state_hash()) {
-        throw std::runtime_error{"microarchitecture is not reset"};
+    if (m_c.hash_tree.hash_function == hash_function_type::keccak256) {
+        // Ensure that the microarchitecture is reset
+        auto current_uarch_state_hash =
+            get_node_hash(AR_SHADOW_UARCH_STATE_START, UARCH_STATE_LOG2_SIZE, skip_hash_tree_update);
+        if (current_uarch_state_hash != get_uarch_pristine_state_hash()) {
+            throw std::runtime_error{"microarchitecture is not reset"};
+        }
     }
     collect_mcycle_hashes_state_access::context context{};
     context.dirty_words.reserve(mcycle_period * 3);
diff --git a/src/merkle-tree-hash.cpp b/src/merkle-tree-hash.cpp
index 314917562..7efa3e8bb 100644
--- a/src/merkle-tree-hash.cpp
+++ b/src/merkle-tree-hash.cpp
@@ -116,9 +116,7 @@ __attribute__((__format__(__printf__, 1, 2))) static void error(const char *fmt,
 /// \param log2_word_size Log<sub>2</sub> of word size
 /// \param hash Receives the word hash
 static void get_word_hash(hasher_type &h, const unsigned char *word, int log2_word_size, machine_hash &hash) {
-    h.begin();
-    h.add_data(std::span<const unsigned char>(word, 1 << log2_word_size));
-    h.end(hash);
+    h.hash(std::span<const unsigned char>(word, 1 << log2_word_size), hash);
 }
 
 /// \brief Computes the Merkle hash of a leaf of data
diff --git a/src/os-features.h b/src/os-features.h
index 0060fca7f..cd5476ab1 100644
--- a/src/os-features.h
+++ b/src/os-features.h
@@ -28,6 +28,10 @@
 #define THREAD_LOCAL
 #endif
 
+#if !defined(NO_THREADS) && !defined(NO_OPENMP) && defined(_OPENMP) && !defined(__wasm__)
+#define HAVE_OPENMP
+#endif
+
 #if !defined(NO_TERMIOS) && !defined(_WIN32) && !defined(__wasi__)
 #define HAVE_TERMIOS
 #endif
diff --git a/src/page-hash-tree-cache-stats.h b/src/page-hash-tree-cache-stats.h
index 8d2977f5e..346544ebb 100644
--- a/src/page-hash-tree-cache-stats.h
+++ b/src/page-hash-tree-cache-stats.h
@@ -22,13 +22,14 @@
 namespace cartesi {
 
 struct page_hash_tree_cache_stats {
-    uint64_t page_hits;          ///\< Number of pages looked up and found in cache
-    uint64_t page_misses;        ///\< Number of pages looked up but missing from cache
-    uint64_t word_hits;          ///\< Number of words equal to corresponding word in cache entry
-    uint64_t word_misses;        ///\< Number of words differing from corresponding word in cache entry
-    uint64_t inner_page_hashes;  ///\< Number of inner page hashing operations performed
-    uint64_t pristine_pages;     ///\< Number of pages found to be pristine during updates
-    uint64_t non_pristine_pages; ///\< Number of pages found not to be pristine during updates
+    uint64_t page_hits{0};          ///\< Number of pages looked up and found in cache
+    uint64_t page_misses{0};        ///\< Number of pages looked up but missing from cache
+    uint64_t word_hits{0};          ///\< Number of words equal to corresponding word in cache entry
+    uint64_t word_misses{0};        ///\< Number of words differing from corresponding word in cache entry
+    uint64_t page_changes{0};       ///\< Number of pages changes during updates
+    uint64_t inner_page_hashes{0};  ///\< Number of inner page hashing operations performed
+    uint64_t pristine_pages{0};     ///\< Number of pages found to be pristine during updates
+    uint64_t non_pristine_pages{0}; ///\< Number of pages found not to be pristine during updates
 };
 
 } // namespace cartesi
diff --git a/src/page-hash-tree-cache.h b/src/page-hash-tree-cache.h
index 5b5b2634c..02dbc5bcc 100644
--- a/src/page-hash-tree-cache.h
+++ b/src/page-hash-tree-cache.h
@@ -20,7 +20,7 @@
 /// \file
 /// \brief Page hash-tree cache interface
 
-#include <atomic>
+#include <bit>
 #include <functional>
 #include <iomanip>
 #include <iostream>
@@ -29,10 +29,12 @@
 #include <span>
 #include <unordered_map>
 
+#include <boost/container/static_vector.hpp>
 #include <boost/intrusive/list.hpp>
 
 #include "address-range-constants.h"
 #include "circular-buffer.h"
+#include "compiler-defines.h"
 #include "hash-tree-constants.h"
 #include "i-hasher.h"
 #include "is-pristine.h"
@@ -41,6 +43,7 @@
 #include "page-hash-tree-cache-stats.h"
 #include "ranges.h"
 #include "signposts.h"
+#include "simd-hasher.h"
 #include "strict-aliasing.h"
 
 namespace cartesi {
@@ -62,6 +65,7 @@ class page_hash_tree_cache {
     using const_page_view = std::span<const unsigned char, m_page_size>;
 
     using page_hash_tree = std::array<machine_hash, m_page_hash_tree_size>;
+    using page_hash_tree_view = std::span<machine_hash, m_page_hash_tree_size>;
     static_assert(POD<page>, "hash_tree must be trivially copyable and standard layout");
     static_assert(POD<machine_hash>, "machine_hash must be trivially copyable and standard layout");
     static_assert(POD<page_hash_tree>, "page_hash_tree must be trivially copyable and standard layout");
@@ -146,6 +150,13 @@ class page_hash_tree_cache {
             return i / 2;
         }
 
+        /// \brief Returns the log2 level of a node in the page hash tree (its height in the tree)
+        /// \param i Node index
+        /// \returns Log 2 level of the node
+        static int log2_level(int i) {
+            return std::countl_zero(static_cast<uint32_t>(i)) - 24;
+        }
+
         /// \brief Returns a pristine page tree for a given hasher
         /// \tparam H Hasher type
         /// \param h Hasher object
@@ -234,7 +245,71 @@ class page_hash_tree_cache {
         }
     };
 
-    /// \brief Updates and entry with new page data
+    template <IHasher hasher_type>
+    class simd_hasher {
+        struct leaf_entry {
+            const_hash_tree_word_view data;
+            machine_hash_view result;
+        };
+
+        struct node_entry {
+            const_machine_hash_view left;
+            const_machine_hash_view right;
+            machine_hash_view result;
+        };
+
+        struct dirty_entry {
+            page_hash_tree_view page_tree;
+            int node_index{0};
+            bool operator==(const dirty_entry &other) const noexcept {
+                return page_tree.data() == other.page_tree.data() && node_index == other.node_index;
+            }
+        };
+
+        static constexpr size_t QUEUE_MAX_SIZE =
+            ((UINT64_C(1) << ((HASH_TREE_LOG2_PAGE_SIZE - HASH_TREE_LOG2_WORD_SIZE) - 1))) *
+            hasher_type::MAX_LANE_COUNT;
+
+        hasher_type m_hasher;
+        simd_data_hasher<hasher_type, const_hash_tree_word_view> m_leaves_queue;
+        simd_concat_hasher<hasher_type, const_machine_hash_view> m_concat_queue;
+        circular_buffer<dirty_entry, QUEUE_MAX_SIZE> m_dirty_queue;
+
+    public:
+        static constexpr int QUEUE_MAX_PAGE_COUNT = hasher_type::MAX_LANE_COUNT;
+
+        /// \brief Enqueues a leaf for hashing
+        void enqueue_leaf(const_hash_tree_word_view data, page_hash_tree_view page_tree, int word_index) noexcept {
+            m_leaves_queue.enqueue(data, page_tree[word_index]);
+            m_dirty_queue.try_push_back(dirty_entry{.page_tree = page_tree, .node_index = entry::parent(word_index)});
+        }
+
+        /// \brief Flushes the entire queue
+        int flush() noexcept {
+            m_leaves_queue.flush();
+            int hashes = 0;
+
+            while (!m_dirty_queue.empty()) {
+                for (size_t i = 0, n = m_dirty_queue.size(); i < n; ++i) {
+                    const auto &d = m_dirty_queue.front();
+                    const auto node_index = d.node_index;
+                    const auto page_tree = d.page_tree;
+                    m_dirty_queue.pop_front();
+                    ++hashes;
+                    m_concat_queue.enqueue(page_tree[entry::left_child(node_index)],
+                        page_tree[entry::right_child(node_index)], page_tree[node_index]);
+                    if (node_index > 1) [[likely]] {
+                        m_dirty_queue.try_push_back(
+                            dirty_entry{.page_tree = page_tree, .node_index = entry::parent(node_index)});
+                    }
+                }
+                m_concat_queue.flush();
+            }
+            return hashes;
+        }
+    };
+
+    /// \brief Enqueue entry to be hashed with new page data
     /// \tparam H Hasher type
     /// \tparam D Data range type
     /// \param h Hasher object
@@ -243,7 +318,8 @@ class page_hash_tree_cache {
     /// \returns True if update succeeded, false otherwise
     template <IHasher H, ContiguousRangeOfByteLike D>
     // NOLINTNEXTLINE(cppcoreguidelines-missing-std-forward)
-    bool update_entry(H &&h, D &&d, entry &e) noexcept {
+    bool enqueue_hash_entry(page_hash_tree_cache::simd_hasher<H> &queue, D &&d, entry &e,
+        page_hash_tree_cache_stats &stats) noexcept {
         if (std::ranges::size(d) != m_page_size) {
             return false;
         }
@@ -253,14 +329,12 @@ class page_hash_tree_cache {
                 SCOPED_SIGNPOST(m_log, m_spid_pristine_update, "phtc: pristine update", "");
                 e.clear_hash_tree(m_pristine_page_hash_tree);
                 e.clear_page();
-                ++m_pristine_pages;
+                ++stats.pristine_pages;
                 return true;
             }
         }
         SCOPED_SIGNPOST(m_log, m_spid_non_pristine_update, "phtc: non-pristine update", "");
-        ++m_non_pristine_pages;
         const const_page_view page{std::ranges::data(d), std::ranges::size(d)};
-        circular_buffer<int, m_page_word_count / 2> dirty_nodes;
         // Go over all words in the entry page, comparing with updated page,
         // and updating the hashes for the modified words
         //??D In C++23, we would use std::views::slide and std::views::zip to write this in declarative style.
@@ -269,31 +343,19 @@ class page_hash_tree_cache {
         int miss = 0;
         auto &page_tree = e.get_page_hash_tree();
         for (int offset = 0, index = m_page_word_count; offset < m_page_size; offset += m_word_size, ++index) {
-            const auto entry_word = entry_page.subspan(offset, m_word_size);
-            const auto page_word = page.subspan(offset, m_word_size);
-            if (!std::ranges::equal(entry_word, page_word)) {
-                get_hash(h, page_word, page_tree[index]);
+            const auto entry_word = std::span<unsigned char, m_word_size>{entry_page.subspan(offset, m_word_size)};
+            const auto page_word = std::span<const unsigned char, m_word_size>{page.subspan(offset, m_word_size)};
+            if (!std::ranges::equal(entry_word, page_word)) [[unlikely]] {
                 std::ranges::copy(page_word, entry_word.begin());
-                dirty_nodes.try_push_back(e.parent(index));
+                queue.enqueue_leaf(page_word, page_tree, index);
                 ++miss;
             } else {
                 ++hit;
             }
         }
-        m_word_hits += hit;
-        m_word_misses += miss;
-        // Now go over fifo, taking a node, updating its from its children, and enqueueing its parent for update
-        int inner_page_hashes = 0;
-        while (!dirty_nodes.empty()) {
-            const int index = dirty_nodes.front();
-            dirty_nodes.pop_front();
-            ++inner_page_hashes;
-            get_concat_hash(h, page_tree[e.left_child(index)], page_tree[e.right_child(index)], page_tree[index]);
-            if (index != 1) {
-                dirty_nodes.try_push_back(e.parent(index));
-            }
-        }
-        m_inner_page_hashes += inner_page_hashes;
+        stats.word_hits += hit;
+        stats.word_misses += miss;
+        ++stats.non_pristine_pages;
         return true;
     }
 
@@ -304,7 +366,7 @@ class page_hash_tree_cache {
         const page_view entry_page{e.get_page()};
         auto &page_tree = e.get_page_hash_tree();
         for (int offset = 0, index = m_page_word_count; offset < m_page_size; offset += m_word_size, ++index) {
-            const auto page_word = entry_page.subspan(offset, m_word_size);
+            const auto page_word = std::span<const unsigned char, m_word_size>{entry_page.subspan(offset, m_word_size)};
             const auto page_word_hash = get_hash(h, page_word);
             if (page_word_hash != page_tree[index]) {
                 const int log2_size = HASH_TREE_LOG2_WORD_SIZE;
@@ -384,14 +446,14 @@ class page_hash_tree_cache {
             // Make it most recently used
             m_lru.splice(m_lru.begin(), m_lru, it->second.first);
             hit = true;
-            ++m_page_hits;
+            ++m_stats.page_hits;
             // Return borrowed entry
             return std::ref(e.set_borrowed(true));
         }
         hit = false;
         // Not in map, but we still have unused entries to lend
         if (m_used < m_entries.size()) {
-            ++m_page_misses;
+            ++m_stats.page_misses;
             entry &e = m_entries[m_used++];
             if (e.get_borrowed()) {
                 throw std::runtime_error{"page hash-tree cache entry already borrowed"};
@@ -407,6 +469,7 @@ class page_hash_tree_cache {
         if (e.get_borrowed()) {
             return {};
         }
+        ++m_stats.page_misses;
         m_map.erase(e.get_paddr_page());
         m_lru.pop_back();
         m_lru.push_front(e);
@@ -451,27 +514,24 @@ class page_hash_tree_cache {
     /// \param clear Whether to clear statistics after retrieving them
     /// \returns Statistics
     page_hash_tree_cache_stats get_stats(bool clear = false) noexcept {
-        auto s = page_hash_tree_cache_stats{
-            .page_hits = m_page_hits.load(),
-            .page_misses = m_page_misses.load(),
-            .word_hits = m_word_hits.load(),
-            .word_misses = m_word_misses.load(),
-            .inner_page_hashes = m_inner_page_hashes.load(),
-            .pristine_pages = m_pristine_pages.load(),
-            .non_pristine_pages = m_non_pristine_pages.load(),
-        };
+        auto s = m_stats;
         if (clear) {
-            m_page_hits = 0;
-            m_page_misses = 0;
-            m_word_hits = 0;
-            m_word_misses = 0;
-            m_inner_page_hashes = 0;
-            m_pristine_pages = 0;
-            m_non_pristine_pages = 0;
+            m_stats.page_hits = 0;
+            m_stats.page_misses = 0;
+            m_stats.word_hits = 0;
+            m_stats.word_misses = 0;
+            m_stats.page_changes = 0;
+            m_stats.inner_page_hashes = 0;
+            m_stats.pristine_pages = 0;
+            m_stats.non_pristine_pages = 0;
         }
         return s;
     }
 
+    page_hash_tree_cache_stats &get_stats_ref() noexcept {
+        return m_stats;
+    }
+
     /// \brief Destructor
     ~page_hash_tree_cache() {
 #ifdef DUMP_HASH_TREE_STATS
@@ -490,11 +550,12 @@ class page_hash_tree_cache {
             std::cerr << "word hit rate: " << 100.0 * static_cast<double>(s.word_hits) / static_cast<double>(word_all)
                       << '\n';
         }
+        std::cerr << "changed pages: " << s.page_changes << '\n';
         std::cerr << "inner page hashes: " << s.inner_page_hashes << '\n';
         auto pristine_all = s.pristine_pages + s.non_pristine_pages;
         if (pristine_all > 0) {
-            std::cerr << "pristine pages: " << s.inner_page_hashes << '\n';
-            std::cerr << "non-pristine pages: " << s.inner_page_hashes << '\n';
+            std::cerr << "pristine pages: " << s.pristine_pages << '\n';
+            std::cerr << "non-pristine pages: " << s.non_pristine_pages << '\n';
             std::cerr << "pristine page ratio: "
                       << 100.0 * static_cast<double>(s.pristine_pages) / static_cast<double>(pristine_all) << '\n';
         }
@@ -549,13 +610,7 @@ class page_hash_tree_cache {
     size_t m_used{0};                                  ///< How many entries have already been used
 
     // Statistics
-    std::atomic<uint64_t> m_page_hits{0};         ///\< Number of pages looked up and found in cache
-    std::atomic<uint64_t> m_page_misses{0};       ///\< Number of pages looked up but missing from cache
-    std::atomic<uint64_t> m_word_hits{0};         ///\< Number of words equal to corresponding word in cache entry
-    std::atomic<uint64_t> m_word_misses{0};       ///\< Number of words differing from corresponding word in cache entry
-    std::atomic<uint64_t> m_inner_page_hashes{0}; ///\< Number of inner page hashing operations performed
-    std::atomic<uint64_t> m_pristine_pages{0};    ///\< Number of pages found to be pristine
-    std::atomic<uint64_t> m_non_pristine_pages{0}; ///\< Number of pages found not to be pristine
+    page_hash_tree_cache_stats m_stats;
 };
 
 } // namespace cartesi
diff --git a/src/pristine-merkle-tree.cpp b/src/pristine-merkle-tree.cpp
index ef31d26b4..5ab01aa1a 100644
--- a/src/pristine-merkle-tree.cpp
+++ b/src/pristine-merkle-tree.cpp
@@ -45,9 +45,7 @@ pristine_merkle_tree::pristine_merkle_tree(int log2_root_size, int log2_word_siz
     std::vector<uint8_t> word(1 << log2_word_size, 0);
     assert(word.size() == (UINT64_C(1) << log2_word_size));
     hasher_type h;
-    h.begin();
-    h.add_data(word);
-    h.end(m_hashes[0]);
+    h.hash(word, m_hashes[0]);
     for (unsigned i = 1; i < m_hashes.size(); ++i) {
         get_concat_hash(h, m_hashes[i - 1], m_hashes[i - 1], m_hashes[i]);
     }
diff --git a/src/sha-256-hasher.cpp b/src/sha-256-hasher.cpp
new file mode 100644
index 000000000..b4a19033b
--- /dev/null
+++ b/src/sha-256-hasher.cpp
@@ -0,0 +1,356 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#include "sha-256-hasher.h"
+#include "compiler-defines.h"
+#include "i-hasher.h"
+#include "machine-hash.h"
+#include "simd-vector-type.h"
+
+#include <bit>
+#include <cstddef>
+#include <cstdint>
+#include <span>
+
+namespace cartesi {
+
+// This code is not portable to big-endian architectures.
+// NOLINTNEXTLINE(misc-redundant-expression)
+static_assert(std::endian::native == std::endian::little, "code assumes little-endian byte ordering");
+
+static constexpr size_t SHA256_ROUND_COUNT = 64;
+static constexpr size_t SHA256_STATE_WORD_COUNT = 8;
+static constexpr size_t SHA256_BUF_WORD_COUNT = 16;
+static constexpr size_t SHA256_BUF_SIZE = 64;
+static constexpr size_t SHA256_LENGTH_WORD_INDEX = 14;
+
+template <size_t LaneCount, size_t DataExtent = std::dynamic_extent>
+struct alignas(uint32_vector_type<LaneCount>::align) sha_256_context final {
+    using word_vector_type = uint32_vector_type<LaneCount>::type;
+    using word_bytes_array = uint8_t[SHA256_BUF_WORD_COUNT][LaneCount][sizeof(uint32_t)];
+    using data_span = std::span<const unsigned char, DataExtent>;
+
+    static constexpr size_t word_vector_align = uint32_vector_type<LaneCount>::align;
+
+    word_vector_type m_words[SHA256_BUF_WORD_COUNT]{}; ///< Buffer for SHA-256 words, interleaved by lanes
+    word_vector_type m_state[SHA256_STATE_WORD_COUNT] = {
+        ///< SHA-256 state, interleaved by lanes
+        word_vector_type{} | 0x6a09e667,
+        word_vector_type{} | 0xbb67ae85,
+        word_vector_type{} | 0x3c6ef372,
+        word_vector_type{} | 0xa54ff53a,
+        word_vector_type{} | 0x510e527f,
+        word_vector_type{} | 0x9b05688c,
+        word_vector_type{} | 0x1f83d9ab,
+        word_vector_type{} | 0x5be0cd19,
+    };
+
+    FORCE_INLINE void update(const std::array<data_span, LaneCount> &data, size_t &pos, size_t &len) noexcept {
+        [[maybe_unused]] auto words_bytes = // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+            reinterpret_cast<word_bytes_array &>(m_words);
+        // Assume all data spans have the same length
+        const size_t data_len = data[0].size();
+        for (size_t i = 0; i < data_len;) {
+            // Interleave data
+            const size_t step = std::min(SHA256_BUF_SIZE - pos, data_len - i);
+            if constexpr (DataExtent != std::dynamic_extent && DataExtent % sizeof(uint32_t) == 0) {
+                // If data length is a multiple of word size, process a word at time
+                UNROLL_LOOP(64)
+                for (size_t j = 0; j < step; j += sizeof(uint32_t)) {
+                    word_vector_type data_word;
+                    UNROLL_LOOP_FULL()
+                    for (size_t l = 0; l < LaneCount; ++l) {
+                        uint32_t lane_word{};
+                        __builtin_memcpy(&lane_word, &data[l][i + j], sizeof(lane_word));
+                        data_word[l] = __builtin_bswap32(lane_word);
+                    }
+                    m_words[(pos + j) / sizeof(uint32_t)] = word_vector_type{} | data_word;
+                }
+            } else { // Otherwise, process a byte at time
+                UNROLL_LOOP(64)
+                for (size_t j = 0; j < step; j++) {
+                    const size_t bi = (pos + j) / sizeof(uint32_t);
+                    const size_t bj = sizeof(uint32_t) - 1 - ((pos + j) % sizeof(uint32_t));
+                    UNROLL_LOOP_FULL()
+                    for (size_t l = 0; l < LaneCount; ++l) {
+                        words_bytes[bi][l][bj] = data[l][i + j];
+                    }
+                }
+            }
+            i += step;
+            pos += step;
+            // Perform SHA-256 compression
+            if (pos >= SHA256_BUF_SIZE) [[unlikely]] {
+                compress();
+                len++;
+                pos = 0;
+            }
+        }
+    }
+
+    FORCE_INLINE void finish(const std::array<machine_hash_view, LaneCount> &hashes, size_t pos, size_t len) noexcept {
+        // Pad and append the 1 bit in the last word
+        const size_t bi = pos / sizeof(uint32_t);
+        const size_t bj = sizeof(uint32_t) - 1 - (pos % sizeof(uint32_t));
+        m_words[bi] &= static_cast<uint32_t>(0xffffff00) << (bj * 8);
+        m_words[bi] |= static_cast<uint32_t>(0x00000080) << (bj * 8);
+        // Pad remaining words with zeros
+        UNROLL_LOOP(64)
+        for (size_t x = (pos / sizeof(uint32_t)) + 1; x < SHA256_BUF_WORD_COUNT; ++x) {
+            m_words[x] = word_vector_type{};
+        }
+        // Compress if there is no space left to store the length
+        if (pos >= SHA256_LENGTH_WORD_INDEX * sizeof(uint32_t)) [[unlikely]] {
+            compress();
+            // Clear all words
+            UNROLL_LOOP_FULL()
+            for (size_t x = 0; x < SHA256_BUF_WORD_COUNT; ++x) { // NOLINT(modernize-loop-convert)
+                m_words[x] = word_vector_type{};
+            }
+        }
+        // Store length in the last two words
+        const uint64_t bit_len = ((static_cast<uint64_t>(len) * SHA256_BUF_SIZE) + static_cast<uint64_t>(pos)) * 8;
+        m_words[SHA256_LENGTH_WORD_INDEX + 0] |= static_cast<uint32_t>(bit_len >> 32);
+        m_words[SHA256_LENGTH_WORD_INDEX + 1] |= static_cast<uint32_t>(bit_len);
+        // Perform final compression
+        compress();
+        // Deinterleave hash
+        UNROLL_LOOP_FULL()
+        for (size_t l = 0; l < LaneCount; ++l) {
+            UNROLL_LOOP_FULL()
+            for (size_t i = 0; i < MACHINE_HASH_SIZE; i += sizeof(uint32_t)) {
+                const uint32_t word = __builtin_bswap32(m_state[i / sizeof(uint32_t)][l]);
+                __builtin_memcpy(&hashes[l][i], &word, sizeof(uint32_t));
+            }
+        }
+    }
+
+    template <size_t ConcatCount>
+    FORCE_INLINE static void simd_concat_hash(array2d<data_span, ConcatCount, LaneCount> data,
+        std::array<machine_hash_view, LaneCount> hashes) noexcept {
+        sha_256_context ctx;
+        // Position and length are kept local to allow the compiler optimize them out
+        // when DataExtent is a compile time constant.
+        size_t pos = 0; // Current position in the buffer in bytes
+        size_t len = 0; // Current position in the buffer in 64-byte blocks
+        UNROLL_LOOP(4)
+        for (size_t i = 0; i < ConcatCount; ++i) {
+            ctx.update(data[i], pos, len);
+        }
+        ctx.finish(hashes, pos, len);
+    }
+
+private:
+    FORCE_INLINE void compress() noexcept {
+        // This code is inspired by SHA-256 pseudo-code from Wikipedia:
+        // https://en.wikipedia.org/wiki/SHA-2#Pseudocode
+        // Selected for its simplicity and vectorization-friendly structure.
+        // However it was optimized to use circular buffers in words array to minimize memory bandwidth,
+        // similar how is done in the generic SHA-256 implementation of OpenSSL.
+        alignas(word_vector_align) static constexpr uint32_t SHA256_K[SHA256_ROUND_COUNT] = {0x428a2f98, 0x71374491,
+            0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be,
+            0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc,
+            0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3,
+            0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb,
+            0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585,
+            0x106aa070, 0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+            0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2};
+        // Unfortunately we can't use C++ functions that take vectors as arguments
+        // because according to GCC it would violate ABI rules, so we have to use macros instead.
+        // NOLINTBEGIN(cppcoreguidelines-macro-usage,cppcoreguidelines-macro-to-enum,modernize-macro-to-enum)
+#define SHA256_CH(x, y, z) (((x) & (y)) ^ ((~(x)) & (z)))
+#define SHA256_MAJ(x, y, z) (((x) & (y)) ^ ((x) & (z)) ^ ((y) & (z)))
+#define SHA256_ROR(x, n) (((x) >> (n)) | ((x) << (32 - (n))))
+#define SHA256_S0(x) (SHA256_ROR(x, 2) ^ SHA256_ROR(x, 13) ^ SHA256_ROR(x, 22))
+#define SHA256_S1(x) (SHA256_ROR(x, 6) ^ SHA256_ROR(x, 11) ^ SHA256_ROR(x, 25))
+#define SHA256_G0(x) (SHA256_ROR(x, 7) ^ SHA256_ROR(x, 18) ^ ((x) >> 3))
+#define SHA256_G1(x) (SHA256_ROR(x, 17) ^ SHA256_ROR(x, 19) ^ ((x) >> 10))
+#define SHA256_WI(i, k) (((i) - (k)) & 15) // Circular buffer index for words
+#define SHA256_SI(i, k) (((k) - (i)) & 7)  // Circular buffer index for state
+        // NOLINTEND(cppcoreguidelines-macro-usage,cppcoreguidelines-macro-to-enum,modernize-macro-to-enum)
+        // Load state
+        word_vector_type s[8]{m_state[0], m_state[1], m_state[2], m_state[3], m_state[4], m_state[5], m_state[6],
+            m_state[7]};
+        word_vector_type w[16];
+        // Perform SHA-256 rounds
+        UNROLL_LOOP_FULL()
+        for (size_t r = 0; r < SHA256_ROUND_COUNT; r++) {
+            const size_t i = r % 16;
+            const size_t j = r - i;
+            if (j == 0) {
+                w[i] = m_words[i];
+            } else {
+                w[i] += SHA256_G1(w[SHA256_WI(i, 2)]) + w[SHA256_WI(i, 7)] + SHA256_G0(w[SHA256_WI(i, 15)]);
+            }
+            s[SHA256_SI(i, 7)] += w[i] + SHA256_S1(s[SHA256_SI(i, 4)]) +
+                SHA256_CH(s[SHA256_SI(i, 4)], s[SHA256_SI(i, 5)], s[SHA256_SI(i, 6)]) + SHA256_K[i + j];
+            s[SHA256_SI(i, 3)] += s[SHA256_SI(i, 7)];
+            s[SHA256_SI(i, 7)] +=
+                SHA256_S0(s[SHA256_SI(i, 0)]) + SHA256_MAJ(s[SHA256_SI(i, 0)], s[SHA256_SI(i, 1)], s[SHA256_SI(i, 2)]);
+        }
+        // Store state
+        UNROLL_LOOP_FULL()
+        for (size_t i = 0; i < SHA256_STATE_WORD_COUNT; ++i) {
+            m_state[i] += s[i];
+        }
+    }
+};
+
+// Generic implementations
+
+MULTIVERSION_GENERIC size_t sha_256_get_optimal_lane_count() noexcept {
+#if defined(__x86_64__)
+    // On AMD64, SSE2 has 128-bit registers, supporting up to 4 lanes.
+    return 4;
+#elif defined(__aarch64__)
+    // On ARM64, NEON has 128-bit registers, supporting up to 4 lanes.
+    return 4;
+#elif defined(__riscv) && defined(__riscv_v)
+    // RISC-V with Vector extension, we assume 128-bit registers are available, supporting up to 4 lanes.
+    return 4;
+#elif defined(__wasm_simd128__)
+    // WebAssembly with SIMD extension has 128-bit registers, supporting up to 4 lanes.
+    return 4;
+#else
+    // For other architectures, we assume vector instructions are not available and use scalar implementation.
+    return 1;
+#endif
+}
+MULTIVERSION_GENERIC void sha_256_data_1x1(const array2d<std::span<const unsigned char>, 1, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept {
+    sha_256_context<1>::simd_concat_hash<1>(data, hash);
+}
+MULTIVERSION_GENERIC void sha_256_word_1x1(const array2d<const_hash_tree_word_view, 1, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept {
+    sha_256_context<1, const_hash_tree_word_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_GENERIC void sha_256_word_1x2(const array2d<const_hash_tree_word_view, 1, 2> &data,
+    const std::array<machine_hash_view, 2> &hash) noexcept {
+    sha_256_context<2, const_hash_tree_word_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_GENERIC void sha_256_word_1x4(const array2d<const_hash_tree_word_view, 1, 4> &data,
+    const std::array<machine_hash_view, 4> &hash) noexcept {
+    sha_256_context<4, const_hash_tree_word_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_GENERIC void sha_256_word_1x8(const array2d<const_hash_tree_word_view, 1, 8> &data,
+    const std::array<machine_hash_view, 8> &hash) noexcept {
+    sha_256_context<8, const_hash_tree_word_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_GENERIC void sha_256_word_1x16(const array2d<const_hash_tree_word_view, 1, 16> &data,
+    const std::array<machine_hash_view, 16> &hash) noexcept {
+    sha_256_context<16, const_hash_tree_word_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_GENERIC void sha_256_data_2x1(const array2d<std::span<const unsigned char>, 2, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept {
+    sha_256_context<1>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_GENERIC void sha_256_hash_2x1(const array2d<const_machine_hash_view, 2, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept {
+    sha_256_context<1, const_machine_hash_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_GENERIC void sha_256_hash_2x2(const array2d<const_machine_hash_view, 2, 2> &data,
+    const std::array<machine_hash_view, 2> &hash) noexcept {
+    sha_256_context<2, const_machine_hash_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_GENERIC void sha_256_hash_2x4(const array2d<const_machine_hash_view, 2, 4> &data,
+    const std::array<machine_hash_view, 4> &hash) noexcept {
+    sha_256_context<4, const_machine_hash_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_GENERIC void sha_256_hash_2x8(const array2d<const_machine_hash_view, 2, 8> &data,
+    const std::array<machine_hash_view, 8> &hash) noexcept {
+    sha_256_context<8, const_machine_hash_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_GENERIC void sha_256_hash_2x16(const array2d<const_machine_hash_view, 2, 16> &data,
+    const std::array<machine_hash_view, 16> &hash) noexcept {
+    sha_256_context<16, const_machine_hash_view::extent>::simd_concat_hash(data, hash);
+}
+
+// x86_64 implementations
+
+#ifdef USE_MULTIVERSINING_AMD64
+
+// AVX2
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 size_t sha_256_get_optimal_lane_count() noexcept {
+    // AVX2 has 256-bit registers, supporting up to 8 lanes.
+    return 8;
+}
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void sha_256_data_1x1(const array2d<std::span<const unsigned char>, 1, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept {
+    sha_256_context<1>::simd_concat_hash<1>(data, hash);
+}
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void sha_256_word_1x1(const array2d<const_hash_tree_word_view, 1, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept {
+    sha_256_context<1, const_hash_tree_word_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void sha_256_word_1x2(const array2d<const_hash_tree_word_view, 1, 2> &data,
+    const std::array<machine_hash_view, 2> &hash) noexcept {
+    sha_256_context<2, const_hash_tree_word_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void sha_256_word_1x4(const array2d<const_hash_tree_word_view, 1, 4> &data,
+    const std::array<machine_hash_view, 4> &hash) noexcept {
+    sha_256_context<4, const_hash_tree_word_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void sha_256_word_1x8(const array2d<const_hash_tree_word_view, 1, 8> &data,
+    const std::array<machine_hash_view, 8> &hash) noexcept {
+    sha_256_context<8, const_hash_tree_word_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void sha_256_word_1x16(const array2d<const_hash_tree_word_view, 1, 16> &data,
+    const std::array<machine_hash_view, 16> &hash) noexcept {
+    sha_256_context<16, const_hash_tree_word_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void sha_256_data_2x1(const array2d<std::span<const unsigned char>, 2, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept {
+    sha_256_context<1>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void sha_256_hash_2x1(const array2d<const_machine_hash_view, 2, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept {
+    sha_256_context<1, const_machine_hash_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void sha_256_hash_2x2(const array2d<const_machine_hash_view, 2, 2> &data,
+    const std::array<machine_hash_view, 2> &hash) noexcept {
+    sha_256_context<2, const_machine_hash_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void sha_256_hash_2x4(const array2d<const_machine_hash_view, 2, 4> &data,
+    const std::array<machine_hash_view, 4> &hash) noexcept {
+    sha_256_context<4, const_machine_hash_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void sha_256_hash_2x8(const array2d<const_machine_hash_view, 2, 8> &data,
+    const std::array<machine_hash_view, 8> &hash) noexcept {
+    sha_256_context<8, const_machine_hash_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void sha_256_hash_2x16(const array2d<const_machine_hash_view, 2, 16> &data,
+    const std::array<machine_hash_view, 16> &hash) noexcept {
+    sha_256_context<16, const_machine_hash_view::extent>::simd_concat_hash(data, hash);
+}
+
+// AVX-512
+
+MULTIVERSION_AMD64_AVX512_BMI_BMI2 size_t sha_256_get_optimal_lane_count() noexcept {
+    // AVX-512 has 512-bit registers, supporting up to 16 lanes.
+    return 16;
+}
+MULTIVERSION_AMD64_AVX512_BMI_BMI2 void sha_256_word_1x16(const array2d<const_hash_tree_word_view, 1, 16> &data,
+    const std::array<machine_hash_view, 16> &hash) noexcept {
+    sha_256_context<16, const_hash_tree_word_view::extent>::simd_concat_hash(data, hash);
+}
+MULTIVERSION_AMD64_AVX512_BMI_BMI2 void sha_256_hash_2x16(const array2d<const_machine_hash_view, 2, 16> &data,
+    const std::array<machine_hash_view, 16> &hash) noexcept {
+    sha_256_context<16, const_machine_hash_view::extent>::simd_concat_hash(data, hash);
+}
+
+#endif // USE_MULTIVERSINING_AMD64
+
+} // namespace cartesi
diff --git a/src/sha-256-hasher.h b/src/sha-256-hasher.h
new file mode 100644
index 000000000..527436609
--- /dev/null
+++ b/src/sha-256-hasher.h
@@ -0,0 +1,202 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef SHA_256_HASHER_H
+#define SHA_256_HASHER_H
+
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <span>
+#include <type_traits>
+
+#include "array2d.h"
+#include "compiler-defines.h"
+#include "i-hasher.h"
+#include "machine-hash.h"
+
+namespace cartesi {
+
+// Generic implementations
+MULTIVERSION_GENERIC size_t sha_256_get_optimal_lane_count() noexcept;
+MULTIVERSION_GENERIC void sha_256_data_1x1(const array2d<std::span<const unsigned char>, 1, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept;
+MULTIVERSION_GENERIC void sha_256_word_1x1(const array2d<const_hash_tree_word_view, 1, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept;
+MULTIVERSION_GENERIC void sha_256_word_1x2(const array2d<const_hash_tree_word_view, 1, 2> &data,
+    const std::array<machine_hash_view, 2> &hash) noexcept;
+MULTIVERSION_GENERIC void sha_256_word_1x4(const array2d<const_hash_tree_word_view, 1, 4> &data,
+    const std::array<machine_hash_view, 4> &hash) noexcept;
+MULTIVERSION_GENERIC void sha_256_word_1x8(const array2d<const_hash_tree_word_view, 1, 8> &data,
+    const std::array<machine_hash_view, 8> &hash) noexcept;
+MULTIVERSION_GENERIC void sha_256_word_1x16(const array2d<const_hash_tree_word_view, 1, 16> &data,
+    const std::array<machine_hash_view, 16> &hash) noexcept;
+MULTIVERSION_GENERIC void sha_256_data_2x1(const array2d<std::span<const unsigned char>, 2, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept;
+MULTIVERSION_GENERIC void sha_256_hash_2x1(const array2d<const_machine_hash_view, 2, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept;
+MULTIVERSION_GENERIC void sha_256_hash_2x2(const array2d<const_machine_hash_view, 2, 2> &data,
+    const std::array<machine_hash_view, 2> &hash) noexcept;
+MULTIVERSION_GENERIC void sha_256_hash_2x4(const array2d<const_machine_hash_view, 2, 4> &data,
+    const std::array<machine_hash_view, 4> &hash) noexcept;
+MULTIVERSION_GENERIC void sha_256_hash_2x8(const array2d<const_machine_hash_view, 2, 8> &data,
+    const std::array<machine_hash_view, 8> &hash) noexcept;
+MULTIVERSION_GENERIC void sha_256_hash_2x16(const array2d<const_machine_hash_view, 2, 16> &data,
+    const std::array<machine_hash_view, 16> &hash) noexcept;
+
+// Optimized implementation for x86_64 architecture leveraging modern CPU instruction sets:
+// - BMI1/BMI2 (Bit Manipulation Instructions) provide specialized bit operations:
+//   * RORX performs optimized bitwise rotation without requiring separate shift operations
+//   * ANDN efficiently computes (~x & y) in a single instruction
+// - AVX2 for x8 SIMD hashing
+// - AVX-512 for x16 SIMD hashing
+#ifdef USE_MULTIVERSINING_AMD64
+// AVX2 implementation for x1, x2, x4, x8, x16 SIMD hashing
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 size_t sha_256_get_optimal_lane_count() noexcept;
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void sha_256_data_1x1(const array2d<std::span<const unsigned char>, 1, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept;
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void sha_256_word_1x1(const array2d<const_hash_tree_word_view, 1, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept;
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void sha_256_word_1x2(const array2d<const_hash_tree_word_view, 1, 2> &data,
+    const std::array<machine_hash_view, 2> &hash) noexcept;
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void sha_256_word_1x4(const array2d<const_hash_tree_word_view, 1, 4> &data,
+    const std::array<machine_hash_view, 4> &hash) noexcept;
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void sha_256_word_1x8(const array2d<const_hash_tree_word_view, 1, 8> &data,
+    const std::array<machine_hash_view, 8> &hash) noexcept;
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void sha_256_word_1x16(const array2d<const_hash_tree_word_view, 1, 16> &data,
+    const std::array<machine_hash_view, 16> &hash) noexcept;
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void sha_256_data_2x1(const array2d<std::span<const unsigned char>, 2, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept;
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void sha_256_hash_2x1(const array2d<const_machine_hash_view, 2, 1> &data,
+    const std::array<machine_hash_view, 1> &hash) noexcept;
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void sha_256_hash_2x2(const array2d<const_machine_hash_view, 2, 2> &data,
+    const std::array<machine_hash_view, 2> &hash) noexcept;
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void sha_256_hash_2x4(const array2d<const_machine_hash_view, 2, 4> &data,
+    const std::array<machine_hash_view, 4> &hash) noexcept;
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void sha_256_hash_2x8(const array2d<const_machine_hash_view, 2, 8> &data,
+    const std::array<machine_hash_view, 8> &hash) noexcept;
+MULTIVERSION_AMD64_AVX2_BMI_BMI2 void sha_256_hash_2x16(const array2d<const_machine_hash_view, 2, 16> &data,
+    const std::array<machine_hash_view, 16> &hash) noexcept;
+// AVX-512 implementation for x16 SIMD hashing
+MULTIVERSION_AMD64_AVX512_BMI_BMI2 size_t sha_256_get_optimal_lane_count() noexcept;
+MULTIVERSION_AMD64_AVX512_BMI_BMI2 void sha_256_word_1x16(const array2d<const_hash_tree_word_view, 1, 16> &data,
+    const std::array<machine_hash_view, 16> &hash) noexcept;
+MULTIVERSION_AMD64_AVX512_BMI_BMI2 void sha_256_hash_2x16(const array2d<const_machine_hash_view, 2, 16> &data,
+    const std::array<machine_hash_view, 16> &hash) noexcept;
+#endif
+
+class sha_256_hasher final : public i_hasher<sha_256_hasher> {
+public:
+    static constexpr int MAX_LANE_COUNT = 16; ///< Number of maximum supported SIMD lanes
+
+    /// \brief Default constructor
+    sha_256_hasher() = default;
+
+    /// \brief Default destructor
+    ~sha_256_hasher() = default;
+
+    /// \brief No copy constructor
+    sha_256_hasher(const sha_256_hasher &) = delete;
+    /// \brief No move constructor
+    sha_256_hasher(sha_256_hasher &&) = delete;
+    /// \brief No copy assignment
+    sha_256_hasher &operator=(const sha_256_hasher &) = delete;
+    /// \brief No move assignment
+    sha_256_hasher &operator=(sha_256_hasher &&) = delete;
+
+    // \brief Hashes the concatenation of data in SIMD using SHA-256
+    // \tparam LaneCount Number of SIMD lanes
+    // \tparam ConcatCount Number of concatenated data items
+    // \tparam Extent Extent of the data span
+    // \param data Data to hash, as a multi-dimensional array of spans
+    // \param hash Array of machine hashes to store the results
+    // \warning When LaneCount is greater than 1, it is assumed data spans have same size, there is no check for that.
+    template <size_t ConcatCount, size_t LaneCount, size_t Extent>
+    static void do_simd_concat_hash(const array2d<std::span<const unsigned char, Extent>, ConcatCount, LaneCount> &data,
+        const std::array<machine_hash_view, LaneCount> &hash) noexcept;
+
+    // \brief Gets the optimal number of SIMD lanes for SHA-256
+    // \returns The optimal number of SIMD lanes for SHA-256
+    // \details This value is architecture-dependent and may vary based on the available instruction sets.
+    static size_t do_get_optimal_lane_count() noexcept {
+        return sha_256_get_optimal_lane_count();
+    }
+};
+
+template <>
+inline void sha_256_hasher::do_simd_concat_hash<1, 1, std::dynamic_extent>(
+    const array2d<std::span<const unsigned char>, 1, 1> &data, const std::array<machine_hash_view, 1> &hash) noexcept {
+    sha_256_data_1x1(data, hash);
+}
+template <>
+inline void sha_256_hasher::do_simd_concat_hash<1, 1, HASH_TREE_WORD_SIZE>(
+    const array2d<const_hash_tree_word_view, 1, 1> &data, const std::array<machine_hash_view, 1> &hash) noexcept {
+    sha_256_word_1x1(data, hash);
+}
+template <>
+inline void sha_256_hasher::do_simd_concat_hash<1, 2, HASH_TREE_WORD_SIZE>(
+    const array2d<const_hash_tree_word_view, 1, 2> &data, const std::array<machine_hash_view, 2> &hash) noexcept {
+    sha_256_word_1x2(data, hash);
+}
+template <>
+inline void sha_256_hasher::do_simd_concat_hash<1, 4, HASH_TREE_WORD_SIZE>(
+    const array2d<const_hash_tree_word_view, 1, 4> &data, const std::array<machine_hash_view, 4> &hash) noexcept {
+    sha_256_word_1x4(data, hash);
+}
+template <>
+inline void sha_256_hasher::do_simd_concat_hash<1, 8, HASH_TREE_WORD_SIZE>(
+    const array2d<const_hash_tree_word_view, 1, 8> &data, const std::array<machine_hash_view, 8> &hash) noexcept {
+    sha_256_word_1x8(data, hash);
+}
+template <>
+inline void sha_256_hasher::do_simd_concat_hash<1, 16, HASH_TREE_WORD_SIZE>(
+    const array2d<const_hash_tree_word_view, 1, 16> &data, const std::array<machine_hash_view, 16> &hash) noexcept {
+    sha_256_word_1x16(data, hash);
+}
+template <>
+inline void sha_256_hasher::do_simd_concat_hash<2, 1, std::dynamic_extent>(
+    const array2d<std::span<const unsigned char>, 2, 1> &data, const std::array<machine_hash_view, 1> &hash) noexcept {
+    sha_256_data_2x1(data, hash);
+}
+template <>
+inline void sha_256_hasher::do_simd_concat_hash<2, 1, MACHINE_HASH_SIZE>(
+    const array2d<const_machine_hash_view, 2, 1> &data, const std::array<machine_hash_view, 1> &hash) noexcept {
+    sha_256_hash_2x1(data, hash);
+}
+template <>
+inline void sha_256_hasher::do_simd_concat_hash<2, 2, MACHINE_HASH_SIZE>(
+    const array2d<const_machine_hash_view, 2, 2> &data, const std::array<machine_hash_view, 2> &hash) noexcept {
+    sha_256_hash_2x2(data, hash);
+}
+template <>
+inline void sha_256_hasher::do_simd_concat_hash<2, 4, MACHINE_HASH_SIZE>(
+    const array2d<const_machine_hash_view, 2, 4> &data, const std::array<machine_hash_view, 4> &hash) noexcept {
+    sha_256_hash_2x4(data, hash);
+}
+template <>
+inline void sha_256_hasher::do_simd_concat_hash<2, 8, MACHINE_HASH_SIZE>(
+    const array2d<const_machine_hash_view, 2, 8> &data, const std::array<machine_hash_view, 8> &hash) noexcept {
+    sha_256_hash_2x8(data, hash);
+}
+template <>
+inline void sha_256_hasher::do_simd_concat_hash<2, 16, MACHINE_HASH_SIZE>(
+    const array2d<const_machine_hash_view, 2, 16> &data, const std::array<machine_hash_view, 16> &hash) noexcept {
+    sha_256_hash_2x16(data, hash);
+}
+
+} // namespace cartesi
+
+#endif
diff --git a/src/simd-hasher.h b/src/simd-hasher.h
new file mode 100644
index 000000000..01353152b
--- /dev/null
+++ b/src/simd-hasher.h
@@ -0,0 +1,357 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef SIMD_HASHER_H
+#define SIMD_HASHER_H
+
+/// \file
+/// \brief SIMD hasher interface
+///
+/// This file provides template classes for SIMD-accelerated hashing operations.
+/// It includes specialized hashers for single data items and concatenated data pairs,
+/// both utilizing queue-based batching to maximize SIMD efficiency.
+
+#include <cstddef>
+
+#include <boost/container/static_vector.hpp>
+
+#include "compiler-defines.h"
+#include "i-hasher.h"
+#include "machine-hash.h"
+
+namespace cartesi {
+
+/// \brief SIMD-accelerated data hasher with queue-based batching
+/// \tparam hasher_type The underlying SIMD hasher implementation
+/// \tparam data_type The type of data to be hashed
+/// \tparam MaxQueueSize Maximum number of items that can be queued (defaults to hasher's max lane count)
+template <typename hasher_type, typename data_type, size_t MaxQueueSize = hasher_type::MAX_LANE_COUNT>
+class simd_data_hasher {
+    struct data_entry {
+        data_type data;           ///< Data to be hashed
+        machine_hash_view result; ///< View where the hash result will be stored
+    };
+
+    hasher_type m_hasher;                                                ///< The underlying SIMD hasher instance
+    boost::container::static_vector<data_entry, MaxQueueSize> m_queue{}; ///< Queue of pending hash operations
+
+public:
+    /// \brief Enqueues data for hashing
+    /// \param data Data to hash
+    /// \param result Receives the hash of data
+    /// \details If the queue reaches the optimal size, it is automatically flushed.
+    void enqueue(data_type data, machine_hash_view result) noexcept {
+        m_queue.emplace_back(data_entry{.data = data, .result = result});
+        static const size_t optimal_queue_size = std::min(MaxQueueSize, hasher_type::get_optimal_lane_count());
+        if (m_queue.size() >= optimal_queue_size) [[unlikely]] { // Queue is full, auto flush it
+            flush();
+        }
+    }
+
+    /// \brief Flushes the queue, clearing it in the process
+    void flush() noexcept {
+        auto &q = m_queue;
+        size_t i = q.size();
+        if constexpr (hasher_type::MAX_LANE_COUNT >= 16) {
+            while (i >= 16) { // x16 parallel hashing
+                i -= 16;
+                m_hasher.simd_concat_hash(array2d<data_type, 1, 16>{{{
+                                              q[i + 0].data,
+                                              q[i + 1].data,
+                                              q[i + 2].data,
+                                              q[i + 3].data,
+                                              q[i + 4].data,
+                                              q[i + 5].data,
+                                              q[i + 6].data,
+                                              q[i + 7].data,
+                                              q[i + 8].data,
+                                              q[i + 9].data,
+                                              q[i + 10].data,
+                                              q[i + 11].data,
+                                              q[i + 12].data,
+                                              q[i + 13].data,
+                                              q[i + 14].data,
+                                              q[i + 15].data,
+                                          }}},
+                    std::array<machine_hash_view, 16>{{
+                        q[i + 0].result,
+                        q[i + 1].result,
+                        q[i + 2].result,
+                        q[i + 3].result,
+                        q[i + 4].result,
+                        q[i + 5].result,
+                        q[i + 6].result,
+                        q[i + 7].result,
+                        q[i + 8].result,
+                        q[i + 9].result,
+                        q[i + 10].result,
+                        q[i + 11].result,
+                        q[i + 12].result,
+                        q[i + 13].result,
+                        q[i + 14].result,
+                        q[i + 15].result,
+                    }});
+            }
+        }
+        while (i >= 8) { // x8 parallel hashing
+            i -= 8;
+            m_hasher.simd_concat_hash(array2d<data_type, 1, 8>{{{
+                                          q[i + 0].data,
+                                          q[i + 1].data,
+                                          q[i + 2].data,
+                                          q[i + 3].data,
+                                          q[i + 4].data,
+                                          q[i + 5].data,
+                                          q[i + 6].data,
+                                          q[i + 7].data,
+                                      }}},
+                std::array<machine_hash_view, 8>{{
+                    q[i + 0].result,
+                    q[i + 1].result,
+                    q[i + 2].result,
+                    q[i + 3].result,
+                    q[i + 4].result,
+                    q[i + 5].result,
+                    q[i + 6].result,
+                    q[i + 7].result,
+                }});
+        }
+        if (i >= 4) { // x4 parallel hashing
+            i -= 4;
+            m_hasher.simd_concat_hash(array2d<data_type, 1, 4>{{{
+                                          q[i + 0].data,
+                                          q[i + 1].data,
+                                          q[i + 2].data,
+                                          q[i + 3].data,
+                                      }}},
+                std::array<machine_hash_view, 4>{{
+                    q[i + 0].result,
+                    q[i + 1].result,
+                    q[i + 2].result,
+                    q[i + 3].result,
+                }});
+        }
+        if (i >= 2) { // x2 parallel hashing
+            i -= 2;
+            m_hasher.simd_concat_hash(array2d<data_type, 1, 2>{{{
+                                          q[i + 0].data,
+                                          q[i + 1].data,
+                                      }}},
+                std::array<machine_hash_view, 2>{{
+                    q[i + 0].result,
+                    q[i + 1].result,
+                }});
+        }
+        if (i >= 1) { // x1 scalar hashing
+            i -= 1;
+            m_hasher.simd_concat_hash(array2d<data_type, 1, 1>{{
+                                          {q[i + 0].data},
+                                      }},
+                std::array<machine_hash_view, 1>{
+                    {q[i + 0].result},
+                });
+        }
+        q.clear();
+    }
+};
+
+/// \brief SIMD-accelerated concatenation hasher with queue-based batching
+/// \tparam hasher_type The underlying SIMD hasher implementation
+/// \tparam data_type The type of data to be hashed
+/// \tparam MaxQueueSize Maximum number of pairs that can be queued (defaults to hasher's max lane count)
+template <typename hasher_type, typename data_type, size_t MaxQueueSize = hasher_type::MAX_LANE_COUNT>
+class simd_concat_hasher {
+    struct concat_entry {
+        data_type left;           ///< Left data to be concatenated and hashed
+        data_type right;          ///< Right data to be concatenated and hashed
+        machine_hash_view result; ///< View where the hash result will be stored
+    };
+
+    hasher_type m_hasher; ///< The underlying SIMD hasher instance
+    boost::container::static_vector<concat_entry, MaxQueueSize>
+        m_queue{}; ///< Queue of pending concatenation hash operations
+
+public:
+    /// \brief Enqueues data pair for concat hashing
+    /// \param left Left data to hash
+    /// \param right Right data to hash
+    /// \param result Receives the hash of concatenated data
+    /// \details If the queue reaches the optimal size, it is automatically flushed.
+    void enqueue(data_type left, data_type right, machine_hash_view result) noexcept {
+        m_queue.emplace_back(concat_entry{.left = left, .right = right, .result = result});
+        static const size_t optimal_queue_size = std::min(MaxQueueSize, hasher_type::get_optimal_lane_count());
+        if (m_queue.size() >= optimal_queue_size) [[unlikely]] { // Queue is full, auto flush it
+            flush();
+        }
+    }
+
+    /// \brief Flushes the queue, clearing it in the process
+    void flush() noexcept {
+        auto &q = m_queue;
+        size_t i = q.size();
+        if constexpr (hasher_type::MAX_LANE_COUNT >= 16) {
+            while (i >= 16) { // x16 parallel hashing
+                i -= 16;
+                m_hasher.simd_concat_hash(array2d<data_type, 2, 16>{{
+                                              {
+                                                  q[i + 0].left,
+                                                  q[i + 1].left,
+                                                  q[i + 2].left,
+                                                  q[i + 3].left,
+                                                  q[i + 4].left,
+                                                  q[i + 5].left,
+                                                  q[i + 6].left,
+                                                  q[i + 7].left,
+                                                  q[i + 8].left,
+                                                  q[i + 9].left,
+                                                  q[i + 10].left,
+                                                  q[i + 11].left,
+                                                  q[i + 12].left,
+                                                  q[i + 13].left,
+                                                  q[i + 14].left,
+                                                  q[i + 15].left,
+                                              },
+                                              {
+                                                  q[i + 0].right,
+                                                  q[i + 1].right,
+                                                  q[i + 2].right,
+                                                  q[i + 3].right,
+                                                  q[i + 4].right,
+                                                  q[i + 5].right,
+                                                  q[i + 6].right,
+                                                  q[i + 7].right,
+                                                  q[i + 8].right,
+                                                  q[i + 9].right,
+                                                  q[i + 10].right,
+                                                  q[i + 11].right,
+                                                  q[i + 12].right,
+                                                  q[i + 13].right,
+                                                  q[i + 14].right,
+                                                  q[i + 15].right,
+                                              },
+                                          }},
+                    std::array<machine_hash_view, 16>{
+                        q[i + 0].result,
+                        q[i + 1].result,
+                        q[i + 2].result,
+                        q[i + 3].result,
+                        q[i + 4].result,
+                        q[i + 5].result,
+                        q[i + 6].result,
+                        q[i + 7].result,
+                        q[i + 8].result,
+                        q[i + 9].result,
+                        q[i + 10].result,
+                        q[i + 11].result,
+                        q[i + 12].result,
+                        q[i + 13].result,
+                        q[i + 14].result,
+                        q[i + 15].result,
+                    });
+            }
+        }
+        while (i >= 8) { // x8 parallel hashing
+            i -= 8;
+            m_hasher.simd_concat_hash(array2d<data_type, 2, 8>{{
+                                          {
+                                              q[i + 0].left,
+                                              q[i + 1].left,
+                                              q[i + 2].left,
+                                              q[i + 3].left,
+                                              q[i + 4].left,
+                                              q[i + 5].left,
+                                              q[i + 6].left,
+                                              q[i + 7].left,
+                                          },
+                                          {
+                                              q[i + 0].right,
+                                              q[i + 1].right,
+                                              q[i + 2].right,
+                                              q[i + 3].right,
+                                              q[i + 4].right,
+                                              q[i + 5].right,
+                                              q[i + 6].right,
+                                              q[i + 7].right,
+                                          },
+                                      }},
+                std::array<machine_hash_view, 8>{
+                    q[i + 0].result,
+                    q[i + 1].result,
+                    q[i + 2].result,
+                    q[i + 3].result,
+                    q[i + 4].result,
+                    q[i + 5].result,
+                    q[i + 6].result,
+                    q[i + 7].result,
+                });
+        }
+        if (i >= 4) { // x4 parallel hashing
+            i -= 4;
+            m_hasher.simd_concat_hash(array2d<data_type, 2, 4>{{
+                                          {
+                                              q[i + 0].left,
+                                              q[i + 1].left,
+                                              q[i + 2].left,
+                                              q[i + 3].left,
+                                          },
+                                          {
+                                              q[i + 0].right,
+                                              q[i + 1].right,
+                                              q[i + 2].right,
+                                              q[i + 3].right,
+                                          },
+                                      }},
+                std::array<machine_hash_view, 4>{
+                    q[i + 0].result,
+                    q[i + 1].result,
+                    q[i + 2].result,
+                    q[i + 3].result,
+                });
+        }
+        if (i >= 2) { // x2 parallel hashing
+            i -= 2;
+            m_hasher.simd_concat_hash(array2d<data_type, 2, 2>{{
+                                          {
+                                              q[i + 0].left,
+                                              q[i + 1].left,
+                                          },
+                                          {
+                                              q[i + 0].right,
+                                              q[i + 1].right,
+                                          },
+                                      }},
+                std::array<machine_hash_view, 2>{
+                    q[i + 0].result,
+                    q[i + 1].result,
+                });
+        }
+        if (i >= 1) { // x1 scalar hashing
+            i -= 1;
+            m_hasher.simd_concat_hash(array2d<data_type, 2, 1>{{
+                                          {q[i + 0].left},
+                                          {q[i + 0].right},
+                                      }},
+                std::array<machine_hash_view, 1>{{
+                    q[i + 0].result,
+                }});
+        }
+        q.clear();
+    }
+};
+
+} // namespace cartesi
+
+#endif // SIMD_HASHER_H
diff --git a/src/simd-vector-type.h b/src/simd-vector-type.h
new file mode 100644
index 000000000..d8e107f40
--- /dev/null
+++ b/src/simd-vector-type.h
@@ -0,0 +1,114 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+/// \file simd_vector_type.h
+/// \brief Defines SIMD vector type traits for uint64_t and uint32_t operations
+///
+/// This header provides template specializations that map lane counts to appropriate
+/// SIMD vector types with their corresponding alignment requirements.
+/// It supports both scalar (single lane) and vector operations for efficient SIMD computations.
+
+#ifndef SIMD_VECTOR_TYPE
+#define SIMD_VECTOR_TYPE
+
+#include <cstddef>
+#include <cstdint>
+
+namespace cartesi {
+
+/// \brief Template struct to define uint64_t vector types based on lane count
+/// \tparam LaneCount Number of 64-bit lanes in the vector
+template <size_t LaneCount>
+struct uint64_vector_type;
+
+/// \brief Specialization for single uint64_t value (1 lane)
+template <>
+struct uint64_vector_type<1> {
+    using type = uint64_t __attribute__((vector_size(8))); ///< Scalar uint64_t type
+    static constexpr size_t align = 16;                    ///< Recommended memory alignment requirement
+};
+
+/// \brief Specialization for 2-lane uint64_t vector (128-bit)
+template <>
+struct uint64_vector_type<2> {
+    using type = uint64_t __attribute__((vector_size(16))); ///< 2x64-bit vector type
+    static constexpr size_t align = 16;                     ///< Recommended memory alignment requirement
+};
+
+/// \brief Specialization for 4-lane uint64_t vector (256-bit)
+template <>
+struct uint64_vector_type<4> {
+    using type = uint64_t __attribute__((vector_size(32))); ///< 4x64-bit vector type
+    static constexpr size_t align = 32;                     ///< Recommended memory alignment requirement
+};
+
+/// \brief Specialization for 8-lane uint64_t vector (512-bit)
+template <>
+struct uint64_vector_type<8> {
+    using type = uint64_t __attribute__((vector_size(64))); ///< 8x64-bit vector type
+    static constexpr size_t align = 64;                     ///< Recommended memory alignment requirement
+};
+
+/// \brief Specialization for 16-lane uint64_t vector (1024-bit)
+template <>
+struct uint64_vector_type<16> {
+    using type = uint64_t __attribute__((vector_size(128))); ///< 16x64-bit vector type
+    static constexpr size_t align = 128;                     ///< Recommended memory alignment requirement
+};
+
+/// \brief Template struct to define uint32_t vector types based on lane count
+/// \tparam LaneCount Number of 32-bit lanes in the vector
+template <size_t LaneCount>
+struct uint32_vector_type;
+
+/// \brief Specialization for single uint32_t value (1 lane)
+template <>
+struct uint32_vector_type<1> {
+    using type = uint32_t __attribute__((vector_size(4))); ///< Scalar uint32_t type
+    static constexpr size_t align = 16;                    ///< Recommended memory alignment requirement
+};
+
+/// \brief Specialization for 2-lane uint32_t vector (64-bit)
+template <>
+struct uint32_vector_type<2> {
+    using type = uint32_t __attribute__((vector_size(8))); ///< 2x32-bit vector type
+    static constexpr size_t align = 16;                    ///< Recommended memory alignment requirement
+};
+
+/// \brief Specialization for 4-lane uint32_t vector (128-bit)
+template <>
+struct uint32_vector_type<4> {
+    using type = uint32_t __attribute__((vector_size(16))); ///< 4x32-bit vector type
+    static constexpr size_t align = 16;                     ///< Recommended memory alignment requirement
+};
+
+/// \brief Specialization for 8-lane uint32_t vector (256-bit)
+template <>
+struct uint32_vector_type<8> {
+    using type = uint32_t __attribute__((vector_size(32))); ///< 8x32-bit vector type
+    static constexpr size_t align = 32;                     ///< Recommended memory alignment requirement
+};
+
+/// \brief Specialization for 16-lane uint32_t vector (512-bit)
+template <>
+struct uint32_vector_type<16> {
+    using type = uint32_t __attribute__((vector_size(64))); ///< 16x32-bit vector type
+    static constexpr size_t align = 64;                     ///< Recommended memory alignment requirement
+};
+
+} // namespace cartesi
+
+#endif
diff --git a/tests/lua/cartesi/tests/util.lua b/tests/lua/cartesi/tests/util.lua
index b5398d0f7..aae0d200a 100644
--- a/tests/lua/cartesi/tests/util.lua
+++ b/tests/lua/cartesi/tests/util.lua
@@ -38,10 +38,10 @@ local zero_keccak_hash_table = {
 }
 
 do
-    local hash = cartesi.keccak(string.rep("\0", 1 << WORD_LOG2_SIZE))
+    local hash = cartesi.keccak256(string.rep("\0", 1 << WORD_LOG2_SIZE))
     for i = WORD_LOG2_SIZE, ROOT_LOG2_SIZE - 1 do
         zero_keccak_hash_table[i] = hash
-        hash = cartesi.keccak(hash, hash)
+        hash = cartesi.keccak256(hash, hash)
     end
 end
 
@@ -91,7 +91,7 @@ function back_merkle_tree_meta.__index:push_back(new_leaf_hash)
     for i = 0, depth do
         if self.m_leaf_count & (0x01 << i) ~= 0x0 then
             local left = self.m_context[i]
-            right = cartesi.keccak(left, right)
+            right = cartesi.keccak256(left, right)
         else
             self.m_context[i] = right
             break
@@ -121,7 +121,7 @@ function back_merkle_tree_meta.__index:pad_back(new_leaf_count)
                 local i_span = 0x1 << i
                 if (self.m_leaf_count & i_span) ~= 0x0 then
                     local left = self.m_context[i]
-                    right = cartesi.keccak(left, right)
+                    right = cartesi.keccak256(left, right)
                 else
                     self.m_context[i] = right
                     -- next outer loop starts again from where inner loop left off
@@ -154,10 +154,10 @@ function back_merkle_tree_meta.__index:get_root_hash()
         for i = 0, depth - 1 do
             if (self.m_leaf_count & (0x01 << i)) ~= 0 then
                 local left = self.m_context[i]
-                root = cartesi.keccak(left, root)
+                root = cartesi.keccak256(left, root)
             else
                 local right = zero_keccak_hash_table[self.m_log2_leaf_size + i]
-                root = cartesi.keccak(root, right)
+                root = cartesi.keccak256(root, right)
             end
         end
         return root
@@ -214,7 +214,7 @@ function test_util.check_proof(proof)
         else
             first, second = hash, proof.sibling_hashes[log2_size - proof.log2_target_size + 1]
         end
-        hash = cartesi.keccak(first, second)
+        hash = cartesi.keccak256(first, second)
     end
     return hash == proof.root_hash
 end
@@ -236,9 +236,9 @@ local function merkle_hash(data, start, log2_size)
         local child_log2_size = log2_size - 1
         local left = merkle_hash(data, start, child_log2_size)
         local right = merkle_hash(data, start + (1 << child_log2_size), child_log2_size)
-        return cartesi.keccak(left, right)
+        return cartesi.keccak256(left, right)
     else
-        return cartesi.keccak(data:sub(start + 1, start + (1 << WORD_LOG2_SIZE)))
+        return cartesi.keccak256(data:sub(start + 1, start + (1 << WORD_LOG2_SIZE)))
     end
 end
 
diff --git a/tests/lua/cmio-test.lua b/tests/lua/cmio-test.lua
index f89f2def8..0d298bb24 100755
--- a/tests/lua/cmio-test.lua
+++ b/tests/lua/cmio-test.lua
@@ -160,7 +160,7 @@ local function check_output(machine, expected)
     end
     assert(expected == output)
 
-    return cartesi.keccak(output)
+    return cartesi.keccak256(output)
 end
 
 local function check_report(machine, expected)
@@ -195,14 +195,14 @@ local function check_outputs_root_hash(root_hash, output_hashes)
             end
             local c2 = output_hashes[child + 1]
             if c2 then
-                parent_output_hashes[parent] = cartesi.keccak(c1, c2)
+                parent_output_hashes[parent] = cartesi.keccak256(c1, c2)
             else
-                parent_output_hashes[parent] = cartesi.keccak(c1, z)
+                parent_output_hashes[parent] = cartesi.keccak256(c1, z)
             end
             parent = parent + 1
             child = child + 2
         end
-        z = cartesi.keccak(z, z)
+        z = cartesi.keccak256(z, z)
         output_hashes = parent_output_hashes
     end
     assert(root_hash == output_hashes[1], "output root hash mismatch")
diff --git a/tests/lua/hash-tree.lua b/tests/lua/hash-tree.lua
index 55ac01f95..2df3f7808 100755
--- a/tests/lua/hash-tree.lua
+++ b/tests/lua/hash-tree.lua
@@ -112,7 +112,7 @@ local function check_proof(proof)
         else
             first, second = hash, sibling_hash
         end
-        hash = cartesi.keccak(first, second)
+        hash = cartesi.keccak256(first, second)
     end
     return hash == proof.root_hash
 end
@@ -208,7 +208,7 @@ for _, p in ipairs(interesting_pages) do
     for address = page, page + PAGE_SIZE - 1, WORD_SIZE do
         local h1 = machine:get_node_hash(address, LOG2_WORD_SIZE)
         local word = machine:read_memory(address, WORD_SIZE)
-        local h2 = cartesi.keccak(word)
+        local h2 = cartesi.keccak256(word)
         if h1 ~= h2 then
             stderr("        hash mismatch on word 0x%016x (%u)\n", address, address)
             stderr("            0x%.16s... vs 0x%.16s...\n", tohex(h1), tohex(h2))
@@ -219,7 +219,7 @@ for _, p in ipairs(interesting_pages) do
     for log2_size = LOG2_WORD_SIZE + 1, LOG2_PAGE_SIZE do
         local new_hashes = {}
         for i = 1, #hashes - 1, 2 do
-            new_hashes[#new_hashes + 1] = cartesi.keccak(hashes[i], hashes[i + 1])
+            new_hashes[#new_hashes + 1] = cartesi.keccak256(hashes[i], hashes[i + 1])
         end
         hashes = new_hashes
         for i = 1, #hashes do
diff --git a/tests/misc/Makefile b/tests/misc/Makefile
index f7e66a5fe..fd886f5bb 100644
--- a/tests/misc/Makefile
+++ b/tests/misc/Makefile
@@ -95,7 +95,7 @@ CLANG_TIDY_HEADER_FILTER=$(CURDIR)/($(subst $(SPACE),|,$(LINTER_HEADERS)))
 CLANG_FORMAT=clang-format
 CLANG_FORMAT_FILES:=$(wildcard *.cpp) $(wildcard *.h)
 
-INCS=-I../../src -I../../third-party/tiny_sha3 -I../../third-party/nlohmann-json -I../../third-party/downloads
+INCS=-I../../src -I../../third-party/nlohmann-json -I../../third-party/downloads
 WARNS=-Wall -Wpedantic $(BOOST_INC)
 
 CXXFLAGS+=-O2 -g -std=gnu++20 -fopenmp -fvisibility=hidden $(INCS) $(UBFLAGS) $(WARNS)
diff --git a/tests/misc/test-merkle-tree-hash.cpp b/tests/misc/test-merkle-tree-hash.cpp
index 863a2ca13..8c60b145c 100644
--- a/tests/misc/test-merkle-tree-hash.cpp
+++ b/tests/misc/test-merkle-tree-hash.cpp
@@ -124,9 +124,7 @@ __attribute__((format(printf, 1, 2))) void error(const char *fmt, ...) {
 /// \param log2_word Log<sub>2</sub> of word size
 /// \param hash Receives the leaf hash
 void get_word_hash(hasher_type &h, const unsigned char *word, int log2_word_size, hash_type &hash) {
-    h.begin();
-    h.add_data(std::span<const unsigned char>(word, 1 << log2_word_size));
-    h.end(hash);
+    h.hash(std::span<const unsigned char>(word, 1 << log2_word_size), hash);
 }
 
 /// \brief Computes the Merkle hash of a leaf of data
diff --git a/tests/misc/test-utils.h b/tests/misc/test-utils.h
index b07356125..5468f00a4 100644
--- a/tests/misc/test-utils.h
+++ b/tests/misc/test-utils.h
@@ -41,10 +41,8 @@ static hash_type merkle_hash(cartesi::keccak_256_hasher &h, const std::string_vi
         auto right = merkle_hash(h, std::string_view{data.data() + half_size, half_size}, log2_size);
         get_concat_hash(h, left, right, result);
     } else {
-        h.begin();
         // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        h.add_data(data);
-        h.end(result);
+        h.hash(data, result);
     }
     return result;
 }
diff --git a/third-party/tiny_sha3/LICENSE b/third-party/tiny_sha3/LICENSE
deleted file mode 100644
index d2d484d88..000000000
--- a/third-party/tiny_sha3/LICENSE
+++ /dev/null
@@ -1,22 +0,0 @@
-The MIT License (MIT)
-
-Copyright (c) 2015 Markku-Juhani O. Saarinen
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
diff --git a/third-party/tiny_sha3/sha3.c b/third-party/tiny_sha3/sha3.c
deleted file mode 100644
index 7277efa14..000000000
--- a/third-party/tiny_sha3/sha3.c
+++ /dev/null
@@ -1,205 +0,0 @@
-// sha3.c
-// 19-Nov-11  Markku-Juhani O. Saarinen <mjos@iki.fi>
-
-// Revised 07-Aug-15 to match with official release of FIPS PUB 202 "SHA3"
-// Revised 03-Sep-15 for portability + OpenSSL - style API
-
-#include "sha3.h"
-
-// Helper macros for stringification
-#define TO_STRING_HELPER(X) #X
-#define TO_STRING(X) TO_STRING_HELPER(X)
-
-// Define loop unrolling depending on the compiler
-#if defined(__clang__)
-#define UNROLL_LOOP(n) _Pragma(TO_STRING(unroll(n)))
-#elif defined(__GNUC__) && !defined(__clang__)
-#define UNROLL_LOOP(n) _Pragma(TO_STRING(GCC unroll(n)))
-#else
-#define UNROLL_LOOP(n)
-#endif
-
-#ifndef KECCAKF_ROUNDS
-#define KECCAKF_ROUNDS 24
-#endif
-
-#ifndef ROTL64
-#define ROTL64(x, y) (((x) << (y)) | ((x) >> (64 - (y))))
-#endif
-
-// update the state with given number of rounds
-
-void sha3_keccakf(uint64_t st[25])
-{
-    // constants
-    const uint64_t keccakf_rndc[24] = {
-        0x0000000000000001, 0x0000000000008082, 0x800000000000808a,
-        0x8000000080008000, 0x000000000000808b, 0x0000000080000001,
-        0x8000000080008081, 0x8000000000008009, 0x000000000000008a,
-        0x0000000000000088, 0x0000000080008009, 0x000000008000000a,
-        0x000000008000808b, 0x800000000000008b, 0x8000000000008089,
-        0x8000000000008003, 0x8000000000008002, 0x8000000000000080,
-        0x000000000000800a, 0x800000008000000a, 0x8000000080008081,
-        0x8000000000008080, 0x0000000080000001, 0x8000000080008008
-    };
-    const int keccakf_rotc[24] = {
-        1,  3,  6,  10, 15, 21, 28, 36, 45, 55, 2,  14,
-        27, 41, 56, 8,  25, 43, 62, 18, 39, 61, 20, 44
-    };
-    const int keccakf_piln[24] = {
-        10, 7,  11, 17, 18, 3, 5,  16, 8,  21, 24, 4,
-        15, 23, 19, 13, 12, 2, 20, 14, 22, 9,  6,  1
-    };
-
-    // variables
-    int i, j, r;
-    uint64_t t, bc[5];
-
-#if __BYTE_ORDER__ != __ORDER_LITTLE_ENDIAN__
-    // endianess conversion. this is redundant on little-endian targets
-    for (i = 0; i < 25; i++) {
-        st[i] = __builtin_bswap64(st[i]);
-    }
-#endif
-
-    // actual iteration
-    for (r = 0; r < KECCAKF_ROUNDS; r++) {
-
-        // Theta
-        UNROLL_LOOP(5)
-        for (i = 0; i < 5; i++)
-            bc[i] = st[i] ^ st[i + 5] ^ st[i + 10] ^ st[i + 15] ^ st[i + 20];
-
-        UNROLL_LOOP(5)
-        for (i = 0; i < 5; i++) {
-            t = bc[(i + 4) % 5] ^ ROTL64(bc[(i + 1) % 5], 1);
-            UNROLL_LOOP(25)
-            for (j = 0; j < 25; j += 5)
-                st[j + i] ^= t;
-        }
-
-        // Rho Pi
-        t = st[1];
-        UNROLL_LOOP(24)
-        for (i = 0; i < 24; i++) {
-            j = keccakf_piln[i];
-            bc[0] = st[j];
-            st[j] = ROTL64(t, keccakf_rotc[i]);
-            t = bc[0];
-        }
-
-        //  Chi
-        UNROLL_LOOP(25)
-        for (j = 0; j < 25; j += 5) {
-            UNROLL_LOOP(5)
-            for (i = 0; i < 5; i++)
-                bc[i] = st[j + i];
-            UNROLL_LOOP(5)
-            for (i = 0; i < 5; i++)
-                st[j + i] ^= (~bc[(i + 1) % 5]) & bc[(i + 2) % 5];
-        }
-
-        //  Iota
-        st[0] ^= keccakf_rndc[r];
-    }
-
-#if __BYTE_ORDER__ != __ORDER_LITTLE_ENDIAN__
-    // endianess conversion. this is redundant on little-endian targets
-    for (i = 0; i < 25; i++) {
-        st[i] = __builtin_bswap64(st[i]);
-    }
-#endif
-}
-
-// Initialize the context for SHA3
-
-int sha3_init(sha3_ctx_t *c, int mdlen, int dsuffix)
-{
-    int i;
-
-    for (i = 0; i < 25; i++)
-        c->st.q[i] = 0;
-    c->mdlen = mdlen;
-    c->rsiz = 200 - 2 * mdlen;
-    c->pt = 0;
-    c->dsuffix = dsuffix;
-
-    return 1;
-}
-
-// update state with more data
-
-int sha3_update(sha3_ctx_t *c, const void *data, size_t len)
-{
-    size_t i;
-    int j;
-
-    j = c->pt;
-    for (i = 0; i < len; i++) {
-        c->st.b[j++] ^= ((const uint8_t *) data)[i];
-        if (j >= c->rsiz) {
-            sha3_keccakf(c->st.q);
-            j = 0;
-        }
-    }
-    c->pt = j;
-
-    return 1;
-}
-
-// finalize and output a hash
-
-int sha3_final(void *md, sha3_ctx_t *c)
-{
-    int i;
-
-    c->st.b[c->pt] ^= c->dsuffix;
-    c->st.b[c->rsiz - 1] ^= 0x80;
-    sha3_keccakf(c->st.q);
-
-    for (i = 0; i < c->mdlen; i++) {
-        ((uint8_t *) md)[i] = c->st.b[i];
-    }
-
-    return 1;
-}
-
-// compute a SHA-3 hash (md) of given byte length from "in"
-
-void *sha3(const void *in, size_t inlen, void *md, int mdlen)
-{
-    sha3_ctx_t sha3;
-
-    sha3_init(&sha3, mdlen, 0x06);
-    sha3_update(&sha3, in, inlen);
-    sha3_final(md, &sha3);
-
-    return md;
-}
-
-// SHAKE128 and SHAKE256 extensible-output functionality
-
-void shake_xof(sha3_ctx_t *c)
-{
-    c->st.b[c->pt] ^= 0x1F;
-    c->st.b[c->rsiz - 1] ^= 0x80;
-    sha3_keccakf(c->st.q);
-    c->pt = 0;
-}
-
-void shake_out(sha3_ctx_t *c, void *out, size_t len)
-{
-    size_t i;
-    int j;
-
-    j = c->pt;
-    for (i = 0; i < len; i++) {
-        if (j >= c->rsiz) {
-            sha3_keccakf(c->st.q);
-            j = 0;
-        }
-        ((uint8_t *) out)[i] = c->st.b[j++];
-    }
-    c->pt = j;
-}
-
diff --git a/third-party/tiny_sha3/sha3.h b/third-party/tiny_sha3/sha3.h
deleted file mode 100644
index d130afdf0..000000000
--- a/third-party/tiny_sha3/sha3.h
+++ /dev/null
@@ -1,39 +0,0 @@
-// sha3.h
-// 19-Nov-11  Markku-Juhani O. Saarinen <mjos@iki.fi>
-
-#ifndef SHA3_H
-#define SHA3_H
-
-#include <stddef.h>
-#include <stdint.h>
-
-// state context
-typedef struct {
-    union {                                 // state:
-        uint8_t b[200];                     // 8-bit bytes
-        uint64_t q[25];                     // 64-bit words
-    } st;
-    int pt, rsiz, mdlen, dsuffix;           // these don't overflow
-} sha3_ctx_t;
-
-// Compression function.
-void sha3_keccakf(uint64_t st[25]);
-
-// OpenSSL - like interfece
-int sha3_init(sha3_ctx_t *c, int mdlen, int dsuffix);    // mdlen = hash output in bytes
-int sha3_update(sha3_ctx_t *c, const void *data, size_t len);
-int sha3_final(void *md, sha3_ctx_t *c);    // digest goes to md
-
-// compute a sha3 hash (md) of given byte length from "in"
-void *sha3(const void *in, size_t inlen, void *md, int mdlen);
-
-// SHAKE128 and SHAKE256 extensible-output functions
-#define shake128_init(c) sha3_init(c, 16, 0x06)
-#define shake256_init(c) sha3_init(c, 32, 0x06)
-#define shake_update sha3_update
-
-void shake_xof(sha3_ctx_t *c);
-void shake_out(sha3_ctx_t *c, void *out, size_t len);
-
-#endif
-
diff --git a/uarch/Makefile b/uarch/Makefile
index 06396d509..df8ea33f5 100644
--- a/uarch/Makefile
+++ b/uarch/Makefile
@@ -20,7 +20,7 @@ else
 HOST_CXX := g++
 HOST_CC := gcc
 endif
-HOST_CFLAGS := -I$(THIRD_PARTY_DIR)/tiny_sha3 -I$(EMULATOR_SRC_DIR)
+HOST_CFLAGS := -I$(EMULATOR_SRC_DIR)
 HOST_CXXFLAGS := -std=c++20
 
 CC := $(TOOLCHAIN_PREFIX)gcc
@@ -80,7 +80,9 @@ COMPUTE_SOURCES=\
 	$(EMULATOR_SRC_DIR)/pristine-merkle-tree.cpp \
 	$(EMULATOR_SRC_DIR)/complete-merkle-tree.cpp \
 	$(EMULATOR_SRC_DIR)/full-merkle-tree.cpp \
-	$(THIRD_PARTY_DIR)/tiny_sha3/sha3.c \
+	$(EMULATOR_SRC_DIR)/keccak-256-hasher.cpp \
+	$(EMULATOR_SRC_DIR)/sha-256-hasher.cpp \
+	$(EMULATOR_SRC_DIR)/is-pristine.cpp \
 	uarch-pristine-ram.c
 
 UARCH_OBJS = $(patsubst %.c,%.uarch_c.o,$(patsubst %.cpp,%.uarch_cpp.o,$(UARCH_SOURCES)))

From b0c0634594d071986762fc730856ce57b6547bbd Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Thu, 17 Jul 2025 12:06:24 -0300
Subject: [PATCH 52/82] feat: make hash function from hash tree configurable

Co-authored-by: Marcos Pernambuco Motta <1091485+mpernambuco@users.noreply.github>
---
 .github/workflows/build.yml              |   8 +-
 Makefile                                 |   2 +-
 src/back-merkle-tree.cpp                 |  14 +-
 src/back-merkle-tree.h                   |  17 +-
 src/cartesi-machine.lua                  |  10 +-
 src/cartesi/proof.lua                    |  43 ---
 src/clua-cartesi.cpp                     |   7 +-
 src/complete-merkle-tree.cpp             |  11 +-
 src/complete-merkle-tree.h               |  21 +-
 src/full-merkle-tree.cpp                 |  21 +-
 src/full-merkle-tree.h                   |  20 +-
 src/hash-tree.cpp                        |  55 +--
 src/hash-tree.h                          |  11 +-
 src/i-hasher.h                           |  41 ++-
 src/json-util.cpp                        |  43 ++-
 src/json-util.h                          |  10 +
 src/jsonrpc-discover.json                |  10 +-
 src/keccak-256-hasher.h                  |  41 +--
 src/machine-config.h                     |   2 +
 src/machine.cpp                          |  49 ++-
 src/machine.h                            |   6 +
 src/merkle-tree-hash.cpp                 |  37 +-
 src/page-hash-tree-cache.h               |   8 +-
 src/pristine-merkle-tree.cpp             |   4 +-
 src/pristine-merkle-tree.h               |   7 +-
 src/record-send-cmio-state-access.h      |  21 +-
 src/record-step-state-access.h           |  13 +-
 src/replay-send-cmio-state-access.h      |  40 ++-
 src/replay-step-state-access-interop.cpp |  17 +-
 src/replay-step-state-access-interop.h   |  12 +-
 src/replay-step-state-access.h           |  63 ++--
 src/sha-256-hasher.h                     |  25 --
 src/simd-hasher.h                        |  18 +-
 src/uarch-record-state-access.h          |   9 -
 src/uarch-replay-state-access.h          |  11 +-
 src/variant-hasher.h                     |  71 ++++
 tests/Makefile                           |   3 +-
 tests/lua/cartesi/tests/util.lua         |  75 ++--
 tests/lua/hash-tree.lua                  |  15 +-
 tests/lua/machine-bind.lua               | 434 ++++++++++++++---------
 tests/lua/machine-test.lua               |   9 +-
 tests/misc/test-machine-c-api.cpp        |   8 +-
 tests/misc/test-merkle-tree-hash.cpp     |  65 ++--
 tests/misc/test-utils.h                  |  41 ++-
 uarch/compute-uarch-pristine-hash.cpp    |  13 +-
 45 files changed, 837 insertions(+), 624 deletions(-)
 delete mode 100644 src/cartesi/proof.lua
 create mode 100644 src/variant-hasher.h

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 997fda5bf..cd5cc0d41 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -211,7 +211,8 @@ jobs:
 
       - name: Run Merkle tree tests
         run: |
-          docker run --rm -t ${{ github.repository_owner }}/machine-emulator:tests test-merkle-tree-hash --log2-root-size=30 --log2-leaf-size=12 --input=/usr/bin/test-merkle-tree-hash
+          docker run --rm -t ${{ github.repository_owner }}/machine-emulator:tests test-merkle-tree-hash --log2-root-size=30 --log2-leaf-size=12 --input=/usr/bin/test-merkle-tree-hash --hash-function=keccak256
+          docker run --rm -t ${{ github.repository_owner }}/machine-emulator:tests test-merkle-tree-hash --log2-root-size=30 --log2-leaf-size=12 --input=/usr/bin/test-merkle-tree-hash --hash-function=sha256
 
       - name: Run C API tests
         run: |
@@ -379,7 +380,8 @@ jobs:
 
       - name: Run Merkle tree tests
         run: |
-          docker run --platform linux/arm64 --rm -t ${{ github.repository_owner }}/machine-emulator:tests test-merkle-tree-hash --log2-root-size=30 --log2-leaf-size=12 --input=/usr/bin/test-merkle-tree-hash
+          docker run --platform linux/arm64 --rm -t ${{ github.repository_owner }}/machine-emulator:tests test-merkle-tree-hash --log2-root-size=30 --log2-leaf-size=12 --input=/usr/bin/test-merkle-tree-hash --hash-function=keccak256
+          docker run --platform linux/arm64 --rm -t ${{ github.repository_owner }}/machine-emulator:tests test-merkle-tree-hash --log2-root-size=30 --log2-leaf-size=12 --input=/usr/bin/test-merkle-tree-hash --hash-function=sha256
 
       - name: Run C API tests
         run: |
@@ -633,7 +635,7 @@ jobs:
 
       - name: Run tests with sanitizer
         run: |
-          docker run --rm -t ${{ github.repository_owner }}/machine-emulator:sanitizer make sanitize=yes test-save-and-load test-machine test-hash test-lua test-jsonrpc test-c-api coverage-machine test-uarch-rv64ui test-uarch-interpreter coverage-uarch
+          docker run --rm -t ${{ github.repository_owner }}/machine-emulator:sanitizer make sanitize=yes test-save-and-load test-machine test-lua test-jsonrpc test-c-api coverage-machine test-uarch-rv64ui test-uarch-interpreter coverage-uarch
 
   publish_artifacts:
     name: Publish artifacts
diff --git a/Makefile b/Makefile
index 98a72b129..9fe55574a 100644
--- a/Makefile
+++ b/Makefile
@@ -77,7 +77,7 @@ EMU_TO_BIN= src/cartesi-jsonrpc-machine src/cartesi-merkle-tree-hash
 EMU_TO_LIB= src/$(LIBCARTESI_SO) src/$(LIBCARTESI_SO_JSONRPC)
 EMU_TO_LIB_A= src/libcartesi.a src/libcartesi_jsonrpc.a src/libluacartesi.a src/libluacartesi_jsonrpc.a
 EMU_LUA_TO_BIN= src/cartesi-machine.lua src/cartesi-machine-stored-hash.lua
-EMU_TO_LUA_PATH= src/cartesi/util.lua src/cartesi/proof.lua src/cartesi/gdbstub.lua
+EMU_TO_LUA_PATH= src/cartesi/util.lua src/cartesi/gdbstub.lua
 EMU_TO_LUA_CPATH= src/cartesi.so
 EMU_TO_LUA_CARTESI_CPATH= src/cartesi/jsonrpc.so
 EMU_TO_INC= $(addprefix src/,jsonrpc-machine-c-api.h machine-c-api.h machine-c-version.h)
diff --git a/src/back-merkle-tree.cpp b/src/back-merkle-tree.cpp
index 9fbcafe28..ab081aa7f 100644
--- a/src/back-merkle-tree.cpp
+++ b/src/back-merkle-tree.cpp
@@ -29,12 +29,14 @@
 
 namespace cartesi {
 
-back_merkle_tree::back_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size) :
+back_merkle_tree::back_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size,
+    hash_function_type hash_function) :
     m_log2_root_size{log2_root_size},
     m_log2_leaf_size{log2_leaf_size},
     m_max_leaves{UINT64_C(1) << (log2_root_size - log2_leaf_size)},
     m_context(std::max(1, log2_root_size - log2_leaf_size + 1)),
-    m_pristine_hashes{log2_root_size, log2_word_size} {
+    m_pristine_hashes{log2_root_size, log2_word_size, hash_function},
+    m_hash_function(hash_function) {
     if (log2_root_size < 0) {
         throw std::out_of_range{"log2_root_size is negative"};
     }
@@ -56,7 +58,7 @@ back_merkle_tree::back_merkle_tree(int log2_root_size, int log2_leaf_size, int l
 }
 
 void back_merkle_tree::push_back(const machine_hash &new_leaf_hash) {
-    hasher_type h;
+    variant_hasher h{m_hash_function};
     machine_hash right = new_leaf_hash;
     if (m_leaf_count >= m_max_leaves) {
         throw std::out_of_range{"too many leaves"};
@@ -75,7 +77,7 @@ void back_merkle_tree::push_back(const machine_hash &new_leaf_hash) {
 }
 
 void back_merkle_tree::pad_back(uint64_t new_leaf_count) {
-    hasher_type h;
+    variant_hasher h{m_hash_function};
     if (new_leaf_count > m_max_leaves || m_leaf_count + new_leaf_count > m_max_leaves) {
         throw std::invalid_argument("too many leaves");
     }
@@ -120,7 +122,7 @@ void back_merkle_tree::pad_back(uint64_t new_leaf_count) {
 }
 
 machine_hash back_merkle_tree::get_root_hash() const {
-    hasher_type h;
+    variant_hasher h{m_hash_function};
     assert(m_leaf_count <= m_max_leaves);
     const int depth = m_log2_root_size - m_log2_leaf_size;
     if (m_leaf_count < m_max_leaves) {
@@ -144,7 +146,7 @@ back_merkle_tree::proof_type back_merkle_tree::get_next_leaf_proof() const {
     if (m_leaf_count >= m_max_leaves) {
         throw std::out_of_range{"tree is full"};
     }
-    hasher_type h;
+    variant_hasher h{m_hash_function};
     proof_type proof{m_log2_root_size, m_log2_leaf_size};
     proof.set_target_address(m_leaf_count << m_log2_leaf_size);
     proof.set_target_hash(m_pristine_hashes.get_hash(m_log2_leaf_size));
diff --git a/src/back-merkle-tree.h b/src/back-merkle-tree.h
index 4b887fcc6..3543bc5c2 100644
--- a/src/back-merkle-tree.h
+++ b/src/back-merkle-tree.h
@@ -21,9 +21,9 @@
 #include <vector>
 
 #include "hash-tree-proof.h"
-#include "keccak-256-hasher.h"
 #include "machine-hash.h"
 #include "pristine-merkle-tree.h"
+#include "variant-hasher.h"
 
 /// \file
 /// \brief Back Merkle tree interface.
@@ -40,12 +40,6 @@ namespace cartesi {
 /// The class only ever stores log(n) hashes (1 for each tree level).
 class back_merkle_tree {
 public:
-    /// \brief Hasher class.
-    using hasher_type = keccak_256_hasher;
-
-    /// \brief Hasher class.
-    using hash_type = machine_hash;
-
     /// \brief Storage for the proof of a word value.
     using proof_type = hash_tree_proof;
 
@@ -53,7 +47,7 @@ class back_merkle_tree {
     /// \param log2_root_size Log<sub>2</sub> of root node
     /// \param log2_leaf_size Log<sub>2</sub> of leaf node
     /// \param log2_word_size Log<sub>2</sub> of word node
-    back_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size);
+    back_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size, hash_function_type hash_function);
 
     /// \brief Appends a new hash to the tree
     /// \param new_leaf_hash Hash of new leaf data
@@ -76,7 +70,7 @@ class back_merkle_tree {
     /// If the bit i is set in leaf_count, we replace context[i] = hash(context[i], right) and move up a bit.
     /// If the bit is not set, we simply store context[i] = right and break.
     /// In other words, we can update the context in log time (log2_root_size-log2_leaf_size)
-    void push_back(const hash_type &new_leaf_hash);
+    void push_back(const machine_hash &new_leaf_hash);
 
     /// \brief Appends a number of padding hashes to the tree
     /// \param leaf_count Number of padding hashes to append
@@ -107,7 +101,7 @@ class back_merkle_tree {
     /// are growing is to the right of what is in the context)
     /// If bit i is not set, we set root = hash(root, pristine[i+log2_leaf_size]) and move up a bit
     /// (i.e., to grow our subtree, we need to pad it on the right with a pristine subtree of the same size)
-    hash_type get_root_hash() const;
+    machine_hash get_root_hash() const;
 
     /// \brief Returns proof for the next pristine leaf
     /// \returns Proof for leaf at given index, or throws exception
@@ -120,8 +114,9 @@ class back_merkle_tree {
     int m_log2_leaf_size;                   ///< Log<sub>2</sub> of leaf size
     uint64_t m_leaf_count{0};               ///< Number of leaves already added
     uint64_t m_max_leaves;                  ///< Maximum number of leaves
-    std::vector<hash_type> m_context;       ///< Hashes of bits set in leaf_count
+    std::vector<machine_hash> m_context;    ///< Hashes of bits set in leaf_count
     pristine_merkle_tree m_pristine_hashes; ///< Hash of pristine subtrees of all sizes
+    hash_function_type m_hash_function;     ///< Hash function
 };
 
 } // namespace cartesi
diff --git a/src/cartesi-machine.lua b/src/cartesi-machine.lua
index b371882e2..9d0e5bdee 100755
--- a/src/cartesi-machine.lua
+++ b/src/cartesi-machine.lua
@@ -214,13 +214,13 @@ where options are:
     configures the global hash tree the the machine
 
     <key>:<value> is one of
-        hasher:<string>
+        hash_function:<string>
         sht_filename:<filename>
         phtc_filename:<filename>
         phtc_size:<number>
         shared
 
-        hasher (default: "keccak")
+        hash_function (default: "keccak256")
 		hashing algorithm used for the tree
 
         sht_filename (optional)
@@ -707,7 +707,7 @@ local uarch = {
 }
 local pmas = {}
 local hash_tree = {
-    hasher = default_config.hash_tree.hasher,
+    hash_function = default_config.hash_tree.hash_function,
 }
 local concurrency_update_hash_tree = 0
 local skip_root_hash_check = false
@@ -1099,7 +1099,7 @@ local options = {
         "^(%-%-hash%-tree%=(.+))$",
         function(all, opts)
             local h = util.parse_options(opts, all, {
-                hasher = "string",
+                hash_function = "string",
                 sht_filename = "string",
                 phtc_filename = "string",
                 phtc_size = "number",
@@ -1107,7 +1107,7 @@ local options = {
             })
             h.sht_filename = h.sht_filename or ""
             h.phtc_filename = h.phtc_filename or ""
-            h.hasher = h.hasher or "keccak"
+            h.hash_function = h.hash_function or "keccak256"
             for i, v in pairs(h) do
                 hash_tree[i] = v
             end
diff --git a/src/cartesi/proof.lua b/src/cartesi/proof.lua
deleted file mode 100644
index b5f7fb0d5..000000000
--- a/src/cartesi/proof.lua
+++ /dev/null
@@ -1,43 +0,0 @@
-local cartesi = require("cartesi")
-
-local _M = {}
-
-function _M.roll_hash_up_tree(proof, target_hash)
-    local hash = target_hash
-    for log2_size = proof.log2_target_size, proof.log2_root_size - 1 do
-        local bit = (proof.target_address & (1 << log2_size)) ~= 0
-        local first, second
-        local i = proof.log2_root_size - log2_size
-        if bit then
-            first, second = proof.sibling_hashes[i], hash
-        else
-            first, second = hash, proof.sibling_hashes[i]
-        end
-        hash = cartesi.keccak256(first, second)
-    end
-    return hash
-end
-
-function _M.slice_assert(root_hash, proof)
-    assert(root_hash == proof.root_hash, "proof root_hash mismatch")
-    assert(_M.roll_hash_up_tree(proof, proof.target_hash) == root_hash, "node not in tree")
-end
-
-function _M.word_slice_assert(root_hash, proof, word)
-    assert(proof.log2_target_size == 3, "not a word proof")
-    assert(root_hash == proof.root_hash, "proof root_hash mismatch")
-    assert(cartesi.keccak256(word) == proof.target_hash, "proof target_hash mismatch")
-    assert(_M.roll_hash_up_tree(proof, proof.target_hash) == root_hash, "node not in tree")
-end
-
-function _M.splice_assert(root_hash, proof, new_target_hash, new_root_hash)
-    _M.slice_assert(root_hash, proof)
-    assert(_M.roll_hash_up_tree(proof, new_target_hash) == new_root_hash, "new root hash mismatch")
-end
-
-function _M.word_splice_assert(root_hash, proof, old_word, new_word, new_root_hash)
-    _M.word_slice_assert(root_hash, proof, old_word)
-    assert(_M.roll_hash_up_tree(proof, cartesi.keccak256(new_word)) == new_root_hash, "new root hash mismatch")
-end
-
-return _M
diff --git a/src/clua-cartesi.cpp b/src/clua-cartesi.cpp
index 74cbc2ac5..733e69efb 100644
--- a/src/clua-cartesi.cpp
+++ b/src/clua-cartesi.cpp
@@ -81,12 +81,7 @@ static int cartesi_mod_hasher(lua_State *L) {
     const auto *data2 = reinterpret_cast<const unsigned char *>(luaL_optlstring(L, 2, "", &len2));
     Hasher h;
     machine_hash hash;
-    // Handle special case that may have optimal implementations
-    if (len1 == MACHINE_HASH_SIZE && len2 == MACHINE_HASH_SIZE) { // Special case for hash tree concatenation
-        h.concat_hash(const_machine_hash_view{data1, len1}, const_machine_hash_view{data2, len2}, hash);
-    } else if (len1 == HASH_TREE_WORD_SIZE && len2 == 0) { // Special case for hash tree word
-        h.hash(const_hash_tree_word_view{data1, len1}, hash);
-    } else if (len2 > 0) { // Generic concat hash
+    if (len2 > 0) { // Generic concat hash
         h.concat_hash(std::span<const unsigned char>{data1, len1}, std::span<const unsigned char>{data2, len2}, hash);
     } else { // Generic hash
         h.hash(std::span<const unsigned char>{data1, len1}, hash);
diff --git a/src/complete-merkle-tree.cpp b/src/complete-merkle-tree.cpp
index 334862846..b7ca70fcd 100644
--- a/src/complete-merkle-tree.cpp
+++ b/src/complete-merkle-tree.cpp
@@ -23,17 +23,20 @@
 #include <utility>
 
 #include "i-hasher.h"
+#include "variant-hasher.h"
 
 /// \file
 /// \brief Complete Merkle tree implementation.
 
 namespace cartesi {
 
-complete_merkle_tree::complete_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size) :
+complete_merkle_tree::complete_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size,
+    hash_function_type hash_function) :
     m_log2_root_size{log2_root_size},
     m_log2_leaf_size{log2_leaf_size},
-    m_pristine{log2_root_size, log2_word_size},
-    m_tree(std::max(0, log2_root_size - log2_leaf_size + 1)) {
+    m_pristine{log2_root_size, log2_word_size, hash_function},
+    m_tree(std::max(0, log2_root_size - log2_leaf_size + 1)),
+    m_hash_function(hash_function) {
     check_log2_sizes(log2_root_size, log2_leaf_size, log2_word_size);
 }
 
@@ -105,7 +108,7 @@ const machine_hash &complete_merkle_tree::get_node_hash(uint64_t address, int lo
 }
 
 void complete_merkle_tree::bubble_up() {
-    hasher_type h;
+    variant_hasher h{m_hash_function};
     // Go bottom up, updating hashes
     for (int log2_next_size = get_log2_leaf_size() + 1; log2_next_size <= get_log2_root_size(); ++log2_next_size) {
         auto log2_prev_size = log2_next_size - 1;
diff --git a/src/complete-merkle-tree.h b/src/complete-merkle-tree.h
index 24950d927..e2e4462c7 100644
--- a/src/complete-merkle-tree.h
+++ b/src/complete-merkle-tree.h
@@ -22,10 +22,10 @@
 #include <vector>
 
 #include "hash-tree-proof.h"
-#include "keccak-256-hasher.h"
 #include "machine-hash.h"
 #include "meta.h"
 #include "pristine-merkle-tree.h"
+#include "variant-hasher.h"
 
 /// \file
 /// \brief Complete Merkle tree interface.
@@ -39,9 +39,6 @@ namespace cartesi {
 /// The tree is optimized to store only the hashes that are not pristine.
 class complete_merkle_tree {
 public:
-    /// \brief Hasher class.
-    using hasher_type = keccak_256_hasher;
-
     /// \brief Storage for a proof.
     using proof_type = hash_tree_proof;
 
@@ -52,15 +49,16 @@ class complete_merkle_tree {
     /// \param log2_root_size Log<sub>2</sub> of tree size
     /// \param log2_leaf_size Log<sub>2</sub> of leaf node
     /// \param log2_word_size Log<sub>2</sub> of word
-    complete_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size);
+    complete_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size, hash_function_type hash_function);
 
     /// \brief Constructor from non-pristine leaves (assumed flushed left)
     /// \param log2_root_size Log<sub>2</sub> of tree size
     /// \param log2_leaf_size Log<sub>2</sub> of leaf node
     /// \param log2_word_size Log<sub>2</sub> of word
     template <typename L>
-    complete_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size, L &&leaves) :
-        complete_merkle_tree{log2_root_size, log2_leaf_size, log2_word_size} {
+    complete_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size, L &&leaves,
+        hash_function_type hash_function) :
+        complete_merkle_tree{log2_root_size, log2_leaf_size, log2_word_size, hash_function} {
         static_assert(std::is_same_v<level_type, std::remove_cvref_t<L>>, "not a leaves vector");
         get_level(get_log2_leaf_size()) = std::forward<L>(leaves);
         bubble_up();
@@ -124,10 +122,11 @@ class complete_merkle_tree {
     /// hash at level
     level_type &get_level(int log2_size);
 
-    int m_log2_root_size;            ///< Log<sub>2</sub> of tree size
-    int m_log2_leaf_size;            ///< Log<sub>2</sub> of page size
-    pristine_merkle_tree m_pristine; ///< Pristine hashes for all levels
-    std::vector<level_type> m_tree;  ///< Merkle tree
+    int m_log2_root_size;               ///< Log<sub>2</sub> of tree size
+    int m_log2_leaf_size;               ///< Log<sub>2</sub> of page size
+    pristine_merkle_tree m_pristine;    ///< Pristine hashes for all levels
+    std::vector<level_type> m_tree;     ///< Merkle tree
+    hash_function_type m_hash_function; ///< Hash function
 };
 
 } // namespace cartesi
diff --git a/src/full-merkle-tree.cpp b/src/full-merkle-tree.cpp
index 286673a1c..64e34c1c9 100644
--- a/src/full-merkle-tree.cpp
+++ b/src/full-merkle-tree.cpp
@@ -29,26 +29,29 @@
 
 namespace cartesi {
 
-full_merkle_tree::full_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size) :
+full_merkle_tree::full_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size,
+    hash_function_type hash_function) :
     m_log2_root_size{log2_root_size},
     m_log2_leaf_size{log2_leaf_size},
-    m_max_leaves{UINT64_C(1) << std::max(0, log2_root_size - log2_leaf_size)} {
+    m_max_leaves{UINT64_C(1) << std::max(0, log2_root_size - log2_leaf_size)},
+    m_hash_function{hash_function} {
     check_log2_sizes(log2_root_size, log2_leaf_size, log2_word_size);
     m_tree.resize(2 * m_max_leaves);
-    init_pristine_subtree(pristine_merkle_tree{log2_root_size, log2_word_size}, 1, log2_root_size);
+    init_pristine_subtree(pristine_merkle_tree{log2_root_size, log2_word_size, hash_function}, 1, log2_root_size);
 }
 
 full_merkle_tree::full_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size,
-    const std::vector<machine_hash> &leaves) :
+    const std::vector<machine_hash> &leaves, hash_function_type hash_function) :
     m_log2_root_size(log2_root_size),
     m_log2_leaf_size(log2_leaf_size),
-    m_max_leaves{UINT64_C(1) << std::max(0, log2_root_size - log2_leaf_size)} {
+    m_max_leaves{UINT64_C(1) << std::max(0, log2_root_size - log2_leaf_size)},
+    m_hash_function{hash_function} {
     check_log2_sizes(log2_root_size, log2_leaf_size, log2_word_size);
     if (leaves.size() > m_max_leaves) {
         throw std::out_of_range{"too many leaves"};
     }
     m_tree.resize(2 * m_max_leaves);
-    init_tree(pristine_merkle_tree{log2_root_size, log2_word_size}, leaves);
+    init_tree(pristine_merkle_tree{log2_root_size, log2_word_size, hash_function}, leaves);
 }
 
 full_merkle_tree::proof_type full_merkle_tree::get_proof(uint64_t address, int log2_size) const {
@@ -68,7 +71,7 @@ full_merkle_tree::proof_type full_merkle_tree::get_proof(uint64_t address, int l
         proof.set_sibling_hash(get_node_hash(sibling_address, log2_sibling_size), log2_sibling_size);
     }
 #ifndef NDEBUG
-    hasher_type h{};
+    variant_hasher h{m_hash_function};
     if (!proof.verify(h)) {
         throw std::runtime_error{"produced invalid proof"};
     }
@@ -105,7 +108,7 @@ void full_merkle_tree::init_pristine_subtree(const pristine_merkle_tree &pristin
     }
 }
 
-void full_merkle_tree::init_subtree(hasher_type &h, int index, int log2_size) {
+void full_merkle_tree::init_subtree(variant_hasher &h, int index, int log2_size) {
     if (log2_size > get_log2_leaf_size()) {
         init_subtree(h, left_child_index(index), log2_size - 1);
         init_subtree(h, right_child_index(index), log2_size - 1);
@@ -117,7 +120,7 @@ void full_merkle_tree::init_tree(const pristine_merkle_tree &pristine, const std
     std::copy(leaves.begin(), leaves.end(), &m_tree[m_max_leaves]);
     std::fill_n(&m_tree[m_max_leaves + leaves.size()], m_max_leaves - leaves.size(),
         pristine.get_hash(get_log2_leaf_size()));
-    hasher_type h;
+    variant_hasher h{m_hash_function};
     init_subtree(h, 1, get_log2_root_size());
 }
 
diff --git a/src/full-merkle-tree.h b/src/full-merkle-tree.h
index 2f063642d..9898de6c1 100644
--- a/src/full-merkle-tree.h
+++ b/src/full-merkle-tree.h
@@ -21,9 +21,9 @@
 #include <vector>
 
 #include "hash-tree-proof.h"
-#include "keccak-256-hasher.h"
 #include "machine-hash.h"
 #include "pristine-merkle-tree.h"
+#include "variant-hasher.h"
 
 /// \file
 /// \brief Full Merkle tree interface.
@@ -34,9 +34,6 @@ namespace cartesi {
 /// \details This class implements a full merkle tree
 class full_merkle_tree {
 public:
-    /// \brief Hasher class.
-    using hasher_type = keccak_256_hasher;
-
     /// \brief Storage for a proof.
     using proof_type = hash_tree_proof;
 
@@ -44,7 +41,7 @@ class full_merkle_tree {
     /// \param log2_root_size Log<sub>2</sub> of root node
     /// \param log2_leaf_size Log<sub>2</sub> of leaf node
     /// \param log2_word_size Log<sub>2</sub> of word
-    full_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size);
+    full_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size, hash_function_type hash_function);
 
     /// \brief Constructor for list of consecutive leaf hashes
     /// \param log2_root_size Log<sub>2</sub> of root node
@@ -52,7 +49,7 @@ class full_merkle_tree {
     /// \param log2_word_size Log<sub>2</sub> of word
     /// \param leaves List of leaf hashes
     full_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size,
-        const std::vector<machine_hash> &leaves);
+        const std::vector<machine_hash> &leaves, hash_function_type hash_function);
 
     /// \brief Returns log<sub>2</sub> of size of tree
     int get_log2_root_size() const {
@@ -114,7 +111,7 @@ class full_merkle_tree {
     /// \param log2_size Log<sub>2</sub> size of root at index
     /// \details The nodes corresponding to subtrees of size log2_leaf_size
     /// are assumed to have already been set prior to calling this function
-    void init_subtree(hasher_type &h, int index, int log2_size);
+    void init_subtree(variant_hasher &h, int index, int log2_size);
 
     /// \brief Initialize tree from a list of consecutive page hashes
     /// \param leaves List of page hashes
@@ -128,10 +125,11 @@ class full_merkle_tree {
     /// \param log2_size
     uint64_t get_node_index(uint64_t address, int log2_size) const;
 
-    int m_log2_root_size;             ///< Log<sub>2</sub> of tree size
-    int m_log2_leaf_size;             ///< Log<sub>2</sub> of leaf size
-    uint64_t m_max_leaves;            ///< Maximum number of leaves
-    std::vector<machine_hash> m_tree; ///< Binary heap with tree node hashes
+    int m_log2_root_size;               ///< Log<sub>2</sub> of tree size
+    int m_log2_leaf_size;               ///< Log<sub>2</sub> of leaf size
+    uint64_t m_max_leaves;              ///< Maximum number of leaves
+    std::vector<machine_hash> m_tree;   ///< Binary heap with tree node hashes
+    hash_function_type m_hash_function; ///< Hash function
 };
 
 } // namespace cartesi
diff --git a/src/hash-tree.cpp b/src/hash-tree.cpp
index 7ee064777..6e3f86ed7 100644
--- a/src/hash-tree.cpp
+++ b/src/hash-tree.cpp
@@ -182,7 +182,8 @@ bool hash_tree::update_dirty_page(address_range &ar, page_hash_tree_cache::entry
     }
     const auto offset = paddr_page - ar.get_start();
     const auto page_view = std::span<const unsigned char, HASH_TREE_PAGE_SIZE>{base + offset, HASH_TREE_PAGE_SIZE};
-    page_hash_tree_cache::simd_hasher<hasher_type> queue;
+    variant_hasher h{m_hash_function};
+    page_hash_tree_cache::simd_page_hasher<variant_hasher> queue(h);
     auto &stats = m_page_cache.get_stats_ref();
     auto ret = m_page_cache.enqueue_hash_entry(queue, page_view, entry, stats);
     stats.inner_page_hashes += queue.flush();
@@ -195,8 +196,8 @@ bool hash_tree::update_dirty_page(address_range &ar, page_hash_tree_cache::entry
     return ret;
 }
 
-bool hash_tree::enqueue_hash_dirty_page(page_hash_tree_cache::simd_hasher<hasher_type> &queue, address_range &ar,
-    page_hash_tree_cache::entry &entry, page_hash_tree_cache_stats &stats) {
+bool hash_tree::enqueue_hash_dirty_page(page_hash_tree_cache::simd_page_hasher<variant_hasher> &queue,
+    address_range &ar, page_hash_tree_cache::entry &entry, page_hash_tree_cache_stats &stats) {
     const auto paddr_page = entry.get_paddr_page();
     const auto *base = ar.get_host_memory();
     if (!ar.is_memory() || base == nullptr || !ar.contains_absolute(paddr_page, HASH_TREE_PAGE_SIZE)) {
@@ -214,12 +215,12 @@ bool hash_tree::return_updated_dirty_pages(address_ranges ars, dirty_pages &batc
     }
     //??D The batch size past which we switch to parallel updates needs to be tuned empirically
     const int batch_size = static_cast<int>(batch.size());
-    const int threads = (m_concurrency > 1 && batch_size > m_concurrency) ? m_concurrency : 1;
-    // ??(edubart): Using block size > 1 with multi-threading was not beneficial in benchmarks
-    // most likely due to work imbalance between threads leading to less effective OpenMP dynamic scheduling.
-    // However for single-threaded execution, a larger block size should always improve performance by
-    // maximizing SIMD hashing.
-    const int block_size = threads > 1 ? 1 : page_hash_tree_cache::simd_hasher<hasher_type>::QUEUE_MAX_PAGE_COUNT;
+    // Set block size to maximize SIMD lane utilization by hashing multiple pages together
+    const int block_size = std::min(static_cast<int>(variant_hasher{m_hash_function}.get_optimal_lane_count()),
+        page_hash_tree_cache::simd_page_hasher<variant_hasher>::QUEUE_MAX_PAGE_COUNT);
+    // It's only worth to use multi-threading if we have enough entries to process
+    const int threads =
+        (m_concurrency > 1 && batch_size > m_concurrency && batch_size > block_size) ? m_concurrency : 1;
     uint64_t update_failures{0};
     uint64_t word_hits{0};
     uint64_t word_misses{0};
@@ -231,7 +232,8 @@ bool hash_tree::return_updated_dirty_pages(address_ranges ars, dirty_pages &batc
         word_hits, word_misses, page_changes, inner_page_hashes, pristine_pages, non_pristine_pages)
     for (int i = 0; i < batch_size; i += block_size) {
         // Queue entries to be hashed
-        page_hash_tree_cache::simd_hasher<hasher_type> queue;
+        variant_hasher h{m_hash_function};
+        page_hash_tree_cache::simd_page_hasher<variant_hasher> queue(h);
         page_hash_tree_cache_stats stats;
         for (int j = i; j < std::min(batch_size, i + block_size); ++j) {
             auto &[ar_index, br, changed] = batch[j];
@@ -376,13 +378,13 @@ void hash_tree::update_and_clear_dense_node_entries(dense_node_entries &batch, i
     }
     //??D The batch size past which we switch to parallel updates needs to be tuned empirically
     const int batch_size = static_cast<int>(batch.size());
+    const int block_size = static_cast<int>(variant_hasher{m_hash_function}.get_optimal_lane_count());
     // It's only worth to use multi-threading if we have enough entries to process
-    const int threads =
-        (m_concurrency > 1 && batch_size > m_concurrency * hasher_type::MAX_LANE_COUNT) ? m_concurrency : 1;
-    const int block_size = hasher_type::MAX_LANE_COUNT;
+    const int threads = (m_concurrency > 1 && batch_size > m_concurrency * block_size) ? m_concurrency : 1;
 #pragma omp parallel for schedule(static) if (threads > 1) num_threads(threads)
     for (int block_start = 0; block_start < batch_size; block_start += block_size) {
-        simd_concat_hasher<hasher_type, const_machine_hash_view> queue;
+        variant_hasher h{m_hash_function};
+        simd_concat_hasher<variant_hasher, const_machine_hash_view> queue(h);
         for (int i = block_start; i < std::min(batch_size, block_start + block_size); ++i) {
             auto &[dht, offset] = batch[i];
             auto child_size = UINT64_C(1) << (log2_size - 1);
@@ -461,7 +463,8 @@ bool hash_tree::update_sparse_tree(address_ranges ars, const changed_address_ran
             changed.emplace(ar_parent_node.log2_size, ar_node.parent);
         }
     }
-    simd_concat_hasher<hasher_type, const_machine_hash_view> queue;
+    variant_hasher h{m_hash_function};
+    simd_concat_hasher<variant_hasher, const_machine_hash_view> queue(h);
     int last_log2_size = -1;
     while (!changed.empty()) {
         auto [log2_size, inner_index] = changed.top();
@@ -559,7 +562,7 @@ machine_hash hash_tree::get_node_hash(address_ranges ars, uint64_t address, int
 }
 
 bool hash_tree::verify(address_ranges ars) const {
-    hasher_type h;
+    variant_hasher h{m_hash_function};
     bool ret = true;
     for (auto ar_node_index = get_ar_sparse_node_index(0); const auto &ar : ars) {
         const std::span<const unsigned char> mem{ar.get_host_memory(), ar.get_length()};
@@ -667,7 +670,7 @@ bool hash_tree::update_words(address_ranges ars, dirty_words_type dirty_words) {
     uint64_t update_failures{0}; // NOLINT(misc-const-correctness)
     int ar_index = 0;
     int max_level_count = 0;
-    hasher_type h;
+    variant_hasher h{m_hash_function};
     std::vector<uint64_t> curr_page_node;
     std::vector<uint64_t> next_page_node;
     dense_node_entries curr_dense_node;
@@ -775,7 +778,7 @@ bool hash_tree::update_words(address_ranges ars, dirty_words_type dirty_words) {
 bool hash_tree::update_page(address_ranges ars, uint64_t paddr_page) {
     paddr_page >>= HASH_TREE_LOG2_PAGE_SIZE;
     paddr_page <<= HASH_TREE_LOG2_PAGE_SIZE;
-    hasher_type h;
+    variant_hasher h{m_hash_function};
     // Find address range where page might lie
     auto it = std::ranges::find_if(ars,
         [paddr_page](auto &ar) { return ar.contains_absolute(paddr_page, HASH_TREE_PAGE_SIZE); });
@@ -831,8 +834,8 @@ bool hash_tree::update_page(address_ranges ars, uint64_t paddr_page) {
     return true;
 }
 
-hash_tree::pristine_hashes hash_tree::get_pristine_hashes() {
-    hasher_type h;
+hash_tree::pristine_hashes hash_tree::get_pristine_hashes(hash_function_type hash_function) {
+    variant_hasher h{hash_function};
     pristine_hashes hashes{};
     std::array<unsigned char, HASH_TREE_WORD_SIZE> zero{};
     machine_hash hash = get_hash(h, zero);
@@ -852,20 +855,22 @@ static int get_concurrency([[maybe_unused]] int value) {
 #endif
 }
 
-hash_tree::hash_tree(const hash_tree_config &config, uint64_t concurrency, const_address_ranges ars) :
+hash_tree::hash_tree(const hash_tree_config &config, uint64_t concurrency, const_address_ranges ars,
+    hash_function_type hash_function) :
 #ifdef HAS_SIGNPOSTS
     m_log{os_log_create("io.cartesi.machine-emulator", "hash-tree")},
     m_spid_update{os_signpost_id_generate(m_log)},
     m_spid_update_page_hashes{os_signpost_id_generate(m_log)},
     m_spid_update_dense_trees{os_signpost_id_generate(m_log)},
     m_spid_update_sparse_tree{os_signpost_id_generate(m_log)},
-    m_page_cache{m_log, hasher_type{}, config.phtc_size},
+    m_page_cache{m_log, variant_hasher{hash_function}, config.phtc_size},
 #else
-    m_page_cache{hasher_type{}, config.phtc_size},
+    m_page_cache{variant_hasher{hash_function}, config.phtc_size},
 #endif
     m_sparse_nodes{create_nodes(ars)},
-    m_pristine_hashes{get_pristine_hashes()},
-    m_concurrency{get_concurrency(static_cast<int>(concurrency))} {
+    m_pristine_hashes{get_pristine_hashes(hash_function)},
+    m_concurrency{get_concurrency(static_cast<int>(concurrency))},
+    m_hash_function{hash_function} {
 }
 
 void hash_tree::check_address_ranges(const_address_ranges ars) {
diff --git a/src/hash-tree.h b/src/hash-tree.h
index dcbdf8770..1043d14bc 100644
--- a/src/hash-tree.h
+++ b/src/hash-tree.h
@@ -25,13 +25,13 @@
 #include "hash-tree-constants.h"
 #include "hash-tree-proof.h"
 #include "hash-tree-stats.h"
-#include "keccak-256-hasher.h"
 #include "machine-address-ranges.h"
 #include "machine-config.h"
 #include "machine-hash.h"
 #include "page-hash-tree-cache.h"
 #include "signposts.h"
 #include "unique-c-ptr.h"
+#include "variant-hasher.h"
 
 namespace cartesi {
 
@@ -114,14 +114,14 @@ class hash_tree {
     using const_address_ranges = hash_tree_view<const machine_address_ranges>;
 
 public:
-    using hasher_type = keccak_256_hasher;
     using proof_type = hash_tree_proof;
 
     using dirty_words_type = std::unordered_set<uint64_t>;
     using nodes_type = std::vector<node_type>;
     using sibling_hashes_type = std::vector<machine_hash>;
 
-    hash_tree(const hash_tree_config &config, uint64_t concurrency, const_address_ranges ars);
+    hash_tree(const hash_tree_config &config, uint64_t concurrency, const_address_ranges ars,
+        hash_function_type hash_function);
 
     hash_tree(const hash_tree &other) = delete;
     hash_tree(hash_tree &&other) = delete;
@@ -155,11 +155,11 @@ class hash_tree {
 
     machine_hash get_dense_node_hash(address_range &ar, uint64_t address, int log2_size);
 
-    static pristine_hashes get_pristine_hashes();
+    static pristine_hashes get_pristine_hashes(hash_function_type hash_function);
 
     bool update_dirty_pages(address_ranges ars, changed_address_ranges &changed_ars);
     bool update_dirty_page(address_range &ar, page_hash_tree_cache::entry &entry, bool &changed);
-    bool enqueue_hash_dirty_page(page_hash_tree_cache::simd_hasher<hasher_type> &queue, address_range &ar,
+    bool enqueue_hash_dirty_page(page_hash_tree_cache::simd_page_hasher<variant_hasher> &queue, address_range &ar,
         page_hash_tree_cache::entry &entry, page_hash_tree_cache_stats &stats);
     bool return_updated_dirty_pages(address_ranges ars, dirty_pages &batch, changed_address_ranges &changed_ars);
 
@@ -191,6 +191,7 @@ class hash_tree {
     nodes_type m_sparse_nodes;
     const pristine_hashes m_pristine_hashes;
     int m_concurrency;
+    hash_function_type m_hash_function;
 
     uint64_t m_sparse_node_hashes{0};
     std::array<uint64_t, HASH_TREE_LOG2_ROOT_SIZE> m_dense_node_hashes{};
diff --git a/src/i-hasher.h b/src/i-hasher.h
index faaf30b96..1b67965cb 100644
--- a/src/i-hasher.h
+++ b/src/i-hasher.h
@@ -53,11 +53,18 @@ class i_hasher { // CRTP
     }
 
 public:
+    static constexpr int MAX_LANE_COUNT = DERIVED::MAX_LANE_COUNT; ///< Number of maximum supported SIMD lanes
+
     template <ContiguousRangeOfByteLike D>
     void hash(D &&data, machine_hash_view hash) noexcept { // NOLINT(cppcoreguidelines-missing-std-forward)
-        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        auto data_span = std::span<const unsigned char>{reinterpret_cast<const uint8_t *>(std::ranges::data(data)),
-            std::ranges::size(data)};
+        const auto data_span =
+            std::span<const unsigned char>{// NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+                reinterpret_cast<const uint8_t *>(std::ranges::data(data)), std::ranges::size(data)};
+        if (data_span.size() == HASH_TREE_WORD_SIZE) { // Special case for hash tree word hashing
+            return derived().do_simd_concat_hash(
+                array2d<std::span<const unsigned char>, 1, 1>{{{const_hash_tree_word_view{data_span}}}},
+                std::array<machine_hash_view, 1>{hash});
+        }
         return derived().do_simd_concat_hash(array2d<std::span<const unsigned char>, 1, 1>{{{data_span}}},
             std::array<machine_hash_view, 1>{hash});
     }
@@ -70,12 +77,17 @@ class i_hasher { // CRTP
     template <ContiguousRangeOfByteLike D>
     void concat_hash(D &&data1, D &&data2, // NOLINT(cppcoreguidelines-missing-std-forward)
         machine_hash_view hash) noexcept {
-        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        auto data1_span = std::span<const unsigned char>{reinterpret_cast<const uint8_t *>(std::ranges::data(data1)),
-            std::ranges::size(data1)};
-        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        auto data2_span = std::span<const unsigned char>{reinterpret_cast<const uint8_t *>(std::ranges::data(data2)),
-            std::ranges::size(data2)};
+        auto data1_span = std::span<const unsigned char>{// NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+            reinterpret_cast<const uint8_t *>(std::ranges::data(data1)), std::ranges::size(data1)};
+        auto data2_span = std::span<const unsigned char>{// NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+            reinterpret_cast<const uint8_t *>(std::ranges::data(data2)), std::ranges::size(data2)};
+        if (data1_span.size() == MACHINE_HASH_SIZE &&
+            data2_span.size() == MACHINE_HASH_SIZE) { // Special case for hash tree hash concatenation
+            return derived().do_simd_concat_hash(
+                array2d<const_machine_hash_view, 2, 1>{
+                    {{const_machine_hash_view{data1_span}}, {const_machine_hash_view{data2_span}}}},
+                std::array<machine_hash_view, 1>{hash});
+        }
         return derived().do_simd_concat_hash(
             array2d<std::span<const unsigned char>, 2, 1>{{{data1_span}, {data2_span}}},
             std::array<machine_hash_view, 1>{hash});
@@ -86,6 +98,13 @@ class i_hasher { // CRTP
             std::array<machine_hash_view, 1>{hash});
     }
 
+    // \brief Hashes the concatenation of data using multiple SIMD lanes.
+    // \tparam LaneCount Number of SIMD lanes
+    // \tparam ConcatCount Number of concatenated data items
+    // \tparam Extent Extent of the data span
+    // \param data Data to hash, as a multi-dimensional array of spans
+    // \param hash Array of machine hashes to store the results
+    // \warning When LaneCount is greater than 1, it is assumed data spans have same size, there is no check for that.
     template <size_t ConcatCount, size_t ParallelCount>
     void simd_concat_hash(const array2d<const_hash_tree_word_view, ConcatCount, ParallelCount> &data,
         const std::array<machine_hash_view, ParallelCount> &hash) noexcept {
@@ -95,8 +114,8 @@ class i_hasher { // CRTP
     // \brief Gets the optimal number of SIMD lanes for hashing.
     // \returns The optimal number of SIMD lanes for hashing.
     // \details This value is architecture-dependent and may vary based on the available instruction sets.
-    static size_t get_optimal_lane_count() noexcept {
-        return DERIVED::do_get_optimal_lane_count();
+    size_t get_optimal_lane_count() const noexcept {
+        return derived().do_get_optimal_lane_count();
     }
 };
 
diff --git a/src/json-util.cpp b/src/json-util.cpp
index 5cf6ae232..c1c7645fe 100644
--- a/src/json-util.cpp
+++ b/src/json-util.cpp
@@ -582,6 +582,26 @@ static uarch_interpreter_break_reason uarch_interpreter_break_reason_from_name(c
     throw std::domain_error{"invalid uarch interpreter break reason"};
 }
 
+static hash_function_type hash_function_from_name(const std::string &name) {
+    const static std::unordered_map<std::string, hash_function_type> g_hash_function_name = {
+        {"sha256", hash_function_type::sha256}, {"keccak256", hash_function_type::keccak256}};
+    auto got = g_hash_function_name.find(name);
+    if (got == g_hash_function_name.end()) {
+        throw std::domain_error{"invalid hash function type"};
+    }
+    return got->second;
+}
+
+static std::string hash_function_to_name(hash_function_type hf) {
+    switch (hf) {
+        case hash_function_type::keccak256:
+            return "keccak256";
+        case hash_function_type::sha256:
+            return "sha256";
+    }
+    throw std::domain_error{"invalid hash function type"};
+}
+
 static std::string access_type_to_name(access_type at) {
     switch (at) {
         case access_type::read:
@@ -1411,6 +1431,24 @@ template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t
 template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key, memory_range_config &value,
     const std::string &path);
 
+template <typename K>
+void ju_get_opt_field(const nlohmann::json &j, const K &key, hash_function_type &value, const std::string &path) {
+    if (!contains(j, key, path)) {
+        return;
+    }
+    const auto &jk = j[key];
+    if (!jk.is_string()) {
+        throw std::invalid_argument("\""s + path + to_string(key) + "\" not a string");
+    }
+    value = hash_function_from_name(jk.template get<std::string>());
+}
+
+template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, hash_function_type &value,
+    const std::string &path);
+
+template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key, hash_function_type &value,
+    const std::string &path);
+
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, hash_tree_config &value, const std::string &path) {
     if (!contains(j, key, path)) {
@@ -1424,6 +1462,7 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, hash_tree_config &v
     ju_get_opt_field(jconfig, "sht_filename"s, value.sht_filename, new_path);
     ju_get_opt_field(jconfig, "phtc_filename"s, value.phtc_filename, new_path);
     ju_get_opt_field(jconfig, "phtc_size"s, value.phtc_size, new_path);
+    ju_get_opt_field(jconfig, "hash_function"s, value.hash_function, new_path);
 }
 
 template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, hash_tree_config &value,
@@ -1959,8 +1998,8 @@ void to_json(nlohmann::json &j, const memory_range_config &config) {
 
 void to_json(nlohmann::json &j, const hash_tree_config &config) {
     j = nlohmann::json{{"shared", config.shared}, {"create", config.create}, {"truncate", config.truncate},
-        {"sht_filename", config.sht_filename}, {"phtc_filename", config.phtc_filename},
-        {"phtc_size", config.phtc_size}};
+        {"sht_filename", config.sht_filename}, {"phtc_filename", config.phtc_filename}, {"phtc_size", config.phtc_size},
+        {"hash_function", hash_function_to_name(config.hash_function)}};
 }
 
 void to_json(nlohmann::json &j, const registers_state &config) {
diff --git a/src/json-util.h b/src/json-util.h
index 9d259640f..24be6237b 100644
--- a/src/json-util.h
+++ b/src/json-util.h
@@ -513,6 +513,16 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, uarch_processor_con
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, uarch_config &value, const std::string &path = "params/");
 
+/// \brief Attempts to load a hash_function_type object from a field in a JSON object
+/// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
+/// \param j JSON object to load from
+/// \param key Key to load value from
+/// \param value Object to store value
+/// \param path Path to j
+template <typename K>
+void ju_get_opt_field(const nlohmann::json &j, const K &key, hash_function_type &value,
+    const std::string &path = "params/");
+
 /// \brief Attempts to load an hash_tree_config object from a field in a JSON object
 /// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
 /// \param j JSON object to load from
diff --git a/src/jsonrpc-discover.json b/src/jsonrpc-discover.json
index 8594bdae5..18426ce06 100644
--- a/src/jsonrpc-discover.json
+++ b/src/jsonrpc-discover.json
@@ -1814,9 +1814,6 @@
         "title": "HashTreeConfig",
         "type": "object",
         "properties": {
-          "hasher": {
-            "type": "string"
-          },
           "shared": {
             "type": "boolean"
           },
@@ -1834,6 +1831,9 @@
           },
           "phtc_size": {
             "$ref": "#/components/schemas/UnsignedInteger"
+          },
+          "hash_function": {
+            "$ref": "#/components/schemas/HashFunctionType"
           }
         }
       },
@@ -1887,6 +1887,10 @@
         },
         "required": ["ram"]
       },
+      "HashFunctionType": {
+        "title": "HashFunctionType",
+        "enum": ["keccak256", "sha256"]
+      },
       "InterpreterBreakReason": {
         "title": "InterpreterBreakReason",
         "enum": [
diff --git a/src/keccak-256-hasher.h b/src/keccak-256-hasher.h
index 16c522139..7d8540c89 100644
--- a/src/keccak-256-hasher.h
+++ b/src/keccak-256-hasher.h
@@ -17,18 +17,6 @@
 #ifndef KECCAK_256_HASHER_H
 #define KECCAK_256_HASHER_H
 
-// TODO(edubart): remove this hack
-#if 0 // NOLINT(readability-avoid-unconditional-preprocessor-if)
-#include "sha-256-hasher.h"
-
-namespace cartesi {
-
-using keccak_256_hasher = sha_256_hasher;
-
-} // namespace cartesi
-
-#else
-
 #include <array>
 #include <cstddef>
 #include <cstdint>
@@ -104,37 +92,12 @@ MULTIVERSION_AMD64_AVX512_BMI_BMI2 void keccak_256_hash_2x8(const array2d<const_
 
 class keccak_256_hasher final : public i_hasher<keccak_256_hasher> {
 public:
-    static constexpr int MAX_LANE_COUNT = 8; ///< Number of maximum supported SIMD lanes
-
-    /// \brief Default constructor
-    keccak_256_hasher() = default;
-
-    /// \brief Default destructor
-    ~keccak_256_hasher() = default;
+    static constexpr int MAX_LANE_COUNT = 8;
 
-    /// \brief No copy constructor
-    keccak_256_hasher(const keccak_256_hasher &) = delete;
-    /// \brief No move constructor
-    keccak_256_hasher(keccak_256_hasher &&) = delete;
-    /// \brief No copy assignment
-    keccak_256_hasher &operator=(const keccak_256_hasher &) = delete;
-    /// \brief No move assignment
-    keccak_256_hasher &operator=(keccak_256_hasher &&) = delete;
-
-    // \brief Hashes the concatenation of data in SIMD using Keccak-256
-    // \tparam LaneCount Number of SIMD lanes
-    // \tparam ConcatCount Number of concatenated data items
-    // \tparam Extent Extent of the data span
-    // \param data Data to hash, as a multi-dimensional array of spans
-    // \param hash Array of machine hashes to store the results
-    // \warning When LaneCount is greater than 1, it is assumed data spans have same size, there is no check for that.
     template <size_t ConcatCount, size_t LaneCount, size_t Extent>
     static void do_simd_concat_hash(const array2d<std::span<const unsigned char, Extent>, ConcatCount, LaneCount> &data,
         const std::array<machine_hash_view, LaneCount> &hash) noexcept;
 
-    // \brief Gets the optimal number of SIMD lanes for SHA-256
-    // \returns The optimal number of SIMD lanes for SHA-256
-    // \details This value is architecture-dependent and may vary based on the available instruction sets.
     static size_t do_get_optimal_lane_count() noexcept {
         return keccak_256_get_optimal_lane_count();
     }
@@ -307,6 +270,4 @@ inline void keccak_256_hasher::do_simd_concat_hash<2, 16, MACHINE_HASH_SIZE>(
 
 } // namespace cartesi
 
-#endif // #if
-
 #endif
diff --git a/src/machine-config.h b/src/machine-config.h
index 58754f8b5..fe10c7ec6 100644
--- a/src/machine-config.h
+++ b/src/machine-config.h
@@ -26,6 +26,7 @@
 #include "riscv-constants.h"
 #include "shadow-registers.h"
 #include "shadow-uarch-state.h"
+#include "variant-hasher.h"
 
 namespace cartesi {
 
@@ -157,6 +158,7 @@ struct hash_tree_config final {
     std::string sht_filename;  ///< Backing storage for sparse hash-tree
     std::string phtc_filename; ///< Backing storage for page hash-tree cache
     uint64_t phtc_size{8192};  ///< Max number of pages in page hash-tree cache
+    hash_function_type hash_function{hash_function_type::keccak256}; ///< Hash function type to use in the hash-tree
 };
 
 /// \brief Machine state config
diff --git a/src/machine.cpp b/src/machine.cpp
index 450b3772b..cc22287c3 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -80,6 +80,7 @@
 #include "uarch-state-access.h"
 #include "uarch-step.h"
 #include "unique-c-ptr.h"
+#include "variant-hasher.h"
 #include "virtio-address-range.h"
 
 /// \file
@@ -301,7 +302,7 @@ machine::machine(machine_config c, machine_runtime_config r) :
     m_c{std::move(c)}, // NOLINT(hicpp-move-const-arg,performance-move-const-arg)
     m_r{std::move(r)}, // NOLINT(hicpp-move-const-arg,performance-move-const-arg)
     m_ars{m_c},
-    m_ht{m_c.hash_tree, m_r.concurrency.update_hash_tree, m_ars},
+    m_ht{m_c.hash_tree, m_r.concurrency.update_hash_tree, m_ars, m_c.hash_tree.hash_function},
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
     m_s{reinterpret_cast<processor_state *>(
         m_ars.find(AR_SHADOW_STATE_START, AR_SHADOW_STATE_LENGTH).get_host_memory())},
@@ -1756,6 +1757,10 @@ void machine::send_cmio_response(uint16_t reason, const unsigned char *data, uin
 
 access_log machine::log_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
     const access_log::type &log_type) {
+    if (m_c.hash_tree.hash_function != hash_function_type::keccak256) {
+        throw std::runtime_error{
+            "access logs can only be used with hash tree configured with Keccak-256 hash function"};
+    }
     auto root_hash_before = get_root_hash();
     access_log log(log_type);
     // Call send_cmio_response  with the recording state accessor
@@ -1764,10 +1769,6 @@ access_log machine::log_send_cmio_response(uint16_t reason, const unsigned char
         [[maybe_unused]] auto note = a.make_scoped_note("send_cmio_response");
         cartesi::send_cmio_response(a, reason, data, length);
     }
-    // Verify access log before returning
-    if (!update_hash_tree()) {
-        throw std::runtime_error{"update hash tree failed"};
-    }
     auto root_hash_after = get_root_hash();
     verify_send_cmio_response(reason, data, length, root_hash_before, log, root_hash_after);
     return log;
@@ -1775,7 +1776,7 @@ access_log machine::log_send_cmio_response(uint16_t reason, const unsigned char
 
 void machine::verify_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
     const machine_hash &root_hash_before, const access_log &log, const machine_hash &root_hash_after) {
-    replay_send_cmio_state_access::context context(log, root_hash_before);
+    replay_send_cmio_state_access::context context{log, root_hash_before, hash_function_type::keccak256};
     // Verify all intermediate state transitions
     replay_send_cmio_state_access a(context);
     cartesi::send_cmio_response(a, reason, data, length);
@@ -1788,6 +1789,10 @@ void machine::verify_send_cmio_response(uint16_t reason, const unsigned char *da
 }
 
 void machine::reset_uarch() {
+    if (m_c.hash_tree.hash_function != hash_function_type::keccak256) {
+        throw std::runtime_error{
+            "microarchitecture can only be used with hash tree configured with Keccak-256 hash function"};
+    }
     write_reg(reg::uarch_halt_flag, UARCH_HALT_FLAG_INIT);
     write_reg(reg::uarch_pc, UARCH_PC_INIT);
     write_reg(reg::uarch_cycle, UARCH_CYCLE_INIT);
@@ -1803,6 +1808,10 @@ void machine::reset_uarch() {
 }
 
 access_log machine::log_reset_uarch(const access_log::type &log_type) {
+    if (m_c.hash_tree.hash_function != hash_function_type::keccak256) {
+        throw std::runtime_error{
+            "microarchitecture can only be used with hash tree configured with Keccak-256 hash function"};
+    }
     const machine_hash root_hash_before = get_root_hash();
     // Call uarch_reset_state with a uarch_record_state_access object
     access_log log(log_type);
@@ -1811,10 +1820,6 @@ access_log machine::log_reset_uarch(const access_log::type &log_type) {
         [[maybe_unused]] auto note = a.make_scoped_note("reset_uarch_state");
         uarch_reset_state(a);
     }
-    // Verify access log before returning
-    if (!update_hash_tree()) {
-        throw std::runtime_error{"update hash tree failed"};
-    }
     const auto root_hash_after = get_root_hash();
     verify_reset_uarch(root_hash_before, log, root_hash_after);
     return log;
@@ -1841,6 +1846,10 @@ access_log machine::log_step_uarch(const access_log::type &log_type) {
     if (read_reg(reg::iunrep) != 0) {
         throw std::runtime_error("microarchitecture cannot be used with unreproducible machines");
     }
+    if (m_c.hash_tree.hash_function != hash_function_type::keccak256) {
+        throw std::runtime_error{
+            "microarchitecture can only be used with hash tree configured with Keccak-256 hash function"};
+    }
     auto root_hash_before = get_root_hash();
     access_log log(log_type);
     // Call interpret with a logged state access object
@@ -1879,6 +1888,10 @@ machine_config machine::get_default_config() {
 
 // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
 uarch_interpreter_break_reason machine::run_uarch(uint64_t uarch_cycle_end) {
+    if (m_c.hash_tree.hash_function != hash_function_type::keccak256) {
+        throw std::runtime_error{
+            "microarchitecture can only be used with hash tree configured with Keccak-256 hash function"};
+    }
     if (read_reg(reg::iunrep) != 0) {
         throw std::runtime_error("microarchitecture cannot be used with unreproducible machines");
     }
@@ -1888,17 +1901,15 @@ uarch_interpreter_break_reason machine::run_uarch(uint64_t uarch_cycle_end) {
 }
 
 interpreter_break_reason machine::log_step(uint64_t mcycle_count, const std::string &filename) {
-    if (!update_hash_tree()) {
-        throw std::runtime_error{"update hash tree failed"};
-    }
-    // Ensure that the microarchitecture is reset
-    auto current_uarch_state_hash =
-        get_node_hash(AR_SHADOW_UARCH_STATE_START, UARCH_STATE_LOG2_SIZE, skip_hash_tree_update);
-    if (current_uarch_state_hash != get_uarch_pristine_state_hash()) {
-        throw std::runtime_error{"microarchitecture is not reset"};
+    if (m_c.hash_tree.hash_function == hash_function_type::keccak256) {
+        // Ensure that the microarchitecture is reset
+        auto current_uarch_state_hash = get_node_hash(AR_SHADOW_UARCH_STATE_START, UARCH_STATE_LOG2_SIZE);
+        if (current_uarch_state_hash != get_uarch_pristine_state_hash()) {
+            throw std::runtime_error{"microarchitecture is not reset"};
+        }
     }
     auto root_hash_before = get_root_hash();
-    record_step_state_access::context context(filename);
+    record_step_state_access::context context(filename, m_c.hash_tree.hash_function);
     record_step_state_access a(context, *this);
     uint64_t mcycle_end{};
     if (__builtin_add_overflow(a.read_mcycle(), mcycle_count, &mcycle_end)) {
diff --git a/src/machine.h b/src/machine.h
index b4b50f602..a065a3b48 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -47,6 +47,7 @@
 #include "uarch-cycle-root-hashes.h"
 #include "uarch-interpret.h"
 #include "uarch-processor-state.h"
+#include "variant-hasher.h"
 #include "virtio-address-range.h"
 
 namespace cartesi {
@@ -582,6 +583,11 @@ class machine final {
     bool get_soft_yield() const {
         return m_r.soft_yield;
     }
+
+    /// \brief Returns hash tree hash function
+    hash_function_type get_hash_function() const {
+        return m_c.hash_tree.hash_function;
+    }
 };
 
 } // namespace cartesi
diff --git a/src/merkle-tree-hash.cpp b/src/merkle-tree-hash.cpp
index 7efa3e8bb..5797bf9ba 100644
--- a/src/merkle-tree-hash.cpp
+++ b/src/merkle-tree-hash.cpp
@@ -21,16 +21,16 @@
 #include <cstdio>
 #include <cstdlib>
 #include <cstring>
+#include <exception>
 #include <iostream>
 #include <tuple>
 
 #include "back-merkle-tree.h"
 #include "i-hasher.h"
-#include "keccak-256-hasher.h"
 #include "unique-c-ptr.h"
+#include "variant-hasher.h"
 
 using namespace cartesi;
-using hasher_type = keccak_256_hasher;
 
 /// \brief Checks if string matches prefix and captures remaninder
 /// \param pre Prefix to match in str.
@@ -80,12 +80,12 @@ static void print_hash(const machine_hash &hash, FILE *f) {
 /// \param f File to read from
 /// \returns Hash if successful, nothing otherwise
 static std::optional<machine_hash> read_hash(FILE *f) {
-    std::array<char, hasher_type::hash_size * 2> hex_hash{};
+    std::array<char, variant_hasher::hash_size * 2> hex_hash{};
     if (fread(hex_hash.data(), 1, hex_hash.size(), f) != hex_hash.size()) {
         return {};
     }
     machine_hash h;
-    for (size_t i = 0; i < hasher_type::hash_size; ++i) {
+    for (size_t i = 0; i < variant_hasher::hash_size; ++i) {
         std::array<char, 3> hex_c{hex_hash[2 * i], hex_hash[2 * i + 1], '\0'};
         unsigned c = 0;
         // NOLINTNEXTLINE(cert-err34-c): we just generated the string so we don't need to verify it
@@ -115,7 +115,7 @@ __attribute__((__format__(__printf__, 1, 2))) static void error(const char *fmt,
 /// \param word Pointer to word data. Must contain 2^log2_word_size bytes
 /// \param log2_word_size Log<sub>2</sub> of word size
 /// \param hash Receives the word hash
-static void get_word_hash(hasher_type &h, const unsigned char *word, int log2_word_size, machine_hash &hash) {
+static void get_word_hash(variant_hasher &h, const unsigned char *word, int log2_word_size, machine_hash &hash) {
     h.hash(std::span<const unsigned char>(word, 1 << log2_word_size), hash);
 }
 
@@ -126,7 +126,7 @@ static void get_word_hash(hasher_type &h, const unsigned char *word, int log2_wo
 /// \param log2_leaf_size Log<sub>2</sub> of leaf size
 /// \param log2_word_size Log<sub>2</sub> of word size
 /// \returns Merkle hash of leaf data
-static machine_hash get_leaf_hash(hasher_type &h, const unsigned char *leaf_data, int log2_leaf_size,
+static machine_hash get_leaf_hash(variant_hasher &h, const unsigned char *leaf_data, int log2_leaf_size,
     int log2_word_size) {
     assert(log2_word_size >= 1);
     assert(log2_leaf_size >= log2_word_size);
@@ -142,17 +142,6 @@ static machine_hash get_leaf_hash(hasher_type &h, const unsigned char *leaf_data
     return leaf;
 }
 
-/// \brief Computes the Merkle hash of a leaf of data
-/// \param leaf_data Pointer to buffer containing leaf data with
-/// at least 2^log2_leaf_size bytes
-/// \param log2_leaf_size Log<sub>2</sub> of leaf size
-/// \param log2_word_size Log<sub>2</sub> of word size
-/// \returns Merkle hash of leaf data
-static machine_hash get_leaf_hash(const unsigned char *leaf_data, int log2_leaf_size, int log2_word_size) {
-    hasher_type h;
-    return get_leaf_hash(h, leaf_data, log2_leaf_size, log2_word_size);
-}
-
 /// \brief Prints help message
 static void help(const char *name) {
     std::ignore = fprintf(stderr, R"(Usage:
@@ -196,7 +185,7 @@ The hash function used is Keccak-256.
     exit(0);
 }
 
-int main(int argc, char *argv[]) {
+int main(int argc, char *argv[]) try {
     const char *input_name = nullptr;
     int log2_word_size = 3;
     int log2_leaf_size = 12;
@@ -244,7 +233,9 @@ int main(int argc, char *argv[]) {
         return 1;
     }
 
-    back_merkle_tree back_tree{log2_root_size, log2_leaf_size, log2_word_size};
+    const auto hash_function = hash_function_type::keccak256;
+    back_merkle_tree back_tree{log2_root_size, log2_leaf_size, log2_word_size, hash_function};
+    variant_hasher h{hash_function};
 
     const uint64_t max_leaves = UINT64_C(1) << (log2_root_size - log2_leaf_size);
     uint64_t leaf_count = 0;
@@ -264,7 +255,7 @@ int main(int argc, char *argv[]) {
         // Pad leaf with zeros if file ended before next leaf boundary
         memset(leaf_buf.get() + got, 0, leaf_size - got);
         // Compute leaf hash
-        auto leaf_hash = get_leaf_hash(leaf_buf.get(), log2_leaf_size, log2_word_size);
+        auto leaf_hash = get_leaf_hash(h, leaf_buf.get(), log2_leaf_size, log2_word_size);
         // Add leaf to incremental tree
         back_tree.push_back(leaf_hash);
         // Compare the root hash for the incremental tree and the
@@ -273,4 +264,10 @@ int main(int argc, char *argv[]) {
     }
     print_hash(back_tree.get_root_hash(), stdout);
     return 0;
+} catch (const std::exception &e) {
+    error("exception: %s\n", e.what());
+    return 1;
+} catch (...) {
+    error("unknown exception\n");
+    return 1;
 }
diff --git a/src/page-hash-tree-cache.h b/src/page-hash-tree-cache.h
index 02dbc5bcc..fbab45bd5 100644
--- a/src/page-hash-tree-cache.h
+++ b/src/page-hash-tree-cache.h
@@ -29,7 +29,6 @@
 #include <span>
 #include <unordered_map>
 
-#include <boost/container/static_vector.hpp>
 #include <boost/intrusive/list.hpp>
 
 #include "address-range-constants.h"
@@ -246,7 +245,7 @@ class page_hash_tree_cache {
     };
 
     template <IHasher hasher_type>
-    class simd_hasher {
+    class simd_page_hasher {
         struct leaf_entry {
             const_hash_tree_word_view data;
             machine_hash_view result;
@@ -270,7 +269,6 @@ class page_hash_tree_cache {
             ((UINT64_C(1) << ((HASH_TREE_LOG2_PAGE_SIZE - HASH_TREE_LOG2_WORD_SIZE) - 1))) *
             hasher_type::MAX_LANE_COUNT;
 
-        hasher_type m_hasher;
         simd_data_hasher<hasher_type, const_hash_tree_word_view> m_leaves_queue;
         simd_concat_hasher<hasher_type, const_machine_hash_view> m_concat_queue;
         circular_buffer<dirty_entry, QUEUE_MAX_SIZE> m_dirty_queue;
@@ -278,6 +276,8 @@ class page_hash_tree_cache {
     public:
         static constexpr int QUEUE_MAX_PAGE_COUNT = hasher_type::MAX_LANE_COUNT;
 
+        explicit simd_page_hasher(hasher_type &hasher) : m_leaves_queue{hasher}, m_concat_queue{hasher} {}
+
         /// \brief Enqueues a leaf for hashing
         void enqueue_leaf(const_hash_tree_word_view data, page_hash_tree_view page_tree, int word_index) noexcept {
             m_leaves_queue.enqueue(data, page_tree[word_index]);
@@ -318,7 +318,7 @@ class page_hash_tree_cache {
     /// \returns True if update succeeded, false otherwise
     template <IHasher H, ContiguousRangeOfByteLike D>
     // NOLINTNEXTLINE(cppcoreguidelines-missing-std-forward)
-    bool enqueue_hash_entry(page_hash_tree_cache::simd_hasher<H> &queue, D &&d, entry &e,
+    bool enqueue_hash_entry(page_hash_tree_cache::simd_page_hasher<H> &queue, D &&d, entry &e,
         page_hash_tree_cache_stats &stats) noexcept {
         if (std::ranges::size(d) != m_page_size) {
             return false;
diff --git a/src/pristine-merkle-tree.cpp b/src/pristine-merkle-tree.cpp
index 5ab01aa1a..57edd6cf1 100644
--- a/src/pristine-merkle-tree.cpp
+++ b/src/pristine-merkle-tree.cpp
@@ -29,7 +29,7 @@
 
 namespace cartesi {
 
-pristine_merkle_tree::pristine_merkle_tree(int log2_root_size, int log2_word_size) :
+pristine_merkle_tree::pristine_merkle_tree(int log2_root_size, int log2_word_size, hash_function_type hash_function) :
     m_log2_root_size{log2_root_size},
     m_log2_word_size{log2_word_size},
     m_hashes(std::max(0, log2_root_size - log2_word_size + 1)) {
@@ -44,7 +44,7 @@ pristine_merkle_tree::pristine_merkle_tree(int log2_root_size, int log2_word_siz
     }
     std::vector<uint8_t> word(1 << log2_word_size, 0);
     assert(word.size() == (UINT64_C(1) << log2_word_size));
-    hasher_type h;
+    variant_hasher h{hash_function};
     h.hash(word, m_hashes[0]);
     for (unsigned i = 1; i < m_hashes.size(); ++i) {
         get_concat_hash(h, m_hashes[i - 1], m_hashes[i - 1], m_hashes[i]);
diff --git a/src/pristine-merkle-tree.h b/src/pristine-merkle-tree.h
index f40b289fb..9f65bf565 100644
--- a/src/pristine-merkle-tree.h
+++ b/src/pristine-merkle-tree.h
@@ -20,8 +20,8 @@
 #include <cstdint>
 #include <vector>
 
-#include "keccak-256-hasher.h"
 #include "machine-hash.h"
+#include "variant-hasher.h"
 
 /// \file
 /// \brief Pristine Merkle tree interface.
@@ -31,13 +31,10 @@ namespace cartesi {
 /// \brief Hashes of pristine subtrees for a range of sizes
 class pristine_merkle_tree {
 public:
-    /// \brief Hasher class.
-    using hasher_type = keccak_256_hasher;
-
     /// \brief Constructor
     /// \param log2_root_size Log<sub>2</sub> of root node
     /// \param log2_word_size Log<sub>2</sub> of word
-    pristine_merkle_tree(int log2_root_size, int log2_word_size);
+    pristine_merkle_tree(int log2_root_size, int log2_word_size, hash_function_type hash_function);
 
     /// \brief Returns hash of pristine subtree
     /// \param log2_size Log<sub>2</sub> of subtree size. Must be between
diff --git a/src/record-send-cmio-state-access.h b/src/record-send-cmio-state-access.h
index 55fdeda38..00f1b024c 100644
--- a/src/record-send-cmio-state-access.h
+++ b/src/record-send-cmio-state-access.h
@@ -53,16 +53,15 @@ struct i_state_access_fast_addr<record_send_cmio_state_access> {
 class record_send_cmio_state_access :
     public i_state_access<record_send_cmio_state_access>,
     public i_accept_scoped_notes<record_send_cmio_state_access> {
-    using hasher_type = hash_tree::hasher_type;
     // NOLINTBEGIN(cppcoreguidelines-avoid-const-or-ref-data-members)
     machine &m_m;      ///< Associated machine
     access_log &m_log; ///< Pointer to access log
     // NOLINTEND(cppcoreguidelines-avoid-const-or-ref-data-members)
 
-    static void get_hash(const access_data &data, machine_hash &hash) {
-        hasher_type hasher;
-        get_merkle_tree_hash(hasher, std::span<const access_data::value_type>{data.data(), data.size()},
-            HASH_TREE_WORD_SIZE, hash);
+    template <IHasher H>
+    static void get_hash(H &h, const access_data &data, machine_hash &hash) {
+        get_merkle_tree_hash(h, std::span<const access_data::value_type>{data.data(), data.size()}, HASH_TREE_WORD_SIZE,
+            hash);
     }
 
 public:
@@ -103,7 +102,8 @@ class record_send_cmio_state_access :
         a.get_read().value().resize(HASH_TREE_WORD_SIZE);
         // read the entire leaf where the word is located
         m_m.read_memory(pleaf_aligned, a.get_read().value().data(), HASH_TREE_WORD_SIZE);
-        get_hash(a.get_read().value(), a.get_read_hash());
+        variant_hasher h(m_m.get_hash_function());
+        get_hash(h, a.get_read().value(), a.get_read_hash());
         // NOLINTEND(bugprone-unchecked-optional-access)
         m_log.push_access(std::move(a), text);
     }
@@ -138,14 +138,15 @@ class record_send_cmio_state_access :
         a.get_read().emplace();
         a.get_read().value().resize(HASH_TREE_WORD_SIZE);
         m_m.read_memory(pleaf_aligned, a.get_read().value().data(), HASH_TREE_WORD_SIZE);
-        get_hash(a.get_read().value(), a.get_read_hash());
+        variant_hasher h(m_m.get_hash_function());
+        get_hash(h, a.get_read().value(), a.get_read_hash());
         // the logged written data is the same as the read data, but with the word at paligned replaced by word
         a.set_written(access_data(a.get_read().value()));                    // copy the read data
         const int word_offset = static_cast<int>(paligned - pleaf_aligned);  // offset of word in leaf
         replace_word_access_data(val, a.get_written().value(), word_offset); // replace the word
         // compute the hash of the written data
         a.get_written_hash().emplace();
-        get_hash(a.get_written().value(), a.get_written_hash().value());
+        get_hash(h, a.get_written().value(), a.get_written_hash().value());
         // NOLINTEND(bugprone-unchecked-optional-access)
         m_log.push_access(std::move(a), text);
     }
@@ -247,9 +248,9 @@ class record_send_cmio_state_access :
         // log hash and written data
         // NOLINTBEGIN(bugprone-unchecked-optional-access)
         a.get_written_hash().emplace();
-        hasher_type hasher{};
+        variant_hasher h(m_m.get_hash_function());
         const auto offset = paddr - ar.get_start();
-        get_merkle_tree_hash(hasher, std::span<const unsigned char>{ar.get_host_memory() + offset, write_length},
+        get_merkle_tree_hash(h, std::span<const unsigned char>{ar.get_host_memory() + offset, write_length},
             HASH_TREE_WORD_SIZE, a.get_written_hash().value());
         if (m_log.get_log_type().has_large_data()) {
             access_data &data = a.get_written().emplace(write_length);
diff --git a/src/record-step-state-access.h b/src/record-step-state-access.h
index 814a703da..bedaa7b00 100644
--- a/src/record-step-state-access.h
+++ b/src/record-step-state-access.h
@@ -31,6 +31,7 @@
 #include "pmas.h"
 #include "shadow-tlb.h"
 #include "unique-c-ptr.h"
+#include "variant-hasher.h"
 
 namespace cartesi {
 
@@ -58,10 +59,13 @@ class record_step_state_access :
     struct context {
         /// \brief Constructor of record step state access context
         /// \param filename where to save the log
-        explicit context(std::string filename) : filename(std::move(filename)) {
+        explicit context(std::string filename, hash_function_type hash_function) :
+            filename(std::move(filename)),
+            hash_function(hash_function) {
             ;
         }
         std::string filename;             ///<  where to save the log
+        hash_function_type hash_function; ///<  hash function type to use for the log
         mutable pages_type touched_pages; ///<  copy of all pages touched during execution
     };
 
@@ -91,11 +95,16 @@ class record_step_state_access :
 
         // Write log file.
         // The log format is as follows:
-        // page_count, [(page_index, data, scratch_area), ...], sibling_count, [sibling_hash, ...]
+        // hash_function, page_count, [(page_index, data, scratch_area), ...], sibling_count, [sibling_hash, ...]
         // We store the page index, instead of the page address.
         // Scratch area is used by the replay to store page hashes, which change during replay
         // This is to work around the lack of dynamic memory allocation when replaying the log in microarchitectures
         auto fp = make_unique_fopen(m_context.filename.c_str(), "wb");
+        // write the hash function type so the hasher can be recreated by the replay
+        auto hash_function = static_cast<uint64_t>(m_context.hash_function);
+        if (fwrite(&hash_function, sizeof(hash_function), 1, fp.get()) != 1) {
+            throw std::runtime_error("Could not write hash function type to log file");
+        }
         if (fwrite(&page_count, sizeof(page_count), 1, fp.get()) != 1) {
             throw std::runtime_error("Could not write page count to log file");
         }
diff --git a/src/replay-send-cmio-state-access.h b/src/replay-send-cmio-state-access.h
index 95b383345..52ba8f38c 100644
--- a/src/replay-send-cmio-state-access.h
+++ b/src/replay-send-cmio-state-access.h
@@ -37,6 +37,7 @@
 #include "riscv-constants.h"
 #include "shadow-registers.h"
 #include "unique-c-ptr.h"
+#include "variant-hasher.h"
 
 namespace cartesi {
 
@@ -51,15 +52,14 @@ struct i_state_access_fast_addr<replay_send_cmio_state_access> {
 /// \brief Allows replaying a machine::send_cmio_response() from an access log.
 class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_state_access> {
 public:
-    using hasher_type = hash_tree::hasher_type;
-
     struct context {
         /// \brief Constructor replay_send_cmio_state_access context
         /// \param log Access log to be replayed
         /// \param initial_hash Initial root hash
-        context(const access_log &log, const machine_hash &initial_hash) :
+        context(const access_log &log, const machine_hash &initial_hash, hash_function_type hash_function) :
             accesses(log.get_accesses()),
-            root_hash(initial_hash) {
+            root_hash(initial_hash),
+            hash_function(hash_function) {
             ;
         }
         const std::vector<access> &accesses; // NOLINT(cppcoreguidelines-avoid-const-or-ref-data-members)
@@ -67,8 +67,8 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
         unsigned int next_access{};
         ///< Root hash before next access
         machine_hash root_hash;
-        ///< Hasher needed to verify proofs
-        hasher_type hasher;
+        ///< Hash function type used for the log
+        hash_function_type hash_function;
     };
 
 private:
@@ -111,7 +111,7 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
         }
     }
 
-    template <typename H>
+    template <IHasher H>
     static void get_hash(H &h, const access_data &data, machine_hash &hash) {
         get_merkle_tree_hash(h, std::span<const unsigned char>{data.data(), data.size()}, HASH_TREE_WORD_SIZE, hash);
     }
@@ -154,9 +154,10 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
             throw std::invalid_argument{"expected read " + std::string(text) + " data to contain 2^" +
                 std::to_string(HASH_TREE_LOG2_WORD_SIZE) + " bytes at " + access_to_report()};
         }
+        variant_hasher h{m_context.hash_function};
         // check if logged read data hashes to the logged read hash
         machine_hash computed_read_hash{};
-        get_hash(m_context.hasher, read_data, computed_read_hash);
+        get_hash(h, read_data, computed_read_hash);
         if (access.get_read_hash() != computed_read_hash) {
             throw std::invalid_argument{"logged read data of " + std::string(text) +
                 " data does not hash to the logged read hash at " + access_to_report()};
@@ -164,7 +165,7 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
         // NOLINTEND(bugprone-unchecked-optional-access)
         // check proof
         auto proof = access.make_proof(m_context.root_hash);
-        if (!proof.verify(m_context.hasher)) {
+        if (!proof.verify(h)) {
             throw std::invalid_argument{"Mismatch in root hash of " + access_to_report()};
         }
         m_context.next_access++;
@@ -211,9 +212,10 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
             throw std::invalid_argument{"expected overwritten data from " + std::string(text) + " to contain 2^" +
                 std::to_string(access.get_log2_size()) + " bytes at " + access_to_report()};
         }
+        variant_hasher h{m_context.hash_function};
         // check if read data hashes to the logged read hash
         machine_hash computed_read_hash{};
-        get_hash(m_context.hasher, read_data, computed_read_hash);
+        get_hash(h, read_data, computed_read_hash);
         if (access.get_read_hash() != computed_read_hash) {
             throw std::invalid_argument{"logged read data of " + std::string(text) +
                 " does not hash to the logged read hash at " + access_to_report()};
@@ -233,7 +235,7 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
         }
         // check if written data hashes to the logged written hash
         machine_hash computed_written_hash{};
-        get_hash(m_context.hasher, written_data, computed_written_hash);
+        get_hash(h, written_data, computed_written_hash);
         if (written_hash != computed_written_hash) {
             throw std::invalid_argument{"logged written data of " + std::string(text) +
                 " does not hash to the logged written hash at " + access_to_report()};
@@ -256,11 +258,11 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
         // NOLINTEND(bugprone-unchecked-optional-access)
         // check proof
         auto proof = access.make_proof(m_context.root_hash);
-        if (!proof.verify(m_context.hasher)) {
+        if (!proof.verify(h)) {
             throw std::invalid_argument{"Mismatch in root hash of " + access_to_report()};
         }
         // Update root hash to reflect the data written by this access
-        m_context.root_hash = proof.bubble_up(m_context.hasher, written_hash);
+        m_context.root_hash = proof.bubble_up(h, written_hash);
         m_context.next_access++;
     }
 
@@ -278,7 +280,7 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
 
     void do_write_memory_with_padding(uint64_t paddr, const unsigned char *data, uint64_t data_length,
         int write_length_log2_size) const {
-        hasher_type hasher{};
+        variant_hasher h{m_context.hash_function};
         if (data == nullptr) {
             throw std::invalid_argument("data is null");
         }
@@ -305,7 +307,7 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
         // if read data is available then its hash and the logged read hash must match
         if (access.get_read().has_value()) {
             machine_hash computed_logged_data_hash{};
-            get_hash(hasher, access.get_read().value(), computed_logged_data_hash);
+            get_hash(h, access.get_read().value(), computed_logged_data_hash);
             if (computed_logged_data_hash != access.get_read_hash()) {
                 throw std::invalid_argument{
                     "hash of read data and read hash at " + access_to_report() + " does not match read hash"};
@@ -325,7 +327,7 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
         if (write_length > data_length) {
             memset(scratch.get() + data_length, 0, write_length - data_length);
         }
-        get_merkle_tree_hash(hasher, std::span<const unsigned char>{scratch.get(), write_length}, HASH_TREE_WORD_SIZE,
+        get_merkle_tree_hash(h, std::span<const unsigned char>{scratch.get(), write_length}, HASH_TREE_WORD_SIZE,
             computed_data_hash);
         // check if logged written hash matches the computed data hash
         if (written_hash != computed_data_hash) {
@@ -335,7 +337,7 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
         if (access.get_written().has_value()) {
             // if written data is available then its hash and the logged written hash must match
             machine_hash computed_hash;
-            get_hash(hasher, access.get_written().value(), computed_hash);
+            get_hash(h, access.get_written().value(), computed_hash);
             if (computed_hash != written_hash) {
                 throw std::invalid_argument{"written hash and written data mismatch at " + access_to_report()};
             }
@@ -343,11 +345,11 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
         // NOLINTEND(bugprone-unchecked-optional-access)
         // check proof
         auto proof = access.make_proof(m_context.root_hash);
-        if (!proof.verify(m_context.hasher)) {
+        if (!proof.verify(h)) {
             throw std::invalid_argument{"Mismatch in root hash of " + access_to_report()};
         }
         // Update root hash to reflect the data written by this access
-        m_context.root_hash = proof.bubble_up(m_context.hasher, written_hash);
+        m_context.root_hash = proof.bubble_up(h, written_hash);
         m_context.next_access++;
     }
 
diff --git a/src/replay-step-state-access-interop.cpp b/src/replay-step-state-access-interop.cpp
index 8d2eaafad..2c312bba8 100644
--- a/src/replay-step-state-access-interop.cpp
+++ b/src/replay-step-state-access-interop.cpp
@@ -30,17 +30,18 @@ static_assert(interop_log2_root_size == HASH_TREE_LOG2_ROOT_SIZE,
 static_assert(sizeof(cartesi::machine_hash) == sizeof(std::remove_pointer_t<interop_hash_type>),
     "hash_type size mismatch");
 
-extern "C" void interop_merkle_tree_hash(const unsigned char *data, size_t size, interop_hash_type hash) {
-    hash_tree::hasher_type hasher{};
-    get_merkle_tree_hash(hasher, std::span<const unsigned char>{data, size}, HASH_TREE_WORD_SIZE,
+extern "C" void interop_merkle_tree_hash(cartesi::hash_function_type hash_function, const unsigned char *data,
+    size_t size, interop_hash_type hash) {
+    variant_hasher h{hash_function};
+    get_merkle_tree_hash(h, std::span<const unsigned char>{data, size}, HASH_TREE_WORD_SIZE,
         machine_hash_view{*hash, interop_machine_hash_byte_size});
 }
 
-extern "C" void interop_concat_hash(interop_const_hash_type left, interop_const_hash_type right,
-    interop_hash_type result) {
-    hash_tree::hasher_type hasher{};
+extern "C" void interop_concat_hash(cartesi::hash_function_type hash_function, interop_const_hash_type left,
+    interop_const_hash_type right, interop_hash_type result) {
+    variant_hasher h{hash_function};
     // NOLINTBEGIN(cppcoreguidelines-pro-type-reinterpret-cast)
-    get_concat_hash(hasher, *reinterpret_cast<const machine_hash *>(left),
-        *reinterpret_cast<const machine_hash *>(right), *reinterpret_cast<machine_hash *>(result));
+    get_concat_hash(h, *reinterpret_cast<const machine_hash *>(left), *reinterpret_cast<const machine_hash *>(right),
+        *reinterpret_cast<machine_hash *>(result));
     // NOLINTEND(cppcoreguidelines-pro-type-reinterpret-cast)
 }
diff --git a/src/replay-step-state-access-interop.h b/src/replay-step-state-access-interop.h
index b8e4d3428..2e4f63f51 100644
--- a/src/replay-step-state-access-interop.h
+++ b/src/replay-step-state-access-interop.h
@@ -17,10 +17,11 @@
 #ifndef REPLAY_STEP_STATE_ACCESS_INTEROP_H
 #define REPLAY_STEP_STATE_ACCESS_INTEROP_H
 
-#include "compiler-defines.h"
 #include <cstdint>
 #include <cstdlib>
-#include <stdexcept>
+
+#include "compiler-defines.h"
+#include "variant-hasher.h"
 
 const static uint64_t interop_log2_root_size = 64;
 constexpr size_t interop_machine_hash_byte_size = 32;
@@ -32,9 +33,10 @@ NO_RETURN inline void interop_throw_runtime_error(const char *msg) {
     throw std::runtime_error(msg);
 }
 
-extern "C" void interop_merkle_tree_hash(const unsigned char *data, size_t size, interop_hash_type hash);
+extern "C" void interop_merkle_tree_hash(cartesi::hash_function_type hash_function, const unsigned char *data,
+    size_t size, interop_hash_type hash);
 
-extern "C" void interop_concat_hash(interop_const_hash_type left, interop_const_hash_type right,
-    interop_hash_type result);
+extern "C" void interop_concat_hash(cartesi::hash_function_type hash_function, interop_const_hash_type left,
+    interop_const_hash_type right, interop_hash_type result);
 
 #endif
diff --git a/src/replay-step-state-access.h b/src/replay-step-state-access.h
index 59a6d373d..60de9271c 100644
--- a/src/replay-step-state-access.h
+++ b/src/replay-step-state-access.h
@@ -20,6 +20,7 @@
 #include <algorithm>
 #include <cassert>
 #include <cstdlib>
+#include <functional>
 #include <optional>
 #include <ranges>
 
@@ -39,6 +40,7 @@
 #include "strict-aliasing.h"
 #include "uarch-constants.h"
 #include "uarch-defines.h"
+#include "variant-hasher.h"
 
 namespace cartesi {
 
@@ -80,21 +82,21 @@ class replay_step_state_access :
 public:
     using address_type = uint64_t;
     using data_type = unsigned char[AR_PAGE_SIZE];
-    using hash_type = std::array<unsigned char, interop_machine_hash_byte_size>;
-    static_assert(sizeof(hash_type) == interop_machine_hash_byte_size);
+    static_assert(sizeof(machine_hash) == interop_machine_hash_byte_size);
 
     struct PACKED page_type {
         address_type index;
         data_type data;
-        hash_type hash;
+        machine_hash hash;
     };
 
     struct context {
-        uint64_t page_count{0};             ///< Number of pages in the step log
-        page_type *pages{nullptr};          ///< Array of page data
-        uint64_t sibling_count{0};          ///< Number of sibling hashes in the step log
-        hash_type *sibling_hashes{nullptr}; ///< Array of sibling hashes
-        mock_address_ranges ars{};          ///< Array of address ranges
+        hash_function_type hash_function{hash_function_type::keccak256}; ///< Hash function used for the step log
+        uint64_t page_count{0};                                          ///< Number of pages in the step log
+        page_type *pages{nullptr};                                       ///< Array of page data
+        uint64_t sibling_count{0};                                       ///< Number of sibling hashes in the step log
+        machine_hash *sibling_hashes{nullptr};                           ///< Array of sibling hashes
+        mock_address_ranges ars{};                                       ///< Array of address ranges
     };
 
 private:
@@ -108,19 +110,38 @@ class replay_step_state_access :
     // \param root_hash_before The expected machine root hash before the replay
     // \throw runtime_error if the initial root hash does not match or the log data is invalid
     replay_step_state_access(context &context, unsigned char *log_image, uint64_t log_size,
-        const hash_type &root_hash_before) :
+        const machine_hash &root_hash_before) :
         m_context(context) {
         // relevant offsets in the log data
+        uint64_t page_count_offset{};
         uint64_t first_page_offset{};
         uint64_t first_sibling_offset{};
         uint64_t sibling_count_offset{};
         uint64_t end_offset{}; // end of the log data
 
+        // hash function type
+        uint64_t temp_hash_function{};
+        if (!validate_and_advance_offset(log_size, 0, sizeof(temp_hash_function), 1, &page_count_offset)) {
+            interop_throw_runtime_error("hash function type past end of step log");
+        }
+        temp_hash_function = aliased_aligned_read<uint64_t, uint8_t>(log_image + 0);
+        switch (temp_hash_function) {
+            case static_cast<uint64_t>(hash_function_type::keccak256):
+                m_context.hash_function = hash_function_type::keccak256;
+                break;
+            case static_cast<uint64_t>(hash_function_type::sha256):
+                m_context.hash_function = hash_function_type::sha256;
+                break;
+            default:
+                interop_throw_runtime_error("invalid log format: unsupported hash function type");
+        }
+
         // set page count
-        if (!validate_and_advance_offset(log_size, 0, sizeof(m_context.page_count), 1, &first_page_offset)) {
+        if (!validate_and_advance_offset(log_size, page_count_offset, sizeof(m_context.page_count), 1,
+                &first_page_offset)) {
             interop_throw_runtime_error("page count past end of step log");
         }
-        m_context.page_count = aliased_aligned_read<uint64_t, uint8_t>(log_image);
+        m_context.page_count = aliased_aligned_read<uint64_t, uint8_t>(log_image + page_count_offset);
         if (m_context.page_count == 0) {
             interop_throw_runtime_error("page count is zero");
         }
@@ -140,12 +161,12 @@ class replay_step_state_access :
         m_context.sibling_count = aliased_aligned_read<uint64_t, uint8_t>(log_image + sibling_count_offset);
 
         // set sibling hashes
-        if (!validate_and_advance_offset(log_size, first_sibling_offset, sizeof(hash_type), m_context.sibling_count,
+        if (!validate_and_advance_offset(log_size, first_sibling_offset, sizeof(machine_hash), m_context.sibling_count,
                 &end_offset)) {
             interop_throw_runtime_error("sibling hashes past end of step log");
         }
         // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        m_context.sibling_hashes = reinterpret_cast<hash_type *>(log_image + first_sibling_offset);
+        m_context.sibling_hashes = reinterpret_cast<machine_hash *>(log_image + first_sibling_offset);
 
         // ensure that we read exactly the expected log size
         if (end_offset != log_size) {
@@ -154,7 +175,7 @@ class replay_step_state_access :
 
         // ensure that the page indexes are in increasing order
         // and that the scratch hash area is all zeros
-        static const hash_type all_zeros{};
+        static const machine_hash all_zeros{};
         for (uint64_t i = 0; i < m_context.page_count; i++) {
             if (i > 0 && m_context.pages[i - 1].index >= m_context.pages[i].index) {
                 interop_throw_runtime_error("invalid log format: page index is not in increasing order");
@@ -183,7 +204,7 @@ class replay_step_state_access :
     // \brief Finish the replay and check the final machine root hash
     // \param final_root_hash The expected final machine root hash
     // \throw runtime_error if the final root hash does not match
-    void finish(const hash_type &root_hash_after) {
+    void finish(const machine_hash &root_hash_after) {
         // reset all tlb vh offsets to zero
         // this is to mimic peek behavior of tlb pma device
         relocate_tlb_vh_offset_to_vp_offset<TLB_CODE>();
@@ -316,13 +337,13 @@ class replay_step_state_access :
     }
 
     // \brief Compute the current machine root hash
-    hash_type compute_root_hash() {
+    machine_hash compute_root_hash() {
         //??D Here we should only do this for dirty pages, right?
         //??D Initially, all pages are dirty, because we don't know their hashes
         //??D But in the end, we should only update those pages that we touched
         //??D May improve performance when we are running this on ZK
         for (uint64_t i = 0; i < m_context.page_count; i++) {
-            interop_merkle_tree_hash(m_context.pages[i].data, AR_PAGE_SIZE,
+            interop_merkle_tree_hash(m_context.hash_function, m_context.pages[i].data, AR_PAGE_SIZE,
                 // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
                 reinterpret_cast<interop_hash_type>(&m_context.pages[i].hash));
         }
@@ -344,7 +365,7 @@ class replay_step_state_access :
     // \param next_page Index of the next page to be visited
     // \param next_sibling Index of the next sibling hash to be visited
     // \return Resulting root hash of the range
-    hash_type compute_root_hash_impl(address_type page_index, int log2_page_count, size_t &next_page,
+    machine_hash compute_root_hash_impl(address_type page_index, int log2_page_count, size_t &next_page,
         size_t &next_sibling) {
         // NOLINTBEGIN(cppcoreguidelines-pro-type-reinterpret-cast))
         auto page_count = UINT64_C(1) << log2_page_count;
@@ -358,9 +379,9 @@ class replay_step_state_access :
             auto left = compute_root_hash_impl(page_index, log2_page_count - 1, next_page, next_sibling);
             const auto halfway_page_index = page_index + (page_count >> 1);
             auto right = compute_root_hash_impl(halfway_page_index, log2_page_count - 1, next_page, next_sibling);
-            hash_type hash{};
-            interop_concat_hash(reinterpret_cast<interop_hash_type>(&left), reinterpret_cast<interop_hash_type>(&right),
-                reinterpret_cast<interop_hash_type>(&hash));
+            machine_hash hash{};
+            interop_concat_hash(m_context.hash_function, reinterpret_cast<interop_hash_type>(&left),
+                reinterpret_cast<interop_hash_type>(&right), reinterpret_cast<interop_hash_type>(&hash));
             return hash;
         }
         if (m_context.pages[next_page].index == page_index) {
diff --git a/src/sha-256-hasher.h b/src/sha-256-hasher.h
index 527436609..d81e4bbf5 100644
--- a/src/sha-256-hasher.h
+++ b/src/sha-256-hasher.h
@@ -102,35 +102,10 @@ class sha_256_hasher final : public i_hasher<sha_256_hasher> {
 public:
     static constexpr int MAX_LANE_COUNT = 16; ///< Number of maximum supported SIMD lanes
 
-    /// \brief Default constructor
-    sha_256_hasher() = default;
-
-    /// \brief Default destructor
-    ~sha_256_hasher() = default;
-
-    /// \brief No copy constructor
-    sha_256_hasher(const sha_256_hasher &) = delete;
-    /// \brief No move constructor
-    sha_256_hasher(sha_256_hasher &&) = delete;
-    /// \brief No copy assignment
-    sha_256_hasher &operator=(const sha_256_hasher &) = delete;
-    /// \brief No move assignment
-    sha_256_hasher &operator=(sha_256_hasher &&) = delete;
-
-    // \brief Hashes the concatenation of data in SIMD using SHA-256
-    // \tparam LaneCount Number of SIMD lanes
-    // \tparam ConcatCount Number of concatenated data items
-    // \tparam Extent Extent of the data span
-    // \param data Data to hash, as a multi-dimensional array of spans
-    // \param hash Array of machine hashes to store the results
-    // \warning When LaneCount is greater than 1, it is assumed data spans have same size, there is no check for that.
     template <size_t ConcatCount, size_t LaneCount, size_t Extent>
     static void do_simd_concat_hash(const array2d<std::span<const unsigned char, Extent>, ConcatCount, LaneCount> &data,
         const std::array<machine_hash_view, LaneCount> &hash) noexcept;
 
-    // \brief Gets the optimal number of SIMD lanes for SHA-256
-    // \returns The optimal number of SIMD lanes for SHA-256
-    // \details This value is architecture-dependent and may vary based on the available instruction sets.
     static size_t do_get_optimal_lane_count() noexcept {
         return sha_256_get_optimal_lane_count();
     }
diff --git a/src/simd-hasher.h b/src/simd-hasher.h
index 01353152b..7afeb5c2a 100644
--- a/src/simd-hasher.h
+++ b/src/simd-hasher.h
@@ -38,24 +38,27 @@ namespace cartesi {
 /// \tparam hasher_type The underlying SIMD hasher implementation
 /// \tparam data_type The type of data to be hashed
 /// \tparam MaxQueueSize Maximum number of items that can be queued (defaults to hasher's max lane count)
-template <typename hasher_type, typename data_type, size_t MaxQueueSize = hasher_type::MAX_LANE_COUNT>
+template <IHasher hasher_type, typename data_type, size_t MaxQueueSize = hasher_type::MAX_LANE_COUNT>
 class simd_data_hasher {
     struct data_entry {
         data_type data;           ///< Data to be hashed
         machine_hash_view result; ///< View where the hash result will be stored
     };
 
-    hasher_type m_hasher;                                                ///< The underlying SIMD hasher instance
+    // NOLINTNEXTLINE(cppcoreguidelines-avoid-const-or-ref-data-members)
+    hasher_type &m_hasher;                                               ///< Underlying hasher instance
     boost::container::static_vector<data_entry, MaxQueueSize> m_queue{}; ///< Queue of pending hash operations
 
 public:
+    explicit simd_data_hasher(hasher_type &hasher) : m_hasher(hasher) {}
+
     /// \brief Enqueues data for hashing
     /// \param data Data to hash
     /// \param result Receives the hash of data
     /// \details If the queue reaches the optimal size, it is automatically flushed.
     void enqueue(data_type data, machine_hash_view result) noexcept {
         m_queue.emplace_back(data_entry{.data = data, .result = result});
-        static const size_t optimal_queue_size = std::min(MaxQueueSize, hasher_type::get_optimal_lane_count());
+        static const size_t optimal_queue_size = std::min(MaxQueueSize, m_hasher.get_optimal_lane_count());
         if (m_queue.size() >= optimal_queue_size) [[unlikely]] { // Queue is full, auto flush it
             flush();
         }
@@ -172,7 +175,7 @@ class simd_data_hasher {
 /// \tparam hasher_type The underlying SIMD hasher implementation
 /// \tparam data_type The type of data to be hashed
 /// \tparam MaxQueueSize Maximum number of pairs that can be queued (defaults to hasher's max lane count)
-template <typename hasher_type, typename data_type, size_t MaxQueueSize = hasher_type::MAX_LANE_COUNT>
+template <IHasher hasher_type, typename data_type, size_t MaxQueueSize = hasher_type::MAX_LANE_COUNT>
 class simd_concat_hasher {
     struct concat_entry {
         data_type left;           ///< Left data to be concatenated and hashed
@@ -180,11 +183,14 @@ class simd_concat_hasher {
         machine_hash_view result; ///< View where the hash result will be stored
     };
 
-    hasher_type m_hasher; ///< The underlying SIMD hasher instance
+    // NOLINTNEXTLINE(cppcoreguidelines-avoid-const-or-ref-data-members)
+    hasher_type &m_hasher; ///< The underlying SIMD hasher instance
     boost::container::static_vector<concat_entry, MaxQueueSize>
         m_queue{}; ///< Queue of pending concatenation hash operations
 
 public:
+    explicit simd_concat_hasher(hasher_type &hasher) : m_hasher(hasher) {}
+
     /// \brief Enqueues data pair for concat hashing
     /// \param left Left data to hash
     /// \param right Right data to hash
@@ -192,7 +198,7 @@ class simd_concat_hasher {
     /// \details If the queue reaches the optimal size, it is automatically flushed.
     void enqueue(data_type left, data_type right, machine_hash_view result) noexcept {
         m_queue.emplace_back(concat_entry{.left = left, .right = right, .result = result});
-        static const size_t optimal_queue_size = std::min(MaxQueueSize, hasher_type::get_optimal_lane_count());
+        static const size_t optimal_queue_size = std::min(MaxQueueSize, m_hasher.get_optimal_lane_count());
         if (m_queue.size() >= optimal_queue_size) [[unlikely]] { // Queue is full, auto flush it
             flush();
         }
diff --git a/src/uarch-record-state-access.h b/src/uarch-record-state-access.h
index 2e2785851..ec79c2067 100644
--- a/src/uarch-record-state-access.h
+++ b/src/uarch-record-state-access.h
@@ -52,20 +52,11 @@ class uarch_record_state_access :
     public i_accept_scoped_notes<uarch_record_state_access>,
     public i_prefer_shadow_uarch_state<uarch_record_state_access> {
 
-    using hasher_type = hash_tree::hasher_type;
-
     // NOLINTBEGIN(cppcoreguidelines-avoid-const-or-ref-data-members)
     machine &m_m;      ///< Macro machine
     access_log &m_log; ///< Access log
     // NOLINTEND(cppcoreguidelines-avoid-const-or-ref-data-members)
 
-    template <typename H>
-    static auto get_hash(H &h, const access_data &data) {
-        machine_hash hash{};
-        get_merkle_tree_hash(h, data.data(), data.size(), HASH_TREE_WORD_SIZE, hash);
-        return hash;
-    }
-
 public:
     /// \brief Constructor from machine and uarch states.
     /// \param m Reference to machine state.
diff --git a/src/uarch-replay-state-access.h b/src/uarch-replay-state-access.h
index ac58ce67e..7fc66b24a 100644
--- a/src/uarch-replay-state-access.h
+++ b/src/uarch-replay-state-access.h
@@ -33,6 +33,7 @@
 #include "i-hasher.h"
 #include "i-prefer-shadow-uarch-state.h"
 #include "i-uarch-state-access.h"
+#include "keccak-256-hasher.h"
 #include "machine-reg.h"
 #include "machine.h"
 #include "meta.h"
@@ -51,8 +52,6 @@ class uarch_replay_state_access :
     using proof_type = hash_tree::proof_type;
 
 public:
-    using hasher_type = hash_tree::hasher_type;
-
     struct context {
         /// \brief Constructor replay_send_cmio_state_access context
         /// \param log Access log to be replayed
@@ -68,7 +67,7 @@ class uarch_replay_state_access :
         ///< Root hash before next access
         machine_hash root_hash;
         ///< Hasher needed to verify proofs
-        hasher_type hasher;
+        keccak_256_hasher hasher;
     };
 
 private:
@@ -91,10 +90,10 @@ class uarch_replay_state_access :
     }
 
 private:
-    static auto get_hash(hasher_type &hasher, const access_data &data) {
+    template <IHasher H>
+    static auto get_hash(H &h, const access_data &data) {
         machine_hash hash{};
-        get_merkle_tree_hash(hasher, std::span<const unsigned char>{data.data(), data.size()}, HASH_TREE_WORD_SIZE,
-            hash);
+        get_merkle_tree_hash(h, std::span<const unsigned char>{data.data(), data.size()}, HASH_TREE_WORD_SIZE, hash);
         return hash;
     }
 
diff --git a/src/variant-hasher.h b/src/variant-hasher.h
new file mode 100644
index 000000000..91a27914a
--- /dev/null
+++ b/src/variant-hasher.h
@@ -0,0 +1,71 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef VARIANT_HASHER_H
+#define VARIANT_HASHER_H
+
+#include <cstdint>
+#include <variant>
+
+#include "i-hasher.h"
+#include "keccak-256-hasher.h"
+#include "sha-256-hasher.h"
+
+namespace cartesi {
+
+/// \brief Hash function
+enum class hash_function_type : uint64_t {
+    keccak256, ///< Keccak-256 (recommended for fraud proofs based on Microarchitecture)
+    sha256,    ///< SHA-256 (recommended for fraud proofs using zkVMs)
+};
+
+class variant_hasher final : public i_hasher<variant_hasher> {
+    std::variant<keccak_256_hasher, sha_256_hasher> m_hasher_impl;
+
+public:
+    static constexpr int MAX_LANE_COUNT = std::max(keccak_256_hasher::MAX_LANE_COUNT, sha_256_hasher::MAX_LANE_COUNT);
+
+    explicit variant_hasher(hash_function_type algo) {
+        switch (algo) {
+            case hash_function_type::keccak256:
+                m_hasher_impl = keccak_256_hasher{};
+                break;
+            case hash_function_type::sha256:
+                m_hasher_impl = sha_256_hasher{};
+                break;
+            default:
+                throw std::invalid_argument("unsupported hash function type");
+        }
+    }
+
+    variant_hasher() = delete; ///< Default constructor is not allowed
+
+    template <size_t ConcatCount, size_t LaneCount, size_t Extent>
+    // NOLINTNEXTLINE(bugprone-exception-escape)
+    void do_simd_concat_hash(const array2d<std::span<const unsigned char, Extent>, ConcatCount, LaneCount> &data,
+        const std::array<machine_hash_view, LaneCount> &hash) noexcept {
+        std::visit([&](auto &h) noexcept { h.do_simd_concat_hash(data, hash); }, m_hasher_impl);
+    }
+
+    // NOLINTNEXTLINE(bugprone-exception-escape)
+    size_t do_get_optimal_lane_count() const noexcept {
+        return std::visit([](auto &h) noexcept { return h.do_get_optimal_lane_count(); }, m_hasher_impl);
+    }
+};
+
+} // namespace cartesi
+
+#endif
diff --git a/tests/Makefile b/tests/Makefile
index b731f638f..ba1ed2ced 100644
--- a/tests/Makefile
+++ b/tests/Makefile
@@ -203,7 +203,8 @@ test-uarch-interpreter:
 	$(MAKE) -C ../third-party/riscv-arch-test verify XLEN=64 RISCV_TARGET=cartesi RISCV_ISA=rv64i RISCV_DEVICE=I WORK=$(BUILDDIR)/uarch-riscv-arch-test RUN_ARCH_TEST='$(RUN_ARCH_TEST)'
 
 test-hash:
-	$(LD_PRELOAD_PREFIX) ./build/misc/test-merkle-tree-hash --log2-root-size=30 --log2-leaf-size=12 --input=build/misc/test-merkle-tree-hash
+	$(LD_PRELOAD_PREFIX) ./build/misc/test-merkle-tree-hash --log2-root-size=30 --log2-leaf-size=12 --input=build/misc/test-merkle-tree-hash --hash-function=keccak256
+	$(LD_PRELOAD_PREFIX) ./build/misc/test-merkle-tree-hash --log2-root-size=30 --log2-leaf-size=12 --input=build/misc/test-merkle-tree-hash --hash-function=sha256
 
 test-jsonrpc:
 	./scripts/test-jsonrpc-server.sh ../src/cartesi-jsonrpc-machine '$(LUA) ../src/cartesi-machine.lua' '$(LUA) ./lua/cartesi-machine-tests.lua' '$(LUA)'
diff --git a/tests/lua/cartesi/tests/util.lua b/tests/lua/cartesi/tests/util.lua
index aae0d200a..5c9690a4f 100644
--- a/tests/lua/cartesi/tests/util.lua
+++ b/tests/lua/cartesi/tests/util.lua
@@ -32,19 +32,23 @@ local test_util = {
     tests_uarch_path = adjust_path(assert(os.getenv("CARTESI_TESTS_UARCH_PATH"), "must set CARTESI_TESTS_UARCH_PATH")),
 }
 
-local zero_keccak_hash_table = {
-    "",
-    "",
-}
-
-do
-    local hash = cartesi.keccak256(string.rep("\0", 1 << WORD_LOG2_SIZE))
+local function compute_zero_hash_table(hash_fn)
+    local zero_hash_table = {
+        "",
+        "",
+    }
+    local hash = cartesi[hash_fn](string.rep("\0", 1 << WORD_LOG2_SIZE))
     for i = WORD_LOG2_SIZE, ROOT_LOG2_SIZE - 1 do
-        zero_keccak_hash_table[i] = hash
-        hash = cartesi.keccak256(hash, hash)
+        zero_hash_table[i] = hash
+        hash = cartesi[hash_fn](hash, hash)
     end
+    return zero_hash_table
 end
 
+local zero_hash_tables = {
+    keccak256 = compute_zero_hash_table("keccak256"),
+    sha256 = compute_zero_hash_table("sha256"),
+}
 local ZERO_PAGE = string.rep("\x00", PAGE_SIZE)
 
 test_util.uarch_programs = {
@@ -91,7 +95,7 @@ function back_merkle_tree_meta.__index:push_back(new_leaf_hash)
     for i = 0, depth do
         if self.m_leaf_count & (0x01 << i) ~= 0x0 then
             local left = self.m_context[i]
-            right = cartesi.keccak256(left, right)
+            right = cartesi[self.hash_fn](left, right)
         else
             self.m_context[i] = right
             break
@@ -116,12 +120,12 @@ function back_merkle_tree_meta.__index:pad_back(new_leaf_count)
         -- is our smallest tree at depth j?
         if (self.m_leaf_count & j_span) ~= 0x0 then
             -- if so, we can add 2^j pristine leaves directly
-            local right = zero_keccak_hash_table[self.m_log2_leaf_size + j]
+            local right = self.zero_hash_table[self.m_log2_leaf_size + j]
             for i = j, depth do
                 local i_span = 0x1 << i
                 if (self.m_leaf_count & i_span) ~= 0x0 then
                     local left = self.m_context[i]
-                    right = cartesi.keccak256(left, right)
+                    right = cartesi[self.hash_fn](left, right)
                 else
                     self.m_context[i] = right
                     -- next outer loop starts again from where inner loop left off
@@ -139,7 +143,7 @@ function back_merkle_tree_meta.__index:pad_back(new_leaf_count)
     for i = 0, depth do
         local i_span = 0x1 << i
         if (new_leaf_count & i_span) ~= 0x0 then
-            self.m_context[i] = zero_keccak_hash_table[self.m_log2_leaf_size + i]
+            self.m_context[i] = self.zero_hash_table[self.m_log2_leaf_size + i]
             new_leaf_count = new_leaf_count - i_span
             self.m_leaf_count = self.m_leaf_count + i_span
         end
@@ -150,14 +154,14 @@ function back_merkle_tree_meta.__index:get_root_hash()
     assert(self.m_leaf_count <= self.m_max_leaves, "too many leaves")
     local depth = self.m_log2_root_size - self.m_log2_leaf_size
     if self.m_leaf_count < self.m_max_leaves then
-        local root = zero_keccak_hash_table[self.m_log2_leaf_size]
+        local root = self.zero_hash_table[self.m_log2_leaf_size]
         for i = 0, depth - 1 do
             if (self.m_leaf_count & (0x01 << i)) ~= 0 then
                 local left = self.m_context[i]
-                root = cartesi.keccak256(left, root)
+                root = cartesi[self.hash_fn](left, root)
             else
-                local right = zero_keccak_hash_table[self.m_log2_leaf_size + i]
-                root = cartesi.keccak256(root, right)
+                local right = self.zero_hash_table[self.m_log2_leaf_size + i]
+                root = cartesi[self.hash_fn](root, right)
             end
         end
         return root
@@ -166,8 +170,10 @@ function back_merkle_tree_meta.__index:get_root_hash()
     end
 end
 
-function test_util.new_back_merkle_tree(log2_root_size, log2_leaf_size)
+function test_util.new_back_merkle_tree(log2_root_size, log2_leaf_size, hash_fn)
     local self = {}
+    self.hash_fn = hash_fn
+    self.zero_hash_table = zero_hash_tables[hash_fn]
     self.m_context = {}
     self.m_log2_leaf_size = log2_leaf_size
     self.m_log2_root_size = log2_root_size
@@ -204,7 +210,8 @@ function test_util.split_string(inputstr, sep)
     return t
 end
 
-function test_util.check_proof(proof)
+function test_util.check_proof(proof, hash_fn)
+    assert(hash_fn, "hash_fn is nil")
     local hash = proof.target_hash
     for log2_size = proof.log2_target_size, proof.log2_root_size - 1 do
         local bit = (proof.target_address & (1 << log2_size)) ~= 0
@@ -214,7 +221,7 @@ function test_util.check_proof(proof)
         else
             first, second = hash, proof.sibling_hashes[log2_size - proof.log2_target_size + 1]
         end
-        hash = cartesi.keccak256(first, second)
+        hash = cartesi[hash_fn](first, second)
     end
     return hash == proof.root_hash
 end
@@ -229,16 +236,18 @@ function test_util.load_file(filename)
     return data
 end
 
-local function merkle_hash(data, start, log2_size)
+local function merkle_hash(data, start, log2_size, hash_fn)
+    assert(hash_fn, "hash_fn is nil")
+    local zero_hash_table = zero_hash_tables[hash_fn]
     if log2_size == PAGE_LOG2_SIZE and data:sub(start + 1, start + PAGE_SIZE) == ZERO_PAGE then
-        return zero_keccak_hash_table[PAGE_LOG2_SIZE]
+        return zero_hash_table[PAGE_LOG2_SIZE]
     elseif log2_size > WORD_LOG2_SIZE then
         local child_log2_size = log2_size - 1
-        local left = merkle_hash(data, start, child_log2_size)
-        local right = merkle_hash(data, start + (1 << child_log2_size), child_log2_size)
-        return cartesi.keccak256(left, right)
+        local left = merkle_hash(data, start, child_log2_size, hash_fn)
+        local right = merkle_hash(data, start + (1 << child_log2_size), child_log2_size, hash_fn)
+        return cartesi[hash_fn](left, right)
     else
-        return cartesi.keccak256(data:sub(start + 1, start + (1 << WORD_LOG2_SIZE)))
+        return cartesi[hash_fn](data:sub(start + 1, start + (1 << WORD_LOG2_SIZE)), nil)
     end
 end
 
@@ -246,14 +255,15 @@ test_util.merkle_hash = merkle_hash
 
 -- Take data from dumped memory files
 -- and calculate root hash of the machine
-function test_util.calculate_emulator_hash(machine)
-    local tree = test_util.new_back_merkle_tree(64, PAGE_LOG2_SIZE)
+function test_util.calculate_emulator_hash(machine, hash_fn)
+    hash_fn = hash_fn or machine:get_initial_config().hash_tree.hash_function
+    local tree = test_util.new_back_merkle_tree(64, PAGE_LOG2_SIZE, hash_fn)
     local last = 0
     for _, v in ipairs(machine:get_address_ranges()) do
         tree:pad_back((v.start - last) >> PAGE_LOG2_SIZE)
         local finish = v.start + v.length
         for j = v.start, finish - 1, PAGE_SIZE do
-            local page_hash = merkle_hash(machine:read_memory(j, PAGE_SIZE), 0, PAGE_LOG2_SIZE)
+            local page_hash = merkle_hash(machine:read_memory(j, PAGE_SIZE), 0, PAGE_LOG2_SIZE, hash_fn)
             tree:push_back(page_hash)
         end
         last = finish
@@ -263,11 +273,12 @@ end
 
 -- Read memory from given machine and calculate uarch state hash
 function test_util.calculate_uarch_state_hash(machine)
+    local hash_fn = machine:get_initial_config().hash_tree.hash_function
     local shadow_data = machine:read_memory(cartesi.UARCH_SHADOW_START_ADDRESS, cartesi.UARCH_SHADOW_LENGTH)
     local ram_data = machine:read_memory(cartesi.UARCH_RAM_START_ADDRESS, cartesi.UARCH_RAM_LENGTH)
-    local tree = test_util.new_back_merkle_tree(cartesi.UARCH_STATE_LOG2_SIZE, PAGE_LOG2_SIZE)
+    local tree = test_util.new_back_merkle_tree(cartesi.UARCH_STATE_LOG2_SIZE, PAGE_LOG2_SIZE, hash_fn)
     for j = 0, #shadow_data - 1, PAGE_SIZE do
-        local page_hash = merkle_hash(shadow_data, j, PAGE_LOG2_SIZE)
+        local page_hash = merkle_hash(shadow_data, j, PAGE_LOG2_SIZE, hash_fn)
         tree:push_back(page_hash)
     end
     -- pad the region between the end of shadow data and start of ram
@@ -275,7 +286,7 @@ function test_util.calculate_uarch_state_hash(machine)
         (cartesi.UARCH_RAM_START_ADDRESS - cartesi.UARCH_SHADOW_START_ADDRESS - #shadow_data) >> PAGE_LOG2_SIZE
     )
     for j = 0, #ram_data - 1, PAGE_SIZE do
-        local page_hash = merkle_hash(ram_data, j, PAGE_LOG2_SIZE)
+        local page_hash = merkle_hash(ram_data, j, PAGE_LOG2_SIZE, hash_fn)
         tree:push_back(page_hash)
     end
     return tree:get_root_hash()
diff --git a/tests/lua/hash-tree.lua b/tests/lua/hash-tree.lua
index 2df3f7808..4eeb05cc7 100755
--- a/tests/lua/hash-tree.lua
+++ b/tests/lua/hash-tree.lua
@@ -101,7 +101,7 @@ local function compare_proofs(p1, p2, padding)
     return true
 end
 
-local function check_proof(proof)
+local function check_proof(proof, hash_fn)
     local hash = proof.target_hash
     for log2_size = proof.log2_target_size, proof.log2_root_size - 1 do
         local bit = 1 << log2_size
@@ -112,7 +112,7 @@ local function check_proof(proof)
         else
             first, second = hash, sibling_hash
         end
-        hash = cartesi.keccak256(first, second)
+        hash = cartesi[hash_fn](first, second)
     end
     return hash == proof.root_hash
 end
@@ -188,10 +188,11 @@ table.insert(interesting_pages, { -PAGE_SIZE, { start = last_end, length = -last
 
 -- check all page hashes
 print("checking all page hashes")
+local hash_fn = machine:get_initial_config().hash_tree.hash_function
 for _, v in ipairs(machine:get_address_ranges()) do
     for address = v.start, v.start + v.length - 1, PAGE_SIZE do
         local h1 = machine:get_node_hash(address, LOG2_PAGE_SIZE)
-        local h2 = test_util.merkle_hash(machine:read_memory(address, PAGE_SIZE), 0, LOG2_PAGE_SIZE)
+        local h2 = test_util.merkle_hash(machine:read_memory(address, PAGE_SIZE), 0, LOG2_PAGE_SIZE, hash_fn)
         if h1 ~= h2 then
             stderr("hash mismatch on page 0x%016x (offset 0x%016x in %s)\n", address, address - v.start, v.description)
             stderr("    0x%.16s... vs 0x%.16s...\n", tohex(h1), tohex(h2))
@@ -208,7 +209,7 @@ for _, p in ipairs(interesting_pages) do
     for address = page, page + PAGE_SIZE - 1, WORD_SIZE do
         local h1 = machine:get_node_hash(address, LOG2_WORD_SIZE)
         local word = machine:read_memory(address, WORD_SIZE)
-        local h2 = cartesi.keccak256(word)
+        local h2 = cartesi[hash_fn](word)
         if h1 ~= h2 then
             stderr("        hash mismatch on word 0x%016x (%u)\n", address, address)
             stderr("            0x%.16s... vs 0x%.16s...\n", tohex(h1), tohex(h2))
@@ -219,7 +220,7 @@ for _, p in ipairs(interesting_pages) do
     for log2_size = LOG2_WORD_SIZE + 1, LOG2_PAGE_SIZE do
         local new_hashes = {}
         for i = 1, #hashes - 1, 2 do
-            new_hashes[#new_hashes + 1] = cartesi.keccak256(hashes[i], hashes[i + 1])
+            new_hashes[#new_hashes + 1] = cartesi[hash_fn](hashes[i], hashes[i + 1])
         end
         hashes = new_hashes
         for i = 1, #hashes do
@@ -252,11 +253,11 @@ for log2_size = LOG2_WORD_SIZE, LOG2_ROOT_SIZE - 1 do
                         if not compare_proofs(mproof, oproof, "        ") then
                             stderr("    proof mismatch for offset 0x%016x (%u)\n", address, address)
                         end
-                        if not check_proof(oproof) then
+                        if not check_proof(oproof, hash_fn) then
                             stderr("    test proof for offset 0x%016x (%u) failed\n", address, address)
                             os.exit(1)
                         end
-                        if not check_proof(mproof) then
+                        if not check_proof(mproof, hash_fn) then
                             stderr("    machine proof for offset 0x%016x (%u) failed\n", address, address)
                             os.exit(1)
                         end
diff --git a/tests/lua/machine-bind.lua b/tests/lua/machine-bind.lua
index bae46af1f..cdd855b5c 100755
--- a/tests/lua/machine-bind.lua
+++ b/tests/lua/machine-bind.lua
@@ -219,6 +219,7 @@ local function build_machine_config(config_options)
     -- Create new machine
     local initial_reg_values = get_cpu_reg_test_values()
     local config = {
+        hash_tree = config_options.hash_tree or nil,
         processor = config_options.processor or {
             registers = initial_reg_values,
         },
@@ -264,6 +265,59 @@ local do_test = test_util.make_do_test(build_machine, machine_type)
 
 print("Testing machine bindings for type " .. machine_type)
 
+print("\n\nDifferent hash tree hash targets")
+
+do_test("Hash tree hash function should be keccak256 by default", function(machine)
+    assert(
+        machine:get_initial_config().hash_tree.hash_function == "keccak256",
+        "hash tree hash function should be uarch"
+    )
+end)
+
+test_util.make_do_test(build_machine, machine_type, { hash_tree = { hash_function = "keccak256" } })(
+    "Hash tree hash function keccak256 should work properly",
+    function(machine)
+        assert(
+            machine:get_initial_config().hash_tree.hash_function == "keccak256",
+            "hash tree hash function should be uarch"
+        )
+        local root_hash = machine:get_root_hash()
+        local keccak256_calculated = test_util.calculate_emulator_hash(machine, "keccak256")
+        assert(root_hash == keccak256_calculated, "initial root hash does not match")
+        local sha256_calculated = test_util.calculate_emulator_hash(machine, "sha256")
+        assert(root_hash ~= sha256_calculated, "initial root hash should not match sha256")
+    end
+)
+
+test_util.make_do_test(build_machine, machine_type, { hash_tree = { hash_function = "sha256" } })(
+    "Hash tree hash function sha256 should work properly",
+    function(machine)
+        assert(
+            machine:get_initial_config().hash_tree.hash_function == "sha256",
+            "hash tree hash function should be sha256"
+        )
+        local root_hash = machine:get_root_hash()
+        local sha256_calculated = test_util.calculate_emulator_hash(machine, "sha256")
+        assert(root_hash == sha256_calculated, "initial root hash does not match")
+        local keccak256_calculated = test_util.calculate_emulator_hash(machine, "keccak256")
+        assert(root_hash ~= keccak256_calculated, "initial root hash should not match keccak256")
+    end
+)
+
+test_util.make_do_test(function() end, machine_type, {})(
+    "Fails to construct machine of unsupported hash tree hash function",
+    function()
+        local success, err = pcall(function()
+            build_machine(machine_type, {
+                hash_tree = { hash_function = "invalid" },
+            })
+        end)
+        assert(success == false)
+        print(err)
+        assert(err and err:match("invalid hash function type"))
+    end
+)
+
 print("\n\ntesting machine initial flags")
 do_test("machine should not have halt and yield initial flags set", function(machine)
     -- Check machine is not halted
@@ -295,10 +349,11 @@ do_test("should provide proof for values in registers", function(machine)
     initial_reg_values.mimpid = nil
 
     -- Check proofs
+    local hash_fn = machine:get_initial_config().hash_tree.hash_function
     for _, v in pairs(initial_reg_values) do
         for el = cartesi.TREE_LOG2_WORD_SIZE, cartesi.TREE_LOG2_ROOT_SIZE - 1 do
             local a = test_util.align(v, el)
-            assert(test_util.check_proof(assert(machine:get_proof(a, el), "no proof")), "proof failed")
+            assert(test_util.check_proof(assert(machine:get_proof(a, el), "no proof"), hash_fn), "proof failed")
         end
     end
 end)
@@ -456,6 +511,7 @@ local function test_config(config)
     assertfield(config, "hash_tree.sht_filename", "string")
     assertfield(config, "hash_tree.phtc_filename", "string")
     assertfield(config, "hash_tree.phtc_size", "number")
+    assertfield(config, "hash_tree.hash_function", "string")
 end
 
 print("\n\ntesting get_default_config function binding")
@@ -965,6 +1021,42 @@ test_util.make_do_test(build_machine, machine_type, { uarch = test_reset_uarch_c
     end
 )
 
+test_util.make_do_test(build_machine, machine_type, { hash_tree = { hash_function = "sha256" } })(
+    "Uarch operations should fail if hash tree hash function is not keccak256",
+    function(machine)
+        assert(
+            machine:get_initial_config().hash_tree.hash_function == "sha256",
+            "hash tree hash function should be sha256"
+        )
+        -- The machine is configured for sha256, therefore:
+        -- run_uarch should fail
+        local success, err = pcall(machine.run_uarch, machine, 1)
+        assert(
+            success == false and err:match("can only be used with hash tree configured with Keccak%-256 hash function")
+        )
+        -- reset_uarch should fail
+        success, err = pcall(machine.reset_uarch, machine)
+        assert(
+            success == false and err:match("can only be used with hash tree configured with Keccak%-256 hash function")
+        )
+        -- log_reset_uarch should fail
+        success, err = pcall(machine.log_reset_uarch, machine)
+        assert(
+            success == false and err:match("can only be used with hash tree configured with Keccak%-256 hash function")
+        )
+        -- log_uarch step should fail
+        success, err = pcall(machine.log_step_uarch, machine)
+        assert(
+            success == false and err:match("can only be used with hash tree configured with Keccak%-256 hash function")
+        )
+        -- log_send_cmio_response should fail
+        success, err = pcall(machine.log_send_cmio_response, machine, 0, 0)
+        assert(
+            success == false and err:match("can only be used with hash tree configured with Keccak%-256 hash function")
+        )
+    end
+)
+
 test_util.make_do_test(build_machine, machine_type, { uarch = test_reset_uarch_config })(
     "Dump of log produced by log_reset_uarch should match",
     function(machine)
@@ -1211,9 +1303,10 @@ local function test_send_cmio_input_with_different_arguments()
     local data = string.rep("a", 1 << cartesi.AR_CMIO_RX_BUFFER_LOG2_SIZE)
     local reason = 1
     local max_rx_buffer_len = 1 << cartesi.AR_CMIO_RX_BUFFER_LOG2_SIZE
-    local data_hash = test_util.merkle_hash(data, 0, cartesi.AR_CMIO_RX_BUFFER_LOG2_SIZE)
+    local hash_fn = "keccak256"
+    local data_hash = test_util.merkle_hash(data, 0, cartesi.AR_CMIO_RX_BUFFER_LOG2_SIZE, hash_fn)
     local all_zeros = string.rep("\0", max_rx_buffer_len)
-    local all_zeros_hash = test_util.merkle_hash(all_zeros, 0, cartesi.AR_CMIO_RX_BUFFER_LOG2_SIZE)
+    local all_zeros_hash = test_util.merkle_hash(all_zeros, 0, cartesi.AR_CMIO_RX_BUFFER_LOG2_SIZE, hash_fn)
     -- prepares and asserts the state before send_cmio_response is called
     local function assert_before_cmio_response_sent(machine)
         machine:write_reg("iflags_Y", 1)
@@ -1564,8 +1657,9 @@ end)
 -- helper function to load a step log file into a table
 local function read_step_log_file(filename)
     local file <close> = assert(io.open(filename, "rb"))
+    local hash_function = string.unpack("<I8", file:read(8))
     local page_count = string.unpack("<I8", file:read(8))
-    local log = { pages = {}, siblings = {} }
+    local log = { hash_function = hash_function, pages = {}, siblings = {} }
     for i = 1, page_count do
         log.pages[i] = {
             index = string.unpack("<I8", file:read(8)),
@@ -1587,6 +1681,7 @@ local function write_step_log_file(logdata, filename)
     if logdata.override_page_count then
         page_count = logdata.override_page_count
     end
+    file:write(string.pack("<I8", logdata.hash_function))
     file:write(string.pack("<I8", page_count))
     for _, page in ipairs(logdata.pages) do
         file:write(string.pack("<I8", page.index))
@@ -1611,168 +1706,175 @@ local function copy_step_log(original_filename, new_filename, callback)
     write_step_log_file(log_data, new_filename)
 end
 
-test_util.make_do_test(build_machine, machine_type, { uarch = {} })("log_step sanity check", function(machine)
-    local success, err, _
-    local filename1 = os.tmpname()
-    local filename2 = os.tmpname()
-    local deleter = {}
-    setmetatable(deleter, {
-        __gc = function()
-            os.remove(filename1)
-            os.remove(filename2)
-        end,
-    })
+for _, hash_fn in pairs({ "keccak256", "sha256" }) do
+    test_util.make_do_test(build_machine, machine_type, { hash_tree = { hash_function = hash_fn }, uarch = {} })(
+        "log_step sanity check",
+        function(machine)
+            local success, err, _
+            local filename1 = os.tmpname()
+            local filename2 = os.tmpname()
+            local deleter = {}
+            setmetatable(deleter, {
+                __gc = function()
+                    os.remove(filename1)
+                    os.remove(filename2)
+                end,
+            })
 
-    machine:write_reg("mcycle", 0)
-    assert(machine:read_reg("mcycle") == 0)
-    -- log_step should fail because the temp file already exists
-    success, err = pcall(function()
-        machine:log_step(1, filename1)
-    end)
-    assert(not success)
-    check_error_find(err, "file already exists")
-    -- delete file and confirm that machine is on same mcycle
-    os.remove(filename1)
-    assert(machine:read_reg("mcycle") == 0)
-    -- get current root hash and log step
-    local root_hash_before = machine:get_root_hash()
-    local mcycle_count = 10
-    local status = machine:log_step(mcycle_count, filename1)
-    assert(status == cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE)
-    assert(machine:read_reg("mcycle") == mcycle_count)
-    local root_hash_after = machine:get_root_hash()
-    assert(root_hash_before ~= root_hash_after)
-    -- verify step should pass
-    status = machine:verify_step(root_hash_before, filename1, mcycle_count, root_hash_after)
-    assert(status == cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE)
-    -- with incorrect hash args, verify step should fail
-    local bad_hash = string.rep("\0", 32)
-    _, err = pcall(function()
-        machine:verify_step(bad_hash, filename1, mcycle_count, root_hash_after)
-    end)
-    check_error_find(err, "initial root hash mismatch")
-    _, err = pcall(function()
-        machine:verify_step(root_hash_before, filename1, mcycle_count, bad_hash)
-    end)
-    check_error_find(err, "final root hash mismatch")
-    -- ensure that copy_step_log() works
-    copy_step_log(filename1, filename2, function()
-        -- copy original file without modifications
-    end)
-    machine:verify_step(root_hash_before, filename2, mcycle_count, root_hash_after)
-    -- modify page data
-    copy_step_log(filename1, filename2, function(log_data)
-        log_data.pages[1].data = string.reverse(log_data.pages[1].data)
-    end)
-    _, err = pcall(function()
-        machine:verify_step(root_hash_before, filename2, mcycle_count, root_hash_after)
-    end)
-    check_error_find(err, "initial root hash mismatch")
-    -- page indices not in ascending order should fail
-    copy_step_log(filename1, filename2, function(log_data)
-        log_data.pages[2].index = log_data.pages[1].index
-    end)
-    _, err = pcall(function()
-        machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
-    end)
-    check_error_find(err, "invalid log format: page index is not in increasing order")
-    -- page scratch hash area not zeroed
-    copy_step_log(filename1, filename2, function(log_data)
-        log_data.pages[1].hash = string.rep("\1", 32)
-    end)
-    _, err = pcall(function()
-        machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
-    end)
-    check_error_find(err, "invalid log format: page scratch hash area is not zero")
-    -- add one extra page
-    copy_step_log(filename1, filename2, function(log_data)
-        table.insert(log_data.pages, {
-            index = log_data.pages[#log_data.pages].index + 1,
-            data = log_data.pages[#log_data.pages].data,
-            hash = log_data.pages[#log_data.pages].hash,
-        })
-    end)
-    _, err = pcall(function()
-        machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
-    end)
-    check_error_find(err, "too many sibling hashes in log")
-    -- remove one page
-    copy_step_log(filename1, filename2, function(log_data)
-        table.remove(log_data.pages)
-    end)
-    _, err = pcall(function()
-        machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
-    end)
-    check_error_find(err, "too many sibling hashes in log")
-    -- override page count to zero
-    copy_step_log(filename1, filename2, function(log_data)
-        log_data.override_page_count = 0
-    end)
-    _, err = pcall(function()
-        machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
-    end)
-    check_error_find(err, "page count is zero")
-    -- override page count to overflow
-    copy_step_log(filename1, filename2, function(log_data)
-        -- There is no UINT64_MAX in Lua, so we have to use the signed representation
-        local MAX_MCYCLE_COUNT = -1
-        log_data.override_page_count = MAX_MCYCLE_COUNT
-    end)
-    _, err = pcall(function()
-        machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
-    end)
-    check_error_find(err, "page data past end of step log")
-    -- remove one sibling
-    copy_step_log(filename1, filename2, function(log_data)
-        table.remove(log_data.siblings)
-    end)
-    _, err = pcall(function()
-        machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
-    end)
-    check_error_find(err, "too few sibling hashes in log")
-    -- add an extra sibling
-    copy_step_log(filename1, filename2, function(log_data)
-        table.insert(log_data.siblings, bad_hash)
-    end)
-    _, err = pcall(function()
-        machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
-    end)
-    check_error_find(err, "too many sibling hashes in log")
-    -- modify one sibling hash
-    copy_step_log(filename1, filename2, function(log_data)
-        log_data.siblings[1] = bad_hash
-    end)
-    _, err = pcall(function()
-        machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
-    end)
-    check_error_find(err, "initial root hash mismatch")
-    -- empty siblings
-    copy_step_log(filename1, filename2, function(log_data)
-        log_data.siblings = {}
-    end)
-    _, err = pcall(function()
-        machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
-    end)
-    check_error_find(err, "too few sibling hashes in log")
-    -- override sibling count to overflow
-    copy_step_log(filename1, filename2, function(log_data)
-        log_data.override_sibling_count = 0xffffffff
-    end)
-    _, err = pcall(function()
-        machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
-    end)
-    check_error_find(err, "sibling hashes past end of step log")
-    -- log_step should fail if uarch is not reset
-    machine:run_uarch(1) -- advance 1 micro step 0< uarch is not reset
-    os.remove(filename1)
-    _, err = pcall(function()
-        machine:log_step(1, filename1)
-    end)
-    check_error_find(err, "microarchitecture is not reset")
-    -- after uarch is reset, log_step should work
-    machine:reset_uarch()
-    status = machine:log_step(1, filename1)
-    assert(status == cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE)
-end)
+            machine:write_reg("mcycle", 0)
+            assert(machine:read_reg("mcycle") == 0)
+            -- log_step should fail because the temp file already exists
+            success, err = pcall(function()
+                machine:log_step(1, filename1)
+            end)
+            assert(not success)
+            check_error_find(err, "file already exists")
+            -- delete file and confirm that machine is on same mcycle
+            os.remove(filename1)
+            assert(machine:read_reg("mcycle") == 0)
+            -- get current root hash and log step
+            local root_hash_before = machine:get_root_hash()
+            local mcycle_count = 10
+            local status = machine:log_step(mcycle_count, filename1)
+            assert(status == cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE)
+            assert(machine:read_reg("mcycle") == mcycle_count)
+            local root_hash_after = machine:get_root_hash()
+            assert(root_hash_before ~= root_hash_after)
+            -- verify step should pass
+            status = machine:verify_step(root_hash_before, filename1, mcycle_count, root_hash_after)
+            assert(status == cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE)
+            -- with incorrect hash args, verify step should fail
+            local bad_hash = string.rep("\0", 32)
+            _, err = pcall(function()
+                machine:verify_step(bad_hash, filename1, mcycle_count, root_hash_after)
+            end)
+            check_error_find(err, "initial root hash mismatch")
+            _, err = pcall(function()
+                machine:verify_step(root_hash_before, filename1, mcycle_count, bad_hash)
+            end)
+            check_error_find(err, "final root hash mismatch")
+            -- ensure that copy_step_log() works
+            copy_step_log(filename1, filename2, function()
+                -- copy original file without modifications
+            end)
+            machine:verify_step(root_hash_before, filename2, mcycle_count, root_hash_after)
+            -- modify page data
+            copy_step_log(filename1, filename2, function(log_data)
+                log_data.pages[1].data = string.reverse(log_data.pages[1].data)
+            end)
+            _, err = pcall(function()
+                machine:verify_step(root_hash_before, filename2, mcycle_count, root_hash_after)
+            end)
+            check_error_find(err, "initial root hash mismatch")
+            -- page indices not in ascending order should fail
+            copy_step_log(filename1, filename2, function(log_data)
+                log_data.pages[2].index = log_data.pages[1].index
+            end)
+            _, err = pcall(function()
+                machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
+            end)
+            check_error_find(err, "invalid log format: page index is not in increasing order")
+            -- page scratch hash area not zeroed
+            copy_step_log(filename1, filename2, function(log_data)
+                log_data.pages[1].hash = string.rep("\1", 32)
+            end)
+            _, err = pcall(function()
+                machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
+            end)
+            check_error_find(err, "invalid log format: page scratch hash area is not zero")
+            -- add one extra page
+            copy_step_log(filename1, filename2, function(log_data)
+                table.insert(log_data.pages, {
+                    index = log_data.pages[#log_data.pages].index + 1,
+                    data = log_data.pages[#log_data.pages].data,
+                    hash = log_data.pages[#log_data.pages].hash,
+                })
+            end)
+            _, err = pcall(function()
+                machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
+            end)
+            check_error_find(err, "too many sibling hashes in log")
+            -- remove one page
+            copy_step_log(filename1, filename2, function(log_data)
+                table.remove(log_data.pages)
+            end)
+            _, err = pcall(function()
+                machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
+            end)
+            check_error_find(err, "too many sibling hashes in log")
+            -- override page count to zero
+            copy_step_log(filename1, filename2, function(log_data)
+                log_data.override_page_count = 0
+            end)
+            _, err = pcall(function()
+                machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
+            end)
+            check_error_find(err, "page count is zero")
+            -- override page count to overflow
+            copy_step_log(filename1, filename2, function(log_data)
+                -- There is no UINT64_MAX in Lua, so we have to use the signed representation
+                local MAX_MCYCLE_COUNT = -1
+                log_data.override_page_count = MAX_MCYCLE_COUNT
+            end)
+            _, err = pcall(function()
+                machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
+            end)
+            check_error_find(err, "page data past end of step log")
+            -- remove one sibling
+            copy_step_log(filename1, filename2, function(log_data)
+                table.remove(log_data.siblings)
+            end)
+            _, err = pcall(function()
+                machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
+            end)
+            check_error_find(err, "too few sibling hashes in log")
+            -- add an extra sibling
+            copy_step_log(filename1, filename2, function(log_data)
+                table.insert(log_data.siblings, bad_hash)
+            end)
+            _, err = pcall(function()
+                machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
+            end)
+            check_error_find(err, "too many sibling hashes in log")
+            -- modify one sibling hash
+            copy_step_log(filename1, filename2, function(log_data)
+                log_data.siblings[1] = bad_hash
+            end)
+            _, err = pcall(function()
+                machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
+            end)
+            check_error_find(err, "initial root hash mismatch")
+            -- empty siblings
+            copy_step_log(filename1, filename2, function(log_data)
+                log_data.siblings = {}
+            end)
+            _, err = pcall(function()
+                machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
+            end)
+            check_error_find(err, "too few sibling hashes in log")
+            -- override sibling count to overflow
+            copy_step_log(filename1, filename2, function(log_data)
+                log_data.override_sibling_count = 0xffffffff
+            end)
+            _, err = pcall(function()
+                machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
+            end)
+            check_error_find(err, "sibling hashes past end of step log")
+            os.remove(filename1)
+            if hash_fn == "keccak256" then
+                -- log_step should fail if uarch is not reset
+                machine:run_uarch(1) -- advance 1 micro step 0< uarch is not reset
+                _, err = pcall(function()
+                    machine:log_step(1, filename1)
+                end)
+                check_error_find(err, "microarchitecture is not reset")
+                -- after uarch is reset, log_step should work
+                machine:reset_uarch()
+            end
+            status = machine:log_step(1, filename1)
+            assert(status == cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE)
+        end
+    )
+end
 
 print("\n\nAll machine binding tests for type " .. machine_type .. " passed")
diff --git a/tests/lua/machine-test.lua b/tests/lua/machine-test.lua
index 3a54b927e..ad7a74372 100755
--- a/tests/lua/machine-test.lua
+++ b/tests/lua/machine-test.lua
@@ -204,7 +204,9 @@ do_test("proof check should pass", function(machine)
     end
     -- Ccalculate hash of ram
     local ram_log2_size = math.ceil(math.log(ram.length, 2))
-    local calculated_ram_hash = test_util.merkle_hash(machine:read_memory(ram.start, ram.length), 0, ram_log2_size)
+    local hash_fn = machine:get_initial_config().hash_tree.hash_function
+    local calculated_ram_hash =
+        test_util.merkle_hash(machine:read_memory(ram.start, ram.length), 0, ram_log2_size, hash_fn)
     -- Get proof of ram and check if hashes match
     local ram_proof = machine:get_proof(ram.start, ram_log2_size)
     local root_hash = machine:get_root_hash()
@@ -297,7 +299,8 @@ do_test("proof  and root hash should match", function(machine)
     local initial_ram_proof = machine:get_proof(ram_address_start, 10)
     -- Calculate hash
     local initial_memory_read = machine:read_memory(ram_address_start, 2 ^ 10)
-    local initial_calculated_hash = test_util.merkle_hash(initial_memory_read, 0, 10)
+    local hash_fn = machine:get_initial_config().hash_tree.hash_function
+    local initial_calculated_hash = test_util.merkle_hash(initial_memory_read, 0, 10, hash_fn)
     assert(initial_ram_proof.target_hash == initial_calculated_hash, "initial hash does not match")
 
     print(
@@ -316,7 +319,7 @@ do_test("proof  and root hash should match", function(machine)
     local ram_proof = machine:get_proof(ram_address_start, 10)
     -- Calculate hash
     local memory_read = machine:read_memory(ram_address_start, 2 ^ 10)
-    local calculated_hash = test_util.merkle_hash(memory_read, 0, 10)
+    local calculated_hash = test_util.merkle_hash(memory_read, 0, 10, hash_fn)
 
     print(
         "end target hash:",
diff --git a/tests/misc/test-machine-c-api.cpp b/tests/misc/test-machine-c-api.cpp
index ab84b48df..a0840ed93 100644
--- a/tests/misc/test-machine-c-api.cpp
+++ b/tests/misc/test-machine-c-api.cpp
@@ -451,7 +451,8 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(get_proof_machine_hash_test, ordinary_machine_fix
     const auto proof =
         cartesi::from_json<cartesi::not_default_constructible<cartesi::hash_tree_proof>>(proof_str, "proof").value();
     auto proof_root_hash = proof.get_root_hash();
-    auto verification = calculate_proof_root_hash(proof);
+    cartesi::variant_hasher h(get_machine_hash_function(_machine));
+    auto verification = calculate_proof_root_hash(h, proof);
     BOOST_CHECK_EQUAL_COLLECTIONS(verification.begin(), verification.end(), proof_root_hash.begin(),
         proof_root_hash.end());
     verification = calculate_emulator_hash(_machine);
@@ -1568,7 +1569,8 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(machine_verify_hash_tree_proof_updates_test, ordi
     auto proof =
         cartesi::from_json<cartesi::not_default_constructible<cartesi::hash_tree_proof>>(proof_str, "proof").value();
     auto proof_root_hash = proof.get_root_hash();
-    auto verification = calculate_proof_root_hash(proof);
+    cartesi::variant_hasher h(get_machine_hash_function(_machine));
+    auto verification = calculate_proof_root_hash(h, proof);
     BOOST_CHECK_EQUAL_COLLECTIONS(verification.begin(), verification.end(), proof_root_hash.begin(),
         proof_root_hash.end());
     verification = calculate_emulator_hash(_machine);
@@ -1585,7 +1587,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(machine_verify_hash_tree_proof_updates_test, ordi
     proof =
         cartesi::from_json<cartesi::not_default_constructible<cartesi::hash_tree_proof>>(proof_str, "proof").value();
     proof_root_hash = proof.get_root_hash();
-    verification = calculate_proof_root_hash(proof);
+    verification = calculate_proof_root_hash(h, proof);
     BOOST_CHECK_EQUAL_COLLECTIONS(verification.begin(), verification.end(), proof_root_hash.begin(),
         proof_root_hash.end());
     verification = calculate_emulator_hash(_machine);
diff --git a/tests/misc/test-merkle-tree-hash.cpp b/tests/misc/test-merkle-tree-hash.cpp
index 8c60b145c..1f0198ccb 100644
--- a/tests/misc/test-merkle-tree-hash.cpp
+++ b/tests/misc/test-merkle-tree-hash.cpp
@@ -32,12 +32,11 @@
 #include <full-merkle-tree.h>
 #include <hash-tree-proof.h>
 #include <i-hasher.h>
-#include <keccak-256-hasher.h>
 #include <unique-c-ptr.h>
+#include <variant-hasher.h>
 
 using namespace cartesi;
-using hasher_type = keccak_256_hasher;
-using hash_type = machine_hash;
+using namespace std::string_literals;
 
 namespace {
 /// \brief Checks if string matches prefix and captures remaninder
@@ -75,7 +74,7 @@ bool intval(const char *pre, const char *str, int *val) {
 /// \brief Prints hash in hex to file
 /// \param hash Hash to be printed.
 /// \param f File to print to
-void print_hash(const hash_type &hash, FILE *f) {
+void print_hash(const machine_hash &hash, FILE *f) {
     for (auto b : hash) {
         std::ignore = fprintf(f, "%02x", static_cast<int>(b));
     }
@@ -87,13 +86,13 @@ void print_hash(const hash_type &hash, FILE *f) {
 /// \brief Reads a hash in hex from file
 /// \param f File to read from
 /// \returns Hash if successful, nothing otherwise
-static std::optional<hash_type> read_hash(FILE *f) {
-    std::array<char, hasher_type::hash_size * 2> hex_hash{};
+static std::optional<machine_hash> read_hash(FILE *f) {
+    std::array<char, variant_hasher::hash_size * 2> hex_hash{};
     if (fread(hex_hash.data(), 1, hex_hash.size(), f) != hex_hash.size()) {
         return {};
     }
-    hash_type h;
-    for (size_t i = 0; i < hasher_type::hash_size; ++i) {
+    machine_hash h;
+    for (size_t i = 0; i < variant_hasher::hash_size; ++i) {
         std::array<char, 3> hex_c = {hex_hash[2 * i], hex_hash[2 * i + 1], '\0'};
         unsigned c = 0;
         // NOLINTNEXTLINE(cert-err34-c): we just generated the string so we don't need to verify it
@@ -123,7 +122,7 @@ __attribute__((format(printf, 1, 2))) void error(const char *fmt, ...) {
 /// \param leaf Pointer to leaf data. Must contain 2^log2_word_size bytes
 /// \param log2_word Log<sub>2</sub> of word size
 /// \param hash Receives the leaf hash
-void get_word_hash(hasher_type &h, const unsigned char *word, int log2_word_size, hash_type &hash) {
+void get_word_hash(variant_hasher &h, const unsigned char *word, int log2_word_size, machine_hash &hash) {
     h.hash(std::span<const unsigned char>(word, 1 << log2_word_size), hash);
 }
 
@@ -134,37 +133,27 @@ void get_word_hash(hasher_type &h, const unsigned char *word, int log2_word_size
 /// at least 2^log2_leaf_size bytes
 /// \param log2_leaf_size Log<sub>2</sub> of leaf size
 /// \returns Merkle hash of leaf data
-hash_type get_leaf_hash(hasher_type &h, int log2_word_size, const unsigned char *leaf_data, int log2_leaf_size) {
+machine_hash get_leaf_hash(variant_hasher &h, int log2_word_size, const unsigned char *leaf_data, int log2_leaf_size) {
     assert(log2_leaf_size >= log2_word_size);
     if (log2_leaf_size > log2_word_size) {
-        hash_type left = get_leaf_hash(h, log2_word_size, leaf_data, log2_leaf_size - 1);
-        const hash_type right =
+        machine_hash left = get_leaf_hash(h, log2_word_size, leaf_data, log2_leaf_size - 1);
+        const machine_hash right =
             get_leaf_hash(h, log2_word_size, leaf_data + (1 << (log2_leaf_size - 1)), log2_leaf_size - 1);
         get_concat_hash(h, left, right, left);
         return left;
     }
-    hash_type leaf;
+    machine_hash leaf;
     get_word_hash(h, leaf_data, log2_word_size, leaf);
     return leaf;
 }
 
-/// \brief Computes the Merkle hash of a leaf of data
-/// \param log2_word_size Log<sub>2</sub> of word size
-/// \param leaf_data Pointer to buffer containing leaf data with
-/// at least 2^log2_leaf_size bytes
-/// \param log2_leaf_size Log<sub>2</sub> of leaf size
-/// \returns Merkle hash of leaf data
-hash_type get_leaf_hash(int log2_word_size, const unsigned char *leaf_data, int log2_leaf_size) {
-    hasher_type h;
-    return get_leaf_hash(h, log2_word_size, leaf_data, log2_leaf_size);
-}
-
 /// \brief Prints help message
 void help(const char *name) {
     std::ignore = fprintf(stderr,
         "Usage:\n  %s [--input=<filename>] "
         "[--log2-word-size=<w>] [--log2-leaf-size=<p>] "
-        "[--log2-root-size=<t>]\n",
+        "[--log2-root-size=<t>]\n"
+        "[--hash-function=(keccak256|sha256)]\n",
         name);
     exit(0);
 }
@@ -172,6 +161,7 @@ void help(const char *name) {
 
 int main(int argc, char *argv[]) try {
     const char *input_name = nullptr;
+    const char *hash_function_name = nullptr;
     int log2_word_size = 3;
     int log2_leaf_size = 12;
     int log2_root_size = 30;
@@ -184,7 +174,8 @@ int main(int argc, char *argv[]) try {
         }
         if (stringval("--input=", argv[i], &input_name) || intval("--log2-word-size=", argv[i], &log2_word_size) ||
             intval("--log2-leaf-size=", argv[i], &log2_leaf_size) ||
-            intval("--log2-root-size=", argv[i], &log2_root_size)) {
+            intval("--log2-root-size=", argv[i], &log2_root_size) ||
+            stringval("--hash-function=", argv[i], &hash_function_name)) {
             ;
         } else {
             error("unrecognized option '%s'\n", argv[i]);
@@ -197,6 +188,15 @@ int main(int argc, char *argv[]) try {
             log2_root_size);
         return 1;
     }
+    hash_function_type hash_function{hash_function_type::keccak256};
+    if (hash_function_name == "keccak256"s) {
+        hash_function = hash_function_type::keccak256;
+    } else if (hash_function_name == "sha256"s) {
+        hash_function = hash_function_type::sha256;
+    } else {
+        error("invalid hash function type '%s'\n", hash_function_name);
+        return 1;
+    }
     // Read from stdin if no input name was given
     auto input_file = unique_file_ptr{stdin};
     if (input_name != nullptr) {
@@ -216,12 +216,12 @@ int main(int argc, char *argv[]) try {
     }
 
     std::cerr << "instantiating back tree\n";
-    back_merkle_tree back_tree{log2_root_size, log2_leaf_size, log2_word_size};
+    back_merkle_tree back_tree{log2_root_size, log2_leaf_size, log2_word_size, hash_function};
 
     std::cerr << "instantiating complete tree\n";
-    complete_merkle_tree complete_tree{log2_root_size, log2_leaf_size, log2_word_size};
+    complete_merkle_tree complete_tree{log2_root_size, log2_leaf_size, log2_word_size, hash_function};
 
-    std::vector<hash_type> leaf_hashes;
+    std::vector<machine_hash> leaf_hashes;
 
     const uint64_t max_leaves = UINT64_C(1) << (log2_root_size - log2_leaf_size); // NOLINT(misc-include-cleaner)
     uint64_t leaf_count = 0;
@@ -237,7 +237,7 @@ int main(int argc, char *argv[]) try {
     // the root hash in log time keeping only constant size state.
     // 4) The complete_merkle_tree can receive leaf hashes and maintain
     // only the part of the tree that is not pristine
-    hasher_type h;
+    variant_hasher h{hash_function};
     while (true) {
         auto got = fread(leaf_buf.get(), 1, leaf_size, input_file.get());
         if (got == 0) {
@@ -254,7 +254,7 @@ int main(int argc, char *argv[]) try {
         // Pad leaf with zeros if file ended before next leaf boundary
         memset(leaf_buf.get() + got, 0, leaf_size - got);
         // Compute leaf hash
-        auto leaf_hash = get_leaf_hash(log2_word_size, leaf_buf.get(), log2_leaf_size);
+        auto leaf_hash = get_leaf_hash(h, log2_word_size, leaf_buf.get(), log2_leaf_size);
         // Add to array of leaf hashes
         leaf_hashes.push_back(leaf_hash);
         // Print leaf hash
@@ -264,7 +264,8 @@ int main(int argc, char *argv[]) try {
         // Add new leaf to back tree
         back_tree.push_back(leaf_hash);
         // Build full tree from array of leaf hashes
-        const full_merkle_tree tree_from_scratch(log2_root_size, log2_leaf_size, log2_word_size, leaf_hashes);
+        const full_merkle_tree tree_from_scratch(log2_root_size, log2_leaf_size, log2_word_size, leaf_hashes,
+            hash_function);
         // Compare the root hash for the back tree and the tree
         // from scratch
         if (back_tree.get_root_hash() != tree_from_scratch.get_root_hash()) {
diff --git a/tests/misc/test-utils.h b/tests/misc/test-utils.h
index 5468f00a4..4d1af3d01 100644
--- a/tests/misc/test-utils.h
+++ b/tests/misc/test-utils.h
@@ -19,11 +19,9 @@
 #include <back-merkle-tree.h>
 #include <hash-tree-proof.h>
 #include <json-util.h>
-#include <keccak-256-hasher.h>
 #include <machine-c-api.h>
 #include <machine-hash.h>
-
-using hash_type = cartesi::machine_hash;
+#include <variant-hasher.h>
 
 // Calculate root hash for data buffer of log2_size
 namespace detail {
@@ -32,8 +30,8 @@ constexpr int WORD_LOG2_SIZE = 5;
 constexpr int MERKLE_PAGE_LOG2_SIZE = 12;
 constexpr int MERKLE_PAGE_SIZE = (UINT64_C(1) << MERKLE_PAGE_LOG2_SIZE);
 
-static hash_type merkle_hash(cartesi::keccak_256_hasher &h, const std::string_view &data, int log2_size) {
-    hash_type result;
+static cartesi::machine_hash merkle_hash(cartesi::variant_hasher &h, const std::string_view &data, int log2_size) {
+    cartesi::machine_hash result;
     if (log2_size > WORD_LOG2_SIZE) {
         --log2_size;
         auto half_size = data.size() / 2;
@@ -49,7 +47,18 @@ static hash_type merkle_hash(cartesi::keccak_256_hasher &h, const std::string_vi
 
 } // namespace detail
 
-static hash_type merkle_hash(const std::string_view &data, int log2_size) {
+// \brief Creates a hasher object compatible with the one used by the machine's config
+static cartesi::hash_function_type get_machine_hash_function(cm_machine *machine) {
+    const char *cfg_jsonstr{};
+    cm_error error_code = cm_get_initial_config(machine, &cfg_jsonstr);
+    if (error_code != 0) {
+        throw std::runtime_error{cm_get_last_error_message()};
+    }
+    const auto cfg = cartesi::from_json<cartesi::machine_config>(cfg_jsonstr, "config");
+    return cfg.hash_tree.hash_function;
+}
+
+static cartesi::machine_hash merkle_hash(cartesi::variant_hasher &h, const std::string_view &data, int log2_size) {
     if (log2_size > 63) {
         throw std::domain_error("log2_size is too large");
     }
@@ -59,18 +68,17 @@ static hash_type merkle_hash(const std::string_view &data, int log2_size) {
     if ((UINT64_C(1) << log2_size) != data.size()) {
         throw std::invalid_argument("log2_size does not match data size");
     }
-    cartesi::keccak_256_hasher h;
     return detail::merkle_hash(h, data, log2_size);
 }
 
-static hash_type calculate_proof_root_hash(const cartesi::hash_tree_proof &proof) {
-    hash_type hash;
+static cartesi::machine_hash calculate_proof_root_hash(cartesi::variant_hasher &h,
+    const cartesi::hash_tree_proof &proof) {
+    cartesi::machine_hash hash;
     memcpy(hash.data(), proof.get_target_hash().data(), sizeof(cm_hash));
     for (int log2_size = proof.get_log2_target_size(); log2_size < proof.get_log2_root_size(); ++log2_size) {
-        cartesi::keccak_256_hasher h;
         auto bit = (proof.get_target_address() & (UINT64_C(1) << log2_size));
-        hash_type first;
-        hash_type second;
+        cartesi::machine_hash first;
+        cartesi::machine_hash second;
         if (bit != 0) {
             memcpy(first.data(), proof.get_sibling_hashes()[log2_size - proof.get_log2_target_size()].data(),
                 sizeof(cm_hash));
@@ -85,8 +93,11 @@ static hash_type calculate_proof_root_hash(const cartesi::hash_tree_proof &proof
     return hash;
 }
 
-static hash_type calculate_emulator_hash(cm_machine *machine) {
-    cartesi::back_merkle_tree tree(CM_TREE_LOG2_ROOT_SIZE, CM_TREE_LOG2_PAGE_SIZE, CM_TREE_LOG2_WORD_SIZE);
+static cartesi::machine_hash calculate_emulator_hash(cm_machine *machine) {
+    const auto hash_function = get_machine_hash_function(machine);
+    cartesi::variant_hasher h(hash_function);
+    cartesi::back_merkle_tree tree(CM_TREE_LOG2_ROOT_SIZE, CM_TREE_LOG2_PAGE_SIZE, CM_TREE_LOG2_WORD_SIZE,
+        hash_function);
     std::string page;
     page.resize(detail::MERKLE_PAGE_SIZE);
     const char *ranges_jsonstr{};
@@ -103,7 +114,7 @@ static hash_type calculate_emulator_hash(cm_machine *machine) {
             if (cm_read_memory(machine, s, reinterpret_cast<unsigned char *>(page.data()), page.size()) != 0) {
                 throw std::runtime_error{cm_get_last_error_message()};
             }
-            auto page_hash = merkle_hash(page, detail::MERKLE_PAGE_LOG2_SIZE);
+            auto page_hash = merkle_hash(h, page, detail::MERKLE_PAGE_LOG2_SIZE);
             tree.push_back(page_hash);
         }
         last = end;
diff --git a/uarch/compute-uarch-pristine-hash.cpp b/uarch/compute-uarch-pristine-hash.cpp
index 0998ce2e2..4cce4281e 100644
--- a/uarch/compute-uarch-pristine-hash.cpp
+++ b/uarch/compute-uarch-pristine-hash.cpp
@@ -20,6 +20,7 @@
 
 #include <back-merkle-tree.h>
 #include <hash-tree-constants.h>
+#include <keccak-256-hasher.h>
 #include <shadow-uarch-state.h>
 #include <uarch-constants.h>
 #include <uarch-pristine.h>
@@ -31,10 +32,6 @@
 
 using namespace cartesi;
 
-using tree_type = back_merkle_tree;
-using hash_type = tree_type::hash_type;
-using hasher_type = tree_type::hasher_type;
-
 static constexpr auto word_size = HASH_TREE_WORD_SIZE;
 static constexpr auto log2_word_size = HASH_TREE_LOG2_WORD_SIZE;
 static constexpr auto page_size = HASH_TREE_PAGE_SIZE;
@@ -68,9 +65,9 @@ Computes the hash of the pristine uarch state.
 }
 
 int main(int argc, char *argv[]) try {
-    tree_type tree{UARCH_STATE_LOG2_SIZE, log2_page_size, log2_word_size};
-    hasher_type hasher{};
-    hash_type hash{};
+    back_merkle_tree tree{UARCH_STATE_LOG2_SIZE, log2_page_size, log2_word_size, hash_function_type::keccak256};
+    keccak_256_hasher hasher{};
+    machine_hash hash{};
 
     // Process command line arguments
     for (int i = 1; i < argc; ++i) {
@@ -88,7 +85,7 @@ int main(int argc, char *argv[]) try {
         throw std::runtime_error("Could not allocate scratch memory");
     }
     auto scratch_span = std::span<unsigned char>{scratch.get(), page_size};
-    hash_type pristine_hash;
+    machine_hash pristine_hash;
     get_merkle_tree_hash(hasher, scratch_span, word_size, pristine_hash);
 
     // Build pristine shadow uarch state

From 274feb82a2344bb201a12d1b6e7b3d50a42ea243 Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Wed, 23 Jul 2025 14:34:07 -0300
Subject: [PATCH 53/82] feat: add hash functions to public C API

---
 src/clua-cartesi.cpp  | 38 +++++++++++-------
 src/machine-c-api.cpp | 90 +++++++++++++++++++++++++++++++++++--------
 src/machine-c-api.h   | 29 ++++++++++++++
 3 files changed, 126 insertions(+), 31 deletions(-)

diff --git a/src/clua-cartesi.cpp b/src/clua-cartesi.cpp
index 733e69efb..b8176f619 100644
--- a/src/clua-cartesi.cpp
+++ b/src/clua-cartesi.cpp
@@ -31,12 +31,10 @@ extern "C" {
 #include "clua-i-machine.h"
 #include "clua.h"
 #include "htif-constants.h"
-#include "keccak-256-hasher.h"
 #include "machine-c-api.h"
 #include "machine-c-version.h"
 #include "machine-hash.h"
 #include "riscv-constants.h"
-#include "sha-256-hasher.h"
 #include "uarch-constants.h"
 #include "uarch-pristine.h"
 
@@ -61,11 +59,10 @@ static const auto gperf_meta = clua_make_luaL_Reg_array({
 #endif
 
 /// \brief Generic hasher function implementation.
-/// \tparam Hasher Type of hasher to use.
+/// \tparam hash_function Hash function type (keccak256 or sha256).
 /// \param L Lua state.
-template <typename Hasher>
+template <cm_hash_function hash_function>
 static int cartesi_mod_hasher(lua_State *L) {
-    using namespace cartesi;
     const auto nargs = lua_gettop(L);
     if (nargs > 2) {
         luaL_argerror(L, 3, "too many arguments");
@@ -79,28 +76,41 @@ static int cartesi_mod_hasher(lua_State *L) {
     const auto *data1 = reinterpret_cast<const unsigned char *>(luaL_checklstring(L, 1, &len1));
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
     const auto *data2 = reinterpret_cast<const unsigned char *>(luaL_optlstring(L, 2, "", &len2));
-    Hasher h;
-    machine_hash hash;
-    if (len2 > 0) { // Generic concat hash
-        h.concat_hash(std::span<const unsigned char>{data1, len1}, std::span<const unsigned char>{data2, len2}, hash);
-    } else { // Generic hash
-        h.hash(std::span<const unsigned char>{data1, len1}, hash);
+
+    cm_hash hash{};
+
+    if (len2 > 0) { // Concat hash of two inputs
+        if (len1 != CM_HASH_SIZE || len2 != CM_HASH_SIZE) {
+            luaL_argerror(L, 1, "concatenate hash is only supported for inputs with size of hash");
+        }
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        const auto *left = reinterpret_cast<const cm_hash *>(data1);
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        const auto *right = reinterpret_cast<const cm_hash *>(data2);
+        if (cm_get_concat_hash(hash_function, left, right, &hash) != 0) {
+            return luaL_error(L, "%s", cm_get_last_error_message());
+        }
+    } else { // Single hash
+        if (cm_get_hash(hash_function, data1, len1, &hash) != 0) {
+            return luaL_error(L, "%s", cm_get_last_error_message());
+        }
     }
+
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-    lua_pushlstring(L, reinterpret_cast<const char *>(hash.data()), hash.size());
+    lua_pushlstring(L, reinterpret_cast<const char *>(hash), sizeof(hash));
     return 1;
 }
 
 /// \brief This is the cartesi.keccak256() function implementation.
 /// \param L Lua state.
 static int cartesi_mod_keccak256(lua_State *L) {
-    return cartesi_mod_hasher<cartesi::keccak_256_hasher>(L);
+    return cartesi_mod_hasher<CM_HASH_KECCAK256>(L);
 }
 
 /// \brief This is the cartesi.sha256() function implementation.
 /// \param L Lua state.
 static int cartesi_mod_sha256(lua_State *L) {
-    return cartesi_mod_hasher<cartesi::sha_256_hasher>(L);
+    return cartesi_mod_hasher<CM_HASH_SHA256>(L);
 }
 
 static int cartesi_mod_tobase64(lua_State *L) try {
diff --git a/src/machine-c-api.cpp b/src/machine-c-api.cpp
index b62516dcb..c7157974e 100644
--- a/src/machine-c-api.cpp
+++ b/src/machine-c-api.cpp
@@ -24,6 +24,7 @@
 #include <memory>
 #include <new>
 #include <optional>
+#include <ranges>
 #include <regex>
 #include <stdexcept>
 #include <string>
@@ -38,6 +39,7 @@
 #include "i-machine.h"
 #include "interpret.h"
 #include "json-util.h"
+#include "keccak-256-hasher.h"
 #include "local-machine.h"
 #include "machine-c-api-internal.h"
 #include "machine-config.h"
@@ -46,6 +48,7 @@
 #include "machine-runtime-config.h"
 #include "machine.h"
 #include "os-features.h"
+#include "sha-256-hasher.h"
 
 static std::string &get_last_err_msg_storage() {
     static THREAD_LOCAL std::string last_err_msg;
@@ -478,10 +481,20 @@ static cartesi::machine_hash convert_from_c(const cm_hash *c_hash) {
         throw std::invalid_argument("invalid hash");
     }
     cartesi::machine_hash cpp_hash; // In emulator this is std::array<unsigned char, hash_size>;
-    memcpy(cpp_hash.data(), c_hash, sizeof(cm_hash));
+    std::memcpy(cpp_hash.data(), c_hash, sizeof(cm_hash));
     return cpp_hash;
 }
 
+static void convert_to_c(cartesi::machine_hash cpp_hash, cm_hash *c_hash) {
+    if (c_hash == nullptr) {
+        throw std::invalid_argument("invalid hash output");
+    }
+    using elem_t = std::ranges::range_value_t<cm_hash>;
+    constexpr auto elem_n = std::extent_v<cm_hash>;
+    static_assert(std::ranges::size(cpp_hash) == elem_n);
+    std::ranges::copy(cpp_hash | cartesi::views::cast_to<elem_t>, std::ranges::data(*c_hash));
+}
+
 // ----------------------------------------------
 // The C API implementation
 // ----------------------------------------------
@@ -807,30 +820,18 @@ cm_error cm_get_proof(const cm_machine *m, uint64_t address, int32_t log2_size,
 }
 
 cm_error cm_get_root_hash(const cm_machine *m, cm_hash *hash) try {
-    if (hash == nullptr) {
-        throw std::invalid_argument("invalid hash output");
-    }
     const auto *cpp_m = convert_from_c(m);
-    cartesi::machine_hash cpp_hash = cpp_m->get_root_hash();
-    using elem_t = std::ranges::range_value_t<cm_hash>;
-    constexpr auto elem_n = std::extent_v<cm_hash>;
-    static_assert(std::ranges::size(cpp_hash) == elem_n);
-    std::ranges::copy(cpp_hash | cartesi::views::cast_to<elem_t>, std::ranges::data(*hash));
+    const cartesi::machine_hash cpp_hash = cpp_m->get_root_hash();
+    convert_to_c(cpp_hash, hash);
     return cm_result_success();
 } catch (...) {
     return cm_result_failure();
 }
 
 cm_error cm_get_node_hash(const cm_machine *m, uint64_t address, int log2_size, cm_hash *hash) try {
-    if (hash == nullptr) {
-        throw std::invalid_argument("invalid hash output");
-    }
     const auto *cpp_m = convert_from_c(m);
-    cartesi::machine_hash cpp_hash = cpp_m->get_node_hash(address, log2_size);
-    using elem_t = std::ranges::range_value_t<cm_hash>;
-    constexpr auto elem_n = std::extent_v<cm_hash>;
-    static_assert(std::ranges::size(cpp_hash) == elem_n);
-    std::ranges::copy(cpp_hash | cartesi::views::cast_to<elem_t>, std::ranges::data(*hash));
+    const cartesi::machine_hash cpp_hash = cpp_m->get_node_hash(address, log2_size);
+    convert_to_c(cpp_hash, hash);
     return cm_result_success();
 } catch (...) {
     return cm_result_failure();
@@ -1165,3 +1166,58 @@ cm_error cm_verify_send_cmio_response(const cm_machine *m, uint16_t reason, cons
 } catch (...) {
     return cm_result_failure();
 }
+
+cm_error cm_get_hash(cm_hash_function hash_function, const uint8_t *data, uint64_t length, cm_hash *result) try {
+    if (data == nullptr && length > 0) {
+        throw std::invalid_argument("invalid data input");
+    }
+    const std::span<const unsigned char> data_span{data, length};
+    cartesi::machine_hash cpp_result;
+
+    switch (hash_function) {
+        case CM_HASH_KECCAK256: {
+            cartesi::keccak_256_hasher hasher;
+            hasher.hash(data_span, cpp_result);
+            break;
+        }
+        case CM_HASH_SHA256: {
+            cartesi::sha_256_hasher hasher;
+            hasher.hash(data_span, cpp_result);
+            break;
+        }
+        default:
+            throw std::invalid_argument("invalid hash function");
+    }
+
+    convert_to_c(cpp_result, result);
+    return cm_result_success();
+} catch (...) {
+    return cm_result_failure();
+}
+
+cm_error cm_get_concat_hash(cm_hash_function hash_function, const cm_hash *left, const cm_hash *right,
+    cm_hash *result) try {
+    cartesi::machine_hash cpp_left = convert_from_c(left);
+    cartesi::machine_hash cpp_right = convert_from_c(right);
+    cartesi::machine_hash cpp_result;
+
+    switch (hash_function) {
+        case CM_HASH_KECCAK256: {
+            cartesi::keccak_256_hasher h;
+            h.concat_hash(cpp_left, cpp_right, cpp_result);
+            break;
+        }
+        case CM_HASH_SHA256: {
+            cartesi::sha_256_hasher h;
+            h.concat_hash(cpp_left, cpp_right, cpp_result);
+            break;
+        }
+        default:
+            throw std::invalid_argument("invalid hash function");
+    }
+
+    convert_to_c(cpp_result, result);
+    return cm_result_success();
+} catch (...) {
+    return cm_result_failure();
+}
diff --git a/src/machine-c-api.h b/src/machine-c-api.h
index b8ad27c53..ac26501e5 100644
--- a/src/machine-c-api.h
+++ b/src/machine-c-api.h
@@ -291,6 +291,12 @@ typedef enum cm_reg {
     CM_REG_LAST_ = CM_REG_UARCH_HALT_FLAG,
 } cm_reg;
 
+/// \brief Hash function types.
+typedef enum cm_hash_function {
+    CM_HASH_KECCAK256 = 0, ///< Keccak-256 (recommended for fraud proofs using microarchitecture)
+    CM_HASH_SHA256 = 1,    ///< SHA-256 (recommended for fraud proofs using zkVMs)
+} cm_hash_function;
+
 /// \brief Storage for machine hash.
 typedef uint8_t cm_hash[CM_HASH_SIZE];
 
@@ -799,6 +805,29 @@ CM_API cm_error cm_verify_hash_tree(cm_machine *m, bool *result);
 /// \returns 0 for success, non zero code for error.
 CM_API cm_error cm_get_hash_tree_stats(cm_machine *m, bool clear, const char **stats);
 
+// ------------------------------------
+// Hashing
+// ------------------------------------
+
+/// \brief Gets the hash of data.
+/// \param hash_function Hash function to use.
+/// \param data Data to hash.
+/// \param length Length of data in bytes.
+/// \param result Valid pointer to cm_hash (32-byte array) that receives the hash.
+/// \returns 0 for success, non zero code for error.
+/// \details This function is optimized to hash words of hash trees, but can be used for any data.
+CM_API cm_error cm_get_hash(cm_hash_function hash_function, const uint8_t *data, uint64_t length, cm_hash *result);
+
+/// \brief Gets the hash of a concatenation of two hashes.
+/// \param hash_function Hash function to use.
+/// \param left Left hash to concatenate.
+/// \param right Right hash to concatenate.
+/// \param result Valid pointer to cm_hash (32-byte array) that receives the hash.
+/// \returns 0 for success, non zero code for error.
+/// \details This function is optimized and intended to be used for concatenating hashes of hash trees.
+CM_API cm_error cm_get_concat_hash(cm_hash_function hash_function, const cm_hash *left, const cm_hash *right,
+    cm_hash *result);
+
 #ifdef __cplusplus
 }
 #endif

From c89ae309cfbcc1d73a374f9ef73b48366e451e27 Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Sun, 2 Feb 2025 15:54:58 -0300
Subject: [PATCH 54/82] feat: optimize SQRT instruction using digit-by-digit
 calculation

---
 src/soft-float.h | 41 ++++++++++++++++-------------------------
 1 file changed, 16 insertions(+), 25 deletions(-)

diff --git a/src/soft-float.h b/src/soft-float.h
index d87040be8..0f23ced34 100644
--- a/src/soft-float.h
+++ b/src/soft-float.h
@@ -123,33 +123,24 @@ template <typename UINT>
 static bool sqrtrem_u(UINT *pr, UINT ah, UINT al) {
     using ULONG = typename make_long_uint<UINT>::type;
     constexpr int UINT_SIZE = sizeof(UINT) * 8;
-    int l = 0;
-    // 2^l >= a
-    if (ah != 0) {
-        l = 2 * UINT_SIZE - clz(ah - 1);
-    } else {
-        // This branch will actually never be taken,
-        // because at this moment sqrtrem_u() is only called by sqrt() which makes sure that ah > 0
-        // LCOV_EXCL_START
-        if (al == 0) {
-            *pr = 0;
-            return false;
+    const ULONG a = (static_cast<ULONG>(ah) << UINT_SIZE) | al;
+
+    // Perform "digit‐by‐digit" square root extraction in base 2.
+    // See https://en.wikipedia.org/wiki/Methods_of_computing_square_roots#Binary_numeral_system_(base_2)
+    ULONG res = 0;
+    ULONG rem = a; // Will eventually hold a - res^2
+    for (ULONG bit = static_cast<ULONG>(1) << ((2 * UINT_SIZE) - 2); bit != 0; bit >>= 2) {
+        const ULONG tmp = res + bit;
+        if (rem >= tmp) {
+            rem -= tmp;
+            res = (res >> 1) + bit;
+        } else {
+            res >>= 1;
         }
-        l = UINT_SIZE - clz(al - 1);
-        // LCOV_EXCL_STOP
     }
-    const ULONG a = (static_cast<ULONG>(ah) << UINT_SIZE) | al;
-    ULONG u = static_cast<ULONG>(1) << ((l + 1) / 2);
-    ULONG s = 0;
-    // NOLINTBEGIN(cppcoreguidelines-avoid-do-while)
-    do {
-        s = u;
-        // here we divide by two by shifting 1 bit to the right as an optimization
-        u = ((a / s) + s) >> 1;
-    } while (u < s);
-    // NOLINTEND(cppcoreguidelines-avoid-do-while)
-    *pr = static_cast<UINT>(s);
-    return (a - s * s) != 0;
+
+    *pr = static_cast<UINT>(res);
+    return (rem != 0);
 }
 
 /// \class i_sfloat

From 2a838e658d22a79072093f4073ae35774848c89d Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Wed, 7 May 2025 12:12:30 -0300
Subject: [PATCH 55/82] feat!: add sharing modes to the C API

---
 src/Makefile                      |   1 +
 src/address-range.h               |  10 +
 src/cartesi-machine.lua           | 127 +++++--
 src/clua-cartesi.cpp              |   3 +
 src/clua-i-machine.cpp            |  36 +-
 src/i-machine.h                   |  26 +-
 src/json-util.cpp                 |  49 +++
 src/json-util.h                   |  14 +
 src/jsonrpc-discover.json         |  59 ++++
 src/jsonrpc-machine.cpp           |  19 +-
 src/jsonrpc-machine.h             |   8 +-
 src/jsonrpc-remote-machine.cpp    |  45 ++-
 src/local-machine.cpp             |  17 +-
 src/local-machine.h               |   8 +-
 src/machine-address-ranges.cpp    | 157 ++++++---
 src/machine-address-ranges.h      |  12 +-
 src/machine-c-api.cpp             |  46 ++-
 src/machine-c-api.h               |  43 ++-
 src/machine-config.cpp            | 104 ++++--
 src/machine-config.h              |  36 +-
 src/machine-runtime-config.h      |   1 +
 src/machine.cpp                   | 189 ++++++-----
 src/machine.h                     |  34 +-
 src/memory-address-range.cpp      |  61 ++--
 src/memory-address-range.h        |  21 +-
 src/os-features.h                 |  10 +-
 src/os-filesystem.cpp             | 542 ++++++++++++++++++++++++++++++
 src/os-filesystem.h               | 130 +++++++
 src/os-mmap.cpp                   | 245 ++++----------
 src/os-mmap.h                     |  16 +-
 src/os-posix-compat.h             | 182 ++++++++++
 src/os.cpp                        | 103 +-----
 src/os.h                          |  41 ---
 src/record-step-state-access.h    |   3 +-
 src/scope-remove.h                |  92 +++++
 src/virtio-p9fs-address-range.cpp | 132 ++------
 tests/misc/test-machine-c-api.cpp |  56 +--
 37 files changed, 1911 insertions(+), 767 deletions(-)
 create mode 100644 src/os-filesystem.cpp
 create mode 100644 src/os-filesystem.h
 create mode 100644 src/os-posix-compat.h
 create mode 100644 src/scope-remove.h

diff --git a/src/Makefile b/src/Makefile
index 54d232b0d..c76d61c33 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -365,6 +365,7 @@ LIBCARTESI_OBJS:= \
 	memory-address-range.o \
 	os.o \
 	os-mmap.o \
+	os-filesystem.o \
 	plic-address-range.o \
 	pristine-merkle-tree.o \
 	replay-step-state-access-interop.o \
diff --git a/src/address-range.h b/src/address-range.h
index 2750ba23e..8525fb7ae 100644
--- a/src/address-range.h
+++ b/src/address-range.h
@@ -313,6 +313,12 @@ class address_range {
         return do_is_host_read_only();
     }
 
+    /// \brief Returns true if the mapped memory is shared with a backing store in the host
+    /// \returns True if the memory is shared in the host
+    bool is_backing_store_shared() const noexcept {
+        return do_is_backing_store_shared();
+    }
+
 protected:
     /// \brief Returns number of levels in a tree where each leaf is a page
     /// \param length Length of range, in bytes
@@ -351,6 +357,10 @@ class address_range {
         return false;
     }
 
+    virtual bool do_is_backing_store_shared() const noexcept {
+        return false;
+    }
+
 #ifndef MICROARCHITECTURE
     // Default implemenationt returns always dirty tree
     virtual const i_dirty_page_tree &do_get_dirty_page_tree() const noexcept {
diff --git a/src/cartesi-machine.lua b/src/cartesi-machine.lua
index 9d0e5bdee..6d7effcf3 100755
--- a/src/cartesi-machine.lua
+++ b/src/cartesi-machine.lua
@@ -339,6 +339,11 @@ where options are:
 
     DON'T USE THIS OPTION IN PRODUCTION
 
+  --no-reserve
+    don't reserve swap memory for flash drives.
+
+    DON'T USE THIS OPTION IN PRODUCTION
+
   --max-mcycle=<number>
     stop at a given mcycle (default: 2305843009213693952).
 
@@ -489,12 +494,47 @@ where options are:
   --no-htif-yield-automatic
     do not honor yield requests with automatic reset by target.
 
-  --store=<directory>
+  --create=<directory>
+    initializes a machine using fully on-disk state stored to <directory>,
+    the effect is similar as creating a machine and using --store=<directory>,
+    however this is the only safe way to create machines with large address spaces
+    or to propagate "shared" backing stores to configuration files.
+
+    MUST BE USED WITH --no-rollback
+
+  --load=<directory>[,<key>:<value>[,...]...]
+    load machine stored in <directory>.
+
+    <key>:<value> is one of
+        clone:<source_directory>
+        sharing:<mode>
+
+        clone (optional)
+        clones previously stored machine from <source_directory> to <directory> and loads it.
+        writable address ranges use reference links on copy-on-write filesystems.
+        read-only address ranges use hard links to avoid unnecessary copying.
+        files sparsity is preserved to minimize storage usage.
+
+        sharing (optional)
+        affects how address ranges modifications reflect the loaded backing stores:
+            none: keeps state in-memory only; no backing store modifications.
+            config: only configured "shared" backing stores operate on-disk and are modified.
+            all: keeps state on-disk, modifying all backing stores.
+        the default mode is "none", but if clone is present then the default mode is "all".
+        all modes except "none" MUST BE USED WITH --no-rollback.
+
+  --store=<directory>[,<key>:<value>[,...]...]
     store machine to <directory>, where "%%h" is substituted by the
     state hash in the directory name.
 
-  --load=<directory>
-    load machine previously stored in <directory>.
+    <key>:<value> is one of
+        sharing:<mode>
+
+        sharing (optional)
+        affects how address ranges modifications reflect the new backing stores:
+            none: copies backing stores as they were during load (rarely useful).
+            config: store "shared" backing stores from current state; others are copied as they were during load.
+            all: (default) store current state for all backings stores.
 
   --initial-hash
     print initial state hash before running machine.
@@ -713,6 +753,7 @@ local concurrency_update_hash_tree = 0
 local skip_root_hash_check = false
 local skip_root_hash_store = false
 local skip_version_check = false
+local no_reserve = false
 local htif_no_console_putchar = false
 local initial_hash = false
 local final_hash = false
@@ -730,6 +771,10 @@ local auto_reset_uarch = false
 local log_reset_uarch = false
 local store_dir
 local load_dir
+local create_dir
+local clone_dir
+local load_sharing
+local store_sharing
 local cmdline_opts_finished = false
 local store_config = false
 local store_json_config = false
@@ -1349,6 +1394,14 @@ local options = {
             return true
         end,
     },
+    {
+        "^%-%-no%-reserve$",
+        function(all)
+            if not all then return false end
+            no_reserve = true
+            return true
+        end,
+    },
     {
         "^(%-%-initial%-proof%=(.+))$",
         function(all, opts)
@@ -1469,18 +1522,49 @@ local options = {
         end,
     },
     {
-        "^%-%-load%=(.*)$",
+        "^%-%-create%=(.*)$",
         function(opts)
             if not opts or #opts < 1 then return false end
-            load_dir = opts
+            create_dir = opts
+            return true
+        end,
+    },
+    {
+        "^%-%-load%=(([^,]+),?(.*))$",
+        function(all, dir, opts)
+            if not all or not dir then return false end
+            if #opts > 0 then
+                local o = util.parse_options(opts, all, {
+                    clone = "string",
+                    sharing = {
+                        none = cartesi.SHARING_NONE,
+                        config = cartesi.SHARING_CONFIG,
+                        all = cartesi.SHARING_ALL,
+                    },
+                })
+                clone_dir = o.clone
+                load_sharing = o.sharing
+                if clone_dir and not load_sharing then load_sharing = cartesi.SHARING_ALL end
+            end
+            load_dir = dir
             return true
         end,
     },
     {
-        "^%-%-store%=(.*)$",
-        function(opts)
-            if not opts or #opts < 1 then return false end
-            store_dir = opts
+        "^%-%-store%=(([^,]+),?(.*))$",
+        function(all, dir, opts)
+            if not all or not dir then return false end
+            if #opts > 0 then
+                local o = util.parse_options(opts, all, {
+                    sharing = {
+                        none = cartesi.SHARING_NONE,
+                        config = cartesi.SHARING_CONFIG,
+                        all = cartesi.SHARING_ALL,
+                    },
+                })
+                store_sharing = o.sharing
+            end
+            store_dir = dir
             return true
         end,
     },
@@ -1855,6 +1939,7 @@ local runtime_config = {
     skip_root_hash_check = skip_root_hash_check,
     skip_root_hash_store = skip_root_hash_store,
     skip_version_check = skip_version_check,
+    no_reserve = no_reserve,
 }
 
 if remote_spawn then
@@ -1865,13 +1950,17 @@ if remote_spawn then
     remote_address = address
 end
 
-local main_machine
-if remote_address and not remote_create then
-    main_machine = new_machine()
-elseif load_dir then
+if create_dir then
+    assert(not (remote_address and not remote_create), "cannot use --create and --no-remote-create at the same time")
+    assert(not load_dir, "cannot use --create and --load at the same time")
+end
+
+local main_machine = new_machine()
+if load_dir then
     stderr("Loading machine: please wait\n")
-    main_machine = new_machine():load(load_dir, runtime_config)
-else
+    if clone_dir then main_machine:clone_stored(clone_dir, load_dir) end
+    main_machine = main_machine:load(load_dir, runtime_config, load_sharing)
+elseif not (remote_address and not remote_create) then
     -- Build machine config
     local config = {
         processor = processor,
@@ -1990,7 +2079,7 @@ echo "
         config = setmetatable(cartesi.fromjson(f:read("a")), { __index = config })
     end
 
-    main_machine = new_machine():create(config, runtime_config)
+    main_machine = main_machine:create(config, runtime_config, create_dir)
 end
 
 for _, r in ipairs(memory_range_replace) do
@@ -2154,13 +2243,13 @@ local function save_cmio_inspect_state_report(inspect, data)
     f:close()
 end
 
-local function store_machine(machine, config, dir)
+local function store_machine(machine, config, dir, sharing)
     assert(config.processor.registers.iunrep == 0, "hashes are meaningless in unreproducible mode")
     stderr("Storing machine: please wait\n")
     local values = {}
     if dir:find("%%h") then values.h = util.hexhash(machine:get_root_hash()) end
     local name = instantiate_filename(dir, values)
-    machine:store(name)
+    machine:store(name, sharing)
 end
 
 local function dump_pmas(machine)
@@ -2443,7 +2532,7 @@ if final_hash then
     print_root_hash(machine, stderr_unsilenceable)
 end
 dump_value_proofs(machine, final_proof, config)
-if store_dir then store_machine(machine, config, store_dir) end
+if store_dir then store_machine(machine, config, store_dir, store_sharing) end
 if assert_rolling_template then
     local cmd, reason = machine:receive_cmio_request()
     if not (cmd == cartesi.CMIO_YIELD_COMMAND_MANUAL and reason == cartesi.CMIO_YIELD_MANUAL_REASON_RX_ACCEPTED) then
diff --git a/src/clua-cartesi.cpp b/src/clua-cartesi.cpp
index b8176f619..88476d1ba 100644
--- a/src/clua-cartesi.cpp
+++ b/src/clua-cartesi.cpp
@@ -237,6 +237,9 @@ CM_API int luaopen_cartesi(lua_State *L) {
     clua_setintegerfield(L, CM_CMIO_YIELD_MANUAL_REASON_TX_EXCEPTION, "CMIO_YIELD_MANUAL_REASON_TX_EXCEPTION", -1);
     clua_setintegerfield(L, CM_CMIO_YIELD_REASON_ADVANCE_STATE, "CMIO_YIELD_REASON_ADVANCE_STATE", -1);
     clua_setintegerfield(L, CM_CMIO_YIELD_REASON_INSPECT_STATE, "CMIO_YIELD_REASON_INSPECT_STATE", -1);
+    clua_setintegerfield(L, CM_SHARING_NONE, "SHARING_NONE", -1);
+    clua_setintegerfield(L, CM_SHARING_CONFIG, "SHARING_CONFIG", -1);
+    clua_setintegerfield(L, CM_SHARING_ALL, "SHARING_ALL", -1);
     clua_setintegerfield(L, CM_AR_CMIO_RX_BUFFER_START, "AR_CMIO_RX_BUFFER_START", -1);
     clua_setintegerfield(L, CM_AR_CMIO_RX_BUFFER_LOG2_SIZE, "AR_CMIO_RX_BUFFER_LOG2_SIZE", -1);
     clua_setintegerfield(L, CM_AR_CMIO_TX_BUFFER_START, "AR_CMIO_TX_BUFFER_START", -1);
diff --git a/src/clua-i-machine.cpp b/src/clua-i-machine.cpp
index 7f99c4d44..41bcab392 100644
--- a/src/clua-i-machine.cpp
+++ b/src/clua-i-machine.cpp
@@ -786,8 +786,23 @@ static int machine_obj_index_log_step_uarch(lua_State *L) {
 /// \brief This is the machine:store() method implementation.
 /// \param L Lua state.
 static int machine_obj_index_store(lua_State *L) {
+    lua_settop(L, 3);
     auto &m = clua_check<clua_managed_cm_ptr<cm_machine>>(L, 1);
-    if (cm_store(m.get(), luaL_checkstring(L, 2)) != 0) {
+    const char *dir = luaL_checkstring(L, 2);
+    const auto sharing = static_cast<cm_sharing_mode>(luaL_optinteger(L, 3, CM_SHARING_ALL));
+    if (cm_store(m.get(), dir, sharing) != 0) {
+        return luaL_error(L, "%s", cm_get_last_error_message());
+    }
+    return 0;
+}
+
+/// \brief This is the machine:clone_stored() method implementation.
+/// \param L Lua state.
+static int machine_obj_index_clone_stored(lua_State *L) {
+    auto &m = clua_check<clua_managed_cm_ptr<cm_machine>>(L, 1);
+    const char *from_dir = luaL_checkstring(L, 2);
+    const char *to_dir = luaL_checkstring(L, 3);
+    if (cm_clone_stored(m.get(), from_dir, to_dir) != 0) {
         return luaL_error(L, "%s", cm_get_last_error_message());
     }
     return 0;
@@ -959,12 +974,13 @@ static int machine_obj_index_is_empty(lua_State *L) {
 /// \brief This is the machine:create() method implementation.
 /// \param L Lua state.
 static int machine_obj_index_create(lua_State *L) {
-    lua_settop(L, 3);
+    lua_settop(L, 4);
     auto &m = clua_check<clua_managed_cm_ptr<cm_machine>>(L, 1);
     const char *runtime_config = !lua_isnil(L, 3) ? clua_check_json_string(L, 3) : nullptr;
+    const char *dir = luaL_optstring(L, 4, nullptr);
     // Create or load a machine depending on the type of the first argument
     const char *config = clua_check_json_string(L, 2);
-    if (cm_create(m.get(), config, runtime_config) != 0) {
+    if (cm_create(m.get(), config, runtime_config, dir) != 0) {
         return luaL_error(L, "%s", cm_get_last_error_message());
     }
     lua_settop(L, 1);
@@ -1004,11 +1020,12 @@ static int machine_obj_index_collect_uarch_cycle_root_hashes(lua_State *L) {
 /// \brief This is the machine:load() method implementation.
 /// \param L Lua state.
 static int machine_obj_index_load(lua_State *L) {
-    lua_settop(L, 3);
+    lua_settop(L, 4);
     auto &m = clua_check<clua_managed_cm_ptr<cm_machine>>(L, 1);
     const char *runtime_config = !lua_isnil(L, 3) ? clua_check_json_string(L, 3) : nullptr;
     const char *dir = luaL_checkstring(L, 2);
-    if (cm_load(m.get(), dir, runtime_config) != 0) {
+    const auto sharing = static_cast<cm_sharing_mode>(luaL_optinteger(L, 4, CM_SHARING_NONE));
+    if (cm_load(m.get(), dir, runtime_config, sharing) != 0) {
         return luaL_error(L, "%s", cm_get_last_error_message());
     }
     lua_settop(L, 1);
@@ -1151,6 +1168,7 @@ static const auto machine_obj_index = cartesi::clua_make_luaL_Reg_array({
     {"send_cmio_response", machine_obj_index_send_cmio_response},
     {"set_runtime_config", machine_obj_index_set_runtime_config},
     {"store", machine_obj_index_store},
+    {"clone_stored", machine_obj_index_clone_stored},
     {"swap", machine_obj_index_swap},
     {"translate_virtual_address", machine_obj_index_translate_virtual_address},
     {"verify_hash_tree", machine_obj_index_verify_hash_tree},
@@ -1169,7 +1187,7 @@ static const auto machine_obj_index = cartesi::clua_make_luaL_Reg_array({
 static int machine_meta_call(lua_State *L) {
     // This receives the source machine that is being "called" as the first argument,
     // either a config or a directory as second argument, and an optional runtime config as third argument.
-    lua_settop(L, 3);
+    lua_settop(L, 4);
     auto &m = clua_check<clua_managed_cm_ptr<cm_machine>>(L, 1); // source machine
     // We could be creating a local machine or a remote machine.
     // When we call cm_clone_empty(m.get(), ...), it creates a new empty object from the same underlying type as
@@ -1182,12 +1200,14 @@ static int machine_meta_call(lua_State *L) {
     // Create or load a machine depending on the type of the first argument
     if (lua_isstring(L, 2) == 0) {
         const char *config = clua_check_json_string(L, 2);
-        if (cm_create(new_m.get(), config, runtime_config) != 0) {
+        const char *dir = luaL_optstring(L, 4, nullptr);
+        if (cm_create(new_m.get(), config, runtime_config, dir) != 0) {
             return luaL_error(L, "%s", cm_get_last_error_message());
         }
     } else {
         const char *dir = luaL_checkstring(L, 2);
-        if (cm_load(new_m.get(), dir, runtime_config) != 0) {
+        const auto sharing = static_cast<cm_sharing_mode>(luaL_optinteger(L, 4, CM_SHARING_NONE));
+        if (cm_load(new_m.get(), dir, runtime_config, sharing) != 0) {
             return luaL_error(L, "%s", cm_get_last_error_message());
         }
     }
diff --git a/src/i-machine.h b/src/i-machine.h
index 9bc8287a9..7f7e8f8dd 100644
--- a/src/i-machine.h
+++ b/src/i-machine.h
@@ -72,13 +72,14 @@ class i_machine {
     }
 
     /// \brief Create a machine from config
-    void create(const machine_config &config, const machine_runtime_config &runtime = {}) {
-        do_create(config, runtime);
+    void create(const machine_config &config, const machine_runtime_config &runtime = {}, const std::string &dir = {}) {
+        do_create(config, runtime, dir);
     }
 
     /// \brief Load Create a machine from config
-    void load(const std::string &directory, const machine_runtime_config &runtime = {}) {
-        do_load(directory, runtime);
+    void load(const std::string &directory, const machine_runtime_config &runtime = {},
+        const sharing_mode sharing = sharing_mode::none) {
+        do_load(directory, runtime, sharing);
     }
 
     /// \brief Runs the machine until mcycle reaches mcycle_end or the machine halts.
@@ -94,8 +95,13 @@ class i_machine {
     }
 
     /// \brief Serialize entire state to directory
-    void store(const std::string &dir) const {
-        do_store(dir);
+    void store(const std::string &dir, sharing_mode sharing = sharing_mode::all) const {
+        do_store(dir, sharing);
+    }
+
+    /// \brief Clones a machine stored from source directory to destination directory
+    void clone_stored(const std::string &from_dir, const std::string &to_dir) const {
+        do_clone_stored(from_dir, to_dir);
     }
 
     /// \brief  Runs the machine for the given mcycle count and generates a log file of accessed pages and proof data.
@@ -285,12 +291,14 @@ class i_machine {
 private:
     virtual i_machine *do_clone_empty() const = 0;
     virtual bool do_is_empty() const = 0;
-    virtual void do_create(const machine_config &config, const machine_runtime_config &runtime) = 0;
-    virtual void do_load(const std::string &directory, const machine_runtime_config &runtime) = 0;
+    virtual void do_create(const machine_config &config, const machine_runtime_config &runtime,
+        const std::string &dir) = 0;
+    virtual void do_load(const std::string &directory, const machine_runtime_config &runtime, sharing_mode sharing) = 0;
     virtual interpreter_break_reason do_run(uint64_t mcycle_end) = 0;
     virtual void do_collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_period, uint64_t period_count,
         mcycle_root_hashes &result) = 0;
-    virtual void do_store(const std::string &dir) const = 0;
+    virtual void do_store(const std::string &dir, sharing_mode sharing) const = 0;
+    virtual void do_clone_stored(const std::string &from_dir, const std::string &to_dir) const = 0;
     virtual interpreter_break_reason do_log_step(uint64_t mcycle_count, const std::string &filename) = 0;
     virtual access_log do_log_step_uarch(const access_log::type &log_type) = 0;
     virtual hash_tree_proof do_get_proof(uint64_t address, int log2_size) const = 0;
diff --git a/src/json-util.cpp b/src/json-util.cpp
index c1c7645fe..32001e688 100644
--- a/src/json-util.cpp
+++ b/src/json-util.cpp
@@ -221,6 +221,31 @@ static auto reg_from_name(const std::string &name) {
     return got->second;
 }
 
+static auto sharing_mode_to_name(sharing_mode sharing) {
+    switch (sharing) {
+        case sharing_mode::none:
+            return "none";
+        case sharing_mode::config:
+            return "config";
+        case sharing_mode::all:
+            return "all";
+        default:
+            throw std::domain_error{"invalid sharing mode"};
+            break;
+    }
+    return "";
+}
+
+static sharing_mode sharing_mode_from_name(const std::string &name) {
+    const static std::unordered_map<std::string, sharing_mode> g_sharing_name = {{"none", sharing_mode::none},
+        {"config", sharing_mode::config}, {"all", sharing_mode::all}};
+    auto got = g_sharing_name.find(name);
+    if (got == g_sharing_name.end()) {
+        throw std::domain_error{"invalid sharing mode"};
+    }
+    return got->second;
+}
+
 static auto reg_to_name(machine_reg r) {
     using reg = machine_reg;
     switch (r) {
@@ -779,6 +804,24 @@ template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t
 template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key, machine_reg &value,
     const std::string &path);
 
+template <typename K>
+void ju_get_opt_field(const nlohmann::json &j, const K &key, sharing_mode &value, const std::string &path) {
+    if (!contains(j, key, path)) {
+        return;
+    }
+    const auto &jk = j[key];
+    if (!jk.is_string()) {
+        throw std::invalid_argument("\""s + path + to_string(key) + "\" not a string");
+    }
+    value = sharing_mode_from_name(jk.template get<std::string>());
+}
+
+template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, sharing_mode &value,
+    const std::string &path);
+
+template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key, sharing_mode &value,
+    const std::string &path);
+
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, interpreter_break_reason &value, const std::string &path) {
     if (!contains(j, key, path)) {
@@ -856,6 +899,7 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, machine_runtime_con
     ju_get_opt_field(j[key], "skip_root_hash_store"s, value.skip_root_hash_store, path + to_string(key) + "/");
     ju_get_opt_field(j[key], "skip_version_check"s, value.skip_version_check, path + to_string(key) + "/");
     ju_get_opt_field(j[key], "soft_yield"s, value.soft_yield, path + to_string(key) + "/");
+    ju_get_opt_field(j[key], "no_reserve"s, value.no_reserve, path + to_string(key) + "/");
 }
 
 template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, machine_runtime_config &value,
@@ -1890,6 +1934,10 @@ void to_json(nlohmann::json &j, const machine_reg &reg) {
     j = reg_to_name(reg);
 }
 
+void to_json(nlohmann::json &j, const sharing_mode &sharing) {
+    j = sharing_mode_to_name(sharing);
+}
+
 void to_json(nlohmann::json &j, const base64_machine_hash &h) {
     j = encode_base64(h.get());
 }
@@ -2214,6 +2262,7 @@ void to_json(nlohmann::json &j, const machine_runtime_config &runtime) {
         {"skip_root_hash_store", runtime.skip_root_hash_store},
         {"skip_version_check", runtime.skip_version_check},
         {"soft_yield", runtime.soft_yield},
+        {"no_reserve", runtime.no_reserve},
     };
 }
 
diff --git a/src/json-util.h b/src/json-util.h
index 24be6237b..e6867e571 100644
--- a/src/json-util.h
+++ b/src/json-util.h
@@ -157,6 +157,15 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, semantic_version &v
 template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, machine_reg &value, const std::string &path = "params/");
 
+/// \brief Attempts to load an sharing_mode name from a field in a JSON object
+/// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
+/// \param j JSON object to load from
+/// \param key Key to load value from
+/// \param value Object to store value
+/// \param path Path to j
+template <typename K>
+void ju_get_opt_field(const nlohmann::json &j, const K &key, sharing_mode &value, const std::string &path = "params/");
+
 /// \brief Attempts to load an interpreter_break_reason name from a field in a JSON object
 /// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
 /// \param j JSON object to load from
@@ -719,6 +728,7 @@ void to_json(nlohmann::json &j, const concurrency_runtime_config &config);
 void to_json(nlohmann::json &j, const htif_runtime_config &config);
 void to_json(nlohmann::json &j, const machine_runtime_config &runtime);
 void to_json(nlohmann::json &j, const machine_reg &reg);
+void to_json(nlohmann::json &j, const sharing_mode &sharing);
 void to_json(nlohmann::json &j, const address_range_description &mrd);
 void to_json(nlohmann::json &j, const address_range_descriptions &mrds);
 void to_json(nlohmann::json &j, const fork_result &fork_result);
@@ -752,6 +762,10 @@ extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &k
     const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, machine_reg &value,
     const std::string &base = "params/");
+extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, sharing_mode &value,
+    const std::string &base = "params/");
+extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, sharing_mode &value,
+    const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key, interpreter_break_reason &value,
     const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, interpreter_break_reason &value,
diff --git a/src/jsonrpc-discover.json b/src/jsonrpc-discover.json
index 18426ce06..e87b40a76 100644
--- a/src/jsonrpc-discover.json
+++ b/src/jsonrpc-discover.json
@@ -130,6 +130,13 @@
           "schema": {
             "$ref": "#/components/schemas/MachineRuntimeConfig"
           }
+        },
+        {
+          "name": "directory",
+          "description": "Directory to create an on-disk machine instance",
+          "schema": {
+            "type": "string"
+          }
         }
       ],
       "result": {
@@ -159,6 +166,14 @@
           "schema": {
             "$ref": "#/components/schemas/MachineRuntimeConfig"
           }
+        },
+        {
+          "name": "sharing",
+          "description": "Backing stores sharing mode",
+          "required": false,
+          "schema": {
+            "$ref": "#/components/schemas/SharingMode"
+          }
         }
       ],
       "result": {
@@ -192,6 +207,43 @@
           "schema": {
             "type": "string"
           }
+        },
+        {
+          "name": "sharing",
+          "description": "Backing stores sharing mode",
+          "required": true,
+          "schema": {
+            "$ref": "#/components/schemas/SharingMode"
+          }
+        }
+      ],
+      "result": {
+        "name": "status",
+        "description": "True when operation succeeded",
+        "schema": {
+          "type": "boolean"
+        }
+      }
+    },
+    {
+      "name": "machine.clone_stored",
+      "summary": "Clones a machine stored from source directory to destination directory",
+      "params": [
+        {
+          "name": "from_dir",
+          "description": "Source directory",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "to_dir",
+          "description": "Destination directory",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
         }
       ],
       "result": {
@@ -1145,6 +1197,9 @@
           },
           "soft_yield": {
             "type": "boolean"
+          },
+          "no_reserve": {
+            "type": "boolean"
           }
         }
       },
@@ -2066,6 +2121,10 @@
         },
         "required": ["log_type", "accesses"]
       },
+      "SharingMode": {
+        "title": "SharingMode",
+        "enum": ["none", "config", "all"]
+      },
       "REG": {
         "title": "REG",
         "enum": [
diff --git a/src/jsonrpc-machine.cpp b/src/jsonrpc-machine.cpp
index cd13b10ea..810b06686 100644
--- a/src/jsonrpc-machine.cpp
+++ b/src/jsonrpc-machine.cpp
@@ -554,9 +554,10 @@ jsonrpc_machine::jsonrpc_machine(const std::string & /*address*/, fork_result &
 
 #endif
 
-void jsonrpc_machine::do_load(const std::string &directory, const machine_runtime_config &runtime) {
+void jsonrpc_machine::do_load(const std::string &directory, const machine_runtime_config &runtime,
+    sharing_mode sharing) {
     bool result = false;
-    request("machine.load", std::tie(directory, runtime), result);
+    request("machine.load", std::tie(directory, runtime, sharing), result);
 }
 
 bool jsonrpc_machine::do_is_empty() const {
@@ -584,9 +585,10 @@ i_machine *jsonrpc_machine::do_clone_empty() const {
     return clone;
 };
 
-void jsonrpc_machine::do_create(const machine_config &config, const machine_runtime_config &runtime) {
+void jsonrpc_machine::do_create(const machine_config &config, const machine_runtime_config &runtime,
+    const std::string &dir) {
     bool result = false;
-    request("machine.create", std::tie(config, runtime), result);
+    request("machine.create", std::tie(config, runtime, dir), result);
 }
 
 jsonrpc_machine::~jsonrpc_machine() {
@@ -654,9 +656,14 @@ interpreter_break_reason jsonrpc_machine::do_log_step(uint64_t mcycle_count, con
     return result;
 }
 
-void jsonrpc_machine::do_store(const std::string &directory) const {
+void jsonrpc_machine::do_store(const std::string &directory, sharing_mode sharing) const {
     bool result = false;
-    request("machine.store", std::tie(directory), result);
+    request("machine.store", std::tie(directory, sharing), result);
+}
+
+void jsonrpc_machine::do_clone_stored(const std::string &from_dir, const std::string &to_dir) const {
+    bool result = false;
+    request("machine.clone_stored", std::tie(from_dir, to_dir), result);
 }
 
 uint64_t jsonrpc_machine::do_read_reg(reg r) const {
diff --git a/src/jsonrpc-machine.h b/src/jsonrpc-machine.h
index d6614df1e..ec2a93694 100644
--- a/src/jsonrpc-machine.h
+++ b/src/jsonrpc-machine.h
@@ -104,13 +104,15 @@ class jsonrpc_machine final : public i_machine {
 private:
     i_machine *do_clone_empty() const override;
     bool do_is_empty() const override;
-    void do_create(const machine_config &config, const machine_runtime_config &runtime) override;
-    void do_load(const std::string &directory, const machine_runtime_config &runtime) override;
+    void do_create(const machine_config &config, const machine_runtime_config &runtime,
+        const std::string &dir) override;
+    void do_load(const std::string &directory, const machine_runtime_config &runtime, sharing_mode sharing) override;
     interpreter_break_reason do_run(uint64_t mcycle_end) override;
     void do_collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_period, uint64_t period_count,
         mcycle_root_hashes &result) override;
     interpreter_break_reason do_log_step(uint64_t mcycle_count, const std::string &filename) override;
-    void do_store(const std::string &dir) const override;
+    void do_store(const std::string &dir, sharing_mode sharing) const override;
+    void do_clone_stored(const std::string &from_dir, const std::string &to_dir) const override;
     uint64_t do_read_reg(reg r) const override;
     void do_write_reg(reg w, uint64_t val) override;
     void do_read_memory(uint64_t address, unsigned char *data, uint64_t length) const override;
diff --git a/src/jsonrpc-remote-machine.cpp b/src/jsonrpc-remote-machine.cpp
index 0777ba59d..9957b3b5f 100644
--- a/src/jsonrpc-remote-machine.cpp
+++ b/src/jsonrpc-remote-machine.cpp
@@ -780,6 +780,9 @@ static std::string endpoint_to_string(const tcp::endpoint &endpoint) {
 /// server.
 static json jsonrpc_fork_handler(const json &j, const std::shared_ptr<http_session> &session) {
     jsonrpc_check_no_params(j);
+    if (session->handler->machine && session->handler->machine->has_shared_address_range()) {
+        throw std::domain_error("cannot fork machines with shared address ranges");
+    }
     // Listen in desired port before fork so failures happen still in parent,
     // who can directly report them to client
     tcp::acceptor acceptor{session->handler->ioc, tcp::endpoint{session->handler->local_endpoint.address(), 0}};
@@ -846,8 +849,9 @@ static json jsonrpc_machine_load_handler(const json &j, const std::shared_ptr<ht
     if (session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "machine exists");
     }
-    static const char *param_name[] = {"directory", "runtime_config"};
-    auto args = parse_args<std::string, cartesi::optional_param<cartesi::machine_runtime_config>>(j, param_name);
+    static const char *param_name[] = {"directory", "runtime_config", "sharing"};
+    auto args = parse_args<std::string, cartesi::optional_param<cartesi::machine_runtime_config>,
+        cartesi::optional_param<cartesi::sharing_mode>>(j, param_name);
     switch (count_args(args)) {
         case 1:
             session->handler->machine = std::make_unique<cartesi::machine>(std::get<0>(args));
@@ -856,6 +860,11 @@ static json jsonrpc_machine_load_handler(const json &j, const std::shared_ptr<ht
             session->handler->machine = std::make_unique<cartesi::machine>(std::get<0>(args),
                 std::get<1>(args).value()); // NOLINT(bugprone-unchecked-optional-access)
             break;
+        case 3:
+            session->handler->machine = std::make_unique<cartesi::machine>(std::get<0>(args),
+                std::get<1>(args).value(),  // NOLINT(bugprone-unchecked-optional-access)
+                std::get<2>(args).value()); // NOLINT(bugprone-unchecked-optional-access)
+            break;
         default:
             throw std::runtime_error{"error detecting number of arguments"};
     }
@@ -870,9 +879,9 @@ static json jsonrpc_machine_create_handler(const json &j, const std::shared_ptr<
     if (session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "machine exists");
     }
-    static const char *param_name[] = {"config", "runtime_config"};
-    auto args =
-        parse_args<cartesi::machine_config, cartesi::optional_param<cartesi::machine_runtime_config>>(j, param_name);
+    static const char *param_name[] = {"config", "runtime_config", "directory"};
+    auto args = parse_args<cartesi::machine_config, cartesi::optional_param<cartesi::machine_runtime_config>,
+        cartesi::optional_param<std::string>>(j, param_name);
     switch (count_args(args)) {
         case 1:
             session->handler->machine = std::make_unique<cartesi::machine>(std::get<0>(args));
@@ -881,6 +890,11 @@ static json jsonrpc_machine_create_handler(const json &j, const std::shared_ptr<
             session->handler->machine = std::make_unique<cartesi::machine>(std::get<0>(args),
                 std::get<1>(args).value()); // // NOLINT(bugprone-unchecked-optional-access)
             break;
+        case 3:
+            session->handler->machine = std::make_unique<cartesi::machine>(std::get<0>(args),
+                std::get<1>(args).value(),  // NOLINT(bugprone-unchecked-optional-access)
+                std::get<2>(args).value()); // NOLINT(bugprone-unchecked-optional-access)
+            break;
         default:
             throw std::runtime_error{"error detecting number of arguments"};
     }
@@ -971,9 +985,23 @@ static json jsonrpc_machine_store_handler(const json &j, const std::shared_ptr<h
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"directory"};
-    auto args = parse_args<std::string>(j, param_name);
-    session->handler->machine->store(std::get<0>(args));
+    static const char *param_name[] = {"directory", "sharing"};
+    auto args = parse_args<std::string, cartesi::sharing_mode>(j, param_name);
+    session->handler->machine->store(std::get<0>(args), std::get<1>(args));
+    return jsonrpc_response_ok(j);
+}
+
+/// \brief JSONRPC handler for the machine.clone_stored method
+/// \param j JSON request object
+/// \param session HTTP session
+/// \returns JSON response object
+static json jsonrpc_machine_clone_stored_handler(const json &j, const std::shared_ptr<http_session> &session) {
+    if (!session->handler->machine) {
+        return jsonrpc_response_invalid_request(j, "no machine");
+    }
+    static const char *param_name[] = {"from_dir", "to_dir"};
+    auto args = parse_args<std::string, std::string>(j, param_name);
+    cartesi::machine::clone_stored(std::get<0>(args), std::get<1>(args));
     return jsonrpc_response_ok(j);
 }
 
@@ -1510,6 +1538,7 @@ static json jsonrpc_dispatch_method(const json &j, const std::shared_ptr<http_se
         {"machine.load", jsonrpc_machine_load_handler},
         {"machine.destroy", jsonrpc_machine_destroy_handler},
         {"machine.store", jsonrpc_machine_store_handler},
+        {"machine.clone_stored", jsonrpc_machine_clone_stored_handler},
         {"machine.run", jsonrpc_machine_run_handler},
         {"machine.log_step", jsonrpc_machine_log_step_handler},
         {"machine.run_uarch", jsonrpc_machine_run_uarch_handler},
diff --git a/src/local-machine.cpp b/src/local-machine.cpp
index 074f85bab..1c589c5d3 100644
--- a/src/local-machine.cpp
+++ b/src/local-machine.cpp
@@ -38,12 +38,13 @@ bool local_machine::do_is_empty() const {
     return m_machine == nullptr;
 }
 
-void local_machine::do_create(const machine_config &config, const machine_runtime_config &runtime) {
-    m_machine = new machine(config, runtime);
+void local_machine::do_create(const machine_config &config, const machine_runtime_config &runtime,
+    const std::string &dir) {
+    m_machine = new machine(config, runtime, dir);
 }
 
-void local_machine::do_load(const std::string &directory, const machine_runtime_config &runtime) {
-    m_machine = new machine(directory, runtime);
+void local_machine::do_load(const std::string &directory, const machine_runtime_config &runtime, sharing_mode sharing) {
+    m_machine = new machine(directory, runtime, sharing);
 }
 
 local_machine::~local_machine() {
@@ -65,8 +66,12 @@ const machine *local_machine::get_machine() const {
     return m_machine;
 }
 
-void local_machine::do_store(const std::string &directory) const {
-    get_machine()->store(directory);
+void local_machine::do_store(const std::string &directory, sharing_mode sharing) const {
+    get_machine()->store(directory, sharing);
+}
+
+void local_machine::do_clone_stored(const std::string &from_dir, const std::string &to_dir) const {
+    machine::clone_stored(from_dir, to_dir);
 }
 
 interpreter_break_reason local_machine::do_run(uint64_t mcycle_end) {
diff --git a/src/local-machine.h b/src/local-machine.h
index 619e2007f..47ead6360 100644
--- a/src/local-machine.h
+++ b/src/local-machine.h
@@ -46,13 +46,15 @@ class local_machine : public i_machine {
 private:
     i_machine *do_clone_empty() const override;
     bool do_is_empty() const override;
-    void do_create(const machine_config &config, const machine_runtime_config &runtime) override;
-    void do_load(const std::string &directory, const machine_runtime_config &runtime) override;
+    void do_create(const machine_config &config, const machine_runtime_config &runtime,
+        const std::string &dir) override;
+    void do_load(const std::string &directory, const machine_runtime_config &runtime, sharing_mode sharing) override;
     interpreter_break_reason do_run(uint64_t mcycle_end) override;
     void do_collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_period, uint64_t period_count,
         mcycle_root_hashes &result) override;
     interpreter_break_reason do_log_step(uint64_t mcycle_count, const std::string &filename) override;
-    void do_store(const std::string &directory) const override;
+    void do_store(const std::string &directory, sharing_mode sharing) const override;
+    void do_clone_stored(const std::string &from_dir, const std::string &to_dir) const override;
     access_log do_log_step_uarch(const access_log::type &log_type) override;
     hash_tree_proof do_get_proof(uint64_t address, int log2_size) const override;
     machine_hash do_get_root_hash() const override;
diff --git a/src/machine-address-ranges.cpp b/src/machine-address-ranges.cpp
index c09be93d2..019e00520 100644
--- a/src/machine-address-ranges.cpp
+++ b/src/machine-address-ranges.cpp
@@ -38,11 +38,14 @@
 #include "htif-address-range.h"
 #include "machine-config.h"
 #include "memory-address-range.h"
+#include "os-filesystem.h"
 #include "os.h"
 #include "plic-address-range.h"
 #include "pmas-constants.h"
 #include "pmas.h"
 #include "processor-state.h"
+#include "scope-exit.h"
+#include "scope-remove.h"
 #include "uarch-pristine.h"
 #include "uarch-processor-state.h"
 #include "unique-c-ptr.h"
@@ -59,7 +62,7 @@ using namespace std::string_literals;
 static const auto throw_invalid_argument = [](const char *err) { throw std::invalid_argument{err}; };
 
 static inline auto make_pmas_address_range(const pmas_config &config) {
-    static constexpr pmas_flags pmas_flags{
+    static constexpr pmas_flags flags{
         .M = true,
         .IO = false,
         .R = true,
@@ -69,7 +72,8 @@ static inline auto make_pmas_address_range(const pmas_config &config) {
         .IW = false,
         .DID = PMA_ISTART_DID::memory,
     };
-    return make_memory_address_range("PMAs", AR_PMAS_START, AR_PMAS_LENGTH, pmas_flags, config.backing_store);
+    return memory_address_range{"PMAs"s, AR_PMAS_START, AR_PMAS_LENGTH, flags, config.backing_store,
+        memory_address_range_config{.host_read_only = true}};
 }
 
 static inline auto make_dtb_address_range(const dtb_config &config) {
@@ -85,7 +89,7 @@ static inline auto make_dtb_address_range(const dtb_config &config) {
         .IW = true,
         .DID = PMA_ISTART_DID::memory,
     };
-    return make_memory_address_range("DTB"s, AR_DTB_START, AR_DTB_LENGTH, dtb_flags, config.backing_store);
+    return memory_address_range{"DTB"s, AR_DTB_START, AR_DTB_LENGTH, dtb_flags, config.backing_store};
 }
 
 static inline auto make_shadow_state_address_range(const processor_config &config) {
@@ -117,8 +121,8 @@ static inline auto make_shadow_uarch_state_address_range(const uarch_processor_c
     };
     static constexpr memory_address_range_config shadow_uarch_state_config{
         .host_length = sizeof(uarch_processor_state)};
-    return make_memory_address_range("shadow uarch state", AR_SHADOW_UARCH_STATE_START, AR_SHADOW_UARCH_STATE_LENGTH,
-        shadow_uarch_state_flags, config.backing_store, shadow_uarch_state_config);
+    return memory_address_range{"shadow uarch state", AR_SHADOW_UARCH_STATE_START, AR_SHADOW_UARCH_STATE_LENGTH,
+        shadow_uarch_state_flags, config.backing_store, shadow_uarch_state_config};
 }
 
 void machine_address_ranges::mark_always_dirty_pages() {
@@ -148,7 +152,92 @@ AR &machine_address_ranges::push_back(AR &&ar, register_where where) {
     return ar_ref; // Return reference to object in heap
 }
 
-machine_address_ranges::machine_address_ranges(machine_config &c) {
+static void prepare_backing_store(const backing_store_config &backing_store, uint64_t length, scope_remove &remover) {
+    if (!backing_store.data_filename.empty() && backing_store.shared) {
+        if (backing_store.create) { // Create new file
+            os::truncate_file(backing_store.data_filename, length, true);
+            remover.add_file(backing_store.data_filename);
+        } else if (backing_store.truncate) { // Truncate existing file
+            os::truncate_file(backing_store.data_filename, length, false);
+        }
+    }
+}
+
+static void prepare_backing_store_for_share(const backing_store_config &from, backing_store_config &to, uint64_t length,
+    bool read_only, scope_remove &remover) {
+    to.shared = true;
+    if (from.newly_created()) { // Nothing to copy
+        os::truncate_file(to.data_filename, length, true);
+        remover.add_file(to.data_filename);
+        // Necessary, so the memory is always mapped as writeable in memory address range constructor
+        to.create = true;
+    } else {
+        os::copy_file(from.data_filename, to.data_filename, length);
+        remover.add_file(to.data_filename);
+    }
+    os::change_writable(to.data_filename, !read_only);
+}
+
+static void prepare_backing_stores(const machine_config &c, scope_remove &remover) {
+    prepare_backing_store(c.processor.backing_store, AR_SHADOW_STATE_LENGTH, remover);
+    prepare_backing_store(c.pmas.backing_store, AR_PMAS_LENGTH, remover);
+    prepare_backing_store(c.dtb.backing_store, AR_DTB_LENGTH, remover);
+    prepare_backing_store(c.ram.backing_store, c.ram.length, remover);
+    prepare_backing_store(c.cmio.rx_buffer.backing_store, AR_CMIO_RX_BUFFER_LENGTH, remover);
+    prepare_backing_store(c.cmio.tx_buffer.backing_store, AR_CMIO_TX_BUFFER_LENGTH, remover);
+    prepare_backing_store(c.uarch.processor.backing_store, AR_SHADOW_UARCH_STATE_LENGTH, remover);
+    prepare_backing_store(c.uarch.ram.backing_store, AR_UARCH_RAM_LENGTH, remover);
+    for (const auto &f : c.flash_drive) {
+        prepare_backing_store(f.backing_store, f.length, remover);
+    }
+}
+
+static void create_backing_stores_for_share(const machine_config &from_c, machine_config &to_c, scope_remove &remover) {
+    prepare_backing_store_for_share(from_c.processor.backing_store, to_c.processor.backing_store,
+        AR_SHADOW_STATE_LENGTH, false, remover);
+    prepare_backing_store_for_share(from_c.pmas.backing_store, to_c.pmas.backing_store, AR_PMAS_LENGTH, false, remover);
+    prepare_backing_store_for_share(from_c.dtb.backing_store, to_c.dtb.backing_store, AR_DTB_LENGTH, false, remover);
+    prepare_backing_store_for_share(from_c.ram.backing_store, to_c.ram.backing_store, to_c.ram.length, false, remover);
+    prepare_backing_store_for_share(from_c.cmio.rx_buffer.backing_store, to_c.cmio.rx_buffer.backing_store,
+        AR_CMIO_RX_BUFFER_LENGTH, false, remover);
+    prepare_backing_store_for_share(from_c.cmio.tx_buffer.backing_store, to_c.cmio.tx_buffer.backing_store,
+        AR_CMIO_TX_BUFFER_LENGTH, false, remover);
+    prepare_backing_store_for_share(from_c.uarch.processor.backing_store, to_c.uarch.processor.backing_store,
+        AR_SHADOW_UARCH_STATE_LENGTH, false, remover);
+    prepare_backing_store_for_share(from_c.uarch.ram.backing_store, to_c.uarch.ram.backing_store, AR_UARCH_RAM_LENGTH,
+        false, remover);
+    for (size_t i = 0; i < to_c.flash_drive.size(); ++i) {
+        const auto &from_f = from_c.flash_drive[i];
+        auto &to_f = to_c.flash_drive[i];
+        prepare_backing_store_for_share(from_f.backing_store, to_f.backing_store, from_f.length, from_f.read_only,
+            remover);
+    }
+}
+
+machine_address_ranges::machine_address_ranges(const machine_config &config,
+    const machine_runtime_config &runtime_config, const std::string &dir, scope_remove &remover) {
+    // Copy config
+    machine_config c = config;
+
+    // Prepare backing stores
+    if (!dir.empty()) { // Machine that it's fully on-disk
+        if (config.processor.registers.iunrep != 0) {
+            throw std::invalid_argument{"fully on-disk machines must not be unreproducible"s};
+        }
+        // Adjust config
+        c.adjust_backing_stores(dir);
+        // Create backing store directory
+        os::create_directory(dir);
+        remover.add_directory(dir);
+        // Store config
+        remover.add_file(c.store(dir));
+        // Copy backing stores and mark them as shared
+        create_backing_stores_for_share(config, c, remover);
+    } else { // A machine that may be partially or fully in-memory
+        // Create and truncate backing stores as necessary
+        prepare_backing_stores(c, remover);
+    }
+
     // Add all address ranges to m_all, and potentially to interpret and merkle
     m_shadow_state_index = static_cast<int>(m_all.size()); // NOLINT(cppcoreguidelines-prefer-member-initializer)
     push_back(make_shadow_state_address_range(c.processor), register_where{.hash_tree = true, .pmas = false});
@@ -158,7 +247,7 @@ machine_address_ranges::machine_address_ranges(machine_config &c) {
     push_back_uarch_ram(c.uarch.ram);
     push_back_ram(c.ram);
     push_back(make_dtb_address_range(c.dtb), register_where{.hash_tree = true, .pmas = true});
-    push_back_flash_drives(c.flash_drive);
+    push_back_flash_drives(c.flash_drive, runtime_config);
     push_back_cmio(c.cmio);
     push_back(make_htif_address_range(throw_invalid_argument), register_where{.hash_tree = false, .pmas = true});
     push_back(make_clint_address_range(throw_invalid_argument), register_where{.hash_tree = false, .pmas = true});
@@ -195,11 +284,11 @@ void machine_address_ranges::push_back_uarch_ram(const uarch_ram_config &uram) {
         .DID = PMA_ISTART_DID::memory,
     };
     constexpr auto ram_description = "uarch RAM";
-    auto &ar = push_back(make_memory_address_range(ram_description, AR_UARCH_RAM_START, AR_UARCH_RAM_LENGTH, uram_flags,
-                             uram.backing_store),
+    auto &ar = push_back(
+        memory_address_range{ram_description, AR_UARCH_RAM_START, AR_UARCH_RAM_LENGTH, uram_flags, uram.backing_store},
         register_where{.hash_tree = true, .pmas = false});
     // Initialize uarch RAM
-    if (uram.backing_store.data_filename.empty() || uram.backing_store.create) {
+    if (uram.backing_store.newly_created()) {
         if (uarch_pristine_ram_len > AR_UARCH_RAM_LENGTH) {
             throw std::runtime_error("embedded uarch RAM image does not fit in uarch memory");
         }
@@ -242,45 +331,19 @@ void machine_address_ranges::push_back_ram(const ram_config &ram) {
     if (ram.length == 0) {
         throw std::invalid_argument("RAM length cannot be zero");
     }
-    push_back(make_memory_address_range("RAM"s, AR_RAM_START, ram.length, ram_flags, ram.backing_store),
+    push_back(memory_address_range{"RAM"s, AR_RAM_START, ram.length, ram_flags, ram.backing_store},
         register_where{.hash_tree = true, .pmas = true});
 }
 
-void machine_address_ranges::push_back_flash_drives(flash_drive_configs &flash_drive) {
+void machine_address_ranges::push_back_flash_drives(const flash_drive_configs &flash_drive,
+    const machine_runtime_config &r) {
     if (flash_drive.size() > FLASH_DRIVE_MAX) {
         throw std::invalid_argument{"too many flash drives"};
     }
     // Register all flash drives
     int i = 0; // NOLINT(misc-const-correctness)
-    for (auto &f : flash_drive) {
+    for (const auto &f : flash_drive) {
         const std::string flash_description = "flash drive "s + std::to_string(i);
-        // Auto detect flash drive start address
-        if (f.start == UINT64_C(-1)) {
-            f.start = AR_DRIVE_START + AR_DRIVE_OFFSET * i;
-        }
-        // Auto detect flash drive image length
-        const auto &image_filename = f.backing_store.data_filename;
-        if (f.length == UINT64_C(-1)) {
-            if (image_filename.empty()) {
-                throw std::runtime_error{
-                    "unable to auto-detect length of "s.append(flash_description).append(" with empty image file")};
-            }
-            auto fp = make_unique_fopen(image_filename.c_str(), "rb");
-            if (fseek(fp.get(), 0, SEEK_END) != 0) {
-                throw std::system_error{errno, std::generic_category(),
-                    "unable to obtain length of image file '"s.append(image_filename)
-                        .append("' when initializing ")
-                        .append(flash_description)};
-            }
-            const auto length = ftell(fp.get());
-            if (length < 0) {
-                throw std::system_error{errno, std::generic_category(),
-                    "unable to obtain length of image file '"s.append(image_filename)
-                        .append("' when initializing ")
-                        .append(flash_description)};
-            }
-            f.length = length;
-        }
         // Flags for the flash drive
         const pmas_flags flash_flags{
             .M = true,
@@ -293,7 +356,7 @@ void machine_address_ranges::push_back_flash_drives(flash_drive_configs &flash_d
             .DID = PMA_ISTART_DID::flash_drive,
         };
         push_back(memory_address_range{flash_description, f.start, f.length, flash_flags, f.backing_store,
-                      memory_address_range_config{.host_read_only = f.read_only}},
+                      memory_address_range_config{.host_read_only = f.read_only, .host_no_reserve = r.no_reserve}},
             register_where{.hash_tree = true, .pmas = true});
         i++;
     }
@@ -385,11 +448,11 @@ void machine_address_ranges::push_back_cmio(const cmio_config &c) {
         .IW = true,
         .DID = PMA_ISTART_DID::cmio_rx_buffer,
     };
-    push_back(make_memory_address_range("CMIO tx buffer"s, AR_CMIO_TX_BUFFER_START, AR_CMIO_TX_BUFFER_LENGTH, tx_flags,
-                  c.tx_buffer.backing_store),
+    push_back(memory_address_range{"CMIO tx buffer"s, AR_CMIO_TX_BUFFER_START, AR_CMIO_TX_BUFFER_LENGTH, tx_flags,
+                  c.tx_buffer.backing_store},
         register_where{.hash_tree = true, .pmas = true});
-    push_back(make_memory_address_range("CMIO rx buffer"s, AR_CMIO_RX_BUFFER_START, AR_CMIO_RX_BUFFER_LENGTH, rx_flags,
-                  c.rx_buffer.backing_store),
+    push_back(memory_address_range{"CMIO rx buffer"s, AR_CMIO_RX_BUFFER_START, AR_CMIO_RX_BUFFER_LENGTH, rx_flags,
+                  c.rx_buffer.backing_store},
         register_where{.hash_tree = true, .pmas = true});
 }
 
@@ -411,8 +474,8 @@ void machine_address_ranges::replace(const memory_range_config &config) {
             }
             // Replace range, preserving original flags.
             // This will automatically start with all pages dirty.
-            ar = make_moved_unique(make_memory_address_range(ar->get_description(), ar->get_start(), ar->get_length(),
-                ar->get_flags(), config.backing_store));
+            ar = make_moved_unique(memory_address_range{ar->get_description(), ar->get_start(), ar->get_length(),
+                ar->get_flags(), config.backing_store});
             return;
         }
     }
diff --git a/src/machine-address-ranges.h b/src/machine-address-ranges.h
index 9dbd10a03..bb57b0528 100644
--- a/src/machine-address-ranges.h
+++ b/src/machine-address-ranges.h
@@ -31,6 +31,7 @@
 #include "machine-config.h"
 #include "machine-runtime-config.h"
 #include "meta.h"
+#include "scope-remove.h"
 #include "virtio-address-range.h"
 
 namespace cartesi {
@@ -49,8 +50,12 @@ class machine_address_ranges {
 
 public:
     /// \brief Constructor
-    /// \param c Machine configuration
-    explicit machine_address_ranges(machine_config &c);
+    /// \param config Machine configuration
+    /// \param runtime_config Runtime configuration
+    /// \param dir Directory for backing store files (can be empty)
+    /// \param remover Scope remove object to remove created files on failure
+    explicit machine_address_ranges(const machine_config &config, const machine_runtime_config &runtime_config,
+        const std::string &dir, scope_remove &remover);
 
     /// \brief Const view of all address ranges
     auto all() const {
@@ -190,8 +195,9 @@ class machine_address_ranges {
 
     /// \brief Adds flash drive address ranges
     /// \param flash_drive Flash drive configurations
+    /// \param runtime_config Runtime configuration
     /// \detail This modifies the flash drive configuration with automatic start/length from backing storage, if needed
-    void push_back_flash_drives(flash_drive_configs &flash_drive);
+    void push_back_flash_drives(const flash_drive_configs &flash_drive, const machine_runtime_config &runtime_config);
 
     /// \brief Adds virtio address ranges
     /// \param virtio VirtIO configurations
diff --git a/src/machine-c-api.cpp b/src/machine-c-api.cpp
index c7157974e..dea557875 100644
--- a/src/machine-c-api.cpp
+++ b/src/machine-c-api.cpp
@@ -455,6 +455,18 @@ static cartesi::machine_reg convert_from_c(cm_reg r) {
     throw std::domain_error{"unknown register"};
 }
 
+static cartesi::sharing_mode convert_from_c(cm_sharing_mode sharing) {
+    switch (sharing) {
+        case CM_SHARING_NONE:
+            return cartesi::sharing_mode::none;
+        case CM_SHARING_CONFIG:
+            return cartesi::sharing_mode::config;
+        case CM_SHARING_ALL:
+            return cartesi::sharing_mode::all;
+    }
+    throw std::domain_error{"unknown sharing mode"};
+}
+
 static cartesi::i_machine *convert_from_c(cm_machine *m) {
     if (m == nullptr) {
         throw std::invalid_argument("invalid machine");
@@ -537,7 +549,7 @@ cm_error cm_is_empty(const cm_machine *m, bool *yes) try {
     return cm_result_failure();
 }
 
-cm_error cm_create(cm_machine *m, const char *config, const char *runtime_config) try {
+cm_error cm_create(cm_machine *m, const char *config, const char *runtime_config, const char *dir) try {
     auto *cpp_m = convert_from_c(m);
     if (config == nullptr) {
         throw std::invalid_argument("invalid machine configuration");
@@ -547,13 +559,13 @@ cm_error cm_create(cm_machine *m, const char *config, const char *runtime_config
     if (runtime_config != nullptr) {
         r = cartesi::from_json<cartesi::machine_runtime_config>(runtime_config, "runtime_config");
     }
-    cpp_m->create(c, r);
+    cpp_m->create(c, r, dir != nullptr ? std::string(dir) : std::string());
     return cm_result_success();
 } catch (...) {
     return cm_result_failure();
 }
 
-cm_error cm_load(cm_machine *m, const char *dir, const char *runtime_config) try {
+cm_error cm_load(cm_machine *m, const char *dir, const char *runtime_config, cm_sharing_mode sharing) try {
     auto *cpp_m = convert_from_c(m);
     if (dir == nullptr) {
         throw std::invalid_argument("invalid dir");
@@ -562,18 +574,18 @@ cm_error cm_load(cm_machine *m, const char *dir, const char *runtime_config) try
     if (runtime_config != nullptr) {
         r = cartesi::from_json<cartesi::machine_runtime_config>(runtime_config, "runtime_config");
     }
-    cpp_m->load(dir, r);
+    cpp_m->load(dir, r, convert_from_c(sharing));
     return cm_result_success();
 } catch (...) {
     return cm_result_failure();
 }
 
-cm_error cm_load_new(const char *dir, const char *runtime_config, cm_machine **new_m) {
+cm_error cm_load_new(const char *dir, const char *runtime_config, cm_sharing_mode sharing, cm_machine **new_m) {
     auto err = cm_new(new_m);
     if (err != 0) {
         return err;
     }
-    err = cm_load(*new_m, dir, runtime_config);
+    err = cm_load(*new_m, dir, runtime_config, sharing);
     if (err != 0) {
         cm_delete(*new_m);
         *new_m = nullptr;
@@ -581,12 +593,12 @@ cm_error cm_load_new(const char *dir, const char *runtime_config, cm_machine **n
     return err;
 }
 
-cm_error cm_create_new(const char *config, const char *runtime_config, cm_machine **new_m) {
+cm_error cm_create_new(const char *config, const char *runtime_config, const char *dir, cm_machine **new_m) {
     auto err = cm_new(new_m);
     if (err != 0) {
         return err;
     }
-    err = cm_create(*new_m, config, runtime_config);
+    err = cm_create(*new_m, config, runtime_config, dir);
     if (err != 0) {
         cm_delete(*new_m);
         *new_m = nullptr;
@@ -594,12 +606,26 @@ cm_error cm_create_new(const char *config, const char *runtime_config, cm_machin
     return err;
 }
 
-cm_error cm_store(const cm_machine *m, const char *dir) try {
+cm_error cm_store(const cm_machine *m, const char *dir, cm_sharing_mode sharing) try {
     if (dir == nullptr) {
         throw std::invalid_argument("invalid dir");
     }
     const auto *cpp_m = convert_from_c(m);
-    cpp_m->store(dir);
+    cpp_m->store(dir, convert_from_c(sharing));
+    return cm_result_success();
+} catch (...) {
+    return cm_result_failure();
+}
+
+cm_error cm_clone_stored(const cm_machine *m, const char *from_dir, const char *to_dir) try {
+    if (from_dir == nullptr) {
+        throw std::invalid_argument("invalid from dir");
+    }
+    if (to_dir == nullptr) {
+        throw std::invalid_argument("invalid to dir");
+    }
+    const auto *cpp_m = convert_from_c(m);
+    cpp_m->clone_stored(from_dir, to_dir);
     return cm_result_success();
 } catch (...) {
     return cm_result_failure();
diff --git a/src/machine-c-api.h b/src/machine-c-api.h
index ac26501e5..ccaeabd9d 100644
--- a/src/machine-c-api.h
+++ b/src/machine-c-api.h
@@ -128,6 +128,13 @@ typedef enum cm_cmio_yield_reason {
     CM_CMIO_YIELD_REASON_INSPECT_STATE = 1,       ///< Input in rx buffer is an inspect state
 } cm_cmio_yield_reason;
 
+/// \brief Sharing modes.
+typedef enum cm_sharing_mode {
+    CM_SHARING_NONE = 0,   ///< No sharing, all machine changes will be in-memory
+    CM_SHARING_CONFIG = 1, ///< Share backing stores marked as shared in the machine configuration
+    CM_SHARING_ALL = 2,    ///< Share all backing stores, all machine changes will be on-disk
+} cm_sharing_mode;
+
 /// \brief Machine x, f, and control and status registers.
 typedef enum cm_reg {
     // Machine x registers
@@ -398,44 +405,66 @@ CM_API void cm_delete(cm_machine *m);
 /// }
 /// ```
 /// \param runtime_config Machine runtime configuration as a JSON object in a string (can be NULL).
+/// \param dir Directory to create an on-disk machine. If NULL or empty, the machine will be created in-memory.
 /// \returns 0 for success, non zero code for error.
 /// \details Use cm_destroy() to destroy the machine instance and remove it from the object.
-CM_API cm_error cm_create(cm_machine *m, const char *config, const char *runtime_config);
+CM_API cm_error cm_create(cm_machine *m, const char *config, const char *runtime_config, const char *dir);
 
 /// \brief Combines cm_new() and cm_create() for convenience.
 /// \param config Machine configuration as a JSON object in a string (at least RAM length must be set).
 /// \param runtime_config Machine runtime configuration as a JSON object in a string (can be NULL).
 /// \param new_m Receives the pointer to the new machine object with a machine instance. Set to NULL on failure.
+/// \param dir Directory to create an on-disk machine. If NULL or empty, the machine will be created in-memory.
 /// \returns 0 for success, non zero code for error.
 /// \details Use cm_destroy() to destroy the machine instance and remove it from the object.
 /// \details Use cm_delete() to delete the object.
 /// \details See cm_new() and cm_create() for more details.
-CM_API cm_error cm_create_new(const char *config, const char *runtime_config, cm_machine **new_m);
+CM_API cm_error cm_create_new(const char *config, const char *runtime_config, const char *dir, cm_machine **new_m);
 
 /// \brief Loads a new machine instance from a previously stored directory.
 /// \param m Pointer to an empty machine object (does not hold a machine instance).
 /// \param dir Directory where previous machine is stored.
+/// \param sharing Backing stores sharing mode.
+/// CM_SHARING_NONE: Machine state will be fully in-memory.
+/// CM_SHARING_CONFIG: Machine state will be on-disk for shared backing stores, but in-memory for everything else.
+/// CM_SHARING_ALL: Machine state will be fully on-disk.
+/// \param new_m Receives the pointer to the new machine object with a machine instance. Set to NULL on failure.
 /// \param runtime_config Machine runtime configuration as a JSON object in a string (can be NULL).
 /// \returns 0 for success, non zero code for error.
 /// \details Use cm_destroy() to destroy the machine instance and remove it from the object.
-CM_API cm_error cm_load(cm_machine *m, const char *dir, const char *runtime_config);
+CM_API cm_error cm_load(cm_machine *m, const char *dir, const char *runtime_config, cm_sharing_mode sharing);
 
 /// \brief Combines cm_new() and cm_load() for convenience.
 /// \param dir Directory where previous machine is stored.
 /// \param runtime_config Machine runtime configuration as a JSON object in a string (can be NULL).
-/// \param new_m Receives the pointer to the new machine object with a machine instance. Set to NULL on failure.
+/// \param sharing Backing stores sharing mode.
 /// \returns 0 for success, non zero code for error.
 /// \details Use cm_destroy() to destroy the machine instance and remove it from the object.
 /// \details Use cm_delete() to delete the object.
-/// \details See cm_new() and cm_load() for more details.
-CM_API cm_error cm_load_new(const char *dir, const char *runtime_config, cm_machine **new_m);
+/// \details See cm_load() and cm_create() for more details.
+CM_API cm_error cm_load_new(const char *dir, const char *runtime_config, cm_sharing_mode sharing, cm_machine **new_m);
 
 /// \brief Stores a machine instance to a directory, serializing its entire state.
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
 /// \param dir Directory where the machine will be stored.
+/// \param sharing Specifies how machine changes are reflected in the new store.
+/// CM_SHARING_NONE: Copies backing stores from the initial machine state (rarely useful).
+/// CM_SHARING_CONFIG: Store current machine state for shared backing stores; others are copied from the initial state.
+/// CM_SHARING_ALL: Store current machine state for all backing stores.
 /// \returns 0 for success, non zero code for error.
 /// \details The function refuses to store into an existing directory (it will not overwrite an existing machine).
-CM_API cm_error cm_store(const cm_machine *m, const char *dir);
+CM_API cm_error cm_store(const cm_machine *m, const char *dir, cm_sharing_mode sharing);
+
+/// \brief Clones a machine stored from source directory to destination directory.
+/// \param m Pointer to a machine object. Can be NULL (for local machines).
+/// \param from_dir Path to the source directory containing a valid machine to be cloned.
+/// \param to_dir Path to the destination directory where the cloned machine will be stored.
+/// \returns 0 for success, non zero code for error.
+/// \details Read-only files are copied using hard links on filesystems that support them.
+/// Writable files are copied using reflinks on copy-on-write filesystems.
+/// Sparsity of files is preserved.
+/// The source directory machine must not have a running instance.
+CM_API cm_error cm_clone_stored(const cm_machine *m, const char *from_dir, const char *to_dir);
 
 /// \brief Destroy a machine instance and remove it from the object.
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
diff --git a/src/machine-config.cpp b/src/machine-config.cpp
index 439382aef..01a51beee 100644
--- a/src/machine-config.cpp
+++ b/src/machine-config.cpp
@@ -19,7 +19,6 @@
 #include <cerrno>
 #include <cstdint>
 #include <exception>
-#include <fstream>
 #include <iomanip>
 #include <ios>
 #include <sstream>
@@ -31,6 +30,7 @@
 
 #include "address-range-constants.h"
 #include "json-util.h"
+#include "os-filesystem.h"
 
 static constexpr uint32_t archive_version = 6;
 
@@ -71,10 +71,25 @@ std::string machine_config::get_config_filename(const std::string &dir) {
 }
 
 void machine_config::adjust_backing_store_config(uint64_t start, uint64_t length, const std::string &dir,
-    backing_store_config &c) {
-    c.shared = false;
+    sharing_mode sharing, backing_store_config &c) {
+    // Convert sharing mode
+    switch (sharing) {
+        case sharing_mode::none:
+            c.shared = false;
+            break;
+        case sharing_mode::config:
+            // Preserve the shared setting as specified in the configuration
+            break;
+        case sharing_mode::all:
+            c.shared = true;
+            break;
+    }
+
+    // Strip create and truncate since backing store should be already created
     c.create = false;
     c.truncate = false;
+
+    // Adjust filenames
     c.data_filename = machine_config::get_data_filename(dir, start, length);
     c.dht_filename = machine_config::get_dht_filename(dir, start, length);
     c.dpt_filename = machine_config::get_dpt_filename(dir, start, length);
@@ -85,31 +100,34 @@ void machine_config::adjust_hash_tree_config(const std::string &dir, hash_tree_c
     c.phtc_filename = machine_config::get_phtc_filename(dir);
 }
 
-void machine_config::adjust_backing_stores(const std::string &dir) {
-    adjust_backing_store_config(AR_RAM_START, ram.length, dir, ram.backing_store);
-    adjust_backing_store_config(AR_DTB_START, AR_DTB_LENGTH, dir, dtb.backing_store);
+machine_config &machine_config::adjust_backing_stores(const std::string &dir, sharing_mode sharing) {
+    adjust_backing_store_config(AR_RAM_START, ram.length, dir, sharing, ram.backing_store);
+    adjust_backing_store_config(AR_DTB_START, AR_DTB_LENGTH, dir, sharing, dtb.backing_store);
     for (auto &f : flash_drive) {
-        adjust_backing_store_config(f.start, f.length, dir, f.backing_store);
+        adjust_backing_store_config(f.start, f.length, dir, sharing, f.backing_store);
     }
-    adjust_backing_store_config(AR_SHADOW_STATE_START, AR_SHADOW_STATE_LENGTH, dir, processor.backing_store);
-    adjust_backing_store_config(AR_CMIO_RX_BUFFER_START, AR_CMIO_RX_BUFFER_LENGTH, dir, cmio.rx_buffer.backing_store);
-    adjust_backing_store_config(AR_CMIO_TX_BUFFER_START, AR_CMIO_TX_BUFFER_LENGTH, dir, cmio.tx_buffer.backing_store);
-    adjust_backing_store_config(AR_PMAS_START, AR_PMAS_LENGTH, dir, pmas.backing_store);
-    adjust_backing_store_config(AR_SHADOW_UARCH_STATE_START, AR_SHADOW_UARCH_STATE_LENGTH, dir,
+    adjust_backing_store_config(AR_SHADOW_STATE_START, AR_SHADOW_STATE_LENGTH, dir, sharing, processor.backing_store);
+    adjust_backing_store_config(AR_CMIO_RX_BUFFER_START, AR_CMIO_RX_BUFFER_LENGTH, dir, sharing,
+        cmio.rx_buffer.backing_store);
+    adjust_backing_store_config(AR_CMIO_TX_BUFFER_START, AR_CMIO_TX_BUFFER_LENGTH, dir, sharing,
+        cmio.tx_buffer.backing_store);
+    adjust_backing_store_config(AR_PMAS_START, AR_PMAS_LENGTH, dir, sharing, pmas.backing_store);
+    adjust_backing_store_config(AR_SHADOW_UARCH_STATE_START, AR_SHADOW_UARCH_STATE_LENGTH, dir, sharing,
         uarch.processor.backing_store);
-    adjust_backing_store_config(AR_UARCH_RAM_START, AR_UARCH_RAM_LENGTH, dir, uarch.ram.backing_store);
+    adjust_backing_store_config(AR_UARCH_RAM_START, AR_UARCH_RAM_LENGTH, dir, sharing, uarch.ram.backing_store);
     adjust_hash_tree_config(dir, hash_tree);
+    return *this;
 }
 
-machine_config machine_config::load(const std::string &dir) {
+machine_config machine_config::load(const std::string &dir, sharing_mode sharing) {
+    if (dir.empty()) {
+        throw std::invalid_argument{"directory name cannot be empty"};
+    }
     machine_config c;
     auto name = machine_config::get_config_filename(dir);
-    std::ifstream ifs(name, std::ios::binary);
-    if (!ifs) {
-        throw std::system_error{errno, std::generic_category(), "unable to open '" + name + "' for reading"};
-    }
+    const auto [ptr, data] = os::read_file(name);
     try {
-        auto j = nlohmann::json::parse(ifs);
+        auto j = nlohmann::json::parse(data);
         if (!j.contains("archive_version")) {
             throw std::runtime_error("missing field \"archive_version\"");
         }
@@ -122,23 +140,57 @@ machine_config machine_config::load(const std::string &dir) {
                 std::to_string(jv.get<int>()) + ")");
         }
         ju_get_field(j, std::string("config"), c, "");
-        c.adjust_backing_stores(dir);
+        c.adjust_backing_stores(dir, sharing);
     } catch (const std::exception &e) {
         throw std::runtime_error{e.what()};
     }
     return c;
 }
 
-void machine_config::store(const std::string &dir) const {
+std::string machine_config::store(const std::string &dir, sharing_mode sharing) const {
+    if (dir.empty()) {
+        throw std::invalid_argument{"directory name cannot be empty"};
+    }
     auto name = get_config_filename(dir);
     nlohmann::json j;
     j["archive_version"] = archive_version;
-    j["config"] = *this;
-    std::ofstream ofs(name, std::ios::binary);
-    if (!ofs) {
-        throw std::system_error{errno, std::generic_category(), "unable to open '" + name + "' for writing"};
+    j["config"] = machine_config(*this).adjust_backing_stores(".", sharing); // Strip relative directories
+    const std::string data = j.dump();
+    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+    os::create_file(name, std::span<const uint8_t>(reinterpret_cast<const uint8_t *>(data.data()), data.size()));
+    return name;
+}
+
+machine_config &machine_config::adjust_defaults() {
+    // Fill version registers
+    if (processor.registers.marchid == UINT64_C(-1)) {
+        processor.registers.marchid = MARCHID_INIT;
+    }
+    if (processor.registers.mvendorid == UINT64_C(-1)) {
+        processor.registers.mvendorid = MVENDORID_INIT;
+    }
+    if (processor.registers.mimpid == UINT64_C(-1)) {
+        processor.registers.mimpid = MIMPID_INIT;
+    }
+    // Auto detect flash drives start address and length
+    int i = 0; // NOLINT(misc-const-correctness)
+    for (auto &f : flash_drive) {
+        const std::string flash_description = "flash drive "s + std::to_string(i);
+        // Auto detect flash drive start address
+        if (f.start == UINT64_C(-1)) {
+            f.start = AR_DRIVE_START + AR_DRIVE_OFFSET * i;
+        }
+        // Auto detect flash drive image length
+        if (f.length == UINT64_C(-1)) {
+            if (f.backing_store.data_filename.empty()) {
+                throw std::runtime_error{
+                    "unable to auto-detect length of "s.append(flash_description).append(" with empty image file")};
+            }
+            f.length = os::file_size(f.backing_store.data_filename);
+        }
+        i += 1;
     }
-    ofs << j;
+    return *this;
 }
 
 } // namespace cartesi
diff --git a/src/machine-config.h b/src/machine-config.h
index fe10c7ec6..a0d37bc7b 100644
--- a/src/machine-config.h
+++ b/src/machine-config.h
@@ -30,6 +30,13 @@
 
 namespace cartesi {
 
+/// \brief Sharing modes
+enum class sharing_mode {
+    none,   ///< No sharing, all machine changes will be in-memory
+    config, ///< Share backing stores marked as shared in the machine configuration
+    all,    ///< Share all backing stores, all machine changes will be on-disk
+};
+
 /// \brief Machine config constants
 enum machine_config_constants {
     FLASH_DRIVE_MAX = 8,     ///< Maximum number of flash drives
@@ -45,6 +52,12 @@ struct backing_store_config final {
     std::string data_filename; ///< Backing store for associated memory address range
     std::string dht_filename;  ///< Backing store for corresponding dense hash-tree
     std::string dpt_filename;  ///< Backing store for corresponding dirty-page tree
+
+    /// \brief Returns true if the backing store was just created.
+    /// Indicates the backing store is zero-initialized and may require further initialization.
+    bool newly_created() const {
+        return create || data_filename.empty();
+    }
 };
 
 /// \brief Processor state config
@@ -60,8 +73,8 @@ struct backing_store_config_only final {
 
 /// \brief RAM state config
 struct ram_config final {
-    uint64_t length{0};                                   ///< RAM length
-    backing_store_config backing_store{.truncate = true}; ///< Backing store
+    uint64_t length{0};                 ///< RAM length
+    backing_store_config backing_store; ///< Backing store
 };
 
 /// \brief DTB state config
@@ -146,8 +159,8 @@ struct uarch_processor_config final {
 
 /// \brief Uarch config
 struct uarch_config final {
-    uarch_processor_config processor{};                        ///< Uarch processor
-    uarch_ram_config ram{.backing_store = {.truncate = true}}; ///< Uarch RAM
+    uarch_processor_config processor{}; ///< Uarch processor
+    uarch_ram_config ram{};             ///< Uarch RAM
 };
 
 /// \brief Hash tree config
@@ -192,20 +205,27 @@ struct machine_config final {
     static std::string get_phtc_filename(const std::string &dir);
 
     static void adjust_backing_store_config(uint64_t start, uint64_t length, const std::string &dir,
-        backing_store_config &c);
+        sharing_mode sharing, backing_store_config &c);
 
     static void adjust_hash_tree_config(const std::string &dir, hash_tree_config &c);
 
-    void adjust_backing_stores(const std::string &dir);
+    /// \brief Adjusts the machine config filling in default values
+    machine_config &adjust_defaults();
+
+    /// \brief Adjust backing stores to point to the directory
+    machine_config &adjust_backing_stores(const std::string &dir, sharing_mode sharing = sharing_mode::config);
 
     /// \brief Loads a machine config from a directory
     /// \param dir Directory from whence "config" will be loaded
+    /// \param sharing Sharing mode conversion policy to use for backing stores
     /// \returns The config loaded
-    static machine_config load(const std::string &dir);
+    static machine_config load(const std::string &dir, sharing_mode sharing = sharing_mode::config);
 
     /// \brief Stores the machine config to a directory
     /// \param dir Directory where "config" will be stored
-    void store(const std::string &dir) const;
+    /// \param sharing Sharing mode conversion policy to use for backing stores
+    /// \returns The filename where the config was stored.
+    std::string store(const std::string &dir, sharing_mode sharing = sharing_mode::config) const;
 };
 
 } // namespace cartesi
diff --git a/src/machine-runtime-config.h b/src/machine-runtime-config.h
index f89170086..242a98d3b 100644
--- a/src/machine-runtime-config.h
+++ b/src/machine-runtime-config.h
@@ -42,6 +42,7 @@ struct machine_runtime_config {
     bool skip_root_hash_store{};
     bool skip_version_check{};
     bool soft_yield{};
+    bool no_reserve{}; ///< Do not reserve swap memory when mapping flash drives
 };
 
 /// \brief CONCURRENCY constants
diff --git a/src/machine.cpp b/src/machine.cpp
index cc22287c3..c39166053 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -55,7 +55,10 @@
 #include "machine-hash.h"
 #include "machine-reg.h"
 #include "machine-runtime-config.h"
+#include "os-filesystem.h"
+#include "os.h"
 #include "page-hash-tree-cache.h"
+#include "pmas-constants.h"
 #include "pmas.h"
 #include "processor-state.h"
 #include "record-send-cmio-state-access.h"
@@ -65,6 +68,7 @@
 #include "riscv-constants.h"
 #include "rtc.h"
 #include "scope-exit.h"
+#include "scope-remove.h"
 #include "send-cmio-response.h"
 #include "shadow-tlb.h"
 #include "shadow-uarch-state.h"
@@ -100,7 +104,7 @@ hash_tree_stats machine::get_hash_tree_stats(bool clear) noexcept {
 }
 
 void machine::init_uarch_processor(const uarch_processor_config &p) {
-    if (p.backing_store.data_filename.empty() || p.backing_store.create) {
+    if (p.backing_store.newly_created()) {
         // Initialize to default values first
         *m_us = uarch_processor_state{};
 
@@ -120,24 +124,11 @@ void machine::init_uarch_processor(const uarch_processor_config &p) {
     }
 }
 
-void machine::init_processor(processor_config &p, const machine_runtime_config &r) {
-    if (p.backing_store.data_filename.empty() || p.backing_store.create) {
+void machine::init_processor(const processor_config &p, const machine_runtime_config &r) {
+    if (p.backing_store.newly_created()) {
         // Initialize to default values first
         *m_s = processor_state{};
 
-        // Initialize registers
-        if (p.registers.marchid == UINT64_C(-1)) {
-            p.registers.marchid = MARCHID_INIT;
-        }
-
-        if (p.registers.mvendorid == UINT64_C(-1)) {
-            p.registers.mvendorid = MVENDORID_INIT;
-        }
-
-        if (p.registers.mimpid == UINT64_C(-1)) {
-            p.registers.mimpid = MIMPID_INIT;
-        }
-
         // General purpose registers
         for (int i = 1; i < X_REG_COUNT; i++) {
             write_reg(machine_reg_enum(reg::x0, i), p.registers.x[i]);
@@ -238,7 +229,7 @@ void machine::init_pmas_contents(const pmas_config &config) {
     std::ranges::transform(m_ars.pmas_view(), pmas_state.begin(),
         [](const auto &ar) { return pmas_entry{.istart = ar.get_istart(), .ilength = ar.get_ilength()}; });
 
-    if (config.backing_store.data_filename.empty() || config.backing_store.create) {
+    if (config.backing_store.newly_created()) {
         memcpy(pmas.get_host_memory(), pmas_state.data(), sizeof(pmas_state));
     } else {
         // Validate PMAs state is consistent
@@ -288,7 +279,7 @@ void machine::init_hot_tlb_contents() {
 }
 
 void machine::init_dtb_contents(const machine_config &config) {
-    if (config.dtb.backing_store.data_filename.empty() || config.dtb.backing_store.create) {
+    if (config.dtb.backing_store.newly_created()) {
         auto &dtb = m_ars.find(AR_DTB_START, AR_DTB_LENGTH);
         if (!dtb.is_memory()) {
             throw std::runtime_error{"initialization error: DTB memory address range not found"};
@@ -298,10 +289,10 @@ void machine::init_dtb_contents(const machine_config &config) {
 }
 
 // ??D It is best to leave the std::move() on r because it may one day be necessary!
-machine::machine(machine_config c, machine_runtime_config r) :
-    m_c{std::move(c)}, // NOLINT(hicpp-move-const-arg,performance-move-const-arg)
-    m_r{std::move(r)}, // NOLINT(hicpp-move-const-arg,performance-move-const-arg)
-    m_ars{m_c},
+machine::machine(machine_config c, machine_runtime_config r, const std::string &dir, scope_remove remover) :
+    m_c{std::move(c).adjust_defaults()}, // NOLINT(hicpp-move-const-arg,performance-move-const-arg)
+    m_r{std::move(r)},                   // NOLINT(hicpp-move-const-arg,performance-move-const-arg)
+    m_ars{m_c, m_r, dir, remover},
     m_ht{m_c.hash_tree, m_r.concurrency.update_hash_tree, m_ars, m_c.hash_tree.hash_function},
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
     m_s{reinterpret_cast<processor_state *>(
@@ -319,6 +310,8 @@ machine::machine(machine_config c, machine_runtime_config r) :
     // when calling write() on closed file descriptors.
     // This can happen with the stdout console file descriptors or network file descriptors.
     os_disable_sigpipe();
+    // Construction succeeded, keep all created files and directories
+    remover.retain_all();
 }
 
 void machine::init_tty() {
@@ -332,26 +325,10 @@ void machine::init_tty() {
     }
 }
 
-static machine_hash load_hash(const std::string &dir) {
-    auto name = dir + "/hash";
-    auto fp = make_unique_fopen(name.c_str(), "rb");
-    machine_hash h;
-    if (fread(h.data(), 1, h.size(), fp.get()) != h.size()) {
-        throw std::runtime_error{"error reading from '" + name + "'"};
-    }
-    return h;
-}
-
 // ??D It is best to leave the std::move() on r because it may one day be necessary!
-// NOLINTNEXTLINE(hicpp-move-const-arg,performance-move-const-arg)
-machine::machine(const std::string &dir, machine_runtime_config r) : machine{machine_config::load(dir), std::move(r)} {
-    if (m_r.skip_root_hash_check) {
-        return;
-    }
-    if (load_hash(dir) != get_root_hash()) {
-        throw std::runtime_error{"stored and restored hashes do not match"};
-    }
-}
+machine::machine(const std::string &dir, machine_runtime_config r, sharing_mode sharing) :
+    // NOLINTNEXTLINE(hicpp-move-const-arg,performance-move-const-arg)
+    machine{machine_config::load(dir, sharing), std::move(r)} {}
 
 void machine::prepare_virtio_devices_select(select_fd_sets *fds, uint64_t *timeout_us) {
     for (auto &v : m_ars.virtio_view()) {
@@ -473,56 +450,108 @@ host_addr machine::get_hp_offset(uint64_t pma_index) const {
     return paddr - haddr;
 }
 
-static void store_hash(const machine_hash &h, const std::string &dir) {
-    auto name = dir + "/hash";
-    auto fp = make_unique_fopen(name.c_str(), "wb");
-    if (fwrite(h.data(), 1, h.size(), fp.get()) != h.size()) {
-        throw std::runtime_error{"error writing to '" + name + "'"};
-    }
-}
-
-void machine::store_address_ranges(const machine_config &c, const std::string &dir) const {
-    store_address_range(m_ars.find<uint64_t>(AR_DTB_START), dir);
-    store_address_range(m_ars.find<uint64_t>(AR_RAM_START), dir);
-    store_address_range(m_ars.find<uint64_t>(AR_SHADOW_STATE_START), dir);
-    for (const auto &f : c.flash_drive) {
-        store_address_range(m_ars.find<uint64_t>(f.start), dir);
-    }
-    store_address_range(m_ars.find<uint64_t>(AR_CMIO_RX_BUFFER_START), dir);
-    store_address_range(m_ars.find<uint64_t>(AR_CMIO_TX_BUFFER_START), dir);
-    store_address_range(m_ars.find<uint64_t>(AR_SHADOW_UARCH_STATE_START), dir);
-    store_address_range(m_ars.find<uint64_t>(AR_UARCH_RAM_START), dir);
-    store_address_range(m_ars.find<uint64_t>(AR_PMAS_START), dir);
-}
-
-void machine::store_address_range(const address_range &ar, const std::string &dir) {
+static void store_address_range(const backing_store_config &from_config, const address_range &ar, bool read_only,
+    const std::string &dir, sharing_mode sharing, scope_remove &remover) {
     if (ar.is_empty()) {
         throw std::runtime_error{"attempt to store empty address range "s.append(ar.get_description())};
     }
-    auto name = machine_config::get_data_filename(dir, ar.get_start(), ar.get_length());
-    auto fp = make_unique_fopen(name.c_str(), "wb"); // will throw if it fails
     if (!ar.is_memory() || ar.get_host_memory() == nullptr) {
         throw std::runtime_error{"attempt to store non-memory address range "s.append(ar.get_description())};
     }
-    if (fwrite(ar.get_host_memory(), 1, ar.get_length(), fp.get()) != ar.get_length()) {
-        throw std::runtime_error{"error writing to '" + name + "'"};
+    // Write the memory data to a file
+    const std::string &data_filename = machine_config::get_data_filename(dir, ar.get_start(), ar.get_length());
+    if (sharing == sharing_mode::all || (sharing == sharing_mode::config && from_config.shared)) {
+        os::create_file(data_filename, std::span{ar.get_host_memory(), static_cast<size_t>(ar.get_length())});
+    } else { // Copy unshared backing store
+        if (from_config.data_filename.empty()) {
+            throw std::runtime_error{"attempt to restore unbacked address range "s.append(ar.get_description())};
+        }
+        if (from_config.shared) {
+            throw std::runtime_error{"attempt to restore shared address range "s.append(ar.get_description())};
+        }
+        os::copy_file(from_config.data_filename, data_filename, ar.get_length());
+    }
+    remover.add_file(data_filename);
+    if (read_only) {
+        // Mark host read-only ranges as read-only
+        os::change_writable(data_filename, false);
     }
 }
 
-void machine::store(const std::string &dir) const {
+void machine::store(const std::string &dir, sharing_mode sharing) const {
+    if (dir.empty()) {
+        throw std::invalid_argument{"directory name cannot be empty"};
+    }
     if (read_reg(reg::iunrep) != 0) {
         throw std::runtime_error{"cannot store unreproducible machines"};
     }
-    if (os_mkdir(dir.c_str(), 0700) != 0) {
-        throw std::system_error{errno, std::generic_category(), "error creating directory '"s + dir + "'"s};
-    }
-    if (!m_r.skip_root_hash_store) {
-        store_hash(get_root_hash(), dir);
-    }
-    machine_config c = m_c;
-    c.adjust_backing_stores(".");
-    c.store(dir);
-    store_address_ranges(c, dir);
+    scope_remove remover;
+    // Create directory
+    os::create_directory(dir);
+    remover.add_directory(dir);
+    // Store config
+    remover.add_file(m_c.store(dir, sharing));
+    // Store all address ranges
+    store_address_range(m_c.processor.backing_store, m_ars.find<uint64_t>(AR_SHADOW_STATE_START), false, dir, sharing,
+        remover);
+    store_address_range(m_c.pmas.backing_store, m_ars.find<uint64_t>(AR_PMAS_START), true, dir, sharing, remover);
+    store_address_range(m_c.dtb.backing_store, m_ars.find<uint64_t>(AR_DTB_START), false, dir, sharing, remover);
+    store_address_range(m_c.ram.backing_store, m_ars.find<uint64_t>(AR_RAM_START), false, dir, sharing, remover);
+    store_address_range(m_c.cmio.rx_buffer.backing_store, m_ars.find<uint64_t>(AR_CMIO_RX_BUFFER_START), false, dir,
+        sharing, remover);
+    store_address_range(m_c.cmio.tx_buffer.backing_store, m_ars.find<uint64_t>(AR_CMIO_TX_BUFFER_START), false, dir,
+        sharing, remover);
+    store_address_range(m_c.uarch.processor.backing_store, m_ars.find<uint64_t>(AR_SHADOW_UARCH_STATE_START), false,
+        dir, sharing, remover);
+    store_address_range(m_c.uarch.ram.backing_store, m_ars.find<uint64_t>(AR_UARCH_RAM_START), false, dir, sharing,
+        remover);
+    for (const auto &f : m_c.flash_drive) {
+        store_address_range(f.backing_store, m_ars.find<uint64_t>(f.start), f.read_only, dir, sharing, remover);
+    }
+    // Retain all stored files
+    remover.retain_all();
+}
+
+static void clone_address_range(const backing_store_config &from, const backing_store_config &to,
+    scope_remove &remover) {
+    os::clone_file(from.data_filename, to.data_filename);
+    remover.add_file(to.data_filename);
+}
+
+void machine::clone_stored(const std::string &from_dir, const std::string &to_dir) {
+    if (from_dir.empty() || to_dir.empty()) {
+        throw std::invalid_argument{"directory name cannot be empty"};
+    }
+    const auto from_c = machine_config::load(from_dir);
+    const auto to_c = machine_config(from_c).adjust_backing_stores(to_dir);
+
+    scope_remove remover;
+
+    // Create directory
+    os::create_directory(to_dir);
+    remover.add_directory(to_dir);
+
+    // Clone config
+    const auto from_config_filename = machine_config::get_config_filename(from_dir);
+    const auto to_config_filename = machine_config::get_config_filename(to_dir);
+    os::clone_file(from_config_filename, to_config_filename);
+    remover.add_file(to_config_filename);
+
+    // Clone all address ranges
+    clone_address_range(from_c.processor.backing_store, to_c.processor.backing_store, remover);
+    clone_address_range(from_c.pmas.backing_store, to_c.pmas.backing_store, remover);
+    clone_address_range(from_c.dtb.backing_store, to_c.dtb.backing_store, remover);
+    clone_address_range(from_c.ram.backing_store, to_c.ram.backing_store, remover);
+    clone_address_range(from_c.cmio.rx_buffer.backing_store, to_c.cmio.rx_buffer.backing_store, remover);
+    clone_address_range(from_c.cmio.tx_buffer.backing_store, to_c.cmio.tx_buffer.backing_store, remover);
+    clone_address_range(from_c.uarch.processor.backing_store, to_c.uarch.processor.backing_store, remover);
+    clone_address_range(from_c.uarch.ram.backing_store, to_c.uarch.ram.backing_store, remover);
+    for (size_t i = 0; i < to_c.flash_drive.size(); ++i) {
+        clone_address_range(from_c.flash_drive[i].backing_store, to_c.flash_drive[i].backing_store, remover);
+    }
+
+    // Retain all stored files
+    remover.retain_all();
 }
 
 void machine::dump_insn_hist() {
@@ -1925,7 +1954,7 @@ interpreter_break_reason machine::log_step(uint64_t mcycle_count, const std::str
 
 interpreter_break_reason machine::verify_step(const machine_hash &root_hash_before, const std::string &filename,
     uint64_t mcycle_count, const machine_hash &root_hash_after) {
-    auto data_length = os_get_file_length(filename.c_str(), "step log file");
+    auto data_length = os::file_size(filename);
     auto data = make_unique_mmap<unsigned char>(data_length, os_mmap_flags{}, filename, data_length);
     replay_step_state_access::context context;
     replay_step_state_access a(context, data.get(), data_length, root_hash_before);
diff --git a/src/machine.h b/src/machine.h
index a065a3b48..c683c207c 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -43,6 +43,7 @@
 #include "os.h"
 #include "pmas-constants.h"
 #include "processor-state.h"
+#include "scope-remove.h"
 #include "shadow-tlb.h"
 #include "uarch-cycle-root-hashes.h"
 #include "uarch-interpret.h"
@@ -64,7 +65,7 @@ constexpr skip_hash_tree_update_t skip_hash_tree_update;
 /// \brief Cartesi Machine implementation
 class machine final {
 private:
-    machine_config m_c;                   ///< Copy of initialization config
+    const machine_config m_c;             ///< Copy of initialization config
     machine_runtime_config m_r;           ///< Copy of initialization runtime config
     mutable machine_address_ranges m_ars; ///< Address ranges
     mutable hash_tree m_ht;               ///< Top level hash tree
@@ -81,7 +82,7 @@ class machine final {
     /// \brief Initializes processor
     /// \param p Processor configuration
     /// \param r Machine runtime configuration
-    void init_processor(processor_config &p, const machine_runtime_config &r);
+    void init_processor(const processor_config &p, const machine_runtime_config &r);
 
     /// \brief Initializes microarchitecture processor
     /// \param c Microarchitecture processor configuration
@@ -115,16 +116,6 @@ class machine final {
     /// \details The counter is key is the concatenation of \p domain with \p name.
     static std::string get_counter_key(const char *name, const char *domain = nullptr);
 
-    /// \brief Stores address ranges into files for serialization
-    /// \param c Serialization machine config
-    /// \param dir Directory where address ranges will be stored
-    void store_address_ranges(const machine_config &c, const std::string &dir) const;
-
-    /// \brief Stores address range into files for serialization
-    /// \param ar Address range to store
-    /// \param dir Directory where address ranges will be stored
-    static void store_address_range(const address_range &ar, const std::string &dir);
-
     /// \brief Checks if the machine has VirtIO devices.
     /// \returns True if at least one VirtIO device is present.
     bool has_virtio_devices() const;
@@ -147,16 +138,24 @@ class machine final {
     /// \brief Constructor from machine configuration
     /// \param config Machine config to use instantiating machine
     /// \param runtime Runtime config to use with machine
-    explicit machine(machine_config config, machine_runtime_config runtime = {});
+    /// \param remover Object that may remove created files and directories if construction fails
+    explicit machine(machine_config config, machine_runtime_config runtime = {}, const std::string &dir = {},
+        scope_remove remover = {});
 
     /// \brief Constructor from previously serialized directory
     /// \param directory Directory to load stored machine from
     /// \param runtime Runtime config to use with machine
-    explicit machine(const std::string &directory, machine_runtime_config runtime = {});
+    explicit machine(const std::string &directory, machine_runtime_config runtime = {},
+        sharing_mode sharing = sharing_mode::none);
 
     /// \brief Serialize entire state to directory
     /// \param directory Directory to store machine into
-    void store(const std::string &directory) const;
+    void store(const std::string &directory, sharing_mode sharing = sharing_mode::all) const;
+
+    /// \brief Clones a machine stored from source directory to destination directory.
+    /// \param from_dir Path to the source directory where the machine is stored.
+    /// \param to_dir Path to the destination directory where the cloned machine will be stored.
+    static void clone_stored(const std::string &from_dir, const std::string &to_dir);
 
     /// \brief Returns address range that covers a given physical memory region
     /// \param paddr Target physical address of start of region.
@@ -588,6 +587,11 @@ class machine final {
     hash_function_type get_hash_function() const {
         return m_c.hash_tree.hash_function;
     }
+
+    /// \brief Returns whether the machine contains a shared address range
+    bool has_shared_address_range() const {
+        return std::ranges::any_of(m_ars.all(), [](const auto &ar) { return ar.is_backing_store_shared(); });
+    }
 };
 
 } // namespace cartesi
diff --git a/src/memory-address-range.cpp b/src/memory-address-range.cpp
index bd7c87d54..7c9458c8f 100644
--- a/src/memory-address-range.cpp
+++ b/src/memory-address-range.cpp
@@ -18,64 +18,55 @@
 
 #include <cerrno>
 #include <cstdio>
-#include <exception>
+#include <cstring>
 #include <stdexcept>
 #include <system_error>
 
 #include "address-range-constants.h"
+#include "os-filesystem.h"
+#include "unique-c-ptr.h"
 
 namespace cartesi {
 
 using namespace std::string_literals;
 
-class base_error : public std::invalid_argument {
-public:
-    explicit base_error(const char *err) : std::invalid_argument{err} {
-        ;
+static os_mmap_flags check_mmap_flags(const pmas_flags &flags, const backing_store_config &backing_store,
+    const memory_address_range_config &memory_config) {
+    if (!flags.M) {
+        throw std::invalid_argument{"memory address range must be flagged memory"};
     }
-};
-
-static bool check_read_only(bool host_read_only, bool flags_W, bool create) {
-    if (host_read_only) {
-        if (create) {
-            throw base_error{"newly-created backing store cannot be read-only"};
-        }
-        if (flags_W) {
-            throw base_error{"backing store for writable memory address range cannot be read-only"};
-        }
+    if (backing_store.shared && backing_store.data_filename.empty()) {
+        throw std::invalid_argument{"shared backing store must have a filename"};
     }
-    return host_read_only;
-}
-
-static const pmas_flags &check_flags(pmas_flags &&) = delete;
-static const pmas_flags &check_flags(const pmas_flags &flags) {
-    if (!flags.M) {
-        throw base_error{"memory address range must be flagged memory"};
+    if (backing_store.create && !backing_store.shared) {
+        throw std::invalid_argument{"created backing store must also be shared"};
+    }
+    if (backing_store.truncate && !backing_store.shared) {
+        throw std::invalid_argument{"truncated backing store must also be shared"};
+    }
+    if (memory_config.host_read_only && flags.W) {
+        throw std::invalid_argument{"backing store for writable memory address range cannot be read-only"};
     }
-    return flags;
+    return os_mmap_flags{
+        .read_only = memory_config.host_read_only && !backing_store.newly_created(),
+        .shared = backing_store.shared,
+        .no_reserve = memory_config.host_no_reserve,
+    };
 }
 
-static const auto throw_base_error = [](const char *err) { throw base_error{err}; };
+static const auto throw_invalid_argument = [](const char *err) { throw std::invalid_argument{err}; };
 
 memory_address_range::memory_address_range(const std::string &description, uint64_t start, uint64_t length,
     const pmas_flags &flags, const backing_store_config &backing_store,
     const memory_address_range_config &memory_config) try :
-    address_range(description.c_str(), start, length, check_flags(flags), throw_base_error),
+    address_range(description.c_str(), start, length, flags, throw_invalid_argument),
     m_ptr{make_unique_mmap<unsigned char>(std::max(memory_config.host_length, length),
-        os_mmap_flags{
-            .read_only = check_read_only(memory_config.host_read_only, flags.W, backing_store.create),
-            .shared = backing_store.shared,
-            .create = backing_store.create,
-            .truncate = backing_store.truncate,
-            .lock = !backing_store.data_filename.empty(),
-        },
-        backing_store.data_filename, length)},
+        check_mmap_flags(flags, backing_store, memory_config), backing_store.data_filename, length)},
     m_host_memory{m_ptr.get()},
     m_config{memory_config},
+    m_backing_store{backing_store},
     m_dpt{get_level_count(length), length >> AR_LOG2_PAGE_SIZE},
     m_dht{get_level_count(length), length >> AR_LOG2_PAGE_SIZE} {
-} catch (const base_error &b) {
-    throw; // already contains the description
 } catch (const std::exception &e) {
     throw std::invalid_argument{std::string{e.what()}.append(" when initializing ").append(description)};
 } catch (...) {
diff --git a/src/memory-address-range.h b/src/memory-address-range.h
index fc08b6fca..37be5c729 100644
--- a/src/memory-address-range.h
+++ b/src/memory-address-range.h
@@ -35,6 +35,10 @@ class machine;
 struct memory_address_range_config {
     ///< Whether memory is read-only on host. (If set, must be read-only on target as well)
     bool host_read_only{false};
+    ///< Whether host should not reserve memory when mapping the memory.
+    /// Only useful to create or load machines with large unused address space on host without enough memory or swap.
+    /// (Use with caution as the process may crash when running out of host memory)/
+    bool host_no_reserve{false};
     ///< Total amount of memory allocated by host. (Must be larger than what is needed by target)
     uint64_t host_length{0};
 };
@@ -42,12 +46,11 @@ struct memory_address_range_config {
 /// \file
 /// \brief An address range occupied by memory
 
-/// \brief An address range occupied by memory
 class memory_address_range : public address_range {
-
     unique_mmap_ptr<unsigned char> m_ptr; ///< Pointer to mapped memory
     unsigned char *m_host_memory;         ///< Start of associated memory region in host.
-    memory_address_range_config m_config; ///< Configuration passed to constructor.
+    memory_address_range_config m_config; ///< Memory configuration passed to constructor.
+    backing_store_config m_backing_store; ///< Backing store configuration passed to constructor.
     dirty_page_tree m_dpt;                ///< Tree of dirty pages.
     dense_hash_tree m_dht;                ///< Dense hash tree of pages.
 
@@ -66,7 +69,7 @@ class memory_address_range : public address_range {
     /// and is not part of the backing storage, but can be used for other purposes.
     /// \p config.host_read_only Marks memory as read-only on host itself. Requires \p flags.W to be cleared as well.
     memory_address_range(const std::string &description, uint64_t start, uint64_t length, const pmas_flags &flags,
-        const backing_store_config &backing_store, const memory_address_range_config &memory_config);
+        const backing_store_config &backing_store = {}, const memory_address_range_config &memory_config = {});
 
     memory_address_range(const memory_address_range &) = delete;
     memory_address_range &operator=(const memory_address_range &) = delete;
@@ -88,6 +91,10 @@ class memory_address_range : public address_range {
         return m_config.host_read_only;
     }
 
+    bool do_is_backing_store_shared() const noexcept override {
+        return m_backing_store.shared;
+    }
+
     dirty_page_tree &do_get_dirty_page_tree() noexcept override {
         return m_dpt;
     }
@@ -105,12 +112,6 @@ class memory_address_range : public address_range {
     }
 };
 
-static inline auto make_memory_address_range(const std::string &description, uint64_t start, uint64_t length,
-    const pmas_flags &flags, const backing_store_config &backing_store = {},
-    const memory_address_range_config &config = {}) {
-    return memory_address_range{description, start, length, flags, backing_store, config};
-}
-
 } // namespace cartesi
 
 #endif
diff --git a/src/os-features.h b/src/os-features.h
index cd5476ab1..597b401fc 100644
--- a/src/os-features.h
+++ b/src/os-features.h
@@ -64,7 +64,7 @@
 #define HAVE_SELECT
 #endif
 
-#if !defined(NO_POSIX_FILE) && !defined(__wasi__)
+#if !defined(NO_POSIX_FS) && !defined(__wasi__)
 #define HAVE_POSIX_FS
 #endif
 
@@ -80,4 +80,12 @@
 #define HAVE_FLOCK
 #endif
 
+#if !defined(NO_FICLONE) && defined(__linux__) && defined(HAVE_IOCTL)
+#define HAVE_FICLONE
+#endif
+
+#if !defined(NO_CLONEFILE) && defined(__APPLE__)
+#define HAVE_CLONEFILE
+#endif
+
 #endif
diff --git a/src/os-filesystem.cpp b/src/os-filesystem.cpp
new file mode 100644
index 000000000..2a6c79385
--- /dev/null
+++ b/src/os-filesystem.cpp
@@ -0,0 +1,542 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#include "os-features.h"
+
+// Must be included before
+#include "os-posix-compat.h"
+
+#include <fcntl.h>    // open
+#include <sys/stat.h> // stat/fstat/mkdir/fchmod
+#include <unistd.h>   // unlink/rmdir/close/ftruncate/pread/pwrite
+
+#include "os-filesystem.h"
+
+#include "address-range-constants.h"
+#include "is-pristine.h"
+#include "scope-exit.h"
+
+#include <array>
+#include <cerrno>
+#include <cstddef>
+#include <cstdint>
+#include <cstdlib>
+#include <cstring>
+#include <memory>
+#include <span>
+#include <sstream>
+#include <system_error>
+#include <tuple>
+#include <utility>
+
+#ifdef HAVE_FLOCK
+#include <sys/file.h> // flock
+#endif
+
+#ifdef HAVE_CLONEFILE
+#include <sys/clonefile.h> // clonefile
+#endif
+
+#ifdef HAVE_FICLONE
+#include <sys/ioctl.h> // ioctl
+#ifndef FICLONE
+#define FICLONE _IOW(0x94, 9, int)
+#endif
+#endif
+
+namespace cartesi::os {
+
+constexpr auto S_WRITE_ALL = S_IWUSR | S_IWGRP | S_IWOTH;
+constexpr auto S_CREATE_DIRECTORY = S_IRWXU | S_IRGRP | S_IXGRP | S_IROTH | S_IXOTH;
+constexpr auto S_CREATE_FILE = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH;
+constexpr auto S_ACCESS_ALL = S_IRWXU | S_IRWXG | S_IRWXO;
+
+using namespace std::string_literals;
+
+/// \brief Retry a function call on EINTR error.
+/// \param func Function to be retried.
+/// \details Some POSIX functions may be interrupted by external signal handlers,
+/// this helper ensures that the function is retried until it succeeds or fails with a different error.
+template <typename F>
+static constexpr auto retry_on_eintr(const F &func) {
+    while (true) {
+        auto result = func();
+        if (!(result == -1 && errno == EINTR)) {
+            return result;
+        }
+    }
+}
+
+/// \brief Rethrow system error with additional path name context.
+/// \param e Original system error.
+/// \param description Description of the error.
+/// \param pathname Path name.
+/// \param operation Operation that failed.
+static inline std::system_error make_path_system_error(int errno_code, const std::string &description,
+    const std::string &pathname, const std::string &operation = {}) {
+    std::ostringstream sout;
+    sout << description << " '"s << pathname << "'"s;
+    if (!operation.empty()) {
+        sout << ": "s << operation;
+    }
+    return std::system_error{errno_code, std::generic_category(), sout.str()};
+}
+
+/// \brief Rethrow system error with additional path name contexts.
+/// \param e Original system error.
+/// \param description Description of the error.
+/// \param from From path name.
+/// \param to To path name.
+/// \param operation Operation that failed.
+static inline std::system_error make_copy_path_system_error(int errno_code, const std::string &description,
+    const std::string &from, const std::string &to, const std::string &operation = {}) {
+    std::ostringstream sout;
+    sout << description << " from '"s << from << "' to '"s << to << "'"s;
+    if (!operation.empty()) {
+        sout << ": "s << operation;
+    }
+    return std::system_error{errno_code, std::generic_category(), sout.str()};
+}
+
+bool exists(const std::string &pathname) {
+    struct stat st{};
+    if (stat(pathname.c_str(), &st) == 0) { // Exists
+        return true;
+    }
+    if (errno == ENOENT) { // Does not exist
+        return false;
+    }
+    throw make_path_system_error(errno, "unable to check existence of path"s, pathname);
+}
+
+uint64_t file_size(const std::string &filename) {
+    struct stat st{};
+    if (stat(filename.c_str(), &st) != 0) {
+        throw make_path_system_error(errno, "unable to get size of file"s, filename);
+    }
+    if (S_ISDIR(st.st_mode)) { // Not a file
+        throw make_path_system_error(EISDIR, "unable to get size of file"s, filename);
+    }
+    return static_cast<uint64_t>(st.st_size);
+}
+
+void create_directory(const std::string &dirname) {
+    if (mkdir(dirname.c_str(), S_CREATE_DIRECTORY) != 0) {
+        throw make_path_system_error(errno, "unable to create directory"s, dirname);
+    }
+}
+
+void remove_directory(const std::string &dirname) {
+    if (rmdir(dirname.c_str()) != 0) {
+        throw make_path_system_error(errno, "unable to remove directory"s, dirname);
+    }
+}
+
+void remove_file(const std::string &filename) {
+    if (unlink(filename.c_str()) != 0) {
+        throw make_path_system_error(errno, "unable to remove file"s, filename);
+    }
+}
+
+void change_writable(const std::string &pathname, bool writable) {
+    // Open the path
+    const auto fd = open(pathname.c_str(), O_RDONLY | O_BINARY); // NOLINT(misc-redundant-expression)
+    if (fd < 0) {
+        throw make_path_system_error(errno, "unable to change write perms of path"s, pathname, "open() failed"s);
+    }
+    auto failure_close = scope_fail([&] { std::ignore = retry_on_eintr([&] { return close(fd); }); });
+
+    // Get permissions
+    struct stat st{};
+    if (fstat(fd, &st) != 0) {
+        throw make_path_system_error(errno, "unable to change write perms of path"s, pathname, "stat() failed"s);
+    }
+
+    // Remove write permissions
+    auto new_mode = (st.st_mode & ~S_WRITE_ALL);
+
+    // Add write permissions for user, group and others if read permissions are set
+    if (writable) {
+        if ((st.st_mode & S_IRUSR) != 0) {
+            new_mode |= S_IWUSR;
+        }
+        if ((st.st_mode & S_IRGRP) != 0) {
+            new_mode |= S_IWGRP;
+        }
+        if ((st.st_mode & S_IROTH) != 0) {
+            new_mode |= S_IWOTH;
+        }
+    }
+
+    // Change permissions
+    if (new_mode != st.st_mode && fchmod(fd, new_mode) != 0) {
+        throw make_path_system_error(errno, "unable to change write perms of path"s, pathname, "chmod() failed"s);
+    }
+
+    // Ensure the path is closed gracefully
+    failure_close.release();
+    if (retry_on_eintr([&] { return close(fd); }) != 0) {
+        throw make_path_system_error(errno, "unable to change write perms of path"s, pathname, "close() failed"s);
+    }
+}
+
+void truncate_file(const std::string &filename, uint64_t size, bool create) {
+    // Determine flags based on whether we should create the file
+    const int flags = O_WRONLY | O_BINARY | (create ? (O_CREAT | O_EXCL) : 0); // NOLINT(misc-redundant-expression)
+    const mode_t mode = create ? S_CREATE_FILE : 0;
+
+    // Open the file
+    const auto fd = open(filename.c_str(), flags, mode);
+    if (fd < 0) {
+        throw make_path_system_error(errno, "unable to truncate file"s, filename, "open() failed"s);
+    }
+    auto failure_unlink = scope_fail([&] {
+        if (create) {
+            std::ignore = unlink(filename.c_str());
+        }
+    });
+    auto failure_close = scope_fail([&] { std::ignore = retry_on_eintr([&] { return close(fd); }); });
+
+#ifdef HAVE_FLOCK
+    // Lock file immediately for writing
+    if (flock(fd, LOCK_EX | LOCK_NB) != 0) {
+        throw make_path_system_error(errno, "unable to truncate file"s, filename, "flock() failed"s);
+    }
+#endif
+
+    // Truncate file size
+    if (retry_on_eintr([&] { return ftruncate(fd, static_cast<off_t>(size)); }) != 0) {
+        throw make_path_system_error(errno, "unable to truncate file"s, filename, "ftruncate() failed"s);
+    }
+
+    // Ensure the file is closed gracefully
+    failure_close.release();
+    if (retry_on_eintr([&] { return close(fd); }) != 0) {
+        throw make_path_system_error(errno, "unable to truncate file"s, filename, "close() failed"s);
+    }
+}
+
+std::pair<std::unique_ptr<uint8_t[]>, std::span<uint8_t>> read_file(const std::string &filename) {
+    // Open file
+    const auto fd = open(filename.c_str(), O_RDONLY | O_BINARY); // NOLINT(misc-redundant-expression)
+    if (fd < 0) {
+        throw make_path_system_error(errno, "unable to read file"s, filename, "open() failed"s);
+    }
+    auto cleanup = scope_exit([&] { std::ignore = retry_on_eintr([&] { return close(fd); }); });
+
+#ifdef HAVE_FLOCK
+    // Lock file imediatelly for reading
+    if (flock(fd, LOCK_SH | LOCK_NB) != 0) {
+        throw make_path_system_error(errno, "unable to read file"s, filename, "flock() failed");
+    }
+#endif
+
+    // Get file size
+    struct stat st{};
+    if (fstat(fd, &st) != 0) {
+        throw make_path_system_error(errno, "unable to read file"s, filename, "fstat() failed"s);
+    }
+    const auto size = static_cast<size_t>(st.st_size);
+
+    // Check if file is empty
+    if (size == 0) {
+        return {};
+    }
+
+    // Allocate data
+    auto data = std::make_unique<uint8_t[]>(size);
+
+    // Read data
+    size_t offset = 0;
+    while (offset < size) {
+        const auto bytes_read =
+            retry_on_eintr([&] { return pread(fd, data.get() + offset, size - offset, static_cast<off_t>(offset)); });
+        if (bytes_read < 0) {
+            throw make_path_system_error(errno, "unable to read file"s, filename, "pread() failed"s);
+        }
+        if (bytes_read == 0) {
+            throw make_path_system_error(ERANGE, "unable to read file"s, filename, "pread() read 0 bytes"s);
+        }
+        offset += static_cast<size_t>(bytes_read);
+    }
+
+    return {std::move(data), std::span<uint8_t>{data.get(), size}};
+}
+
+void create_file(const std::string &filename, std::span<const uint8_t> data) {
+    // Create file
+    const auto fd = open(filename.c_str(), O_WRONLY | O_BINARY | O_CREAT | O_EXCL,
+        S_CREATE_FILE); // NOLINT(misc-redundant-expression)
+    if (fd < 0) {
+        throw make_path_system_error(errno, "unable to create file"s, filename, "open() failed"s);
+    }
+    auto failure_unlink = scope_fail([&] { std::ignore = unlink(filename.c_str()); });
+    auto failure_close = scope_fail([&] { std::ignore = retry_on_eintr([&] { return close(fd); }); });
+
+#ifdef HAVE_FLOCK
+    // Lock file immediately for writing
+    if (flock(fd, LOCK_EX | LOCK_NB) != 0) {
+        throw make_path_system_error(errno, "unable to create file"s, filename, "flock() failed"s);
+    }
+#endif
+
+    // Truncate file size
+    if (retry_on_eintr([&] { return ftruncate(fd, static_cast<off_t>(data.size())); }) != 0) {
+        throw make_path_system_error(errno, "unable to create file"s, filename, "ftruncate() failed"s);
+    }
+
+    // Write data keeping file sparsity
+    size_t offset = 0;
+    while (offset < data.size()) {
+        auto bytes_to_write = std::min<size_t>(AR_PAGE_SIZE, data.size() - offset);
+        // Only write non-sparse blocks
+        if (!is_pristine(std::span<const unsigned char>{data.data() + offset, bytes_to_write})) {
+            const auto bytes_written = retry_on_eintr(
+                [&] { return pwrite(fd, data.data() + offset, bytes_to_write, static_cast<off_t>(offset)); });
+            if (bytes_written < 0) {
+                throw make_path_system_error(errno, "unable to create file"s, filename, "pwrite() failed"s);
+            }
+            if (bytes_written == 0) {
+                throw make_path_system_error(EIO, "unable to create file"s, filename, "pwrite() wrote 0 bytes"s);
+            }
+            offset += static_cast<size_t>(bytes_written);
+        } else {
+            offset += bytes_to_write;
+        }
+    }
+
+    // Ensure the file is closed gracefully
+    failure_close.release();
+    if (retry_on_eintr([&] { return close(fd); }) != 0) {
+        throw make_path_system_error(errno, "unable to create file"s, filename, "close() failed"s);
+    }
+}
+
+void copy_file(const std::string &from, const std::string &to, uint64_t size) {
+    // Open source file
+    const auto from_fd = open(from.c_str(), O_RDONLY | O_BINARY); // NOLINT(misc-redundant-expression)
+    if (from_fd < 0) {
+        throw make_copy_path_system_error(errno, "unable to copy file"s, from, to, "open() failed"s);
+    }
+    auto cleanup_from = scope_exit([&] { std::ignore = retry_on_eintr([&] { return close(from_fd); }); });
+
+#ifdef HAVE_FLOCK
+    // Lock source file immediately for reading
+    if (flock(from_fd, LOCK_SH | LOCK_NB) != 0) {
+        throw make_copy_path_system_error(errno, "unable to copy file"s, from, to, "flock() failed"s);
+    }
+#endif
+
+    // Get source file permissions and size
+    struct stat st{};
+    if (fstat(from_fd, &st) != 0) {
+        throw make_copy_path_system_error(errno, "unable to copy file"s, from, to, "fstat() failed"s);
+    }
+
+    // Determine actual copy size
+    if (size == UINT64_MAX) {
+        size = static_cast<uint64_t>(st.st_size);
+    }
+    const size_t copy_size = std::min<size_t>(st.st_size, size);
+
+    // Create destination file
+    const auto to_fd = open(to.c_str(), O_WRONLY | O_BINARY | O_CREAT | O_EXCL,
+        st.st_mode & S_ACCESS_ALL); // NOLINT(misc-redundant-expression)
+    if (to_fd < 0) {
+        throw make_copy_path_system_error(errno, "unable to copy file"s, from, to, "open() failed"s);
+    }
+    auto failure_unlink_to = scope_fail([&] { std::ignore = unlink(to.c_str()); });
+    auto failure_close_to = scope_fail([&] { std::ignore = retry_on_eintr([&] { return close(to_fd); }); });
+
+#ifdef HAVE_FLOCK
+    // Lock destination file immediately for writing
+    if (flock(to_fd, LOCK_EX | LOCK_NB) != 0) {
+        throw make_copy_path_system_error(errno, "unable to copy file"s, from, to, "flock() failed"s);
+    }
+#endif
+
+    // Truncate destination file size
+    if (retry_on_eintr([&] { return ftruncate(to_fd, static_cast<off_t>(size)); }) != 0) {
+        throw make_copy_path_system_error(errno, "unable to copy file"s, from, to, "ftruncate() failed"s);
+    }
+
+    // 16-byte aligned buffer for efficient pristine page checks during file copy
+    alignas(16) std::array<uint8_t, AR_PAGE_SIZE> buffer{};
+
+    // Copy data keeping file sparsity
+    size_t offset = 0;
+    while (offset < copy_size) {
+        const auto bytes_to_read = std::min<size_t>(buffer.size(), copy_size - offset);
+
+        // Read data from source
+        const auto bytes_read =
+            retry_on_eintr([&] { return pread(from_fd, buffer.data(), bytes_to_read, static_cast<off_t>(offset)); });
+        if (bytes_read < 0) {
+            throw make_copy_path_system_error(errno, "unable to copy file"s, from, to, "pread() failed"s);
+        }
+        if (bytes_read == 0) {
+            throw make_copy_path_system_error(EIO, "unable to copy file"s, from, to, "pread() read 0 bytes"s);
+        }
+
+        // Write only non-sparse blocks to destination
+        if (!is_pristine(std::span<const unsigned char>{buffer.data(), static_cast<size_t>(bytes_read)})) {
+            const auto bytes_written =
+                retry_on_eintr([&] { return pwrite(to_fd, buffer.data(), bytes_read, static_cast<off_t>(offset)); });
+            if (bytes_written < 0) {
+                throw make_copy_path_system_error(errno, "unable to copy file"s, from, to, "pwrite() failed"s);
+            }
+            if (bytes_written == 0) {
+                throw make_copy_path_system_error(EIO, "unable to copy file"s, from, to, "pwrite() wrote 0 bytes"s);
+            }
+            offset += static_cast<size_t>(bytes_written);
+        } else {
+            offset += bytes_read;
+        }
+
+        // Attempt to advance the offset to the next data block if SEEK_DATA is supported.
+        // This efficiently skips over holes in sparse files (supported on Linux, not on macOS).
+#ifdef SEEK_DATA
+        auto next_offset = lseek(from_fd, static_cast<off_t>(offset), SEEK_DATA);
+        if (next_offset == -1) {
+            if (errno == ENXIO) { // End of file, or within a hole at the end of the file
+                break;
+            }
+            if (errno == EINVAL || errno == ENOTSUP) { // SEEK_DATA is not supported
+                continue;
+            }
+            throw make_copy_path_system_error(errno, "unable to copy file"s, from, to, "lseek() failed"s);
+        }
+        offset = static_cast<size_t>(next_offset);
+#endif
+    }
+
+    // Ensure destination file is closed gracefully
+    failure_close_to.release();
+    if (retry_on_eintr([&] { return close(to_fd); }) != 0) {
+        throw make_copy_path_system_error(errno, "unable to copy file"s, from, to, "close() failed"s);
+    }
+}
+
+void hardlink_file(const std::string &from, const std::string &to) {
+    if (link(from.c_str(), to.c_str()) != 0) {
+        throw make_copy_path_system_error(errno, "unable to create hard link"s, from, to);
+    }
+}
+
+void reflink_file(const std::string &from, const std::string &to) {
+#if defined(HAVE_FICLONE) // Linux
+    // Open source file
+    const auto from_fd = open(from.c_str(), O_RDONLY | O_BINARY); // NOLINT(misc-redundant-expression)
+    if (from_fd < 0) {
+        throw make_copy_path_system_error(errno, "unable to create reference link"s, from, to, "open() failed"s);
+    }
+    auto cleanup_from = scope_exit([&] { std::ignore = retry_on_eintr([&] { return close(from_fd); }); });
+
+#ifdef HAVE_FLOCK
+    // Lock source file immediately for reading
+    if (flock(from_fd, LOCK_SH | LOCK_NB) != 0) {
+        throw make_copy_path_system_error(errno, "unable to create reference link"s, from, to, "flock() failed"s);
+    }
+#endif
+
+    // Get source file permissions
+    struct stat st{};
+    if (fstat(from_fd, &st) != 0) {
+        throw make_copy_path_system_error(errno, "unable to create reference link"s, from, to, "fstat() failed"s);
+    }
+
+    // Create destination file
+    const auto to_fd = open(to.c_str(), O_WRONLY | O_BINARY | O_CREAT | O_EXCL,
+        st.st_mode & ACCESSPERMS); // NOLINT(misc-redundant-expression)
+    if (to_fd < 0) {
+        throw make_copy_path_system_error(errno, "unable to create reference link"s, from, to, "open() failed"s);
+    }
+    auto failure_unlink = scope_fail([&] { std::ignore = unlink(to.c_str()); });
+    auto failure_close = scope_fail([&] { std::ignore = retry_on_eintr([&] { return close(to_fd); }); });
+
+#ifdef HAVE_FLOCK
+    // Lock destination file immediately for writing
+    if (flock(to_fd, LOCK_EX | LOCK_NB) != 0) {
+        throw make_copy_path_system_error(errno, "unable to create reference link"s, from, to, "flock() failed"s);
+    }
+#endif
+
+    // Clone the file
+    if (ioctl(to_fd, FICLONE, from_fd) != 0) {
+        throw make_copy_path_system_error(errno, "unable to create reference link"s, from, to,
+            "FICLONE ioctl() failed"s);
+    }
+
+    // Ensure the file is closed gracefully
+    failure_close.release();
+    if (retry_on_eintr([&] { return close(to_fd); }) != 0) {
+        throw make_copy_path_system_error(errno, "unable to create reference link"s, from, to, "close() failed"s);
+    }
+#elif defined(HAVE_CLONEFILE) // macOS
+    if (clonefile(from.c_str(), to.c_str(), 0) != 0) {
+        throw make_copy_path_system_error(errno, "unable to create reference link"s, from, to, "clonefile() failed"s);
+    }
+#else
+    throw make_copy_path_system_error(ENOTSUP, "unable to create reference link"s, from, to);
+#endif
+}
+
+void clone_file(const std::string &from, const std::string &to) {
+    // Open source file
+    const auto from_fd = open(from.c_str(), O_RDONLY | O_BINARY); // NOLINT(misc-redundant-expression)
+    if (from_fd < 0) {
+        throw make_copy_path_system_error(errno, "unable to clone file"s, from, to, "open() failed"s);
+    }
+    auto cleanup_from = scope_exit([&] { std::ignore = retry_on_eintr([&] { return close(from_fd); }); });
+
+#ifdef HAVE_FLOCK
+    // Lock source file immediately for reading
+    if (flock(from_fd, LOCK_SH | LOCK_NB) != 0) {
+        throw make_copy_path_system_error(errno, "unable to clone file"s, from, to, "flock() failed"s);
+    }
+#endif
+
+    // Check if source file exists and get its permissions
+    struct stat st{};
+    if (fstat(from_fd, &st) != 0) {
+        throw make_copy_path_system_error(errno, "unable to clone file"s, from, to, "stat() failed"s);
+    }
+    if (S_ISDIR(st.st_mode)) { // Not a file
+        throw make_copy_path_system_error(EISDIR, "unable to clone file"s, from, to);
+    }
+
+    // Attempt to link the file, otherwise fall back to copy
+    try {
+        if ((st.st_mode & S_WRITE_ALL) != 0) {
+            reflink_file(from, to);
+        } else {
+            hardlink_file(from, to);
+        }
+    } catch (const std::system_error &e) {
+        if (e.code().value() == ENOTSUP || // Operation not supported
+            e.code().value() == EXDEV ||   // Not on the same mounted filesystem
+            e.code().value() == EPERM      // Can happen if the filesystem does not support hard link
+        ) {
+            // Fall back to regular copy
+            copy_file(from, to, UINT64_MAX);
+        } else {
+            // Error is not related to platform support, rethrow
+            throw;
+        }
+    }
+}
+
+} // namespace cartesi::os
diff --git a/src/os-filesystem.h b/src/os-filesystem.h
new file mode 100644
index 000000000..12630faa9
--- /dev/null
+++ b/src/os-filesystem.h
@@ -0,0 +1,130 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef OS_FILESYSTEM_H
+#define OS_FILESYSTEM_H
+
+#include <cstdint>
+#include <memory>
+#include <span>
+#include <string>
+#include <system_error>
+#include <utility>
+
+namespace cartesi::os {
+
+/// \brief Check if given path exists.
+/// \param pathname Path to a file or directory.
+/// \returns True if exists, false otherwise.
+/// \throw std::system_error on error.
+/// \details Symbolic links are followed.
+[[nodiscard]] bool exists(const std::string &pathname);
+
+/// \brief Get the length of a file.
+/// \param filename Path to the file.
+/// \returns Length of the file in bytes.
+/// \throw std::system_error on error.
+/// \details Symbolic links are followed.
+[[nodiscard]] uint64_t file_size(const std::string &filename);
+
+/// \brief Creates a new directory.
+/// \param dirname Path to the directory, must not already exist.
+/// \throw std::system_error on error.
+void create_directory(const std::string &dirname);
+
+/// \brief Removes a directory.
+/// \param dirname Path to the directory, must exist.
+/// \throw std::system_error on error.
+void remove_directory(const std::string &dirname);
+
+/// \brief Removes a file.
+/// \param filename Path to the file, must exist.
+/// \throw std::system_error on error.
+void remove_file(const std::string &filename);
+
+/// \brief Changes write permissions of a path.
+/// \param pathname Path to the file or directory.
+/// \param writable If true, makes the path writable, otherwise read-only.
+/// \throw std::system_error on error.
+/// \details Symbolic links are followed.
+void change_writable(const std::string &pathname, bool writable);
+
+/// \brief Truncates a file.
+/// \param filename Path to the file.
+/// \param size New size of the file.
+/// \param create If true, creates the file if it does not exist.
+/// \details The file is locked for exclusive writing during the operation.
+void truncate_file(const std::string &filename, uint64_t size, bool create = false);
+
+/// \brief Reads a file.
+/// \param filename Path to the file, must exist.
+/// \returns A pair containing a unique pointer to the data and a span to the data.
+/// \throw std::system_error on error.
+/// The file is locked for shared reading during the operation.
+[[nodiscard]] std::pair<std::unique_ptr<uint8_t[]>, std::span<uint8_t>> read_file(const std::string &filename);
+
+/// \brief Creates a new file and writes data to it.
+/// \param filename Path to the file, must not already exist.
+/// \param data A span containing the data to be written to the file.
+/// \throw std::system_error on error.
+/// \details File sparsity is preserved at 4KB granularity.
+/// The file is locked for exclusive writing during the operation.
+void create_file(const std::string &filename, std::span<const uint8_t> data);
+
+/// \brief Copies a file.
+/// \param from Path to the source file.
+/// \param to Path to the destination file, must not already exist.
+/// \param size Size of the destination file. If UINT64_MAX, the entire file is copied.
+/// If the source file is smaller than size, the destination file is padded with zeros.
+/// If the source file is larger than size, the destination file is truncated to size.
+/// \details The sparsity of the original file is preserved at 4KB granularity.
+/// The source file is locked for shared reading during the operation.
+/// The destination file is locked for exclusive writing during the operation.
+/// \throw std::system_error on error.
+void copy_file(const std::string &from, const std::string &to, uint64_t size = UINT64_MAX);
+
+/// \brief Creates a hard link to a file.
+/// \param from Path to the source file.
+/// \param to Path to the destination file, must not already exist.
+/// \throw std::system_error on error.
+/// \details This is only supported on some filesystems (e.g. EXT4).
+/// Recommended for use with read-only files.
+void hardlink_file(const std::string &from, const std::string &to);
+
+/// \brief Creates a reference link to a file.
+/// \param from Path to the source file.
+/// \param to Path to the destination file, must not already exist.
+/// \throw std::system_error on error.
+/// \details This is only supported on copy-on-write filesystems (e.g. BTRFS or XFS).
+/// The source file is locked for shared reading during the operation.
+/// The destination file is locked for exclusive writing during the operation.
+void reflink_file(const std::string &from, const std::string &to);
+
+/// \brief Clones a file.
+/// \param from Path to the source file.
+/// \param to Path to the destination file, must not already exist.
+/// \throw std::system_error on error.
+/// \details If the original file is read-only, the new file is also read-only, and os::hardlink_file() is used.
+/// If the original file is writable, the new file is also writable, and os::reflink_file() is used.
+/// If neither os::hardlink_file() nor os::reflink_file() is supported, then os::copy_file() is used.
+/// File sparsity is preserved for all cases.
+/// The source file is locked for shared reading during the operation.
+/// The destination file may be locked for exclusive writing during the operation.
+void clone_file(const std::string &from, const std::string &to);
+
+} // namespace cartesi::os
+
+#endif // OS_FILESYSTEM_H
diff --git a/src/os-mmap.cpp b/src/os-mmap.cpp
index 74bb92b04..d89dedc5d 100644
--- a/src/os-mmap.cpp
+++ b/src/os-mmap.cpp
@@ -14,25 +14,10 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#ifdef _WIN32
-#ifndef WIN32_LEAN_AND_MEAN
-#define WIN32_LEAN_AND_MEAN
-#endif
-#ifndef _CRT_SECURE_NO_WARNINGS
-#define _CRT_SECURE_NO_WARNINGS
-#endif
-#include <windows.h>
-#endif // _WIN32
-
-#include <cstring>
-#include <stdexcept>
-#include <system_error>
-
 #include "os-features.h"
-#include "os-mmap.h"
-#include "scope-exit.h"
 
-//------------------------------------------------------------------------------
+// Must be included before
+#include "os-posix-compat.h"
 
 #if defined(HAVE_MMAP)
 #include <fcntl.h>    // open
@@ -48,6 +33,15 @@
 #include <sys/file.h> // flock
 #endif
 
+#include "os-mmap.h"
+
+#include "scope-exit.h"
+
+#include <cerrno>
+#include <cstring>
+#include <stdexcept>
+#include <system_error>
+
 namespace cartesi {
 
 using namespace std::string_literals;
@@ -76,15 +70,9 @@ uint64_t os_get_mmap_page_size() {
 os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string &backing_filename,
     uint64_t backing_length) {
     // Check some preconditions
-    if (backing_filename.empty() && (flags.lock || flags.shared || flags.create)) {
+    if (backing_filename.empty() && flags.shared) {
         throw std::invalid_argument{"backing filename must be specified"s};
     }
-    if (flags.create && !flags.shared) {
-        throw std::invalid_argument{"created backing files must be shared"s};
-    }
-    if (flags.read_only && flags.shared && (flags.create || flags.truncate)) {
-        throw std::invalid_argument{"cannot create or truncate backing files that are shared read-only"s};
-    }
     if (length == 0) {
         throw std::invalid_argument{"memory map length cannot be zero"s};
     }
@@ -109,10 +97,6 @@ os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string
         if (backing_fd >= 0) {
             // Close backing file
             close(backing_fd);
-            // Remove backing file in case it was created
-            if (flags.create) {
-                unlink(backing_filename.c_str());
-            }
         }
     });
 
@@ -121,14 +105,9 @@ os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string
         // Determine backing file open flags
         int oflags = (shared_write ? O_RDWR : O_RDONLY);
         oflags |= O_CLOEXEC; // to remove file locks on fork + exec
-        mode_t omode = 0;
-        if (flags.create) {
-            oflags |= O_CREAT | O_EXCL;
-            omode = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH;
-        }
 
         // Open backing file
-        backing_fd = open(backing_filename.c_str(), oflags, omode);
+        backing_fd = open(backing_filename.c_str(), oflags);
         if (backing_fd < 0) {
             throw std::system_error{errno, std::generic_category(),
                 "unable to open backing file '"s + backing_filename + "'"s};
@@ -136,42 +115,31 @@ os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string
 
 #ifdef HAVE_FLOCK
         // Lock backing file immediately after opening it
-        if (flags.lock) {
-            const int flockop = (shared_write ? LOCK_EX : LOCK_SH) | LOCK_NB;
-            if (flock(backing_fd, flockop) < 0) {
-                throw std::system_error{errno, std::generic_category(),
-                    "unable to lock backing file '"s + backing_filename + "'"s};
-            }
+        const int flockop = (shared_write ? LOCK_EX : LOCK_SH) | LOCK_NB;
+        if (flock(backing_fd, flockop) != 0) {
+            throw std::system_error{errno, std::generic_category(),
+                "unable to lock backing file '"s + backing_filename + "'"s};
         }
 #endif // HAVE_FLOCK
 
         // Get backing file size
         struct stat statbuf{};
-        if (fstat(backing_fd, &statbuf) < 0) {
+        if (fstat(backing_fd, &statbuf) != 0) {
             throw std::system_error{errno, std::generic_category(),
                 "unable to obtain length of backing file '"s + backing_filename + "'"s};
         }
         backing_file_length = static_cast<uint64_t>(statbuf.st_size);
 
-        // When backing file length mismatch the desired backing length we may need to truncate
+        // Check backing file length mismatch
         if (backing_file_length != backing_length) {
-            if (!(flags.truncate || flags.create)) { // Can we truncate?
+            if (flags.shared) {
                 throw std::runtime_error{"backing file '"s + backing_filename + "' length ("s +
                     std::to_string(backing_file_length) + ") does not match desired backing length ("s +
                     std::to_string(backing_length) + ")"s};
             }
-            if (flags.shared) { // Truncate backing file to match the desired length
-                if (ftruncate(backing_fd, static_cast<off_t>(backing_length)) < 0) {
-                    throw std::runtime_error{"unable to truncate backing file '"s + backing_filename + "' length ("s +
-                        std::to_string(backing_file_length) + ") to desired backing length ("s +
-                        std::to_string(backing_length) + ")"s};
-                }
-                backing_file_length = backing_length;
-            } else {
-                // Backing file length may be less than desired backing length,
-                // but this is fine, as we are not sharing the file.
-                // The gap between the file length and the memory length will be allocated as anonymous memory.
-            }
+            // Backing file length may be less than desired backing length,
+            // but this is fine, as we are not sharing the file.
+            // The gap between the file length and the memory length will be allocated as anonymous memory.
         }
     }
 
@@ -180,6 +148,11 @@ os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string
     if (backing_fd < 0) { // The mapping is not backed by any file
         mflags |= MAP_ANONYMOUS;
     }
+    int extra_mflags = 0;
+    if (flags.no_reserve) {
+        extra_mflags |= MAP_NORESERVE;
+    }
+    mflags |= extra_mflags;
 
     // Determine map protection flags
     int mprot = PROT_READ;
@@ -204,7 +177,8 @@ os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string
         // and the second portion is backed by anonymous memory.
 
         // Map entire memory range, this is required to use the subsequent MAP_FIXED safely.
-        host_memory = mmap(nullptr, length, mprot, MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
+        // const int m
+        host_memory = mmap(nullptr, length, mprot, MAP_PRIVATE | MAP_ANONYMOUS | extra_mflags, -1, 0);
         if (host_memory == MAP_FAILED) {
             throw std::system_error{errno, std::generic_category(), "unable to map memory"s};
         }
@@ -248,6 +222,7 @@ os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string
 
     return os_mmapd{.host_memory = host_memory,
         .length = length,
+        .flags = flags,
         .backing_sync_length = shared_write ? backing_length : 0,
         .backing_fd = backing_fd};
 
@@ -274,16 +249,11 @@ os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string
             std::ignore = CloseHandle(memory_mapping);
         }
         if (backing_fh != INVALID_HANDLE_VALUE) {
-            if (flags.lock) {
-                OVERLAPPED overlapped{};
-                std::ignore = UnlockFileEx(backing_fh, 0, MAXDWORD, MAXDWORD, &overlapped);
-            }
+            // Unlock file
+            OVERLAPPED overlapped{};
+            std::ignore = UnlockFileEx(backing_fh, 0, MAXDWORD, MAXDWORD, &overlapped);
             // Close backing file
             std::ignore = CloseHandle(backing_fh);
-            // Remove backing file in case it was created
-            if (flags.create) {
-                std::ignore = DeleteFileA(backing_filename.c_str());
-            }
         }
     });
 
@@ -292,7 +262,7 @@ os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string
         // Determine backing file open flags
         const DWORD open_access = GENERIC_READ | (!flags.read_only ? GENERIC_WRITE : 0);
         const DWORD share_mode = FILE_SHARE_READ | (!flags.read_only ? FILE_SHARE_WRITE : 0);
-        const DWORD creation = flags.create ? CREATE_NEW : OPEN_EXISTING;
+        const DWORD creation = OPEN_EXISTING;
 
         // Open backing file
         backing_fh = CreateFileA(backing_filename.c_str(), open_access, share_mode, nullptr, creation,
@@ -303,16 +273,14 @@ os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string
         }
 
         // Lock backing file immediately after opening it
-        if (flags.lock) {
-            DWORD lock_flags = LOCKFILE_FAIL_IMMEDIATELY; // Non-blocking lock
-            if (shared_write) {
-                lock_flags |= LOCKFILE_EXCLUSIVE_LOCK; // Exclusive lock for writing
-            }
-            OVERLAPPED overlapped{};
-            if (!LockFileEx(backing_fh, lock_flags, 0, MAXDWORD, MAXDWORD, &overlapped)) {
-                throw std::system_error{static_cast<int>(GetLastError()), std::system_category(),
-                    "unable to lock backing file '" + backing_filename + "'"};
-            }
+        DWORD lock_flags = LOCKFILE_FAIL_IMMEDIATELY; // Non-blocking lock
+        if (shared_write) {
+            lock_flags |= LOCKFILE_EXCLUSIVE_LOCK; // Exclusive lock for writing
+        }
+        OVERLAPPED overlapped{};
+        if (!LockFileEx(backing_fh, lock_flags, 0, MAXDWORD, MAXDWORD, &overlapped)) {
+            throw std::system_error{static_cast<int>(GetLastError()), std::system_category(),
+                "unable to lock backing file '" + backing_filename + "'"};
         }
 
         // Get backing file size
@@ -323,63 +291,18 @@ os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string
         }
         backing_file_length = static_cast<uint64_t>(size.QuadPart);
 
-        // When backing file length mismatch the desired backing length we may need to truncate
+        // Check backing file length mismatch
         if (backing_file_length != backing_length) {
-            if (!(flags.truncate || flags.create)) { // Can we truncate?
+            if (flags.shared) {
                 throw std::runtime_error{"backing file '"s + backing_filename + "' length ("s +
                     std::to_string(backing_file_length) + ") does not match desired backing length ("s +
                     std::to_string(backing_length) + ")"s};
-            }
-            if (flags.shared) { // Truncate backing file to match the desired length
-                // Set file pointer to the new size position
-                LARGE_INTEGER new_size{.QuadPart = static_cast<LONGLONG>(backing_length)};
-                if (!SetFilePointerEx(backing_fh, new_size, nullptr, FILE_BEGIN)) {
-                    throw std::system_error{static_cast<int>(GetLastError()), std::system_category(),
-                        "unable to seek backing file '"s + backing_filename + "'"s};
-                }
-
-                // Set the end of file at the current position
-                if (!SetEndOfFile(backing_fh)) {
-                    throw std::system_error{static_cast<int>(GetLastError()), std::system_category(),
-                        "unable to truncate backing file '"s + backing_filename + "'"s};
-                }
-
-                // Initialize truncated bytes to zeros
-                if (backing_length > backing_file_length) {
-                    // Set file pointer to truncate position
-                    LARGE_INTEGER truncate_pos{.QuadPart = static_cast<LONGLONG>(backing_file_length)};
-                    if (!SetFilePointerEx(backing_fh, truncate_pos, nullptr, FILE_BEGIN)) {
-                        throw std::system_error{static_cast<int>(GetLastError()), std::system_category(),
-                            "unable to seek backing file '"s + backing_filename + "'"s};
-                    }
-
-                    // Write zeros in chunks
-                    static uint8_t zero_buffer[65536]{};
-                    uint64_t remaining = backing_length - backing_file_length;
-                    while (remaining > 0) {
-                        const auto write_size = static_cast<DWORD>(std::min<uint64_t>(remaining, sizeof(zero_buffer)));
-                        DWORD bytes_written = 0;
-                        if (!WriteFile(backing_fh, zero_buffer, write_size, &bytes_written, nullptr) ||
-                            bytes_written != write_size) {
-                            throw std::system_error{static_cast<int>(GetLastError()), std::system_category(),
-                                "unable to write backing file '"s + backing_filename + "'"s};
-                        }
-                        remaining -= bytes_written;
-                    }
-                }
-
-                // Flush file changes
-                if (!FlushFileBuffers(backing_fh)) {
-                    throw std::system_error{static_cast<int>(GetLastError()), std::system_category(),
-                        "unable to flush backing file '"s + backing_filename + "'"s};
-                }
 
                 backing_file_length = backing_length;
-            } else {
-                // Backing file length may be less than desired backing length,
-                // but this is fine, as we are not sharing the file.
-                // The gap between the file length and the memory length will be allocated as anonymous memory.
             }
+            // Backing file length may be less than desired backing length,
+            // but this is fine, as we are not sharing the file.
+            // The gap between the file length and the memory length will be allocated as anonymous memory.
         }
     }
 
@@ -446,12 +369,12 @@ os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string
 
     return os_mmapd{.host_memory = host_memory,
         .length = length,
+        .flags = flags,
         .backing_sync_length = shared_write ? backing_length : 0,
         .memory_mapping = static_cast<void *>(memory_mapping),
         .backing_host_memory = backing_host_memory,
         .backing_mapping = backing_mapping,
-        .backing_fh = static_cast<void *>(backing_fh),
-        .backing_lock = flags.lock};
+        .backing_fh = static_cast<void *>(backing_fh)};
 
 #else  // Fallback implementation using standard C APIs
     // Over-allocate to ensure we can align the pointer and store the original pointer.
@@ -480,10 +403,6 @@ os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string
         if (backing_fp != nullptr) {
             // Close backing file
             std::ignore = std::fclose(backing_fp);
-            // Remove backing file in case it was created
-            if (flags.create) {
-                std::ignore = std::remove(backing_filename.c_str());
-            }
         }
     });
 
@@ -491,16 +410,7 @@ os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string
     if (!backing_filename.empty()) {
         // Determine backing file open flags
         const char *mode{};
-        if (flags.create) {
-            // Check if file already exists first
-            auto *fp = std::fopen(backing_filename.c_str(), "rb");
-            if (fp != nullptr) {
-                std::ignore = std::fclose(fp);
-                throw std::system_error{errno, std::generic_category(),
-                    "unable to create backing file '"s + backing_filename + "': file already exists"s};
-            }
-            mode = "w+b";
-        } else if (shared_write) {
+        if (shared_write) {
             mode = "r+b";
         } else {
             mode = "rb";
@@ -536,38 +446,16 @@ os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string
                 "unable to read from backing file '"s + backing_filename + "'"s};
         }
 
-        // When backing file length mismatch the desired backing length we may need to truncate
+        // Check backing file length mismatch
         if (backing_file_length != backing_length) {
-            if (!(flags.truncate || flags.create)) { // Can we truncate?
+            if (flags.shared) {
                 throw std::runtime_error{"backing file '"s + backing_filename + "' length ("s +
                     std::to_string(backing_file_length) + ") does not match desired backing length ("s +
                     std::to_string(backing_length) + ")"s};
             }
-            if (flags.shared) { // Truncate backing file to match the desired length
-                // In order to truncate the file using standard C API,
-                // we need recreate from scratch and copy over the existing content.
-                if (std::fclose(backing_fp) != 0) {
-                    throw std::system_error{errno, std::generic_category(),
-                        "unable to truncate backing file '"s + backing_filename + "': fclose() failed"s};
-                }
-                backing_fp = std::fopen(backing_filename.c_str(), "w+b");
-                if (backing_fp == nullptr) {
-                    throw std::system_error{errno, std::generic_category(),
-                        "unable to truncate backing file '"s + backing_filename + "': fopen() failed"s};
-                }
-                if (static_cast<uint64_t>(std::fwrite(host_memory, 1, backing_length, backing_fp)) != backing_length) {
-                    throw std::system_error{errno, std::generic_category(),
-                        "unable to truncate backing file '"s + backing_filename + "': fwrite() failed"s};
-                }
-                if (std::fflush(backing_fp) != 0) {
-                    throw std::system_error{errno, std::generic_category(),
-                        "unable to truncate backing file '"s + backing_filename + "': fflush() failed"s};
-                }
-            } else {
-                // Backing file length may be less than desired backing length,
-                // but this is fine, as we are not sharing the file.
-                // The gap between the file length and the memory length will be allocated as anonymous memory.
-            }
+            // Backing file length may be less than desired backing length,
+            // but this is fine, as we are not sharing the file.
+            // The gap between the file length and the memory length will be allocated as anonymous memory.
         }
 
         // Rewind the backing file to the beginning
@@ -579,6 +467,7 @@ os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string
 
     return os_mmapd{.host_memory = host_memory,
         .length = length,
+        .flags = flags,
         .backing_sync_length = shared_write ? backing_length : 0,
         .backing_fp = backing_fp,
         .unaligned_host_memory = unaligned_host_memory};
@@ -588,30 +477,29 @@ os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string
 void os_munmap(const os_mmapd &mmapd) noexcept {
 #ifdef HAVE_MMAP
     if (mmapd.host_memory != nullptr && mmapd.length > 0) {
+        // Asynchronously flush mapped memory to disk to help prevent data loss
         if (mmapd.backing_sync_length > 0) {
-            // Request the kernel to flush the mapped file to disk asynchronously.
-            // This may reduce the risk of file corruption in the event of unexpected host power loss.
             std::ignore = msync(mmapd.host_memory, mmapd.backing_sync_length, MS_ASYNC);
         }
         std::ignore = munmap(mmapd.host_memory, mmapd.length);
     }
     if (mmapd.backing_fd != -1) {
         // Closing a file will also release file locks
-        std::ignore = close(mmapd.backing_fd);
+        while (close(mmapd.backing_fd) != 0 && errno == EINTR) {
+            // Interrupted by signal, retry
+        };
     }
 
 #elif defined(_WIN32) // Windows implementation
     // Flush changes to disk if necessary
     if (mmapd.backing_sync_length > 0 && mmapd.host_memory != nullptr) {
-        if (mmapd.backing_host_memory != nullptr) { // Copy contents to the backing file
+        // Asynchronously flush mapped memory to disk to help prevent data loss
+        if (mmapd.backing_host_memory != nullptr) {
             std::memcpy(mmapd.backing_host_memory, mmapd.host_memory, mmapd.backing_sync_length);
             std::ignore = FlushViewOfFile(mmapd.backing_host_memory, mmapd.backing_sync_length);
         } else {
             std::ignore = FlushViewOfFile(mmapd.host_memory, mmapd.backing_sync_length);
         }
-        if (mmapd.backing_fh != nullptr && mmapd.backing_fh != INVALID_HANDLE_VALUE) {
-            std::ignore = FlushFileBuffers(mmapd.backing_fh);
-        }
     }
     if (mmapd.host_memory != nullptr) {
         std::ignore = UnmapViewOfFile(mmapd.host_memory);
@@ -626,10 +514,8 @@ void os_munmap(const os_mmapd &mmapd) noexcept {
         std::ignore = CloseHandle(static_cast<HANDLE>(mmapd.backing_mapping));
     }
     if (mmapd.backing_fh != nullptr && mmapd.backing_fh != INVALID_HANDLE_VALUE) {
-        if (mmapd.backing_lock) {
-            OVERLAPPED overlapped{};
-            std::ignore = UnlockFileEx(static_cast<HANDLE>(mmapd.backing_fh), 0, MAXDWORD, MAXDWORD, &overlapped);
-        }
+        OVERLAPPED overlapped{};
+        std::ignore = UnlockFileEx(static_cast<HANDLE>(mmapd.backing_fh), 0, MAXDWORD, MAXDWORD, &overlapped);
         std::ignore = CloseHandle(static_cast<HANDLE>(mmapd.backing_fh));
     }
 
@@ -637,7 +523,6 @@ void os_munmap(const os_mmapd &mmapd) noexcept {
     if (mmapd.backing_sync_length > 0 && mmapd.host_memory != nullptr && mmapd.backing_fp != nullptr) {
         // Write back changes to backing file
         std::ignore = std::fwrite(mmapd.host_memory, 1, mmapd.backing_sync_length, mmapd.backing_fp);
-        std::ignore = std::fflush(mmapd.backing_fp);
     }
     if (mmapd.unaligned_host_memory != nullptr) {
         std::free(mmapd.unaligned_host_memory); // NOLINT(cppcoreguidelines-no-malloc,hicpp-no-malloc)
diff --git a/src/os-mmap.h b/src/os-mmap.h
index 0f9f4542d..53bf02fda 100644
--- a/src/os-mmap.h
+++ b/src/os-mmap.h
@@ -32,7 +32,7 @@
 /// - Cross-platform compatibility with platform-specific optimizations.
 ///
 /// This module is designed to handle complex memory mapping scenarios, such as partial file
-/// mappings, file truncation, and synchronization of file-backed memory regions.
+/// mappings, and synchronization of file-backed memory regions.
 /// \}
 
 #include <cstdint>
@@ -49,17 +49,16 @@ namespace cartesi {
 
 /// \brief Flags for memory mapping operations.
 struct os_mmap_flags {
-    bool read_only{false}; ///< Mark mapped memory as read-only
-    bool shared{false};    ///< Share mapped memory with the backing file
-    bool create{false};    ///< Create the backing file (requires shared to be true)
-    bool truncate{false};  ///< Truncate backing file to match the specified backing file length
-    bool lock{false};      ///< Lock the backing file for exclusive writing when shared, otherwise for shared reading
+    bool read_only{false};  ///< Mark mapped memory as read-only
+    bool shared{false};     ///< Share mapped memory with the backing file
+    bool no_reserve{false}; ///< Do not reserve sawp memory for the mapping
 };
 
 /// \brief Structure representing a memory-mapped region.
 struct os_mmapd {
     void *host_memory{nullptr};      ///< Pointer to the mapped memory region
     uint64_t length{0};              ///< The total size of the mapped memory
+    os_mmap_flags flags;             ///< Flags used for the mapping
     uint64_t backing_sync_length{0}; ///< Length of file-backed portion for which memory sync is needed
 #ifdef HAVE_MMAP
     int backing_fd{-1}; ///< File descriptor of the backing file
@@ -68,7 +67,6 @@ struct os_mmapd {
     void *backing_host_memory{nullptr}; ///< Pointer to the backing file mapped memory region
     void *backing_mapping{nullptr};     ///< Handle of the backing file mapping
     void *backing_fh{nullptr};          ///< Handle of the backing file
-    bool backing_lock{false};           ///< Whether the backing file was locked
 #else
     FILE *backing_fp{nullptr};            ///< Pointer of the backing file
     void *unaligned_host_memory{nullptr}; ///< Pointer to the memory that we can deallocate with std::free()
@@ -82,8 +80,8 @@ uint64_t os_get_mmap_page_size();
 /// \brief Maps a memory region, optionally backed by a file.
 /// \param length Total memory length to map.
 /// \param flags Flags for the mapping.
-/// \param backing_filename Path to the file to back the memory mapping (if empty, creates anonymous mapping).
-/// \param backing_length The expected or intended size of the backing file in bytes (must be <= length).
+/// \param backing_filename Path to the file to back the memory mapping.
+/// \param backing_length The expected size of the backing file in bytes (must be <= length).
 /// \returns Structure containing the memory mapping information.
 /// \details The memory is guaranteed to be aligned to 4096-byte boundaries.
 /// Memory above backing file length are zereod, and modifications to that region are not written out to the file.
diff --git a/src/os-posix-compat.h b/src/os-posix-compat.h
new file mode 100644
index 000000000..f4b00c53f
--- /dev/null
+++ b/src/os-posix-compat.h
@@ -0,0 +1,182 @@
+#ifndef OS_POSIX_COMPAT_H
+#define OS_POSIX_COMPAT_H
+
+#ifdef _WIN32
+
+#ifndef WIN32_LEAN_AND_MEAN
+#define WIN32_LEAN_AND_MEAN
+#endif
+#ifndef _CRT_SECURE_NO_WARNINGS
+#define _CRT_SECURE_NO_WARNINGS
+#endif
+
+#include <windows.h>
+
+#include <direct.h> // mkdir
+#include <io.h>     // _write/_close
+#include <sys/stat.h>
+
+#include <cstddef>
+#include <cstdint>
+#include <cstdio>
+
+#ifndef STDOUT_FILENO
+#define STDOUT_FILENO 0
+#endif
+
+#define UTIME_NOW -1
+#define UTIME_OMIT -2
+
+#ifdef mkdir
+#undef mkdir
+#endif
+
+#ifndef write
+#define write _write
+#endif
+
+#ifndef read
+#define read _read
+#endif
+
+#define lstat stat
+
+[[maybe_unused]] static int fsync(int fd) {
+    HANDLE h = (HANDLE) _get_osfhandle(fd);
+    if (h == INVALID_HANDLE_VALUE) {
+        errno = EBADF;
+        return -1;
+    }
+    if (!FlushFileBuffers(h)) {
+        errno = GetLastError();
+        return -1;
+    }
+    return 0;
+}
+
+[[maybe_unused]] static ssize_t pread(int fd, void *buf, size_t count, uint64_t offset) {
+    HANDLE hFile = (HANDLE) _get_osfhandle(fd);
+    DWORD dwBytesRead = 0;
+    OVERLAPPED ovl{};
+    ovl.Offset = (DWORD) offset;
+    ovl.OffsetHigh = (DWORD) (offset >> 32);
+    SetLastError(0);
+    if (!ReadFile(hFile, buf, (DWORD) count, &dwBytesRead, &ovl) && GetLastError() != ERROR_HANDLE_EOF) {
+        errno = GetLastError();
+        return -1;
+    }
+    return dwBytesRead;
+}
+
+[[maybe_unused]] static ssize_t pwrite(int fd, const void *buf, size_t count, uint64_t offset) {
+    HANDLE hFile = (HANDLE) _get_osfhandle(fd);
+    DWORD dwBytesWritten = 0;
+    OVERLAPPED ovl{};
+    ovl.Offset = (DWORD) offset;
+    ovl.OffsetHigh = (DWORD) (offset >> 32);
+    SetLastError(0);
+    if (!WriteFile(hFile, buf, (DWORD) count, &dwBytesWritten, &ovl) && GetLastError() != ERROR_HANDLE_EOF) {
+        errno = GetLastError();
+        return -1;
+    }
+    return dwBytesWritten;
+}
+
+[[maybe_unused]] static int futimens(int fd, const struct timespec times[2]) {
+    HANDLE hFile = (HANDLE) _get_osfhandle(fd);
+    if (hFile == INVALID_HANDLE_VALUE) {
+        errno = EBADF;
+        return -1;
+    }
+    FILETIME now{}, aft{}, mft{};
+    FILETIME *pft[2] = {&aft, &mft};
+    GetSystemTimeAsFileTime(&now);
+    if (times) {
+        for (int i = 0; i < 2; ++i) {
+            if (times[i].tv_nsec == UTIME_NOW) {
+                *pft[i] = now;
+            } else if (times[i].tv_nsec == UTIME_OMIT) {
+                pft[i] = NULL;
+            } else if (times[i].tv_nsec >= 0 && times[i].tv_nsec < 1000000000L) {
+                long long winTime = times[i].tv_sec * 10000000LL + times[i].tv_nsec / 100LL + 116444736000000000LL;
+                pft[i]->dwLowDateTime = winTime;
+                pft[i]->dwHighDateTime = winTime >> 32;
+            } else {
+                errno = EINVAL;
+                return -1;
+            }
+        }
+    } else {
+        aft = mft = now;
+    }
+    if (!SetFileTime(hFile, NULL, pft[0], pft[1])) {
+        errno = GetLastError();
+        return -1;
+    }
+    return 0;
+}
+
+[[maybe_unused]] static int link(const char * /*from*/, const char * /*to*/) {
+    errno = ENOTSUP;
+    return -1;
+}
+
+[[maybe_unused]] static int fchmod(int fd, mode_t mode) {
+    // Validate file descriptor
+    if (fd < 0) {
+        errno = EBADF;
+        return -1;
+    }
+
+    // Convert file descriptor to Windows HANDLE
+    HANDLE hFile = (HANDLE) _get_osfhandle(fd);
+    if (hFile == INVALID_HANDLE_VALUE) {
+        errno = EBADF;
+        return -1;
+    }
+
+    // Get file path from handle
+    char filePath[MAX_PATH]{};
+    DWORD pathLen = GetFinalPathNameByHandleA(hFile, filePath, MAX_PATH, FILE_NAME_NORMALIZED);
+    if (pathLen == 0 || pathLen >= MAX_PATH) {
+        errno = (pathLen >= MAX_PATH) ? ENAMETOOLONG : EBADF;
+        return -1;
+    }
+
+    // Get current attributes
+    DWORD attributes = GetFileAttributesA(filePath);
+    if (attributes == INVALID_FILE_ATTRIBUTES) {
+        errno = EBADF;
+        return -1;
+    }
+
+    // Windows can really only represent the write permission as a read-only flag
+    // If any write permission is set, clear the read-only attribute; otherwise, set it
+    if (mode & (S_IWUSR | S_IWGRP | S_IWOTH)) {
+        attributes &= ~FILE_ATTRIBUTE_READONLY;
+    } else {
+        attributes |= FILE_ATTRIBUTE_READONLY;
+    }
+
+    // Apply the new attributes
+    if (!SetFileAttributesA(filePath, attributes)) {
+        errno = EACCES;
+        return -1;
+    }
+
+    return 0;
+}
+
+[[maybe_unused]] static int mkdir(const char *dirname, mode_t /*mode*/) {
+    return _mkdir(dirname);
+}
+
+#endif // _WIN32
+
+#include <fcntl.h>
+
+#ifndef O_BINARY
+#define O_BINARY 0 // NOLINT(cppcoreguidelines-macro-usage)
+#endif
+
+#endif // OS_POSIX_COMPAT_H
diff --git a/src/os.cpp b/src/os.cpp
index 5f509978b..8ed0ec728 100644
--- a/src/os.cpp
+++ b/src/os.cpp
@@ -14,9 +14,13 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#include "os.h"
 #include "os-features.h"
 
+// Must be included first
+#include "os-posix-compat.h"
+
+#include "os.h"
+
 #include <array>
 #include <cerrno>
 #include <chrono>
@@ -37,12 +41,6 @@
 #include <csignal>
 #endif
 
-#ifdef HAVE_THREADS
-#include <future>
-#include <mutex>
-#include <thread>
-#endif
-
 #if defined(HAVE_TTY) || defined(HAVE_TERMIOS) || defined(_WIN32)
 #include <fcntl.h> // open
 #endif
@@ -54,31 +52,8 @@
 #endif
 #endif
 
-#if defined(HAVE_MKDIR) || defined(_WIN32)
-#include <sys/stat.h> // fstat/mkdir
-#endif
-
 #ifdef _WIN32
 
-#ifndef WIN32_LEAN_AND_MEAN
-#define WIN32_LEAN_AND_MEAN
-#endif
-
-#ifndef _CRT_SECURE_NO_WARNINGS
-#define _CRT_SECURE_NO_WARNINGS
-#endif
-
-#include <direct.h> // mkdir
-#include <io.h>     // _write/_close
-#include <windows.h>
-
-#ifndef STDOUT_FILENO
-#define STDOUT_FILENO 0
-#endif
-
-#define plat_write _write
-#define plat_mkdir(a, mode) _mkdir(a)
-
 #if defined(HAVE_SELECT)
 #include <winsock2.h> // select
 #endif
@@ -93,9 +68,6 @@
 #include <sys/select.h> // select
 #endif
 
-#define plat_write write
-#define plat_mkdir mkdir
-
 #endif // _WIN32
 
 #include "compiler-defines.h"
@@ -532,7 +504,7 @@ void os_putchar(uint8_t ch) {
     } else {
         // In interactive sessions we want to immediately write the character to stdout,
         // without any buffering.
-        if (plat_write(STDOUT_FILENO, &ch, 1) < 1) {
+        if (write(STDOUT_FILENO, &ch, 1) < 1) {
             ;
         }
     }
@@ -551,14 +523,6 @@ void os_putchars(const uint8_t *data, size_t len) {
     }
 }
 
-int os_mkdir(const char *path, [[maybe_unused]] int mode) {
-#ifdef HAVE_MKDIR
-    return plat_mkdir(path, mode);
-#else
-    return -1;
-#endif // HAVE_MKDIR
-}
-
 int64_t os_now_us() {
     static const std::chrono::time_point<std::chrono::high_resolution_clock> start{
         std::chrono::high_resolution_clock::now()};
@@ -566,42 +530,6 @@ int64_t os_now_us() {
     return static_cast<int64_t>(std::chrono::duration_cast<std::chrono::microseconds>(end - start).count());
 }
 
-uint64_t os_get_concurrency() {
-#ifdef HAVE_THREADS
-    return std::thread::hardware_concurrency();
-#else
-    return 1;
-#endif
-}
-
-bool os_parallel_for(uint64_t n, const std::function<bool(uint64_t j, const parallel_for_mutex &mutex)> &task) {
-#ifdef HAVE_THREADS
-    if (n > 1) {
-        std::mutex mutex;
-        const parallel_for_mutex for_mutex = {.lock = [&] { mutex.lock(); }, .unlock = [&] { mutex.unlock(); }};
-        std::vector<std::future<bool>> futures;
-        futures.reserve(n);
-        for (uint64_t j = 0; j < n; ++j) {
-            futures.emplace_back(std::async(std::launch::async, task, j, for_mutex));
-        }
-        // Check if any thread failed
-        bool succeeded = true;
-        for (auto &f : futures) {
-            succeeded = succeeded && f.get();
-        }
-        // Return overall status
-        return succeeded;
-    }
-#endif
-    // Run without extra threads when concurrency is 1 or as fallback
-    const parallel_for_mutex for_mutex{.lock = [] {}, .unlock = [] {}};
-    bool succeeded = true;
-    for (uint64_t j = 0; j < n; ++j) {
-        succeeded = succeeded && task(j, for_mutex);
-    }
-    return succeeded;
-}
-
 bool os_select_fds(const os_select_before_callback &before_cb, const os_select_after_callback &after_cb,
     uint64_t *timeout_us) {
     // Create empty fd sets
@@ -663,23 +591,4 @@ void os_sleep_us(uint64_t timeout_us) {
 #endif
 }
 
-int64_t os_get_file_length(const char *filename, const char *text) {
-    auto fp = make_unique_fopen(filename, "rb");
-    if (fseek(fp.get(), 0, SEEK_END) != 0) {
-        throw std::system_error{errno, std::generic_category(),
-            "unable to obtain length of file '"s + filename + "' "s + text};
-    }
-    const auto length = ftell(fp.get());
-    if (length < 0) {
-        throw std::system_error{errno, std::generic_category(),
-            "unable to obtain length of file '"s + filename + "' "s + text};
-    }
-    return length;
-}
-
-bool os_file_exists(const char *filename) {
-    struct stat buffer{};
-    return (stat(filename, &buffer) == 0);
-}
-
 } // namespace cartesi
diff --git a/src/os.h b/src/os.h
index d271f609d..c6ecac079 100644
--- a/src/os.h
+++ b/src/os.h
@@ -90,44 +90,9 @@ void os_putchars(const uint8_t *data, size_t len);
 /// \param yes If true, putchar is silenced
 void os_silence_putchar(bool yes);
 
-/// \brief Creates a new directory
-int os_mkdir(const char *path, int mode);
-
 /// \brief Get time elapsed since its first call with microsecond precision
 int64_t os_now_us();
 
-/// \brief Get the number of concurrent threads supported by the OS
-uint64_t os_get_concurrency();
-
-/// \brief Mutex for os_parallel_for()
-struct parallel_for_mutex {
-    std::function<void()> lock;
-    std::function<void()> unlock;
-};
-
-/// \brief Mutex guard for os_parallel_for()
-struct parallel_for_mutex_guard {
-    explicit parallel_for_mutex_guard(const parallel_for_mutex &mutex) : mutex(mutex) {
-        mutex.lock();
-    }
-    ~parallel_for_mutex_guard() {
-        mutex.unlock();
-    }
-
-    parallel_for_mutex_guard() = delete;
-    parallel_for_mutex_guard(const parallel_for_mutex_guard &) = default;
-    parallel_for_mutex_guard(parallel_for_mutex_guard &&) = default;
-    parallel_for_mutex_guard &operator=(const parallel_for_mutex_guard &) = delete;
-    parallel_for_mutex_guard &operator=(parallel_for_mutex_guard &&) = delete;
-
-private:
-    parallel_for_mutex mutex;
-};
-
-/// \brief Runs a for loop in parallel using up to n threads
-/// \return True if all thread tasks succeeded
-bool os_parallel_for(uint64_t n, const std::function<bool(uint64_t j, const parallel_for_mutex &mutex)> &task);
-
 // Callbacks used by os_select_fds().
 using os_select_before_callback = std::function<void(select_fd_sets *fds, uint64_t *timeout_us)>;
 using os_select_after_callback = std::function<bool(int select_ret, select_fd_sets *fds)>;
@@ -146,12 +111,6 @@ void os_disable_sigpipe();
 /// \brief Sleep until timeout_us microseconds elapsed
 void os_sleep_us(uint64_t timeout_us);
 
-/// \brief Get the length of a file
-int64_t os_get_file_length(const char *filename, const char *text = "");
-
-/// \brief Check if a file exists
-bool os_file_exists(const char *filename);
-
 } // namespace cartesi
 
 #endif
diff --git a/src/record-step-state-access.h b/src/record-step-state-access.h
index bedaa7b00..b09c07e5a 100644
--- a/src/record-step-state-access.h
+++ b/src/record-step-state-access.h
@@ -28,6 +28,7 @@
 #include "i-prefer-shadow-state.h"
 #include "i-state-access.h"
 #include "machine.h"
+#include "os-filesystem.h"
 #include "pmas.h"
 #include "shadow-tlb.h"
 #include "unique-c-ptr.h"
@@ -81,7 +82,7 @@ class record_step_state_access :
     /// \param m reference to machine
     /// \details The log file is saved when finish() is called
     record_step_state_access(context &context, machine &m) : m_context(context), m_m(m) {
-        if (os_file_exists(m_context.filename.c_str())) {
+        if (os::exists(m_context.filename)) {
             throw std::runtime_error("file already exists");
         }
     }
diff --git a/src/scope-remove.h b/src/scope-remove.h
new file mode 100644
index 000000000..31e894f5b
--- /dev/null
+++ b/src/scope-remove.h
@@ -0,0 +1,92 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef SCOPE_REMOVE_H
+#define SCOPE_REMOVE_H
+
+#include <exception>
+#include <ranges>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include "os-filesystem.h"
+
+namespace cartesi {
+
+/// \brief A class that manages the removal of files and directories when it goes out of scope.
+class scope_remove {
+public:
+    /// \brief Calls the exit function when the scope is exited when active, then destroys the scope_remove.
+    ~scope_remove() {
+        remove_all();
+    }
+
+    scope_remove() = default;
+    scope_remove(const scope_remove &) = delete;
+    scope_remove &operator=(const scope_remove &) = delete;
+    scope_remove(scope_remove &&) = delete;
+    scope_remove &operator=(scope_remove &&) = delete;
+
+    /// \brief Adds a file to be removed by the scope_remove.
+    /// \param filename The name of the file to add.
+    void add_file(const std::string &filename) {
+        m_filenames.emplace_back(filename);
+    }
+
+    /// \brief Adds a directory to be removed by the scope_remove.
+    /// \param dirname The name of the directory to add.
+    void add_directory(const std::string &dirname) {
+        m_dirnames.emplace_back(dirname);
+    }
+
+    /// \brief Removes all files and directories added to the scope_remove.
+    void remove_all() noexcept {
+        // Remove files in reverse order
+        for (const auto &filename : m_filenames | std::views::reverse) {
+            try {
+                os::remove_file(filename);
+            } catch (...) { // NOLINT(bugprone-empty-catch)
+                // Silent ignore cleanup errors
+            }
+        }
+        m_filenames.clear();
+
+        // Remove directories in reverse order to avoid issues with nested directories
+        for (const auto &dirname : m_dirnames | std::views::reverse) {
+            try {
+                os::remove_directory(dirname);
+            } catch (...) { // NOLINT(bugprone-empty-catch)
+                // Silent ignore cleanup errors
+            }
+        }
+        m_dirnames.clear();
+    }
+
+    /// \brief Retain all files and directories added to the scope_remove, keeping them stored.
+    void retain_all() noexcept {
+        m_filenames.clear();
+        m_dirnames.clear();
+    }
+
+private:
+    std::vector<std::string> m_filenames; ///< List of files to be removed
+    std::vector<std::string> m_dirnames;  ///< List of directories to be removed
+};
+
+}; // namespace cartesi
+
+#endif
diff --git a/src/virtio-p9fs-address-range.cpp b/src/virtio-p9fs-address-range.cpp
index 447317b45..56f582900 100644
--- a/src/virtio-p9fs-address-range.cpp
+++ b/src/virtio-p9fs-address-range.cpp
@@ -32,10 +32,28 @@
 // Enable this define to debug VirtIO Plan 9 filesystem operations
 // #define DEBUG_VIRTIO_P9FS
 
-#include "virtio-p9fs-address-range.h"
-
+#include "os-features.h"
 #ifdef HAVE_POSIX_FS
 
+// Must be included before
+#include "os-posix-compat.h"
+
+#ifdef __APPLE__
+#include <sys/mount.h>
+#include <sys/param.h>
+#elif !defined(_WIN32)
+#include <sys/statfs.h>
+#include <sys/sysmacros.h>
+#endif
+
+#include <dirent.h>
+#include <fcntl.h>
+#include <sys/stat.h>
+#include <sys/types.h>
+#include <unistd.h>
+
+#include "virtio-p9fs-address-range.h"
+
 #include <algorithm>
 #include <array>
 #include <cerrno>
@@ -49,114 +67,10 @@
 #include <tuple>
 #include <utility>
 
-#include <dirent.h>
-#include <fcntl.h>
-#include <sys/stat.h>
-#include <sys/types.h>
-#ifdef __APPLE__
-#include <sys/mount.h>
-#include <sys/param.h>
-#elif defined(_WIN32)
-#define WIN32_LEAN_AND_MEAN
-#include <direct.h>
-#include <sys/utime.h>
-#include <windows.h>
-#else
-#include <sys/statfs.h>
-#include <sys/sysmacros.h>
-#endif
-#include <unistd.h>
-
 #include "i-device-state-access.h"
 #include "virtio-address-range.h"
 #include "virtio-serializer.h"
 
-#ifdef _WIN32
-#define lstat stat
-int fsync(int fd) {
-    HANDLE h = (HANDLE) _get_osfhandle(fd);
-    if (h == INVALID_HANDLE_VALUE) {
-        return -1;
-    }
-    if (!FlushFileBuffers(h)) {
-        return -1;
-    }
-    return 0;
-}
-
-static inline void timespec_to_filetime(const struct timespec tv, FILETIME *ft) {
-    long long winTime = tv.tv_sec * 10000000LL + tv.tv_nsec / 100LL + 116444736000000000LL;
-    ft->dwLowDateTime = winTime;
-    ft->dwHighDateTime = winTime >> 32;
-}
-
-ssize_t pread(int fd, void *buf, size_t count, uint64_t offset) {
-    HANDLE hFile = (HANDLE) _get_osfhandle(fd);
-    DWORD dwBytesRead = 0;
-    OVERLAPPED ovl{};
-    ovl.Offset = (DWORD) offset;
-    ovl.OffsetHigh = (DWORD) (offset >> 32);
-    SetLastError(0);
-    if (!ReadFile(hFile, buf, (DWORD) count, &dwBytesRead, &ovl) && GetLastError() != ERROR_HANDLE_EOF) {
-        errno = GetLastError();
-        return -1;
-    }
-    return dwBytesRead;
-}
-
-ssize_t pwrite(int fd, const void *buf, size_t count, uint64_t offset) {
-    HANDLE hFile = (HANDLE) _get_osfhandle(fd);
-    DWORD dwBytesWritten = 0;
-    OVERLAPPED ovl{};
-    ovl.Offset = (DWORD) offset;
-    ovl.OffsetHigh = (DWORD) (offset >> 32);
-    SetLastError(0);
-    if (!WriteFile(hFile, buf, (DWORD) count, &dwBytesWritten, &ovl) && GetLastError() != ERROR_HANDLE_EOF) {
-        errno = GetLastError();
-        return -1;
-    }
-    return dwBytesWritten;
-}
-
-#define UTIME_NOW -1
-#define UTIME_OMIT -2
-
-static int futimens(int fd, const struct timespec times[2]) {
-    HANDLE hFile = (HANDLE) _get_osfhandle(fd);
-    if (hFile == INVALID_HANDLE_VALUE) {
-        errno = EBADF;
-        return -1;
-    }
-    FILETIME now{}, aft{}, mft{};
-    FILETIME *pft[2] = {&aft, &mft};
-    GetSystemTimeAsFileTime(&now);
-    if (times) {
-        for (int i = 0; i < 2; ++i) {
-            if (times[i].tv_nsec == UTIME_NOW) {
-                *pft[i] = now;
-            } else if (times[i].tv_nsec == UTIME_OMIT) {
-                pft[i] = NULL;
-            } else if (times[i].tv_nsec >= 0 && times[i].tv_nsec < 1000000000L) {
-                long long winTime = times[i].tv_sec * 10000000LL + times[i].tv_nsec / 100LL + 116444736000000000LL;
-                pft[i]->dwLowDateTime = winTime;
-                pft[i]->dwHighDateTime = winTime >> 32;
-            } else {
-                errno = EINVAL;
-                return -1;
-            }
-        }
-    } else {
-        aft = mft = now;
-    }
-    if (!SetFileTime(hFile, NULL, pft[0], pft[1])) {
-        errno = GetLastError();
-        return -1;
-    }
-    return 0;
-}
-
-#endif // _WIN32
-
 namespace cartesi {
 
 // Aliases for struct names that conflicts with function names
@@ -2084,14 +1998,10 @@ bool virtio_p9fs_address_range::op_mkdir(virtq_unserializer &&mmsg, uint16_t tag
     }
     // Create the directory
     const std::string path = join_path_name(dfidp->path, name);
-#ifdef _WIN32
-    if (_mkdir(path.c_str()) != 0) {
-        return send_error(msg, tag, host_errno_to_p9(errno));
-    }
-#else
     if (mkdir(path.c_str(), static_cast<mode_t>(mode)) != 0) {
         return send_error(msg, tag, host_errno_to_p9(errno));
     }
+#ifndef _WIN32
     // If we fail to change ownership, we silent ignore the error
     if (lchown(path.c_str(), static_cast<uid_t>(dfidp->uid), static_cast<gid_t>(gid)) != 0) {
         errno = 0;
diff --git a/tests/misc/test-machine-c-api.cpp b/tests/misc/test-machine-c-api.cpp
index a0840ed93..d8a58dbed 100644
--- a/tests/misc/test-machine-c-api.cpp
+++ b/tests/misc/test-machine-c-api.cpp
@@ -87,15 +87,15 @@ class default_machine_fixture {
 };
 
 BOOST_FIXTURE_TEST_CASE_NOLINT(load_machine_unknown_dir_test, default_machine_fixture) {
-    cm_error error_code = cm_load_new("/unknown_dir", nullptr, &_machine);
+    cm_error error_code = cm_load_new("/unknown_dir", nullptr, CM_SHARING_NONE, &_machine);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_SYSTEM_ERROR);
 
     std::string result = cm_get_last_error_message();
-    BOOST_REQUIRE(result.find("unable to open '/unknown_dir/config.json' for reading") == 0);
+    BOOST_REQUIRE(result.find("unable to read file '/unknown_dir/config.json'") == 0);
 }
 
 BOOST_FIXTURE_TEST_CASE_NOLINT(load_machine_null_path_test, default_machine_fixture) {
-    cm_error error_code = cm_load_new(nullptr, nullptr, &_machine);
+    cm_error error_code = cm_load_new(nullptr, nullptr, CM_SHARING_NONE, &_machine);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 
     std::string result = cm_get_last_error_message();
@@ -103,7 +103,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(load_machine_null_path_test, default_machine_fixt
 }
 
 BOOST_FIXTURE_TEST_CASE_NOLINT(create_machine_null_config_test, default_machine_fixture) {
-    cm_error error_code = cm_create_new(nullptr, nullptr, &_machine);
+    cm_error error_code = cm_create_new(nullptr, nullptr, nullptr, &_machine);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
     std::string result = cm_get_last_error_message();
     std::string origin("invalid machine configuration");
@@ -111,7 +111,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(create_machine_null_config_test, default_machine_
 }
 
 BOOST_FIXTURE_TEST_CASE_NOLINT(create_machine_default_machine_test, default_machine_fixture) {
-    cm_error error_code = cm_create_new(_default_machine_config.c_str(), nullptr, &_machine);
+    cm_error error_code = cm_create_new(_default_machine_config.c_str(), nullptr, nullptr, &_machine);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
     BOOST_REQUIRE_EQUAL(std::string(cm_get_last_error_message()), std::string("RAM length cannot be zero"));
 }
@@ -138,7 +138,7 @@ class incomplete_machine_fixture : public default_machine_fixture {
 
 BOOST_FIXTURE_TEST_CASE_NOLINT(create_machine_null_machine_test, incomplete_machine_fixture) {
     const auto dumped_config = _machine_config.dump();
-    cm_error error_code = cm_create_new(dumped_config.c_str(), nullptr, nullptr);
+    cm_error error_code = cm_create_new(dumped_config.c_str(), nullptr, nullptr, nullptr);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 
     std::string result = cm_get_last_error_message();
@@ -151,7 +151,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_pma_overlapping_test, incomp
         {{"start", 0x7ffffffffff000}, {"length", 0x2000}}};
     const auto dumped_config = _machine_config.dump();
 
-    cm_error error_code = cm_create_new(dumped_config.c_str(), nullptr, &_machine);
+    cm_error error_code = cm_create_new(dumped_config.c_str(), nullptr, nullptr, &_machine);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 
     std::string result = cm_get_last_error_message();
@@ -179,11 +179,12 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_invalid_alignment_test, mach
     _machine_config["flash_drive"][0]["start"] = 0x80000000000000 - 1;
     const auto dumped_config = _machine_config.dump();
 
-    cm_error error_code = cm_create_new(dumped_config.c_str(), nullptr, &_machine);
+    cm_error error_code = cm_create_new(dumped_config.c_str(), nullptr, nullptr, &_machine);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 
     std::string result = cm_get_last_error_message();
-    std::string origin("start of flash drive 0 (0x7fffffffffffff) must be aligned to page boundary (every 4096 bytes)");
+    std::string origin("start of flash drive 0 (0x7fffffffffffff) must be aligned to page boundary (every 4096 bytes) "
+                       "when initializing flash drive 0");
     BOOST_CHECK_EQUAL(origin, result);
 }
 
@@ -192,7 +193,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(replace_memory_range_not_addressable_test, machin
     _machine_config["flash_drive"][0]["length"] = 0x3c00000;
     const auto dumped_config = _machine_config.dump();
 
-    cm_error error_code = cm_create_new(dumped_config.c_str(), nullptr, &_machine);
+    cm_error error_code = cm_create_new(dumped_config.c_str(), nullptr, nullptr, &_machine);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 
     std::string result = cm_get_last_error_message();
@@ -205,7 +206,7 @@ class ordinary_machine_fixture : public incomplete_machine_fixture {
     ordinary_machine_fixture() {
         _machine_dir_path = (std::filesystem::temp_directory_path() / "661b6096c377cdc07756df488059f4407c8f4").string();
         const auto dumped_config = _machine_config.dump();
-        cm_create_new(dumped_config.c_str(), nullptr, &_machine);
+        cm_create_new(dumped_config.c_str(), nullptr, nullptr, &_machine);
     }
     ~ordinary_machine_fixture() {
         std::filesystem::remove_all(_machine_dir_path);
@@ -225,7 +226,7 @@ class ordinary_machine_fixture : public incomplete_machine_fixture {
 class serialized_machine_fixture : public ordinary_machine_fixture {
 public:
     serialized_machine_fixture() : _machine_config_path{std::filesystem::temp_directory_path() / "machine"} {
-        cm_error error_code = cm_store(_machine, _machine_config_path.string().c_str());
+        cm_error error_code = cm_store(_machine, _machine_config_path.string().c_str(), CM_SHARING_ALL);
         BOOST_CHECK_EQUAL(error_code, CM_ERROR_OK);
         BOOST_CHECK_EQUAL(std::string(""), std::string(cm_get_last_error_message()));
     }
@@ -273,7 +274,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(load_machine_invalid_config_version_test, seriali
     expected_err << "expected \"archive_version\" " << v << " (got " << v + 1 << ")";
 
     cm_machine *restored_machine{};
-    cm_error error_code = cm_load_new(_machine_config_path.c_str(), nullptr, &restored_machine);
+    cm_error error_code = cm_load_new(_machine_config_path.c_str(), nullptr, CM_SHARING_NONE, &restored_machine);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_RUNTIME_ERROR);
     BOOST_CHECK_EQUAL(std::string(cm_get_last_error_message()), expected_err.str());
 
@@ -299,7 +300,7 @@ class store_file_fixture : public ordinary_machine_fixture {
 
 BOOST_FIXTURE_TEST_CASE_NOLINT(store_file_creation_test, store_file_fixture) {
     BOOST_REQUIRE(!std::filesystem::exists(_broken_machine_path));
-    cm_error error_code = cm_store(_machine, _broken_machine_path.c_str());
+    cm_error error_code = cm_store(_machine, _broken_machine_path.c_str(), CM_SHARING_ALL);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_OK);
     BOOST_CHECK_EQUAL(std::string(""), std::string(cm_get_last_error_message()));
     BOOST_CHECK(std::filesystem::exists(_broken_machine_path));
@@ -309,7 +310,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(store_file_creation_test, store_file_fixture) {
 BOOST_FIXTURE_TEST_CASE_NOLINT(store_machine_config_version_test, store_file_fixture) {
     // store machine
     BOOST_REQUIRE(!std::filesystem::exists(_broken_machine_path));
-    cm_error error_code = cm_store(_machine, _broken_machine_path.c_str());
+    cm_error error_code = cm_store(_machine, _broken_machine_path.c_str(), CM_SHARING_ALL);
     BOOST_REQUIRE_EQUAL(error_code, CM_ERROR_OK);
     BOOST_REQUIRE_EQUAL(std::string(cm_get_last_error_message()), std::string(""));
     BOOST_REQUIRE(std::filesystem::exists(_broken_machine_path));
@@ -325,33 +326,40 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(store_machine_config_version_test, store_file_fix
 }
 
 BOOST_FIXTURE_TEST_CASE_NOLINT(store_null_machine_test, ordinary_machine_fixture) {
-    cm_error error_code = cm_store(nullptr, _machine_dir_path.c_str());
+    cm_error error_code = cm_store(nullptr, _machine_dir_path.c_str(), CM_SHARING_ALL);
     BOOST_REQUIRE_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
     BOOST_CHECK_EQUAL(std::string("invalid machine"), std::string(cm_get_last_error_message()));
 }
 
 BOOST_FIXTURE_TEST_CASE_NOLINT(store_empty_dir_path_test, ordinary_machine_fixture) {
-    cm_error error_code = cm_store(_machine, "");
+    cm_error error_code = cm_store(_machine, "", CM_SHARING_ALL);
+    BOOST_CHECK_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
+    std::string result = cm_get_last_error_message();
+    BOOST_REQUIRE(result.find("directory name cannot be empty") == 0);
+}
+
+BOOST_FIXTURE_TEST_CASE_NOLINT(store_current_dir_path_test, ordinary_machine_fixture) {
+    cm_error error_code = cm_store(_machine, ".", CM_SHARING_ALL);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_SYSTEM_ERROR);
     std::string result = cm_get_last_error_message();
-    BOOST_REQUIRE(result.find("error creating directory") == 0);
+    BOOST_REQUIRE(result.find("unable to create directory") == 0);
 }
 
 BOOST_FIXTURE_TEST_CASE_NOLINT(load_machine_null_machine_test, ordinary_machine_fixture) {
-    cm_error error_code = cm_store(_machine, _machine_dir_path.c_str());
+    cm_error error_code = cm_store(_machine, _machine_dir_path.c_str(), CM_SHARING_ALL);
     BOOST_REQUIRE_EQUAL(error_code, CM_ERROR_OK);
 
-    error_code = cm_load_new(_machine_dir_path.c_str(), nullptr, nullptr);
+    error_code = cm_load_new(_machine_dir_path.c_str(), nullptr, CM_SHARING_NONE, nullptr);
     BOOST_REQUIRE_EQUAL(error_code, CM_ERROR_INVALID_ARGUMENT);
 }
 
 BOOST_FIXTURE_TEST_CASE_NOLINT(serde_complex_test, ordinary_machine_fixture) {
-    cm_error error_code = cm_store(_machine, _machine_dir_path.c_str());
+    cm_error error_code = cm_store(_machine, _machine_dir_path.c_str(), CM_SHARING_ALL);
     BOOST_REQUIRE_EQUAL(error_code, CM_ERROR_OK);
     BOOST_CHECK_EQUAL(std::string(""), std::string(cm_get_last_error_message()));
 
     cm_machine *restored_machine{};
-    error_code = cm_load_new(_machine_dir_path.c_str(), nullptr, &restored_machine);
+    error_code = cm_load_new(_machine_dir_path.c_str(), nullptr, CM_SHARING_NONE, &restored_machine);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_OK);
     BOOST_CHECK_EQUAL(std::string(""), std::string(cm_get_last_error_message()));
 
@@ -847,7 +855,7 @@ class flash_drive_machine_fixture : public machine_flash_simple_fixture {
         _flash_data{"test data 1234567890"} {
         _machine_dir_path = (std::filesystem::temp_directory_path() / "661b6096c377cdc07756df488059f4407c8f4").string();
         const auto dumped_config = _machine_config.dump();
-        cm_error error_code = cm_create_new(dumped_config.c_str(), nullptr, &_machine);
+        cm_error error_code = cm_create_new(dumped_config.c_str(), nullptr, nullptr, &_machine);
         BOOST_CHECK_EQUAL(error_code, CM_ERROR_OK);
         BOOST_CHECK_EQUAL(std::string(""), std::string(cm_get_last_error_message()));
 
@@ -1117,7 +1125,7 @@ class access_log_machine_fixture : public incomplete_machine_fixture {
         _machine_config["uarch"]["ram"] = {{"backing_store", {{"data_filename", _uarch_ram_path}}}};
         const auto dumped_config = _machine_config.dump();
 
-        cm_create_new(dumped_config.c_str(), nullptr, &_machine);
+        cm_create_new(dumped_config.c_str(), nullptr, nullptr, &_machine);
     }
     ~access_log_machine_fixture() {
         cm_delete(_machine);

From d0bd66fc72972ecd4294d3aefe84d2c892a9d736 Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Wed, 13 Aug 2025 14:40:40 -0300
Subject: [PATCH 56/82] feat!: bump base image to Debian 13 (Trixie)

---
 .dockerignore                         |   2 -
 .github/workflows/build.yml           |   8 +-
 Dockerfile                            |  58 ++-----
 Makefile                              |  18 +--
 README.md                             |   8 +-
 doc/Doxyfile                          |   2 +-
 src/Makefile                          |  13 +-
 src/hash-tree.cpp                     |   5 +-
 tests/Dockerfile                      |   5 +-
 tests/Makefile                        |  18 +--
 tests/lua/cartesi-machine-tests.lua   | 214 +++++++++++++-------------
 third-party/riscv-arch-test           |   2 +-
 third-party/riscv-tests               |   2 +-
 tools/docker-entrypoint.sh            |   2 +-
 tools/template/tests-control.template |   2 +-
 uarch/Makefile                        |   4 +-
 16 files changed, 168 insertions(+), 195 deletions(-)

diff --git a/.dockerignore b/.dockerignore
index 99ea8dfa7..53b9d887b 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -2,8 +2,6 @@
 **/*.a
 **/*.swp
 **/*.d
-**/*.pb.cc
-**/*.pb.h
 **/*.gcno
 **/*.so
 **/*.dtb
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index cd5cc0d41..1b6fae0a7 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -531,6 +531,7 @@ jobs:
             GIT_COMMIT=${GITHUB_SHA}
             DEBUG=yes
             COVERAGE=yes
+            THREADS=no
             MACHINE_EMULATOR_VERSION=${{ env.MACHINE_EMULATOR_VERSION }}
           project: ${{ vars.DEPOT_PROJECT }}
           token: ${{ secrets.DEPOT_TOKEN }}
@@ -548,6 +549,7 @@ jobs:
           build-args: |
             DEBUG=yes
             COVERAGE=yes
+            THREADS=no
             MACHINE_EMULATOR_VERSION=${{ env.MACHINE_EMULATOR_VERSION }}
 
       - name: Run coverage
@@ -571,7 +573,7 @@ jobs:
 
   sanitize:
     name: Sanitize
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
         with:
@@ -630,7 +632,7 @@ jobs:
             SANITIZE=yes
             MACHINE_EMULATOR_VERSION=${{ env.MACHINE_EMULATOR_VERSION }}
 
-      - name: MMAP rnd_bits workaround for the new GitHub ubuntu-22 runner
+      - name: MMAP rnd_bits workaround for the new GitHub Ubuntu runner
         run: sudo sysctl vm.mmap_rnd_bits=28
 
       - name: Run tests with sanitizer
@@ -640,7 +642,7 @@ jobs:
   publish_artifacts:
     name: Publish artifacts
     needs: [build, static-analysis, coverage, sanitize, test_amd64, test_arm64]
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout emulator source code
         uses: actions/checkout@v4
diff --git a/Dockerfile b/Dockerfile
index cbab55718..f12877818 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,35 +1,17 @@
-FROM debian:bookworm-20250407 AS toolchain
+FROM debian:trixie-20250811 AS toolchain
 
 RUN apt-get update && \
     DEBIAN_FRONTEND=noninteractive apt-get install --no-install-recommends -y \
-        build-essential vim wget git lcov \
-        libomp-19-dev libboost1.81-dev libssl-dev libslirp-dev \
+        build-essential vim wget git gcovr \
+        libomp-19-dev libboost1.83-dev libssl-dev libslirp-dev \
         ca-certificates pkg-config lua5.4 liblua5.4-dev \
-        luarocks xxd procps \
-        g++-12-riscv64-linux-gnu=12.2.0-13cross1 \
-        gcc-riscv64-unknown-elf=12.2.0-14+11+b1 && \
+        lua-check lua-socket lua-posix lua-lpeg \
+        xxd procps unzip gosu \
+        clang-tidy clang-format \
+        g++-14-riscv64-linux-gnu=14.2.0-19cross1 \
+        gcc-riscv64-unknown-elf=14.2.0+19 && \
     rm -rf /var/lib/apt/lists/*
 
-# Install clang 19
-RUN apt-get update && \
-    DEBIAN_FRONTEND=noninteractive apt-get install --no-install-recommends -y \
-        wget software-properties-common gnupg && \
-    wget -qO- https://apt.llvm.org/llvm-snapshot.gpg.key | tee /etc/apt/trusted.gpg.d/apt.llvm.org.asc && \
-    add-apt-repository -y 'deb http://apt.llvm.org/bookworm/  llvm-toolchain-bookworm-19 main' && \
-    add-apt-repository -y 'deb http://apt.llvm.org/bookworm/  llvm-toolchain-bookworm-19 main' && \
-    apt-get update && \
-    DEBIAN_FRONTEND=noninteractive apt-get install --no-install-recommends -y \
-        clang-tidy-19 clang-format-19 && \
-    update-alternatives --install /usr/bin/clang-format clang-format /usr/bin/clang-format-19 120 && \
-    update-alternatives --install /usr/bin/clang-tidy clang-tidy /usr/bin/clang-tidy-19 120 && \
-    rm -rf /var/lib/apt/lists/*
-
-# Install lua packages
-RUN luarocks install --lua-version=5.4 luasocket && \
-    luarocks install --lua-version=5.4 luasec && \
-    luarocks install --lua-version=5.4 luaposix && \
-    luarocks install --lua-version=5.4 luacheck
-
 # Install stylua
 RUN cd /tmp && \
     wget https://github.com/JohnnyMorganz/StyLua/releases/download/v0.20.0/stylua-linux-`uname -m`.zip && \
@@ -44,15 +26,6 @@ RUN cd /tmp && \
 # Environment has the riscv64 toolchains
 ENV DEV_ENV_HAS_TOOLCHAIN=yes
 
-# Install su-exec
-RUN cd /tmp && \
-    git clone --branch v0.2 --depth 1 https://github.com/ncopa/su-exec.git && \
-    cd su-exec && \
-    if [ `git rev-parse --verify HEAD` != 'f85e5bde1afef399021fbc2a99c837cf851ceafa' ]; then exit 1; fi && \
-    make && \
-    cp su-exec /usr/local/bin/ && \
-    rm -rf /tmp/su-exec
-
 # Install workaround to run as current user
 COPY tools/docker-entrypoint.sh /usr/local/bin/entrypoint.sh
 RUN chmod +x /usr/local/bin/entrypoint.sh
@@ -69,10 +42,11 @@ FROM toolchain AS builder
 ARG GIT_COMMIT=""
 ARG DEBUG=no
 ARG COVERAGE=no
+ARG THREADS=yes
 ARG SANITIZE=no
 
 COPY . .
-RUN make -j$(nproc) git_commit=$GIT_COMMIT debug=$DEBUG coverage=$COVERAGE sanitize=$SANITIZE
+RUN make -j$(nproc) git_commit=$GIT_COMMIT debug=$DEBUG coverage=$COVERAGE threads=$THREADS sanitize=$SANITIZE
 
 ####################################################################################################
 FROM builder AS debian-packager
@@ -80,21 +54,17 @@ FROM builder AS debian-packager
 RUN make install-uarch debian-package DESTDIR=$PWD/_install
 
 ####################################################################################################
-FROM debian:bookworm-20250407-slim
+FROM debian:trixie-20250811-slim
 ARG TARGETARCH
 
-COPY --from=debian-packager \
-    /usr/src/emulator/machine-emulator_${TARGETARCH}.deb \
-    machine-emulator.deb
-COPY --from=debian-packager /usr/local/lib/lua /usr/local/lib/lua
-COPY --from=debian-packager /usr/local/share/lua /usr/local/share/lua
+COPY --from=debian-packager /usr/src/emulator/machine-emulator_${TARGETARCH}.deb machine-emulator.deb
 
 RUN apt-get update && \
     apt-get install -y ./machine-emulator.deb && \
     rm -rf /var/lib/apt/lists/* /var/cache/apt/* machine-emulator.deb
 
-RUN addgroup --system --gid 102 cartesi && \
-    adduser --system --uid 102 --ingroup cartesi --disabled-login --no-create-home --home /nonexistent --gecos "cartesi user" --shell /bin/false cartesi
+RUN groupadd --system --gid 102 cartesi && \
+    useradd --system --uid 102 --gid 102 --no-create-home --home /nonexistent --comment "cartesi user" --shell /bin/false cartesi
 
 WORKDIR /opt/cartesi
 
diff --git a/Makefile b/Makefile
index 9fe55574a..8404e5596 100644
--- a/Makefile
+++ b/Makefile
@@ -209,10 +209,10 @@ doc:
 bundle-boost: $(DEPDIR)/downloads/boost
 $(DEPDIR)/downloads/boost:
 	mkdir -p $(DOWNLOADDIR)
-	wget -O $(DEPDIR)/downloads/boost_1_81_0.tar.gz https://archives.boost.io/release/1.81.0/source/boost_1_81_0.tar.gz
-	tar -C $(DEPDIR)/downloads -xzf $(DEPDIR)/downloads/boost_1_81_0.tar.gz boost_1_81_0/boost
-	mv $(DEPDIR)/downloads/boost_1_81_0/boost $(DEPDIR)/downloads/boost
-	rm -rf $(DEPDIR)/downloads/boost_1_81_0.tar.gz $(DEPDIR)/downloads/boost_1_81_0
+	wget -O $(DEPDIR)/downloads/boost_1_83_0.tar.gz https://archives.boost.io/release/1.83.0/source/boost_1_83_0.tar.gz
+	tar -C $(DEPDIR)/downloads -xzf $(DEPDIR)/downloads/boost_1_83_0.tar.gz boost_1_83_0/boost
+	mv $(DEPDIR)/downloads/boost_1_83_0/boost $(DEPDIR)/downloads/boost
+	rm -rf $(DEPDIR)/downloads/boost_1_83_0.tar.gz $(DEPDIR)/downloads/boost_1_83_0
 
 submodules:
 	git submodule update --init --recursive
@@ -253,22 +253,22 @@ $(SRCDIR)/interpret-jump-table.h:
 	@eval $$($(MAKE) -s --no-print-directory env); $(MAKE) -C $(SRCDIR) interpret-jump-table.h
 
 build-emulator-builder-image:
-	docker build $(DOCKER_PLATFORM) --build-arg DEBUG=$(debug) --build-arg COVERAGE=$(coverage) --build-arg SANITIZE=$(sanitize) --target builder -t cartesi/machine-emulator:builder -f Dockerfile .
+	docker build $(DOCKER_PLATFORM) --build-arg DEBUG=$(debug) --build-arg COVERAGE=$(coverage) --build-arg THREADS=$(threads) --build-arg SANITIZE=$(sanitize) --target builder -t cartesi/machine-emulator:builder -f Dockerfile .
 
 build-emulator-toolchain-image build-toolchain:
 	docker build $(DOCKER_PLATFORM) --target toolchain -t cartesi/machine-emulator:toolchain -f Dockerfile .
 
 build-emulator-image:
-	docker build $(DOCKER_PLATFORM) --build-arg DEBUG=$(debug) --build-arg COVERAGE=$(coverage) --build-arg SANITIZE=$(sanitize) -t cartesi/machine-emulator:$(TAG) -f Dockerfile .
+	docker build $(DOCKER_PLATFORM) --build-arg DEBUG=$(debug) --build-arg COVERAGE=$(coverage) --build-arg THREADS=$(threads) --build-arg SANITIZE=$(sanitize) -t cartesi/machine-emulator:$(TAG) -f Dockerfile .
 
 build-emulator-tests-image: build-emulator-builder-image build-emulator-image
-	docker build $(DOCKER_PLATFORM) --build-arg DEBUG=$(debug) --build-arg COVERAGE=$(coverage) --build-arg SANITIZE=$(sanitize) --build-arg TAG=$(TAG) -t cartesi/machine-emulator:tests -f tests/Dockerfile .
+	docker build $(DOCKER_PLATFORM) --build-arg DEBUG=$(debug) --build-arg COVERAGE=$(coverage) --build-arg THREADS=$(threads) --build-arg SANITIZE=$(sanitize) --build-arg TAG=$(TAG) -t cartesi/machine-emulator:tests -f tests/Dockerfile .
 
 build-emulator-tests-builder-image: build-emulator-builder-image
-	docker build $(DOCKER_PLATFORM) --target tests-builder --build-arg DEBUG=$(debug) --build-arg COVERAGE=$(coverage) --build-arg SANITIZE=$(sanitize) --build-arg TAG=$(TAG) -t cartesi/machine-emulator:tests-builder -f tests/Dockerfile .
+	docker build $(DOCKER_PLATFORM) --target tests-builder --build-arg DEBUG=$(debug) --build-arg COVERAGE=$(coverage) --build-arg THREADS=$(threads) --build-arg SANITIZE=$(sanitize) --build-arg TAG=$(TAG) -t cartesi/machine-emulator:tests-builder -f tests/Dockerfile .
 
 build-debian-package:
-	docker build $(DOCKER_PLATFORM) --target debian-packager --build-arg DEBUG=$(debug) --build-arg COVERAGE=$(coverage) --build-arg SANITIZE=$(sanitize) -t $(DEBIAN_IMG) -f Dockerfile .
+	docker build $(DOCKER_PLATFORM) --target debian-packager --build-arg DEBUG=$(debug) --build-arg COVERAGE=$(coverage) --build-arg THREADS=$(threads) --build-arg SANITIZE=$(sanitize) -t $(DEBIAN_IMG) -f Dockerfile .
 
 build-tests-debian-packages: build-emulator-builder-image
 	docker build $(DOCKER_PLATFORM) --target tests-debian-packager --build-arg TAG=$(TAG) -t cartesi/machine-emulator:tests-debian-packager -f tests/Dockerfile .
diff --git a/README.md b/README.md
index 5739f7576..53a68fdb6 100644
--- a/README.md
+++ b/README.md
@@ -80,7 +80,7 @@ sudo apt-get update
 sudo apt-get install cartesi-machine
 ```
 
-The packages provided in this APT repository are known to work with **Debian 12** (Bookworm) and **Ubuntu 24.04** (Noble).
+The packages provided in this APT repository are known to work with **Debian 13** (Trixie) and **Ubuntu 24.04** (Noble).
 
 #### Alpine Linux
 
@@ -118,14 +118,14 @@ brew install cartesi-machine
 
 - C++ Compiler with support for C++20 (tested with GCC >= 11.x and Clang >= 14.x).
 - GNU Make >= 3.81
-- Boost >= 1.81
-- Lua >= 5.4.4 (optional, required for scripting support and interactive terminal)
+- Boost >= 1.83
+- Lua >= 5.4.6 (optional, required for scripting support and interactive terminal)
 - Libslirp >= 4.6.0 (optional, required for networking support)
 
 ###### Debian Requirements
 
 ```sh
-sudo apt-get install build-essential git wget libgomp-dev libboost1.81-dev liblua5.4-dev libslirp-dev lua5.4
+sudo apt-get install build-essential git wget libgomp-dev libboost1.83-dev liblua5.4-dev libslirp-dev lua5.4
 ```
 
 ###### MacPorts Requirements
diff --git a/doc/Doxyfile b/doc/Doxyfile
index c7d38e32c..154b51eae 100644
--- a/doc/Doxyfile
+++ b/doc/Doxyfile
@@ -924,7 +924,7 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       = *.pb.*
+EXCLUDE_PATTERNS       =
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
diff --git a/src/Makefile b/src/Makefile
index c76d61c33..0d99c2881 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -196,11 +196,14 @@ export UARCH_DEFS += $(DUMP_DEFS)
 
 # By default we compile in release with debug information,
 # so the emulator is packaged correctly by default.
-ifeq (,$(filter yes,$(relwithdebinfo) $(release) $(debug) $(sanitize)))
+ifeq (,$(filter yes,$(relwithdebinfo) $(release) $(debug) $(coverage) $(sanitize)))
 relwithdebinfo=yes
 endif
 
-ifeq ($(relwithdebinfo),yes)
+ifeq ($(coverage),yes)
+OPTFLAGS+=-Og -g -fno-omit-frame-pointer -fno-dce -fno-inline
+DEFS+=-DCODE_COVERAGE
+else ifeq ($(relwithdebinfo),yes)
 OPTFLAGS+=-O2 -g
 INTERPRET_CXXFLAGS+=-DNDEBUG # disable asserts only for interpret.cpp
 else ifeq ($(release),yes)
@@ -309,6 +312,8 @@ CXXFLAGS+=$(PTHREAD_CFLAGS)
 LDFLAGS+=$(PTHREAD_LDFLAGS)
 else
 DEFS+=-DNO_THREADS
+C_WARNS+=-Wno-unknown-pragmas
+CXX_WARNS+=-Wno-unknown-pragmas
 endif
 
 CXXFLAGS+=$(OPTFLAGS) -std=gnu++20 -fvisibility=hidden -MMD $(PICCFLAGS) $(CC_MARCH) $(INCS) $(GCFLAGS) $(UBCFLAGS) $(DEFS) $(CXX_WARNS)
@@ -319,12 +324,12 @@ ifeq ($(coverage),yes)
 ifeq ($(COVERAGE_TOOLCHAIN),gcc)
 CC=gcc
 CXX=g++
-CXXFLAGS+=-g -Og -fno-dce -fno-inline -DCODE_COVERAGE --coverage
+CXXFLAGS+=--coverage
 LDFLAGS+=--coverage
 else ifeq ($(COVERAGE_TOOLCHAIN),clang)
 CC=clang
 CXX=clang++
-CXXFLAGS+=-g -O0 -DCODE_COVERAGE -fprofile-instr-generate -fcoverage-mapping
+CXXFLAGS+=-fprofile-instr-generate -fcoverage-mapping
 LDFLAGS+=-fprofile-instr-generate -fcoverage-mapping
 else ifneq ($(COVERAGE_TOOLCHAIN),)
 $(error invalid value for COVERAGE_TOOLCHAIN: $(COVERAGE_TOOLCHAIN))
diff --git a/src/hash-tree.cpp b/src/hash-tree.cpp
index 6e3f86ed7..0fa36979b 100644
--- a/src/hash-tree.cpp
+++ b/src/hash-tree.cpp
@@ -219,7 +219,7 @@ bool hash_tree::return_updated_dirty_pages(address_ranges ars, dirty_pages &batc
     const int block_size = std::min(static_cast<int>(variant_hasher{m_hash_function}.get_optimal_lane_count()),
         page_hash_tree_cache::simd_page_hasher<variant_hasher>::QUEUE_MAX_PAGE_COUNT);
     // It's only worth to use multi-threading if we have enough entries to process
-    const int threads =
+    [[maybe_unused]] const int threads =
         (m_concurrency > 1 && batch_size > m_concurrency && batch_size > block_size) ? m_concurrency : 1;
     uint64_t update_failures{0};
     uint64_t word_hits{0};
@@ -380,7 +380,8 @@ void hash_tree::update_and_clear_dense_node_entries(dense_node_entries &batch, i
     const int batch_size = static_cast<int>(batch.size());
     const int block_size = static_cast<int>(variant_hasher{m_hash_function}.get_optimal_lane_count());
     // It's only worth to use multi-threading if we have enough entries to process
-    const int threads = (m_concurrency > 1 && batch_size > m_concurrency * block_size) ? m_concurrency : 1;
+    [[maybe_unused]] const int threads =
+        (m_concurrency > 1 && batch_size > m_concurrency * block_size) ? m_concurrency : 1;
 #pragma omp parallel for schedule(static) if (threads > 1) num_threads(threads)
     for (int block_start = 0; block_start < batch_size; block_start += block_size) {
         variant_hasher h{m_hash_function};
diff --git a/tests/Dockerfile b/tests/Dockerfile
index 55c14cf7e..fe492dbc0 100644
--- a/tests/Dockerfile
+++ b/tests/Dockerfile
@@ -2,10 +2,11 @@ ARG TAG=devel
 FROM cartesi/machine-emulator:builder AS tests-builder
 ARG DEBUG=no
 ARG COVERAGE=no
+ARG THREADS=yes
 ARG SANITIZE=no
 
-RUN make -j$(nproc) build-tests-machine debug=$DEBUG coverage=$COVERAGE sanitize=$SANITIZE
-RUN make -j$(nproc) build-tests-misc build-tests-uarch build-tests-images debug=$DEBUG coverage=$COVERAGE sanitize=$SANITIZE
+RUN make -j$(nproc) build-tests-machine debug=$DEBUG coverage=$COVERAGE threads=$THREADS sanitize=$SANITIZE
+RUN make -j$(nproc) build-tests-misc build-tests-uarch build-tests-images debug=$DEBUG coverage=$COVERAGE threads=$THREADS sanitize=$SANITIZE
 
 ####################################################################################################
 FROM tests-builder AS tests-debian-packager
diff --git a/tests/Makefile b/tests/Makefile
index ba1ed2ced..943e24b66 100644
--- a/tests/Makefile
+++ b/tests/Makefile
@@ -58,10 +58,8 @@ endif
 
 COVERAGE_TOOLCHAIN?=gcc
 COVERAGE_OUTPUT_DIR=$(BUILDDIR)/coverage
-COVERAGE_WORKLOAD=\
-	dhrystone 1000000; \
-	whetstone 10000
-COVERAGE_SOURCES=$(filter-out ../src/%.pb.h, $(wildcard ../src/*.h) $(wildcard ../src/*.cpp))
+COVERAGE_WORKLOAD=stress-ng --cpu 1 --cpu-ops 1
+COVERAGE_SOURCES=$(wildcard ../src/*.h) $(wildcard ../src/*.cpp)
 
 ifeq ($(sanitize),yes)
 ifeq ($(TARGET_OS),Darwin)
@@ -240,14 +238,12 @@ coverage-uarch:
 	$(LUA) ./lua/htif-yield.lua --uarch
 
 ifeq ($(COVERAGE_TOOLCHAIN),gcc)
-LCOV_CONFIG=--rc lcov_branch_coverage=1
+GCOVR_FLAGS=--gcov-ignore-parse-errors
 coverage-report: $(COVERAGE_OUTPUT_DIR)
-	rm -f ../src/*.pb.cc.gcda ../src/*.pb.h.gcda
-	gcov --demangled-names --relative-only --branch-probabilities ../src/*.gcda
-	lcov --capture --directory ../src/ --no-external --exclude '*.pb.*' -o coverage.info $(LCOV_CONFIG) --quiet
-	genhtml --quiet coverage.info --output-directory $(COVERAGE_OUTPUT_DIR)/gcc $(LCOV_CONFIG)
-	lcov --list coverage.info $(LCOV_CONFIG) | tee $(COVERAGE_OUTPUT_DIR)/coverage.txt
-	lcov --summary coverage.info $(LCOV_CONFIG) | tee -a $(COVERAGE_OUTPUT_DIR)/coverage.txt
+	cd ../src && gcov --demangled-names --relative-only --branch-probabilities *.gcda
+	mkdir -p $(COVERAGE_OUTPUT_DIR)/gcc
+	gcovr $(GCOVR_FLAGS) --root ../src --html-details $(COVERAGE_OUTPUT_DIR)/gcc/index.html
+	gcovr $(GCOVR_FLAGS) --print-summary | tee $(COVERAGE_OUTPUT_DIR)/coverage.txt
 else ifeq ($(COVERAGE_TOOLCHAIN),clang)
 coverage-report: $(COVERAGE_OUTPUT_DIR)
 	llvm-profdata merge -sparse $(shell find . -name 'coverage*.profraw') -o coverage.profdata
diff --git a/tests/lua/cartesi-machine-tests.lua b/tests/lua/cartesi-machine-tests.lua
index c23f4c7a6..95baf0318 100755
--- a/tests/lua/cartesi-machine-tests.lua
+++ b/tests/lua/cartesi-machine-tests.lua
@@ -67,25 +67,25 @@ local riscv_tests = {
     { "rv64ua-p-amoxor_d.bin", 102 },
     { "rv64ua-p-amoxor_w.bin", 104 },
     { "rv64ua-p-lrsc.bin", 6276 },
-    { "rv64ua-v-amoadd_d.bin", 12908 },
-    { "rv64ua-v-amoadd_w.bin", 12905 },
-    { "rv64ua-v-amoand_d.bin", 12917 },
-    { "rv64ua-v-amoand_w.bin", 12916 },
-    { "rv64ua-v-amomax_d.bin", 12898 },
-    { "rv64ua-v-amomax_w.bin", 12898 },
-    { "rv64ua-v-amomaxu_d.bin", 12898 },
-    { "rv64ua-v-amomaxu_w.bin", 12898 },
-    { "rv64ua-v-amomin_d.bin", 12898 },
-    { "rv64ua-v-amomin_w.bin", 12898 },
-    { "rv64ua-v-amominu_d.bin", 12904 },
-    { "rv64ua-v-amominu_w.bin", 12904 },
-    { "rv64ua-v-amoor_d.bin", 12897 },
-    { "rv64ua-v-amoor_w.bin", 12897 },
-    { "rv64ua-v-amoswap_d.bin", 12917 },
-    { "rv64ua-v-amoswap_w.bin", 12916 },
-    { "rv64ua-v-amoxor_d.bin", 12900 },
-    { "rv64ua-v-amoxor_w.bin", 12902 },
-    { "rv64ua-v-lrsc.bin", 19074 },
+    { "rv64ua-v-amoadd_d.bin", 12868 },
+    { "rv64ua-v-amoadd_w.bin", 12865 },
+    { "rv64ua-v-amoand_d.bin", 12877 },
+    { "rv64ua-v-amoand_w.bin", 12876 },
+    { "rv64ua-v-amomax_d.bin", 12858 },
+    { "rv64ua-v-amomax_w.bin", 12858 },
+    { "rv64ua-v-amomaxu_d.bin", 12858 },
+    { "rv64ua-v-amomaxu_w.bin", 12858 },
+    { "rv64ua-v-amomin_d.bin", 12858 },
+    { "rv64ua-v-amomin_w.bin", 12858 },
+    { "rv64ua-v-amominu_d.bin", 12864 },
+    { "rv64ua-v-amominu_w.bin", 12864 },
+    { "rv64ua-v-amoor_d.bin", 12857 },
+    { "rv64ua-v-amoor_w.bin", 12857 },
+    { "rv64ua-v-amoswap_d.bin", 12877 },
+    { "rv64ua-v-amoswap_w.bin", 12876 },
+    { "rv64ua-v-amoxor_d.bin", 12860 },
+    { "rv64ua-v-amoxor_w.bin", 12862 },
+    { "rv64ua-v-lrsc.bin", 19034 },
     { "rv64ui-p-add.bin", 505 },
     { "rv64ui-p-addi.bin", 280 },
     { "rv64ui-p-addiw.bin", 277 },
@@ -137,57 +137,57 @@ local riscv_tests = {
     { "rv64ui-p-subw.bin", 492 },
     { "rv64ui-p-xor.bin", 608 },
     { "rv64ui-p-xori.bin", 242 },
-    { "rv64ui-v-add.bin", 7926 },
-    { "rv64ui-v-addi.bin", 7701 },
-    { "rv64ui-v-addiw.bin", 7698 },
-    { "rv64ui-v-addw.bin", 7921 },
-    { "rv64ui-v-and.bin", 8001 },
-    { "rv64ui-v-andi.bin", 7672 },
-    { "rv64ui-v-auipc.bin", 7514 },
-    { "rv64ui-v-beq.bin", 7747 },
-    { "rv64ui-v-bge.bin", 7765 },
-    { "rv64ui-v-bgeu.bin", 7855 },
-    { "rv64ui-v-blt.bin", 7747 },
-    { "rv64ui-v-bltu.bin", 7833 },
-    { "rv64ui-v-bne.bin", 7747 },
-    { "rv64ui-v-fence_i.bin", 13165 },
-    { "rv64ui-v-jal.bin", 7511 },
-    { "rv64ui-v-jalr.bin", 7571 },
-    { "rv64ui-v-lb.bin", 13575 },
-    { "rv64ui-v-lbu.bin", 13575 },
-    { "rv64ui-v-ld.bin", 13757 },
-    { "rv64ui-v-lh.bin", 13591 },
-    { "rv64ui-v-lhu.bin", 13600 },
-    { "rv64ui-v-lui.bin", 7521 },
-    { "rv64ui-v-lw.bin", 13605 },
-    { "rv64ui-v-lwu.bin", 13639 },
-    { "rv64ui-v-or.bin", 8034 },
-    { "rv64ui-v-ori.bin", 7665 },
-    { "rv64ui-v-sb.bin", 13287 },
-    { "rv64ui-v-sd.bin", 19325 },
-    { "rv64ui-v-sh.bin", 13340 },
-    { "rv64ui-v-simple.bin", 7497 },
-    { "rv64ui-v-sll.bin", 7996 },
-    { "rv64ui-v-slli.bin", 7726 },
-    { "rv64ui-v-slliw.bin", 7733 },
-    { "rv64ui-v-sllw.bin", 7996 },
-    { "rv64ui-v-slt.bin", 7915 },
-    { "rv64ui-v-slti.bin", 7693 },
-    { "rv64ui-v-sltiu.bin", 7693 },
-    { "rv64ui-v-sltu.bin", 7932 },
-    { "rv64ui-v-sra.bin", 7968 },
-    { "rv64ui-v-srai.bin", 7714 },
-    { "rv64ui-v-sraiw.bin", 7760 },
-    { "rv64ui-v-sraw.bin", 8008 },
-    { "rv64ui-v-srl.bin", 8010 },
-    { "rv64ui-v-srli.bin", 7735 },
-    { "rv64ui-v-srliw.bin", 7742 },
-    { "rv64ui-v-srlw.bin", 8002 },
-    { "rv64ui-v-sub.bin", 7917 },
-    { "rv64ui-v-subw.bin", 7913 },
-    { "rv64ui-v-sw.bin", 13347 },
-    { "rv64ui-v-xor.bin", 8029 },
-    { "rv64ui-v-xori.bin", 7663 },
+    { "rv64ui-v-add.bin", 7908 },
+    { "rv64ui-v-addi.bin", 7683 },
+    { "rv64ui-v-addiw.bin", 7680 },
+    { "rv64ui-v-addw.bin", 7903 },
+    { "rv64ui-v-and.bin", 7983 },
+    { "rv64ui-v-andi.bin", 7654 },
+    { "rv64ui-v-auipc.bin", 7496 },
+    { "rv64ui-v-beq.bin", 7729 },
+    { "rv64ui-v-bge.bin", 7746 },
+    { "rv64ui-v-bgeu.bin", 7837 },
+    { "rv64ui-v-blt.bin", 7729 },
+    { "rv64ui-v-bltu.bin", 7815 },
+    { "rv64ui-v-bne.bin", 7729 },
+    { "rv64ui-v-fence_i.bin", 13125 },
+    { "rv64ui-v-jal.bin", 7493 },
+    { "rv64ui-v-jalr.bin", 7553 },
+    { "rv64ui-v-lb.bin", 13535 },
+    { "rv64ui-v-lbu.bin", 13535 },
+    { "rv64ui-v-ld.bin", 13717 },
+    { "rv64ui-v-lh.bin", 13551 },
+    { "rv64ui-v-lhu.bin", 13560 },
+    { "rv64ui-v-lui.bin", 7503 },
+    { "rv64ui-v-lw.bin", 13565 },
+    { "rv64ui-v-lwu.bin", 13599 },
+    { "rv64ui-v-or.bin", 8016 },
+    { "rv64ui-v-ori.bin", 7647 },
+    { "rv64ui-v-sb.bin", 13247 },
+    { "rv64ui-v-sd.bin", 19263 },
+    { "rv64ui-v-sh.bin", 13300 },
+    { "rv64ui-v-simple.bin", 7479 },
+    { "rv64ui-v-sll.bin", 13822 },
+    { "rv64ui-v-slli.bin", 7708 },
+    { "rv64ui-v-slliw.bin", 7715 },
+    { "rv64ui-v-sllw.bin", 13822 },
+    { "rv64ui-v-slt.bin", 7897 },
+    { "rv64ui-v-slti.bin", 7675 },
+    { "rv64ui-v-sltiu.bin", 7675 },
+    { "rv64ui-v-sltu.bin", 7914 },
+    { "rv64ui-v-sra.bin", 7950 },
+    { "rv64ui-v-srai.bin", 7696 },
+    { "rv64ui-v-sraiw.bin", 7742 },
+    { "rv64ui-v-sraw.bin", 13834 },
+    { "rv64ui-v-srl.bin", 13836 },
+    { "rv64ui-v-srli.bin", 7717 },
+    { "rv64ui-v-srliw.bin", 7724 },
+    { "rv64ui-v-srlw.bin", 13828 },
+    { "rv64ui-v-sub.bin", 7899 },
+    { "rv64ui-v-subw.bin", 7895 },
+    { "rv64ui-v-sw.bin", 13307 },
+    { "rv64ui-v-xor.bin", 8011 },
+    { "rv64ui-v-xori.bin", 7645 },
     { "rv64um-p-div.bin", 136 },
     { "rv64um-p-divu.bin", 142 },
     { "rv64um-p-divuw.bin", 134 },
@@ -201,22 +201,22 @@ local riscv_tests = {
     { "rv64um-p-remu.bin", 136 },
     { "rv64um-p-remuw.bin", 131 },
     { "rv64um-p-remw.bin", 137 },
-    { "rv64um-v-div.bin", 7557 },
-    { "rv64um-v-divu.bin", 7563 },
-    { "rv64um-v-divuw.bin", 7555 },
-    { "rv64um-v-divw.bin", 7552 },
-    { "rv64um-v-mul.bin", 7916 },
-    { "rv64um-v-mulh.bin", 7924 },
-    { "rv64um-v-mulhsu.bin", 7924 },
-    { "rv64um-v-mulhu.bin", 7956 },
-    { "rv64um-v-mulw.bin", 7855 },
-    { "rv64um-v-rem.bin", 7556 },
-    { "rv64um-v-remu.bin", 7557 },
-    { "rv64um-v-remuw.bin", 7552 },
-    { "rv64um-v-remw.bin", 7558 },
+    { "rv64um-v-div.bin", 7539 },
+    { "rv64um-v-divu.bin", 7545 },
+    { "rv64um-v-divuw.bin", 7537 },
+    { "rv64um-v-divw.bin", 7534 },
+    { "rv64um-v-mul.bin", 7898 },
+    { "rv64um-v-mulh.bin", 7906 },
+    { "rv64um-v-mulhsu.bin", 7906 },
+    { "rv64um-v-mulhu.bin", 7938 },
+    { "rv64um-v-mulw.bin", 7837 },
+    { "rv64um-v-rem.bin", 7538 },
+    { "rv64um-v-remu.bin", 7539 },
+    { "rv64um-v-remuw.bin", 7534 },
+    { "rv64um-v-remw.bin", 7540 },
     -- C extension tests
     { "rv64uc-p-rvc.bin", 295 },
-    { "rv64uc-v-rvc.bin", 18975 },
+    { "rv64uc-v-rvc.bin", 18913 },
     -- float tests
     { "rv64uf-p-fadd.bin", 210 },
     { "rv64uf-p-fclass.bin", 147 },
@@ -229,17 +229,17 @@ local riscv_tests = {
     { "rv64uf-p-ldst.bin", 106 },
     { "rv64uf-p-move.bin", 255 },
     { "rv64uf-p-recoding.bin", 113 },
-    { "rv64uf-v-fadd.bin", 13495 },
-    { "rv64uf-v-fclass.bin", 7566 },
-    { "rv64uf-v-fcmp.bin", 13545 },
-    { "rv64uf-v-fcvt.bin", 13437 },
-    { "rv64uf-v-fcvt_w.bin", 19701 },
-    { "rv64uf-v-fdiv.bin", 13456 },
-    { "rv64uf-v-fmadd.bin", 13521 },
-    { "rv64uf-v-fmin.bin", 13599 },
-    { "rv64uf-v-ldst.bin", 12936 },
-    { "rv64uf-v-move.bin", 7674 },
-    { "rv64uf-v-recoding.bin", 13398 },
+    { "rv64uf-v-fadd.bin", 13455 },
+    { "rv64uf-v-fclass.bin", 7548 },
+    { "rv64uf-v-fcmp.bin", 13505 },
+    { "rv64uf-v-fcvt.bin", 13397 },
+    { "rv64uf-v-fcvt_w.bin", 19639 },
+    { "rv64uf-v-fdiv.bin", 13416 },
+    { "rv64uf-v-fmadd.bin", 13481 },
+    { "rv64uf-v-fmin.bin", 13559 },
+    { "rv64uf-v-ldst.bin", 12896 },
+    { "rv64uf-v-move.bin", 7656 },
+    { "rv64uf-v-recoding.bin", 13358 },
     { "rv64ud-p-fadd.bin", 210 },
     { "rv64ud-p-fclass.bin", 153 },
     { "rv64ud-p-fcmp.bin", 260 },
@@ -252,18 +252,18 @@ local riscv_tests = {
     { "rv64ud-p-move.bin", 1030 },
     { "rv64ud-p-recoding.bin", 138 },
     { "rv64ud-p-structural.bin", 203 },
-    { "rv64ud-v-fadd.bin", 13495 },
-    { "rv64ud-v-fclass.bin", 7572 },
-    { "rv64ud-v-fcmp.bin", 13545 },
-    { "rv64ud-v-fcvt.bin", 13477 },
-    { "rv64ud-v-fcvt_w.bin", 19761 },
-    { "rv64ud-v-fdiv.bin", 13469 },
-    { "rv64ud-v-fmadd.bin", 13521 },
-    { "rv64ud-v-fmin.bin", 13599 },
-    { "rv64ud-v-ldst.bin", 12931 },
-    { "rv64ud-v-move.bin", 14315 },
-    { "rv64ud-v-recoding.bin", 12974 },
-    { "rv64ud-v-structural.bin", 7622 },
+    { "rv64ud-v-fadd.bin", 13455 },
+    { "rv64ud-v-fclass.bin", 7554 },
+    { "rv64ud-v-fcmp.bin", 13505 },
+    { "rv64ud-v-fcvt.bin", 13437 },
+    { "rv64ud-v-fcvt_w.bin", 19699 },
+    { "rv64ud-v-fdiv.bin", 13429 },
+    { "rv64ud-v-fmadd.bin", 13481 },
+    { "rv64ud-v-fmin.bin", 13559 },
+    { "rv64ud-v-ldst.bin", 12891 },
+    { "rv64ud-v-move.bin", 14275 },
+    { "rv64ud-v-recoding.bin", 12934 },
+    { "rv64ud-v-structural.bin", 7604 },
     { "fclass.bin", 453 },
     { "fcvt.bin", 17610 },
     { "fcmp.bin", 46783 },
diff --git a/third-party/riscv-arch-test b/third-party/riscv-arch-test
index c05f9b7d3..8f92acd11 160000
--- a/third-party/riscv-arch-test
+++ b/third-party/riscv-arch-test
@@ -1 +1 @@
-Subproject commit c05f9b7d3cd8b83a7a9c17ea26e570f080dc95fe
+Subproject commit 8f92acd11aa5d59005505ec7a48569c75e128167
diff --git a/third-party/riscv-tests b/third-party/riscv-tests
index 898474875..a64ad67b8 160000
--- a/third-party/riscv-tests
+++ b/third-party/riscv-tests
@@ -1 +1 @@
-Subproject commit 8984748759aed292714efd148026f00923af61ce
+Subproject commit a64ad67b8235c681cd244b087ced36c4d5df3cb9
diff --git a/tools/docker-entrypoint.sh b/tools/docker-entrypoint.sh
index 2c401e674..34385844b 100644
--- a/tools/docker-entrypoint.sh
+++ b/tools/docker-entrypoint.sh
@@ -52,5 +52,5 @@ else
   fi
 
   echo Running as $USERNAME and group $(id -ng $UID)
-  exec /usr/local/bin/su-exec $USERNAME "$@"
+  exec gosu $USERNAME "$@"
 fi
diff --git a/tools/template/tests-control.template b/tools/template/tests-control.template
index bda59b5a9..d580cbd81 100644
--- a/tools/template/tests-control.template
+++ b/tools/template/tests-control.template
@@ -5,7 +5,7 @@ Homepage: https://github.com/cartesi/machine-emulator
 Architecture: ARG_ARCH
 Maintainer: Cartesi Machine Reference Unit
 Provides: cartesi-machine-tests
-Depends: cartesi-machine-emulator (>= ARG_VERSION)
+Depends: cartesi-machine-emulator (>= ARG_VERSION), lua-posix
 Section: devel
 Priority: optional
 Multi-Arch: foreign
diff --git a/uarch/Makefile b/uarch/Makefile
index df8ea33f5..8ba9f6c2b 100644
--- a/uarch/Makefile
+++ b/uarch/Makefile
@@ -3,8 +3,8 @@ TOOLCHAIN_LIBS = -lgcc
 
 ifeq ($(DEV_ENV_HAS_TOOLCHAIN),yes)
 TOOLCHAIN_INCS=\
-	-I/usr/riscv64-linux-gnu/include/c++/12 \
-	-I/usr/riscv64-linux-gnu/include/c++/12/riscv64-linux-gnu \
+	-I/usr/riscv64-linux-gnu/include/c++/14 \
+	-I/usr/riscv64-linux-gnu/include/c++/14/riscv64-linux-gnu \
 	-I/usr/riscv64-linux-gnu/include
 else
 TOOLCHAIN_INCS=

From 11cef25f23471974a86a756624f0451b9d4f9952 Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Wed, 13 Aug 2025 17:16:43 -0300
Subject: [PATCH 57/82] feat!: bump C++ standard to C++23

---
 .clang-format           | 2 +-
 README.md               | 2 +-
 src/Makefile            | 2 +-
 tests/machine/README.md | 2 +-
 tests/misc/Makefile     | 2 +-
 uarch/Makefile          | 4 ++--
 6 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/.clang-format b/.clang-format
index 0255bce9c..555606d8e 100644
--- a/.clang-format
+++ b/.clang-format
@@ -16,4 +16,4 @@ ConstructorInitializerAllOnOneLineOrOnePerLine: true
 IndentCaseLabels: true
 IndentWidth: 4
 SpaceAfterCStyleCast: true
-Standard: c++20
+Standard: Latest
diff --git a/README.md b/README.md
index 53a68fdb6..c2cf67d7b 100644
--- a/README.md
+++ b/README.md
@@ -116,7 +116,7 @@ brew install cartesi-machine
 
 ##### System Requirements
 
-- C++ Compiler with support for C++20 (tested with GCC >= 11.x and Clang >= 14.x).
+- C++ Compiler with support for C++23 (tested with GCC >= 14.x and Clang >= 19.x).
 - GNU Make >= 3.81
 - Boost >= 1.83
 - Lua >= 5.4.6 (optional, required for scripting support and interactive terminal)
diff --git a/src/Makefile b/src/Makefile
index 0d99c2881..2a4ae0df2 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -316,7 +316,7 @@ C_WARNS+=-Wno-unknown-pragmas
 CXX_WARNS+=-Wno-unknown-pragmas
 endif
 
-CXXFLAGS+=$(OPTFLAGS) -std=gnu++20 -fvisibility=hidden -MMD $(PICCFLAGS) $(CC_MARCH) $(INCS) $(GCFLAGS) $(UBCFLAGS) $(DEFS) $(CXX_WARNS)
+CXXFLAGS+=$(OPTFLAGS) -std=gnu++23 -fvisibility=hidden -MMD $(PICCFLAGS) $(CC_MARCH) $(INCS) $(GCFLAGS) $(UBCFLAGS) $(DEFS) $(CXX_WARNS)
 CFLAGS+=$(OPTFLAGS) -std=gnu99 -fvisibility=hidden -MMD $(PICCFLAGS) $(CC_MARCH) $(INCS) $(GCFLAGS) $(UBCFLAGS) $(DEFS) $(C_WARNS)
 LDFLAGS+=$(UBLDFLAGS)
 
diff --git a/tests/machine/README.md b/tests/machine/README.md
index ae338abd2..4d71cd879 100644
--- a/tests/machine/README.md
+++ b/tests/machine/README.md
@@ -6,7 +6,7 @@ The Cartesi Machine Tests is a repository containing RISC-V testing code.
 
 ### Requirements
 
-- RISCV64 C/C++ Compiler with support for C++20 (tested with GCC >= 8+).
+- RISCV64 C/C++ Compiler with support for C++23 (tested with GCC >= 14.x).
 - GNU Make >= 3.81
 
 ### Build
diff --git a/tests/misc/Makefile b/tests/misc/Makefile
index fd886f5bb..309a2f690 100644
--- a/tests/misc/Makefile
+++ b/tests/misc/Makefile
@@ -98,7 +98,7 @@ CLANG_FORMAT_FILES:=$(wildcard *.cpp) $(wildcard *.h)
 INCS=-I../../src -I../../third-party/nlohmann-json -I../../third-party/downloads
 WARNS=-Wall -Wpedantic $(BOOST_INC)
 
-CXXFLAGS+=-O2 -g -std=gnu++20 -fopenmp -fvisibility=hidden $(INCS) $(UBFLAGS) $(WARNS)
+CXXFLAGS+=-O2 -g -std=gnu++23 -fopenmp -fvisibility=hidden $(INCS) $(UBFLAGS) $(WARNS)
 
 ifeq ($(slirp),yes)
 LIBCARTESI_LIBS+=$(SLIRP_LIB)
diff --git a/uarch/Makefile b/uarch/Makefile
index 8ba9f6c2b..74f2d6f2d 100644
--- a/uarch/Makefile
+++ b/uarch/Makefile
@@ -21,7 +21,7 @@ HOST_CXX := g++
 HOST_CC := gcc
 endif
 HOST_CFLAGS := -I$(EMULATOR_SRC_DIR)
-HOST_CXXFLAGS := -std=c++20
+HOST_CXXFLAGS := -std=c++23
 
 CC := $(TOOLCHAIN_PREFIX)gcc
 LD := $(TOOLCHAIN_PREFIX)ld
@@ -58,7 +58,7 @@ CFLAGS := -march=rv64i -mabi=lp64 -Wl,--gc-sections $(OPTFLAGS) $(UBFLAGS) $(WAR
 	$(UARCH_DEFS) \
 	$(TOOLCHAIN_INCS)
 
-CXXFLAGS := -std=c++20 -fno-rtti \
+CXXFLAGS := -std=c++23 -fno-rtti \
 	-fno-threadsafe-statics \
 	-fno-use-cxa-atexit
 

From 44a88e7fbe286ec7caf6d341a9f28bb07e2c3f8e Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Mon, 18 Aug 2025 14:59:59 -0300
Subject: [PATCH 58/82] refactor: bundle third-party pure Lua libraries

---
 src/.styluaignore                        |    1 +
 src/Makefile                             |    2 +-
 src/cartesi/calldata.lua                 |    2 +-
 src/cartesi/third-party/bint.lua         | 1767 ++++++++++++++++++++++
 tests/Makefile                           |    2 +-
 tests/lua/.styluaignore                  |    1 +
 tests/lua/cartesi/third-party/lester.lua |  599 ++++++++
 7 files changed, 2371 insertions(+), 3 deletions(-)
 create mode 100644 src/.styluaignore
 create mode 100644 src/cartesi/third-party/bint.lua
 create mode 100644 tests/lua/.styluaignore
 create mode 100644 tests/lua/cartesi/third-party/lester.lua

diff --git a/src/.styluaignore b/src/.styluaignore
new file mode 100644
index 000000000..67d08e3a1
--- /dev/null
+++ b/src/.styluaignore
@@ -0,0 +1 @@
+cartesi/third-party/*
diff --git a/src/Makefile b/src/Makefile
index 2a4ae0df2..dde671241 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -300,7 +300,7 @@ CLANG_FORMAT_FILES:=$(strip $(CLANG_FORMAT_FILES))
 CLANG_FORMAT_FILES:=$(filter-out $(CLANG_FORMAT_IGNORE_FILES),$(strip $(CLANG_FORMAT_FILES)))
 
 STYLUA=stylua
-STYLUA_FLAGS=--indent-type Spaces --collapse-simple-statement Always
+STYLUA_FLAGS=--indent-type Spaces --collapse-simple-statement Always --respect-ignores
 
 EMPTY:=
 SPACE:=$(EMPTY) $(EMPTY)
diff --git a/src/cartesi/calldata.lua b/src/cartesi/calldata.lua
index 513e8f13d..6c4ebf349 100644
--- a/src/cartesi/calldata.lua
+++ b/src/cartesi/calldata.lua
@@ -16,7 +16,7 @@
 
 local lpeg = require("lpeg")
 local bint_extra = 256
-local bint = require("bint")(256 + bint_extra)
+local bint = require("cartesi.third-party.bint")(256 + bint_extra)
 
 local P, R, S, C, Ct, V, Cmt, Carg = lpeg.P, lpeg.R, lpeg.S, lpeg.C, lpeg.Ct, lpeg.V, lpeg.Cmt, lpeg.Carg
 local cartesi = require("cartesi")
diff --git a/src/cartesi/third-party/bint.lua b/src/cartesi/third-party/bint.lua
new file mode 100644
index 000000000..72ce0ef1f
--- /dev/null
+++ b/src/cartesi/third-party/bint.lua
@@ -0,0 +1,1767 @@
+--[[--
+lua-bint - v0.5.2 - 30/Oct/2024
+Eduardo Bart - edub4rt@gmail.com
+https://github.com/edubart/lua-bint
+
+Small portable arbitrary-precision integer arithmetic library in pure Lua for
+computing with large integers.
+
+Different from most arbitrary-precision integer libraries in pure Lua out there this one
+uses an array of lua integers as underlying data-type in its implementation instead of
+using strings or large tables, this make it efficient for working with fixed width integers
+and to make bitwise operations.
+
+## Design goals
+
+The main design goal of this library is to be small, correct, self contained and use few
+resources while retaining acceptable performance and feature completeness.
+
+The library is designed to follow recent Lua integer semantics, this means that
+integer overflow warps around,
+signed integers are implemented using two-complement arithmetic rules,
+integer division operations rounds towards minus infinity,
+any mixed operations with float numbers promotes the value to a float,
+and the usual division/power operation always promotes to floats.
+
+The library is designed to be possible to work with only unsigned integer arithmetic
+when using the proper methods.
+
+All the lua arithmetic operators (+, -, *, //, /, %) and bitwise operators (&, |, ~, <<, >>)
+are implemented as metamethods.
+
+The integer size must be fixed in advance and the library is designed to be more efficient when
+working with integers of sizes between 64-4096 bits. If you need to work with really huge numbers
+without size restrictions then use another library. This choice has been made to have more efficiency
+in that specific size range.
+
+## Usage
+
+First on you should require the bint file including how many bits the bint module will work with,
+by calling the returned function from the require, for example:
+
+```lua
+local bint = require 'bint'(1024)
+```
+
+For more information about its arguments see @{newmodule}.
+Then when you need create a bint, you can use one of the following functions:
+
+* @{bint.fromuinteger} (convert from lua integers, but read as unsigned integer)
+* @{bint.frominteger} (convert from lua integers, preserving the sign)
+* @{bint.frombase} (convert from arbitrary bases, like hexadecimal)
+* @{bint.fromstring} (convert from arbitrary string, support binary/hexadecimal/decimal)
+* @{bint.trunc} (convert from lua numbers, truncating the fractional part)
+* @{bint.new} (convert from anything, asserts on invalid integers)
+* @{bint.tobint} (convert from anything, returns nil on invalid integers)
+* @{bint.parse} (convert from anything, returns a lua number as fallback)
+* @{bint.zero}
+* @{bint.one}
+* `bint`
+
+You can also call `bint` as it is an alias to `bint.new`.
+In doubt use @{bint.new} to create a new bint.
+
+Then you can use all the usual lua numeric operations on it,
+all the arithmetic metamethods are implemented.
+When you are done computing and need to get the result,
+get the output from one of the following functions:
+
+* @{bint.touinteger} (convert to a lua integer, wraps around as an unsigned integer)
+* @{bint.tointeger} (convert to a lua integer, wraps around, preserves the sign)
+* @{bint.tonumber} (convert to lua float, losing precision)
+* @{bint.tobase} (convert to a string in any base)
+* @{bint.__tostring} (convert to a string in base 10)
+
+To output a very large integer with no loss you probably want to use @{bint.tobase}
+or call `tostring` to get a string representation.
+
+## Precautions
+
+All library functions can be mixed with lua numbers,
+this makes easy to mix operations between bints and lua numbers,
+however the user should take care in some situations:
+
+* Don't mix integers and float operations if you want to work with integers only.
+* Don't use the regular equal operator ('==') to compare values from this library,
+unless you know in advance that both values are of the same primitive type,
+otherwise it will always return false, use @{bint.eq} to be safe.
+* Don't pass fractional numbers to functions that an integer is expected
+* Don't mix operations between bint classes with different sizes as this is not supported, this
+will throw assertions.
+* Remember that casting back to lua integers or numbers precision can be lost.
+* For dividing while preserving integers use the @{bint.__idiv} (the '//' operator).
+* For doing power operation preserving integers use the @{bint.ipow} function.
+* Configure the proper integer size you intend to work with, otherwise large integers may wrap around.
+
+## License
+
+MIT, see end of file.
+
+]]
+
+-- Returns number of bits of the internal lua integer type.
+local function luainteger_bitsize()
+  local n, i = -1, 0
+  repeat
+    n, i = n >> 16, i + 16
+  until n==0
+  return i
+end
+
+local math_type = math.type
+local math_floor = math.floor
+local math_abs = math.abs
+local math_ceil = math.ceil
+local math_modf = math.modf
+local math_mininteger = math.mininteger
+local math_maxinteger = math.maxinteger
+local math_max = math.max
+local math_min = math.min
+local string_format = string.format
+local table_insert = table.insert
+local table_concat = table.concat
+local table_unpack = table.unpack
+
+local memo = {}
+
+--- Create a new bint module representing integers of the desired bit size.
+-- This is the returned function when `require 'bint'` is called.
+-- @function newmodule
+-- @param bits Number of bits for the integer representation, must be multiple of wordbits and
+-- at least 64.
+-- @param[opt] wordbits Number of the bits for the internal word,
+-- defaults to half of Lua's integer size.
+local function newmodule(bits, wordbits)
+
+local intbits = luainteger_bitsize()
+bits = bits or 256
+wordbits = wordbits or (intbits // 2)
+
+-- Memoize bint modules
+local memoindex = bits * 64 + wordbits
+if memo[memoindex] then
+  return memo[memoindex]
+end
+
+-- Validate
+assert(bits % wordbits == 0, 'bitsize is not multiple of word bitsize')
+assert(2*wordbits <= intbits, 'word bitsize must be half of the lua integer bitsize')
+assert(bits >= 64, 'bitsize must be >= 64')
+assert(wordbits >= 8, 'wordbits must be at least 8')
+assert(bits % 8 == 0, 'bitsize must be multiple of 8')
+
+-- Create bint module
+local bint = {}
+bint.__index = bint
+
+--- Number of bits representing a bint instance.
+bint.bits = bits
+
+-- Constants used internally
+local BINT_BITS = bits
+local BINT_BYTES = bits // 8
+local BINT_WORDBITS = wordbits
+local BINT_SIZE = BINT_BITS // BINT_WORDBITS
+local BINT_WORDMAX = (1 << BINT_WORDBITS) - 1
+local BINT_WORDMSB = (1 << (BINT_WORDBITS - 1))
+local BINT_LEPACKFMT = '<'..('I'..(wordbits // 8)):rep(BINT_SIZE)
+local BINT_MATHMININTEGER, BINT_MATHMAXINTEGER
+local BINT_MININTEGER
+
+--- Create a new bint with 0 value.
+function bint.zero()
+  local x = setmetatable({}, bint)
+  for i=1,BINT_SIZE do
+    x[i] = 0
+  end
+  return x
+end
+local bint_zero = bint.zero
+
+--- Create a new bint with 1 value.
+function bint.one()
+  local x = setmetatable({}, bint)
+  x[1] = 1
+  for i=2,BINT_SIZE do
+    x[i] = 0
+  end
+  return x
+end
+local bint_one = bint.one
+
+-- Convert a value to a lua integer without losing precision.
+local function tointeger(x)
+  x = tonumber(x)
+  local ty = math_type(x)
+  if ty == 'float' then
+    local floorx = math_floor(x)
+    if floorx == x then
+      x = floorx
+      ty = math_type(x)
+    end
+  end
+  if ty == 'integer' then
+    return x
+  end
+end
+
+--- Create a bint from an unsigned integer.
+-- Treats signed integers as an unsigned integer.
+-- @param x A value to initialize from convertible to a lua integer.
+-- @return A new bint or nil in case the input cannot be represented by an integer.
+-- @see bint.frominteger
+function bint.fromuinteger(x)
+  x = tointeger(x)
+  if x then
+    if x == 1 then
+      return bint_one()
+    elseif x == 0 then
+      return bint_zero()
+    end
+    local n = setmetatable({}, bint)
+    for i=1,BINT_SIZE do
+      n[i] = x & BINT_WORDMAX
+      x = x >> BINT_WORDBITS
+    end
+    return n
+  end
+end
+local bint_fromuinteger = bint.fromuinteger
+
+--- Create a bint from a signed integer.
+-- @param x A value to initialize from convertible to a lua integer.
+-- @return A new bint or nil in case the input cannot be represented by an integer.
+-- @see bint.fromuinteger
+function bint.frominteger(x)
+  x = tointeger(x)
+  if x then
+    if x == 1 then
+      return bint_one()
+    elseif x == 0 then
+      return bint_zero()
+    end
+    local neg = false
+    if x < 0 then
+      x = math_abs(x)
+      neg = true
+    end
+    local n = setmetatable({}, bint)
+    for i=1,BINT_SIZE do
+      n[i] = x & BINT_WORDMAX
+      x = x >> BINT_WORDBITS
+    end
+    if neg then
+      n:_unm()
+    end
+    return n
+  end
+end
+local bint_frominteger = bint.frominteger
+
+local basesteps = {}
+
+-- Compute the read step for frombase function
+local function getbasestep(base)
+  local step = basesteps[base]
+  if step then
+    return step
+  end
+  step = 0
+  local dmax = 1
+  local limit = math_maxinteger // base
+  repeat
+    step = step + 1
+    dmax = dmax * base
+  until dmax >= limit
+  basesteps[base] = step
+  return step
+end
+
+-- Compute power with lua integers.
+local function ipow(y, x, n)
+  if n == 1 then
+    return y * x
+  elseif n & 1 == 0 then --even
+    return ipow(y, x * x, n // 2)
+  end
+  return ipow(x * y, x * x, (n-1) // 2)
+end
+
+--- Create a bint from a string of the desired base.
+-- @param s The string to be converted from,
+-- must have only alphanumeric and '+-' characters.
+-- @param[opt] base Base that the number is represented, defaults to 10.
+-- Must be at least 2 and at most 36.
+-- @return A new bint or nil in case the conversion failed.
+function bint.frombase(s, base)
+  if type(s) ~= 'string' then
+    return
+  end
+  base = base or 10
+  if not (base >= 2 and base <= 36) then
+    -- number base is too large
+    return
+  end
+  local step = getbasestep(base)
+  if #s < step then
+    -- string is small, use tonumber (faster)
+    return bint_frominteger(tonumber(s, base))
+  end
+  local sign, int = s:lower():match('^([+-]?)(%w+)$')
+  if not (sign and int) then
+    -- invalid integer string representation
+    return
+  end
+  local n = bint_zero()
+  for i=1,#int,step do
+    local part = int:sub(i,i+step-1)
+    local d = tonumber(part, base)
+    if not d then
+      -- invalid integer string representation
+      return
+    end
+    if i > 1 then
+      n = n * ipow(1, base, #part)
+    end
+    if d ~= 0 then
+      n:_add(d)
+    end
+  end
+  if sign == '-' then
+    n:_unm()
+  end
+  return n
+end
+local bint_frombase = bint.frombase
+
+--- Create a new bint from a string.
+-- The string can by a decimal number, binary number prefixed with '0b' or hexadecimal number prefixed with '0x'.
+-- @param s A string convertible to a bint.
+-- @return A new bint or nil in case the conversion failed.
+-- @see bint.frombase
+function bint.fromstring(s)
+  if type(s) ~= 'string' then
+    return
+  end
+  if s:find('^[+-]?[0-9]+$') then
+    return bint_frombase(s, 10)
+  elseif s:find('^[+-]?0[xX][0-9a-fA-F]+$') then
+    return bint_frombase(s:gsub('0[xX]', '', 1), 16)
+  elseif s:find('^[+-]?0[bB][01]+$') then
+    return bint_frombase(s:gsub('0[bB]', '', 1), 2)
+  end
+end
+local bint_fromstring = bint.fromstring
+
+--- Create a new bint from a buffer of little-endian bytes.
+-- @param buffer Buffer of bytes, extra bytes are trimmed from the right, missing bytes are padded to the right.
+-- @raise An assert is thrown in case buffer is not an string.
+-- @return A bint.
+function bint.fromle(buffer)
+  assert(type(buffer) == 'string', 'buffer is not a string')
+  if #buffer > BINT_BYTES then -- trim extra bytes from the right
+    buffer = buffer:sub(1, BINT_BYTES)
+  elseif #buffer < BINT_BYTES then -- add missing bytes to the right
+    buffer = buffer..('\x00'):rep(BINT_BYTES - #buffer)
+  end
+  return setmetatable({BINT_LEPACKFMT:unpack(buffer)}, bint)
+end
+
+--- Create a new bint from a buffer of big-endian bytes.
+-- @param buffer Buffer of bytes, extra bytes are trimmed from the left, missing bytes are padded to the left.
+-- @raise An assert is thrown in case buffer is not an string.
+-- @return A bint.
+function bint.frombe(buffer)
+  assert(type(buffer) == 'string', 'buffer is not a string')
+  if #buffer > BINT_BYTES then -- trim extra bytes from the left
+    buffer = buffer:sub(-BINT_BYTES, #buffer)
+  elseif #buffer < BINT_BYTES then -- add missing bytes to the left
+    buffer = ('\x00'):rep(BINT_BYTES - #buffer)..buffer
+  end
+  return setmetatable({BINT_LEPACKFMT:unpack(buffer:reverse())}, bint)
+end
+
+--- Create a new bint from a value.
+-- @param x A value convertible to a bint (string, number or another bint).
+-- @return A new bint, guaranteed to be a new reference in case needed.
+-- @raise An assert is thrown in case x is not convertible to a bint.
+-- @see bint.tobint
+-- @see bint.parse
+function bint.new(x)
+  if getmetatable(x) ~= bint then
+    local ty = type(x)
+    if ty == 'number' then
+      x = bint_frominteger(x)
+    elseif ty == 'string' then
+      x = bint_fromstring(x)
+    end
+    assert(x, 'value cannot be represented by a bint')
+    return x
+  end
+  -- return a clone
+  local n = setmetatable({}, bint)
+  for i=1,BINT_SIZE do
+    n[i] = x[i]
+  end
+  return n
+end
+local bint_new = bint.new
+
+--- Convert a value to a bint if possible.
+-- @param x A value to be converted (string, number or another bint).
+-- @param[opt] clone A boolean that tells if a new bint reference should be returned.
+-- Defaults to false.
+-- @return A bint or nil in case the conversion failed.
+-- @see bint.new
+-- @see bint.parse
+function bint.tobint(x, clone)
+  if getmetatable(x) == bint then
+    if not clone then
+      return x
+    end
+    -- return a clone
+    local n = setmetatable({}, bint)
+    for i=1,BINT_SIZE do
+      n[i] = x[i]
+    end
+    return n
+  end
+  local ty = type(x)
+  if ty == 'number' then
+    return bint_frominteger(x)
+  elseif ty == 'string' then
+    return bint_fromstring(x)
+  end
+end
+local tobint = bint.tobint
+
+--- Convert a value to a bint if possible otherwise to a lua number.
+-- Useful to prepare values that you are unsure if it's going to be an integer or float.
+-- @param x A value to be converted (string, number or another bint).
+-- @param[opt] clone A boolean that tells if a new bint reference should be returned.
+-- Defaults to false.
+-- @return A bint or a lua number or nil in case the conversion failed.
+-- @see bint.new
+-- @see bint.tobint
+function bint.parse(x, clone)
+  local i = tobint(x, clone)
+  if i then
+    return i
+  end
+  return tonumber(x)
+end
+local bint_parse = bint.parse
+
+--- Convert a bint to an unsigned integer.
+-- Note that large unsigned integers may be represented as negatives in lua integers.
+-- Note that lua cannot represent values larger than 64 bits,
+-- in that case integer values wrap around.
+-- @param x A bint or a number to be converted into an unsigned integer.
+-- @return An integer or nil in case the input cannot be represented by an integer.
+-- @see bint.tointeger
+function bint.touinteger(x)
+  if getmetatable(x) == bint then
+    local n = 0
+    for i=1,BINT_SIZE do
+      n = n | (x[i] << (BINT_WORDBITS * (i - 1)))
+    end
+    return n
+  end
+  return tointeger(x)
+end
+
+--- Convert a bint to a signed integer.
+-- It works by taking absolute values then applying the sign bit in case needed.
+-- Note that lua cannot represent values larger than 64 bits,
+-- in that case integer values wrap around.
+-- @param x A bint or value to be converted into an unsigned integer.
+-- @return An integer or nil in case the input cannot be represented by an integer.
+-- @see bint.touinteger
+function bint.tointeger(x)
+  if getmetatable(x) == bint then
+    local n = 0
+    local neg = x:isneg()
+    if neg then
+      x = -x
+    end
+    for i=1,BINT_SIZE do
+      n = n | (x[i] << (BINT_WORDBITS * (i - 1)))
+    end
+    if neg then
+      n = -n
+    end
+    return n
+  end
+  return tointeger(x)
+end
+local bint_tointeger = bint.tointeger
+
+local function bint_assert_tointeger(x)
+  x = bint_tointeger(x)
+  if not x then
+    error('value has no integer representation')
+  end
+  return x
+end
+
+--- Convert a bint to a lua float in case integer would wrap around or lua integer otherwise.
+-- Different from @{bint.tointeger} the operation does not wrap around integers,
+-- but digits precision are lost in the process of converting to a float.
+-- @param x A bint or value to be converted into a lua number.
+-- @return A lua number or nil in case the input cannot be represented by a number.
+-- @see bint.tointeger
+function bint.tonumber(x)
+  if getmetatable(x) == bint then
+    if x <= BINT_MATHMAXINTEGER and x >= BINT_MATHMININTEGER then
+      return x:tointeger()
+    end
+    return tonumber(tostring(x))
+  end
+  return tonumber(x)
+end
+local bint_tonumber = bint.tonumber
+
+-- Compute base letters to use in bint.tobase
+local BASE_LETTERS = {}
+do
+  for i=1,36 do
+    BASE_LETTERS[i-1] = ('0123456789abcdefghijklmnopqrstuvwxyz'):sub(i,i)
+  end
+end
+
+--- Convert a bint to a string in the desired base.
+-- @param x The bint to be converted from.
+-- @param[opt] base Base to be represented, defaults to 10.
+-- Must be at least 2 and at most 36.
+-- @param[opt] unsigned Whether to output as an unsigned integer.
+-- Defaults to false for base 10 and true for others.
+-- When unsigned is false the symbol '-' is prepended in negative values.
+-- @return A string representing the input.
+-- @raise An assert is thrown in case the base is invalid.
+function bint.tobase(x, base, unsigned)
+  x = tobint(x)
+  if not x then
+    -- x is a fractional float or something else
+    return
+  end
+  base = base or 10
+  if not (base >= 2 and base <= 36) then
+    -- number base is too large
+    return
+  end
+  if unsigned == nil then
+    unsigned = base ~= 10
+  end
+  local isxneg = x:isneg()
+  if (base == 10 and not unsigned) or (base == 16 and unsigned and not isxneg) then
+    if x <= BINT_MATHMAXINTEGER and x >= BINT_MATHMININTEGER then
+      -- integer is small, use tostring or string.format (faster)
+      local n = x:tointeger()
+      if base == 10 then
+        return tostring(n)
+      elseif unsigned then
+        return string_format('%x', n)
+      end
+    end
+  end
+  local ss = {}
+  local neg = not unsigned and isxneg
+  x = neg and x:abs() or bint_new(x)
+  local xiszero = x:iszero()
+  if xiszero then
+    return '0'
+  end
+  -- calculate basepow
+  local step = 0
+  local basepow = 1
+  local limit = (BINT_WORDMSB - 1) // base
+  repeat
+    step = step + 1
+    basepow = basepow * base
+  until basepow >= limit
+  -- serialize base digits
+  local size = BINT_SIZE
+  local xd, carry, d
+  repeat
+    -- single word division
+    carry = 0
+    xiszero = true
+    for i=size,1,-1 do
+      carry = carry | x[i]
+      d, xd = carry // basepow, carry % basepow
+      if xiszero and d ~= 0 then
+        size = i
+        xiszero = false
+      end
+      x[i] = d
+      carry = xd << BINT_WORDBITS
+    end
+    -- digit division
+    for _=1,step do
+      xd, d = xd // base, xd % base
+      if xiszero and xd == 0 and d == 0 then
+        -- stop on leading zeros
+        break
+      end
+      table_insert(ss, 1, BASE_LETTERS[d])
+    end
+  until xiszero
+  if neg then
+    table_insert(ss, 1, '-')
+  end
+  return table_concat(ss)
+end
+
+local function bint_assert_convert(x)
+  return assert(tobint(x), 'value has not integer representation')
+end
+
+--- Convert a bint to a buffer of little-endian bytes.
+-- @param x A bint or lua integer.
+-- @param[opt] trim If true, zero bytes on the right are trimmed.
+-- @return A buffer of bytes representing the input.
+-- @raise Asserts in case input is not convertible to an integer.
+function bint.tole(x, trim)
+  x = bint_assert_convert(x)
+  local s = BINT_LEPACKFMT:pack(table_unpack(x))
+  if trim then
+    s = s:gsub('\x00+$', '')
+    if s == '' then
+      s = '\x00'
+    end
+  end
+  return s
+end
+
+--- Convert a bint to a buffer of big-endian bytes.
+-- @param x A bint or lua integer.
+-- @param[opt] trim If true, zero bytes on the left are trimmed.
+-- @return A buffer of bytes representing the input.
+-- @raise Asserts in case input is not convertible to an integer.
+function bint.tobe(x, trim)
+  x = bint_assert_convert(x)
+  local s = BINT_LEPACKFMT:pack(table_unpack(x)):reverse()
+  if trim then
+    s = s:gsub('^\x00+', '')
+    if s == '' then
+      s = '\x00'
+    end
+  end
+  return s
+end
+
+--- Check if a number is 0 considering bints.
+-- @param x A bint or a lua number.
+function bint.iszero(x)
+  if getmetatable(x) == bint then
+    for i=1,BINT_SIZE do
+      if x[i] ~= 0 then
+        return false
+      end
+    end
+    return true
+  end
+  return x == 0
+end
+
+--- Check if a number is 1 considering bints.
+-- @param x A bint or a lua number.
+function bint.isone(x)
+  if getmetatable(x) == bint then
+    if x[1] ~= 1 then
+      return false
+    end
+    for i=2,BINT_SIZE do
+      if x[i] ~= 0 then
+        return false
+      end
+    end
+    return true
+  end
+  return x == 1
+end
+
+--- Check if a number is -1 considering bints.
+-- @param x A bint or a lua number.
+function bint.isminusone(x)
+  if getmetatable(x) == bint then
+    for i=1,BINT_SIZE do
+      if x[i] ~= BINT_WORDMAX then
+        return false
+      end
+    end
+    return true
+  end
+  return x == -1
+end
+local bint_isminusone = bint.isminusone
+
+--- Check if the input is a bint.
+-- @param x Any lua value.
+function bint.isbint(x)
+  return getmetatable(x) == bint
+end
+
+--- Check if the input is a lua integer or a bint.
+-- @param x Any lua value.
+function bint.isintegral(x)
+  return getmetatable(x) == bint or math_type(x) == 'integer'
+end
+
+--- Check if the input is a bint or a lua number.
+-- @param x Any lua value.
+function bint.isnumeric(x)
+  return getmetatable(x) == bint or type(x) == 'number'
+end
+
+--- Get the number type of the input (bint, integer or float).
+-- @param x Any lua value.
+-- @return Returns "bint" for bints, "integer" for lua integers,
+-- "float" from lua floats or nil otherwise.
+function bint.type(x)
+  if getmetatable(x) == bint then
+    return 'bint'
+  end
+  return math_type(x)
+end
+
+--- Check if a number is negative considering bints.
+-- Zero is guaranteed to never be negative for bints.
+-- @param x A bint or a lua number.
+function bint.isneg(x)
+  if getmetatable(x) == bint then
+    return x[BINT_SIZE] & BINT_WORDMSB ~= 0
+  end
+  return x < 0
+end
+local bint_isneg = bint.isneg
+
+--- Check if a number is positive considering bints.
+-- @param x A bint or a lua number.
+function bint.ispos(x)
+  if getmetatable(x) == bint then
+    return not x:isneg() and not x:iszero()
+  end
+  return x > 0
+end
+
+--- Check if a number is even considering bints.
+-- @param x A bint or a lua number.
+function bint.iseven(x)
+  if getmetatable(x) == bint then
+    return x[1] & 1 == 0
+  end
+  return math_abs(x) % 2 == 0
+end
+
+--- Check if a number is odd considering bints.
+-- @param x A bint or a lua number.
+function bint.isodd(x)
+  if getmetatable(x) == bint then
+    return x[1] & 1 == 1
+  end
+  return math_abs(x) % 2 == 1
+end
+
+--- Create a new bint with the maximum possible integer value.
+function bint.maxinteger()
+  local x = setmetatable({}, bint)
+  for i=1,BINT_SIZE-1 do
+    x[i] = BINT_WORDMAX
+  end
+  x[BINT_SIZE] = BINT_WORDMAX ~ BINT_WORDMSB
+  return x
+end
+
+--- Create a new bint with the minimum possible integer value.
+function bint.mininteger()
+  local x = setmetatable({}, bint)
+  for i=1,BINT_SIZE-1 do
+    x[i] = 0
+  end
+  x[BINT_SIZE] = BINT_WORDMSB
+  return x
+end
+
+--- Bitwise left shift a bint in one bit (in-place).
+function bint:_shlone()
+  local wordbitsm1 = BINT_WORDBITS - 1
+  for i=BINT_SIZE,2,-1 do
+    self[i] = ((self[i] << 1) | (self[i-1] >> wordbitsm1)) & BINT_WORDMAX
+  end
+  self[1] = (self[1] << 1) & BINT_WORDMAX
+  return self
+end
+
+--- Bitwise right shift a bint in one bit (in-place).
+function bint:_shrone()
+  local wordbitsm1 = BINT_WORDBITS - 1
+  for i=1,BINT_SIZE-1 do
+    self[i] = ((self[i] >> 1) | (self[i+1] << wordbitsm1)) & BINT_WORDMAX
+  end
+  self[BINT_SIZE] = self[BINT_SIZE] >> 1
+  return self
+end
+
+-- Bitwise left shift words of a bint (in-place). Used only internally.
+function bint:_shlwords(n)
+  for i=BINT_SIZE,n+1,-1 do
+    self[i] = self[i - n]
+  end
+  for i=1,n do
+    self[i] = 0
+  end
+  return self
+end
+
+-- Bitwise right shift words of a bint (in-place). Used only internally.
+function bint:_shrwords(n)
+  if n < BINT_SIZE then
+    for i=1,BINT_SIZE-n do
+      self[i] = self[i + n]
+    end
+    for i=BINT_SIZE-n+1,BINT_SIZE do
+      self[i] = 0
+    end
+  else
+    for i=1,BINT_SIZE do
+      self[i] = 0
+    end
+  end
+  return self
+end
+
+--- Increment a bint by one (in-place).
+function bint:_inc()
+  for i=1,BINT_SIZE do
+    local tmp = self[i]
+    local v = (tmp + 1) & BINT_WORDMAX
+    self[i] = v
+    if v > tmp then
+      break
+    end
+  end
+  return self
+end
+
+--- Increment a number by one considering bints.
+-- @param x A bint or a lua number to increment.
+function bint.inc(x)
+  local ix = tobint(x, true)
+  if ix then
+    return ix:_inc()
+  end
+  return x + 1
+end
+
+--- Decrement a bint by one (in-place).
+function bint:_dec()
+  for i=1,BINT_SIZE do
+    local tmp = self[i]
+    local v = (tmp - 1) & BINT_WORDMAX
+    self[i] = v
+    if v <= tmp then
+      break
+    end
+  end
+  return self
+end
+
+--- Decrement a number by one considering bints.
+-- @param x A bint or a lua number to decrement.
+function bint.dec(x)
+  local ix = tobint(x, true)
+  if ix then
+    return ix:_dec()
+  end
+  return x - 1
+end
+
+--- Assign a bint to a new value (in-place).
+-- @param y A value to be copied from.
+-- @raise Asserts in case inputs are not convertible to integers.
+function bint:_assign(y)
+  y = bint_assert_convert(y)
+  for i=1,BINT_SIZE do
+    self[i] = y[i]
+  end
+  return self
+end
+
+--- Take absolute of a bint (in-place).
+function bint:_abs()
+  if self:isneg() then
+    self:_unm()
+  end
+  return self
+end
+
+--- Take absolute of a number considering bints.
+-- @param x A bint or a lua number to take the absolute.
+function bint.abs(x)
+  local ix = tobint(x, true)
+  if ix then
+    return ix:_abs()
+  end
+  return math_abs(x)
+end
+local bint_abs = bint.abs
+
+--- Take the floor of a number considering bints.
+-- @param x A bint or a lua number to perform the floor operation.
+function bint.floor(x)
+  if getmetatable(x) == bint then
+    return bint_new(x)
+  end
+  return bint_new(math_floor(tonumber(x)))
+end
+
+--- Take ceil of a number considering bints.
+-- @param x A bint or a lua number to perform the ceil operation.
+function bint.ceil(x)
+  if getmetatable(x) == bint then
+    return bint_new(x)
+  end
+  return bint_new(math_ceil(tonumber(x)))
+end
+
+--- Wrap around bits of an integer (discarding left bits) considering bints.
+-- @param x A bint or a lua integer.
+-- @param y Number of right bits to preserve.
+function bint.bwrap(x, y)
+  x = bint_assert_convert(x)
+  if y <= 0 then
+    return bint_zero()
+  elseif y < BINT_BITS then
+    return x & (bint_one() << y):_dec()
+  end
+  return bint_new(x)
+end
+
+--- Rotate left integer x by y bits considering bints.
+-- @param x A bint or a lua integer.
+-- @param y Number of bits to rotate.
+function bint.brol(x, y)
+  x, y = bint_assert_convert(x), bint_assert_tointeger(y)
+  if y > 0 then
+    return (x << y) | (x >> (BINT_BITS - y))
+  elseif y < 0 then
+    if y ~= math_mininteger then
+      return x:bror(-y)
+    else
+      x:bror(-(y+1))
+      x:bror(1)
+    end
+  end
+  return x
+end
+
+--- Rotate right integer x by y bits considering bints.
+-- @param x A bint or a lua integer.
+-- @param y Number of bits to rotate.
+function bint.bror(x, y)
+  x, y = bint_assert_convert(x), bint_assert_tointeger(y)
+  if y > 0 then
+    return (x >> y) | (x << (BINT_BITS - y))
+  elseif y < 0 then
+    if y ~= math_mininteger then
+      return x:brol(-y)
+    else
+      x:brol(-(y+1))
+      x:brol(1)
+    end
+  end
+  return x
+end
+
+--- Truncate a number to a bint.
+-- Floats numbers are truncated, that is, the fractional port is discarded.
+-- @param x A number to truncate.
+-- @return A new bint or nil in case the input does not fit in a bint or is not a number.
+function bint.trunc(x)
+  if getmetatable(x) ~= bint then
+    x = tonumber(x)
+    if x then
+      local ty = math_type(x)
+      if ty == 'float' then
+        -- truncate to integer
+        x = math_modf(x)
+      end
+      return bint_frominteger(x)
+    end
+    return
+  end
+  return bint_new(x)
+end
+
+--- Take maximum between two numbers considering bints.
+-- @param x A bint or lua number to compare.
+-- @param y A bint or lua number to compare.
+-- @return A bint or a lua number. Guarantees to return a new bint for integer values.
+function bint.max(x, y)
+  local ix, iy = tobint(x), tobint(y)
+  if ix and iy then
+    return bint_new(ix > iy and ix or iy)
+  end
+  return bint_parse(math_max(x, y))
+end
+
+--- Take minimum between two numbers considering bints.
+-- @param x A bint or lua number to compare.
+-- @param y A bint or lua number to compare.
+-- @return A bint or a lua number. Guarantees to return a new bint for integer values.
+function bint.min(x, y)
+  local ix, iy = tobint(x), tobint(y)
+  if ix and iy then
+    return bint_new(ix < iy and ix or iy)
+  end
+  return bint_parse(math_min(x, y))
+end
+
+--- Add an integer to a bint (in-place).
+-- @param y An integer to be added.
+-- @raise Asserts in case inputs are not convertible to integers.
+function bint:_add(y)
+  y = bint_assert_convert(y)
+  local carry = 0
+  for i=1,BINT_SIZE do
+    local tmp = self[i] + y[i] + carry
+    carry = tmp >> BINT_WORDBITS
+    self[i] = tmp & BINT_WORDMAX
+  end
+  return self
+end
+
+--- Add two numbers considering bints.
+-- @param x A bint or a lua number to be added.
+-- @param y A bint or a lua number to be added.
+function bint.__add(x, y)
+  local ix, iy = tobint(x), tobint(y)
+  if ix and iy then
+    local z = setmetatable({}, bint)
+    local carry = 0
+    for i=1,BINT_SIZE do
+      local tmp = ix[i] + iy[i] + carry
+      carry = tmp >> BINT_WORDBITS
+      z[i] = tmp & BINT_WORDMAX
+    end
+    return z
+  end
+  return bint_tonumber(x) + bint_tonumber(y)
+end
+
+--- Subtract an integer from a bint (in-place).
+-- @param y An integer to subtract.
+-- @raise Asserts in case inputs are not convertible to integers.
+function bint:_sub(y)
+  y = bint_assert_convert(y)
+  local borrow = 0
+  local wordmaxp1 = BINT_WORDMAX + 1
+  for i=1,BINT_SIZE do
+    local res = self[i] + wordmaxp1 - y[i] - borrow
+    self[i] = res & BINT_WORDMAX
+    borrow = (res >> BINT_WORDBITS) ~ 1
+  end
+  return self
+end
+
+--- Subtract two numbers considering bints.
+-- @param x A bint or a lua number to be subtracted from.
+-- @param y A bint or a lua number to subtract.
+function bint.__sub(x, y)
+  local ix, iy = tobint(x), tobint(y)
+  if ix and iy then
+    local z = setmetatable({}, bint)
+    local borrow = 0
+    local wordmaxp1 = BINT_WORDMAX + 1
+    for i=1,BINT_SIZE do
+      local res = ix[i] + wordmaxp1 - iy[i] - borrow
+      z[i] = res & BINT_WORDMAX
+      borrow = (res >> BINT_WORDBITS) ~ 1
+    end
+    return z
+  end
+  return bint_tonumber(x) - bint_tonumber(y)
+end
+
+--- Multiply two numbers considering bints.
+-- @param x A bint or a lua number to multiply.
+-- @param y A bint or a lua number to multiply.
+function bint.__mul(x, y)
+  local ix, iy = tobint(x), tobint(y)
+  if ix and iy then
+    local z = bint_zero()
+    local sizep1 = BINT_SIZE+1
+    local s = sizep1
+    local e = 0
+    for i=1,BINT_SIZE do
+      if ix[i] ~= 0 or iy[i] ~= 0 then
+        e = math_max(e, i)
+        s = math_min(s, i)
+      end
+    end
+    for i=s,e do
+      for j=s,math_min(sizep1-i,e) do
+        local a = ix[i] * iy[j]
+        if a ~= 0 then
+          local carry = 0
+          for k=i+j-1,BINT_SIZE do
+            local tmp = z[k] + (a & BINT_WORDMAX) + carry
+            carry = tmp >> BINT_WORDBITS
+            z[k] = tmp & BINT_WORDMAX
+            a = a >> BINT_WORDBITS
+          end
+        end
+      end
+    end
+    return z
+  end
+  return bint_tonumber(x) * bint_tonumber(y)
+end
+
+--- Check if bints are equal.
+-- @param x A bint to compare.
+-- @param y A bint to compare.
+function bint.__eq(x, y)
+  for i=1,BINT_SIZE do
+    if x[i] ~= y[i] then
+      return false
+    end
+  end
+  return true
+end
+
+--- Check if numbers are equal considering bints.
+-- @param x A bint or lua number to compare.
+-- @param y A bint or lua number to compare.
+function bint.eq(x, y)
+  local ix, iy = tobint(x), tobint(y)
+  if ix and iy then
+    return ix == iy
+  end
+  return x == y
+end
+local bint_eq = bint.eq
+
+local function findleftbit(x)
+  for i=BINT_SIZE,1,-1 do
+    local v = x[i]
+    if v ~= 0 then
+      local j = 0
+      repeat
+        v = v >> 1
+        j = j + 1
+      until v == 0
+      return (i-1)*BINT_WORDBITS + j - 1, i
+    end
+  end
+end
+
+-- Single word division modulus
+local function sudivmod(nume, deno)
+  local rema
+  local carry = 0
+  for i=BINT_SIZE,1,-1 do
+    carry = carry | nume[i]
+    nume[i] = carry // deno
+    rema = carry % deno
+    carry = rema << BINT_WORDBITS
+  end
+  return rema
+end
+
+--- Perform unsigned division and modulo operation between two integers considering bints.
+-- This is effectively the same of @{bint.udiv} and @{bint.umod}.
+-- @param x The numerator, must be a bint or a lua integer.
+-- @param y The denominator, must be a bint or a lua integer.
+-- @return The quotient following the remainder, both bints.
+-- @raise Asserts on attempt to divide by zero
+-- or if inputs are not convertible to integers.
+-- @see bint.udiv
+-- @see bint.umod
+function bint.udivmod(x, y)
+  local nume = bint_new(x)
+  local deno = bint_assert_convert(y)
+  -- compute if high bits of denominator are all zeros
+  local ishighzero = true
+  for i=2,BINT_SIZE do
+    if deno[i] ~= 0 then
+      ishighzero = false
+      break
+    end
+  end
+  if ishighzero then
+    -- try to divide by a single word (optimization)
+    local low = deno[1]
+    assert(low ~= 0, 'attempt to divide by zero')
+    if low == 1 then
+      -- denominator is one
+      return nume, bint_zero()
+    elseif low <= (BINT_WORDMSB - 1) then
+      -- can do single word division
+      local rema = sudivmod(nume, low)
+      return nume, bint_fromuinteger(rema)
+    end
+  end
+  if nume:ult(deno) then
+    -- denominator is greater than numerator
+    return bint_zero(), nume
+  end
+  -- align leftmost digits in numerator and denominator
+  local denolbit = findleftbit(deno)
+  local numelbit, numesize = findleftbit(nume)
+  local bit = numelbit - denolbit
+  deno = deno << bit
+  local wordmaxp1 = BINT_WORDMAX + 1
+  local wordbitsm1 = BINT_WORDBITS - 1
+  local denosize = numesize
+  local quot = bint_zero()
+  while bit >= 0 do
+    -- compute denominator <= numerator
+    local le = true
+    local size = math_max(numesize, denosize)
+    for i=size,1,-1 do
+      local a, b = deno[i], nume[i]
+      if a ~= b then
+        le = a < b
+        break
+      end
+    end
+    -- if the portion of the numerator above the denominator is greater or equal than to the denominator
+    if le then
+      -- subtract denominator from the portion of the numerator
+      local borrow = 0
+      for i=1,size do
+        local res = nume[i] + wordmaxp1 - deno[i] - borrow
+        nume[i] = res & BINT_WORDMAX
+        borrow = (res >> BINT_WORDBITS) ~ 1
+      end
+      -- concatenate 1 to the right bit of the quotient
+      local i = (bit // BINT_WORDBITS) + 1
+      quot[i] = quot[i] | (1 << (bit % BINT_WORDBITS))
+    end
+    -- shift right the denominator in one bit
+    for i=1,denosize-1 do
+      deno[i] = ((deno[i] >> 1) | (deno[i+1] << wordbitsm1)) & BINT_WORDMAX
+    end
+    local lastdenoword = deno[denosize] >> 1
+    deno[denosize] = lastdenoword
+    -- recalculate denominator size (optimization)
+    if lastdenoword == 0 then
+      while deno[denosize] == 0 do
+        denosize = denosize - 1
+      end
+      if denosize == 0 then
+        break
+      end
+    end
+    -- decrement current set bit for the quotient
+    bit = bit - 1
+  end
+  -- the remaining numerator is the remainder
+  return quot, nume
+end
+local bint_udivmod = bint.udivmod
+
+--- Perform unsigned division between two integers considering bints.
+-- @param x The numerator, must be a bint or a lua integer.
+-- @param y The denominator, must be a bint or a lua integer.
+-- @return The quotient, a bint.
+-- @raise Asserts on attempt to divide by zero
+-- or if inputs are not convertible to integers.
+function bint.udiv(x, y)
+  return (bint_udivmod(x, y))
+end
+
+--- Perform unsigned integer modulo operation between two integers considering bints.
+-- @param x The numerator, must be a bint or a lua integer.
+-- @param y The denominator, must be a bint or a lua integer.
+-- @return The remainder, a bint.
+-- @raise Asserts on attempt to divide by zero
+-- or if the inputs are not convertible to integers.
+function bint.umod(x, y)
+  local _, rema = bint_udivmod(x, y)
+  return rema
+end
+local bint_umod = bint.umod
+
+--- Perform integer truncate division and modulo operation between two numbers considering bints.
+-- This is effectively the same of @{bint.tdiv} and @{bint.tmod}.
+-- @param x The numerator, a bint or lua number.
+-- @param y The denominator, a bint or lua number.
+-- @return The quotient following the remainder, both bint or lua number.
+-- @raise Asserts on attempt to divide by zero or on division overflow.
+-- @see bint.tdiv
+-- @see bint.tmod
+function bint.tdivmod(x, y)
+  local ax, ay = bint_abs(x), bint_abs(y)
+  local ix, iy = tobint(ax), tobint(ay)
+  local quot, rema
+  if ix and iy then
+    assert(not (bint_eq(x, BINT_MININTEGER) and bint_isminusone(y)), 'division overflow')
+    quot, rema = bint_udivmod(ix, iy)
+  else
+    quot, rema = ax // ay, ax % ay
+  end
+  local isxneg, isyneg = bint_isneg(x), bint_isneg(y)
+  if isxneg ~= isyneg then
+    quot = -quot
+  end
+  if isxneg then
+    rema = -rema
+  end
+  return quot, rema
+end
+local bint_tdivmod = bint.tdivmod
+
+--- Perform truncate division between two numbers considering bints.
+-- Truncate division is a division that rounds the quotient towards zero.
+-- @param x The numerator, a bint or lua number.
+-- @param y The denominator, a bint or lua number.
+-- @return The quotient, a bint or lua number.
+-- @raise Asserts on attempt to divide by zero or on division overflow.
+function bint.tdiv(x, y)
+  return (bint_tdivmod(x, y))
+end
+
+--- Perform integer truncate modulo operation between two numbers considering bints.
+-- The operation is defined as the remainder of the truncate division
+-- (division that rounds the quotient towards zero).
+-- @param x The numerator, a bint or lua number.
+-- @param y The denominator, a bint or lua number.
+-- @return The remainder, a bint or lua number.
+-- @raise Asserts on attempt to divide by zero or on division overflow.
+function bint.tmod(x, y)
+  local _, rema = bint_tdivmod(x, y)
+  return rema
+end
+
+--- Perform integer floor division and modulo operation between two numbers considering bints.
+-- This is effectively the same of @{bint.__idiv} and @{bint.__mod}.
+-- @param x The numerator, a bint or lua number.
+-- @param y The denominator, a bint or lua number.
+-- @return The quotient following the remainder, both bint or lua number.
+-- @raise Asserts on attempt to divide by zero.
+-- @see bint.__idiv
+-- @see bint.__mod
+function bint.idivmod(x, y)
+  local ix, iy = tobint(x), tobint(y)
+  if ix and iy then
+    local isnumeneg = ix[BINT_SIZE] & BINT_WORDMSB ~= 0
+    local isdenoneg = iy[BINT_SIZE] & BINT_WORDMSB ~= 0
+    if isnumeneg then
+      ix = -ix
+    end
+    if isdenoneg then
+      iy = -iy
+    end
+    local quot, rema = bint_udivmod(ix, iy)
+    if isnumeneg ~= isdenoneg then
+      quot:_unm()
+      -- round quotient towards minus infinity
+      if not rema:iszero() then
+        quot:_dec()
+        -- adjust the remainder
+        if isnumeneg and not isdenoneg then
+          rema:_unm():_add(y)
+        elseif isdenoneg and not isnumeneg then
+          rema:_add(y)
+        end
+      end
+    elseif isnumeneg then
+      -- adjust the remainder
+      rema:_unm()
+    end
+    return quot, rema
+  end
+  local nx, ny = bint_tonumber(x), bint_tonumber(y)
+  return nx // ny, nx % ny
+end
+local bint_idivmod = bint.idivmod
+
+--- Perform floor division between two numbers considering bints.
+-- Floor division is a division that rounds the quotient towards minus infinity,
+-- resulting in the floor of the division of its operands.
+-- @param x The numerator, a bint or lua number.
+-- @param y The denominator, a bint or lua number.
+-- @return The quotient, a bint or lua number.
+-- @raise Asserts on attempt to divide by zero.
+function bint.__idiv(x, y)
+  local ix, iy = tobint(x), tobint(y)
+  if ix and iy then
+    local isnumeneg = ix[BINT_SIZE] & BINT_WORDMSB ~= 0
+    local isdenoneg = iy[BINT_SIZE] & BINT_WORDMSB ~= 0
+    if isnumeneg then
+      ix = -ix
+    end
+    if isdenoneg then
+      iy = -iy
+    end
+    local quot, rema = bint_udivmod(ix, iy)
+    if isnumeneg ~= isdenoneg then
+      quot:_unm()
+      -- round quotient towards minus infinity
+      if not rema:iszero() then
+        quot:_dec()
+      end
+    end
+    return quot, rema
+  end
+  return bint_tonumber(x) // bint_tonumber(y)
+end
+
+--- Perform division between two numbers considering bints.
+-- This always casts inputs to floats, for integer division only use @{bint.__idiv}.
+-- @param x The numerator, a bint or lua number.
+-- @param y The denominator, a bint or lua number.
+-- @return The quotient, a lua number.
+function bint.__div(x, y)
+  return bint_tonumber(x) / bint_tonumber(y)
+end
+
+--- Perform integer floor modulo operation between two numbers considering bints.
+-- The operation is defined as the remainder of the floor division
+-- (division that rounds the quotient towards minus infinity).
+-- @param x The numerator, a bint or lua number.
+-- @param y The denominator, a bint or lua number.
+-- @return The remainder, a bint or lua number.
+-- @raise Asserts on attempt to divide by zero.
+function bint.__mod(x, y)
+  local _, rema = bint_idivmod(x, y)
+  return rema
+end
+
+--- Perform integer power between two integers considering bints.
+-- If y is negative then pow is performed as an unsigned integer.
+-- @param x The base, an integer.
+-- @param y The exponent, an integer.
+-- @return The result of the pow operation, a bint.
+-- @raise Asserts in case inputs are not convertible to integers.
+-- @see bint.__pow
+-- @see bint.upowmod
+function bint.ipow(x, y)
+  y = bint_assert_convert(y)
+  if y:iszero() then
+    return bint_one()
+  elseif y:isone() then
+    return bint_new(x)
+  end
+  -- compute exponentiation by squaring
+  x, y = bint_new(x),  bint_new(y)
+  local z = bint_one()
+  repeat
+    if y:iseven() then
+      x = x * x
+      y:_shrone()
+    else
+      z = x * z
+      x = x * x
+      y:_dec():_shrone()
+    end
+  until y:isone()
+  return x * z
+end
+
+--- Perform integer power between two unsigned integers over a modulus considering bints.
+-- @param x The base, an integer.
+-- @param y The exponent, an integer.
+-- @param m The modulus, an integer.
+-- @return The result of the pow operation, a bint.
+-- @raise Asserts in case inputs are not convertible to integers.
+-- @see bint.__pow
+-- @see bint.ipow
+function bint.upowmod(x, y, m)
+  m = bint_assert_convert(m)
+  if m:isone() then
+    return bint_zero()
+  end
+  x, y = bint_new(x),  bint_new(y)
+  local z = bint_one()
+  x = bint_umod(x, m)
+  while not y:iszero() do
+    if y:isodd() then
+      z = bint_umod(z*x, m)
+    end
+    y:_shrone()
+    x = bint_umod(x*x, m)
+  end
+  return z
+end
+
+--- Perform numeric power between two numbers considering bints.
+-- This always casts inputs to floats, for integer power only use @{bint.ipow}.
+-- @param x The base, a bint or lua number.
+-- @param y The exponent, a bint or lua number.
+-- @return The result of the pow operation, a lua number.
+-- @see bint.ipow
+function bint.__pow(x, y)
+  return bint_tonumber(x) ^ bint_tonumber(y)
+end
+
+--- Bitwise left shift integers considering bints.
+-- @param x An integer to perform the bitwise shift.
+-- @param y An integer with the number of bits to shift.
+-- @return The result of shift operation, a bint.
+-- @raise Asserts in case inputs are not convertible to integers.
+function bint.__shl(x, y)
+  x, y = bint_new(x), bint_assert_tointeger(y)
+  if y == math_mininteger or math_abs(y) >= BINT_BITS then
+    return bint_zero()
+  end
+  if y < 0 then
+    return x >> -y
+  end
+  local nvals = y // BINT_WORDBITS
+  if nvals ~= 0 then
+    x:_shlwords(nvals)
+    y = y - nvals * BINT_WORDBITS
+  end
+  if y ~= 0 then
+    local wordbitsmy = BINT_WORDBITS - y
+    for i=BINT_SIZE,2,-1 do
+      x[i] = ((x[i] << y) | (x[i-1] >> wordbitsmy)) & BINT_WORDMAX
+    end
+    x[1] = (x[1] << y) & BINT_WORDMAX
+  end
+  return x
+end
+
+--- Bitwise right shift integers considering bints.
+-- @param x An integer to perform the bitwise shift.
+-- @param y An integer with the number of bits to shift.
+-- @return The result of shift operation, a bint.
+-- @raise Asserts in case inputs are not convertible to integers.
+function bint.__shr(x, y)
+  x, y = bint_new(x), bint_assert_tointeger(y)
+  if y == math_mininteger or math_abs(y) >= BINT_BITS then
+    return bint_zero()
+  end
+  if y < 0 then
+    return x << -y
+  end
+  local nvals = y // BINT_WORDBITS
+  if nvals ~= 0 then
+    x:_shrwords(nvals)
+    y = y - nvals * BINT_WORDBITS
+  end
+  if y ~= 0 then
+    local wordbitsmy = BINT_WORDBITS - y
+    for i=1,BINT_SIZE-1 do
+      x[i] = ((x[i] >> y) | (x[i+1] << wordbitsmy)) & BINT_WORDMAX
+    end
+    x[BINT_SIZE] = x[BINT_SIZE] >> y
+  end
+  return x
+end
+
+--- Bitwise AND bints (in-place).
+-- @param y An integer to perform bitwise AND.
+-- @raise Asserts in case inputs are not convertible to integers.
+function bint:_band(y)
+  y = bint_assert_convert(y)
+  for i=1,BINT_SIZE do
+    self[i] = self[i] & y[i]
+  end
+  return self
+end
+
+--- Bitwise AND two integers considering bints.
+-- @param x An integer to perform bitwise AND.
+-- @param y An integer to perform bitwise AND.
+-- @raise Asserts in case inputs are not convertible to integers.
+function bint.__band(x, y)
+  return bint_new(x):_band(y)
+end
+
+--- Bitwise OR bints (in-place).
+-- @param y An integer to perform bitwise OR.
+-- @raise Asserts in case inputs are not convertible to integers.
+function bint:_bor(y)
+  y = bint_assert_convert(y)
+  for i=1,BINT_SIZE do
+    self[i] = self[i] | y[i]
+  end
+  return self
+end
+
+--- Bitwise OR two integers considering bints.
+-- @param x An integer to perform bitwise OR.
+-- @param y An integer to perform bitwise OR.
+-- @raise Asserts in case inputs are not convertible to integers.
+function bint.__bor(x, y)
+  return bint_new(x):_bor(y)
+end
+
+--- Bitwise XOR bints (in-place).
+-- @param y An integer to perform bitwise XOR.
+-- @raise Asserts in case inputs are not convertible to integers.
+function bint:_bxor(y)
+  y = bint_assert_convert(y)
+  for i=1,BINT_SIZE do
+    self[i] = self[i] ~ y[i]
+  end
+  return self
+end
+
+--- Bitwise XOR two integers considering bints.
+-- @param x An integer to perform bitwise XOR.
+-- @param y An integer to perform bitwise XOR.
+-- @raise Asserts in case inputs are not convertible to integers.
+function bint.__bxor(x, y)
+  return bint_new(x):_bxor(y)
+end
+
+--- Bitwise NOT a bint (in-place).
+function bint:_bnot()
+  for i=1,BINT_SIZE do
+    self[i] = (~self[i]) & BINT_WORDMAX
+  end
+  return self
+end
+
+--- Bitwise NOT a bint.
+-- @param x An integer to perform bitwise NOT.
+-- @raise Asserts in case inputs are not convertible to integers.
+function bint.__bnot(x)
+  local y = setmetatable({}, bint)
+  for i=1,BINT_SIZE do
+    y[i] = (~x[i]) & BINT_WORDMAX
+  end
+  return y
+end
+
+--- Negate a bint (in-place). This effectively applies two's complements.
+function bint:_unm()
+  return self:_bnot():_inc()
+end
+
+--- Negate a bint. This effectively applies two's complements.
+-- @param x A bint to perform negation.
+function bint.__unm(x)
+  return (~x):_inc()
+end
+
+--- Compare if integer x is less than y considering bints (unsigned version).
+-- @param x Left integer to compare.
+-- @param y Right integer to compare.
+-- @raise Asserts in case inputs are not convertible to integers.
+-- @see bint.__lt
+function bint.ult(x, y)
+  x, y = bint_assert_convert(x), bint_assert_convert(y)
+  for i=BINT_SIZE,1,-1 do
+    local a, b = x[i], y[i]
+    if a ~= b then
+      return a < b
+    end
+  end
+  return false
+end
+
+--- Compare if bint x is less or equal than y considering bints (unsigned version).
+-- @param x Left integer to compare.
+-- @param y Right integer to compare.
+-- @raise Asserts in case inputs are not convertible to integers.
+-- @see bint.__le
+function bint.ule(x, y)
+  x, y = bint_assert_convert(x), bint_assert_convert(y)
+  for i=BINT_SIZE,1,-1 do
+    local a, b = x[i], y[i]
+    if a ~= b then
+      return a < b
+    end
+  end
+  return true
+end
+
+--- Compare if number x is less than y considering bints and signs.
+-- @param x Left value to compare, a bint or lua number.
+-- @param y Right value to compare, a bint or lua number.
+-- @see bint.ult
+function bint.__lt(x, y)
+  local ix, iy = tobint(x), tobint(y)
+  if ix and iy then
+    local xneg = ix[BINT_SIZE] & BINT_WORDMSB ~= 0
+    local yneg = iy[BINT_SIZE] & BINT_WORDMSB ~= 0
+    if xneg == yneg then
+      for i=BINT_SIZE,1,-1 do
+        local a, b = ix[i], iy[i]
+        if a ~= b then
+          return a < b
+        end
+      end
+      return false
+    end
+    return xneg and not yneg
+  end
+  return bint_tonumber(x) < bint_tonumber(y)
+end
+
+--- Compare if number x is less or equal than y considering bints and signs.
+-- @param x Left value to compare, a bint or lua number.
+-- @param y Right value to compare, a bint or lua number.
+-- @see bint.ule
+function bint.__le(x, y)
+  local ix, iy = tobint(x), tobint(y)
+  if ix and iy then
+    local xneg = ix[BINT_SIZE] & BINT_WORDMSB ~= 0
+    local yneg = iy[BINT_SIZE] & BINT_WORDMSB ~= 0
+    if xneg == yneg then
+      for i=BINT_SIZE,1,-1 do
+        local a, b = ix[i], iy[i]
+        if a ~= b then
+          return a < b
+        end
+      end
+      return true
+    end
+    return xneg and not yneg
+  end
+  return bint_tonumber(x) <= bint_tonumber(y)
+end
+
+--- Convert a bint to a string on base 10.
+-- @see bint.tobase
+function bint:__tostring()
+  return self:tobase(10)
+end
+
+-- Allow creating bints by calling bint itself
+setmetatable(bint, {
+  __call = function(_, x)
+    return bint_new(x)
+  end
+})
+
+BINT_MATHMININTEGER, BINT_MATHMAXINTEGER = bint_new(math.mininteger), bint_new(math.maxinteger)
+BINT_MININTEGER = bint.mininteger()
+memo[memoindex] = bint
+
+return bint
+
+end
+
+return newmodule
+
+--[[
+The MIT License (MIT)
+
+Copyright (c) 2020-2024 Eduardo Bart (https://github.com/edubart)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+]]
diff --git a/tests/Makefile b/tests/Makefile
index 943e24b66..1ceb1ec19 100644
--- a/tests/Makefile
+++ b/tests/Makefile
@@ -81,7 +81,7 @@ RUN_ARCH_TEST = $(LUA) $(abspath ./lua/run-rv64i-arch-test.lua)
 CARTESI_IMAGES = $(CARTESI_IMAGES_PATH)/linux.bin
 
 STYLUA=stylua
-STYLUA_FLAGS=--indent-type Spaces
+STYLUA_FLAGS=--indent-type Spaces --respect-ignores
 
 build-tests-all: misc build-tests-machine-with-toolchain build-tests-uarch-with-toolchain images $(CARTESI_CMIO_PATH)
 
diff --git a/tests/lua/.styluaignore b/tests/lua/.styluaignore
new file mode 100644
index 000000000..67d08e3a1
--- /dev/null
+++ b/tests/lua/.styluaignore
@@ -0,0 +1 @@
+cartesi/third-party/*
diff --git a/tests/lua/cartesi/third-party/lester.lua b/tests/lua/cartesi/third-party/lester.lua
new file mode 100644
index 000000000..56d2e9873
--- /dev/null
+++ b/tests/lua/cartesi/third-party/lester.lua
@@ -0,0 +1,599 @@
+--[[
+Minimal test framework for Lua.
+lester - v0.1.5 - 18/Oct/2023
+Eduardo Bart - edub4rt@gmail.com
+https://github.com/edubart/lester
+Minimal Lua test framework.
+See end of file for LICENSE.
+]]
+
+--[[--
+Lester is a minimal unit testing framework for Lua with a focus on being simple to use.
+
+## Features
+
+* Minimal, just one file.
+* Self contained, no external dependencies.
+* Simple and hackable when needed.
+* Use `describe` and `it` blocks to describe tests.
+* Supports `before` and `after` handlers.
+* Colored output.
+* Configurable via the script or with environment variables.
+* Quiet mode, to use in live development.
+* Optionally filter tests by name.
+* Show traceback on errors.
+* Show time to complete tests.
+* Works with Lua 5.1+.
+* Efficient.
+
+## Usage
+
+Copy `lester.lua` file to a project and require it,
+which returns a table that includes all of the functionality:
+
+```lua
+local lester = require 'lester'
+local describe, it, expect = lester.describe, lester.it, lester.expect
+
+-- Customize lester configuration.
+lester.show_traceback = false
+
+-- Parse arguments from command line.
+lester.parse_args()
+
+describe('my project', function()
+  lester.before(function()
+    -- This function is run before every test.
+  end)
+
+  describe('module1', function() -- Describe blocks can be nested.
+    it('feature1', function()
+      expect.equal('something', 'something') -- Pass.
+    end)
+
+    it('feature2', function()
+      expect.truthy(false) -- Fail.
+    end)
+
+    local feature3_test_enabled = false
+    it('feature3', function() -- This test will be skipped.
+      expect.truthy(false) -- Fail.
+    end, feature3_test_enabled)
+  end)
+end)
+
+lester.report() -- Print overall statistic of the tests run.
+lester.exit() -- Exit with success if all tests passed.
+```
+
+## Customizing output with environment variables
+
+To customize the output of lester externally,
+you can set the following environment variables before running a test suite:
+
+* `LESTER_QUIET="true"`, omit print of passed tests.
+* `LESTER_COLOR="false"`, disable colored output.
+* `LESTER_SHOW_TRACEBACK="false"`, disable traceback on test failures.
+* `LESTER_SHOW_ERROR="false"`, omit print of error description of failed tests.
+* `LESTER_STOP_ON_FAIL="true"`, stop on first test failure.
+* `LESTER_UTF8TERM="false"`, disable printing of UTF-8 characters.
+* `LESTER_FILTER="some text"`, filter the tests that should be run.
+
+Note that these configurations can be changed via script too, check the documentation.
+
+## Customizing output with command line arguments
+
+You can also customize output using command line arguments
+if `lester.parse_args()` is called at startup.
+
+The following command line arguments are available:
+
+* `--quiet`, omit print of passed tests.
+* `--no-quiet`, show print of passed tests.
+* `--no-color`, disable colored output.
+* `--no-show-traceback`, disable traceback on test failures.
+* `--no-show-error`, omit print of error description of failed tests.
+* `--stop-on-fail`, stop on first test failure.
+* `--no-utf8term`, disable printing of UTF-8 characters.
+* `--filter="some text"`, filter the tests that should be run.
+
+]]
+
+-- Returns whether the terminal supports UTF-8 characters.
+local function is_utf8term()
+  local lang = os.getenv('LANG')
+  return (lang and lang:lower():match('utf%-?8$')) and true or false
+end
+
+-- Returns whether a system environment variable is "true".
+local function getboolenv(varname, default)
+  local val = os.getenv(varname)
+  if val == 'true' then
+    return true
+  elseif val == 'false' then
+    return false
+  end
+  return default
+end
+
+-- The lester module.
+local lester = {
+  --- Whether lines of passed tests should not be printed. False by default.
+  quiet = getboolenv('LESTER_QUIET', false),
+  --- Whether the output should  be colorized. True by default.
+  color = getboolenv('LESTER_COLOR', true),
+  --- Whether a traceback must be shown on test failures. True by default.
+  show_traceback = getboolenv('LESTER_SHOW_TRACEBACK', true),
+  --- Whether the error description of a test failure should be shown. True by default.
+  show_error = getboolenv('LESTER_SHOW_ERROR', true),
+  --- Whether test suite should exit on first test failure. False by default.
+  stop_on_fail = getboolenv('LESTER_STOP_ON_FAIL', false),
+  --- Whether we can print UTF-8 characters to the terminal. True by default when supported.
+  utf8term = getboolenv('LESTER_UTF8TERM', is_utf8term()),
+  --- A string with a lua pattern to filter tests. Nil by default.
+  filter = os.getenv('LESTER_FILTER') or '',
+  --- Function to retrieve time in seconds with milliseconds precision, `os.clock` by default.
+  seconds = os.clock,
+}
+
+-- Variables used internally for the lester state.
+local lester_start = nil
+local last_succeeded = false
+local level = 0
+local successes = 0
+local total_successes = 0
+local failures = 0
+local total_failures = 0
+local skipped = 0
+local total_skipped = 0
+local start = 0
+local befores = {}
+local afters = {}
+local names = {}
+
+-- Color codes.
+local color_codes = {
+  reset = string.char(27) .. '[0m',
+  bright = string.char(27) .. '[1m',
+  red = string.char(27) .. '[31m',
+  green = string.char(27) .. '[32m',
+  yellow = string.char(27) .. '[33m',
+  blue = string.char(27) .. '[34m',
+  magenta = string.char(27) .. '[35m',
+}
+
+local quiet_o_char = string.char(226, 151, 143)
+
+-- Colors table, returning proper color code if color mode is enabled.
+local colors = setmetatable({}, { __index = function(_, key)
+  return lester.color and color_codes[key] or ''
+end})
+
+--- Table of terminal colors codes, can be customized.
+lester.colors = colors
+
+-- Parse command line arguments from `arg` table.
+-- It `arg` is nil then the global `arg` is used.
+function lester.parse_args(arg)
+  for _,opt in ipairs(arg or _G.arg) do
+    local name, value
+    if opt:find('^%-%-filter') then
+      name = 'filter'
+      value = opt:match('^%-%-filter%=(.*)$')
+    elseif opt:find('^%-%-no%-[a-z0-9-]+$') then
+      name = opt:match('^%-%-no%-([a-z0-9-]+)$'):gsub('-','_')
+      value = false
+    elseif opt:find('^%-%-[a-z0-9-]+$') then
+      name = opt:match('^%-%-([a-z0-9-]+)$'):gsub('-','_')
+      value = true
+    end
+    if value ~= nil and lester[name] ~= nil and (type(lester[name]) == 'boolean' or type(lester[name]) == 'string') then
+      lester[name] = value
+    end
+  end
+end
+
+--- Describe a block of tests, which consists in a set of tests.
+-- Describes can be nested.
+-- @param name A string used to describe the block.
+-- @param func A function containing all the tests or other describes.
+function lester.describe(name, func)
+  if level == 0 then -- Get start time for top level describe blocks.
+    failures = 0
+    successes = 0
+    skipped = 0
+    start = lester.seconds()
+    if not lester_start then
+      lester_start = start
+    end
+  end
+  -- Setup describe block variables.
+  level = level + 1
+  names[level] = name
+  -- Run the describe block.
+  func()
+  -- Cleanup describe block.
+  afters[level] = nil
+  befores[level] = nil
+  names[level] = nil
+  level = level - 1
+  -- Pretty print statistics for top level describe block.
+  if level == 0 and not lester.quiet and (successes > 0 or failures > 0) then
+    local io_write = io.write
+    local colors_reset, colors_green = colors.reset, colors.green
+    io_write(failures == 0 and colors_green or colors.red, '[====] ',
+             colors.magenta, name, colors_reset, ' | ',
+             colors_green, successes, colors_reset, ' successes / ')
+    if skipped > 0 then
+      io_write(colors.yellow, skipped, colors_reset, ' skipped / ')
+    end
+    if failures > 0 then
+      io_write(colors.red, failures, colors_reset, ' failures / ')
+    end
+    io_write(colors.bright, string.format('%.6f', lester.seconds() - start), colors_reset, ' seconds\n')
+  end
+end
+
+-- Error handler used to get traceback for errors.
+local function xpcall_error_handler(err)
+  return debug.traceback(tostring(err), 2)
+end
+
+-- Pretty print the line on the test file where an error happened.
+local function show_error_line(err)
+  local info = debug.getinfo(3)
+  local io_write = io.write
+  local colors_reset = colors.reset
+  local short_src, currentline = info.short_src, info.currentline
+  io_write(' (', colors.blue, short_src, colors_reset,
+           ':', colors.bright, currentline, colors_reset)
+  if err and lester.show_traceback then
+    local fnsrc = short_src..':'..currentline
+    for cap1, cap2 in err:gmatch('\t[^\n:]+:(%d+): in function <([^>]+)>\n') do
+      if cap2 == fnsrc then
+        io_write('/', colors.bright, cap1, colors_reset)
+        break
+      end
+    end
+  end
+  io_write(')')
+end
+
+-- Pretty print the test name, with breadcrumb for the describe blocks.
+local function show_test_name(name)
+  local io_write = io.write
+  local colors_reset = colors.reset
+  for _,descname in ipairs(names) do
+    io_write(colors.magenta, descname, colors_reset, ' | ')
+  end
+  io_write(colors.bright, name, colors_reset)
+end
+
+--- Declare a test, which consists of a set of assertions.
+-- @param name A name for the test.
+-- @param func The function containing all assertions.
+-- @param enabled If not nil and equals to false, the test will be skipped and this will be reported.
+function lester.it(name, func, enabled)
+  -- Skip the test silently if it does not match the filter.
+  if lester.filter then
+    local fullname = table.concat(names, ' | ')..' | '..name
+    if not fullname:match(lester.filter) then
+      return
+    end
+  end
+  local io_write = io.write
+  local colors_reset = colors.reset
+  -- Skip the test if it's disabled, while displaying a message
+  if enabled == false then
+    if not lester.quiet then
+      io_write(colors.yellow, '[SKIP] ', colors_reset)
+      show_test_name(name)
+      io_write('\n')
+    else -- Show just a character hinting that the test was skipped.
+      local o = (lester.utf8term and lester.color) and quiet_o_char or 'o'
+      io_write(colors.yellow, o, colors_reset)
+    end
+    skipped = skipped + 1
+    total_skipped = total_skipped + 1
+    return
+  end
+  -- Execute before handlers.
+  for _,levelbefores in pairs(befores) do
+    for _,beforefn in ipairs(levelbefores) do
+      beforefn(name)
+    end
+  end
+  -- Run the test, capturing errors if any.
+  local success, err
+  if lester.show_traceback then
+    success, err = xpcall(func, xpcall_error_handler)
+  else
+    success, err = pcall(func)
+    if not success and err then
+      err = tostring(err)
+    end
+  end
+  -- Count successes and failures.
+  if success then
+    successes = successes + 1
+    total_successes = total_successes + 1
+  else
+    failures = failures + 1
+    total_failures = total_failures + 1
+  end
+  -- Print the test run.
+  if not lester.quiet then -- Show test status and complete test name.
+    if success then
+      io_write(colors.green, '[PASS] ', colors_reset)
+    else
+      io_write(colors.red, '[FAIL] ', colors_reset)
+    end
+    show_test_name(name)
+    if not success then
+      show_error_line(err)
+    end
+    io_write('\n')
+  else
+    if success then -- Show just a character hinting that the test succeeded.
+      local o = (lester.utf8term and lester.color) and quiet_o_char or 'o'
+      io_write(colors.green, o, colors_reset)
+    else -- Show complete test name on failure.
+      io_write(last_succeeded and '\n' or '',
+               colors.red, '[FAIL] ', colors_reset)
+      show_test_name(name)
+      show_error_line(err)
+      io_write('\n')
+    end
+  end
+  -- Print error message, colorizing its output if possible.
+  if err and lester.show_error then
+    if lester.color then
+      local errfile, errline, errmsg, rest = err:match('^([^:\n]+):(%d+): ([^\n]+)(.*)')
+      if errfile and errline and errmsg and rest then
+        io_write(colors.blue, errfile, colors_reset,
+                 ':', colors.bright, errline, colors_reset, ': ')
+        if errmsg:match('^%w([^:]*)$') then
+          io_write(colors.red, errmsg, colors_reset)
+        else
+          io_write(errmsg)
+        end
+        err = rest
+      end
+    end
+    io_write(err, '\n\n')
+  end
+  io.flush()
+  -- Stop on failure.
+  if not success and lester.stop_on_fail then
+    if lester.quiet then
+      io_write('\n')
+      io.flush()
+    end
+    lester.exit()
+  end
+  -- Execute after handlers.
+  for _,levelafters in pairs(afters) do
+    for _,afterfn in ipairs(levelafters) do
+      afterfn(name)
+    end
+  end
+  last_succeeded = success
+end
+
+--- Set a function that is called before every test inside a describe block.
+-- A single string containing the name of the test about to be run will be passed to `func`.
+function lester.before(func)
+  local levelbefores = befores[level]
+  if not levelbefores then
+    levelbefores = {}
+    befores[level] = levelbefores
+  end
+  levelbefores[#levelbefores+1] = func
+end
+
+--- Set a function that is called after every test inside a describe block.
+-- A single string containing the name of the test that was finished will be passed to `func`.
+-- The function is executed independently if the test passed or failed.
+function lester.after(func)
+  local levelafters = afters[level]
+  if not levelafters then
+    levelafters = {}
+    afters[level] = levelafters
+  end
+  levelafters[#levelafters+1] = func
+end
+
+--- Pretty print statistics of all test runs.
+-- With total success, total failures and run time in seconds.
+function lester.report()
+  local now = lester.seconds()
+  local colors_reset = colors.reset
+  io.write(lester.quiet and '\n' or '',
+           colors.green, total_successes, colors_reset, ' successes / ',
+           colors.yellow, total_skipped, colors_reset, ' skipped / ',
+           colors.red, total_failures, colors_reset, ' failures / ',
+           colors.bright, string.format('%.6f', now - (lester_start or now)), colors_reset, ' seconds\n')
+  io.flush()
+  return total_failures == 0
+end
+
+--- Exit the application with success code if all tests passed, or failure code otherwise.
+function lester.exit()
+  -- Collect garbage before exiting to call __gc handlers
+  collectgarbage()
+  collectgarbage()
+  os.exit(total_failures == 0, true)
+end
+
+local expect = {}
+--- Expect module, containing utility function for doing assertions inside a test.
+lester.expect = expect
+
+--- Converts a value to a human-readable string.
+-- If the final string not contains only ASCII characters,
+-- then it is converted to a Lua hexdecimal string.
+function expect.tohumanstring(v)
+  local s = tostring(v)
+  if s:find'[^ -~\n\t]' then -- string contains non printable ASCII
+    return '"'..s:gsub('.', function(c) return string.format('\\x%02X', c:byte()) end)..'"'
+  end
+  return s
+end
+
+--- Check if a function fails with an error.
+-- If `expected` is nil then any error is accepted.
+-- If `expected` is a string then we check if the error contains that string.
+-- If `expected` is anything else then we check if both are equal.
+function expect.fail(func, expected)
+  local ok, err = pcall(func)
+  if ok then
+    error('expected function to fail', 2)
+  elseif expected ~= nil then
+    local found = expected == err
+    if not found and type(expected) == 'string' then
+      found = string.find(tostring(err), expected, 1, true)
+    end
+    if not found then
+      error('expected function to fail\nexpected:\n'..tostring(expected)..'\ngot:\n'..tostring(err), 2)
+    end
+  end
+end
+
+--- Check if a function does not fail with a error.
+function expect.not_fail(func)
+  local ok, err = pcall(func)
+  if not ok then
+    error('expected function to not fail\ngot error:\n'..expect.tohumanstring(err), 2)
+  end
+end
+
+--- Check if a value is not `nil`.
+function expect.exist(v)
+  if v == nil then
+    error('expected value to exist\ngot:\n'..expect.tohumanstring(v), 2)
+  end
+end
+
+--- Check if a value is `nil`.
+function expect.not_exist(v)
+  if v ~= nil then
+    error('expected value to not exist\ngot:\n'..expect.tohumanstring(v), 2)
+  end
+end
+
+--- Check if an expression is evaluates to `true`.
+function expect.truthy(v)
+  if not v then
+    error('expected expression to be true\ngot:\n'..expect.tohumanstring(v), 2)
+  end
+end
+
+--- Check if an expression is evaluates to `false`.
+function expect.falsy(v)
+  if v then
+    error('expected expression to be false\ngot:\n'..expect.tohumanstring(v), 2)
+  end
+end
+
+--- Returns raw tostring result for a value.
+local function rawtostring(v)
+  local mt = getmetatable(v)
+  if mt then
+    setmetatable(v, nil)
+  end
+  local s = tostring(v)
+  if mt then
+    setmetatable(v, mt)
+  end
+  return s
+end
+
+-- Returns key suffix for a string_eq table key.
+local function strict_eq_key_suffix(k)
+  if type(k) == 'string' then
+    if k:find('^[a-zA-Z_][a-zA-Z0-9]*$') then -- string is a lua field
+      return '.'..k
+    elseif k:find'[^ -~\n\t]' then -- string contains non printable ASCII
+      return '["'..k:gsub('.', function(c) return string.format('\\x%02X', c:byte()) end)..'"]'
+    else
+      return '["'..k..'"]'
+    end
+  else
+    return string.format('[%s]', rawtostring(k))
+  end
+end
+
+--- Compare if two values are equal, considering nested tables.
+function expect.strict_eq(t1, t2, name)
+  if rawequal(t1, t2) then return true end
+  name = name or 'value'
+  local t1type, t2type = type(t1), type(t2)
+  if t1type ~= t2type then
+    return false, string.format("expected types to be equal for %s\nfirst: %s\nsecond: %s",
+      name, t1type, t2type)
+  end
+  if t1type == 'table' then
+    if getmetatable(t1) ~= getmetatable(t2) then
+      return false, string.format("expected metatables to be equal for %s\nfirst: %s\nsecond: %s",
+        name,  expect.tohumanstring(t1), expect.tohumanstring(t2))
+    end
+    for k,v1 in pairs(t1) do
+      local ok, err = expect.strict_eq(v1, t2[k], name..strict_eq_key_suffix(k))
+      if not ok then
+        return false, err
+      end
+    end
+    for k,v2 in pairs(t2) do
+      local ok, err = expect.strict_eq(v2, t1[k], name..strict_eq_key_suffix(k))
+      if not ok then
+        return false, err
+      end
+    end
+  elseif t1 ~= t2 then
+    return false, string.format("expected values to be equal for %s\nfirst:\n%s\nsecond:\n%s",
+      name,  expect.tohumanstring(t1), expect.tohumanstring(t2))
+  end
+  return true
+end
+
+--- Check if two values are equal.
+function expect.equal(v1, v2)
+  local ok, err = expect.strict_eq(v1, v2)
+  if not ok then
+    error(err, 2)
+  end
+end
+
+--- Check if two values are not equal.
+function expect.not_equal(v1, v2)
+  if expect.strict_eq(v1, v2) then
+    local v1s, v2s = expect.tohumanstring(v1), expect.tohumanstring(v2)
+    error('expected values to be not equal\nfirst value:\n'..v1s..'\nsecond value:\n'..v2s, 2)
+  end
+end
+
+return lester
+
+--[[
+The MIT License (MIT)
+
+Copyright (c) 2021-2023 Eduardo Bart (https://github.com/edubart)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+]]

From 36ae3b871bcf538b98052059699a1c0d30c8d491 Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Thu, 21 Aug 2025 12:04:13 -0300
Subject: [PATCH 59/82] test: SHA-256/KECCAK-256 hash functions

---
 tests/lua/cartesi/tests/util.lua  |  24 ++++-
 tests/lua/spec-hash-functions.lua | 149 ++++++++++++++++++++++++++++++
 tests/lua/test-spec.lua           |  27 ++++++
 tests/scripts/run-lua-tests.sh    |  13 ++-
 4 files changed, 208 insertions(+), 5 deletions(-)
 create mode 100644 tests/lua/spec-hash-functions.lua
 create mode 100755 tests/lua/test-spec.lua

diff --git a/tests/lua/cartesi/tests/util.lua b/tests/lua/cartesi/tests/util.lua
index 5c9690a4f..890f7048d 100644
--- a/tests/lua/cartesi/tests/util.lua
+++ b/tests/lua/cartesi/tests/util.lua
@@ -25,11 +25,27 @@ local function adjust_path(path)
     return string.gsub(path or ".", "/*$", "") .. "/"
 end
 
+-- Returns the directory absolute path at level `dirlevel` for the calling script at level `calllevel`.
+local function get_script_path(dirlevel, calllevel)
+    local info = debug.getinfo(calllevel or 1, "S")
+    local path = info and info.source and info.source:match("^@([^\n\r]+)")
+    assert(path, "could not retrieve calling script path")
+    path = require("posix.stdlib").realpath(path)
+    if dirlevel and dirlevel > 0 then
+        local segments = {}
+        for segment in path:gmatch("[^/]+") do
+            table.insert(segments, segment)
+        end
+        return "/" .. table.concat(segments, "/", 1, #segments - dirlevel)
+    end
+    return path
+end
+
 local test_util = {
-    images_path = adjust_path(assert(os.getenv("CARTESI_IMAGES_PATH"), "must set CARTESI_IMAGES_PATH")),
-    tests_path = adjust_path(assert(os.getenv("CARTESI_TESTS_PATH"), "must set CARTESI_TESTS_PATH")),
-    cmio_path = adjust_path(assert(os.getenv("CARTESI_CMIO_PATH"), "must set CARTESI_CMIO_PATH")),
-    tests_uarch_path = adjust_path(assert(os.getenv("CARTESI_TESTS_UARCH_PATH"), "must set CARTESI_TESTS_UARCH_PATH")),
+    images_path = adjust_path(os.getenv("CARTESI_IMAGES_PATH") or get_script_path(5) .. "/src"),
+    tests_path = adjust_path(os.getenv("CARTESI_TESTS_PATH") or get_script_path(4) .. "/build/machine"),
+    cmio_path = adjust_path(os.getenv("CARTESI_CMIO_PATH") or get_script_path(4) .. "/build/cmio"),
+    tests_uarch_path = adjust_path(os.getenv("CARTESI_TESTS_UARCH_PATH") or get_script_path(4) .. "/build/uarch"),
 }
 
 local function compute_zero_hash_table(hash_fn)
diff --git a/tests/lua/spec-hash-functions.lua b/tests/lua/spec-hash-functions.lua
new file mode 100644
index 000000000..b6b6bf57f
--- /dev/null
+++ b/tests/lua/spec-hash-functions.lua
@@ -0,0 +1,149 @@
+--[[
+Test suite for hash functions (SHA-256 and Keccak-256).
+Specifically, it provides test coverage for:
+    sha-256-hasher.cpp
+    keccak-256-hasher.cpp
+Can be run independently during development the mentioned files.
+]]
+
+local lester = require("cartesi.third-party.lester")
+local util = require("cartesi.tests.util")
+local describe, it, expect = lester.describe, lester.it, lester.expect
+
+describe("hash function", function()
+    describe("keccak256", function()
+        local keccak256 = require("cartesi").keccak256
+        local function hexkeccak256(...)
+            return util.tohex(keccak256(...)):lower()
+        end
+
+        it("should fail when passing invalid arguments", function()
+            expect.fail(function()
+                keccak256("a", "b", "c")
+            end, "too many arguments")
+            expect.fail(function()
+                keccak256(1, 2)
+            end, "only supported for inputs with size of hash")
+            expect.fail(function()
+                keccak256()
+            end, "too few arguments")
+        end)
+
+        it("should match hashes", function()
+            expect.equal(hexkeccak256(""), "c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470")
+            expect.equal(hexkeccak256("0"), "044852b2a670ade5407e78fb2863c51de9fcb96542a07186fe3aeda6bb8a116d")
+            expect.equal(hexkeccak256("test"), "9c22ff5f21f0b81b113e63f7db6da94fedef11b2119b4088b89664fb9a3cb658")
+            expect.equal(
+                hexkeccak256(hexkeccak256("")),
+                "79482f93ea0d714e293366322922962af38ecdd95cff648355c1af4b40a78b32"
+            )
+        end)
+
+        it("should match concat hashes", function()
+            expect.equal(
+                hexkeccak256(string.rep("\x00", 32), string.rep("\x00", 32)),
+                hexkeccak256(string.rep("\x00", 64))
+            )
+            expect.equal(
+                hexkeccak256(string.rep("a", 32), string.rep("b", 32)),
+                hexkeccak256(string.rep("a", 32) .. string.rep("b", 32))
+            )
+        end)
+
+        it("should match with special lengths", function()
+            local KECCAK_RSIZE = 136
+            -- The data lengths are chosen to cover special cases of the KECCAK-256 algorithm
+            for data, expected_hash in pairs({
+                -- luacheck: push no max line length
+                [string.rep("a", 0)] = "c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470",
+                [string.rep("a", 1)] = "3ac225168df54212a25c1c01fd35bebfea408fdac2e31ddd6f80a4bbf9a5f1cb",
+                [string.rep("a", 2)] = "dfa57c542fea29ed292cef0ce135d0e22189365fa59abedc7a310b751ace684f",
+                [string.rep("a", 4)] = "a80470dba00d5faf620fd6c51a1ca94668e13cd66fffaee3702f5497a8549053",
+                [string.rep("a", 8)] = "a6eb2a81043a7349b2d066b3433ceadd8dd290343e6c41a4e36e82261e0b25cb",
+                [string.rep("a", 16)] = "05bf23668a24407fc90dc33375cdeb2c8aef9db64ba12353dbc7e8d103dfba00",
+                [string.rep("a", 32)] = "47a01324181e85459310f8fb9b24dc09744323ebdcef26cbf98959effdc76e02",
+                [string.rep("a", 64)] = "1036d73cc8350b0635393d79759b10488165e792073f84d4462e22edec243b92",
+                [string.rep("a", 128)] = "81555b8e18b3c117311c16373b1aa78c0a84aad7b8f7f4c753d0021fd9a6700e",
+                [string.rep("a", KECCAK_RSIZE - 1)] = "34367dc248bbd832f4e3e69dfaac2f92638bd0bbd18f2912ba4ef454919cf446",
+                [string.rep("a", KECCAK_RSIZE / 2)] = "e4b16954d021544d168b5ea23de13c97c762d1f331fe4c7470df3c1000a62fdb",
+                [string.rep("a", KECCAK_RSIZE)] = "a6c4d403279fe3e0af03729caada8374b5ca54d8065329a3ebcaeb4b60aa386e",
+                [string.rep("a", KECCAK_RSIZE + 1)] = "d869f639c7046b4929fc92a4d988a8b22c55fbadb802c0c66ebcd484f1915f39",
+                [string.rep("a", KECCAK_RSIZE + (KECCAK_RSIZE / 2))] = "5f6404fdb4057bbd7bce17d97cc655fca0c1c4129a083d323d79136f768ae757",
+                [string.rep("a", (KECCAK_RSIZE * 2) - 1)] = "132f47effd6c8b1b299efa53fe68aece77ec8ae4eb2e294f668eec94f76001e1",
+                [string.rep("a", KECCAK_RSIZE * 2)] = "cf7fcd4f705ee749930d19ca84561a9bf62516bd90a471545fa2f49fdc7e63c8",
+                [string.rep("a", (KECCAK_RSIZE * 2) + 1)] = "5a7b8187d2778e614097fac3097573de1fee4d972304d3360796a857029bb176",
+                -- luacheck: pop
+            }) do
+                expect.equal(hexkeccak256(data), expected_hash)
+            end
+        end)
+    end)
+
+    describe("sha256", function()
+        local sha256 = require("cartesi").sha256
+        local function hexsha256(...)
+            return util.tohex(sha256(...)):lower()
+        end
+
+        it("should fail when passing invalid arguments", function()
+            expect.fail(function()
+                sha256("a", "b", "c")
+            end, "too many arguments")
+            expect.fail(function()
+                sha256(1, 2)
+            end, "only supported for inputs with size of hash")
+            expect.fail(function()
+                sha256()
+            end, "too few arguments")
+        end)
+
+        it("should match hashes", function()
+            expect.equal(hexsha256(""), "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855")
+            expect.equal(hexsha256("0"), "5feceb66ffc86f38d952786c6d696c79c2dbc239dd4e91b46729d73a27fb57e9")
+            expect.equal(hexsha256("test"), "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08")
+            expect.equal(hexsha256(hexsha256("")), "cd372fb85148700fa88095e3492d3f9f5beb43e555e5ff26d95f5a6adc36f8e6")
+        end)
+
+        it("should match concat hashes", function()
+            expect.equal(hexsha256(string.rep("\x00", 32), string.rep("\x00", 32)), hexsha256(string.rep("\x00", 64)))
+            expect.equal(
+                hexsha256(string.rep("a", 32), string.rep("b", 32)),
+                hexsha256(string.rep("a", 32) .. string.rep("b", 32))
+            )
+        end)
+
+        it("should match hashes with special lengths", function()
+            local SHA256_LEN_POS = 56
+            local SHA256_BUF_SIZE = 64
+            -- The data lengths are chosen to cover special cases of the SHA-256 algorithm
+            for data, expected_hash in pairs({
+                -- luacheck: push no max line length
+                [string.rep("a", 0)] = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+                [string.rep("a", 1)] = "ca978112ca1bbdcafac231b39a23dc4da786eff8147c4e72b9807785afee48bb",
+                [string.rep("a", 2)] = "961b6dd3ede3cb8ecbaacbd68de040cd78eb2ed5889130cceb4c49268ea4d506",
+                [string.rep("a", 4)] = "61be55a8e2f6b4e172338bddf184d6dbee29c98853e0a0485ecee7f27b9af0b4",
+                [string.rep("a", 8)] = "1f3ce40415a2081fa3eee75fc39fff8e56c22270d1a978a7249b592dcebd20b4",
+                [string.rep("a", 16)] = "0c0beacef8877bbf2416eb00f2b5dc96354e26dd1df5517320459b1236860f8c",
+                [string.rep("a", 32)] = "3ba3f5f43b92602683c19aee62a20342b084dd5971ddd33808d81a328879a547",
+                [string.rep("a", 64)] = "ffe054fe7ae0cb6dc65c3af9b61d5209f439851db43d0ba5997337df154668eb",
+                [string.rep("a", 128)] = "6836cf13bac400e9105071cd6af47084dfacad4e5e302c94bfed24e013afb73e",
+                [string.rep("a", SHA256_LEN_POS - 1)] = "9f4390f8d30c2dd92ec9f095b65e2b9ae9b0a925a5258e241c9f1e910f734318",
+                [string.rep("a", SHA256_LEN_POS / 2)] = "9c547cb8115a44883b9f70ba68f75117cd55359c92611875e386f8af98c172ab",
+                [string.rep("a", SHA256_LEN_POS)] = "b35439a4ac6f0948b6d6f9e3c6af0f5f590ce20f1bde7090ef7970686ec6738a",
+                [string.rep("a", SHA256_LEN_POS + 1)] = "f13b2d724659eb3bf47f2dd6af1accc87b81f09f59f2b75e5c0bed6589dfe8c6",
+                [string.rep("a", SHA256_LEN_POS + (SHA256_LEN_POS // 2))] = "f5475022feb69870295b9c1e78c5a4919374061d5345167815801879f931ebb0",
+                [string.rep("a", (SHA256_LEN_POS * 2) - 1)] = "6374f73208854473827f6f6a3f43b1f53eaa3b82c21c1a6d69a2110b2a79baad",
+                [string.rep("a", SHA256_LEN_POS * 2)] = "f54353008a2553262ecdc4a34749563ba0950e8b0fc8652780b0a614b99683c1",
+                [string.rep("a", (SHA256_LEN_POS * 2) + 1)] = "ba02731ae695aae5cd49b49d84330b63995733eb22102aca755f0179b1e0e20f",
+                [string.rep("a", SHA256_BUF_SIZE - 1)] = "7d3e74a05d7db15bce4ad9ec0658ea98e3f06eeecf16b4c6fff2da457ddc2f34",
+                [string.rep("a", SHA256_BUF_SIZE + 1)] = "635361c48bb9eab14198e76ea8ab7f1a41685d6ad62aa9146d301d4f17eb0ae0",
+                [string.rep("a", SHA256_BUF_SIZE + (SHA256_BUF_SIZE // 2))] = "ee4caa5518a866f33e174d6e71ba3961a86ca00a7486b132e5a9f01bfaa1d794",
+                [string.rep("a", (SHA256_BUF_SIZE * 2) - 1)] = "c57e9278af78fa3cab38667bef4ce29d783787a2f731d4e12200270f0c32320a",
+                [string.rep("a", (SHA256_BUF_SIZE * 2) + 1)] = "c12cb024a2e5551cca0e08fce8f1c5e314555cc3fef6329ee994a3db752166ae",
+                -- luacheck: pop
+            }) do
+                expect.equal(hexsha256(data), expected_hash)
+            end
+        end)
+    end)
+end)
diff --git a/tests/lua/test-spec.lua b/tests/lua/test-spec.lua
new file mode 100755
index 000000000..cc36a8f68
--- /dev/null
+++ b/tests/lua/test-spec.lua
@@ -0,0 +1,27 @@
+#!/usr/bin/env lua5.4
+
+-- Copyright 2023 Cartesi Pte. Ltd.
+--
+-- This file is part of the machine-emulator. The machine-emulator is free
+-- software: you can redistribute it and/or modify it under the terms of the GNU
+-- Lesser General Public License as published by the Free Software Foundation,
+-- either version 3 of the License, or (at your option) any later version.
+--
+-- The machine-emulator is distributed in the hope that it will be useful, but
+-- WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+-- FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+-- for more details.
+--
+-- You should have received a copy of the GNU Lesser General Public License
+-- along with the machine-emulator. If not, see http://www.gnu.org/licenses/.
+--
+
+local lester = require("cartesi.third-party.lester")
+
+-- Parse arguments from command line.
+lester.parse_args()
+
+require("spec-hash-functions")
+
+lester.report() -- Print overall statistic of the tests run.
+lester.exit() -- Exit with success if all tests passed.
diff --git a/tests/scripts/run-lua-tests.sh b/tests/scripts/run-lua-tests.sh
index 29d0bfbc8..75d2e0954 100755
--- a/tests/scripts/run-lua-tests.sh
+++ b/tests/scripts/run-lua-tests.sh
@@ -22,8 +22,19 @@ SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
 
 LUA=${1:-lua5.4}
 
-TEST_LIST=(htif-console.lua htif-cmio.lua htif-yield.lua log-with-mtime-transition.lua machine-bind.lua machine-test.lua mcycle-overflow.lua mtime-interrupt.lua)
+TEST_LIST=(
+htif-console.lua
+htif-cmio.lua
+htif-yield.lua
+log-with-mtime-transition.lua
+machine-bind.lua
+machine-test.lua
+mcycle-overflow.lua
+mtime-interrupt.lua
+test-spec.lua
+)
 
+cd $SCRIPT_DIR/../lua
 for x in ${TEST_LIST[@]}; do
     echo "Running $x"
     echo -n 'CTSICTSI' | (bash -c "${LUA} $SCRIPT_DIR/../lua/$x local") || exit 1;

From 738388c4634fee01d709a1e8f6a08ef31fb4ec08 Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Thu, 21 Aug 2025 12:10:13 -0300
Subject: [PATCH 60/82] test: hash tree and collect hashes

---
 src/collect-mcycle-hashes-state-access.h      |   2 +-
 src/collect-uarch-cycle-hashes-state-access.h |   2 +-
 src/hash-tree.cpp                             |  72 ++---
 src/page-hash-tree-cache.h                    |   3 +
 tests/Makefile                                |   5 +-
 tests/lua/hash-tree.lua                       | 273 ----------------
 tests/lua/spec-collect-hashes.lua             | 153 +++++++++
 tests/lua/spec-hash-tree.lua                  | 296 ++++++++++++++++++
 tests/lua/test-spec.lua                       |   2 +
 9 files changed, 491 insertions(+), 317 deletions(-)
 delete mode 100755 tests/lua/hash-tree.lua
 create mode 100644 tests/lua/spec-collect-hashes.lua
 create mode 100644 tests/lua/spec-hash-tree.lua

diff --git a/src/collect-mcycle-hashes-state-access.h b/src/collect-mcycle-hashes-state-access.h
index c0c9a6223..10c569f7f 100644
--- a/src/collect-mcycle-hashes-state-access.h
+++ b/src/collect-mcycle-hashes-state-access.h
@@ -69,7 +69,7 @@ class collect_mcycle_hashes_state_access :
     using fast_addr_type = host_addr;
 
     void mark_dirty_word(uint64_t address) const {
-        constexpr uint64_t word_mask = ~UINT64_C(HASH_TREE_WORD_SIZE - 1);
+        constexpr uint64_t word_mask = ~(HASH_TREE_WORD_SIZE - 1);
         m_c.dirty_words.insert(address & word_mask);
     }
 
diff --git a/src/collect-uarch-cycle-hashes-state-access.h b/src/collect-uarch-cycle-hashes-state-access.h
index 097dfbb8f..b80f752fd 100644
--- a/src/collect-uarch-cycle-hashes-state-access.h
+++ b/src/collect-uarch-cycle-hashes-state-access.h
@@ -59,7 +59,7 @@ class collect_uarch_cycle_hashes_state_access :
 
 private:
     void mark_dirty_word(uint64_t address) const {
-        constexpr uint64_t word_mask = ~UINT64_C(HASH_TREE_WORD_SIZE - 1);
+        constexpr uint64_t word_mask = ~(HASH_TREE_WORD_SIZE - 1);
         m_c.dirty_words.insert(address & word_mask);
     }
 
diff --git a/src/hash-tree.cpp b/src/hash-tree.cpp
index 0fa36979b..5b2862fba 100644
--- a/src/hash-tree.cpp
+++ b/src/hash-tree.cpp
@@ -130,14 +130,14 @@ hash_tree::proof_type hash_tree::get_proof(address_ranges ars, uint64_t address,
         // hit pristine node
         if (is_pristine(node_index)) {
             get_pristine_proof(curr_log2_size, proof);
-            return proof;
+            break;
         }
         const auto &node = m_sparse_nodes[node_index];
         assert(static_cast<int>(node.log2_size) == curr_log2_size && "incorrect node log2_size");
         // hit sparse tree node
         if (curr_log2_size == log2_size) {
             proof.set_target_hash(node.hash);
-            return proof;
+            break;
         }
         // transition to dense tree
         if (is_ar_node(node)) {
@@ -145,7 +145,7 @@ hash_tree::proof_type hash_tree::get_proof(address_ranges ars, uint64_t address,
             const int ar_log2_size = HASH_TREE_LOG2_PAGE_SIZE + ar.get_level_count() - 1;
             assert(curr_log2_size == ar_log2_size && "incorrect ar node log2_size");
             get_dense_proof(ar, ar_log2_size, address, proof);
-            return proof;
+            break;
         }
         // go down left or right on sparse tree depending on address
         --curr_log2_size;
@@ -157,6 +157,7 @@ hash_tree::proof_type hash_tree::get_proof(address_ranges ars, uint64_t address,
             node_index = node.right;
         }
     }
+    return proof;
 }
 
 hash_tree_stats hash_tree::get_stats(bool clear) noexcept {
@@ -211,7 +212,7 @@ bool hash_tree::enqueue_hash_dirty_page(page_hash_tree_cache::simd_page_hasher<v
 bool hash_tree::return_updated_dirty_pages(address_ranges ars, dirty_pages &batch,
     changed_address_ranges &changed_ars) {
     if (batch.empty()) {
-        return true;
+        return false;
     }
     //??D The batch size past which we switch to parallel updates needs to be tuned empirically
     const int batch_size = static_cast<int>(batch.size());
@@ -577,6 +578,7 @@ bool hash_tree::verify(address_ranges ars) const {
             auto actually_dirty = !std::ranges::equal(page_hash, dht.node_hash_view(offset, HASH_TREE_LOG2_PAGE_SIZE));
             ar_actually_dirty = ar_actually_dirty || actually_dirty;
             auto marked_dirty = dpt.is_node_dirty(offset, HASH_TREE_LOG2_PAGE_SIZE);
+            // LCOV_EXCL_START
             if (actually_dirty != marked_dirty) {
                 if (!marked_dirty) {
                     ret = false;
@@ -621,6 +623,7 @@ bool hash_tree::verify(address_ranges ars) const {
         if (!std::ranges::equal(ar_node.hash, dht.node_hash_view(0, ar_log2_size))) {
             std::cerr << ar.get_description() << " dense hash tree root does not match sparse node hash\n";
         }
+        // LCOV_EXCL_STOP
         ++ar_node_index;
     }
     return ret;
@@ -641,7 +644,7 @@ bool hash_tree::update(address_ranges ars) {
 }
 
 bool hash_tree::update_words(address_ranges ars, dirty_words_type dirty_words) {
-    constexpr auto page_mask = ~UINT64_C(HASH_TREE_PAGE_SIZE - 1);
+    constexpr auto page_mask = ~(HASH_TREE_PAGE_SIZE - 1);
     // Dirty_words contains an unordered set of the address of all words that became dirty since last update
     // We copy these to a sorted vector "words"
     // Every word in the same page must be updated by the same thread
@@ -671,9 +674,6 @@ bool hash_tree::update_words(address_ranges ars, dirty_words_type dirty_words) {
     uint64_t update_failures{0}; // NOLINT(misc-const-correctness)
     int ar_index = 0;
     int max_level_count = 0;
-    variant_hasher h{m_hash_function};
-    std::vector<uint64_t> curr_page_node;
-    std::vector<uint64_t> next_page_node;
     dense_node_entries curr_dense_node;
     dense_node_entries next_dense_node;
     changed_address_ranges changed_ars;
@@ -688,13 +688,15 @@ bool hash_tree::update_words(address_ranges ars, dirty_words_type dirty_words) {
             continue;
         }
         auto &cache_entry = opt_br->get();
-        while (!ars[ar_index].contains_absolute(paddr_page, HASH_TREE_PAGE_SIZE)) {
-            if (ar_index >= static_cast<int>(ars.size())) {
-                ++update_failures;
-                m_page_cache.return_entry(cache_entry);
-                continue;
+        for (; ar_index < static_cast<int>(ars.size()); ++ar_index) {
+            if (ars[ar_index].contains_absolute(paddr_page, HASH_TREE_PAGE_SIZE)) {
+                break;
             }
-            ++ar_index;
+        }
+        if (ar_index >= static_cast<int>(ars.size())) {
+            ++update_failures;
+            m_page_cache.return_entry(cache_entry);
+            continue;
         }
         auto &ar = ars[ar_index];
         if (changed_ars.empty() || changed_ars.back() != ar_index) {
@@ -710,41 +712,30 @@ bool hash_tree::update_words(address_ranges ars, dirty_words_type dirty_words) {
         const auto page_offset = paddr_page - ar.get_start();
         // if we had a cache hit, update only the words that changed in the cache
         if (hit) {
-            auto page = std::span<const unsigned char, HASH_TREE_PAGE_SIZE>{base + page_offset, HASH_TREE_PAGE_SIZE};
+            variant_hasher h{m_hash_function};
+            page_hash_tree_cache::simd_page_hasher<variant_hasher> queue(h);
+            const auto page =
+                std::span<const unsigned char, HASH_TREE_PAGE_SIZE>{base + page_offset, HASH_TREE_PAGE_SIZE};
             auto &page_tree = cache_entry.get_page_hash_tree();
             const page_hash_tree_cache::page_view entry_page{cache_entry.get_page()};
-            curr_page_node.clear();
             for (auto word_address : std::span(words).subspan(begin, end - begin)) {
                 const auto word_offset = word_address - paddr_page;
-                const auto page_word = page.subspan(word_offset, HASH_TREE_WORD_SIZE);
-                const auto entry_word = entry_page.subspan(word_offset, HASH_TREE_WORD_SIZE);
-                auto index = (HASH_TREE_PAGE_SIZE + word_offset) / HASH_TREE_WORD_SIZE;
-                get_hash(h, page_word, page_tree[index]);
+                const auto page_word =
+                    std::span<const unsigned char, HASH_TREE_WORD_SIZE>{page.subspan(word_offset, HASH_TREE_WORD_SIZE)};
+                const auto entry_word =
+                    std::span<unsigned char, HASH_TREE_WORD_SIZE>{entry_page.subspan(word_offset, HASH_TREE_WORD_SIZE)};
+                const auto index = static_cast<int>((HASH_TREE_PAGE_SIZE + word_offset) / HASH_TREE_WORD_SIZE);
+                queue.enqueue_leaf(page_word, page_tree, index);
                 std::ranges::copy(page_word, entry_word.begin());
-                auto parent = index / 2;
-                if (curr_page_node.empty() || curr_page_node.back() != parent) {
-                    curr_page_node.push_back(parent);
-                }
-            }
-            for (int log2_size = HASH_TREE_LOG2_WORD_SIZE + 1; log2_size <= HASH_TREE_LOG2_PAGE_SIZE; ++log2_size) {
-                next_page_node.clear();
-                for (auto index : curr_page_node) {
-                    auto left = index * 2;
-                    auto right = (index * 2) + 1;
-                    get_concat_hash(h, page_tree[left], page_tree[right], page_tree[index]);
-                    auto parent = index / 2;
-                    if (next_page_node.empty() || next_page_node.back() != parent) { // We know parent != 0
-                        next_page_node.push_back(parent);
-                    }
-                }
-                std::swap(curr_page_node, next_page_node);
             }
+            queue.flush();
             // otherwise, the update from scratch
         } else {
             bool changed = false;
             if (!update_dirty_page(ar, cache_entry, changed)) {
                 ++update_failures;
                 m_page_cache.return_entry(cache_entry);
+                continue;
             }
         }
         auto &dht = ar.get_dense_hash_tree();
@@ -760,17 +751,20 @@ bool hash_tree::update_words(address_ranges ars, dirty_words_type dirty_words) {
     for (int level = 1; level < max_level_count; ++level) {
         auto log2_size = HASH_TREE_LOG2_PAGE_SIZE + level;
         next_dense_node.clear();
+        variant_hasher h{m_hash_function};
+        simd_concat_hasher<variant_hasher, const_machine_hash_view> queue(h);
         for (auto &[dht, offset] : curr_dense_node) {
             auto child_size = UINT64_C(1) << (log2_size - 1);
             auto parent = dht.node_hash_view(offset, log2_size);
             auto left = dht.node_hash_view(offset, log2_size - 1);
             auto right = dht.node_hash_view(offset + child_size, log2_size - 1);
-            get_concat_hash(h, left, right, parent);
+            queue.enqueue(left, right, parent);
             auto dense_node = dense_node_entry{.dht = dht, .offset = get_aligned_address(offset, log2_size + 1)};
             if (next_dense_node.empty() || next_dense_node.back() != dense_node) {
                 next_dense_node.push_back(dense_node);
             }
         }
+        queue.flush();
         std::swap(curr_dense_node, next_dense_node);
     }
     return !static_cast<bool>(update_failures > 0) && update_sparse_tree(ars, changed_ars);
@@ -990,6 +984,7 @@ hash_tree::nodes_type hash_tree::create_nodes(const_address_ranges ars) {
     return nodes;
 }
 
+// LCOV_EXCL_START
 void hash_tree::dump(const_address_ranges ars, std::ostream &out) {
     out << "digraph HashTree {\n";
     out << "  rankdir=TB;\n";
@@ -1059,5 +1054,6 @@ void hash_tree::dump(const_address_ranges ars, std::ostream &out) {
     }
     out << "}\n";
 }
+// LCOV_EXCL_STOP
 
 } // namespace cartesi
diff --git a/src/page-hash-tree-cache.h b/src/page-hash-tree-cache.h
index fbab45bd5..0b2e6fdb3 100644
--- a/src/page-hash-tree-cache.h
+++ b/src/page-hash-tree-cache.h
@@ -408,6 +408,9 @@ class page_hash_tree_cache {
         m_pristine_page_hash_tree{entry::get_pristine_page_hash_tree(std::forward<H>(h))},
         m_entries{num_entries, entry{m_pristine_page_hash_tree}} {
         m_map.reserve(num_entries);
+        if (num_entries == 0) {
+            throw std::invalid_argument{"page hash-tree cache must have at least one entry"};
+        }
     }
 
     page_hash_tree_cache(const page_hash_tree_cache &other) = delete;
diff --git a/tests/Makefile b/tests/Makefile
index 1ceb1ec19..114f731fe 100644
--- a/tests/Makefile
+++ b/tests/Makefile
@@ -188,9 +188,6 @@ test-machine-with-log-step:
 test-uarch:
 	$(LUA) ./lua/cartesi-machine-tests.lua --jobs=$(NUM_JOBS) run_uarch
 
-test-hash-tree:
-	$(LUA) ./lua/hash-tree.lua
-
 test-uarch-compare:
 	$(LUA) ./lua/cartesi-machine-tests.lua --test="^rv64ui.*$$" --concurrency=update_hash_tree:1 --jobs=$(NUM_JOBS) run_host_and_uarch
 
@@ -257,7 +254,7 @@ coverage-report: $(COVERAGE_OUTPUT_DIR)
 export LLVM_PROFILE_FILE=coverage-%p.profraw
 endif
 
-test: test-save-and-load test-yield-and-save test-machine test-uarch test-uarch-rv64ui test-uarch-interpreter test-hash-tree test-lua test-jsonrpc test-c-api test-hash test-cmio test-machine-with-log-step
+test: test-save-and-load test-yield-and-save test-machine test-uarch test-uarch-rv64ui test-uarch-interpreter test-lua test-jsonrpc test-c-api test-hash test-cmio test-machine-with-log-step
 
 lint format check-format:
 	@$(MAKE) -C misc $@
diff --git a/tests/lua/hash-tree.lua b/tests/lua/hash-tree.lua
deleted file mode 100755
index 4eeb05cc7..000000000
--- a/tests/lua/hash-tree.lua
+++ /dev/null
@@ -1,273 +0,0 @@
-#!/usr/bin/env lua5.4
-
--- Copyright Cartesi and individual authors (see AUTHORS)
--- SPDX-License-Identifier: LGPL-3.0-or-later
---
--- This program is free software: you can redistribute it and/or modify it under
--- the terms of the GNU Lesser General Public License as published by the Free
--- Software Foundation, either version 3 of the License, or (at your option) any
--- later version.
---
--- This program is distributed in the hope that it will be useful, but WITHOUT ANY
--- WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
--- PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
---
--- You should have received a copy of the GNU Lesser General Public License along
--- with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
---
-local cartesi = require("cartesi")
-local test_util = require("cartesi.tests.util")
-local tohex = test_util.tohex
-
-local function stderr(...)
-    io.stderr:write((string.format(...)))
-end
-
-local function bit_ceil(n)
-    if n == 0 then
-        return 0
-    end
-    n = n - 1
-    n = n | (n >> 1)
-    n = n | (n >> 2)
-    n = n | (n >> 4)
-    n = n | (n >> 8)
-    n = n | (n >> 16)
-    n = n | (n >> 32)
-    return n + 1
-end
-
-local LOG2_ROOT_SIZE = 64
-local LOG2_PAGE_SIZE = 12
-local PAGE_SIZE = 1 << LOG2_PAGE_SIZE
-local LOG2_WORD_SIZE = 5
-local WORD_SIZE = 1 << LOG2_WORD_SIZE
-
-local function get_sibling_address(address, log2_size)
-    local bit = 1 << log2_size
-    local mask = ~(bit - 1)
-    return (address ~ bit) & mask
-end
-
-local function get_aligned_address(address, log2_size)
-    local bit = 1 << log2_size
-    local mask = ~(bit - 1)
-    return address & mask
-end
-
-local function get_proof(m, target_address, log2_target_size)
-    local proof = {
-        log2_root_size = LOG2_ROOT_SIZE,
-        log2_target_size = log2_target_size,
-        root_hash = m:get_root_hash(),
-        target_address = target_address,
-        target_hash = m:get_node_hash(target_address, log2_target_size),
-        sibling_hashes = {},
-    }
-    for log2_size = log2_target_size, 63 do
-        table.insert(proof.sibling_hashes, m:get_node_hash(get_sibling_address(target_address, log2_size), log2_size))
-    end
-    return proof
-end
-
-local function compare_proofs(p1, p2, padding)
-    padding = padding or ""
-    if p1.target_address ~= p2.target_address then
-        stderr("%starget address mismatch\n", padding)
-        return false
-    end
-    if p1.log2_target_size ~= p2.log2_target_size then
-        stderr("%slog2_size mismatch\n", padding)
-        return false
-    end
-    if p1.root_hash ~= p2.root_hash then
-        stderr("%sroot hash mismatch\n", padding)
-        return false
-    end
-    if p1.target_hash ~= p2.target_hash then
-        stderr("%starget hash mismatch\n", padding)
-        return false
-    end
-    if #p1.sibling_hashes ~= #p2.sibling_hashes then
-        stderr("%starget hash mismatch\n", padding)
-        return false
-    end
-    for i = 1, #p1.sibling_hashes do
-        if p1.sibling_hashes[i] ~= p2.sibling_hashes[i] then
-            stderr("%ssibling hash mismatch (%d)\n", padding, i + p1.log2_target_size - 1)
-            return false
-        end
-    end
-    return true
-end
-
-local function check_proof(proof, hash_fn)
-    local hash = proof.target_hash
-    for log2_size = proof.log2_target_size, proof.log2_root_size - 1 do
-        local bit = 1 << log2_size
-        local first, second
-        local sibling_hash = proof.sibling_hashes[log2_size - proof.log2_target_size + 1]
-        if (proof.target_address & bit) ~= 0 then
-            first, second = sibling_hash, hash
-        else
-            first, second = hash, sibling_hash
-        end
-        hash = cartesi[hash_fn](first, second)
-    end
-    return hash == proof.root_hash
-end
-
-local config = {
-    hash_tree = {
-        phtc_size = 0x800, -- default
-    },
-    ram = {
-        backing_store = {
-            data_filename = test_util.tests_path .. "rv64ui-p-addi.bin",
-        },
-        length = 0x10000,
-    },
-    flash_drive = {
-        { start = 0x90000000, length = 0x100000 },
-        { start = 0xa0000000, length = 0x100000 },
-    },
-}
-
-local function check_root_hash(m)
-    local sh = test_util.calculate_emulator_hash(m)
-    local rh = m:get_root_hash()
-    local nh = m:get_node_hash(0, LOG2_ROOT_SIZE)
-    if sh ~= nh or sh ~= rh then
-        stderr("    0x%.16s state hash \n", tohex(sh))
-        stderr("    0x%.16s root hash \n", tohex(rh))
-        stderr("    0x%.16s node hash \n", tohex(nh))
-        os.exit(1)
-    end
-end
-
-local machine = cartesi.machine(config)
-check_root_hash(machine)
-machine:run(math.maxinteger)
-check_root_hash(machine)
-
-local interesting_pages = {}
--- add first, middle, and last page of each range and gap
-local last_end = 0
-for _, v in ipairs(machine:get_address_ranges()) do
-    if math.ult(v.start, last_end) then
-        stderr("range %s, when rounded up to power of two length, overlaps with previous range", v.description)
-        os.exit(1)
-    end
-    if last_end < v.start then
-        local gap = { start = last_end, length = v.start - last_end, description = "gap" }
-        local s = last_end
-        local e = v.start - PAGE_SIZE
-        local m = (((s + e) / 2) >> LOG2_PAGE_SIZE) << LOG2_PAGE_SIZE
-        table.insert(interesting_pages, { s, gap })
-        if not math.ult(s + PAGE_SIZE, m) then
-            table.insert(interesting_pages, { m, gap })
-        end
-        if not math.ult(m + PAGE_SIZE, e) then
-            table.insert(interesting_pages, { e, gap })
-        end
-    end
-    local s = v.start
-    local e = s + v.length - PAGE_SIZE
-    local m = (((s + e) / 2) >> LOG2_PAGE_SIZE) << LOG2_PAGE_SIZE
-    if not math.ult(s + PAGE_SIZE, m) then
-        table.insert(interesting_pages, { m, v })
-    end
-    if not math.ult(m + PAGE_SIZE, e) then
-        table.insert(interesting_pages, { e, v })
-    end
-    table.insert(interesting_pages, { s, v })
-    last_end = v.start + bit_ceil(v.length)
-end
-table.insert(interesting_pages, { last_end, { start = last_end, length = -last_end, description = "pad" } })
-table.insert(interesting_pages, { -PAGE_SIZE, { start = last_end, length = -last_end, description = "pad" } })
-
--- check all page hashes
-print("checking all page hashes")
-local hash_fn = machine:get_initial_config().hash_tree.hash_function
-for _, v in ipairs(machine:get_address_ranges()) do
-    for address = v.start, v.start + v.length - 1, PAGE_SIZE do
-        local h1 = machine:get_node_hash(address, LOG2_PAGE_SIZE)
-        local h2 = test_util.merkle_hash(machine:read_memory(address, PAGE_SIZE), 0, LOG2_PAGE_SIZE, hash_fn)
-        if h1 ~= h2 then
-            stderr("hash mismatch on page 0x%016x (offset 0x%016x in %s)\n", address, address - v.start, v.description)
-            stderr("    0x%.16s... vs 0x%.16s...\n", tohex(h1), tohex(h2))
-            os.exit(1)
-        end
-    end
-end
-
-stderr("checking all hashes in the page hash tree for a few pages\n")
-for _, p in ipairs(interesting_pages) do
-    local page, v = table.unpack(p)
-    stderr("    page 0x%016x is in %s 0x%016x:0x%x\n", page, v.description, v.start, v.length)
-    local hashes = {}
-    for address = page, page + PAGE_SIZE - 1, WORD_SIZE do
-        local h1 = machine:get_node_hash(address, LOG2_WORD_SIZE)
-        local word = machine:read_memory(address, WORD_SIZE)
-        local h2 = cartesi[hash_fn](word)
-        if h1 ~= h2 then
-            stderr("        hash mismatch on word 0x%016x (%u)\n", address, address)
-            stderr("            0x%.16s... vs 0x%.16s...\n", tohex(h1), tohex(h2))
-            os.exit(1)
-        end
-        hashes[#hashes + 1] = h2
-    end
-    for log2_size = LOG2_WORD_SIZE + 1, LOG2_PAGE_SIZE do
-        local new_hashes = {}
-        for i = 1, #hashes - 1, 2 do
-            new_hashes[#new_hashes + 1] = cartesi[hash_fn](hashes[i], hashes[i + 1])
-        end
-        hashes = new_hashes
-        for i = 1, #hashes do
-            local address = page + (i - 1) * (1 << log2_size)
-            local h1 = machine:get_node_hash(address, log2_size)
-            local h2 = hashes[i]
-            if h1 ~= h2 then
-                stderr("        hash mismatch on 0x%016x:%d\n", address, log2_size)
-                stderr("            0x%.16s... vs 0x%.16s...\n", tohex(h1), tohex(h2))
-                os.exit(1)
-            end
-        end
-    end
-end
-
-stderr("checking proofs for all words (and up) in a few pages\n")
-for log2_size = LOG2_WORD_SIZE, LOG2_ROOT_SIZE - 1 do
-    stderr("  checking log2 size %u ---\n", log2_size)
-    local size = 1 << log2_size
-    local last_address = -1
-    for _, p in ipairs(interesting_pages) do
-        local page = table.unpack(p)
-        local base = get_aligned_address(page, log2_size)
-        if math.ult(last_address, base) or last_address == -1 then
-            if base ~= last_address then
-                for address = base, base + size - 1, size do
-                    if address ~= last_address then
-                        local mproof = machine:get_proof(address, log2_size)
-                        local oproof = get_proof(machine, address, log2_size)
-                        if not compare_proofs(mproof, oproof, "        ") then
-                            stderr("    proof mismatch for offset 0x%016x (%u)\n", address, address)
-                        end
-                        if not check_proof(oproof, hash_fn) then
-                            stderr("    test proof for offset 0x%016x (%u) failed\n", address, address)
-                            os.exit(1)
-                        end
-                        if not check_proof(mproof, hash_fn) then
-                            stderr("    machine proof for offset 0x%016x (%u) failed\n", address, address)
-                            os.exit(1)
-                        end
-                    end
-                    last_address = address
-                end
-            end
-            last_address = get_aligned_address(base + size - 1, log2_size)
-        end
-    end
-end
-
-stderr("ok\n")
diff --git a/tests/lua/spec-collect-hashes.lua b/tests/lua/spec-collect-hashes.lua
new file mode 100644
index 000000000..94520fe53
--- /dev/null
+++ b/tests/lua/spec-collect-hashes.lua
@@ -0,0 +1,153 @@
+--[[
+Test suite for computation hashes.
+]]
+
+local lester = require("cartesi.third-party.lester")
+local describe, it, expect = lester.describe, lester.it, lester.expect
+local cartesi = require("cartesi")
+local util = require("cartesi.tests.util")
+
+local function expect_consistent_root_hash(machine)
+    expect.truthy(machine:verify_hash_tree())
+    local root_hash = machine:get_root_hash()
+    local external_root_hash = util.calculate_emulator_hash(machine)
+    local node_hash = machine:get_node_hash(0, cartesi.TREE_LOG2_ROOT_SIZE)
+    expect.truthy(machine:verify_hash_tree())
+    expect.equal(root_hash, node_hash)
+    expect.equal(external_root_hash, root_hash)
+end
+
+local function expect_mcycle_root_hashes(machine, mcycle_phase, mcycle_period, period_count)
+    local break_reason
+    local hashes = {}
+    local mcycle_start = machine:read_reg("mcycle") - mcycle_phase
+    local mcycle_max = mcycle_start + (period_count * mcycle_period)
+    for mcycle = mcycle_start + mcycle_period, mcycle_max, mcycle_period do
+        break_reason = machine:run(mcycle)
+        expect_consistent_root_hash(machine)
+        if break_reason ~= cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE then
+            break
+        end
+        table.insert(hashes, machine:get_root_hash())
+    end
+    local mcycle = machine:read_reg("mcycle")
+    mcycle_phase = mcycle % mcycle_period
+    return {
+        hashes = hashes,
+        break_reason = break_reason,
+        mcycle_phase = mcycle_phase,
+    }
+end
+
+local function expect_uarch_cycle_root_hashes(machine, mcycle_count)
+    local hashes = {}
+    local reset_indices = {}
+    local break_reason = "reached_target_mcycle"
+    local initial_mcycle = machine:read_reg("mcycle")
+    for mcycle = initial_mcycle + 1, initial_mcycle + mcycle_count do
+        if machine:read_reg("iflags_H") ~= 0 then
+            break_reason = "halted"
+            break
+        end
+        if machine:read_reg("iflags_X") ~= 0 then
+            break_reason = "yielded_automatically"
+            break
+        end
+        if machine:read_reg("iflags_Y") ~= 0 then
+            break_reason = "yielded_manually"
+            break
+        end
+        expect.equal(machine:read_reg("uarch_cycle"), 0)
+        for uarch_cycle = 1, math.maxinteger do
+            if machine:run_uarch(uarch_cycle) == cartesi.UARCH_BREAK_REASON_UARCH_HALTED then
+                break
+            end
+            table.insert(hashes, machine:get_root_hash())
+            if uarch_cycle % 200 == 0 then -- checking every step would be very slow in CI
+                expect_consistent_root_hash(machine)
+            end
+        end
+        expect.equal(machine:read_reg("uarch_halt_flag"), 1)
+        expect_consistent_root_hash(machine)
+        machine:reset_uarch()
+        expect_consistent_root_hash(machine)
+        expect.equal(machine:read_reg("mcycle"), mcycle)
+        table.insert(hashes, machine:get_root_hash())
+        table.insert(reset_indices, #hashes)
+    end
+    return {
+        hashes = hashes,
+        reset_indices = reset_indices,
+        break_reason = break_reason,
+    }
+end
+
+describe("collect hashes", function()
+    for _, hash_function in pairs({ "sha256", "keccak256" }) do
+        describe(hash_function, function()
+            local test_machine_config = {
+                ram = {
+                    length = 8191 * 4096, -- non power of 2 on purpose to exercise address range boundaries
+                    backing_store = {
+                        data_filename = util.images_path .. "linux.bin",
+                    },
+                },
+                flash_drive = {
+                    { length = 13 * 4096 }, -- non power of 2 on purpose to exercise address range boundaries
+                },
+                dtb = {
+                    -- let it boot and panic silently when failing to find rootfs
+                    bootargs = cartesi.machine:get_default_config().dtb.bootargs .. " loglevel=0",
+                },
+                hash_tree = {
+                    hash_function = hash_function,
+                },
+            }
+
+            local test_last_mcycle
+            local test_last_root_hash
+
+            it("should match sparse periodic root hashes", function()
+                local machine <close> = cartesi.machine(test_machine_config)
+                local collect_machine <close> = cartesi.machine(test_machine_config)
+                expect_consistent_root_hash(machine)
+                expect.equal(machine:get_root_hash(), collect_machine:get_root_hash())
+                local mcycle_phase = 0
+                local mcycle_period = 8 * 1024 * 1024
+                local period_count = 16
+                local collected = collect_machine:collect_mcycle_root_hashes(mcycle_phase, mcycle_period, period_count)
+                local expected_collected = expect_mcycle_root_hashes(machine, mcycle_phase, mcycle_period, period_count)
+                local halt_exit_code = machine:read_reg("htif_tohost_data") >> 1
+                expect.equal(collected, expected_collected)
+                expect.equal(collect_machine:get_root_hash(), machine:get_root_hash())
+                expect.equal(collected.break_reason, cartesi.BREAK_REASON_HALTED)
+                expect.equal(halt_exit_code, 255)
+                test_last_mcycle = machine:read_reg("mcycle")
+                test_last_root_hash = machine:get_root_hash()
+            end)
+
+            if hash_function == "keccak256" then
+                it("should match dense uarch root hashes", function()
+                    expect.truthy(test_last_mcycle ~= nil and test_last_root_hash ~= nil)
+                    local machine <close> = cartesi.machine(test_machine_config)
+                    local collect_machine <close> = cartesi.machine(test_machine_config)
+                    local mcycle_count = 2
+                    expect.equal(
+                        machine:run(test_last_mcycle - mcycle_count),
+                        cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE
+                    )
+                    expect_consistent_root_hash(machine)
+                    collect_machine:run(test_last_mcycle - mcycle_count)
+                    expect.equal(machine:get_root_hash(), collect_machine:get_root_hash())
+                    local collected = collect_machine:collect_uarch_cycle_root_hashes(mcycle_count)
+                    local expected_collected = expect_uarch_cycle_root_hashes(machine, mcycle_count)
+                    local halt_exit_code = machine:read_reg("htif_tohost_data") >> 1
+                    expect.equal(collected, expected_collected)
+                    expect.equal(machine:read_reg("mcycle"), test_last_mcycle)
+                    expect.equal(machine:get_root_hash(), test_last_root_hash)
+                    expect.equal(halt_exit_code, 255)
+                end)
+            end
+        end)
+    end
+end)
diff --git a/tests/lua/spec-hash-tree.lua b/tests/lua/spec-hash-tree.lua
new file mode 100644
index 000000000..1caf6f323
--- /dev/null
+++ b/tests/lua/spec-hash-tree.lua
@@ -0,0 +1,296 @@
+--[[
+Test suite for hash trees.
+Specifically, it provides test coverage for:
+    hash-tree.cpp
+    page-hash-tree-cache.h
+Can be run independently during development the mentioned files.
+]]
+
+local lester = require("cartesi.third-party.lester")
+local describe, it, expect = lester.describe, lester.it, lester.expect
+local cartesi = require("cartesi")
+local util = require("cartesi.tests.util")
+
+local LOG2_ROOT_SIZE = 64
+local LOG2_PAGE_SIZE = 12
+local PAGE_SIZE = 1 << LOG2_PAGE_SIZE
+local LOG2_WORD_SIZE = 5
+local WORD_SIZE = 1 << LOG2_WORD_SIZE
+
+local function bit_ceil(n)
+    if n == 0 then
+        return 0
+    end
+    n = n - 1
+    n = n | (n >> 1)
+    n = n | (n >> 2)
+    n = n | (n >> 4)
+    n = n | (n >> 8)
+    n = n | (n >> 16)
+    n = n | (n >> 32)
+    return n + 1
+end
+
+local function get_sibling_address(address, log2_size)
+    local bit = 1 << log2_size
+    local mask = ~(bit - 1)
+    return (address ~ bit) & mask
+end
+
+local function get_aligned_address(address, log2_size)
+    local bit = 1 << log2_size
+    local mask = ~(bit - 1)
+    return address & mask
+end
+
+local function get_proof(m, target_address, log2_target_size)
+    local proof = {
+        log2_root_size = LOG2_ROOT_SIZE,
+        log2_target_size = log2_target_size,
+        root_hash = m:get_root_hash(),
+        target_address = target_address,
+        target_hash = m:get_node_hash(target_address, log2_target_size),
+        sibling_hashes = {},
+    }
+    for log2_size = log2_target_size, 63 do
+        table.insert(proof.sibling_hashes, m:get_node_hash(get_sibling_address(target_address, log2_size), log2_size))
+    end
+    return proof
+end
+
+local function expect_consistent_proof(proof, hash_fn)
+    local hash = proof.target_hash
+    for log2_size = proof.log2_target_size, proof.log2_root_size - 1 do
+        local bit = 1 << log2_size
+        local first, second
+        local sibling_hash = proof.sibling_hashes[log2_size - proof.log2_target_size + 1]
+        if (proof.target_address & bit) ~= 0 then
+            first, second = sibling_hash, hash
+        else
+            first, second = hash, sibling_hash
+        end
+        hash = cartesi[hash_fn](first, second)
+    end
+    expect.equal(proof.root_hash, hash)
+end
+
+local function expect_consistent_root_hash(machine)
+    expect.truthy(machine:verify_hash_tree())
+    local root_hash = machine:get_root_hash()
+    local external_root_hash = util.calculate_emulator_hash(machine)
+    expect.truthy(machine:verify_hash_tree())
+    local node_hash = machine:get_node_hash(0, cartesi.TREE_LOG2_ROOT_SIZE)
+    expect.truthy(root_hash == node_hash)
+    expect.equal(root_hash, external_root_hash)
+end
+
+describe("hash tree", function()
+    for _, hash_function in ipairs({ "keccak256", "sha256" }) do
+        describe(hash_function, function()
+            local function make_machine(o)
+                return cartesi.machine({
+                    hash_tree = {
+                        hash_function = hash_function,
+                        phtc_size = o and o.phtc_size,
+                    },
+                    ram = {
+                        backing_store = {
+                            data_filename = util.tests_path .. "rv64ui-p-addi.bin",
+                        },
+                        length = 0x10000,
+                    },
+                    flash_drive = {
+                        { start = 0x90000000, length = 0x20000 },
+                        { start = 0xa0000000, length = 0x200000 },
+                    },
+                })
+            end
+            local machine <close> = make_machine()
+
+            it("should have consistent root hash", function()
+                expect_consistent_root_hash(machine)
+                machine:run()
+                expect_consistent_root_hash(machine)
+                expect.equal(machine:get_root_hash(), machine:get_node_hash(0, LOG2_ROOT_SIZE))
+            end)
+
+            it("should have consistent root hash when using different phct sizes", function()
+                for _, phtc_size in pairs({ 1, 2, 3, 4 }) do
+                    local temp_machine <close> = make_machine({ phtc_size = phtc_size })
+                    expect_consistent_root_hash(temp_machine)
+                    temp_machine:run()
+                    expect_consistent_root_hash(temp_machine)
+                end
+            end)
+
+            it("should fail on invalid API calls", function()
+                expect.fail(function()
+                    machine:get_proof(0, LOG2_ROOT_SIZE + 1)
+                end, "invalid log2_size")
+                expect.fail(function()
+                    machine:get_proof(0, LOG2_WORD_SIZE - 1)
+                end, "invalid log2_size")
+                expect.fail(function()
+                    machine:get_proof(1, LOG2_ROOT_SIZE)
+                end, "address not aligned to log2_size")
+                expect.fail(function()
+                    machine:get_proof(LOG2_WORD_SIZE + 1, LOG2_WORD_SIZE)
+                end, "address not aligned to log2_size")
+                expect.fail(function()
+                    machine:get_node_hash(0, LOG2_ROOT_SIZE + 1)
+                end, "invalid log2_size")
+                expect.fail(function()
+                    machine:get_node_hash(0, LOG2_WORD_SIZE - 1)
+                end, "invalid log2_size")
+                expect.fail(function()
+                    machine:get_node_hash(1, LOG2_ROOT_SIZE)
+                end, "address not aligned to log2_size")
+                expect.fail(function()
+                    machine:get_node_hash(LOG2_WORD_SIZE + 1, LOG2_WORD_SIZE)
+                end, "address not aligned to log2_size")
+                expect.fail(function()
+                    cartesi.machine({
+                        ram = { length = 0x1000 },
+                        hash_tree = {
+                            hash_function = hash_function,
+                            phtc_size = 0,
+                        },
+                    })
+                end, "page hash-tree cache must have at least one entry")
+            end)
+
+            it("should retrieve hash tree stats", function()
+                local hash_tree_stats = machine:get_hash_tree_stats(true)
+                expect.equal(#hash_tree_stats.dense_node_hashes, 64)
+                expect.truthy(hash_tree_stats.sparse_node_hashes > 0)
+                expect.truthy(hash_tree_stats.phtc.inner_page_hashes > 0)
+                expect.truthy((hash_tree_stats.phtc.page_hits + hash_tree_stats.phtc.page_misses) > 0)
+                expect.truthy((hash_tree_stats.phtc.word_hits + hash_tree_stats.phtc.word_misses) > 0)
+                expect.truthy((hash_tree_stats.phtc.pristine_pages + hash_tree_stats.phtc.non_pristine_pages) > 0)
+                hash_tree_stats = machine:get_hash_tree_stats()
+                expect.equal(#hash_tree_stats.dense_node_hashes, 64)
+                expect.equal(hash_tree_stats.sparse_node_hashes, 0)
+                expect.equal(hash_tree_stats.phtc.inner_page_hashes, 0)
+                expect.equal((hash_tree_stats.phtc.page_hits + hash_tree_stats.phtc.page_misses), 0)
+                expect.equal((hash_tree_stats.phtc.word_hits + hash_tree_stats.phtc.word_misses), 0)
+                expect.equal((hash_tree_stats.phtc.pristine_pages + hash_tree_stats.phtc.non_pristine_pages), 0)
+            end)
+
+            it("should have consistent page hashes", function()
+                for _, v in ipairs(machine:get_address_ranges()) do
+                    for address = v.start, v.start + v.length - 1, PAGE_SIZE do
+                        local node_hash = machine:get_node_hash(address, LOG2_PAGE_SIZE)
+                        local external_node_hash =
+                            util.merkle_hash(machine:read_memory(address, PAGE_SIZE), 0, LOG2_PAGE_SIZE, hash_function)
+                        expect.equal(node_hash, external_node_hash)
+                    end
+                end
+            end)
+
+            local interesting_pages = {}
+            do -- fill interesting pages
+                -- add first, middle, and last page of each range and gap
+                local last_end = 0
+                for _, v in ipairs(machine:get_address_ranges()) do
+                    assert(not math.ult(v.start, last_end))
+                    if last_end < v.start then
+                        local gap = { start = last_end, length = v.start - last_end, description = "gap" }
+                        local s = last_end
+                        local e = v.start - PAGE_SIZE
+                        local m = (((s + e) / 2) >> LOG2_PAGE_SIZE) << LOG2_PAGE_SIZE
+                        table.insert(interesting_pages, { s, gap })
+                        if not math.ult(s + PAGE_SIZE, m) then
+                            table.insert(interesting_pages, { m, gap })
+                        end
+                        if not math.ult(m + PAGE_SIZE, e) then
+                            table.insert(interesting_pages, { e, gap })
+                        end
+                    end
+                    local s = v.start
+                    local e = s + v.length - PAGE_SIZE
+                    local m = (((s + e) / 2) >> LOG2_PAGE_SIZE) << LOG2_PAGE_SIZE
+                    if m ~= s and not math.ult(s + PAGE_SIZE, m) then
+                        table.insert(interesting_pages, { m, v })
+                    end
+                    if e ~= s and e ~= m and not math.ult(m + PAGE_SIZE, e) then
+                        table.insert(interesting_pages, { e, v })
+                    end
+                    table.insert(interesting_pages, { s, v })
+                    last_end = v.start + bit_ceil(v.length)
+                end
+                table.insert(
+                    interesting_pages,
+                    { last_end, { start = last_end, length = -last_end, description = "pad" } }
+                )
+                table.insert(
+                    interesting_pages,
+                    { -PAGE_SIZE, { start = last_end, length = -last_end, description = "pad" } }
+                )
+            end
+
+            it("should have consistent hashes in the page hash tree for a few pages", function()
+                local clone_machine <close> = make_machine({ phtc_size = 1 })
+                clone_machine:run()
+                for _, p in ipairs(interesting_pages) do
+                    local page = table.unpack(p)
+                    local hashes = {}
+                    for address = page, page + PAGE_SIZE - 1, WORD_SIZE do
+                        local node_hash = machine:get_node_hash(address, LOG2_WORD_SIZE)
+                        local clone_node_hash = clone_machine:get_node_hash(address, LOG2_WORD_SIZE)
+                        local word = machine:read_memory(address, WORD_SIZE)
+                        local external_node_hash = cartesi[hash_function](word)
+                        expect.equal(node_hash, external_node_hash)
+                        expect.equal(node_hash, clone_node_hash)
+                        hashes[#hashes + 1] = external_node_hash
+                    end
+                    for log2_size = LOG2_WORD_SIZE + 1, LOG2_PAGE_SIZE do
+                        local new_hashes = {}
+                        for i = 1, #hashes - 1, 2 do
+                            new_hashes[#new_hashes + 1] = cartesi[hash_function](hashes[i], hashes[i + 1])
+                        end
+                        hashes = new_hashes
+                        for i = 1, #hashes do
+                            local address = page + (i - 1) * (1 << log2_size)
+                            local node_hash = machine:get_node_hash(address, log2_size)
+                            local clone_node_hash = clone_machine:get_node_hash(address, log2_size)
+                            local external_node_hash = hashes[i]
+                            expect.equal(node_hash, external_node_hash)
+                            expect.equal(node_hash, clone_node_hash)
+                        end
+                    end
+                end
+            end)
+
+            it("should have consistent proofs for all words (and up) in a few pages", function()
+                local clone_machine <close> = make_machine({ phtc_size = 1 })
+                clone_machine:run()
+                for log2_size = LOG2_WORD_SIZE, LOG2_ROOT_SIZE - 1 do
+                    local size = 1 << log2_size
+                    local last_address = -1
+                    for _, p in ipairs(interesting_pages) do
+                        local page = table.unpack(p)
+                        local base = get_aligned_address(page, log2_size)
+                        if math.ult(last_address, base) or last_address == -1 then
+                            if base ~= last_address then
+                                for address = base, base + size - 1, size do
+                                    if address ~= last_address then
+                                        local mproof = machine:get_proof(address, log2_size)
+                                        local cproof = clone_machine:get_proof(address, log2_size)
+                                        local oproof = get_proof(machine, address, log2_size)
+                                        expect_consistent_proof(oproof, hash_function)
+                                        expect_consistent_proof(mproof, hash_function)
+                                        expect_consistent_proof(cproof, hash_function)
+                                        expect.equal(mproof, oproof)
+                                        expect.equal(mproof, cproof)
+                                    end
+                                    last_address = address
+                                end
+                            end
+                            last_address = get_aligned_address(base + size - 1, log2_size)
+                        end
+                    end
+                end
+            end)
+        end)
+    end
+end)
diff --git a/tests/lua/test-spec.lua b/tests/lua/test-spec.lua
index cc36a8f68..1046d8ea6 100755
--- a/tests/lua/test-spec.lua
+++ b/tests/lua/test-spec.lua
@@ -22,6 +22,8 @@ local lester = require("cartesi.third-party.lester")
 lester.parse_args()
 
 require("spec-hash-functions")
+require("spec-hash-tree")
+require("spec-collect-hashes")
 
 lester.report() -- Print overall statistic of the tests run.
 lester.exit() -- Exit with success if all tests passed.

From 993098dfd4476e4af40312f9210b87ad86226b41 Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Mon, 25 Aug 2025 17:50:52 -0300
Subject: [PATCH 61/82] feat: bundle ankerl::unordered_dense third party
 library

---
 LICENSES.md                          |    1 +
 src/Makefile                         |    1 +
 tests/misc/Makefile                  |    2 +-
 third-party/ankerl/LICENSE           |   21 +
 third-party/ankerl/unordered_dense.h | 2101 ++++++++++++++++++++++++++
 5 files changed, 2125 insertions(+), 1 deletion(-)
 create mode 100644 third-party/ankerl/LICENSE
 create mode 100644 third-party/ankerl/unordered_dense.h

diff --git a/LICENSES.md b/LICENSES.md
index 89a7f8ac4..0569ab0ba 100644
--- a/LICENSES.md
+++ b/LICENSES.md
@@ -8,6 +8,7 @@ This project includes several submodules and dependencies, each with its own lic
 
 - `tests/machine`: Licensed under the Apache License 2.0. See the license terms in [tests/machine/LICENSE](tests/machine/LICENSE).
 - `tests/uarch`: Licensed under the Apache License 2.0. Licensing details are available in [tests/uarch/LICENSE](tests/uarch/LICENSE).
+- `third-party/ankerl`: Licensed under the MIT License. The license can be found at [third-party/ankerl/LICENSE](third-party/ankerl/LICENSE).
 - `third-party/llvm-flang-uint128`: Licensed under the Apache License 2.0 with LLVM exceptions. The license can be found at [third-party/llvm-flang-uint128/LICENSE](third-party/llvm-flang-uint128/LICENSE).
 - `third-party/riscv-arch-test`: Source code licensed under the Apache 2.0 and BSD 3-Clause licenses. Documentation under `CC-BY-4.0`. License information is provided in README.md and other COPYING.* files like [third-party/riscv-arch-test/COPYING.APACHE](third-party/riscv-arch-test/COPYING.APACHE).
 - `third-party/riscv-tests`: Licensed under the BSD 3-Clause "New" or "Revised" License. See [third-party/riscv-tests/LICENSE](third-party/riscv-tests/LICENSE) for license details.
diff --git a/src/Makefile b/src/Makefile
index dde671241..110d3e5e8 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -163,6 +163,7 @@ CLANG_TIDY_WARNS=-Wthread-safety -Wglobal-constructors
 
 # Place our include directories before the system's
 INCS+= \
+	-I../third-party/ankerl \
 	-I../third-party/llvm-flang-uint128 \
 	-I../third-party/nlohmann-json \
 	-I../third-party/downloads \
diff --git a/tests/misc/Makefile b/tests/misc/Makefile
index 309a2f690..e1f0fd1ca 100644
--- a/tests/misc/Makefile
+++ b/tests/misc/Makefile
@@ -95,7 +95,7 @@ CLANG_TIDY_HEADER_FILTER=$(CURDIR)/($(subst $(SPACE),|,$(LINTER_HEADERS)))
 CLANG_FORMAT=clang-format
 CLANG_FORMAT_FILES:=$(wildcard *.cpp) $(wildcard *.h)
 
-INCS=-I../../src -I../../third-party/nlohmann-json -I../../third-party/downloads
+INCS=-I../../src -I../../third-party/ankerl -I../../third-party/nlohmann-json -I../../third-party/downloads
 WARNS=-Wall -Wpedantic $(BOOST_INC)
 
 CXXFLAGS+=-O2 -g -std=gnu++23 -fopenmp -fvisibility=hidden $(INCS) $(UBFLAGS) $(WARNS)
diff --git a/third-party/ankerl/LICENSE b/third-party/ankerl/LICENSE
new file mode 100644
index 000000000..c4d1a0e48
--- /dev/null
+++ b/third-party/ankerl/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Martin Leitner-Ankerl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/third-party/ankerl/unordered_dense.h b/third-party/ankerl/unordered_dense.h
new file mode 100644
index 000000000..13484a981
--- /dev/null
+++ b/third-party/ankerl/unordered_dense.h
@@ -0,0 +1,2101 @@
+///////////////////////// ankerl::unordered_dense::{map, set} /////////////////////////
+
+// A fast & densely stored hashmap and hashset based on robin-hood backward shift deletion.
+// Version 4.5.0
+// https://github.com/martinus/unordered_dense
+//
+// Licensed under the MIT License <http://opensource.org/licenses/MIT>.
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2022-2024 Martin Leitner-Ankerl <martin.ankerl@gmail.com>
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+#ifndef ANKERL_UNORDERED_DENSE_H
+#define ANKERL_UNORDERED_DENSE_H
+
+// see https://semver.org/spec/v2.0.0.html
+#define ANKERL_UNORDERED_DENSE_VERSION_MAJOR 4 // NOLINT(cppcoreguidelines-macro-usage) incompatible API changes
+#define ANKERL_UNORDERED_DENSE_VERSION_MINOR 5 // NOLINT(cppcoreguidelines-macro-usage) backwards compatible functionality
+#define ANKERL_UNORDERED_DENSE_VERSION_PATCH 0 // NOLINT(cppcoreguidelines-macro-usage) backwards compatible bug fixes
+
+// API versioning with inline namespace, see https://www.foonathan.net/2018/11/inline-namespaces/
+
+// NOLINTNEXTLINE(cppcoreguidelines-macro-usage)
+#define ANKERL_UNORDERED_DENSE_VERSION_CONCAT1(major, minor, patch) v##major##_##minor##_##patch
+// NOLINTNEXTLINE(cppcoreguidelines-macro-usage)
+#define ANKERL_UNORDERED_DENSE_VERSION_CONCAT(major, minor, patch) ANKERL_UNORDERED_DENSE_VERSION_CONCAT1(major, minor, patch)
+#define ANKERL_UNORDERED_DENSE_NAMESPACE   \
+    ANKERL_UNORDERED_DENSE_VERSION_CONCAT( \
+        ANKERL_UNORDERED_DENSE_VERSION_MAJOR, ANKERL_UNORDERED_DENSE_VERSION_MINOR, ANKERL_UNORDERED_DENSE_VERSION_PATCH)
+
+#if defined(_MSVC_LANG)
+#    define ANKERL_UNORDERED_DENSE_CPP_VERSION _MSVC_LANG
+#else
+#    define ANKERL_UNORDERED_DENSE_CPP_VERSION __cplusplus
+#endif
+
+#if defined(__GNUC__)
+// NOLINTNEXTLINE(cppcoreguidelines-macro-usage)
+#    define ANKERL_UNORDERED_DENSE_PACK(decl) decl __attribute__((__packed__))
+#elif defined(_MSC_VER)
+// NOLINTNEXTLINE(cppcoreguidelines-macro-usage)
+#    define ANKERL_UNORDERED_DENSE_PACK(decl) __pragma(pack(push, 1)) decl __pragma(pack(pop))
+#endif
+
+// exceptions
+#if defined(__cpp_exceptions) || defined(__EXCEPTIONS) || defined(_CPPUNWIND)
+#    define ANKERL_UNORDERED_DENSE_HAS_EXCEPTIONS() 1 // NOLINT(cppcoreguidelines-macro-usage)
+#else
+#    define ANKERL_UNORDERED_DENSE_HAS_EXCEPTIONS() 0 // NOLINT(cppcoreguidelines-macro-usage)
+#endif
+#ifdef _MSC_VER
+#    define ANKERL_UNORDERED_DENSE_NOINLINE __declspec(noinline)
+#else
+#    define ANKERL_UNORDERED_DENSE_NOINLINE __attribute__((noinline))
+#endif
+
+// defined in unordered_dense.cpp
+#if !defined(ANKERL_UNORDERED_DENSE_EXPORT)
+#    define ANKERL_UNORDERED_DENSE_EXPORT
+#endif
+
+#if ANKERL_UNORDERED_DENSE_CPP_VERSION < 201703L
+#    error ankerl::unordered_dense requires C++17 or higher
+#else
+#    include <array>            // for array
+#    include <cstdint>          // for uint64_t, uint32_t, uint8_t, UINT64_C
+#    include <cstring>          // for size_t, memcpy, memset
+#    include <functional>       // for equal_to, hash
+#    include <initializer_list> // for initializer_list
+#    include <iterator>         // for pair, distance
+#    include <limits>           // for numeric_limits
+#    include <memory>           // for allocator, allocator_traits, shared_ptr
+#    include <optional>         // for optional
+#    include <stdexcept>        // for out_of_range
+#    include <string>           // for basic_string
+#    include <string_view>      // for basic_string_view, hash
+#    include <tuple>            // for forward_as_tuple
+#    include <type_traits>      // for enable_if_t, declval, conditional_t, ena...
+#    include <utility>          // for forward, exchange, pair, as_const, piece...
+#    include <vector>           // for vector
+#    if ANKERL_UNORDERED_DENSE_HAS_EXCEPTIONS() == 0
+#        include <cstdlib> // for abort
+#    endif
+
+#    if defined(__has_include) && !defined(ANKERL_UNORDERED_DENSE_DISABLE_PMR)
+#        if __has_include(<memory_resource>)
+#            define ANKERL_UNORDERED_DENSE_PMR std::pmr // NOLINT(cppcoreguidelines-macro-usage)
+#            include <memory_resource>                  // for polymorphic_allocator
+#        elif __has_include(<experimental/memory_resource>)
+#            define ANKERL_UNORDERED_DENSE_PMR std::experimental::pmr // NOLINT(cppcoreguidelines-macro-usage)
+#            include <experimental/memory_resource>                   // for polymorphic_allocator
+#        endif
+#    endif
+
+#    if defined(_MSC_VER) && defined(_M_X64)
+#        include <intrin.h>
+#        pragma intrinsic(_umul128)
+#    endif
+
+#    if defined(__GNUC__) || defined(__INTEL_COMPILER) || defined(__clang__)
+#        define ANKERL_UNORDERED_DENSE_LIKELY(x) __builtin_expect(x, 1)   // NOLINT(cppcoreguidelines-macro-usage)
+#        define ANKERL_UNORDERED_DENSE_UNLIKELY(x) __builtin_expect(x, 0) // NOLINT(cppcoreguidelines-macro-usage)
+#    else
+#        define ANKERL_UNORDERED_DENSE_LIKELY(x) (x)   // NOLINT(cppcoreguidelines-macro-usage)
+#        define ANKERL_UNORDERED_DENSE_UNLIKELY(x) (x) // NOLINT(cppcoreguidelines-macro-usage)
+#    endif
+
+namespace ankerl::unordered_dense {
+inline namespace ANKERL_UNORDERED_DENSE_NAMESPACE {
+
+namespace detail {
+
+#    if ANKERL_UNORDERED_DENSE_HAS_EXCEPTIONS()
+
+// make sure this is not inlined as it is slow and dramatically enlarges code, thus making other
+// inlinings more difficult. Throws are also generally the slow path.
+[[noreturn]] inline ANKERL_UNORDERED_DENSE_NOINLINE void on_error_key_not_found() {
+    throw std::out_of_range("ankerl::unordered_dense::map::at(): key not found");
+}
+[[noreturn]] inline ANKERL_UNORDERED_DENSE_NOINLINE void on_error_bucket_overflow() {
+    throw std::overflow_error("ankerl::unordered_dense: reached max bucket size, cannot increase size");
+}
+[[noreturn]] inline ANKERL_UNORDERED_DENSE_NOINLINE void on_error_too_many_elements() {
+    throw std::out_of_range("ankerl::unordered_dense::map::replace(): too many elements");
+}
+
+#    else
+
+[[noreturn]] inline void on_error_key_not_found() {
+    abort();
+}
+[[noreturn]] inline void on_error_bucket_overflow() {
+    abort();
+}
+[[noreturn]] inline void on_error_too_many_elements() {
+    abort();
+}
+
+#    endif
+
+} // namespace detail
+
+// hash ///////////////////////////////////////////////////////////////////////
+
+// This is a stripped-down implementation of wyhash: https://github.com/wangyi-fudan/wyhash
+// No big-endian support (because different values on different machines don't matter),
+// hardcodes seed and the secret, reformats the code, and clang-tidy fixes.
+namespace detail::wyhash {
+
+inline void mum(uint64_t* a, uint64_t* b) {
+#    if defined(__SIZEOF_INT128__)
+    __uint128_t r = *a;
+    r *= *b;
+    *a = static_cast<uint64_t>(r);
+    *b = static_cast<uint64_t>(r >> 64U);
+#    elif defined(_MSC_VER) && defined(_M_X64)
+    *a = _umul128(*a, *b, b);
+#    else
+    uint64_t ha = *a >> 32U;
+    uint64_t hb = *b >> 32U;
+    uint64_t la = static_cast<uint32_t>(*a);
+    uint64_t lb = static_cast<uint32_t>(*b);
+    uint64_t hi{};
+    uint64_t lo{};
+    uint64_t rh = ha * hb;
+    uint64_t rm0 = ha * lb;
+    uint64_t rm1 = hb * la;
+    uint64_t rl = la * lb;
+    uint64_t t = rl + (rm0 << 32U);
+    auto c = static_cast<uint64_t>(t < rl);
+    lo = t + (rm1 << 32U);
+    c += static_cast<uint64_t>(lo < t);
+    hi = rh + (rm0 >> 32U) + (rm1 >> 32U) + c;
+    *a = lo;
+    *b = hi;
+#    endif
+}
+
+// multiply and xor mix function, aka MUM
+[[nodiscard]] inline auto mix(uint64_t a, uint64_t b) -> uint64_t {
+    mum(&a, &b);
+    return a ^ b;
+}
+
+// read functions. WARNING: we don't care about endianness, so results are different on big endian!
+[[nodiscard]] inline auto r8(const uint8_t* p) -> uint64_t {
+    uint64_t v{};
+    std::memcpy(&v, p, 8U);
+    return v;
+}
+
+[[nodiscard]] inline auto r4(const uint8_t* p) -> uint64_t {
+    uint32_t v{};
+    std::memcpy(&v, p, 4);
+    return v;
+}
+
+// reads 1, 2, or 3 bytes
+[[nodiscard]] inline auto r3(const uint8_t* p, size_t k) -> uint64_t {
+    return (static_cast<uint64_t>(p[0]) << 16U) | (static_cast<uint64_t>(p[k >> 1U]) << 8U) | p[k - 1];
+}
+
+[[maybe_unused]] [[nodiscard]] inline auto hash(void const* key, size_t len) -> uint64_t {
+    static constexpr auto secret = std::array{UINT64_C(0xa0761d6478bd642f),
+                                              UINT64_C(0xe7037ed1a0b428db),
+                                              UINT64_C(0x8ebc6af09c88c6e3),
+                                              UINT64_C(0x589965cc75374cc3)};
+
+    auto const* p = static_cast<uint8_t const*>(key);
+    uint64_t seed = secret[0];
+    uint64_t a{};
+    uint64_t b{};
+    if (ANKERL_UNORDERED_DENSE_LIKELY(len <= 16)) {
+        if (ANKERL_UNORDERED_DENSE_LIKELY(len >= 4)) {
+            a = (r4(p) << 32U) | r4(p + ((len >> 3U) << 2U));
+            b = (r4(p + len - 4) << 32U) | r4(p + len - 4 - ((len >> 3U) << 2U));
+        } else if (ANKERL_UNORDERED_DENSE_LIKELY(len > 0)) {
+            a = r3(p, len);
+            b = 0;
+        } else {
+            a = 0;
+            b = 0;
+        }
+    } else {
+        size_t i = len;
+        if (ANKERL_UNORDERED_DENSE_UNLIKELY(i > 48)) {
+            uint64_t see1 = seed;
+            uint64_t see2 = seed;
+            do {
+                seed = mix(r8(p) ^ secret[1], r8(p + 8) ^ seed);
+                see1 = mix(r8(p + 16) ^ secret[2], r8(p + 24) ^ see1);
+                see2 = mix(r8(p + 32) ^ secret[3], r8(p + 40) ^ see2);
+                p += 48;
+                i -= 48;
+            } while (ANKERL_UNORDERED_DENSE_LIKELY(i > 48));
+            seed ^= see1 ^ see2;
+        }
+        while (ANKERL_UNORDERED_DENSE_UNLIKELY(i > 16)) {
+            seed = mix(r8(p) ^ secret[1], r8(p + 8) ^ seed);
+            i -= 16;
+            p += 16;
+        }
+        a = r8(p + i - 16);
+        b = r8(p + i - 8);
+    }
+
+    return mix(secret[1] ^ len, mix(a ^ secret[1], b ^ seed));
+}
+
+[[nodiscard]] inline auto hash(uint64_t x) -> uint64_t {
+    return detail::wyhash::mix(x, UINT64_C(0x9E3779B97F4A7C15));
+}
+
+} // namespace detail::wyhash
+
+ANKERL_UNORDERED_DENSE_EXPORT template <typename T, typename Enable = void>
+struct hash {
+    auto operator()(T const& obj) const noexcept(noexcept(std::declval<std::hash<T>>().operator()(std::declval<T const&>())))
+        -> uint64_t {
+        return std::hash<T>{}(obj);
+    }
+};
+
+template <typename T>
+struct hash<T, typename std::hash<T>::is_avalanching> {
+    using is_avalanching = void;
+    auto operator()(T const& obj) const noexcept(noexcept(std::declval<std::hash<T>>().operator()(std::declval<T const&>())))
+        -> uint64_t {
+        return std::hash<T>{}(obj);
+    }
+};
+
+template <typename CharT>
+struct hash<std::basic_string<CharT>> {
+    using is_avalanching = void;
+    auto operator()(std::basic_string<CharT> const& str) const noexcept -> uint64_t {
+        return detail::wyhash::hash(str.data(), sizeof(CharT) * str.size());
+    }
+};
+
+template <typename CharT>
+struct hash<std::basic_string_view<CharT>> {
+    using is_avalanching = void;
+    auto operator()(std::basic_string_view<CharT> const& sv) const noexcept -> uint64_t {
+        return detail::wyhash::hash(sv.data(), sizeof(CharT) * sv.size());
+    }
+};
+
+template <class T>
+struct hash<T*> {
+    using is_avalanching = void;
+    auto operator()(T* ptr) const noexcept -> uint64_t {
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        return detail::wyhash::hash(reinterpret_cast<uintptr_t>(ptr));
+    }
+};
+
+template <class T>
+struct hash<std::unique_ptr<T>> {
+    using is_avalanching = void;
+    auto operator()(std::unique_ptr<T> const& ptr) const noexcept -> uint64_t {
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        return detail::wyhash::hash(reinterpret_cast<uintptr_t>(ptr.get()));
+    }
+};
+
+template <class T>
+struct hash<std::shared_ptr<T>> {
+    using is_avalanching = void;
+    auto operator()(std::shared_ptr<T> const& ptr) const noexcept -> uint64_t {
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        return detail::wyhash::hash(reinterpret_cast<uintptr_t>(ptr.get()));
+    }
+};
+
+template <typename Enum>
+struct hash<Enum, typename std::enable_if<std::is_enum<Enum>::value>::type> {
+    using is_avalanching = void;
+    auto operator()(Enum e) const noexcept -> uint64_t {
+        using underlying = typename std::underlying_type_t<Enum>;
+        return detail::wyhash::hash(static_cast<underlying>(e));
+    }
+};
+
+template <typename... Args>
+struct tuple_hash_helper {
+    // Converts the value into 64bit. If it is an integral type, just cast it. Mixing is doing the rest.
+    // If it isn't an integral we need to hash it.
+    template <typename Arg>
+    [[nodiscard]] constexpr static auto to64(Arg const& arg) -> uint64_t {
+        if constexpr (std::is_integral_v<Arg> || std::is_enum_v<Arg>) {
+            return static_cast<uint64_t>(arg);
+        } else {
+            return hash<Arg>{}(arg);
+        }
+    }
+
+    [[nodiscard]] static auto mix64(uint64_t state, uint64_t v) -> uint64_t {
+        return detail::wyhash::mix(state + v, uint64_t{0x9ddfea08eb382d69});
+    }
+
+    // Creates a buffer that holds all the data from each element of the tuple. If possible we memcpy the data directly. If
+    // not, we hash the object and use this for the array. Size of the array is known at compile time, and memcpy is optimized
+    // away, so filling the buffer is highly efficient. Finally, call wyhash with this buffer.
+    template <typename T, std::size_t... Idx>
+    [[nodiscard]] static auto calc_hash(T const& t, std::index_sequence<Idx...>) noexcept -> uint64_t {
+        auto h = uint64_t{};
+        ((h = mix64(h, to64(std::get<Idx>(t)))), ...);
+        return h;
+    }
+};
+
+template <typename... Args>
+struct hash<std::tuple<Args...>> : tuple_hash_helper<Args...> {
+    using is_avalanching = void;
+    auto operator()(std::tuple<Args...> const& t) const noexcept -> uint64_t {
+        return tuple_hash_helper<Args...>::calc_hash(t, std::index_sequence_for<Args...>{});
+    }
+};
+
+template <typename A, typename B>
+struct hash<std::pair<A, B>> : tuple_hash_helper<A, B> {
+    using is_avalanching = void;
+    auto operator()(std::pair<A, B> const& t) const noexcept -> uint64_t {
+        return tuple_hash_helper<A, B>::calc_hash(t, std::index_sequence_for<A, B>{});
+    }
+};
+
+// NOLINTNEXTLINE(cppcoreguidelines-macro-usage)
+#    define ANKERL_UNORDERED_DENSE_HASH_STATICCAST(T)                    \
+        template <>                                                      \
+        struct hash<T> {                                                 \
+            using is_avalanching = void;                                 \
+            auto operator()(T const& obj) const noexcept -> uint64_t {   \
+                return detail::wyhash::hash(static_cast<uint64_t>(obj)); \
+            }                                                            \
+        }
+
+#    if defined(__GNUC__) && !defined(__clang__)
+#        pragma GCC diagnostic push
+#        pragma GCC diagnostic ignored "-Wuseless-cast"
+#    endif
+// see https://en.cppreference.com/w/cpp/utility/hash
+ANKERL_UNORDERED_DENSE_HASH_STATICCAST(bool);
+ANKERL_UNORDERED_DENSE_HASH_STATICCAST(char);
+ANKERL_UNORDERED_DENSE_HASH_STATICCAST(signed char);
+ANKERL_UNORDERED_DENSE_HASH_STATICCAST(unsigned char);
+#    if ANKERL_UNORDERED_DENSE_CPP_VERSION >= 202002L && defined(__cpp_char8_t)
+ANKERL_UNORDERED_DENSE_HASH_STATICCAST(char8_t);
+#    endif
+ANKERL_UNORDERED_DENSE_HASH_STATICCAST(char16_t);
+ANKERL_UNORDERED_DENSE_HASH_STATICCAST(char32_t);
+ANKERL_UNORDERED_DENSE_HASH_STATICCAST(wchar_t);
+ANKERL_UNORDERED_DENSE_HASH_STATICCAST(short);
+ANKERL_UNORDERED_DENSE_HASH_STATICCAST(unsigned short);
+ANKERL_UNORDERED_DENSE_HASH_STATICCAST(int);
+ANKERL_UNORDERED_DENSE_HASH_STATICCAST(unsigned int);
+ANKERL_UNORDERED_DENSE_HASH_STATICCAST(long);
+ANKERL_UNORDERED_DENSE_HASH_STATICCAST(long long);
+ANKERL_UNORDERED_DENSE_HASH_STATICCAST(unsigned long);
+ANKERL_UNORDERED_DENSE_HASH_STATICCAST(unsigned long long);
+
+#    if defined(__GNUC__) && !defined(__clang__)
+#        pragma GCC diagnostic pop
+#    endif
+
+// bucket_type //////////////////////////////////////////////////////////
+
+namespace bucket_type {
+
+struct standard {
+    static constexpr uint32_t dist_inc = 1U << 8U;             // skip 1 byte fingerprint
+    static constexpr uint32_t fingerprint_mask = dist_inc - 1; // mask for 1 byte of fingerprint
+
+    uint32_t m_dist_and_fingerprint; // upper 3 byte: distance to original bucket. lower byte: fingerprint from hash
+    uint32_t m_value_idx;            // index into the m_values vector.
+};
+
+ANKERL_UNORDERED_DENSE_PACK(struct big {
+    static constexpr uint32_t dist_inc = 1U << 8U;             // skip 1 byte fingerprint
+    static constexpr uint32_t fingerprint_mask = dist_inc - 1; // mask for 1 byte of fingerprint
+
+    uint32_t m_dist_and_fingerprint; // upper 3 byte: distance to original bucket. lower byte: fingerprint from hash
+    size_t m_value_idx;              // index into the m_values vector.
+});
+
+} // namespace bucket_type
+
+namespace detail {
+
+struct nonesuch {};
+struct default_container_t {};
+
+template <class Default, class AlwaysVoid, template <class...> class Op, class... Args>
+struct detector {
+    using value_t = std::false_type;
+    using type = Default;
+};
+
+template <class Default, template <class...> class Op, class... Args>
+struct detector<Default, std::void_t<Op<Args...>>, Op, Args...> {
+    using value_t = std::true_type;
+    using type = Op<Args...>;
+};
+
+template <template <class...> class Op, class... Args>
+using is_detected = typename detail::detector<detail::nonesuch, void, Op, Args...>::value_t;
+
+template <template <class...> class Op, class... Args>
+constexpr bool is_detected_v = is_detected<Op, Args...>::value;
+
+template <typename T>
+using detect_avalanching = typename T::is_avalanching;
+
+template <typename T>
+using detect_is_transparent = typename T::is_transparent;
+
+template <typename T>
+using detect_iterator = typename T::iterator;
+
+template <typename T>
+using detect_reserve = decltype(std::declval<T&>().reserve(size_t{}));
+
+// enable_if helpers
+
+template <typename Mapped>
+constexpr bool is_map_v = !std::is_void_v<Mapped>;
+
+// clang-format off
+template <typename Hash, typename KeyEqual>
+constexpr bool is_transparent_v = is_detected_v<detect_is_transparent, Hash> && is_detected_v<detect_is_transparent, KeyEqual>;
+// clang-format on
+
+template <typename From, typename To1, typename To2>
+constexpr bool is_neither_convertible_v = !std::is_convertible_v<From, To1> && !std::is_convertible_v<From, To2>;
+
+template <typename T>
+constexpr bool has_reserve = is_detected_v<detect_reserve, T>;
+
+// base type for map has mapped_type
+template <class T>
+struct base_table_type_map {
+    using mapped_type = T;
+};
+
+// base type for set doesn't have mapped_type
+struct base_table_type_set {};
+
+} // namespace detail
+
+// Very much like std::deque, but faster for indexing (in most cases). As of now this doesn't implement the full std::vector
+// API, but merely what's necessary to work as an underlying container for ankerl::unordered_dense::{map, set}.
+// It allocates blocks of equal size and puts them into the m_blocks vector. That means it can grow simply by adding a new
+// block to the back of m_blocks, and doesn't double its size like an std::vector. The disadvantage is that memory is not
+// linear and thus there is one more indirection necessary for indexing.
+template <typename T, typename Allocator = std::allocator<T>, size_t MaxSegmentSizeBytes = 4096>
+class segmented_vector {
+    template <bool IsConst>
+    class iter_t;
+
+public:
+    using allocator_type = Allocator;
+    using pointer = typename std::allocator_traits<allocator_type>::pointer;
+    using const_pointer = typename std::allocator_traits<allocator_type>::const_pointer;
+    using difference_type = typename std::allocator_traits<allocator_type>::difference_type;
+    using value_type = T;
+    using size_type = std::size_t;
+    using reference = T&;
+    using const_reference = T const&;
+    using iterator = iter_t<false>;
+    using const_iterator = iter_t<true>;
+
+private:
+    using vec_alloc = typename std::allocator_traits<Allocator>::template rebind_alloc<pointer>;
+    std::vector<pointer, vec_alloc> m_blocks{};
+    size_t m_size{};
+
+    // Calculates the maximum number for x in  (s << x) <= max_val
+    static constexpr auto num_bits_closest(size_t max_val, size_t s) -> size_t {
+        auto f = size_t{0};
+        while (s << (f + 1) <= max_val) {
+            ++f;
+        }
+        return f;
+    }
+
+    using self_t = segmented_vector<T, Allocator, MaxSegmentSizeBytes>;
+    static constexpr auto num_bits = num_bits_closest(MaxSegmentSizeBytes, sizeof(T));
+    static constexpr auto num_elements_in_block = 1U << num_bits;
+    static constexpr auto mask = num_elements_in_block - 1U;
+
+    /**
+     * Iterator class doubles as const_iterator and iterator
+     */
+    template <bool IsConst>
+    class iter_t {
+        using ptr_t = typename std::conditional_t<IsConst, segmented_vector::const_pointer const*, segmented_vector::pointer*>;
+        ptr_t m_data{};
+        size_t m_idx{};
+
+        template <bool B>
+        friend class iter_t;
+
+    public:
+        using difference_type = segmented_vector::difference_type;
+        using value_type = T;
+        using reference = typename std::conditional_t<IsConst, value_type const&, value_type&>;
+        using pointer = typename std::conditional_t<IsConst, segmented_vector::const_pointer, segmented_vector::pointer>;
+        using iterator_category = std::forward_iterator_tag;
+
+        iter_t() noexcept = default;
+
+        template <bool OtherIsConst, typename = typename std::enable_if<IsConst && !OtherIsConst>::type>
+        // NOLINTNEXTLINE(google-explicit-constructor,hicpp-explicit-conversions)
+        constexpr iter_t(iter_t<OtherIsConst> const& other) noexcept
+            : m_data(other.m_data)
+            , m_idx(other.m_idx) {}
+
+        constexpr iter_t(ptr_t data, size_t idx) noexcept
+            : m_data(data)
+            , m_idx(idx) {}
+
+        template <bool OtherIsConst, typename = typename std::enable_if<IsConst && !OtherIsConst>::type>
+        constexpr auto operator=(iter_t<OtherIsConst> const& other) noexcept -> iter_t& {
+            m_data = other.m_data;
+            m_idx = other.m_idx;
+            return *this;
+        }
+
+        constexpr auto operator++() noexcept -> iter_t& {
+            ++m_idx;
+            return *this;
+        }
+
+        constexpr auto operator++(int) noexcept -> iter_t {
+            iter_t prev(*this);
+            this->operator++();
+            return prev;
+        }
+
+        constexpr auto operator+(difference_type diff) noexcept -> iter_t {
+            return {m_data, static_cast<size_t>(static_cast<difference_type>(m_idx) + diff)};
+        }
+
+        template <bool OtherIsConst>
+        constexpr auto operator-(iter_t<OtherIsConst> const& other) noexcept -> difference_type {
+            return static_cast<difference_type>(m_idx) - static_cast<difference_type>(other.m_idx);
+        }
+
+        constexpr auto operator*() const noexcept -> reference {
+            return m_data[m_idx >> num_bits][m_idx & mask];
+        }
+
+        constexpr auto operator->() const noexcept -> pointer {
+            return &m_data[m_idx >> num_bits][m_idx & mask];
+        }
+
+        template <bool O>
+        constexpr auto operator==(iter_t<O> const& o) const noexcept -> bool {
+            return m_idx == o.m_idx;
+        }
+
+        template <bool O>
+        constexpr auto operator!=(iter_t<O> const& o) const noexcept -> bool {
+            return !(*this == o);
+        }
+    };
+
+    // slow path: need to allocate a new segment every once in a while
+    void increase_capacity() {
+        auto ba = Allocator(m_blocks.get_allocator());
+        pointer block = std::allocator_traits<Allocator>::allocate(ba, num_elements_in_block);
+        m_blocks.push_back(block);
+    }
+
+    // Moves everything from other
+    void append_everything_from(segmented_vector&& other) {
+        reserve(size() + other.size());
+        for (auto&& o : other) {
+            emplace_back(std::move(o));
+        }
+    }
+
+    // Copies everything from other
+    void append_everything_from(segmented_vector const& other) {
+        reserve(size() + other.size());
+        for (auto const& o : other) {
+            emplace_back(o);
+        }
+    }
+
+    void dealloc() {
+        auto ba = Allocator(m_blocks.get_allocator());
+        for (auto ptr : m_blocks) {
+            std::allocator_traits<Allocator>::deallocate(ba, ptr, num_elements_in_block);
+        }
+    }
+
+    [[nodiscard]] static constexpr auto calc_num_blocks_for_capacity(size_t capacity) {
+        return (capacity + num_elements_in_block - 1U) / num_elements_in_block;
+    }
+
+public:
+    segmented_vector() = default;
+
+    // NOLINTNEXTLINE(google-explicit-constructor,hicpp-explicit-conversions)
+    segmented_vector(Allocator alloc)
+        : m_blocks(vec_alloc(alloc)) {}
+
+    segmented_vector(segmented_vector&& other, Allocator alloc)
+        : segmented_vector(alloc) {
+        *this = std::move(other);
+    }
+
+    segmented_vector(segmented_vector const& other, Allocator alloc)
+        : m_blocks(vec_alloc(alloc)) {
+        append_everything_from(other);
+    }
+
+    segmented_vector(segmented_vector&& other) noexcept
+        : segmented_vector(std::move(other), get_allocator()) {}
+
+    segmented_vector(segmented_vector const& other) {
+        append_everything_from(other);
+    }
+
+    auto operator=(segmented_vector const& other) -> segmented_vector& {
+        if (this == &other) {
+            return *this;
+        }
+        clear();
+        append_everything_from(other);
+        return *this;
+    }
+
+    auto operator=(segmented_vector&& other) noexcept -> segmented_vector& {
+        clear();
+        dealloc();
+        if (other.get_allocator() == get_allocator()) {
+            m_blocks = std::move(other.m_blocks);
+            m_size = std::exchange(other.m_size, {});
+        } else {
+            // make sure to construct with other's allocator!
+            m_blocks = std::vector<pointer, vec_alloc>(vec_alloc(other.get_allocator()));
+            append_everything_from(std::move(other));
+        }
+        return *this;
+    }
+
+    ~segmented_vector() {
+        clear();
+        dealloc();
+    }
+
+    [[nodiscard]] constexpr auto size() const -> size_t {
+        return m_size;
+    }
+
+    [[nodiscard]] constexpr auto capacity() const -> size_t {
+        return m_blocks.size() * num_elements_in_block;
+    }
+
+    // Indexing is highly performance critical
+    [[nodiscard]] constexpr auto operator[](size_t i) const noexcept -> T const& {
+        return m_blocks[i >> num_bits][i & mask];
+    }
+
+    [[nodiscard]] constexpr auto operator[](size_t i) noexcept -> T& {
+        return m_blocks[i >> num_bits][i & mask];
+    }
+
+    [[nodiscard]] constexpr auto begin() -> iterator {
+        return {m_blocks.data(), 0U};
+    }
+    [[nodiscard]] constexpr auto begin() const -> const_iterator {
+        return {m_blocks.data(), 0U};
+    }
+    [[nodiscard]] constexpr auto cbegin() const -> const_iterator {
+        return {m_blocks.data(), 0U};
+    }
+
+    [[nodiscard]] constexpr auto end() -> iterator {
+        return {m_blocks.data(), m_size};
+    }
+    [[nodiscard]] constexpr auto end() const -> const_iterator {
+        return {m_blocks.data(), m_size};
+    }
+    [[nodiscard]] constexpr auto cend() const -> const_iterator {
+        return {m_blocks.data(), m_size};
+    }
+
+    [[nodiscard]] constexpr auto back() -> reference {
+        return operator[](m_size - 1);
+    }
+    [[nodiscard]] constexpr auto back() const -> const_reference {
+        return operator[](m_size - 1);
+    }
+
+    void pop_back() {
+        back().~T();
+        --m_size;
+    }
+
+    [[nodiscard]] auto empty() const {
+        return 0 == m_size;
+    }
+
+    void reserve(size_t new_capacity) {
+        m_blocks.reserve(calc_num_blocks_for_capacity(new_capacity));
+        while (new_capacity > capacity()) {
+            increase_capacity();
+        }
+    }
+
+    [[nodiscard]] auto get_allocator() const -> allocator_type {
+        return allocator_type{m_blocks.get_allocator()};
+    }
+
+    template <class... Args>
+    auto emplace_back(Args&&... args) -> reference {
+        if (m_size == capacity()) {
+            increase_capacity();
+        }
+        auto* ptr = static_cast<void*>(&operator[](m_size));
+        auto& ref = *new (ptr) T(std::forward<Args>(args)...);
+        ++m_size;
+        return ref;
+    }
+
+    void clear() {
+        if constexpr (!std::is_trivially_destructible_v<T>) {
+            for (size_t i = 0, s = size(); i < s; ++i) {
+                operator[](i).~T();
+            }
+        }
+        m_size = 0;
+    }
+
+    void shrink_to_fit() {
+        auto ba = Allocator(m_blocks.get_allocator());
+        auto num_blocks_required = calc_num_blocks_for_capacity(m_size);
+        while (m_blocks.size() > num_blocks_required) {
+            std::allocator_traits<Allocator>::deallocate(ba, m_blocks.back(), num_elements_in_block);
+            m_blocks.pop_back();
+        }
+        m_blocks.shrink_to_fit();
+    }
+};
+
+namespace detail {
+
+// This is it, the table. Doubles as map and set, and uses `void` for T when its used as a set.
+template <class Key,
+          class T, // when void, treat it as a set.
+          class Hash,
+          class KeyEqual,
+          class AllocatorOrContainer,
+          class Bucket,
+          class BucketContainer,
+          bool IsSegmented>
+class table : public std::conditional_t<is_map_v<T>, base_table_type_map<T>, base_table_type_set> {
+    using underlying_value_type = typename std::conditional_t<is_map_v<T>, std::pair<Key, T>, Key>;
+    using underlying_container_type = std::conditional_t<IsSegmented,
+                                                         segmented_vector<underlying_value_type, AllocatorOrContainer>,
+                                                         std::vector<underlying_value_type, AllocatorOrContainer>>;
+
+public:
+    using value_container_type = std::
+        conditional_t<is_detected_v<detect_iterator, AllocatorOrContainer>, AllocatorOrContainer, underlying_container_type>;
+
+private:
+    using bucket_alloc =
+        typename std::allocator_traits<typename value_container_type::allocator_type>::template rebind_alloc<Bucket>;
+    using default_bucket_container_type =
+        std::conditional_t<IsSegmented, segmented_vector<Bucket, bucket_alloc>, std::vector<Bucket, bucket_alloc>>;
+
+    using bucket_container_type = std::conditional_t<std::is_same_v<BucketContainer, detail::default_container_t>,
+                                                     default_bucket_container_type,
+                                                     BucketContainer>;
+
+    static constexpr uint8_t initial_shifts = 64 - 2; // 2^(64-m_shift) number of buckets
+    static constexpr float default_max_load_factor = 0.8F;
+
+public:
+    using key_type = Key;
+    using value_type = typename value_container_type::value_type;
+    using size_type = typename value_container_type::size_type;
+    using difference_type = typename value_container_type::difference_type;
+    using hasher = Hash;
+    using key_equal = KeyEqual;
+    using allocator_type = typename value_container_type::allocator_type;
+    using reference = typename value_container_type::reference;
+    using const_reference = typename value_container_type::const_reference;
+    using pointer = typename value_container_type::pointer;
+    using const_pointer = typename value_container_type::const_pointer;
+    using const_iterator = typename value_container_type::const_iterator;
+    using iterator = std::conditional_t<is_map_v<T>, typename value_container_type::iterator, const_iterator>;
+    using bucket_type = Bucket;
+
+private:
+    using value_idx_type = decltype(Bucket::m_value_idx);
+    using dist_and_fingerprint_type = decltype(Bucket::m_dist_and_fingerprint);
+
+    static_assert(std::is_trivially_destructible_v<Bucket>, "assert there's no need to call destructor / std::destroy");
+    static_assert(std::is_trivially_copyable_v<Bucket>, "assert we can just memset / memcpy");
+
+    value_container_type m_values{}; // Contains all the key-value pairs in one densely stored container. No holes.
+    bucket_container_type m_buckets{};
+    size_t m_max_bucket_capacity = 0;
+    float m_max_load_factor = default_max_load_factor;
+    Hash m_hash{};
+    KeyEqual m_equal{};
+    uint8_t m_shifts = initial_shifts;
+
+    [[nodiscard]] auto next(value_idx_type bucket_idx) const -> value_idx_type {
+        return ANKERL_UNORDERED_DENSE_UNLIKELY(bucket_idx + 1U == bucket_count())
+                   ? 0
+                   : static_cast<value_idx_type>(bucket_idx + 1U);
+    }
+
+    // Helper to access bucket through pointer types
+    [[nodiscard]] static constexpr auto at(bucket_container_type& bucket, size_t offset) -> Bucket& {
+        return bucket[offset];
+    }
+
+    [[nodiscard]] static constexpr auto at(const bucket_container_type& bucket, size_t offset) -> const Bucket& {
+        return bucket[offset];
+    }
+
+    // use the dist_inc and dist_dec functions so that uint16_t types work without warning
+    [[nodiscard]] static constexpr auto dist_inc(dist_and_fingerprint_type x) -> dist_and_fingerprint_type {
+        return static_cast<dist_and_fingerprint_type>(x + Bucket::dist_inc);
+    }
+
+    [[nodiscard]] static constexpr auto dist_dec(dist_and_fingerprint_type x) -> dist_and_fingerprint_type {
+        return static_cast<dist_and_fingerprint_type>(x - Bucket::dist_inc);
+    }
+
+    // The goal of mixed_hash is to always produce a high quality 64bit hash.
+    template <typename K>
+    [[nodiscard]] constexpr auto mixed_hash(K const& key) const -> uint64_t {
+        if constexpr (is_detected_v<detect_avalanching, Hash>) {
+            // we know that the hash is good because is_avalanching.
+            if constexpr (sizeof(decltype(m_hash(key))) < sizeof(uint64_t)) {
+                // 32bit hash and is_avalanching => multiply with a constant to avalanche bits upwards
+                return m_hash(key) * UINT64_C(0x9ddfea08eb382d69);
+            } else {
+                // 64bit and is_avalanching => only use the hash itself.
+                return m_hash(key);
+            }
+        } else {
+            // not is_avalanching => apply wyhash
+            return wyhash::hash(m_hash(key));
+        }
+    }
+
+    [[nodiscard]] constexpr auto dist_and_fingerprint_from_hash(uint64_t hash) const -> dist_and_fingerprint_type {
+        return Bucket::dist_inc | (static_cast<dist_and_fingerprint_type>(hash) & Bucket::fingerprint_mask);
+    }
+
+    [[nodiscard]] constexpr auto bucket_idx_from_hash(uint64_t hash) const -> value_idx_type {
+        return static_cast<value_idx_type>(hash >> m_shifts);
+    }
+
+    [[nodiscard]] static constexpr auto get_key(value_type const& vt) -> key_type const& {
+        if constexpr (is_map_v<T>) {
+            return vt.first;
+        } else {
+            return vt;
+        }
+    }
+
+    template <typename K>
+    [[nodiscard]] auto next_while_less(K const& key) const -> Bucket {
+        auto hash = mixed_hash(key);
+        auto dist_and_fingerprint = dist_and_fingerprint_from_hash(hash);
+        auto bucket_idx = bucket_idx_from_hash(hash);
+
+        while (dist_and_fingerprint < at(m_buckets, bucket_idx).m_dist_and_fingerprint) {
+            dist_and_fingerprint = dist_inc(dist_and_fingerprint);
+            bucket_idx = next(bucket_idx);
+        }
+        return {dist_and_fingerprint, bucket_idx};
+    }
+
+    void place_and_shift_up(Bucket bucket, value_idx_type place) {
+        while (0 != at(m_buckets, place).m_dist_and_fingerprint) {
+            bucket = std::exchange(at(m_buckets, place), bucket);
+            bucket.m_dist_and_fingerprint = dist_inc(bucket.m_dist_and_fingerprint);
+            place = next(place);
+        }
+        at(m_buckets, place) = bucket;
+    }
+
+    [[nodiscard]] static constexpr auto calc_num_buckets(uint8_t shifts) -> size_t {
+        return (std::min)(max_bucket_count(), size_t{1} << (64U - shifts));
+    }
+
+    [[nodiscard]] constexpr auto calc_shifts_for_size(size_t s) const -> uint8_t {
+        auto shifts = initial_shifts;
+        while (shifts > 0 && static_cast<size_t>(static_cast<float>(calc_num_buckets(shifts)) * max_load_factor()) < s) {
+            --shifts;
+        }
+        return shifts;
+    }
+
+    // assumes m_values has data, m_buckets=m_buckets_end=nullptr, m_shifts is INITIAL_SHIFTS
+    void copy_buckets(table const& other) {
+        // assumes m_values has already the correct data copied over.
+        if (empty()) {
+            // when empty, at least allocate an initial buckets and clear them.
+            allocate_buckets_from_shift();
+            clear_buckets();
+        } else {
+            m_shifts = other.m_shifts;
+            allocate_buckets_from_shift();
+            if constexpr (IsSegmented || !std::is_same_v<BucketContainer, default_container_t>) {
+                for (auto i = 0UL; i < bucket_count(); ++i) {
+                    at(m_buckets, i) = at(other.m_buckets, i);
+                }
+            } else {
+                std::memcpy(m_buckets.data(), other.m_buckets.data(), sizeof(Bucket) * bucket_count());
+            }
+        }
+    }
+
+    /**
+     * True when no element can be added any more without increasing the size
+     */
+    [[nodiscard]] auto is_full() const -> bool {
+        return size() > m_max_bucket_capacity;
+    }
+
+    void deallocate_buckets() {
+        m_buckets.clear();
+        m_buckets.shrink_to_fit();
+        m_max_bucket_capacity = 0;
+    }
+
+    void allocate_buckets_from_shift() {
+        auto num_buckets = calc_num_buckets(m_shifts);
+        if constexpr (IsSegmented || !std::is_same_v<BucketContainer, default_container_t>) {
+            if constexpr (has_reserve<bucket_container_type>) {
+                m_buckets.reserve(num_buckets);
+            }
+            for (size_t i = m_buckets.size(); i < num_buckets; ++i) {
+                m_buckets.emplace_back();
+            }
+        } else {
+            m_buckets.resize(num_buckets);
+        }
+        if (num_buckets == max_bucket_count()) {
+            // reached the maximum, make sure we can use each bucket
+            m_max_bucket_capacity = max_bucket_count();
+        } else {
+            m_max_bucket_capacity = static_cast<value_idx_type>(static_cast<float>(num_buckets) * max_load_factor());
+        }
+    }
+
+    void clear_buckets() {
+        if constexpr (IsSegmented || !std::is_same_v<BucketContainer, default_container_t>) {
+            for (auto&& e : m_buckets) {
+                std::memset(&e, 0, sizeof(e));
+            }
+        } else {
+            std::memset(m_buckets.data(), 0, sizeof(Bucket) * bucket_count());
+        }
+    }
+
+    void clear_and_fill_buckets_from_values() {
+        clear_buckets();
+        for (value_idx_type value_idx = 0, end_idx = static_cast<value_idx_type>(m_values.size()); value_idx < end_idx;
+             ++value_idx) {
+            auto const& key = get_key(m_values[value_idx]);
+            auto [dist_and_fingerprint, bucket] = next_while_less(key);
+
+            // we know for certain that key has not yet been inserted, so no need to check it.
+            place_and_shift_up({dist_and_fingerprint, value_idx}, bucket);
+        }
+    }
+
+    void increase_size() {
+        if (m_max_bucket_capacity == max_bucket_count()) {
+            // remove the value again, we can't add it!
+            m_values.pop_back();
+            on_error_bucket_overflow();
+        }
+        --m_shifts;
+        if constexpr (!IsSegmented || std::is_same_v<BucketContainer, default_container_t>) {
+            deallocate_buckets();
+        }
+        allocate_buckets_from_shift();
+        clear_and_fill_buckets_from_values();
+    }
+
+    template <typename Op>
+    void do_erase(value_idx_type bucket_idx, Op handle_erased_value) {
+        auto const value_idx_to_remove = at(m_buckets, bucket_idx).m_value_idx;
+
+        // shift down until either empty or an element with correct spot is found
+        auto next_bucket_idx = next(bucket_idx);
+        while (at(m_buckets, next_bucket_idx).m_dist_and_fingerprint >= Bucket::dist_inc * 2) {
+            at(m_buckets, bucket_idx) = {dist_dec(at(m_buckets, next_bucket_idx).m_dist_and_fingerprint),
+                                         at(m_buckets, next_bucket_idx).m_value_idx};
+            bucket_idx = std::exchange(next_bucket_idx, next(next_bucket_idx));
+        }
+        at(m_buckets, bucket_idx) = {};
+        handle_erased_value(std::move(m_values[value_idx_to_remove]));
+
+        // update m_values
+        if (value_idx_to_remove != m_values.size() - 1) {
+            // no luck, we'll have to replace the value with the last one and update the index accordingly
+            auto& val = m_values[value_idx_to_remove];
+            val = std::move(m_values.back());
+
+            // update the values_idx of the moved entry. No need to play the info game, just look until we find the values_idx
+            auto mh = mixed_hash(get_key(val));
+            bucket_idx = bucket_idx_from_hash(mh);
+
+            auto const values_idx_back = static_cast<value_idx_type>(m_values.size() - 1);
+            while (values_idx_back != at(m_buckets, bucket_idx).m_value_idx) {
+                bucket_idx = next(bucket_idx);
+            }
+            at(m_buckets, bucket_idx).m_value_idx = value_idx_to_remove;
+        }
+        m_values.pop_back();
+    }
+
+    template <typename K, typename Op>
+    auto do_erase_key(K&& key, Op handle_erased_value) -> size_t {
+        if (empty()) {
+            return 0;
+        }
+
+        auto [dist_and_fingerprint, bucket_idx] = next_while_less(key);
+
+        while (dist_and_fingerprint == at(m_buckets, bucket_idx).m_dist_and_fingerprint &&
+               !m_equal(key, get_key(m_values[at(m_buckets, bucket_idx).m_value_idx]))) {
+            dist_and_fingerprint = dist_inc(dist_and_fingerprint);
+            bucket_idx = next(bucket_idx);
+        }
+
+        if (dist_and_fingerprint != at(m_buckets, bucket_idx).m_dist_and_fingerprint) {
+            return 0;
+        }
+        do_erase(bucket_idx, handle_erased_value);
+        return 1;
+    }
+
+    template <class K, class M>
+    auto do_insert_or_assign(K&& key, M&& mapped) -> std::pair<iterator, bool> {
+        auto it_isinserted = try_emplace(std::forward<K>(key), std::forward<M>(mapped));
+        if (!it_isinserted.second) {
+            it_isinserted.first->second = std::forward<M>(mapped);
+        }
+        return it_isinserted;
+    }
+
+    template <typename... Args>
+    auto do_place_element(dist_and_fingerprint_type dist_and_fingerprint, value_idx_type bucket_idx, Args&&... args)
+        -> std::pair<iterator, bool> {
+
+        // emplace the new value. If that throws an exception, no harm done; index is still in a valid state
+        m_values.emplace_back(std::forward<Args>(args)...);
+
+        auto value_idx = static_cast<value_idx_type>(m_values.size() - 1);
+        if (ANKERL_UNORDERED_DENSE_UNLIKELY(is_full())) {
+            increase_size();
+        } else {
+            place_and_shift_up({dist_and_fingerprint, value_idx}, bucket_idx);
+        }
+
+        // place element and shift up until we find an empty spot
+        return {begin() + static_cast<difference_type>(value_idx), true};
+    }
+
+    template <typename K, typename... Args>
+    auto do_try_emplace(K&& key, Args&&... args) -> std::pair<iterator, bool> {
+        auto hash = mixed_hash(key);
+        auto dist_and_fingerprint = dist_and_fingerprint_from_hash(hash);
+        auto bucket_idx = bucket_idx_from_hash(hash);
+
+        while (true) {
+            auto* bucket = &at(m_buckets, bucket_idx);
+            if (dist_and_fingerprint == bucket->m_dist_and_fingerprint) {
+                if (m_equal(key, get_key(m_values[bucket->m_value_idx]))) {
+                    return {begin() + static_cast<difference_type>(bucket->m_value_idx), false};
+                }
+            } else if (dist_and_fingerprint > bucket->m_dist_and_fingerprint) {
+                return do_place_element(dist_and_fingerprint,
+                                        bucket_idx,
+                                        std::piecewise_construct,
+                                        std::forward_as_tuple(std::forward<K>(key)),
+                                        std::forward_as_tuple(std::forward<Args>(args)...));
+            }
+            dist_and_fingerprint = dist_inc(dist_and_fingerprint);
+            bucket_idx = next(bucket_idx);
+        }
+    }
+
+    template <typename K>
+    auto do_find(K const& key) -> iterator {
+        if (ANKERL_UNORDERED_DENSE_UNLIKELY(empty())) {
+            return end();
+        }
+
+        auto mh = mixed_hash(key);
+        auto dist_and_fingerprint = dist_and_fingerprint_from_hash(mh);
+        auto bucket_idx = bucket_idx_from_hash(mh);
+        auto* bucket = &at(m_buckets, bucket_idx);
+
+        // unrolled loop. *Always* check a few directly, then enter the loop. This is faster.
+        if (dist_and_fingerprint == bucket->m_dist_and_fingerprint && m_equal(key, get_key(m_values[bucket->m_value_idx]))) {
+            return begin() + static_cast<difference_type>(bucket->m_value_idx);
+        }
+        dist_and_fingerprint = dist_inc(dist_and_fingerprint);
+        bucket_idx = next(bucket_idx);
+        bucket = &at(m_buckets, bucket_idx);
+
+        if (dist_and_fingerprint == bucket->m_dist_and_fingerprint && m_equal(key, get_key(m_values[bucket->m_value_idx]))) {
+            return begin() + static_cast<difference_type>(bucket->m_value_idx);
+        }
+        dist_and_fingerprint = dist_inc(dist_and_fingerprint);
+        bucket_idx = next(bucket_idx);
+        bucket = &at(m_buckets, bucket_idx);
+
+        while (true) {
+            if (dist_and_fingerprint == bucket->m_dist_and_fingerprint) {
+                if (m_equal(key, get_key(m_values[bucket->m_value_idx]))) {
+                    return begin() + static_cast<difference_type>(bucket->m_value_idx);
+                }
+            } else if (dist_and_fingerprint > bucket->m_dist_and_fingerprint) {
+                return end();
+            }
+            dist_and_fingerprint = dist_inc(dist_and_fingerprint);
+            bucket_idx = next(bucket_idx);
+            bucket = &at(m_buckets, bucket_idx);
+        }
+    }
+
+    template <typename K>
+    auto do_find(K const& key) const -> const_iterator {
+        return const_cast<table*>(this)->do_find(key); // NOLINT(cppcoreguidelines-pro-type-const-cast)
+    }
+
+    template <typename K, typename Q = T, std::enable_if_t<is_map_v<Q>, bool> = true>
+    auto do_at(K const& key) -> Q& {
+        if (auto it = find(key); ANKERL_UNORDERED_DENSE_LIKELY(end() != it)) {
+            return it->second;
+        }
+        on_error_key_not_found();
+    }
+
+    template <typename K, typename Q = T, std::enable_if_t<is_map_v<Q>, bool> = true>
+    auto do_at(K const& key) const -> Q const& {
+        return const_cast<table*>(this)->at(key); // NOLINT(cppcoreguidelines-pro-type-const-cast)
+    }
+
+public:
+    explicit table(size_t bucket_count,
+                   Hash const& hash = Hash(),
+                   KeyEqual const& equal = KeyEqual(),
+                   allocator_type const& alloc_or_container = allocator_type())
+        : m_values(alloc_or_container)
+        , m_buckets(alloc_or_container)
+        , m_hash(hash)
+        , m_equal(equal) {
+        if (0 != bucket_count) {
+            reserve(bucket_count);
+        } else {
+            allocate_buckets_from_shift();
+            clear_buckets();
+        }
+    }
+
+    table()
+        : table(0) {}
+
+    table(size_t bucket_count, allocator_type const& alloc)
+        : table(bucket_count, Hash(), KeyEqual(), alloc) {}
+
+    table(size_t bucket_count, Hash const& hash, allocator_type const& alloc)
+        : table(bucket_count, hash, KeyEqual(), alloc) {}
+
+    explicit table(allocator_type const& alloc)
+        : table(0, Hash(), KeyEqual(), alloc) {}
+
+    template <class InputIt>
+    table(InputIt first,
+          InputIt last,
+          size_type bucket_count = 0,
+          Hash const& hash = Hash(),
+          KeyEqual const& equal = KeyEqual(),
+          allocator_type const& alloc = allocator_type())
+        : table(bucket_count, hash, equal, alloc) {
+        insert(first, last);
+    }
+
+    template <class InputIt>
+    table(InputIt first, InputIt last, size_type bucket_count, allocator_type const& alloc)
+        : table(first, last, bucket_count, Hash(), KeyEqual(), alloc) {}
+
+    template <class InputIt>
+    table(InputIt first, InputIt last, size_type bucket_count, Hash const& hash, allocator_type const& alloc)
+        : table(first, last, bucket_count, hash, KeyEqual(), alloc) {}
+
+    table(table const& other)
+        : table(other, other.m_values.get_allocator()) {}
+
+    table(table const& other, allocator_type const& alloc)
+        : m_values(other.m_values, alloc)
+        , m_max_load_factor(other.m_max_load_factor)
+        , m_hash(other.m_hash)
+        , m_equal(other.m_equal) {
+        copy_buckets(other);
+    }
+
+    table(table&& other) noexcept
+        : table(std::move(other), other.m_values.get_allocator()) {}
+
+    table(table&& other, allocator_type const& alloc) noexcept
+        : m_values(alloc) {
+        *this = std::move(other);
+    }
+
+    table(std::initializer_list<value_type> ilist,
+          size_t bucket_count = 0,
+          Hash const& hash = Hash(),
+          KeyEqual const& equal = KeyEqual(),
+          allocator_type const& alloc = allocator_type())
+        : table(bucket_count, hash, equal, alloc) {
+        insert(ilist);
+    }
+
+    table(std::initializer_list<value_type> ilist, size_type bucket_count, allocator_type const& alloc)
+        : table(ilist, bucket_count, Hash(), KeyEqual(), alloc) {}
+
+    table(std::initializer_list<value_type> init, size_type bucket_count, Hash const& hash, allocator_type const& alloc)
+        : table(init, bucket_count, hash, KeyEqual(), alloc) {}
+
+    ~table() {}
+
+    auto operator=(table const& other) -> table& {
+        if (&other != this) {
+            deallocate_buckets(); // deallocate before m_values is set (might have another allocator)
+            m_values = other.m_values;
+            m_max_load_factor = other.m_max_load_factor;
+            m_hash = other.m_hash;
+            m_equal = other.m_equal;
+            m_shifts = initial_shifts;
+            copy_buckets(other);
+        }
+        return *this;
+    }
+
+    auto operator=(table&& other) noexcept(noexcept(std::is_nothrow_move_assignable_v<value_container_type> &&
+                                                    std::is_nothrow_move_assignable_v<Hash> &&
+                                                    std::is_nothrow_move_assignable_v<KeyEqual>)) -> table& {
+        if (&other != this) {
+            deallocate_buckets(); // deallocate before m_values is set (might have another allocator)
+            m_values = std::move(other.m_values);
+            other.m_values.clear();
+
+            // we can only reuse m_buckets when both maps have the same allocator!
+            if (get_allocator() == other.get_allocator()) {
+                m_buckets = std::move(other.m_buckets);
+                other.m_buckets.clear();
+                m_max_bucket_capacity = std::exchange(other.m_max_bucket_capacity, 0);
+                m_shifts = std::exchange(other.m_shifts, initial_shifts);
+                m_max_load_factor = std::exchange(other.m_max_load_factor, default_max_load_factor);
+                m_hash = std::exchange(other.m_hash, {});
+                m_equal = std::exchange(other.m_equal, {});
+                other.allocate_buckets_from_shift();
+                other.clear_buckets();
+            } else {
+                // set max_load_factor *before* copying the other's buckets, so we have the same
+                // behavior
+                m_max_load_factor = other.m_max_load_factor;
+
+                // copy_buckets sets m_buckets, m_num_buckets, m_max_bucket_capacity, m_shifts
+                copy_buckets(other);
+                // clear's the other's buckets so other is now already usable.
+                other.clear_buckets();
+                m_hash = other.m_hash;
+                m_equal = other.m_equal;
+            }
+            // map "other" is now already usable, it's empty.
+        }
+        return *this;
+    }
+
+    auto operator=(std::initializer_list<value_type> ilist) -> table& {
+        clear();
+        insert(ilist);
+        return *this;
+    }
+
+    auto get_allocator() const noexcept -> allocator_type {
+        return m_values.get_allocator();
+    }
+
+    // iterators //////////////////////////////////////////////////////////////
+
+    auto begin() noexcept -> iterator {
+        return m_values.begin();
+    }
+
+    auto begin() const noexcept -> const_iterator {
+        return m_values.begin();
+    }
+
+    auto cbegin() const noexcept -> const_iterator {
+        return m_values.cbegin();
+    }
+
+    auto end() noexcept -> iterator {
+        return m_values.end();
+    }
+
+    auto cend() const noexcept -> const_iterator {
+        return m_values.cend();
+    }
+
+    auto end() const noexcept -> const_iterator {
+        return m_values.end();
+    }
+
+    // capacity ///////////////////////////////////////////////////////////////
+
+    [[nodiscard]] auto empty() const noexcept -> bool {
+        return m_values.empty();
+    }
+
+    [[nodiscard]] auto size() const noexcept -> size_t {
+        return m_values.size();
+    }
+
+    [[nodiscard]] static constexpr auto max_size() noexcept -> size_t {
+        if constexpr ((std::numeric_limits<value_idx_type>::max)() == (std::numeric_limits<size_t>::max)()) {
+            return size_t{1} << (sizeof(value_idx_type) * 8 - 1);
+        } else {
+            return size_t{1} << (sizeof(value_idx_type) * 8);
+        }
+    }
+
+    // modifiers //////////////////////////////////////////////////////////////
+
+    void clear() {
+        m_values.clear();
+        clear_buckets();
+    }
+
+    auto insert(value_type const& value) -> std::pair<iterator, bool> {
+        return emplace(value);
+    }
+
+    auto insert(value_type&& value) -> std::pair<iterator, bool> {
+        return emplace(std::move(value));
+    }
+
+    template <class P, std::enable_if_t<std::is_constructible_v<value_type, P&&>, bool> = true>
+    auto insert(P&& value) -> std::pair<iterator, bool> {
+        return emplace(std::forward<P>(value));
+    }
+
+    auto insert(const_iterator /*hint*/, value_type const& value) -> iterator {
+        return insert(value).first;
+    }
+
+    auto insert(const_iterator /*hint*/, value_type&& value) -> iterator {
+        return insert(std::move(value)).first;
+    }
+
+    template <class P, std::enable_if_t<std::is_constructible_v<value_type, P&&>, bool> = true>
+    auto insert(const_iterator /*hint*/, P&& value) -> iterator {
+        return insert(std::forward<P>(value)).first;
+    }
+
+    template <class InputIt>
+    void insert(InputIt first, InputIt last) {
+        while (first != last) {
+            insert(*first);
+            ++first;
+        }
+    }
+
+    void insert(std::initializer_list<value_type> ilist) {
+        insert(ilist.begin(), ilist.end());
+    }
+
+    // nonstandard API: *this is emptied.
+    // Also see "A Standard flat_map" https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p0429r9.pdf
+    auto extract() && -> value_container_type {
+        return std::move(m_values);
+    }
+
+    // nonstandard API:
+    // Discards the internally held container and replaces it with the one passed. Erases non-unique elements.
+    auto replace(value_container_type&& container) {
+        if (ANKERL_UNORDERED_DENSE_UNLIKELY(container.size() > max_size())) {
+            on_error_too_many_elements();
+        }
+        auto shifts = calc_shifts_for_size(container.size());
+        if (0 == bucket_count() || shifts < m_shifts || container.get_allocator() != m_values.get_allocator()) {
+            m_shifts = shifts;
+            deallocate_buckets();
+            allocate_buckets_from_shift();
+        }
+        clear_buckets();
+
+        m_values = std::move(container);
+
+        // can't use clear_and_fill_buckets_from_values() because container elements might not be unique
+        auto value_idx = value_idx_type{};
+
+        // loop until we reach the end of the container. duplicated entries will be replaced with back().
+        while (value_idx != static_cast<value_idx_type>(m_values.size())) {
+            auto const& key = get_key(m_values[value_idx]);
+
+            auto hash = mixed_hash(key);
+            auto dist_and_fingerprint = dist_and_fingerprint_from_hash(hash);
+            auto bucket_idx = bucket_idx_from_hash(hash);
+
+            bool key_found = false;
+            while (true) {
+                auto const& bucket = at(m_buckets, bucket_idx);
+                if (dist_and_fingerprint > bucket.m_dist_and_fingerprint) {
+                    break;
+                }
+                if (dist_and_fingerprint == bucket.m_dist_and_fingerprint &&
+                    m_equal(key, get_key(m_values[bucket.m_value_idx]))) {
+                    key_found = true;
+                    break;
+                }
+                dist_and_fingerprint = dist_inc(dist_and_fingerprint);
+                bucket_idx = next(bucket_idx);
+            }
+
+            if (key_found) {
+                if (value_idx != static_cast<value_idx_type>(m_values.size() - 1)) {
+                    m_values[value_idx] = std::move(m_values.back());
+                }
+                m_values.pop_back();
+            } else {
+                place_and_shift_up({dist_and_fingerprint, value_idx}, bucket_idx);
+                ++value_idx;
+            }
+        }
+    }
+
+    template <class M, typename Q = T, std::enable_if_t<is_map_v<Q>, bool> = true>
+    auto insert_or_assign(Key const& key, M&& mapped) -> std::pair<iterator, bool> {
+        return do_insert_or_assign(key, std::forward<M>(mapped));
+    }
+
+    template <class M, typename Q = T, std::enable_if_t<is_map_v<Q>, bool> = true>
+    auto insert_or_assign(Key&& key, M&& mapped) -> std::pair<iterator, bool> {
+        return do_insert_or_assign(std::move(key), std::forward<M>(mapped));
+    }
+
+    template <typename K,
+              typename M,
+              typename Q = T,
+              typename H = Hash,
+              typename KE = KeyEqual,
+              std::enable_if_t<is_map_v<Q> && is_transparent_v<H, KE>, bool> = true>
+    auto insert_or_assign(K&& key, M&& mapped) -> std::pair<iterator, bool> {
+        return do_insert_or_assign(std::forward<K>(key), std::forward<M>(mapped));
+    }
+
+    template <class M, typename Q = T, std::enable_if_t<is_map_v<Q>, bool> = true>
+    auto insert_or_assign(const_iterator /*hint*/, Key const& key, M&& mapped) -> iterator {
+        return do_insert_or_assign(key, std::forward<M>(mapped)).first;
+    }
+
+    template <class M, typename Q = T, std::enable_if_t<is_map_v<Q>, bool> = true>
+    auto insert_or_assign(const_iterator /*hint*/, Key&& key, M&& mapped) -> iterator {
+        return do_insert_or_assign(std::move(key), std::forward<M>(mapped)).first;
+    }
+
+    template <typename K,
+              typename M,
+              typename Q = T,
+              typename H = Hash,
+              typename KE = KeyEqual,
+              std::enable_if_t<is_map_v<Q> && is_transparent_v<H, KE>, bool> = true>
+    auto insert_or_assign(const_iterator /*hint*/, K&& key, M&& mapped) -> iterator {
+        return do_insert_or_assign(std::forward<K>(key), std::forward<M>(mapped)).first;
+    }
+
+    // Single arguments for unordered_set can be used without having to construct the value_type
+    template <class K,
+              typename Q = T,
+              typename H = Hash,
+              typename KE = KeyEqual,
+              std::enable_if_t<!is_map_v<Q> && is_transparent_v<H, KE>, bool> = true>
+    auto emplace(K&& key) -> std::pair<iterator, bool> {
+        auto hash = mixed_hash(key);
+        auto dist_and_fingerprint = dist_and_fingerprint_from_hash(hash);
+        auto bucket_idx = bucket_idx_from_hash(hash);
+
+        while (dist_and_fingerprint <= at(m_buckets, bucket_idx).m_dist_and_fingerprint) {
+            if (dist_and_fingerprint == at(m_buckets, bucket_idx).m_dist_and_fingerprint &&
+                m_equal(key, m_values[at(m_buckets, bucket_idx).m_value_idx])) {
+                // found it, return without ever actually creating anything
+                return {begin() + static_cast<difference_type>(at(m_buckets, bucket_idx).m_value_idx), false};
+            }
+            dist_and_fingerprint = dist_inc(dist_and_fingerprint);
+            bucket_idx = next(bucket_idx);
+        }
+
+        // value is new, insert element first, so when exception happens we are in a valid state
+        return do_place_element(dist_and_fingerprint, bucket_idx, std::forward<K>(key));
+    }
+
+    template <class... Args>
+    auto emplace(Args&&... args) -> std::pair<iterator, bool> {
+        // we have to instantiate the value_type to be able to access the key.
+        // 1. emplace_back the object so it is constructed. 2. If the key is already there, pop it later in the loop.
+        auto& key = get_key(m_values.emplace_back(std::forward<Args>(args)...));
+        auto hash = mixed_hash(key);
+        auto dist_and_fingerprint = dist_and_fingerprint_from_hash(hash);
+        auto bucket_idx = bucket_idx_from_hash(hash);
+
+        while (dist_and_fingerprint <= at(m_buckets, bucket_idx).m_dist_and_fingerprint) {
+            if (dist_and_fingerprint == at(m_buckets, bucket_idx).m_dist_and_fingerprint &&
+                m_equal(key, get_key(m_values[at(m_buckets, bucket_idx).m_value_idx]))) {
+                m_values.pop_back(); // value was already there, so get rid of it
+                return {begin() + static_cast<difference_type>(at(m_buckets, bucket_idx).m_value_idx), false};
+            }
+            dist_and_fingerprint = dist_inc(dist_and_fingerprint);
+            bucket_idx = next(bucket_idx);
+        }
+
+        // value is new, place the bucket and shift up until we find an empty spot
+        auto value_idx = static_cast<value_idx_type>(m_values.size() - 1);
+        if (ANKERL_UNORDERED_DENSE_UNLIKELY(is_full())) {
+            // increase_size just rehashes all the data we have in m_values
+            increase_size();
+        } else {
+            // place element and shift up until we find an empty spot
+            place_and_shift_up({dist_and_fingerprint, value_idx}, bucket_idx);
+        }
+        return {begin() + static_cast<difference_type>(value_idx), true};
+    }
+
+    template <class... Args>
+    auto emplace_hint(const_iterator /*hint*/, Args&&... args) -> iterator {
+        return emplace(std::forward<Args>(args)...).first;
+    }
+
+    template <class... Args, typename Q = T, std::enable_if_t<is_map_v<Q>, bool> = true>
+    auto try_emplace(Key const& key, Args&&... args) -> std::pair<iterator, bool> {
+        return do_try_emplace(key, std::forward<Args>(args)...);
+    }
+
+    template <class... Args, typename Q = T, std::enable_if_t<is_map_v<Q>, bool> = true>
+    auto try_emplace(Key&& key, Args&&... args) -> std::pair<iterator, bool> {
+        return do_try_emplace(std::move(key), std::forward<Args>(args)...);
+    }
+
+    template <class... Args, typename Q = T, std::enable_if_t<is_map_v<Q>, bool> = true>
+    auto try_emplace(const_iterator /*hint*/, Key const& key, Args&&... args) -> iterator {
+        return do_try_emplace(key, std::forward<Args>(args)...).first;
+    }
+
+    template <class... Args, typename Q = T, std::enable_if_t<is_map_v<Q>, bool> = true>
+    auto try_emplace(const_iterator /*hint*/, Key&& key, Args&&... args) -> iterator {
+        return do_try_emplace(std::move(key), std::forward<Args>(args)...).first;
+    }
+
+    template <
+        typename K,
+        typename... Args,
+        typename Q = T,
+        typename H = Hash,
+        typename KE = KeyEqual,
+        std::enable_if_t<is_map_v<Q> && is_transparent_v<H, KE> && is_neither_convertible_v<K&&, iterator, const_iterator>,
+                         bool> = true>
+    auto try_emplace(K&& key, Args&&... args) -> std::pair<iterator, bool> {
+        return do_try_emplace(std::forward<K>(key), std::forward<Args>(args)...);
+    }
+
+    template <
+        typename K,
+        typename... Args,
+        typename Q = T,
+        typename H = Hash,
+        typename KE = KeyEqual,
+        std::enable_if_t<is_map_v<Q> && is_transparent_v<H, KE> && is_neither_convertible_v<K&&, iterator, const_iterator>,
+                         bool> = true>
+    auto try_emplace(const_iterator /*hint*/, K&& key, Args&&... args) -> iterator {
+        return do_try_emplace(std::forward<K>(key), std::forward<Args>(args)...).first;
+    }
+
+    auto erase(iterator it) -> iterator {
+        auto hash = mixed_hash(get_key(*it));
+        auto bucket_idx = bucket_idx_from_hash(hash);
+
+        auto const value_idx_to_remove = static_cast<value_idx_type>(it - cbegin());
+        while (at(m_buckets, bucket_idx).m_value_idx != value_idx_to_remove) {
+            bucket_idx = next(bucket_idx);
+        }
+
+        do_erase(bucket_idx, [](value_type&& /*unused*/) {
+        });
+        return begin() + static_cast<difference_type>(value_idx_to_remove);
+    }
+
+    auto extract(iterator it) -> value_type {
+        auto hash = mixed_hash(get_key(*it));
+        auto bucket_idx = bucket_idx_from_hash(hash);
+
+        auto const value_idx_to_remove = static_cast<value_idx_type>(it - cbegin());
+        while (at(m_buckets, bucket_idx).m_value_idx != value_idx_to_remove) {
+            bucket_idx = next(bucket_idx);
+        }
+
+        auto tmp = std::optional<value_type>{};
+        do_erase(bucket_idx, [&tmp](value_type&& val) {
+            tmp = std::move(val);
+        });
+        return std::move(tmp).value();
+    }
+
+    template <typename Q = T, std::enable_if_t<is_map_v<Q>, bool> = true>
+    auto erase(const_iterator it) -> iterator {
+        return erase(begin() + (it - cbegin()));
+    }
+
+    template <typename Q = T, std::enable_if_t<is_map_v<Q>, bool> = true>
+    auto extract(const_iterator it) -> value_type {
+        return extract(begin() + (it - cbegin()));
+    }
+
+    auto erase(const_iterator first, const_iterator last) -> iterator {
+        auto const idx_first = first - cbegin();
+        auto const idx_last = last - cbegin();
+        auto const first_to_last = std::distance(first, last);
+        auto const last_to_end = std::distance(last, cend());
+
+        // remove elements from left to right which moves elements from the end back
+        auto const mid = idx_first + (std::min)(first_to_last, last_to_end);
+        auto idx = idx_first;
+        while (idx != mid) {
+            erase(begin() + idx);
+            ++idx;
+        }
+
+        // all elements from the right are moved, now remove the last element until all done
+        idx = idx_last;
+        while (idx != mid) {
+            --idx;
+            erase(begin() + idx);
+        }
+
+        return begin() + idx_first;
+    }
+
+    auto erase(Key const& key) -> size_t {
+        return do_erase_key(key, [](value_type&& /*unused*/) {
+        });
+    }
+
+    auto extract(Key const& key) -> std::optional<value_type> {
+        auto tmp = std::optional<value_type>{};
+        do_erase_key(key, [&tmp](value_type&& val) {
+            tmp = std::move(val);
+        });
+        return tmp;
+    }
+
+    template <class K, class H = Hash, class KE = KeyEqual, std::enable_if_t<is_transparent_v<H, KE>, bool> = true>
+    auto erase(K&& key) -> size_t {
+        return do_erase_key(std::forward<K>(key), [](value_type&& /*unused*/) {
+        });
+    }
+
+    template <class K, class H = Hash, class KE = KeyEqual, std::enable_if_t<is_transparent_v<H, KE>, bool> = true>
+    auto extract(K&& key) -> std::optional<value_type> {
+        auto tmp = std::optional<value_type>{};
+        do_erase_key(std::forward<K>(key), [&tmp](value_type&& val) {
+            tmp = std::move(val);
+        });
+        return tmp;
+    }
+
+    void swap(table& other) noexcept(noexcept(std::is_nothrow_swappable_v<value_container_type> &&
+                                              std::is_nothrow_swappable_v<Hash> && std::is_nothrow_swappable_v<KeyEqual>)) {
+        using std::swap;
+        swap(other, *this);
+    }
+
+    // lookup /////////////////////////////////////////////////////////////////
+
+    template <typename Q = T, std::enable_if_t<is_map_v<Q>, bool> = true>
+    auto at(key_type const& key) -> Q& {
+        return do_at(key);
+    }
+
+    template <typename K,
+              typename Q = T,
+              typename H = Hash,
+              typename KE = KeyEqual,
+              std::enable_if_t<is_map_v<Q> && is_transparent_v<H, KE>, bool> = true>
+    auto at(K const& key) -> Q& {
+        return do_at(key);
+    }
+
+    template <typename Q = T, std::enable_if_t<is_map_v<Q>, bool> = true>
+    auto at(key_type const& key) const -> Q const& {
+        return do_at(key);
+    }
+
+    template <typename K,
+              typename Q = T,
+              typename H = Hash,
+              typename KE = KeyEqual,
+              std::enable_if_t<is_map_v<Q> && is_transparent_v<H, KE>, bool> = true>
+    auto at(K const& key) const -> Q const& {
+        return do_at(key);
+    }
+
+    template <typename Q = T, std::enable_if_t<is_map_v<Q>, bool> = true>
+    auto operator[](Key const& key) -> Q& {
+        return try_emplace(key).first->second;
+    }
+
+    template <typename Q = T, std::enable_if_t<is_map_v<Q>, bool> = true>
+    auto operator[](Key&& key) -> Q& {
+        return try_emplace(std::move(key)).first->second;
+    }
+
+    template <typename K,
+              typename Q = T,
+              typename H = Hash,
+              typename KE = KeyEqual,
+              std::enable_if_t<is_map_v<Q> && is_transparent_v<H, KE>, bool> = true>
+    auto operator[](K&& key) -> Q& {
+        return try_emplace(std::forward<K>(key)).first->second;
+    }
+
+    auto count(Key const& key) const -> size_t {
+        return find(key) == end() ? 0 : 1;
+    }
+
+    template <class K, class H = Hash, class KE = KeyEqual, std::enable_if_t<is_transparent_v<H, KE>, bool> = true>
+    auto count(K const& key) const -> size_t {
+        return find(key) == end() ? 0 : 1;
+    }
+
+    auto find(Key const& key) -> iterator {
+        return do_find(key);
+    }
+
+    auto find(Key const& key) const -> const_iterator {
+        return do_find(key);
+    }
+
+    template <class K, class H = Hash, class KE = KeyEqual, std::enable_if_t<is_transparent_v<H, KE>, bool> = true>
+    auto find(K const& key) -> iterator {
+        return do_find(key);
+    }
+
+    template <class K, class H = Hash, class KE = KeyEqual, std::enable_if_t<is_transparent_v<H, KE>, bool> = true>
+    auto find(K const& key) const -> const_iterator {
+        return do_find(key);
+    }
+
+    auto contains(Key const& key) const -> bool {
+        return find(key) != end();
+    }
+
+    template <class K, class H = Hash, class KE = KeyEqual, std::enable_if_t<is_transparent_v<H, KE>, bool> = true>
+    auto contains(K const& key) const -> bool {
+        return find(key) != end();
+    }
+
+    auto equal_range(Key const& key) -> std::pair<iterator, iterator> {
+        auto it = do_find(key);
+        return {it, it == end() ? end() : it + 1};
+    }
+
+    auto equal_range(const Key& key) const -> std::pair<const_iterator, const_iterator> {
+        auto it = do_find(key);
+        return {it, it == end() ? end() : it + 1};
+    }
+
+    template <class K, class H = Hash, class KE = KeyEqual, std::enable_if_t<is_transparent_v<H, KE>, bool> = true>
+    auto equal_range(K const& key) -> std::pair<iterator, iterator> {
+        auto it = do_find(key);
+        return {it, it == end() ? end() : it + 1};
+    }
+
+    template <class K, class H = Hash, class KE = KeyEqual, std::enable_if_t<is_transparent_v<H, KE>, bool> = true>
+    auto equal_range(K const& key) const -> std::pair<const_iterator, const_iterator> {
+        auto it = do_find(key);
+        return {it, it == end() ? end() : it + 1};
+    }
+
+    // bucket interface ///////////////////////////////////////////////////////
+
+    auto bucket_count() const noexcept -> size_t { // NOLINT(modernize-use-nodiscard)
+        return m_buckets.size();
+    }
+
+    static constexpr auto max_bucket_count() noexcept -> size_t { // NOLINT(modernize-use-nodiscard)
+        return max_size();
+    }
+
+    // hash policy ////////////////////////////////////////////////////////////
+
+    [[nodiscard]] auto load_factor() const -> float {
+        return bucket_count() ? static_cast<float>(size()) / static_cast<float>(bucket_count()) : 0.0F;
+    }
+
+    [[nodiscard]] auto max_load_factor() const -> float {
+        return m_max_load_factor;
+    }
+
+    void max_load_factor(float ml) {
+        m_max_load_factor = ml;
+        if (bucket_count() != max_bucket_count()) {
+            m_max_bucket_capacity = static_cast<value_idx_type>(static_cast<float>(bucket_count()) * max_load_factor());
+        }
+    }
+
+    void rehash(size_t count) {
+        count = (std::min)(count, max_size());
+        auto shifts = calc_shifts_for_size((std::max)(count, size()));
+        if (shifts != m_shifts) {
+            m_shifts = shifts;
+            deallocate_buckets();
+            m_values.shrink_to_fit();
+            allocate_buckets_from_shift();
+            clear_and_fill_buckets_from_values();
+        }
+    }
+
+    void reserve(size_t capa) {
+        capa = (std::min)(capa, max_size());
+        if constexpr (has_reserve<value_container_type>) {
+            // std::deque doesn't have reserve(). Make sure we only call when available
+            m_values.reserve(capa);
+        }
+        auto shifts = calc_shifts_for_size((std::max)(capa, size()));
+        if (0 == bucket_count() || shifts < m_shifts) {
+            m_shifts = shifts;
+            deallocate_buckets();
+            allocate_buckets_from_shift();
+            clear_and_fill_buckets_from_values();
+        }
+    }
+
+    // observers //////////////////////////////////////////////////////////////
+
+    auto hash_function() const -> hasher {
+        return m_hash;
+    }
+
+    auto key_eq() const -> key_equal {
+        return m_equal;
+    }
+
+    // nonstandard API: expose the underlying values container
+    [[nodiscard]] auto values() const noexcept -> value_container_type const& {
+        return m_values;
+    }
+
+    // non-member functions ///////////////////////////////////////////////////
+
+    friend auto operator==(table const& a, table const& b) -> bool {
+        if (&a == &b) {
+            return true;
+        }
+        if (a.size() != b.size()) {
+            return false;
+        }
+        for (auto const& b_entry : b) {
+            auto it = a.find(get_key(b_entry));
+            if constexpr (is_map_v<T>) {
+                // map: check that key is here, then also check that value is the same
+                if (a.end() == it || !(b_entry.second == it->second)) {
+                    return false;
+                }
+            } else {
+                // set: only check that the key is here
+                if (a.end() == it) {
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+
+    friend auto operator!=(table const& a, table const& b) -> bool {
+        return !(a == b);
+    }
+};
+
+} // namespace detail
+
+ANKERL_UNORDERED_DENSE_EXPORT template <class Key,
+                                        class T,
+                                        class Hash = hash<Key>,
+                                        class KeyEqual = std::equal_to<Key>,
+                                        class AllocatorOrContainer = std::allocator<std::pair<Key, T>>,
+                                        class Bucket = bucket_type::standard,
+                                        class BucketContainer = detail::default_container_t>
+using map = detail::table<Key, T, Hash, KeyEqual, AllocatorOrContainer, Bucket, BucketContainer, false>;
+
+ANKERL_UNORDERED_DENSE_EXPORT template <class Key,
+                                        class T,
+                                        class Hash = hash<Key>,
+                                        class KeyEqual = std::equal_to<Key>,
+                                        class AllocatorOrContainer = std::allocator<std::pair<Key, T>>,
+                                        class Bucket = bucket_type::standard,
+                                        class BucketContainer = detail::default_container_t>
+using segmented_map = detail::table<Key, T, Hash, KeyEqual, AllocatorOrContainer, Bucket, BucketContainer, true>;
+
+ANKERL_UNORDERED_DENSE_EXPORT template <class Key,
+                                        class Hash = hash<Key>,
+                                        class KeyEqual = std::equal_to<Key>,
+                                        class AllocatorOrContainer = std::allocator<Key>,
+                                        class Bucket = bucket_type::standard,
+                                        class BucketContainer = detail::default_container_t>
+using set = detail::table<Key, void, Hash, KeyEqual, AllocatorOrContainer, Bucket, BucketContainer, false>;
+
+ANKERL_UNORDERED_DENSE_EXPORT template <class Key,
+                                        class Hash = hash<Key>,
+                                        class KeyEqual = std::equal_to<Key>,
+                                        class AllocatorOrContainer = std::allocator<Key>,
+                                        class Bucket = bucket_type::standard,
+                                        class BucketContainer = detail::default_container_t>
+using segmented_set = detail::table<Key, void, Hash, KeyEqual, AllocatorOrContainer, Bucket, BucketContainer, true>;
+
+#    if defined(ANKERL_UNORDERED_DENSE_PMR)
+
+namespace pmr {
+
+ANKERL_UNORDERED_DENSE_EXPORT template <class Key,
+                                        class T,
+                                        class Hash = hash<Key>,
+                                        class KeyEqual = std::equal_to<Key>,
+                                        class Bucket = bucket_type::standard>
+using map = detail::table<Key,
+                          T,
+                          Hash,
+                          KeyEqual,
+                          ANKERL_UNORDERED_DENSE_PMR::polymorphic_allocator<std::pair<Key, T>>,
+                          Bucket,
+                          detail::default_container_t,
+                          false>;
+
+ANKERL_UNORDERED_DENSE_EXPORT template <class Key,
+                                        class T,
+                                        class Hash = hash<Key>,
+                                        class KeyEqual = std::equal_to<Key>,
+                                        class Bucket = bucket_type::standard>
+using segmented_map = detail::table<Key,
+                                    T,
+                                    Hash,
+                                    KeyEqual,
+                                    ANKERL_UNORDERED_DENSE_PMR::polymorphic_allocator<std::pair<Key, T>>,
+                                    Bucket,
+                                    detail::default_container_t,
+                                    true>;
+
+ANKERL_UNORDERED_DENSE_EXPORT template <class Key,
+                                        class Hash = hash<Key>,
+                                        class KeyEqual = std::equal_to<Key>,
+                                        class Bucket = bucket_type::standard>
+using set = detail::table<Key,
+                          void,
+                          Hash,
+                          KeyEqual,
+                          ANKERL_UNORDERED_DENSE_PMR::polymorphic_allocator<Key>,
+                          Bucket,
+                          detail::default_container_t,
+                          false>;
+
+ANKERL_UNORDERED_DENSE_EXPORT template <class Key,
+                                        class Hash = hash<Key>,
+                                        class KeyEqual = std::equal_to<Key>,
+                                        class Bucket = bucket_type::standard>
+using segmented_set = detail::table<Key,
+                                    void,
+                                    Hash,
+                                    KeyEqual,
+                                    ANKERL_UNORDERED_DENSE_PMR::polymorphic_allocator<Key>,
+                                    Bucket,
+                                    detail::default_container_t,
+                                    true>;
+
+} // namespace pmr
+
+#    endif
+
+// deduction guides ///////////////////////////////////////////////////////////
+
+// deduction guides for alias templates are only possible since C++20
+// see https://en.cppreference.com/w/cpp/language/class_template_argument_deduction
+
+} // namespace ANKERL_UNORDERED_DENSE_NAMESPACE
+} // namespace ankerl::unordered_dense
+
+// std extensions /////////////////////////////////////////////////////////////
+
+namespace std { // NOLINT(cert-dcl58-cpp)
+
+ANKERL_UNORDERED_DENSE_EXPORT template <class Key,
+                                        class T,
+                                        class Hash,
+                                        class KeyEqual,
+                                        class AllocatorOrContainer,
+                                        class Bucket,
+                                        class Pred,
+                                        class BucketContainer,
+                                        bool IsSegmented>
+// NOLINTNEXTLINE(cert-dcl58-cpp)
+auto erase_if(
+    ankerl::unordered_dense::detail::table<Key, T, Hash, KeyEqual, AllocatorOrContainer, Bucket, BucketContainer, IsSegmented>&
+        map,
+    Pred pred) -> size_t {
+    using map_t = ankerl::unordered_dense::detail::
+        table<Key, T, Hash, KeyEqual, AllocatorOrContainer, Bucket, BucketContainer, IsSegmented>;
+
+    // going back to front because erase() invalidates the end iterator
+    auto const old_size = map.size();
+    auto idx = old_size;
+    while (idx) {
+        --idx;
+        auto it = map.begin() + static_cast<typename map_t::difference_type>(idx);
+        if (pred(*it)) {
+            map.erase(it);
+        }
+    }
+
+    return old_size - map.size();
+}
+
+} // namespace std
+
+#endif
+#endif

From 1be5b82102bbe1581aa7ce04320b9ea03140cbfa Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Mon, 25 Aug 2025 15:26:34 -0300
Subject: [PATCH 62/82] perf: optimize collect APIs

---
 src/collect-mcycle-hashes-state-access.h      | 19 ++--
 src/collect-uarch-cycle-hashes-state-access.h | 21 +++--
 src/hash-tree.h                               |  5 +-
 src/i-dirty-page-tree.h                       |  6 +-
 src/machine-address-ranges.h                  |  2 +-
 src/machine.cpp                               | 89 ++-----------------
 src/machine.h                                 | 80 ++++++++++++++---
 7 files changed, 109 insertions(+), 113 deletions(-)

diff --git a/src/collect-mcycle-hashes-state-access.h b/src/collect-mcycle-hashes-state-access.h
index 10c569f7f..532046254 100644
--- a/src/collect-mcycle-hashes-state-access.h
+++ b/src/collect-mcycle-hashes-state-access.h
@@ -19,8 +19,8 @@
 
 #include <cassert>
 #include <stdexcept>
-#include <unordered_set>
 
+#include "compiler-defines.h"
 #include "hash-tree.h"
 #include "i-accept-scoped-notes.h"
 #include "i-prefer-shadow-state.h"
@@ -68,7 +68,7 @@ class collect_mcycle_hashes_state_access :
 private:
     using fast_addr_type = host_addr;
 
-    void mark_dirty_word(uint64_t address) const {
+    NO_INLINE void mark_dirty_word(uint64_t address) const {
         constexpr uint64_t word_mask = ~(HASH_TREE_WORD_SIZE - 1);
         m_c.dirty_words.insert(address & word_mask);
     }
@@ -79,13 +79,20 @@ class collect_mcycle_hashes_state_access :
     friend i_prefer_shadow_state<collect_mcycle_hashes_state_access>;
 
     uint64_t do_read_shadow_register(shadow_registers_what what) const {
-        return m_m.read_reg(machine_reg_enum(what));
+        // Code assumes we only attempt to read valid registers
+        static_assert(shadow_registers_get_what(AR_SHADOW_REGISTERS_START) == shadow_registers_what::x0,
+            "code assumes x0 is the first shadow register");
+        const auto *regs = &m_m.get_state().shadow.registers.x[0];
+        return regs[(static_cast<uint64_t>(what) - AR_SHADOW_REGISTERS_START) / sizeof(uint64_t)];
     }
 
     void do_write_shadow_register(shadow_registers_what what, uint64_t val) const {
-        auto reg = machine_reg_enum(what);
-        mark_dirty_word(machine_reg_address(reg));
-        m_m.write_reg(reg, val);
+        // Code assumes we only attempt to write valid and writeable registers
+        static_assert(shadow_registers_get_what(AR_SHADOW_REGISTERS_START) == shadow_registers_what::x0,
+            "code assumes x0 is the first shadow register");
+        auto *regs = &m_m.get_state().shadow.registers.x[0];
+        regs[(static_cast<uint64_t>(what) - AR_SHADOW_REGISTERS_START) / sizeof(uint64_t)] = val;
+        mark_dirty_word(static_cast<uint64_t>(what));
     }
 
     // -----
diff --git a/src/collect-uarch-cycle-hashes-state-access.h b/src/collect-uarch-cycle-hashes-state-access.h
index b80f752fd..17bf7e2ef 100644
--- a/src/collect-uarch-cycle-hashes-state-access.h
+++ b/src/collect-uarch-cycle-hashes-state-access.h
@@ -21,8 +21,8 @@
 /// \brief State access implementation that record and logs all accesses
 #include <cstdint>
 #include <stdexcept>
-#include <unordered_set>
 
+#include "compiler-defines.h"
 #include "hash-tree.h"
 #include "i-accept-scoped-notes.h"
 #include "i-prefer-shadow-uarch-state.h"
@@ -58,7 +58,7 @@ class collect_uarch_cycle_hashes_state_access :
     collect_uarch_cycle_hashes_state_access(context &c, machine &m) : m_c(c), m_m(m) {}
 
 private:
-    void mark_dirty_word(uint64_t address) const {
+    NO_INLINE void mark_dirty_word(uint64_t address) const {
         constexpr uint64_t word_mask = ~(HASH_TREE_WORD_SIZE - 1);
         m_c.dirty_words.insert(address & word_mask);
     }
@@ -69,13 +69,22 @@ class collect_uarch_cycle_hashes_state_access :
     friend i_prefer_shadow_uarch_state<collect_uarch_cycle_hashes_state_access>;
 
     uint64_t do_read_shadow_uarch_state(shadow_uarch_state_what what) const {
-        return m_m.read_reg(machine_reg_enum(what));
+        // Code assumes we only attempt to read valid registers
+        static_assert(shadow_uarch_state_get_what(AR_SHADOW_UARCH_STATE_START) ==
+                shadow_uarch_state_what::uarch_halt_flag,
+            "code assumes halt_flag is the first shadow uarch register");
+        const auto *regs = &m_m.get_uarch_state().registers.halt_flag;
+        return regs[(static_cast<uint64_t>(what) - AR_SHADOW_UARCH_STATE_START) / sizeof(uint64_t)];
     }
 
     void do_write_shadow_uarch_state(shadow_uarch_state_what what, uint64_t val) const {
-        auto reg = machine_reg_enum(what);
-        mark_dirty_word(machine_reg_address(reg));
-        m_m.write_reg(reg, val);
+        // Code assumes we only attempt to write valid and writeable registers
+        static_assert(shadow_uarch_state_get_what(AR_SHADOW_UARCH_STATE_START) ==
+                shadow_uarch_state_what::uarch_halt_flag,
+            "code assumes halt_flag is the first shadow uarch register");
+        auto *regs = &m_m.get_uarch_state().registers.halt_flag;
+        regs[(static_cast<uint64_t>(what) - AR_SHADOW_UARCH_STATE_START) / sizeof(uint64_t)] = val;
+        mark_dirty_word(static_cast<uint64_t>(what));
     }
 
     // -----
diff --git a/src/hash-tree.h b/src/hash-tree.h
index 1043d14bc..30bfab88d 100644
--- a/src/hash-tree.h
+++ b/src/hash-tree.h
@@ -18,9 +18,10 @@
 #define HASH_TREE_H
 
 #include <iosfwd>
-#include <unordered_set>
 #include <vector>
 
+#include "unordered_dense.h"
+
 #include "address-range.h"
 #include "hash-tree-constants.h"
 #include "hash-tree-proof.h"
@@ -116,7 +117,7 @@ class hash_tree {
 public:
     using proof_type = hash_tree_proof;
 
-    using dirty_words_type = std::unordered_set<uint64_t>;
+    using dirty_words_type = ankerl::unordered_dense::set<uint64_t>;
     using nodes_type = std::vector<node_type>;
     using sibling_hashes_type = std::vector<machine_hash>;
 
diff --git a/src/i-dirty-page-tree.h b/src/i-dirty-page-tree.h
index 2d9edb8c7..07e146a5b 100644
--- a/src/i-dirty-page-tree.h
+++ b/src/i-dirty-page-tree.h
@@ -274,7 +274,7 @@ class i_dirty_page_tree {
     /// \detail The derived class is free to ignore the operation
     void mark_dirty_page_and_up(uint64_t offset) noexcept {
         const auto pos = to_position(offset, AR_LOG2_PAGE_SIZE); // Returns invalid position if node is out of bounds
-        if (pos != invalid_position) {
+        if (pos != invalid_position) [[likely]] {
             mark_dirty_leaf_position_and_up(pos);
         }
     }
@@ -290,7 +290,7 @@ class i_dirty_page_tree {
     /// \detail The derived class is free to ignore the operation
     void mark_clean_page_and_up(uint64_t offset) noexcept {
         const auto pos = to_position(offset, AR_LOG2_PAGE_SIZE); // Returns invalid position if node is out of bounds
-        if (pos != invalid_position) {
+        if (pos != invalid_position) [[likely]] {
             mark_clean_leaf_position_and_up(pos);
         }
     }
@@ -300,7 +300,7 @@ class i_dirty_page_tree {
     /// \param length Length of range of interest, in bytes
     void mark_dirty_pages_and_up(uint64_t offset, uint64_t length) noexcept {
         const auto end = offset + length;
-        for (offset &= ~(AR_PAGE_SIZE - 1); offset < end; offset += AR_PAGE_SIZE) {
+        for (offset &= ~(AR_PAGE_SIZE - 1); offset < end; offset += AR_PAGE_SIZE) [[likely]] {
             mark_dirty_page_and_up(offset);
         }
     }
diff --git a/src/machine-address-ranges.h b/src/machine-address-ranges.h
index bb57b0528..26408b3bc 100644
--- a/src/machine-address-ranges.h
+++ b/src/machine-address-ranges.h
@@ -94,7 +94,7 @@ class machine_address_ranges {
 
     /// \brief Returns the address range corresponding to the ith PMA
     const address_range &read_pma(uint64_t index) const noexcept {
-        if (index >= m_pmas.size()) {
+        if (index >= m_pmas.size()) [[unlikely]] {
             static auto sentinel = make_empty_address_range("sentinel");
             return sentinel;
         }
diff --git a/src/machine.cpp b/src/machine.cpp
index c39166053..cbcd64fbc 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -382,74 +382,6 @@ void machine::set_runtime_config(machine_runtime_config r) {
     m_r = std::move(r); // NOLINT(hicpp-move-const-arg,performance-move-const-arg)
 }
 
-uint64_t machine::get_paddr(host_addr haddr, uint64_t pma_index) const {
-    return static_cast<uint64_t>(haddr + get_hp_offset(pma_index));
-}
-
-host_addr machine::get_host_addr(uint64_t paddr, uint64_t pma_index) const {
-    return host_addr{paddr} - get_hp_offset(pma_index);
-}
-
-void machine::mark_dirty_page(uint64_t paddr, uint64_t pma_index) {
-    auto &ar = read_pma(pma_index);
-    ar.get_dirty_page_tree().mark_dirty_page_and_up(paddr - ar.get_start());
-}
-
-void machine::mark_dirty_page(host_addr haddr, uint64_t pma_index) {
-    auto paddr = get_paddr(haddr, pma_index);
-    mark_dirty_page(paddr, pma_index);
-}
-
-uint64_t machine::read_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, shadow_tlb_what reg) const {
-    switch (reg) {
-        case shadow_tlb_what::vaddr_page:
-            return m_s->shadow.tlb[set_index][slot_index].vaddr_page;
-        case shadow_tlb_what::vp_offset:
-            return m_s->shadow.tlb[set_index][slot_index].vp_offset;
-        case shadow_tlb_what::pma_index:
-            return m_s->shadow.tlb[set_index][slot_index].pma_index;
-        case shadow_tlb_what::zero_padding_:
-            return m_s->shadow.tlb[set_index][slot_index].zero_padding_;
-        default:
-            throw std::domain_error{"unknown shadow TLB register"};
-    }
-}
-
-void machine::write_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, host_addr vh_offset,
-    uint64_t pma_index) {
-    uint64_t vp_offset = 0;
-    if (vaddr_page != TLB_INVALID_PAGE) {
-        vp_offset = get_paddr(vh_offset, pma_index);
-    }
-    m_s->penumbra.tlb[set_index][slot_index].vaddr_page = vaddr_page;
-    m_s->penumbra.tlb[set_index][slot_index].vh_offset = vh_offset;
-    m_s->shadow.tlb[set_index][slot_index].vaddr_page = vaddr_page;
-    m_s->shadow.tlb[set_index][slot_index].vp_offset = vp_offset;
-    m_s->shadow.tlb[set_index][slot_index].pma_index = pma_index;
-    m_s->shadow.tlb[set_index][slot_index].zero_padding_ = 0;
-}
-
-void machine::write_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset,
-    uint64_t pma_index) {
-    if (vaddr_page != TLB_INVALID_PAGE) {
-        auto paddr_page = vaddr_page + vp_offset;
-        const auto vh_offset = get_host_addr(paddr_page, pma_index) - vaddr_page;
-        write_tlb(set_index, slot_index, vaddr_page, vh_offset, pma_index);
-    } else {
-        write_tlb(set_index, slot_index, TLB_INVALID_PAGE, host_addr{0}, TLB_INVALID_PMA_INDEX);
-    }
-}
-
-host_addr machine::get_hp_offset(uint64_t pma_index) const {
-    const auto &ar = read_pma(pma_index);
-    if (!ar.is_memory()) {
-        throw std::domain_error{"PMA index is not of memory range ("s + ar.get_description() + ")"};
-    }
-    auto haddr = cast_ptr_to_host_addr(ar.get_host_memory());
-    auto paddr = ar.get_start();
-    return paddr - haddr;
-}
-
 static void store_address_range(const backing_store_config &from_config, const address_range &ar, bool read_only,
     const std::string &dir, sharing_mode sharing, scope_remove &remover) {
     if (ar.is_empty()) {
@@ -1413,10 +1345,6 @@ bool machine::update_hash_tree() const {
     return m_ht.update(m_ars);
 }
 
-bool machine::update_hash_tree_page(uint64_t address) {
-    return m_ht.update_page(m_ars, address);
-}
-
 machine_hash machine::get_root_hash() const {
     if (!update_hash_tree()) {
         throw std::runtime_error{"update hash tree failed"};
@@ -1424,10 +1352,6 @@ machine_hash machine::get_root_hash() const {
     return m_ht.get_root_hash();
 }
 
-machine_hash machine::get_node_hash(uint64_t address, int log2_size, skip_hash_tree_update_t /* unused */) const {
-    return m_ht.get_node_hash(m_ars, address, log2_size);
-}
-
 const char *machine::get_what_name(uint64_t paddr) {
     if (paddr >= AR_UARCH_RAM_START && paddr - AR_UARCH_RAM_START < AR_UARCH_RAM_LENGTH) {
         return "uarch.ram";
@@ -1463,10 +1387,6 @@ bool machine::verify_hash_tree() const {
     return m_ht.verify(m_ars);
 }
 
-machine::proof_type machine::get_proof(uint64_t address, int log2_size, skip_hash_tree_update_t /*unused*/) const {
-    return m_ht.get_proof(m_ars, address, log2_size);
-}
-
 machine::proof_type machine::get_proof(uint64_t address, int log2_size) const {
     if (!update_hash_tree()) {
         throw std::runtime_error{"update hash tree failed"};
@@ -1944,10 +1864,10 @@ interpreter_break_reason machine::log_step(uint64_t mcycle_count, const std::str
     if (__builtin_add_overflow(a.read_mcycle(), mcycle_count, &mcycle_end)) {
         mcycle_end = UINT64_MAX;
     }
+    os_silence_putchar(m_r.htif.no_console_putchar);
     auto break_reason = interpret(a, mcycle_end);
     a.finish();
     auto root_hash_after = get_root_hash();
-    os_silence_putchar(m_r.htif.no_console_putchar);
     verify_step(root_hash_before, filename, mcycle_count, root_hash_after);
     return break_reason;
 }
@@ -2071,13 +1991,13 @@ void machine::collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_
         }
     }
     collect_mcycle_hashes_state_access::context context{};
-    context.dirty_words.reserve(mcycle_period * 3);
+    context.dirty_words.reserve(std::clamp<uint64_t>(mcycle_period * 4, 256, 2048));
+    result.hashes.reserve(mcycle_period);
     const collect_mcycle_hashes_state_access a(context, *this);
     os_silence_putchar(m_r.htif.no_console_putchar);
     auto mcycle_start = read_reg(reg::mcycle);
     for (uint64_t period = 0; period < period_count; ++period) {
         uint64_t mcycle_target{};
-        context.dirty_words.clear();
         if (__builtin_add_overflow(mcycle_start, mcycle_period - mcycle_phase, &mcycle_target)) {
             mcycle_target = UINT64_MAX;
         }
@@ -2116,7 +2036,8 @@ void machine::collect_uarch_cycle_root_hashes(uint64_t mcycle_count, uarch_cycle
         throw std::runtime_error{"microarchitecture is not reset"};
     }
     collect_uarch_cycle_hashes_state_access::context context{};
-    context.dirty_words.reserve(mcycle_count);
+    context.dirty_words.reserve(std::clamp<uint64_t>(mcycle_count * 4, 256, 2048));
+    result.hashes.reserve(mcycle_count * 512);
     const collect_uarch_cycle_hashes_state_access a(context, *this);
     os_silence_putchar(m_r.htif.no_console_putchar);
     auto mcycle_start = read_reg(reg::mcycle);
diff --git a/src/machine.h b/src/machine.h
index c683c207c..a46638aa2 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -22,6 +22,7 @@
 
 #include <cstdint>
 #include <memory>
+#include <stdexcept>
 #include <string>
 #include <unordered_map>
 #include <utility>
@@ -77,7 +78,16 @@ class machine final {
 
     /// \brief Returns offset that converts between machine host addresses and target physical addresses
     /// \param pma_index Index of the memory PMA for the desired offset
-    host_addr get_hp_offset(uint64_t pma_index) const;
+    host_addr get_hp_offset(uint64_t pma_index) const {
+        using namespace std::string_literals;
+        const auto &ar = read_pma(pma_index);
+        if (!ar.is_memory()) [[unlikely]] {
+            throw std::domain_error{"PMA index is not of memory range ("s + ar.get_description() + ")"s};
+        }
+        auto haddr = cast_ptr_to_host_addr(ar.get_host_memory());
+        auto paddr = ar.get_start();
+        return paddr - haddr;
+    }
 
     /// \brief Initializes processor
     /// \param p Processor configuration
@@ -327,7 +337,9 @@ class machine final {
     /// \brief Update a single page in the hash-tree after it is modified in the machine state.
     /// \param address Any address inside modified page.
     /// \returns true if succeeded, false otherwise.
-    bool update_hash_tree_page(uint64_t address);
+    bool update_hash_tree_page(uint64_t address) {
+        return m_ht.update_page(m_ars, address);
+    }
 
     /// \brief Obtains the proof for a node in the hash-tree.
     /// \param address Address of target node. Must be aligned to a 2<sup>log2_size</sup> boundary.
@@ -346,7 +358,9 @@ class machine final {
     /// \details If the node is smaller than a page size, then it must lie entirely inside the same PMA range.
     /// This overload is used to optimize proof generation when the caller knows that the tree is already up to
     /// date.
-    proof_type get_proof(uint64_t address, int log2_size, skip_hash_tree_update_t /*unused*/) const;
+    proof_type get_proof(uint64_t address, int log2_size, skip_hash_tree_update_t /*unused*/) const {
+        return m_ht.get_proof(m_ars, address, log2_size);
+    }
 
     /// \brief Obtains the root hash of the hash-tree.
     /// \returns The hash.
@@ -362,7 +376,9 @@ class machine final {
     /// \param address Address of target node. Must be aligned to a 2<sup>log2_size</sup> boundary.
     /// \param log2_size log<sub>2</sub> of size subintended by target node.
     /// \returns The hash.
-    machine_hash get_node_hash(uint64_t address, int log2_size, skip_hash_tree_update_t /*unused*/) const;
+    machine_hash get_node_hash(uint64_t address, int log2_size, skip_hash_tree_update_t /*unused*/) const {
+        return m_ht.get_node_hash(m_ars, address, log2_size);
+    }
 
     /// \brief Verifies integrity of hash tree without making any modifications to it tree.
     /// \returns True if tree is self-consistent, false otherwise.
@@ -486,24 +502,34 @@ class machine final {
     /// \param pma_index Index of PMA where address falls
     /// \returns Corresponding target physical address
     /// \details This method also converts from vh_offset to vp_offset
-    uint64_t get_paddr(host_addr haddr, uint64_t pma_index) const;
+    uint64_t get_paddr(host_addr haddr, uint64_t pma_index) const {
+        return static_cast<uint64_t>(haddr + get_hp_offset(pma_index));
+    }
 
     /// \brief Converts from target physical address to machine host address
     /// \param paddr Target physical address to convert
     /// \param pma_index Index of PMA where address falls
     /// \returns Corresponding machine host address
     /// \details This method also converts from vp_offset to vh_offset
-    host_addr get_host_addr(uint64_t paddr, uint64_t pma_index) const;
+    host_addr get_host_addr(uint64_t paddr, uint64_t pma_index) const {
+        return host_addr{paddr} - get_hp_offset(pma_index);
+    }
 
     /// \brief Marks a page as dirty
     /// \param haddr Machine host address within page
     /// \param pma_index Index of PMA where address falls
-    void mark_dirty_page(host_addr haddr, uint64_t pma_index);
+    void mark_dirty_page(host_addr haddr, uint64_t pma_index) {
+        auto paddr = get_paddr(haddr, pma_index);
+        mark_dirty_page(paddr, pma_index);
+    }
 
     /// \brief Marks a page as dirty
     /// \param paddr Target phyislcal address within page
     /// \param pma_index Index of PMA where address falls
-    void mark_dirty_page(uint64_t paddr, uint64_t pma_index);
+    void mark_dirty_page(uint64_t paddr, uint64_t pma_index) {
+        auto &ar = read_pma(pma_index);
+        ar.get_dirty_page_tree().mark_dirty_page_and_up(paddr - ar.get_start());
+    }
 
     /// \brief Updates a TLB slot
     /// \param set_index TLB_CODE, TLB_READ, or TLB_WRITE
@@ -512,7 +538,18 @@ class machine final {
     /// \param vh_offset Offset from target virtual addresses to host addresses within page
     /// \param pma_index Index of PMA where address falls
     void write_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, host_addr vh_offset,
-        uint64_t pma_index);
+        uint64_t pma_index) {
+        uint64_t vp_offset = 0;
+        if (vaddr_page != TLB_INVALID_PAGE) [[likely]] {
+            vp_offset = get_paddr(vh_offset, pma_index);
+        }
+        m_s->penumbra.tlb[set_index][slot_index].vaddr_page = vaddr_page;
+        m_s->penumbra.tlb[set_index][slot_index].vh_offset = vh_offset;
+        m_s->shadow.tlb[set_index][slot_index].vaddr_page = vaddr_page;
+        m_s->shadow.tlb[set_index][slot_index].vp_offset = vp_offset;
+        m_s->shadow.tlb[set_index][slot_index].pma_index = pma_index;
+        m_s->shadow.tlb[set_index][slot_index].zero_padding_ = 0;
+    }
 
     /// \brief Updates a TLB slot
     /// \param set_index TLB_CODE, TLB_READ, or TLB_WRITE
@@ -521,14 +558,35 @@ class machine final {
     /// \param vp_offset Offset from target virtual addresses to target physical addresses within page
     /// \param pma_index Index of PMA where address falls
     void write_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, uint64_t vaddr_page, uint64_t vp_offset,
-        uint64_t pma_index);
+        uint64_t pma_index) {
+        if (vaddr_page != TLB_INVALID_PAGE) [[likely]] {
+            auto paddr_page = vaddr_page + vp_offset;
+            const auto vh_offset = get_host_addr(paddr_page, pma_index) - vaddr_page;
+            write_tlb(set_index, slot_index, vaddr_page, vh_offset, pma_index);
+        } else {
+            write_tlb(set_index, slot_index, TLB_INVALID_PAGE, host_addr{0}, TLB_INVALID_PMA_INDEX);
+        }
+    }
 
     /// \brief Reads a TLB register
     /// \param set_index TLB_CODE, TLB_READ, or TLB_WRITE
     /// \param slot_index Index of slot to read
     /// \param reg Register to read from slot
     /// \returns Value of register
-    uint64_t read_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, shadow_tlb_what reg) const;
+    uint64_t read_shadow_tlb(TLB_set_index set_index, uint64_t slot_index, shadow_tlb_what reg) const {
+        switch (reg) {
+            case shadow_tlb_what::vaddr_page:
+                return m_s->shadow.tlb[set_index][slot_index].vaddr_page;
+            case shadow_tlb_what::vp_offset:
+                return m_s->shadow.tlb[set_index][slot_index].vp_offset;
+            case shadow_tlb_what::pma_index:
+                return m_s->shadow.tlb[set_index][slot_index].pma_index;
+            case shadow_tlb_what::zero_padding_:
+                return m_s->shadow.tlb[set_index][slot_index].zero_padding_;
+            default:
+                throw std::domain_error{"unknown shadow TLB register"};
+        }
+    }
 
     /// \brief Sends cmio response and returns an access log
     /// \param reason Reason for sending response.

From 267057db4e0273eb03411f12e57ab37a2be61f7d Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Wed, 27 Aug 2025 16:04:03 -0300
Subject: [PATCH 63/82] refactor: remove circular_buffer

---
 src/algorithm.h            |  37 ++++
 src/circular-buffer.h      | 412 -------------------------------------
 src/concepts.h             |   8 +
 src/hash-tree.cpp          |  22 +-
 src/page-hash-tree-cache.h |  27 +--
 5 files changed, 66 insertions(+), 440 deletions(-)
 create mode 100644 src/algorithm.h
 delete mode 100644 src/circular-buffer.h

diff --git a/src/algorithm.h b/src/algorithm.h
new file mode 100644
index 000000000..e0732ea4d
--- /dev/null
+++ b/src/algorithm.h
@@ -0,0 +1,37 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef ALGORITHM_H
+#define ALGORITHM_H
+
+#include "concepts.h"
+
+namespace cartesi::algorithm {
+
+/// \brief Adds new entry to back of container, if not already there
+/// \param value Value to insert.
+template <BackInsertableContainer Container, typename T>
+    requires std::constructible_from<typename Container::value_type, T &&> &&
+    std::equality_comparable_with<typename Container::value_type, T>
+constexpr void try_push_back(Container &container, T &&value) {
+    if (container.empty() || container.back() != value) {
+        container.push_back(std::forward<T>(value));
+    }
+}
+
+} // namespace cartesi::algorithm
+
+#endif
diff --git a/src/circular-buffer.h b/src/circular-buffer.h
deleted file mode 100644
index 4c59d46b9..000000000
--- a/src/circular-buffer.h
+++ /dev/null
@@ -1,412 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef CIRCULAR_BUFFER_H
-#define CIRCULAR_BUFFER_H
-
-/// \file
-/// \brief Circular buffer container
-
-#include <concepts>
-#include <cstddef>
-#include <iterator>
-#include <limits>
-#include <span>
-#include <utility>
-#include <variant>
-#include <vector>
-
-#include <boost/container/static_vector.hpp>
-#include <boost/iterator/iterator_adaptor.hpp>
-
-#include "concepts.h"
-#include "meta.h"
-
-namespace cartesi {
-
-/// \brief Circular buffer container.
-/// \tparam T type of entry in container.
-/// \tparam N maximum number of entries container can hold.
-/// \details The circular buffer container with a fixed number of entries.
-/// The container that be statically allocated, when \p N is passed as a template argument at compile time.
-/// It can be dynamically allocated, with the size is chosen in the constructor at runtime.
-/// \p T does not need to be default-constructible.
-template <typename T, size_t N = std::dynamic_extent>
-class circular_buffer {
-    using base = circular_buffer<T, N>;
-    using container_dynamic = std::vector<T>;
-    using container_static = boost::container::static_vector<T, N + 1>;
-    using container_base = std::conditional_t<N == std::dynamic_extent, container_dynamic, container_static>;
-
-public:
-    using value_type = typename container_base::value_type;
-    using size_type = typename container_base::size_type;
-    using difference_type = typename container_base::difference_type;
-    using reference = typename container_base::reference;
-    using const_reference = typename container_base::const_reference;
-    using pointer = typename container_base::pointer;
-    using const_pointer = typename container_base::const_pointer;
-
-    static constexpr auto max_size = std::numeric_limits<difference_type>::max() - 1;
-
-    /// \brief Constructor for statically allocated container
-    constexpr circular_buffer() noexcept
-        requires(N > 0 && N < max_size && N != std::dynamic_extent)
-        : m_uninitialized_entries{modulus()} {}
-
-    /// \brief Constructor for dynamically allocated container
-    /// \param n maximum number of entries container can hold
-    explicit circular_buffer(size_type n)
-        requires(N == std::dynamic_extent)
-        : m_uninitialized_entries{static_cast<difference_type>(n + 1)}, m_modulus{static_cast<difference_type>(n + 1)} {
-        if (n == 0) {
-            throw std::invalid_argument{"capacity must be > 0"};
-        }
-        if (n > max_size) {
-            throw std::invalid_argument{"capacity is too large"};
-        }
-        m_storage.reserve(n + 1); // Allocate once and for all
-    }
-
-    // Default move and copy constructors
-    circular_buffer(const circular_buffer &) = default;
-    circular_buffer(circular_buffer &&) noexcept = default;
-    circular_buffer &operator=(const circular_buffer &) = default;
-    circular_buffer &operator=(circular_buffer &&) noexcept = default;
-    ~circular_buffer() = default;
-
-    /// \brief Returns number of entries currently in container
-    /// \returns Number of entries currently in container
-    [[nodiscard]] size_type size() const noexcept {
-        auto n = m_end - m_begin;
-        if (n < 0) {
-            n += modulus();
-        }
-        return static_cast<size_type>(n);
-    }
-
-    /// \brief Returns maximum number of entries container can hold
-    /// \returns Maximum number of entries container can hold
-    [[nodiscard]] constexpr size_type capacity() const noexcept {
-        if constexpr (N == std::dynamic_extent) {
-            return m_modulus - 1;
-        } else {
-            return N;
-        }
-    }
-
-    /// \brief Returns modulus to use for modular arithmetic
-    /// \returns Modulus to use for modular arithmetic
-    [[nodiscard]] constexpr difference_type modulus() const noexcept {
-        if constexpr (N == std::dynamic_extent) {
-            return m_modulus;
-        } else {
-            return static_cast<difference_type>(N + 1);
-        }
-    }
-
-    /// \brief Tells if container is empty
-    /// \returns True if empty, false otherwise
-    [[nodiscard]] bool empty() const noexcept {
-        return m_begin == m_end;
-    }
-
-    /// \brief Tells if container is full
-    /// \returns True if true, false otherwise
-    [[nodiscard]] bool full() const noexcept {
-        return size() == capacity();
-    }
-
-    /// \brief Adds new entry to back of container
-    /// \tparam U Type for universal reference to value
-    /// \param value Value to insert. L-value references are copied, r-value references are moved.
-    template <typename U>
-        requires std::constructible_from<T, U &&>
-    void push_back(U &&value) noexcept {
-        // If we still have uninitialized entries, push_back into storage
-        if (m_uninitialized_entries != 0) {
-            --m_uninitialized_entries;
-            m_storage.push_back(std::forward<U>(value));
-            // Otherwise, simply copy/move construct over initialized entries
-        } else {
-            dereference_offset(m_end) = std::forward<U>(value);
-        }
-        increment_offset(m_end);
-        if (m_end == m_begin) {
-            increment_offset(m_begin);
-        }
-    }
-
-    /// \brief Construct entry at back of container
-    /// \tparam Args... Types of entry constructor arguments
-    /// \param ...args Arguments to entry constructor
-    template <typename... Args>
-        requires std::constructible_from<T, Args...>
-    void emplace_back(Args &&...args) {
-        if (m_uninitialized_entries != 0) {
-            --m_uninitialized_entries;
-            m_storage.emplace_back(std::forward<Args>(args)...);
-        } else {
-            dereference_offset(m_end) = T(std::forward<Args>(args)...);
-        }
-        increment_offset(m_end);
-        if (m_end == m_begin) {
-            increment_offset(m_begin);
-        }
-    }
-
-    /// \brief Adds new entry to back of container, if not already there
-    /// \tparam U Type for universal reference to value
-    /// \param value Value to insert. L-value references are copied, r-value references are moved.
-    /// \details The container must not be full.
-    template <typename U>
-        requires std::constructible_from<T, U &&> && std::equality_comparable_with<T, U>
-    void try_push_back(U &&value) noexcept {
-        if (empty() || back() != value) {
-            assert(!full() && "circular buffer container is full");
-            push_back(std::forward<U>(value));
-        }
-    }
-
-    /// \brief Removes entry at back of container, if any
-    void pop_back() noexcept {
-        if (!empty()) {
-            decrement_offset(m_end);
-        }
-    }
-
-    /// \brief Removes entry at the front of container, if any
-    void pop_front() noexcept {
-        if (!empty()) {
-            increment_offset(m_begin);
-        }
-    }
-
-    /// \brief Returns entry at front of container
-    /// \detail If container is empty, returns garbage
-    reference front() noexcept {
-        return dereference_offset(m_begin);
-    }
-
-    /// \brief Returns entry at front of container
-    /// \detail If container is empty, returns garbage
-    const_reference front() const noexcept {
-        return dereference_offset(m_begin);
-    }
-
-    /// \brief Returns entry at back of container
-    /// \detail If container is empty, returns garbage
-    reference back() noexcept {
-        auto b = m_end;
-        decrement_offset(b);
-        return dereference_offset(b);
-    }
-
-    /// \brief Returns entry at back of container
-    /// \detail If container is empty, returns garbage
-    const_reference back() const noexcept {
-        auto b = m_end;
-        decrement_offset(b);
-        return dereference_offset(b);
-    }
-
-    /// \brief Removes all entries from container
-    void clear() noexcept {
-        m_storage.clear();
-        m_storage.reserve(modulus());
-        m_begin = m_end = 0;
-        m_uninitialized_entries = modulus();
-    }
-
-    /// \brief Base class for all iterators
-    /// \tparam CB class of container (so it works with const and non-const)
-    /// \tparam Value class of container entry (so it works with const and non-const)
-    template <typename CB, typename Value>
-    class iterator_base :
-        public boost::iterator_facade<iterator_base<CB, Value>, Value, std::random_access_iterator_tag, Value &,
-            difference_type> {
-        CB *m_cb;
-        difference_type m_offset;
-
-    public:
-        iterator_base() noexcept : iterator_base::iterator_facade_{}, m_cb{}, m_offset{0} {}
-
-        iterator_base(CB *cb, difference_type offset) noexcept :
-            iterator_base::iterator_facade_{},
-            m_cb{cb},
-            m_offset{offset} {}
-
-    private:
-        friend class boost::iterator_core_access;
-
-        void increment() {
-            m_cb->increment_offset(m_offset);
-        }
-
-        void decrement() {
-            m_cb->decrement_offset(m_offset);
-        }
-
-        template <typename CB_Other, typename ValueOther>
-
-        bool equal(const iterator_base<CB_Other, ValueOther> &other) const
-            requires SameAsNoCVRef<CB, CB_Other> && SameAsNoCVRef<Value, ValueOther>
-        {
-            if (m_cb != other.m_cb) {
-                return false;
-            }
-            return m_cb->equal_offset(m_offset, other.m_offset);
-        }
-
-        Value &dereference() const {
-            return m_cb->dereference_offset(m_offset);
-        }
-    };
-
-    // Friend declaration so iterators can use private methods in container
-    template <typename CB, typename Value>
-    friend class iterator_base;
-
-    // Iterator types
-    using iterator = iterator_base<base, value_type>;
-    using const_iterator = iterator_base<const base, const value_type>;
-    using const_reverse_iterator = std::reverse_iterator<const_iterator>;
-    using reverse_iterator = std::reverse_iterator<iterator>;
-
-    /// \brief Returns iterator to first entry in container
-    /// \returns Iterator to first entry in container
-    auto begin() noexcept {
-        return iterator{this, m_begin};
-    }
-
-    /// \brief Returns iterator to one past last entry in container
-    /// \returns Iterator to one past last entry in container
-    auto end() noexcept {
-        return iterator{this, m_end};
-    }
-
-    /// \brief Returns iterator to first entry in container
-    /// \returns Iterator to first entry in container
-    auto begin() const noexcept {
-        return const_iterator{this, m_begin};
-    }
-
-    /// \brief Returns iterator to one past last entry in container
-    /// \returns Iterator to one past last entry in container
-    auto end() const noexcept {
-        return const_iterator{this, m_end};
-    }
-
-    /// \brief Returns constant iterator to first entry in container
-    /// \returns Constant iterator to first entry in container
-    auto cbegin() const noexcept {
-        return const_iterator{this, m_begin};
-    }
-
-    /// \brief Returns constant iterator to one past last entry in container
-    /// \returns Constant iterator to one past last entry in container
-    auto cend() const noexcept {
-        return const_iterator{this, m_end};
-    }
-
-    /// \brief Returns iterator to first entry in reversed container
-    /// \returns Iterator to first entry in reversed container
-    auto rbegin() noexcept {
-        return reverse_iterator{end()};
-    }
-
-    /// \brief Returns iterator to one past last entry in revesed container
-    /// \returns Iterator to one past last entry in revesed container
-    auto rend() noexcept {
-        return reverse_iterator{begin()};
-    }
-
-    /// \brief Returns iterator to first entry in reversed container
-    /// \returns Iterator to first entry in reversed container
-    auto rbegin() const noexcept {
-        return const_reverse_iterator{end()};
-    }
-
-    /// \brief Returns iterator to one past last entry in revesed container
-    /// \returns Iterator to one past last entry in revesed container
-    auto rend() const noexcept {
-        return const_reverse_iterator{begin()};
-    }
-
-    /// \brief Returns constant iterator to first entry in reversed container
-    /// \returns Constant iterator to first entry in reversed container
-    auto crbegin() const noexcept {
-        return const_reverse_iterator{end()};
-    }
-
-    /// \brief Returns constant iterator to one past last entry in revesed container
-    /// \returns Constant iterator to one past last entry in revesed container
-    auto crend() const noexcept {
-        return const_reverse_iterator{begin()};
-    }
-
-private:
-    /// \brief Increment offset using modular arithmetic
-    /// \details Assumes offset is in {0, ..., modulus()-1}
-    void increment_offset(difference_type &offset) noexcept {
-        assert(offset >= 0 && offset < modulus() && "offset is out of range");
-        ++offset;
-        if (offset >= modulus()) {
-            offset -= modulus();
-        }
-    }
-
-    /// \brief Decrements offset using modular arithmetic
-    /// \details Assumes offset is in {0, ..., modulus()-1}
-    void decrement_offset(difference_type &offset) noexcept {
-        assert(offset >= 0 && offset < modulus() && "offset is out of range");
-        --offset;
-        if (offset < 0) {
-            offset += modulus();
-        }
-    }
-
-    /// \brief Returns reference to entry at offset
-    /// \details Assumes offset is in {0, ..., modulus()-1}
-    reference dereference_offset(difference_type offset) noexcept {
-        assert(offset >= 0 && offset < modulus() && "offset is out of range");
-        return *(m_storage.data() + offset);
-    }
-
-    /// \brief Returns constant reference to entry at offset
-    /// \details Assumes offset is in {0, ..., modulus()-1}
-    const_reference dereference_offset(difference_type offset) const noexcept {
-        assert(offset >= 0 && offset < modulus() && "offset is out of range");
-        return *(m_storage.data() + offset);
-    }
-
-    /// \brief Checks if offsets refer to same entry
-    /// \details Assumes offset is in {0, ..., modulus()-1}
-    static bool equal_offset(difference_type a, difference_type b) noexcept {
-        return a == b;
-    }
-
-    container_base m_storage; // Storage for all entries. Starts empty (but already allocated).
-    // m_begin and m_end use modular arithmetic and are always in {0, modulus()-1}
-    difference_type m_begin{0};              // First entry
-    difference_type m_end{0};                // One past past last entry
-    difference_type m_uninitialized_entries; // Number of entries not yet initialized
-    [[no_unique_address]] std::conditional_t<N == std::dynamic_extent, difference_type, std::monostate> m_modulus;
-};
-
-} // namespace cartesi
-
-#endif // CIRCULAR_BUFFER_H
diff --git a/src/concepts.h b/src/concepts.h
index fe02342ca..4d1c852ea 100644
--- a/src/concepts.h
+++ b/src/concepts.h
@@ -53,6 +53,14 @@ concept ScopedEnum = std::is_enum_v<E> && !std::is_convertible_v<E, std::underly
 template <typename T, typename... Ts>
 concept SameAsAny = (std::same_as<T, Ts> || ...);
 
+// C++20 concept to check if a container is back insertable
+template <typename T>
+concept BackInsertableContainer = std::ranges::range<T> && requires(T container, typename T::value_type value) {
+    { container.empty() } -> std::convertible_to<bool>;
+    { container.back() } -> std::convertible_to<typename T::reference>;
+    container.push_back(value);
+};
+
 } // namespace cartesi
 
 #endif
diff --git a/src/hash-tree.cpp b/src/hash-tree.cpp
index 5b2862fba..554dcd242 100644
--- a/src/hash-tree.cpp
+++ b/src/hash-tree.cpp
@@ -23,6 +23,7 @@
 #include <string>
 #include <utility>
 
+#include "algorithm.h"
 #include "os-features.h"
 
 #ifdef HAVE_OPENMP
@@ -283,9 +284,7 @@ bool hash_tree::return_updated_dirty_pages(address_ranges ars, dirty_pages &batc
             // If page hash was changed during update
             if (changed) {
                 // If we haven't already done so, add changed address range to list
-                if (changed_ars.empty() || ar_index != changed_ars.back()) {
-                    changed_ars.push_back(ar_index);
-                }
+                algorithm::try_push_back(changed_ars, ar_index);
                 // If page was marked dirty but was not in fact dirty
             } else {
                 // We can safely mark the page clean because its contents already matched its hash
@@ -699,9 +698,7 @@ bool hash_tree::update_words(address_ranges ars, dirty_words_type dirty_words) {
             continue;
         }
         auto &ar = ars[ar_index];
-        if (changed_ars.empty() || changed_ars.back() != ar_index) {
-            changed_ars.push_back(ar_index);
-        }
+        algorithm::try_push_back(changed_ars, ar_index);
         max_level_count = std::max(max_level_count, ar.get_level_count());
         const auto *base = ar.get_host_memory();
         if (!ar.is_memory() || base == nullptr) {
@@ -742,11 +739,8 @@ bool hash_tree::update_words(address_ranges ars, dirty_words_type dirty_words) {
         auto node_hash_view = dht.node_hash_view(page_offset, HASH_TREE_LOG2_PAGE_SIZE);
         std::ranges::copy(cache_entry.root_hash_view(), node_hash_view.begin());
         m_page_cache.return_entry(cache_entry);
-        auto dense_node =
-            dense_node_entry{.dht = dht, .offset = get_aligned_address(page_offset, HASH_TREE_LOG2_PAGE_SIZE + 1)};
-        if (curr_dense_node.empty() || curr_dense_node.back() != dense_node) {
-            curr_dense_node.push_back(dense_node);
-        }
+        algorithm::try_push_back(curr_dense_node,
+            dense_node_entry{.dht = dht, .offset = get_aligned_address(page_offset, HASH_TREE_LOG2_PAGE_SIZE + 1)});
     }
     for (int level = 1; level < max_level_count; ++level) {
         auto log2_size = HASH_TREE_LOG2_PAGE_SIZE + level;
@@ -759,10 +753,8 @@ bool hash_tree::update_words(address_ranges ars, dirty_words_type dirty_words) {
             auto left = dht.node_hash_view(offset, log2_size - 1);
             auto right = dht.node_hash_view(offset + child_size, log2_size - 1);
             queue.enqueue(left, right, parent);
-            auto dense_node = dense_node_entry{.dht = dht, .offset = get_aligned_address(offset, log2_size + 1)};
-            if (next_dense_node.empty() || next_dense_node.back() != dense_node) {
-                next_dense_node.push_back(dense_node);
-            }
+            algorithm::try_push_back(next_dense_node,
+                dense_node_entry{.dht = dht, .offset = get_aligned_address(offset, log2_size + 1)});
         }
         queue.flush();
         std::swap(curr_dense_node, next_dense_node);
diff --git a/src/page-hash-tree-cache.h b/src/page-hash-tree-cache.h
index 0b2e6fdb3..2523a476d 100644
--- a/src/page-hash-tree-cache.h
+++ b/src/page-hash-tree-cache.h
@@ -29,10 +29,11 @@
 #include <span>
 #include <unordered_map>
 
+#include <boost/container/static_vector.hpp>
 #include <boost/intrusive/list.hpp>
 
 #include "address-range-constants.h"
-#include "circular-buffer.h"
+#include "algorithm.h"
 #include "compiler-defines.h"
 #include "hash-tree-constants.h"
 #include "i-hasher.h"
@@ -271,7 +272,7 @@ class page_hash_tree_cache {
 
         simd_data_hasher<hasher_type, const_hash_tree_word_view> m_leaves_queue;
         simd_concat_hasher<hasher_type, const_machine_hash_view> m_concat_queue;
-        circular_buffer<dirty_entry, QUEUE_MAX_SIZE> m_dirty_queue;
+        boost::container::static_vector<dirty_entry, QUEUE_MAX_SIZE> m_dirty_queue;
 
     public:
         static constexpr int QUEUE_MAX_PAGE_COUNT = hasher_type::MAX_LANE_COUNT;
@@ -281,7 +282,8 @@ class page_hash_tree_cache {
         /// \brief Enqueues a leaf for hashing
         void enqueue_leaf(const_hash_tree_word_view data, page_hash_tree_view page_tree, int word_index) noexcept {
             m_leaves_queue.enqueue(data, page_tree[word_index]);
-            m_dirty_queue.try_push_back(dirty_entry{.page_tree = page_tree, .node_index = entry::parent(word_index)});
+            algorithm::try_push_back(m_dirty_queue,
+                dirty_entry{.page_tree = page_tree, .node_index = entry::parent(word_index)});
         }
 
         /// \brief Flushes the entire queue
@@ -289,21 +291,20 @@ class page_hash_tree_cache {
             m_leaves_queue.flush();
             int hashes = 0;
 
+            decltype(m_dirty_queue) next_dirty_queue;
             while (!m_dirty_queue.empty()) {
-                for (size_t i = 0, n = m_dirty_queue.size(); i < n; ++i) {
-                    const auto &d = m_dirty_queue.front();
-                    const auto node_index = d.node_index;
-                    const auto page_tree = d.page_tree;
-                    m_dirty_queue.pop_front();
+                for (const dirty_entry &d : m_dirty_queue) {
                     ++hashes;
-                    m_concat_queue.enqueue(page_tree[entry::left_child(node_index)],
-                        page_tree[entry::right_child(node_index)], page_tree[node_index]);
-                    if (node_index > 1) [[likely]] {
-                        m_dirty_queue.try_push_back(
-                            dirty_entry{.page_tree = page_tree, .node_index = entry::parent(node_index)});
+                    m_concat_queue.enqueue(d.page_tree[entry::left_child(d.node_index)],
+                        d.page_tree[entry::right_child(d.node_index)], d.page_tree[d.node_index]);
+                    if (d.node_index > 1) [[likely]] {
+                        algorithm::try_push_back(next_dirty_queue,
+                            dirty_entry{.page_tree = d.page_tree, .node_index = entry::parent(d.node_index)});
                     }
                 }
                 m_concat_queue.flush();
+                m_dirty_queue.clear();
+                std::swap(m_dirty_queue, next_dirty_queue);
             }
             return hashes;
         }

From 8bcfe4b30fe28a05237d4807391aa96686e188b0 Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Wed, 27 Aug 2025 17:26:53 -0300
Subject: [PATCH 64/82] perf: optimize collect mcycle hashes

---
 src/collect-mcycle-hashes-state-access.h | 370 +++++++++++++++++++++--
 src/hash-tree.h                          |   1 +
 src/machine-address-ranges.cpp           |  10 -
 src/machine-address-ranges.h             |  15 +-
 src/machine.cpp                          |  15 +-
 src/machine.h                            |   5 +-
 6 files changed, 369 insertions(+), 47 deletions(-)

diff --git a/src/collect-mcycle-hashes-state-access.h b/src/collect-mcycle-hashes-state-access.h
index 532046254..188acf90f 100644
--- a/src/collect-mcycle-hashes-state-access.h
+++ b/src/collect-mcycle-hashes-state-access.h
@@ -44,12 +44,11 @@ struct i_state_access_fast_addr<collect_mcycle_hashes_state_access> {
 /// \brief Records machine state access into a step log file
 class collect_mcycle_hashes_state_access :
     public i_state_access<collect_mcycle_hashes_state_access>,
-    public i_prefer_shadow_state<collect_mcycle_hashes_state_access>,
     public i_accept_scoped_notes<collect_mcycle_hashes_state_access> {
 
 public:
     struct context {
-        hash_tree::dirty_words_type dirty_words;
+        hash_tree::dirty_pages_type dirty_pages;
     };
 
 private:
@@ -67,38 +66,358 @@ class collect_mcycle_hashes_state_access :
 
 private:
     using fast_addr_type = host_addr;
+    static constexpr uint64_t page_mask = ~(HASH_TREE_PAGE_SIZE - 1);
 
     NO_INLINE void mark_dirty_word(uint64_t address) const {
-        constexpr uint64_t word_mask = ~(HASH_TREE_WORD_SIZE - 1);
-        m_c.dirty_words.insert(address & word_mask);
+        m_c.dirty_pages.insert(address & page_mask);
+    }
+
+    NO_INLINE void mark_dirty_word(host_addr address, uint64_t pma_index) const {
+        m_c.dirty_pages.insert(m_m.get_paddr(address, pma_index) & page_mask);
     }
 
     // -----
-    // i_prefer_shadow_state interface implementation
+    // i_state_access interface implementation
     // -----
-    friend i_prefer_shadow_state<collect_mcycle_hashes_state_access>;
+    friend i_state_access<collect_mcycle_hashes_state_access>;
 
-    uint64_t do_read_shadow_register(shadow_registers_what what) const {
-        // Code assumes we only attempt to read valid registers
-        static_assert(shadow_registers_get_what(AR_SHADOW_REGISTERS_START) == shadow_registers_what::x0,
-            "code assumes x0 is the first shadow register");
-        const auto *regs = &m_m.get_state().shadow.registers.x[0];
-        return regs[(static_cast<uint64_t>(what) - AR_SHADOW_REGISTERS_START) / sizeof(uint64_t)];
+    uint64_t do_read_x(int i) const {
+        return m_m.get_state().shadow.registers.x[i];
     }
 
-    void do_write_shadow_register(shadow_registers_what what, uint64_t val) const {
-        // Code assumes we only attempt to write valid and writeable registers
-        static_assert(shadow_registers_get_what(AR_SHADOW_REGISTERS_START) == shadow_registers_what::x0,
-            "code assumes x0 is the first shadow register");
-        auto *regs = &m_m.get_state().shadow.registers.x[0];
-        regs[(static_cast<uint64_t>(what) - AR_SHADOW_REGISTERS_START) / sizeof(uint64_t)] = val;
-        mark_dirty_word(static_cast<uint64_t>(what));
+    void do_write_x(int i, uint64_t val) const {
+        assert(i != 0);
+        m_m.get_state().shadow.registers.x[i] = val;
     }
 
-    // -----
-    // i_state_access interface implementation
-    // -----
-    friend i_state_access<collect_mcycle_hashes_state_access>;
+    uint64_t do_read_f(int i) const {
+        return m_m.get_state().shadow.registers.f[i];
+    }
+
+    void do_write_f(int i, uint64_t val) const {
+        m_m.get_state().shadow.registers.f[i] = val;
+    }
+
+    uint64_t do_read_pc() const {
+        return m_m.get_state().shadow.registers.pc;
+    }
+
+    void do_write_pc(uint64_t val) const {
+        m_m.get_state().shadow.registers.pc = val;
+    }
+
+    uint64_t do_read_fcsr() const {
+        return m_m.get_state().shadow.registers.fcsr;
+    }
+
+    void do_write_fcsr(uint64_t val) const {
+        m_m.get_state().shadow.registers.fcsr = val;
+    }
+
+    uint64_t do_read_icycleinstret() const {
+        return m_m.get_state().shadow.registers.icycleinstret;
+    }
+
+    void do_write_icycleinstret(uint64_t val) const {
+        m_m.get_state().shadow.registers.icycleinstret = val;
+    }
+
+    uint64_t do_read_mvendorid() const { // NOLINT(readability-convert-member-functions-to-static)
+        return MVENDORID_INIT;
+    }
+
+    uint64_t do_read_marchid() const { // NOLINT(readability-convert-member-functions-to-static)
+        return MARCHID_INIT;
+    }
+
+    uint64_t do_read_mimpid() const { // NOLINT(readability-convert-member-functions-to-static)
+        return MIMPID_INIT;
+    }
+
+    uint64_t do_read_mcycle() const {
+        return m_m.get_state().shadow.registers.mcycle;
+    }
+
+    void do_write_mcycle(uint64_t val) const {
+        m_m.get_state().shadow.registers.mcycle = val;
+
+        // Only mcycle writes mark all registers as dirty.
+        // This is done for efficiency, since the interpreter writes mcycle only when exiting its loop.
+        // Also note that by design it is impossible for the interpreter to write other registers without writing
+        // mcycle.
+        for (uint64_t paddr_page = AR_SHADOW_REGISTERS_START;
+            paddr_page < AR_SHADOW_REGISTERS_START + AR_SHADOW_STATE_LENGTH; paddr_page += HASH_TREE_PAGE_SIZE) {
+            mark_dirty_word(paddr_page);
+        }
+    }
+
+    uint64_t do_read_mstatus() const {
+        return m_m.get_state().shadow.registers.mstatus;
+    }
+
+    void do_write_mstatus(uint64_t val) const {
+        m_m.get_state().shadow.registers.mstatus = val;
+    }
+
+    uint64_t do_read_menvcfg() const {
+        return m_m.get_state().shadow.registers.menvcfg;
+    }
+
+    void do_write_menvcfg(uint64_t val) const {
+        m_m.get_state().shadow.registers.menvcfg = val;
+    }
+
+    uint64_t do_read_mtvec() const {
+        return m_m.get_state().shadow.registers.mtvec;
+    }
+
+    void do_write_mtvec(uint64_t val) const {
+        m_m.get_state().shadow.registers.mtvec = val;
+    }
+
+    uint64_t do_read_mscratch() const {
+        return m_m.get_state().shadow.registers.mscratch;
+    }
+
+    void do_write_mscratch(uint64_t val) const {
+        m_m.get_state().shadow.registers.mscratch = val;
+    }
+
+    uint64_t do_read_mepc() const {
+        return m_m.get_state().shadow.registers.mepc;
+    }
+
+    void do_write_mepc(uint64_t val) const {
+        m_m.get_state().shadow.registers.mepc = val;
+    }
+
+    uint64_t do_read_mcause() const {
+        return m_m.get_state().shadow.registers.mcause;
+    }
+
+    void do_write_mcause(uint64_t val) const {
+        m_m.get_state().shadow.registers.mcause = val;
+    }
+
+    uint64_t do_read_mtval() const {
+        return m_m.get_state().shadow.registers.mtval;
+    }
+
+    void do_write_mtval(uint64_t val) const {
+        m_m.get_state().shadow.registers.mtval = val;
+    }
+
+    uint64_t do_read_misa() const {
+        return m_m.get_state().shadow.registers.misa;
+    }
+
+    void do_write_misa(uint64_t val) const {
+        m_m.get_state().shadow.registers.misa = val;
+    }
+
+    uint64_t do_read_mie() const {
+        return m_m.get_state().shadow.registers.mie;
+    }
+
+    void do_write_mie(uint64_t val) const {
+        m_m.get_state().shadow.registers.mie = val;
+    }
+
+    uint64_t do_read_mip() const {
+        return m_m.get_state().shadow.registers.mip;
+    }
+
+    void do_write_mip(uint64_t val) const {
+        m_m.get_state().shadow.registers.mip = val;
+    }
+
+    uint64_t do_read_medeleg() const {
+        return m_m.get_state().shadow.registers.medeleg;
+    }
+
+    void do_write_medeleg(uint64_t val) const {
+        m_m.get_state().shadow.registers.medeleg = val;
+    }
+
+    uint64_t do_read_mideleg() const {
+        return m_m.get_state().shadow.registers.mideleg;
+    }
+
+    void do_write_mideleg(uint64_t val) const {
+        m_m.get_state().shadow.registers.mideleg = val;
+    }
+
+    uint64_t do_read_mcounteren() const {
+        return m_m.get_state().shadow.registers.mcounteren;
+    }
+
+    void do_write_mcounteren(uint64_t val) const {
+        m_m.get_state().shadow.registers.mcounteren = val;
+    }
+
+    uint64_t do_read_senvcfg() const {
+        return m_m.get_state().shadow.registers.senvcfg;
+    }
+
+    void do_write_senvcfg(uint64_t val) const {
+        m_m.get_state().shadow.registers.senvcfg = val;
+    }
+
+    uint64_t do_read_stvec() const {
+        return m_m.get_state().shadow.registers.stvec;
+    }
+
+    void do_write_stvec(uint64_t val) const {
+        m_m.get_state().shadow.registers.stvec = val;
+    }
+
+    uint64_t do_read_sscratch() const {
+        return m_m.get_state().shadow.registers.sscratch;
+    }
+
+    void do_write_sscratch(uint64_t val) const {
+        m_m.get_state().shadow.registers.sscratch = val;
+    }
+
+    uint64_t do_read_sepc() const {
+        return m_m.get_state().shadow.registers.sepc;
+    }
+
+    void do_write_sepc(uint64_t val) const {
+        m_m.get_state().shadow.registers.sepc = val;
+    }
+
+    uint64_t do_read_scause() const {
+        return m_m.get_state().shadow.registers.scause;
+    }
+
+    void do_write_scause(uint64_t val) const {
+        m_m.get_state().shadow.registers.scause = val;
+    }
+
+    uint64_t do_read_stval() const {
+        return m_m.get_state().shadow.registers.stval;
+    }
+
+    void do_write_stval(uint64_t val) const {
+        m_m.get_state().shadow.registers.stval = val;
+    }
+
+    uint64_t do_read_satp() const {
+        return m_m.get_state().shadow.registers.satp;
+    }
+
+    void do_write_satp(uint64_t val) const {
+        m_m.get_state().shadow.registers.satp = val;
+    }
+
+    uint64_t do_read_scounteren() const {
+        return m_m.get_state().shadow.registers.scounteren;
+    }
+
+    void do_write_scounteren(uint64_t val) const {
+        m_m.get_state().shadow.registers.scounteren = val;
+    }
+
+    uint64_t do_read_ilrsc() const {
+        return m_m.get_state().shadow.registers.ilrsc;
+    }
+
+    void do_write_ilrsc(uint64_t val) const {
+        m_m.get_state().shadow.registers.ilrsc = val;
+    }
+
+    uint64_t do_read_iprv() const {
+        return m_m.get_state().shadow.registers.iprv;
+    }
+
+    void do_write_iprv(uint64_t val) const {
+        m_m.get_state().shadow.registers.iprv = val;
+    }
+
+    uint64_t do_read_iflags_X() const {
+        return m_m.get_state().shadow.registers.iflags.X;
+    }
+
+    void do_write_iflags_X(uint64_t val) const {
+        m_m.get_state().shadow.registers.iflags.X = val;
+    }
+
+    uint64_t do_read_iflags_Y() const {
+        return m_m.get_state().shadow.registers.iflags.Y;
+    }
+
+    void do_write_iflags_Y(uint64_t val) const {
+        m_m.get_state().shadow.registers.iflags.Y = val;
+    }
+
+    uint64_t do_read_iflags_H() const {
+        return m_m.get_state().shadow.registers.iflags.H;
+    }
+
+    void do_write_iflags_H(uint64_t val) const {
+        m_m.get_state().shadow.registers.iflags.H = val;
+    }
+
+    uint64_t do_read_iunrep() const {
+        return m_m.get_state().shadow.registers.iunrep;
+    }
+
+    void do_write_iunrep(uint64_t val) const {
+        m_m.get_state().shadow.registers.iunrep = val;
+    }
+
+    uint64_t do_read_clint_mtimecmp() const {
+        return m_m.get_state().shadow.registers.clint.mtimecmp;
+    }
+
+    void do_write_clint_mtimecmp(uint64_t val) const {
+        m_m.get_state().shadow.registers.clint.mtimecmp = val;
+    }
+
+    uint64_t do_read_plic_girqpend() const {
+        return m_m.get_state().shadow.registers.plic.girqpend;
+    }
+
+    void do_write_plic_girqpend(uint64_t val) const {
+        m_m.get_state().shadow.registers.plic.girqpend = val;
+    }
+
+    uint64_t do_read_plic_girqsrvd() const {
+        return m_m.get_state().shadow.registers.plic.girqsrvd;
+    }
+
+    void do_write_plic_girqsrvd(uint64_t val) const {
+        m_m.get_state().shadow.registers.plic.girqsrvd = val;
+    }
+
+    uint64_t do_read_htif_fromhost() const {
+        return m_m.get_state().shadow.registers.htif.fromhost;
+    }
+
+    void do_write_htif_fromhost(uint64_t val) const {
+        m_m.get_state().shadow.registers.htif.fromhost = val;
+    }
+
+    uint64_t do_read_htif_tohost() const {
+        return m_m.get_state().shadow.registers.htif.tohost;
+    }
+
+    void do_write_htif_tohost(uint64_t val) const {
+        m_m.get_state().shadow.registers.htif.tohost = val;
+    }
+
+    uint64_t do_read_htif_ihalt() const {
+        return m_m.get_state().shadow.registers.htif.ihalt;
+    }
+
+    uint64_t do_read_htif_iconsole() const {
+        return m_m.get_state().shadow.registers.htif.iconsole;
+    }
+
+    uint64_t do_read_htif_iyield() const {
+        return m_m.get_state().shadow.registers.htif.iyield;
+    }
 
     // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
     bool do_read_memory(uint64_t paddr, const unsigned char *data, uint64_t length) const {
@@ -129,7 +448,7 @@ class collect_mcycle_hashes_state_access :
 
     template <typename T, typename A>
     void do_write_memory_word(host_addr haddr, uint64_t pma_index, T val) const {
-        mark_dirty_word(m_m.get_paddr(haddr, pma_index));
+        mark_dirty_word(haddr, pma_index);
         aliased_aligned_write<T, A>(haddr, val);
     }
 
@@ -152,9 +471,8 @@ class collect_mcycle_hashes_state_access :
     //??D This is still a bit too complicated for my taste
     template <TLB_set_index SET>
     void do_write_tlb(uint64_t slot_index, uint64_t vaddr_page, host_addr vh_offset, uint64_t pma_index) const {
+        // Marking only one slot field suffices because mark_dirty_word actually marks pages
         mark_dirty_word(shadow_tlb_get_abs_addr(SET, slot_index, shadow_tlb_what::vaddr_page));
-        mark_dirty_word(shadow_tlb_get_abs_addr(SET, slot_index, shadow_tlb_what::vp_offset));
-        mark_dirty_word(shadow_tlb_get_abs_addr(SET, slot_index, shadow_tlb_what::pma_index));
         m_m.write_tlb(SET, slot_index, vaddr_page, vh_offset, pma_index);
     }
 
diff --git a/src/hash-tree.h b/src/hash-tree.h
index 30bfab88d..4c9bed522 100644
--- a/src/hash-tree.h
+++ b/src/hash-tree.h
@@ -118,6 +118,7 @@ class hash_tree {
     using proof_type = hash_tree_proof;
 
     using dirty_words_type = ankerl::unordered_dense::set<uint64_t>;
+    using dirty_pages_type = ankerl::unordered_dense::set<uint64_t>;
     using nodes_type = std::vector<node_type>;
     using sibling_hashes_type = std::vector<machine_hash>;
 
diff --git a/src/machine-address-ranges.cpp b/src/machine-address-ranges.cpp
index 019e00520..8bb44bbd1 100644
--- a/src/machine-address-ranges.cpp
+++ b/src/machine-address-ranges.cpp
@@ -482,14 +482,4 @@ void machine_address_ranges::replace(const memory_range_config &config) {
     throw std::invalid_argument{"attempted replace of inexistent memory range"};
 }
 
-const address_range &machine_address_ranges::find(uint64_t paddr, uint64_t length) const noexcept {
-    static auto sentinel = make_empty_address_range("sentinel");
-    for (const auto &ar : m_all) {
-        if (ar->contains_absolute(paddr, length)) {
-            return *ar;
-        }
-    }
-    return sentinel;
-}
-
 } // namespace cartesi
diff --git a/src/machine-address-ranges.h b/src/machine-address-ranges.h
index 26408b3bc..b3220cddf 100644
--- a/src/machine-address-ranges.h
+++ b/src/machine-address-ranges.h
@@ -47,6 +47,7 @@ class machine_address_ranges {
     address_range_descriptions m_descrs;               ///< Address range descriptions for users
     int m_shadow_state_index;                          ///< Index of shadow state address range
     int m_shadow_uarch_state_index;                    ///< Index of shadow uarch state address range
+    address_range m_sentinel{make_empty_address_range("sentinel")};
 
 public:
     /// \brief Constructor
@@ -95,18 +96,24 @@ class machine_address_ranges {
     /// \brief Returns the address range corresponding to the ith PMA
     const address_range &read_pma(uint64_t index) const noexcept {
         if (index >= m_pmas.size()) [[unlikely]] {
-            static auto sentinel = make_empty_address_range("sentinel");
-            return sentinel;
+            return m_sentinel;
         }
         // NOLINTNEXTLINE(bugprone-narrowing-conversions)
-        return *m_all[static_cast<int>(m_pmas[static_cast<int>(index)])];
+        return *m_all[static_cast<size_t>(m_pmas[static_cast<size_t>(index)])];
     }
 
     /// \brief Returns const address range that covers a given physical memory region
     /// \param paddr Target physical address of start of region.
     /// \param length Length of region, in bytes.
     /// \returns Corresponding address range if found, or an empty sentinel otherwise.
-    const address_range &find(uint64_t paddr, uint64_t length) const noexcept;
+    const address_range &find(uint64_t paddr, uint64_t length) const noexcept {
+        for (const auto &ar : m_all) {
+            if (ar->contains_absolute(paddr, length)) {
+                return *ar;
+            }
+        }
+        return m_sentinel;
+    }
 
     /// \brief Returns address range that covers a given physical memory region
     /// \param paddr Target physical address of start of region.
diff --git a/src/machine.cpp b/src/machine.cpp
index cbcd64fbc..104fc7e26 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -15,6 +15,7 @@
 //
 
 #include "machine.h"
+#include "hash-tree-constants.h"
 #include "os-features.h"
 
 #include <algorithm>
@@ -1991,7 +1992,7 @@ void machine::collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_
         }
     }
     collect_mcycle_hashes_state_access::context context{};
-    context.dirty_words.reserve(std::clamp<uint64_t>(mcycle_period * 4, 256, 2048));
+    context.dirty_pages.reserve(std::clamp<uint64_t>(mcycle_period * 4, 16, 4096));
     result.hashes.reserve(mcycle_period);
     const collect_mcycle_hashes_state_access a(context, *this);
     os_silence_putchar(m_r.htif.no_console_putchar);
@@ -2004,10 +2005,15 @@ void machine::collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_
         mcycle_phase = 0;
         result.break_reason = interpret(a, mcycle_target);
         const auto mcycle_end = read_reg(reg::mcycle);
-        if (!m_ht.update_words(m_ars, context.dirty_words)) {
+        for (const uint64_t paddr_page : context.dirty_pages) {
+            // NOLINTNEXTLINE(cppcoreguidelines-pro-type-const-cast)
+            auto &ar = const_cast<address_range &>(find_address_range(paddr_page, HASH_TREE_PAGE_SIZE));
+            ar.get_dirty_page_tree().mark_dirty_pages_and_up(paddr_page - ar.get_start(), HASH_TREE_PAGE_SIZE);
+        }
+        if (!m_ht.update(m_ars)) {
             throw std::runtime_error{"update hash tree failed"};
         }
-        context.dirty_words.clear();
+        context.dirty_pages.clear();
         // If the machine stopped before we asked, we are done
         if (mcycle_end != mcycle_target) {
             break;
@@ -2036,8 +2042,9 @@ void machine::collect_uarch_cycle_root_hashes(uint64_t mcycle_count, uarch_cycle
         throw std::runtime_error{"microarchitecture is not reset"};
     }
     collect_uarch_cycle_hashes_state_access::context context{};
-    context.dirty_words.reserve(std::clamp<uint64_t>(mcycle_count * 4, 256, 2048));
+    context.dirty_words.reserve(8);
     result.hashes.reserve(mcycle_count * 512);
+    result.reset_indices.reserve(mcycle_count);
     const collect_uarch_cycle_hashes_state_access a(context, *this);
     os_silence_putchar(m_r.htif.no_console_putchar);
     auto mcycle_start = read_reg(reg::mcycle);
diff --git a/src/machine.h b/src/machine.h
index a46638aa2..58ce2bf95 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -79,10 +79,9 @@ class machine final {
     /// \brief Returns offset that converts between machine host addresses and target physical addresses
     /// \param pma_index Index of the memory PMA for the desired offset
     host_addr get_hp_offset(uint64_t pma_index) const {
-        using namespace std::string_literals;
-        const auto &ar = read_pma(pma_index);
+        const auto &ar = m_ars.read_pma(pma_index);
         if (!ar.is_memory()) [[unlikely]] {
-            throw std::domain_error{"PMA index is not of memory range ("s + ar.get_description() + ")"s};
+            throw std::domain_error{"attempt to get host to physical offset of PMA that is not a memory range"};
         }
         auto haddr = cast_ptr_to_host_addr(ar.get_host_memory());
         auto paddr = ar.get_start();

From 357ccf604641cc84ba3e76d6d7a35440c4c19ddb Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Thu, 28 Aug 2025 09:24:34 -0300
Subject: [PATCH 65/82] perf: optimize hash tree memory allocations

---
 src/hash-tree.cpp | 27 ++++++++++++++++-----------
 src/hash-tree.h   | 11 ++++++-----
 2 files changed, 22 insertions(+), 16 deletions(-)

diff --git a/src/hash-tree.cpp b/src/hash-tree.cpp
index 554dcd242..b64b3a2e7 100644
--- a/src/hash-tree.cpp
+++ b/src/hash-tree.cpp
@@ -319,7 +319,7 @@ hash_tree::~hash_tree() {
 bool hash_tree::update_dirty_pages(address_ranges ars, changed_address_ranges &changed_ars) {
     SCOPED_SIGNPOST(m_log, m_spid_update_page_hashes, "hash-tree: update page hashes", "");
     bool update_failed = false;
-    dirty_pages batch;
+    dirty_pages batch{&m_memory_pool};
     batch.reserve(m_page_cache.capacity());
     // Go sequentially over dirty pages of all address ranges, collecting borrowed cache entries for them.
     // The cache eventually runs out of entries to lend.
@@ -407,7 +407,7 @@ bool hash_tree::update_dense_trees(address_ranges ars, const changed_address_ran
     }
     // We can batch more if we have more concurrency, however we need to limit to not run out of memory.
     const size_t batch_size = std::min(m_concurrency << 10, 16384);
-    dense_node_entries batch;
+    dense_node_entries batch{&m_memory_pool};
     batch.reserve(batch_size);
     // Get maximum log2_size of all address ranges
     const auto max_level_count = std::ranges::max(
@@ -450,9 +450,10 @@ bool hash_tree::update_sparse_tree(address_ranges ars, const changed_address_ran
         return true;
     }
     using E = std::pair<int, int>;
-    std::vector<E> changed_backing;
+    std::pmr::vector<E> changed_backing{&m_memory_pool};
     changed_backing.reserve(changed_count);
-    std::priority_queue<E, std::vector<E>, std::greater<>> changed(std::greater<>{}, std::move(changed_backing));
+    std::priority_queue<E, decltype(changed_backing), std::greater<>> changed(std::greater<>{},
+        std::move(changed_backing));
     for (auto ar_index : changed_ars) {
         auto ar_node_index = get_ar_sparse_node_index(ar_index);
         auto &ar_node = m_sparse_nodes[ar_node_index];
@@ -630,7 +631,7 @@ bool hash_tree::verify(address_ranges ars) const {
 
 bool hash_tree::update(address_ranges ars) {
     SCOPED_SIGNPOST(m_log, m_spid_update, "hash-tree: update", "");
-    changed_address_ranges changed_ars;
+    changed_address_ranges changed_ars{&m_memory_pool};
     changed_ars.reserve(ars.size());
     auto update_succeeded = update_dirty_pages(ars, changed_ars) && update_dense_trees(ars, changed_ars) &&
         update_sparse_tree(ars, changed_ars);
@@ -642,7 +643,7 @@ bool hash_tree::update(address_ranges ars) {
     return update_succeeded;
 }
 
-bool hash_tree::update_words(address_ranges ars, dirty_words_type dirty_words) {
+bool hash_tree::update_words(address_ranges ars, const dirty_words_type &dirty_words) {
     constexpr auto page_mask = ~(HASH_TREE_PAGE_SIZE - 1);
     // Dirty_words contains an unordered set of the address of all words that became dirty since last update
     // We copy these to a sorted vector "words"
@@ -652,11 +653,18 @@ bool hash_tree::update_words(address_ranges ars, dirty_words_type dirty_words) {
     if (dirty_words.empty()) {
         return true;
     }
-    std::vector<uint64_t> words;
+    dense_node_entries curr_dense_node{&m_memory_pool};
+    dense_node_entries next_dense_node{&m_memory_pool};
+    changed_address_ranges changed_ars{&m_memory_pool};
+    std::pmr::vector<uint64_t> words{&m_memory_pool};
+    std::pmr::vector<uint64_t> page_starts{&m_memory_pool};
+    curr_dense_node.reserve(4);
+    next_dense_node.reserve(4);
+    changed_ars.reserve(2);
     words.reserve(dirty_words.size());
+    page_starts.reserve(words.size());
     std::ranges::copy(dirty_words, std::back_inserter(words));
     std::ranges::sort(words);
-    std::vector<uint64_t> page_starts;
     uint64_t last_paddr_page = -1;
     //??D change to std::views::enumerate on C++23
     for (uint64_t start = 0; auto word : words) {
@@ -673,9 +681,6 @@ bool hash_tree::update_words(address_ranges ars, dirty_words_type dirty_words) {
     uint64_t update_failures{0}; // NOLINT(misc-const-correctness)
     int ar_index = 0;
     int max_level_count = 0;
-    dense_node_entries curr_dense_node;
-    dense_node_entries next_dense_node;
-    changed_address_ranges changed_ars;
     for (unsigned i = 0; i < page_starts.size() - 1; ++i) {
         auto begin = page_starts[i];
         auto end = page_starts[i + 1];
diff --git a/src/hash-tree.h b/src/hash-tree.h
index 4c9bed522..260f94727 100644
--- a/src/hash-tree.h
+++ b/src/hash-tree.h
@@ -18,6 +18,7 @@
 #define HASH_TREE_H
 
 #include <iosfwd>
+#include <memory_resource>
 #include <vector>
 
 #include "unordered_dense.h"
@@ -45,7 +46,7 @@ class hash_tree {
         bool changed;                    ///< Whether the update operation really changed the page
     };
 
-    using dirty_pages = std::vector<dirty_page>;
+    using dirty_pages = std::pmr::vector<dirty_page>;
     struct dense_node_entry {
         // NOLINTNEXTLINE(cppcoreguidelines-avoid-const-or-ref-data-members)
         i_dense_hash_tree &dht;
@@ -54,7 +55,7 @@ class hash_tree {
             return &dht == &other.dht && offset == other.offset;
         }
     };
-    using dense_node_entries = std::vector<dense_node_entry>;
+    using dense_node_entries = std::pmr::vector<dense_node_entry>;
     using pristine_hashes = std::array<machine_hash, HASH_TREE_LOG2_ROOT_SIZE + 1>;
 
     using index_type = int64_t;
@@ -134,7 +135,7 @@ class hash_tree {
 
     bool update(address_ranges ars);
 
-    bool update_words(address_ranges ars, dirty_words_type dirty_words);
+    bool update_words(address_ranges ars, const dirty_words_type &dirty_words);
 
     bool update_page(address_ranges ars, uint64_t paddr_page);
 
@@ -149,7 +150,7 @@ class hash_tree {
     hash_tree_stats get_stats(bool clear = false) noexcept;
 
 private:
-    using changed_address_ranges = std::vector<int>;
+    using changed_address_ranges = std::pmr::vector<int>;
 
     void get_pristine_proof(int curr_log2_size, proof_type &proof) const;
     void get_dense_proof(address_range &ar, int ar_log2_size, uint64_t address, proof_type &proof);
@@ -194,7 +195,7 @@ class hash_tree {
     const pristine_hashes m_pristine_hashes;
     int m_concurrency;
     hash_function_type m_hash_function;
-
+    std::pmr::unsynchronized_pool_resource m_memory_pool;
     uint64_t m_sparse_node_hashes{0};
     std::array<uint64_t, HASH_TREE_LOG2_ROOT_SIZE> m_dense_node_hashes{};
 };

From 9eca13c2fd5422c84d0afbc0364092e8324c0d87 Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Thu, 28 Aug 2025 11:56:07 -0300
Subject: [PATCH 66/82] fix: issues in collect hashes APIs and add more tests

---
 src/clua-i-machine.cpp            |   1 +
 src/machine.cpp                   | 114 +++++++---
 tests/lua/spec-collect-hashes.lua | 337 ++++++++++++++++++++++++++----
 3 files changed, 386 insertions(+), 66 deletions(-)

diff --git a/src/clua-i-machine.cpp b/src/clua-i-machine.cpp
index 41bcab392..42c7b9250 100644
--- a/src/clua-i-machine.cpp
+++ b/src/clua-i-machine.cpp
@@ -514,6 +514,7 @@ static const nlohmann::json &clua_get_machine_schema_dict(lua_State *L) try {
             {
                 {"hashes", "Base64Array"},
                 {"reset_indices", "ArrayArrayIndex"},
+                {"break_reason", "InterpreterBreakReason"},
             }},
     };
     return machine_schema_dict;
diff --git a/src/machine.cpp b/src/machine.cpp
index 104fc7e26..2be1680c3 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -1967,13 +1967,17 @@ void machine::write_counter(uint64_t val, const char *name, const char *domain)
 
 void machine::collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_period, uint64_t period_count,
     mcycle_root_hashes &result) {
-    result.hashes.clear();
+    mcycle_root_hashes next_result;
+    std::swap(next_result, result);
     if (mcycle_period == 0) {
         throw std::runtime_error{"mcycle_period cannot be 0"};
     }
     if (mcycle_phase >= mcycle_period) {
         throw std::runtime_error{"mcycle_phase must be in {0, ..., mcycle_period-1}"};
     }
+    if (mcycle_phase > read_reg(reg::mcycle)) {
+        throw std::runtime_error{"mcycle_phase cannot be greater than machine mcycle"};
+    }
     if (read_reg(reg::iunrep) != 0) {
         throw std::runtime_error{"cannot collect hashes from unreproducible machines"};
     }
@@ -1991,20 +1995,32 @@ void machine::collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_
             throw std::runtime_error{"microarchitecture is not reset"};
         }
     }
+    next_result.hashes.clear();
+    next_result.mcycle_phase = mcycle_phase;
+    // Check halted and yielded break reasons first to behave with same priority as the interpreter
+    if (read_reg(reg::iflags_H) != 0) {
+        next_result.break_reason = interpreter_break_reason::halted;
+        std::swap(next_result, result);
+        return;
+    }
+    if (read_reg(reg::iflags_Y) != 0) {
+        next_result.break_reason = interpreter_break_reason::yielded_manually;
+        std::swap(next_result, result);
+        return;
+    }
+    next_result.hashes.reserve(mcycle_period);
+    next_result.break_reason = interpreter_break_reason::reached_target_mcycle;
     collect_mcycle_hashes_state_access::context context{};
     context.dirty_pages.reserve(std::clamp<uint64_t>(mcycle_period * 4, 16, 4096));
-    result.hashes.reserve(mcycle_period);
     const collect_mcycle_hashes_state_access a(context, *this);
     os_silence_putchar(m_r.htif.no_console_putchar);
-    auto mcycle_start = read_reg(reg::mcycle);
+    auto mcycle_start = read_reg(reg::mcycle) - mcycle_phase;
     for (uint64_t period = 0; period < period_count; ++period) {
         uint64_t mcycle_target{};
-        if (__builtin_add_overflow(mcycle_start, mcycle_period - mcycle_phase, &mcycle_target)) {
+        if (__builtin_add_overflow(mcycle_start, mcycle_period, &mcycle_target)) {
             mcycle_target = UINT64_MAX;
         }
-        mcycle_phase = 0;
-        result.break_reason = interpret(a, mcycle_target);
-        const auto mcycle_end = read_reg(reg::mcycle);
+        next_result.break_reason = interpret(a, mcycle_target);
         for (const uint64_t paddr_page : context.dirty_pages) {
             // NOLINTNEXTLINE(cppcoreguidelines-pro-type-const-cast)
             auto &ar = const_cast<address_range &>(find_address_range(paddr_page, HASH_TREE_PAGE_SIZE));
@@ -2014,25 +2030,36 @@ void machine::collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_
             throw std::runtime_error{"update hash tree failed"};
         }
         context.dirty_pages.clear();
+        const auto mcycle_end = read_reg(reg::mcycle);
         // If the machine stopped before we asked, we are done
-        if (mcycle_end != mcycle_target) {
+        if (mcycle_end != mcycle_target || mcycle_target == UINT64_MAX) {
             break;
         }
-        result.hashes.emplace_back(m_ht.get_root_hash());
+        next_result.hashes.emplace_back(m_ht.get_root_hash());
         mcycle_start = mcycle_end;
+        // If the machine stopped before we asked, we are done
+        if (next_result.break_reason != interpreter_break_reason::reached_target_mcycle) {
+            break;
+        }
     }
-    result.mcycle_phase = read_reg(reg::mcycle) - mcycle_start;
+    next_result.mcycle_phase = read_reg(reg::mcycle) - mcycle_start;
+    // Commit new result
+    std::swap(next_result, result);
 }
 
 void machine::collect_uarch_cycle_root_hashes(uint64_t mcycle_count, uarch_cycle_root_hashes &result) {
-    result.hashes.clear();
-    result.reset_indices.clear();
+    uarch_cycle_root_hashes next_result;
+    std::swap(next_result, result);
     if (read_reg(reg::iunrep) != 0) {
         throw std::runtime_error{"cannot collect hashes from unreproducible machines"};
     }
     if (m_r.soft_yield) {
         throw std::runtime_error{"cannot collect hashes when soft yield is enabled"};
     }
+    if (m_c.hash_tree.hash_function != hash_function_type::keccak256) {
+        throw std::runtime_error{
+            "microarchitecture can only be used with hash tree configured with Keccak-256 hash function"};
+    }
     if (!update_hash_tree()) {
         throw std::runtime_error{"update hash tree failed"};
     }
@@ -2041,18 +2068,48 @@ void machine::collect_uarch_cycle_root_hashes(uint64_t mcycle_count, uarch_cycle
     if (current_uarch_state_hash != get_uarch_pristine_state_hash()) {
         throw std::runtime_error{"microarchitecture is not reset"};
     }
+    next_result.hashes.clear();
+    next_result.reset_indices.clear();
+    // Check halted and yielded break reasons first to behave with same priority as the interpreter
+    if (read_reg(reg::iflags_H) != 0) {
+        next_result.break_reason = interpreter_break_reason::halted;
+        std::swap(next_result, result);
+        return;
+    }
+    if (read_reg(reg::iflags_Y) != 0) {
+        next_result.break_reason = interpreter_break_reason::yielded_manually;
+        std::swap(next_result, result);
+        return;
+    }
+    next_result.hashes.reserve(mcycle_count * 512);
+    next_result.reset_indices.reserve(mcycle_count);
+    next_result.break_reason = interpreter_break_reason::reached_target_mcycle;
     collect_uarch_cycle_hashes_state_access::context context{};
     context.dirty_words.reserve(8);
-    result.hashes.reserve(mcycle_count * 512);
-    result.reset_indices.reserve(mcycle_count);
     const collect_uarch_cycle_hashes_state_access a(context, *this);
     os_silence_putchar(m_r.htif.no_console_putchar);
-    auto mcycle_start = read_reg(reg::mcycle);
     for (uint64_t mcycles = 0; mcycles < mcycle_count; ++mcycles) {
+        // If the machine stopped before we asked, we are done
+        if (read_reg(reg::iflags_H) != 0) {
+            next_result.break_reason = interpreter_break_reason::halted;
+            break;
+        }
+        if (read_reg(reg::iflags_Y) != 0) {
+            next_result.break_reason = interpreter_break_reason::yielded_manually;
+            break;
+        }
+        if (read_reg(reg::iflags_X) != 0 && mcycles > 0) {
+            next_result.break_reason = interpreter_break_reason::yielded_automatically;
+            break;
+        }
+        uint64_t mcycle_target{};
+        if (__builtin_add_overflow(read_reg(reg::mcycle), 1, &mcycle_target)) {
+            break;
+        }
         auto uarch_cycle_start = read_reg(reg::uarch_cycle);
         // Add one hash after each uarch cycle
         for (;;) {
-            uint64_t uarch_cycle_target = 0;
+            uint64_t uarch_cycle_target{};
             if (__builtin_add_overflow(uarch_cycle_start, 1, &uarch_cycle_target)) {
                 break;
             }
@@ -2065,29 +2122,24 @@ void machine::collect_uarch_cycle_root_hashes(uint64_t mcycle_count, uarch_cycle
             if (uarch_cycle_end != uarch_cycle_target) {
                 break;
             }
-            result.hashes.emplace_back(m_ht.get_root_hash());
+            next_result.hashes.emplace_back(m_ht.get_root_hash());
             uarch_cycle_start = uarch_cycle_end;
         }
-        // Add one hash after the uarch reset, and the index where it happened
         //??D maybe optimize this?
         reset_uarch();
         if (!update_hash_tree()) {
             throw std::runtime_error{"update hash tree failed"};
         }
-        result.reset_indices.emplace_back(result.hashes.size());
-        result.hashes.emplace_back(m_ht.get_root_hash());
-    }
-    // Now check why we stopped
-    auto mcycle_end = read_reg(reg::mcycle);
-    if (mcycle_end - mcycle_start == mcycle_count) {
-        result.break_reason = interpreter_break_reason::reached_target_mcycle;
-    } else if (read_reg(reg::iflags_H) != 0) {
-        result.break_reason = interpreter_break_reason::halted;
-    } else if (read_reg(reg::iflags_Y) != 0) {
-        result.break_reason = interpreter_break_reason::yielded_manually;
-    } else if (read_reg(reg::iflags_X) != 0) {
-        result.break_reason = interpreter_break_reason::yielded_automatically;
+        const auto mcycle_end = read_reg(reg::mcycle);
+        if (mcycle_end != mcycle_target) {
+            throw std::runtime_error{"machine did not reach the expected target mcycle"};
+        }
+        // Add one hash after the uarch reset, and the index where it happened
+        next_result.reset_indices.emplace_back(next_result.hashes.size());
+        next_result.hashes.emplace_back(m_ht.get_root_hash());
     }
+    // Commit new result
+    std::swap(next_result, result);
 }
 
 } // namespace cartesi
diff --git a/tests/lua/spec-collect-hashes.lua b/tests/lua/spec-collect-hashes.lua
index 94520fe53..f5f3be63c 100644
--- a/tests/lua/spec-collect-hashes.lua
+++ b/tests/lua/spec-collect-hashes.lua
@@ -8,11 +8,9 @@ local cartesi = require("cartesi")
 local util = require("cartesi.tests.util")
 
 local function expect_consistent_root_hash(machine)
-    expect.truthy(machine:verify_hash_tree())
     local root_hash = machine:get_root_hash()
-    local external_root_hash = util.calculate_emulator_hash(machine)
     local node_hash = machine:get_node_hash(0, cartesi.TREE_LOG2_ROOT_SIZE)
-    expect.truthy(machine:verify_hash_tree())
+    local external_root_hash = util.calculate_emulator_hash(machine)
     expect.equal(root_hash, node_hash)
     expect.equal(external_root_hash, root_hash)
 end
@@ -20,18 +18,22 @@ end
 local function expect_mcycle_root_hashes(machine, mcycle_phase, mcycle_period, period_count)
     local break_reason
     local hashes = {}
-    local mcycle_start = machine:read_reg("mcycle") - mcycle_phase
-    local mcycle_max = mcycle_start + (period_count * mcycle_period)
-    for mcycle = mcycle_start + mcycle_period, mcycle_max, mcycle_period do
-        break_reason = machine:run(mcycle)
+    local mcycle_start = machine:read_reg("mcycle") + mcycle_period - mcycle_phase
+    local mcycle_end = machine:read_reg("mcycle") - mcycle_phase + (period_count * mcycle_period)
+    for mcycle_target = mcycle_start, mcycle_end, mcycle_period do
+        break_reason = machine:run(mcycle_target)
         expect_consistent_root_hash(machine)
-        if break_reason ~= cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE then
+        if machine:read_reg("mcycle") ~= mcycle_target then
+            mcycle_phase = mcycle_period - (mcycle_target - machine:read_reg("mcycle"))
             break
         end
+        mcycle_phase = 0
         table.insert(hashes, machine:get_root_hash())
+        if break_reason ~= cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE then
+            break
+        end
     end
-    local mcycle = machine:read_reg("mcycle")
-    mcycle_phase = mcycle % mcycle_period
+    assert(break_reason, "expect_mcycle_root_hashes failed")
     return {
         hashes = hashes,
         break_reason = break_reason,
@@ -42,19 +44,20 @@ end
 local function expect_uarch_cycle_root_hashes(machine, mcycle_count)
     local hashes = {}
     local reset_indices = {}
-    local break_reason = "reached_target_mcycle"
-    local initial_mcycle = machine:read_reg("mcycle")
-    for mcycle = initial_mcycle + 1, initial_mcycle + mcycle_count do
+    local break_reason
+    local mcycle_start = machine:read_reg("mcycle")
+    local mcycle_end = mcycle_start + mcycle_count
+    for mcycle = mcycle_start + 1, mcycle_end do
         if machine:read_reg("iflags_H") ~= 0 then
-            break_reason = "halted"
+            break_reason = cartesi.BREAK_REASON_HALTED
             break
         end
-        if machine:read_reg("iflags_X") ~= 0 then
-            break_reason = "yielded_automatically"
+        if machine:read_reg("iflags_Y") ~= 0 then
+            break_reason = cartesi.BREAK_REASON_YIELDED_MANUALLY
             break
         end
-        if machine:read_reg("iflags_Y") ~= 0 then
-            break_reason = "yielded_manually"
+        if mcycle ~= mcycle_start + 1 and machine:read_reg("iflags_X") ~= 0 then
+            break_reason = cartesi.BREAK_REASON_YIELDED_AUTOMATICALLY
             break
         end
         expect.equal(machine:read_reg("uarch_cycle"), 0)
@@ -74,7 +77,12 @@ local function expect_uarch_cycle_root_hashes(machine, mcycle_count)
         expect.equal(machine:read_reg("mcycle"), mcycle)
         table.insert(hashes, machine:get_root_hash())
         table.insert(reset_indices, #hashes)
+        if mcycle == mcycle_end then
+            break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE
+            break
+        end
     end
+    assert(break_reason, "expect_uarch_cycle_root_hashes failed")
     return {
         hashes = hashes,
         reset_indices = reset_indices,
@@ -83,9 +91,124 @@ local function expect_uarch_cycle_root_hashes(machine, mcycle_count)
 end
 
 describe("collect hashes", function()
+    it("should fail when collecting with invalid arguments", function()
+        local machine <close> = cartesi.machine({ ram = { length = 4096 } })
+        expect.fail(function()
+            machine:collect_mcycle_root_hashes(32, 32, 1)
+        end, "mcycle_phase must be in")
+        expect.fail(function()
+            machine:collect_mcycle_root_hashes(0, 0, 1)
+        end, "mcycle_period cannot be 0")
+        expect.fail(function()
+            machine:collect_mcycle_root_hashes(1, 32, 1)
+        end, "mcycle_phase cannot be greater than machine mcycle")
+    end)
+
+    it("should fail when collecting from unsupported machines", function()
+        local unrep_machine <close> =
+            cartesi.machine({ ram = { length = 4096 }, processor = { registers = { iunrep = 1 } } })
+        local soft_machine <close> = cartesi.machine({ ram = { length = 4096 } }, { soft_yield = true })
+        expect.fail(function()
+            unrep_machine:collect_mcycle_root_hashes(0, 32, 1)
+        end, "cannot collect hashes from unreproducible machines")
+        expect.fail(function()
+            unrep_machine:collect_uarch_cycle_root_hashes(32)
+        end, "cannot collect hashes from unreproducible machines")
+        expect.fail(function()
+            soft_machine:collect_mcycle_root_hashes(0, 32, 1)
+        end, "cannot collect hashes when soft yield is enabled")
+        expect.fail(function()
+            soft_machine:collect_uarch_cycle_root_hashes(32)
+        end, "cannot collect hashes when soft yield is enabled")
+    end)
+
+    it("should succeed when collecting 0 periods", function()
+        local machine <close> = cartesi.machine({ ram = { length = 4096 } })
+        machine:run(1)
+        expect.equal(machine:collect_mcycle_root_hashes(1, 32, 0), {
+            hashes = {},
+            break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE,
+            mcycle_phase = 1,
+        })
+        expect.equal(machine:collect_uarch_cycle_root_hashes(0), {
+            hashes = {},
+            reset_indices = {},
+            break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE,
+        })
+    end)
+
+    it("should succeed when collecting from halted machines", function()
+        local machine <close> = cartesi.machine({ ram = { length = 4096 } })
+        machine:write_reg("iflags_H", 1)
+        expect.equal(machine:collect_mcycle_root_hashes(0, 32, 1), {
+            hashes = {},
+            break_reason = cartesi.BREAK_REASON_HALTED,
+            mcycle_phase = 0,
+        })
+        expect.equal(machine:read_reg("mcycle"), 0)
+        expect.equal(machine:collect_uarch_cycle_root_hashes(32), {
+            hashes = {},
+            reset_indices = {},
+            break_reason = cartesi.BREAK_REASON_HALTED,
+        })
+        expect.equal(machine:read_reg("mcycle"), 0)
+    end)
+
+    it("should succeed when collecting from yielded machines", function()
+        local machine <close> = cartesi.machine({ ram = { length = 4096 } })
+        machine:write_reg("iflags_Y", 1)
+        expect.equal(machine:collect_mcycle_root_hashes(0, 32, 1), {
+            hashes = {},
+            break_reason = cartesi.BREAK_REASON_YIELDED_MANUALLY,
+            mcycle_phase = 0,
+        })
+        expect.equal(machine:read_reg("mcycle"), 0)
+        expect.equal(machine:collect_uarch_cycle_root_hashes(32), {
+            hashes = {},
+            reset_indices = {},
+            break_reason = cartesi.BREAK_REASON_YIELDED_MANUALLY,
+        })
+        expect.equal(machine:read_reg("mcycle"), 0)
+    end)
+
+    it("should succeed when collecting mcycles during mcycle overflow", function()
+        local machine <close> = cartesi.machine({ ram = { length = 4096 } })
+        local MAX_MCYCLE <const> = -1
+        machine:write_reg("mcycle", MAX_MCYCLE - 1)
+        expect.equal(machine:collect_mcycle_root_hashes(machine:read_reg("mcycle") % 32, 32, 1), {
+            hashes = {},
+            break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE,
+            mcycle_phase = 31,
+        })
+        expect.equal(machine:read_reg("mcycle"), MAX_MCYCLE)
+        expect.equal(machine:collect_mcycle_root_hashes(machine:read_reg("mcycle") % 32, 32, 1), {
+            hashes = {},
+            break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE,
+            mcycle_phase = 31,
+        })
+        expect.equal(machine:read_reg("mcycle"), MAX_MCYCLE)
+    end)
+
+    it("should succeed when collecting uarch cycles during mcycle overflows", function()
+        local machine <close> = cartesi.machine({ ram = { length = 4096 } })
+        local MAX_MCYCLE <const> = -1
+        machine:write_reg("mcycle", MAX_MCYCLE - 1)
+        expect.equal(
+            machine:collect_uarch_cycle_root_hashes(machine:read_reg("mcycle") % 32, 32, 1).break_reason,
+            cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE
+        )
+        expect.equal(machine:read_reg("mcycle"), MAX_MCYCLE)
+        expect.equal(machine:collect_uarch_cycle_root_hashes(machine:read_reg("mcycle") % 32, 32, 1), {
+            hashes = {},
+            reset_indices = {},
+            break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE,
+        })
+        expect.equal(machine:read_reg("mcycle"), MAX_MCYCLE)
+    end)
+
     for _, hash_function in pairs({ "sha256", "keccak256" }) do
         describe(hash_function, function()
-            local test_machine_config = {
+            local big_machine_config = {
                 ram = {
                     length = 8191 * 4096, -- non power of 2 on purpose to exercise address range boundaries
                     backing_store = {
@@ -103,18 +226,61 @@ describe("collect hashes", function()
                     hash_function = hash_function,
                 },
             }
+            local empty_machine_config = {
+                ram = { length = 4096 },
+                hash_tree = {
+                    hash_function = hash_function,
+                },
+            }
+            local yield_machine_config = {
+                ram = {
+                    length = 8191 * 4096, -- non power of 2 on purpose to exercise address range boundaries
+                    backing_store = {
+                        data_filename = util.tests_path .. "htif_yield.bin",
+                    },
+                },
+                hash_tree = {
+                    hash_function = hash_function,
+                },
+            }
 
-            local test_last_mcycle
-            local test_last_root_hash
+            local big_last_mcycle
+            local big_last_root_hash
+            local yield_last_mcycle = 500
+            local yield_last_root_hash
+            local yield_sparse_hashes = {}
+
+            if hash_function == "keccak256" then
+                it("should fail when microarchitecture is not reset", function()
+                    local machine <close> = cartesi.machine(empty_machine_config)
+                    machine:run_uarch(1)
+                    expect.fail(function()
+                        machine:collect_mcycle_root_hashes(0, 32, 1)
+                    end, "microarchitecture is not reset")
+                    expect.fail(function()
+                        machine:collect_uarch_cycle_root_hashes(1)
+                    end, "microarchitecture is not reset")
+                end)
+            else
+                it("should fail when collecting uarch cycles", function()
+                    local machine <close> = cartesi.machine(empty_machine_config)
+                    expect.fail(function()
+                        machine:collect_uarch_cycle_root_hashes(1)
+                    end, "microarchitecture can only be used with hash tree")
+                end)
+            end
 
             it("should match sparse periodic root hashes", function()
-                local machine <close> = cartesi.machine(test_machine_config)
-                local collect_machine <close> = cartesi.machine(test_machine_config)
-                expect_consistent_root_hash(machine)
-                expect.equal(machine:get_root_hash(), collect_machine:get_root_hash())
-                local mcycle_phase = 0
+                local mcycle_start = 1
                 local mcycle_period = 8 * 1024 * 1024
                 local period_count = 16
+                local machine <close> = cartesi.machine(big_machine_config)
+                local collect_machine <close> = cartesi.machine(big_machine_config)
+                machine:run(mcycle_start)
+                collect_machine:run(mcycle_start)
+                expect_consistent_root_hash(machine)
+                expect.equal(machine:get_root_hash(), collect_machine:get_root_hash())
+                local mcycle_phase = machine:read_reg("mcycle") % mcycle_period
                 local collected = collect_machine:collect_mcycle_root_hashes(mcycle_phase, mcycle_period, period_count)
                 local expected_collected = expect_mcycle_root_hashes(machine, mcycle_phase, mcycle_period, period_count)
                 local halt_exit_code = machine:read_reg("htif_tohost_data") >> 1
@@ -122,31 +288,132 @@ describe("collect hashes", function()
                 expect.equal(collect_machine:get_root_hash(), machine:get_root_hash())
                 expect.equal(collected.break_reason, cartesi.BREAK_REASON_HALTED)
                 expect.equal(halt_exit_code, 255)
-                test_last_mcycle = machine:read_reg("mcycle")
-                test_last_root_hash = machine:get_root_hash()
+                big_last_mcycle = machine:read_reg("mcycle")
+                big_last_root_hash = machine:get_root_hash()
+            end)
+
+            it("should match sparse periodic root hashes while yielding", function()
+                -- use prime numbers on purpose to test corner cases
+                local mcycle_start = 7
+                local mcycle_phase = 3
+                local mcycle_period = 21
+                local period_count = yield_last_mcycle // mcycle_period
+                local machine <close> = cartesi.machine(yield_machine_config)
+                local collect_machine <close> = cartesi.machine(yield_machine_config)
+                expect.equal(machine:run(mcycle_start), cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE)
+                expect.equal(machine:read_reg("mcycle"), mcycle_start)
+                collect_machine:run(mcycle_start)
+                expect_consistent_root_hash(machine)
+                expect.equal(machine:get_root_hash(), collect_machine:get_root_hash())
+                local count_manual_yields = 0
+                local count_automatic_yields = 0
+                local halt_exit_code
+                for _ = 1, period_count * 2 do
+                    local collected =
+                        collect_machine:collect_mcycle_root_hashes(mcycle_phase, mcycle_period, period_count)
+                    local expected_collected =
+                        expect_mcycle_root_hashes(machine, mcycle_phase, mcycle_period, period_count)
+                    expect.equal(collect_machine:read_reg("mcycle"), machine:read_reg("mcycle"))
+                    expect.equal(collected, expected_collected)
+                    expect.equal(collect_machine:get_root_hash(), machine:get_root_hash())
+                    mcycle_phase = collected.mcycle_phase
+                    for _, hash in ipairs(collected.hashes) do
+                        table.insert(yield_sparse_hashes, hash)
+                    end
+                    if collected.break_reason == cartesi.BREAK_REASON_YIELDED_MANUALLY then
+                        collect_machine:write_reg("iflags_Y", 0)
+                        machine:write_reg("iflags_Y", 0)
+                        count_manual_yields = count_manual_yields + 1
+                    elseif collected.break_reason == cartesi.BREAK_REASON_YIELDED_AUTOMATICALLY then
+                        count_automatic_yields = count_automatic_yields + 1
+                    elseif collected.break_reason == cartesi.BREAK_REASON_HALTED then
+                        halt_exit_code = machine:read_reg("htif_tohost_data") >> 1
+                        break
+                    else
+                        error("unexpected break reason")
+                    end
+                end
+                expect.equal(machine:read_reg("mcycle"), yield_last_mcycle)
+                expect.equal(#yield_sparse_hashes, period_count)
+                expect.equal(count_manual_yields, 8)
+                expect.equal(count_automatic_yields, 7)
+                expect.equal(halt_exit_code, 42)
+                yield_last_root_hash = machine:get_root_hash()
             end)
 
             if hash_function == "keccak256" then
                 it("should match dense uarch root hashes", function()
-                    expect.truthy(test_last_mcycle ~= nil and test_last_root_hash ~= nil)
-                    local machine <close> = cartesi.machine(test_machine_config)
-                    local collect_machine <close> = cartesi.machine(test_machine_config)
+                    expect.truthy(big_last_mcycle ~= nil and big_last_root_hash ~= nil)
+                    local machine <close> = cartesi.machine(big_machine_config)
+                    local collect_machine <close> = cartesi.machine(big_machine_config)
                     local mcycle_count = 2
                     expect.equal(
-                        machine:run(test_last_mcycle - mcycle_count),
+                        machine:run(big_last_mcycle - mcycle_count),
                         cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE
                     )
                     expect_consistent_root_hash(machine)
-                    collect_machine:run(test_last_mcycle - mcycle_count)
+                    collect_machine:run(big_last_mcycle - mcycle_count)
                     expect.equal(machine:get_root_hash(), collect_machine:get_root_hash())
                     local collected = collect_machine:collect_uarch_cycle_root_hashes(mcycle_count)
                     local expected_collected = expect_uarch_cycle_root_hashes(machine, mcycle_count)
                     local halt_exit_code = machine:read_reg("htif_tohost_data") >> 1
                     expect.equal(collected, expected_collected)
-                    expect.equal(machine:read_reg("mcycle"), test_last_mcycle)
-                    expect.equal(machine:get_root_hash(), test_last_root_hash)
+                    expect.equal(machine:read_reg("mcycle"), big_last_mcycle)
+                    expect.equal(machine:get_root_hash(), big_last_root_hash)
                     expect.equal(halt_exit_code, 255)
                 end)
+
+                it("should match dense uarch root hashes while yielding", function()
+                    expect.truthy(yield_last_mcycle ~= nil and yield_last_root_hash ~= nil)
+                    -- use prime numbers on purpose to test corner cases
+                    local mcycle_start = 7
+                    local mcycle_phase = 3
+                    local mcycle_period = 21
+                    local period_count = yield_last_mcycle // mcycle_period
+                    local machine <close> = cartesi.machine(yield_machine_config)
+                    local collect_machine <close> = cartesi.machine(yield_machine_config)
+                    machine:run(mcycle_start)
+                    expect.equal(machine:read_reg("mcycle"), mcycle_start)
+                    collect_machine:run(mcycle_start)
+                    expect_consistent_root_hash(machine)
+                    expect.equal(machine:get_root_hash(), collect_machine:get_root_hash())
+                    local mcycle_phase_offset = mcycle_start - mcycle_phase
+                    local sparse_hashes_count = 0
+                    local count_manual_yields = 0
+                    local count_automatic_yields = 0
+                    local halt_exit_code
+                    for _ = 1, period_count * 2 do
+                        local mcycles_to_phase0 = mcycle_period
+                            - ((machine:read_reg("mcycle") - mcycle_phase_offset) % mcycle_period)
+                        local collected = collect_machine:collect_uarch_cycle_root_hashes(mcycles_to_phase0)
+                        local expected_collected = expect_uarch_cycle_root_hashes(machine, mcycles_to_phase0)
+                        expect.equal(collect_machine:read_reg("mcycle"), machine:read_reg("mcycle"))
+                        expect.equal(collected, expected_collected)
+                        expect.equal(collect_machine:get_root_hash(), machine:get_root_hash())
+                        mcycles_to_phase0 = (machine:read_reg("mcycle") - mcycle_phase_offset) % mcycle_period
+                        if mcycles_to_phase0 == 0 then
+                            local period_index = (machine:read_reg("mcycle") - mcycle_phase_offset) // mcycle_period
+                            expect.equal(yield_sparse_hashes[period_index], machine:get_root_hash())
+                            sparse_hashes_count = sparse_hashes_count + 1
+                        end
+                        if machine:read_reg("iflags_Y") == 1 then
+                            collect_machine:write_reg("iflags_Y", 0)
+                            machine:write_reg("iflags_Y", 0)
+                            count_manual_yields = count_manual_yields + 1
+                        elseif machine:read_reg("iflags_X") == 1 then
+                            count_automatic_yields = count_automatic_yields + 1
+                        elseif machine:read_reg("iflags_H") == 1 then
+                            halt_exit_code = machine:read_reg("htif_tohost_data") >> 1
+                            break
+                        end
+                    end
+                    expect.equal(machine:read_reg("mcycle"), yield_last_mcycle)
+                    expect.equal(machine:get_root_hash(), yield_last_root_hash)
+                    expect.equal(count_manual_yields, 8)
+                    expect.equal(count_automatic_yields, 7)
+                    expect.equal(halt_exit_code, 42)
+                    expect.equal(sparse_hashes_count, #yield_sparse_hashes)
+                end)
             end
         end)
     end

From 21e7b290960877900f40d434dfb02b29d0a9eb8d Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Mon, 1 Sep 2025 16:23:23 -0300
Subject: [PATCH 67/82] refactor: change collect APIs to use mcycle_end instead
 of mcycle_count

---
 src/clua-i-machine.cpp            |  17 +++--
 src/i-machine.h                   |  24 ++++---
 src/jsonrpc-discover.json         |  28 ++++++--
 src/jsonrpc-machine.cpp           |  12 ++--
 src/jsonrpc-machine.h             |   7 +-
 src/jsonrpc-remote-machine.cpp    |  21 +++---
 src/local-machine.cpp             |  12 ++--
 src/local-machine.h               |   7 +-
 src/machine-c-api.cpp             |  11 +--
 src/machine-c-api.h               |  45 +++++++-----
 src/machine.cpp                   | 112 ++++++++++++++++--------------
 src/machine.h                     |  24 ++++---
 src/test-collect-hashes.lua       |   6 +-
 tests/lua/spec-collect-hashes.lua |  66 ++++++++++--------
 14 files changed, 226 insertions(+), 166 deletions(-)

diff --git a/src/clua-i-machine.cpp b/src/clua-i-machine.cpp
index 42c7b9250..543db45f3 100644
--- a/src/clua-i-machine.cpp
+++ b/src/clua-i-machine.cpp
@@ -991,13 +991,15 @@ static int machine_obj_index_create(lua_State *L) {
 /// \brief This is the machine:collect_mcycle_root_hashes() method implementation.
 /// \param L Lua state.
 static int machine_obj_index_collect_mcycle_root_hashes(lua_State *L) {
-    lua_settop(L, 4);
+    lua_settop(L, 5);
     auto &m = clua_check<clua_managed_cm_ptr<cm_machine>>(L, 1);
-    const uint64_t mcycle_phase = luaL_checkinteger(L, 2);
+    const uint64_t mcycle_end = luaL_checkinteger(L, 2);
     const uint64_t mcycle_period = luaL_checkinteger(L, 3);
-    const uint64_t period_count = luaL_checkinteger(L, 4);
+    const uint64_t mcycle_phase = luaL_optinteger(L, 4, 0);
+    const auto log2_bundle_uarch_cycle_count = static_cast<uint32_t>(luaL_optinteger(L, 5, 0));
     const char *result = nullptr;
-    if (cm_collect_mcycle_root_hashes(m.get(), mcycle_phase, mcycle_period, period_count, &result) != 0) {
+    if (cm_collect_mcycle_root_hashes(m.get(), mcycle_end, mcycle_period, mcycle_phase, log2_bundle_uarch_cycle_count,
+            &result) != 0) {
         return luaL_error(L, "%s", cm_get_last_error_message());
     }
     clua_push_schemed_json_table(L, result, "McycleRootHashes");
@@ -1007,11 +1009,12 @@ static int machine_obj_index_collect_mcycle_root_hashes(lua_State *L) {
 /// \brief This is the machine:collect_uarch_cycle_root_hashes() method implementation.
 /// \param L Lua state.
 static int machine_obj_index_collect_uarch_cycle_root_hashes(lua_State *L) {
-    lua_settop(L, 2);
+    lua_settop(L, 3);
     auto &m = clua_check<clua_managed_cm_ptr<cm_machine>>(L, 1);
-    const uint64_t mcycle_count = luaL_checkinteger(L, 2);
+    const uint64_t mcycle_end = luaL_checkinteger(L, 2);
+    const auto log2_bundle_uarch_cycle_count = static_cast<uint32_t>(luaL_optinteger(L, 3, 0));
     const char *result = nullptr;
-    if (cm_collect_uarch_cycle_root_hashes(m.get(), mcycle_count, &result) != 0) {
+    if (cm_collect_uarch_cycle_root_hashes(m.get(), mcycle_end, log2_bundle_uarch_cycle_count, &result) != 0) {
         return luaL_error(L, "%s", cm_get_last_error_message());
     }
     clua_push_schemed_json_table(L, result, "UarchCycleRootHashes");
diff --git a/src/i-machine.h b/src/i-machine.h
index 7f7e8f8dd..57e732ea4 100644
--- a/src/i-machine.h
+++ b/src/i-machine.h
@@ -87,11 +87,11 @@ class i_machine {
         return do_run(mcycle_end);
     }
 
-    /// \brief Collects the root hashes after every \p mcycle_period machine cycles, for \p period_count periods.
-    /// Returns when done, or if the machine halts or yields.
-    void collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_period, uint64_t period_count,
-        mcycle_root_hashes &result) {
-        do_collect_mcycle_root_hashes(mcycle_phase, mcycle_period, period_count, result);
+    /// \brief Collects the root hashes after every \p mcycle_period machine cycles until mcycle reaches \p mcycle_end,
+    /// or if the machine halts or yields.
+    void collect_mcycle_root_hashes(uint64_t mcycle_end, uint64_t mcycle_period, uint64_t mcycle_phase,
+        uint32_t log2_bundle_mcycle_count, mcycle_root_hashes &result) {
+        do_collect_mcycle_root_hashes(mcycle_end, mcycle_period, mcycle_phase, log2_bundle_mcycle_count, result);
     }
 
     /// \brief Serialize entire state to directory
@@ -227,10 +227,11 @@ class i_machine {
         return do_run_uarch(uarch_cycle_end);
     }
 
-    /// \brief Collects the root hashes after every \p uarch_cycle, for \p mcycle_count machine cycles, implicitly
+    /// \brief Collects the root hashes after every \p uarch_cycle until \p mcycle_end machine cycle, implicitly
     /// resetting the uarch between mcycles.
-    void collect_uarch_cycle_root_hashes(uint64_t mcycle_count, uarch_cycle_root_hashes &result) {
-        do_collect_uarch_cycle_root_hashes(mcycle_count, result);
+    void collect_uarch_cycle_root_hashes(uint64_t mcycle_end, uint32_t log2_bundle_uarch_cycle_count,
+        uarch_cycle_root_hashes &result) {
+        do_collect_uarch_cycle_root_hashes(mcycle_end, log2_bundle_uarch_cycle_count, result);
     }
 
     /// \brief Returns a list of descriptions for all PMA entries registered in the machine, sorted by start
@@ -295,8 +296,8 @@ class i_machine {
         const std::string &dir) = 0;
     virtual void do_load(const std::string &directory, const machine_runtime_config &runtime, sharing_mode sharing) = 0;
     virtual interpreter_break_reason do_run(uint64_t mcycle_end) = 0;
-    virtual void do_collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_period, uint64_t period_count,
-        mcycle_root_hashes &result) = 0;
+    virtual void do_collect_mcycle_root_hashes(uint64_t mcycle_end, uint64_t mcycle_period, uint64_t mcycle_phase,
+        uint32_t log2_bundle_mcycle_count, mcycle_root_hashes &result) = 0;
     virtual void do_store(const std::string &dir, sharing_mode sharing) const = 0;
     virtual void do_clone_stored(const std::string &from_dir, const std::string &to_dir) const = 0;
     virtual interpreter_break_reason do_log_step(uint64_t mcycle_count, const std::string &filename) = 0;
@@ -322,7 +323,8 @@ class i_machine {
     virtual void do_reset_uarch() = 0;
     virtual access_log do_log_reset_uarch(const access_log::type &log_type) = 0;
     virtual uarch_interpreter_break_reason do_run_uarch(uint64_t uarch_cycle_end) = 0;
-    virtual void do_collect_uarch_cycle_root_hashes(uint64_t mcycle_count, uarch_cycle_root_hashes &result) = 0;
+    virtual void do_collect_uarch_cycle_root_hashes(uint64_t mcycle_end, uint32_t log2_bundle_uarch_cycle_count,
+        uarch_cycle_root_hashes &result) = 0;
     virtual address_range_descriptions do_get_address_ranges() const = 0;
     virtual void do_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length) = 0;
     virtual access_log do_log_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
diff --git a/src/jsonrpc-discover.json b/src/jsonrpc-discover.json
index e87b40a76..96237b761 100644
--- a/src/jsonrpc-discover.json
+++ b/src/jsonrpc-discover.json
@@ -280,8 +280,8 @@
       "summary": "Collect root hashes periodically while running the emulator",
       "params": [
         {
-          "name": "mcycle_phase",
-          "description": "Number of machine cycles elapsed since last root hash collected",
+          "name": "mcycle_end",
+          "description": "End machine cycle value",
           "required": true,
           "schema": {
             "$ref": "#/components/schemas/UnsignedInteger"
@@ -296,8 +296,16 @@
           }
         },
         {
-          "name": "period_count",
-          "description": "Number of hashes to collect",
+          "name": "mcycle_phase",
+          "description": "Number of machine cycles elapsed since last root hash collected",
+          "required": true,
+          "schema": {
+            "$ref": "#/components/schemas/UnsignedInteger"
+          }
+        },
+        {
+          "name": "log2_bundle_mcycle_count",
+          "description": "Log base 2 of the amount of mcycle root hashes to bundle",
           "required": true,
           "schema": {
             "$ref": "#/components/schemas/UnsignedInteger"
@@ -338,8 +346,16 @@
       "summary": "Collect root hashes while running the emulator's uarch",
       "params": [
         {
-          "name": "mcycle_count",
-          "description": "Number of machine cycles to execute, uarch cycle by uarch cycle",
+          "name": "mcycle_end",
+          "description": "End machine cycle value to execute, uarch cycle by uarch cycle",
+          "required": true,
+          "schema": {
+            "$ref": "#/components/schemas/UnsignedInteger"
+          }
+        },
+        {
+          "name": "log2_bundle_uarch_cycle_count",
+          "description": "Log base 2 of the amount of uarch cycle root hashes to bundle",
           "required": true,
           "schema": {
             "$ref": "#/components/schemas/UnsignedInteger"
diff --git a/src/jsonrpc-machine.cpp b/src/jsonrpc-machine.cpp
index 810b06686..dfda36eda 100644
--- a/src/jsonrpc-machine.cpp
+++ b/src/jsonrpc-machine.cpp
@@ -645,9 +645,10 @@ interpreter_break_reason jsonrpc_machine::do_run(uint64_t mcycle_end) {
     return result;
 }
 
-void jsonrpc_machine::do_collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_period,
-    uint64_t period_count, mcycle_root_hashes &result) {
-    request("machine.collect_mcycle_root_hashes", std::tie(mcycle_phase, mcycle_period, period_count), result);
+void jsonrpc_machine::do_collect_mcycle_root_hashes(uint64_t mcycle_end, uint64_t mcycle_period, uint64_t mcycle_phase,
+    uint32_t log2_bundle_mcycle_count, mcycle_root_hashes &result) {
+    request("machine.collect_mcycle_root_hashes",
+        std::tie(mcycle_end, mcycle_period, mcycle_phase, log2_bundle_mcycle_count), result);
 }
 
 interpreter_break_reason jsonrpc_machine::do_log_step(uint64_t mcycle_count, const std::string &filename) {
@@ -816,8 +817,9 @@ uarch_interpreter_break_reason jsonrpc_machine::do_run_uarch(uint64_t uarch_cycl
     return result;
 }
 
-void jsonrpc_machine::do_collect_uarch_cycle_root_hashes(uint64_t mcycle_count, uarch_cycle_root_hashes &result) {
-    request("machine.collect_uarch_cycle_root_hashes", std::tie(mcycle_count), result);
+void jsonrpc_machine::do_collect_uarch_cycle_root_hashes(uint64_t mcycle_end, uint32_t log2_bundle_uarch_cycle_count,
+    uarch_cycle_root_hashes &result) {
+    request("machine.collect_uarch_cycle_root_hashes", std::tie(mcycle_end, log2_bundle_uarch_cycle_count), result);
 }
 
 address_range_descriptions jsonrpc_machine::do_get_address_ranges() const {
diff --git a/src/jsonrpc-machine.h b/src/jsonrpc-machine.h
index ec2a93694..963677a89 100644
--- a/src/jsonrpc-machine.h
+++ b/src/jsonrpc-machine.h
@@ -108,8 +108,8 @@ class jsonrpc_machine final : public i_machine {
         const std::string &dir) override;
     void do_load(const std::string &directory, const machine_runtime_config &runtime, sharing_mode sharing) override;
     interpreter_break_reason do_run(uint64_t mcycle_end) override;
-    void do_collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_period, uint64_t period_count,
-        mcycle_root_hashes &result) override;
+    void do_collect_mcycle_root_hashes(uint64_t mcycle_end, uint64_t mcycle_period, uint64_t mcycle_phase,
+        uint32_t log2_bundle_mcycle_count, mcycle_root_hashes &result) override;
     interpreter_break_reason do_log_step(uint64_t mcycle_count, const std::string &filename) override;
     void do_store(const std::string &dir, sharing_mode sharing) const override;
     void do_clone_stored(const std::string &from_dir, const std::string &to_dir) const override;
@@ -136,7 +136,8 @@ class jsonrpc_machine final : public i_machine {
     hash_tree_stats do_get_hash_tree_stats(bool clear) override;
     bool do_verify_hash_tree() const override;
     uarch_interpreter_break_reason do_run_uarch(uint64_t uarch_cycle_end) override;
-    void do_collect_uarch_cycle_root_hashes(uint64_t mcycle_count, uarch_cycle_root_hashes &result) override;
+    void do_collect_uarch_cycle_root_hashes(uint64_t mcycle_end, uint32_t log2_bundle_uarch_cycle_count,
+        uarch_cycle_root_hashes &result) override;
     address_range_descriptions do_get_address_ranges() const override;
     void do_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length) override;
     access_log do_log_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
diff --git a/src/jsonrpc-remote-machine.cpp b/src/jsonrpc-remote-machine.cpp
index 9957b3b5f..4073732e3 100644
--- a/src/jsonrpc-remote-machine.cpp
+++ b/src/jsonrpc-remote-machine.cpp
@@ -909,13 +909,15 @@ static json jsonrpc_machine_collect_mcycle_root_hashes(const json &j, const std:
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"mcycle_phase", "mcycle_period", "period_count"};
-    auto args = parse_args<uint64_t, uint64_t, uint64_t>(j, param_name);
-    auto mcycle_phase = std::get<0>(args);
+    static const char *param_name[] = {"mcycle_end", "mcycle_period", "mcycle_phase", "log2_bundle_mcycle_count"};
+    auto args = parse_args<uint64_t, uint64_t, uint64_t, uint64_t>(j, param_name);
+    auto mcycle_end = std::get<0>(args);
     auto mcycle_period = std::get<1>(args);
-    auto period_count = std::get<2>(args);
+    auto mcycle_phase = std::get<2>(args);
+    auto log2_bundle_mcycle_count = std::get<3>(args);
     cartesi::mcycle_root_hashes result;
-    session->handler->machine->collect_mcycle_root_hashes(mcycle_phase, mcycle_period, period_count, result);
+    session->handler->machine->collect_mcycle_root_hashes(mcycle_end, mcycle_period, mcycle_phase,
+        log2_bundle_mcycle_count, result);
     return jsonrpc_response_ok(j, result);
 }
 
@@ -928,11 +930,12 @@ static json jsonrpc_machine_collect_uarch_cycle_root_hashes(const json &j,
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"mcycle_count"};
-    auto args = parse_args<uint64_t>(j, param_name);
-    auto mcycle_count = std::get<0>(args);
+    static const char *param_name[] = {"mcycle_end", "log2_bundle_uarch_cycle_count"};
+    auto args = parse_args<uint64_t, uint64_t>(j, param_name);
+    auto mcycle_end = std::get<0>(args);
+    auto log2_bundle_uarch_cycle_count = std::get<1>(args);
     cartesi::uarch_cycle_root_hashes result;
-    session->handler->machine->collect_uarch_cycle_root_hashes(mcycle_count, result);
+    session->handler->machine->collect_uarch_cycle_root_hashes(mcycle_end, log2_bundle_uarch_cycle_count, result);
     return jsonrpc_response_ok(j, result);
 }
 
diff --git a/src/local-machine.cpp b/src/local-machine.cpp
index 1c589c5d3..91d4b0128 100644
--- a/src/local-machine.cpp
+++ b/src/local-machine.cpp
@@ -78,9 +78,10 @@ interpreter_break_reason local_machine::do_run(uint64_t mcycle_end) {
     return get_machine()->run(mcycle_end);
 }
 
-void local_machine::do_collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_period, uint64_t period_count,
-    mcycle_root_hashes &result) {
-    get_machine()->collect_mcycle_root_hashes(mcycle_phase, mcycle_period, period_count, result);
+void local_machine::do_collect_mcycle_root_hashes(uint64_t mcycle_end, uint64_t mcycle_period, uint64_t mcycle_phase,
+    uint32_t log2_bundle_mcycle_count, mcycle_root_hashes &result) {
+    get_machine()->collect_mcycle_root_hashes(mcycle_end, mcycle_period, mcycle_phase, log2_bundle_mcycle_count,
+        result);
 }
 
 interpreter_break_reason local_machine::do_log_step(uint64_t mcycle_count, const std::string &filename) {
@@ -180,8 +181,9 @@ uarch_interpreter_break_reason local_machine::do_run_uarch(uint64_t uarch_cycle_
     return get_machine()->run_uarch(uarch_cycle_end);
 }
 
-void local_machine::do_collect_uarch_cycle_root_hashes(uint64_t mcycle_count, uarch_cycle_root_hashes &result) {
-    get_machine()->collect_uarch_cycle_root_hashes(mcycle_count, result);
+void local_machine::do_collect_uarch_cycle_root_hashes(uint64_t mcycle_end, uint32_t log2_bundle_uarch_cycle_count,
+    uarch_cycle_root_hashes &result) {
+    get_machine()->collect_uarch_cycle_root_hashes(mcycle_end, log2_bundle_uarch_cycle_count, result);
 }
 
 address_range_descriptions local_machine::do_get_address_ranges() const {
diff --git a/src/local-machine.h b/src/local-machine.h
index 47ead6360..0afe8806a 100644
--- a/src/local-machine.h
+++ b/src/local-machine.h
@@ -50,8 +50,8 @@ class local_machine : public i_machine {
         const std::string &dir) override;
     void do_load(const std::string &directory, const machine_runtime_config &runtime, sharing_mode sharing) override;
     interpreter_break_reason do_run(uint64_t mcycle_end) override;
-    void do_collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_period, uint64_t period_count,
-        mcycle_root_hashes &result) override;
+    void do_collect_mcycle_root_hashes(uint64_t mcycle_end, uint64_t mcycle_period, uint64_t mcycle_phase,
+        uint32_t log2_bundle_mcycle_count, mcycle_root_hashes &result) override;
     interpreter_break_reason do_log_step(uint64_t mcycle_count, const std::string &filename) override;
     void do_store(const std::string &directory, sharing_mode sharing) const override;
     void do_clone_stored(const std::string &from_dir, const std::string &to_dir) const override;
@@ -78,7 +78,8 @@ class local_machine : public i_machine {
     void do_reset_uarch() override;
     access_log do_log_reset_uarch(const access_log::type &log_type) override;
     uarch_interpreter_break_reason do_run_uarch(uint64_t uarch_cycle_end) override;
-    void do_collect_uarch_cycle_root_hashes(uint64_t mcycle_count, uarch_cycle_root_hashes &result) override;
+    void do_collect_uarch_cycle_root_hashes(uint64_t mcycle_end, uint32_t log2_bundle_uarch_cycle_count,
+        uarch_cycle_root_hashes &result) override;
     address_range_descriptions do_get_address_ranges() const override;
     void do_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length) override;
     access_log do_log_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
diff --git a/src/machine-c-api.cpp b/src/machine-c-api.cpp
index dea557875..d33a2210c 100644
--- a/src/machine-c-api.cpp
+++ b/src/machine-c-api.cpp
@@ -645,14 +645,14 @@ cm_error cm_run(cm_machine *m, uint64_t mcycle_end, cm_break_reason *break_reaso
     return cm_result_failure();
 }
 
-cm_error cm_collect_mcycle_root_hashes(cm_machine *m, uint64_t mcycle_phase, uint64_t mcycle_period,
-    uint64_t period_count, const char **result) try {
+cm_error cm_collect_mcycle_root_hashes(cm_machine *m, uint64_t mcycle_end, uint64_t mcycle_period,
+    uint64_t mcycle_phase, uint32_t log2_bundle_mcycle_count, const char **result) try {
     if (result == nullptr) {
         throw std::invalid_argument("invalid result output");
     }
     auto *cpp_m = convert_from_c(m);
     cartesi::mcycle_root_hashes cpp_res;
-    cpp_m->collect_mcycle_root_hashes(mcycle_phase, mcycle_period, period_count, cpp_res);
+    cpp_m->collect_mcycle_root_hashes(mcycle_end, mcycle_period, mcycle_phase, log2_bundle_mcycle_count, cpp_res);
     *result = cm_set_temp_string(cartesi::to_json(cpp_res).dump());
     return cm_result_success();
 } catch (...) {
@@ -662,13 +662,14 @@ cm_error cm_collect_mcycle_root_hashes(cm_machine *m, uint64_t mcycle_phase, uin
     return cm_result_failure();
 }
 
-cm_error cm_collect_uarch_cycle_root_hashes(cm_machine *m, uint64_t mcycle_count, const char **result) try {
+cm_error cm_collect_uarch_cycle_root_hashes(cm_machine *m, uint64_t mcycle_end, uint32_t log2_bundle_uarch_cycle_count,
+    const char **result) try {
     if (result == nullptr) {
         throw std::invalid_argument("invalid result output");
     }
     auto *cpp_m = convert_from_c(m);
     cartesi::uarch_cycle_root_hashes cpp_res;
-    cpp_m->collect_uarch_cycle_root_hashes(mcycle_count, cpp_res);
+    cpp_m->collect_uarch_cycle_root_hashes(mcycle_end, log2_bundle_uarch_cycle_count, cpp_res);
     *result = cm_set_temp_string(cartesi::to_json(cpp_res).dump());
     return cm_result_success();
 } catch (...) {
diff --git a/src/machine-c-api.h b/src/machine-c-api.h
index ccaeabd9d..30418abeb 100644
--- a/src/machine-c-api.h
+++ b/src/machine-c-api.h
@@ -539,7 +539,7 @@ CM_API cm_error cm_get_root_hash(const cm_machine *m, cm_hash *hash);
 /// \param log2_size Log<sub>2</sub> of node size.
 /// \param hash Valid pointer to cm_hash structure that receives the hash.
 /// \returns 0 for success, non zero code for error.
-CM_API cm_error cm_get_node_hash(const cm_machine *m, uint64_t address, int log2_size, cm_hash *hash);
+CM_API cm_error cm_get_node_hash(const cm_machine *m, uint64_t address, int32_t log2_size, cm_hash *hash);
 
 /// \brief Obtains the proof for a node in the machine state Merkle tree.
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
@@ -643,30 +643,33 @@ CM_API cm_error cm_translate_virtual_address(cm_machine *m, uint64_t vaddr, uint
 /// \details You may want to receive cmio requests depending on the run break reason.
 CM_API cm_error cm_run(cm_machine *m, uint64_t mcycle_end, cm_break_reason *break_reason);
 
-/// \brief Collects the root hashes after every \p mcycle_period machine cycles, for \p period_count periods.
-/// Returns when done, or if the machine halts or yields.
-/// \param mcycle_phase Number of machine cycles elapsed since last root hash collected.
+/// \brief Collects the root hashes after every \p mcycle_period machine cycles
+/// until mcycle reaches \p mcycle_end, the machine yields, or halts.
+/// \param m Pointer to a non-empty machine object (holds a machine instance).
+/// \param mcycle_end End machine cycle value.
 /// \param mcycle_period Number of machine cycles between root hashes to collect.
-/// \param period_count Number of hashes to collect.
-/// \param result Receives an JSON object as a string, guaranteed to remain valid only until
+/// \param mcycle_phase Number of machine cycles elapsed since last root hash collected.
+/// \param log2_bundle_mcycle_count Log base 2 of the amount of mcycle root hashes to bundle.
+/// If greater than 0, it collects subtree root hashes for 2^log2_bundle_mcycle_count root hashes.
+/// \param result Receives a JSON object as a string, guaranteed to remain valid only until
 /// the next CM_API function is called from the same thread.
-/// The field "hashes" is an array (of hashes as base64-encoded strings) with the root hashes after each period.
+/// The field "hashes" is an array of root hashes (as base64-encoded strings) after each period.
 /// The field "mcycle_phase" is the number of machine cycles elapsed since last root hash collected.
-/// The field "break_reason" is an integer with the reason why the function returned.
-/// (Set to CM_BREAK_REASON_FAILED on failure.)
+/// The field "break_reason" is a string with the reason why the function returned.
+/// (Set to "failed" on failure.)
 /// For example:
 /// ```json
 /// {
 ///     "hashes": ["2av44Q3TaHKREgULA/iMoNe+btxCr+ja+hHGtXxaGjM=", ..., "FMAHn7mc2f+I30UjiywbAtOkw99iOa3NWS6fWql3UNU="],
 ///     "mcycle_phase": 1278,
-///     "break_reason": CM_BREAK_REASON_YIELDED_AUTOMATICALLY
+///     "break_reason": "yielded_manually"
 /// }
 /// ```
 /// \returns 0 for success, non zero code for error.
 /// \detail The first hash added to \p result.hashes is the root hash after (\p mcycle_period - \p mcycle_phase)
 /// machine cycles (if the function managed to get that far before returning).
-CM_API cm_error cm_collect_mcycle_root_hashes(cm_machine *m, uint64_t mcycle_phase, uint64_t mcycle_period,
-    uint64_t period_count, const char **result);
+CM_API cm_error cm_collect_mcycle_root_hashes(cm_machine *m, uint64_t mcycle_end, uint64_t mcycle_period,
+    uint64_t mcycle_phase, uint32_t log2_bundle_mcycle_count, const char **result);
 
 /// \brief Runs the machine microarchitecture until CM_REG_UARCH_CYCLE reaches uarch_cycle_end or it halts.
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
@@ -675,28 +678,32 @@ CM_API cm_error cm_collect_mcycle_root_hashes(cm_machine *m, uint64_t mcycle_pha
 /// \returns 0 for success, non zero code for error.
 CM_API cm_error cm_run_uarch(cm_machine *m, uint64_t uarch_cycle_end, cm_uarch_break_reason *uarch_break_reason);
 
-/// \brief Collects the root hashes after every uarch cycle, for \p mcycle_count machine cycles, implicitly
-/// resetting the uarch between each machine cycle. Returns when done, or if the machine halts or yields.
-/// \param mcycle_count Number of machine cycles to execute, uarch cycle by uarch cycle.
-/// \param hashes Receives an JSON object as a string, guaranteed to remain valid only until
+/// \brief Collects the root hashes after every uarch cycle until mcycle reaches \p mcycle_end,
+/// the machine yields, or halts. Implicitly resetting the uarch between mcycles.
+/// \param m Pointer to a non-empty machine object (holds a machine instance).
+/// \param mcycle_end End machine cycle value to execute, uarch cycle by uarch cycle.
+/// \param log2_bundle_uarch_cycle_count Log base 2 of the amount of uarch cycle root hashes to bundle.
+/// If greater than 0, it collects subtree root hashes for 2^log2_bundle_mcycle_count root hashes.
+/// \param result Receives an JSON object as a string, guaranteed to remain valid only until
 /// the next CM_API function is called from the same thread.
 /// The field "hashes" is an array (of hashes as base64-encoded strings) with the root hashes after each uarch cycle.
 /// The field "reset_indices" is an array with indices of the root hashes after each implicit uarch reset
 /// (i.e., after each machine cycle).
 /// The field "break_reason" is an integer with the reason why the function returned.
-/// (Set to CM_BREAK_REASON_FAILED on failure.)
+/// (Set to "failed" on failure.)
 /// For example:
 /// ```json
 /// {
 ///     "hashes": ["2av44Q3TaHKREgULA/iMoNe+btxCr+ja+hHGtXxaGjM=", ..., "FMAHn7mc2f+I30UjiywbAtOkw99iOa3NWS6fWql3UNU="],
 ///     "reset_indices": [712, ..., 2293768],
-///     "break_reason": CM_BREAK_REASON_YIELDED_MANUALLY
+///     "break_reason": "yielded_manually"
 /// }
 /// ```
 /// \returns 0 for success, non zero code for error.
 /// \detail The first hash added to \p hashes is the root hash after the first uarch cycle, the last is the
 /// root hash at the time function returns (for whatever reason), which always happens right after an uarch reset.
-CM_API cm_error cm_collect_uarch_cycle_root_hashes(cm_machine *m, uint64_t mcycle_count, const char **result);
+CM_API cm_error cm_collect_uarch_cycle_root_hashes(cm_machine *m, uint64_t mcycle_end,
+    uint32_t log2_bundle_uarch_cycle_count, const char **result);
 
 /// \brief Resets the entire microarchitecture state to pristine values.
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
diff --git a/src/machine.cpp b/src/machine.cpp
index 2be1680c3..21f8972de 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -1965,18 +1965,23 @@ void machine::write_counter(uint64_t val, const char *name, const char *domain)
     m_counters[get_counter_key(name, domain)] = val;
 }
 
-void machine::collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_period, uint64_t period_count,
-    mcycle_root_hashes &result) {
-    mcycle_root_hashes next_result;
-    std::swap(next_result, result);
+void machine::collect_mcycle_root_hashes(uint64_t mcycle_end, uint64_t mcycle_period, uint64_t mcycle_phase,
+    uint32_t log2_bundle_mcycle_count, mcycle_root_hashes &result) {
+    auto clear_result_on_failure = make_scope_fail([&] {
+        result = mcycle_root_hashes{};
+    });
+    const uint64_t mcycle_start = read_reg(reg::mcycle);
+    if (mcycle_end < mcycle_start) {
+        throw std::runtime_error{"mcycle is past"};
+    }
     if (mcycle_period == 0) {
         throw std::runtime_error{"mcycle_period cannot be 0"};
     }
     if (mcycle_phase >= mcycle_period) {
         throw std::runtime_error{"mcycle_phase must be in {0, ..., mcycle_period-1}"};
     }
-    if (mcycle_phase > read_reg(reg::mcycle)) {
-        throw std::runtime_error{"mcycle_phase cannot be greater than machine mcycle"};
+    if (log2_bundle_mcycle_count != 0) {
+        throw std::runtime_error{"log2_bundle_mcycle_count != 0 is unsupported yet"};
     }
     if (read_reg(reg::iunrep) != 0) {
         throw std::runtime_error{"cannot collect hashes from unreproducible machines"};
@@ -1995,32 +2000,31 @@ void machine::collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_
             throw std::runtime_error{"microarchitecture is not reset"};
         }
     }
-    next_result.hashes.clear();
-    next_result.mcycle_phase = mcycle_phase;
+    result.hashes.clear();
+    result.mcycle_phase = mcycle_phase;
     // Check halted and yielded break reasons first to behave with same priority as the interpreter
     if (read_reg(reg::iflags_H) != 0) {
-        next_result.break_reason = interpreter_break_reason::halted;
-        std::swap(next_result, result);
+        result.break_reason = interpreter_break_reason::halted;
+        std::swap(result, result);
         return;
     }
     if (read_reg(reg::iflags_Y) != 0) {
-        next_result.break_reason = interpreter_break_reason::yielded_manually;
-        std::swap(next_result, result);
+        result.break_reason = interpreter_break_reason::yielded_manually;
+        std::swap(result, result);
         return;
     }
-    next_result.hashes.reserve(mcycle_period);
-    next_result.break_reason = interpreter_break_reason::reached_target_mcycle;
+    result.hashes.reserve(mcycle_period);
+    result.break_reason = interpreter_break_reason::reached_target_mcycle;
     collect_mcycle_hashes_state_access::context context{};
     context.dirty_pages.reserve(std::clamp<uint64_t>(mcycle_period * 4, 16, 4096));
     const collect_mcycle_hashes_state_access a(context, *this);
     os_silence_putchar(m_r.htif.no_console_putchar);
-    auto mcycle_start = read_reg(reg::mcycle) - mcycle_phase;
-    for (uint64_t period = 0; period < period_count; ++period) {
-        uint64_t mcycle_target{};
-        if (__builtin_add_overflow(mcycle_start, mcycle_period, &mcycle_target)) {
+    uint64_t mcycle_last_phase = mcycle_phase;
+    for (uint64_t mcycle_target = mcycle_start; mcycle_target < mcycle_end;) {
+        if (__builtin_add_overflow(mcycle_target, mcycle_period - mcycle_last_phase, &mcycle_target)) {
             mcycle_target = UINT64_MAX;
         }
-        next_result.break_reason = interpret(a, mcycle_target);
+        result.break_reason = interpret(a, mcycle_target);
         for (const uint64_t paddr_page : context.dirty_pages) {
             // NOLINTNEXTLINE(cppcoreguidelines-pro-type-const-cast)
             auto &ar = const_cast<address_range &>(find_address_range(paddr_page, HASH_TREE_PAGE_SIZE));
@@ -2030,26 +2034,33 @@ void machine::collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_
             throw std::runtime_error{"update hash tree failed"};
         }
         context.dirty_pages.clear();
-        const auto mcycle_end = read_reg(reg::mcycle);
+        const auto mcycle_reached = read_reg(reg::mcycle);
         // If the machine stopped before we asked, we are done
-        if (mcycle_end != mcycle_target || mcycle_target == UINT64_MAX) {
+        if (mcycle_reached != mcycle_target || mcycle_target == UINT64_MAX) {
             break;
         }
-        next_result.hashes.emplace_back(m_ht.get_root_hash());
-        mcycle_start = mcycle_end;
+        result.hashes.emplace_back(m_ht.get_root_hash());
+        mcycle_last_phase = 0;
         // If the machine stopped before we asked, we are done
-        if (next_result.break_reason != interpreter_break_reason::reached_target_mcycle) {
+        if (result.break_reason != interpreter_break_reason::reached_target_mcycle) {
             break;
         }
     }
-    next_result.mcycle_phase = read_reg(reg::mcycle) - mcycle_start;
-    // Commit new result
-    std::swap(next_result, result);
+    result.mcycle_phase = (read_reg(reg::mcycle) - mcycle_start + mcycle_phase) % mcycle_period;
 }
 
-void machine::collect_uarch_cycle_root_hashes(uint64_t mcycle_count, uarch_cycle_root_hashes &result) {
-    uarch_cycle_root_hashes next_result;
-    std::swap(next_result, result);
+void machine::collect_uarch_cycle_root_hashes(uint64_t mcycle_end, uint32_t log2_bundle_uarch_cycle_count,
+    uarch_cycle_root_hashes &result) {
+    auto clear_result_on_failure = make_scope_fail([&] {
+        result = uarch_cycle_root_hashes{};
+    });
+    const uint64_t mcycle_start = read_reg(reg::mcycle);
+    if (mcycle_end < mcycle_start) {
+        throw std::runtime_error{"mcycle is past"};
+    }
+    if (log2_bundle_uarch_cycle_count != 0) {
+        throw std::runtime_error{"log2_bundle_mcycle_count != 0 is unsupported yet"};
+    }
     if (read_reg(reg::iunrep) != 0) {
         throw std::runtime_error{"cannot collect hashes from unreproducible machines"};
     }
@@ -2068,22 +2079,21 @@ void machine::collect_uarch_cycle_root_hashes(uint64_t mcycle_count, uarch_cycle
     if (current_uarch_state_hash != get_uarch_pristine_state_hash()) {
         throw std::runtime_error{"microarchitecture is not reset"};
     }
-    next_result.hashes.clear();
-    next_result.reset_indices.clear();
+    result.hashes.clear();
+    result.reset_indices.clear();
     // Check halted and yielded break reasons first to behave with same priority as the interpreter
     if (read_reg(reg::iflags_H) != 0) {
-        next_result.break_reason = interpreter_break_reason::halted;
-        std::swap(next_result, result);
+        result.break_reason = interpreter_break_reason::halted;
         return;
     }
     if (read_reg(reg::iflags_Y) != 0) {
-        next_result.break_reason = interpreter_break_reason::yielded_manually;
-        std::swap(next_result, result);
+        result.break_reason = interpreter_break_reason::yielded_manually;
         return;
     }
-    next_result.hashes.reserve(mcycle_count * 512);
-    next_result.reset_indices.reserve(mcycle_count);
-    next_result.break_reason = interpreter_break_reason::reached_target_mcycle;
+    const uint64_t mcycle_count = mcycle_end - mcycle_start;
+    result.hashes.reserve(mcycle_count * 512);
+    result.reset_indices.reserve(mcycle_count);
+    result.break_reason = interpreter_break_reason::reached_target_mcycle;
     collect_uarch_cycle_hashes_state_access::context context{};
     context.dirty_words.reserve(8);
     const collect_uarch_cycle_hashes_state_access a(context, *this);
@@ -2091,15 +2101,15 @@ void machine::collect_uarch_cycle_root_hashes(uint64_t mcycle_count, uarch_cycle
     for (uint64_t mcycles = 0; mcycles < mcycle_count; ++mcycles) {
         // If the machine stopped before we asked, we are done
         if (read_reg(reg::iflags_H) != 0) {
-            next_result.break_reason = interpreter_break_reason::halted;
+            result.break_reason = interpreter_break_reason::halted;
             break;
         }
         if (read_reg(reg::iflags_Y) != 0) {
-            next_result.break_reason = interpreter_break_reason::yielded_manually;
+            result.break_reason = interpreter_break_reason::yielded_manually;
             break;
         }
         if (read_reg(reg::iflags_X) != 0 && mcycles > 0) {
-            next_result.break_reason = interpreter_break_reason::yielded_automatically;
+            result.break_reason = interpreter_break_reason::yielded_automatically;
             break;
         }
         uint64_t mcycle_target{};
@@ -2114,32 +2124,30 @@ void machine::collect_uarch_cycle_root_hashes(uint64_t mcycle_count, uarch_cycle
                 break;
             }
             uarch_interpret(a, uarch_cycle_target);
-            const auto uarch_cycle_end = read_reg(reg::uarch_cycle);
+            const auto uarch_cycle_reached = read_reg(reg::uarch_cycle);
             if (!m_ht.update_words(m_ars, context.dirty_words)) {
                 throw std::runtime_error{"update hash tree failed"};
             }
             context.dirty_words.clear();
-            if (uarch_cycle_end != uarch_cycle_target) {
+            if (uarch_cycle_reached != uarch_cycle_target) {
                 break;
             }
-            next_result.hashes.emplace_back(m_ht.get_root_hash());
-            uarch_cycle_start = uarch_cycle_end;
+            result.hashes.emplace_back(m_ht.get_root_hash());
+            uarch_cycle_start = uarch_cycle_reached;
         }
         //??D maybe optimize this?
         reset_uarch();
         if (!update_hash_tree()) {
             throw std::runtime_error{"update hash tree failed"};
         }
-        const auto mcycle_end = read_reg(reg::mcycle);
-        if (mcycle_end != mcycle_target) {
+        const auto mcycle_reached = read_reg(reg::mcycle);
+        if (mcycle_reached != mcycle_target) {
             throw std::runtime_error{"machine did not reach the expected target mcycle"};
         }
         // Add one hash after the uarch reset, and the index where it happened
-        next_result.reset_indices.emplace_back(next_result.hashes.size());
-        next_result.hashes.emplace_back(m_ht.get_root_hash());
+        result.reset_indices.emplace_back(result.hashes.size());
+        result.hashes.emplace_back(m_ht.get_root_hash());
     }
-    // Commit new result
-    std::swap(next_result, result);
 }
 
 } // namespace cartesi
diff --git a/src/machine.h b/src/machine.h
index 58ce2bf95..4fb522b3f 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -201,18 +201,20 @@ class machine final {
     ///  halts.
     interpreter_break_reason run(uint64_t mcycle_end);
 
-    /// \brief Collects the root hashes after every \p mcycle_period machine cycles, for \p period_count periods.
-    /// Returns when done, or if the machine halts or yields.
-    /// \param mcycle_phase Number of machine cycles elapsed since last root hash collected.
+    /// \brief Collects the root hashes after every \p mcycle_period machine cycles
+    /// until mcycle reaches \p mcycle_end, the machine yields, or halts.
+    /// \param mcycle_end Maximum value of mcycle before function returns.
     /// \param mcycle_period Number of machine cycles between root hashes to collect.
-    /// \param period_count Number of hashes to collect.
+    /// \param mcycle_phase Number of machine cycles elapsed since last root hash collected.
+    /// \param log2_bundle_mcycle_count Log base 2 of the amount of mcycle root hashes to bundle.
+    /// If greater than 0, it collects subtree root hashes for 2^log2_bundle_mcycle_count root hashes.
     /// \param result Stores into result.hashes the root hashes after each period.
     /// Stores into result.mcycle_phase the number of machine cycles after last root hash collected.
     /// Stores into result.break_reason the reason the function returned.
     /// \detail The first hash added to \p result.hashes is the root hash after (\p mcycle_period - \p mcycle_phase)
     /// machine cycles (if the function managed to get that far before returning).
-    void collect_mcycle_root_hashes(uint64_t mcycle_phase, uint64_t mcycle_period, uint64_t period_count,
-        mcycle_root_hashes &result);
+    void collect_mcycle_root_hashes(uint64_t mcycle_end, uint64_t mcycle_period, uint64_t mcycle_phase,
+        uint32_t log2_bundle_mcycle_count, mcycle_root_hashes &result);
 
     /// \brief Runs the machine for the given mcycle count and generates a log of accessed pages and proof data.
     /// \param mcycle_count Number of mcycles to run the machine for.
@@ -233,15 +235,17 @@ class machine final {
     /// \param uarch_cycle_end uarch_cycle limit
     uarch_interpreter_break_reason run_uarch(uint64_t uarch_cycle_end);
 
-    /// \brief Collects the root hashes after every uarch cycle, for \p mcycle_count machine cycles, implicitly
-    /// resetting the uarch between each machine cycle. Returns when done, or if the machine halts or yields.
-    /// \param mcycle_count Number of machine cycles to execute, uarch cycle by uarch cycle.
+    /// \brief Collects the root hashes after every uarch cycle until mcycle reaches \p mcycle_end,
+    /// the machine yields, or halts. Implicitly resetting the uarch between mcycles.
+    /// \param mcycle_end End machine cycle value to execute, uarch cycle by uarch cycle.
     /// \param result Stores into result.hashes the root hashes after each uarch cycle.
+    /// \param log2_bundle_uarch_cycle_count Log base 2 of the amount of uarch cycle root hashes to bundle.
     /// Stores into result.reset_indices the indices of the root hashes after each implicit uarch reset (i.e., after
     /// each machine cycle). Stores into result.break_reason the reason why the function returned.
     /// \detail The first hash added to \p result.hashes is the root hash after the first uarch cycle, the last is the
     /// root hash at the time function returns (for whatever reason), which always happens right after an uarch reset.
-    void collect_uarch_cycle_root_hashes(uint64_t mcycle_count, uarch_cycle_root_hashes &result);
+    void collect_uarch_cycle_root_hashes(uint64_t mcycle_end, uint32_t log2_bundle_uarch_cycle_count,
+        uarch_cycle_root_hashes &result);
 
     /// \brief Advances one micro step and returns a state access log.
     /// \param log_type Type of access log to generate.
diff --git a/src/test-collect-hashes.lua b/src/test-collect-hashes.lua
index 6eb66b457..ac52767a4 100755
--- a/src/test-collect-hashes.lua
+++ b/src/test-collect-hashes.lua
@@ -176,7 +176,11 @@ local function get_root_hashes_with_collect(input_count)
             m:send_cmio_response(cartesi.CMIO_YIELD_REASON_ADVANCE_STATE, input)
             index = index + 1
         end
-        local collected = m:collect_mcycle_root_hashes(mcycle_phase, MCYCLE_PERIOD, period_count)
+        local collected = m:collect_mcycle_root_hashes(
+            m:read_reg("mcycle") + period_count * MCYCLE_PERIOD,
+            MCYCLE_PERIOD,
+            mcycle_phase
+        )
         break_reason, mcycle_phase = collected.break_reason, collected.mcycle_phase
         tappend(hashes, collected.hashes)
     end
diff --git a/tests/lua/spec-collect-hashes.lua b/tests/lua/spec-collect-hashes.lua
index f5f3be63c..7852afb6d 100644
--- a/tests/lua/spec-collect-hashes.lua
+++ b/tests/lua/spec-collect-hashes.lua
@@ -15,11 +15,10 @@ local function expect_consistent_root_hash(machine)
     expect.equal(external_root_hash, root_hash)
 end
 
-local function expect_mcycle_root_hashes(machine, mcycle_phase, mcycle_period, period_count)
+local function expect_mcycle_root_hashes(machine, mcycle_end, mcycle_period, mcycle_phase)
     local break_reason
     local hashes = {}
     local mcycle_start = machine:read_reg("mcycle") + mcycle_period - mcycle_phase
-    local mcycle_end = machine:read_reg("mcycle") - mcycle_phase + (period_count * mcycle_period)
     for mcycle_target = mcycle_start, mcycle_end, mcycle_period do
         break_reason = machine:run(mcycle_target)
         expect_consistent_root_hash(machine)
@@ -41,12 +40,11 @@ local function expect_mcycle_root_hashes(machine, mcycle_phase, mcycle_period, p
     }
 end
 
-local function expect_uarch_cycle_root_hashes(machine, mcycle_count)
+local function expect_uarch_cycle_root_hashes(machine, mcycle_end)
     local hashes = {}
     local reset_indices = {}
     local break_reason
     local mcycle_start = machine:read_reg("mcycle")
-    local mcycle_end = mcycle_start + mcycle_count
     for mcycle = mcycle_start + 1, mcycle_end do
         if machine:read_reg("iflags_H") ~= 0 then
             break_reason = cartesi.BREAK_REASON_HALTED
@@ -93,15 +91,19 @@ end
 describe("collect hashes", function()
     it("should fail when collecting with invalid arguments", function()
         local machine <close> = cartesi.machine({ ram = { length = 4096 } })
+        machine:run(1)
         expect.fail(function()
-            machine:collect_mcycle_root_hashes(32, 32, 1)
+            machine:collect_mcycle_root_hashes(32, 32, 32)
         end, "mcycle_phase must be in")
         expect.fail(function()
-            machine:collect_mcycle_root_hashes(0, 0, 1)
+            machine:collect_mcycle_root_hashes(32, 0)
         end, "mcycle_period cannot be 0")
         expect.fail(function()
-            machine:collect_mcycle_root_hashes(1, 32, 1)
-        end, "mcycle_phase cannot be greater than machine mcycle")
+            machine:collect_mcycle_root_hashes(machine:read_reg("mcycle") - 1, 32)
+        end, "mcycle is past")
+        expect.fail(function()
+            machine:collect_uarch_cycle_root_hashes(0)
+        end, "mcycle is past")
     end)
 
     it("should fail when collecting from unsupported machines", function()
@@ -109,13 +111,13 @@ describe("collect hashes", function()
             cartesi.machine({ ram = { length = 4096 }, processor = { registers = { iunrep = 1 } } })
         local soft_machine <close> = cartesi.machine({ ram = { length = 4096 } }, { soft_yield = true })
         expect.fail(function()
-            unrep_machine:collect_mcycle_root_hashes(0, 32, 1)
+            unrep_machine:collect_mcycle_root_hashes(32, 32)
         end, "cannot collect hashes from unreproducible machines")
         expect.fail(function()
             unrep_machine:collect_uarch_cycle_root_hashes(32)
         end, "cannot collect hashes from unreproducible machines")
         expect.fail(function()
-            soft_machine:collect_mcycle_root_hashes(0, 32, 1)
+            soft_machine:collect_mcycle_root_hashes(32, 32)
         end, "cannot collect hashes when soft yield is enabled")
         expect.fail(function()
             soft_machine:collect_uarch_cycle_root_hashes(32)
@@ -125,12 +127,12 @@ describe("collect hashes", function()
     it("should succeed when collecting 0 periods", function()
         local machine <close> = cartesi.machine({ ram = { length = 4096 } })
         machine:run(1)
-        expect.equal(machine:collect_mcycle_root_hashes(1, 32, 0), {
+        expect.equal(machine:collect_mcycle_root_hashes(machine:read_reg("mcycle"), 32, 1), {
             hashes = {},
             break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE,
             mcycle_phase = 1,
         })
-        expect.equal(machine:collect_uarch_cycle_root_hashes(0), {
+        expect.equal(machine:collect_uarch_cycle_root_hashes(machine:read_reg("mcycle")), {
             hashes = {},
             reset_indices = {},
             break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE,
@@ -140,10 +142,10 @@ describe("collect hashes", function()
     it("should succeed when collecting from halted machines", function()
         local machine <close> = cartesi.machine({ ram = { length = 4096 } })
         machine:write_reg("iflags_H", 1)
-        expect.equal(machine:collect_mcycle_root_hashes(0, 32, 1), {
+        expect.equal(machine:collect_mcycle_root_hashes(32, 32, 1), {
             hashes = {},
             break_reason = cartesi.BREAK_REASON_HALTED,
-            mcycle_phase = 0,
+            mcycle_phase = 1,
         })
         expect.equal(machine:read_reg("mcycle"), 0)
         expect.equal(machine:collect_uarch_cycle_root_hashes(32), {
@@ -157,10 +159,10 @@ describe("collect hashes", function()
     it("should succeed when collecting from yielded machines", function()
         local machine <close> = cartesi.machine({ ram = { length = 4096 } })
         machine:write_reg("iflags_Y", 1)
-        expect.equal(machine:collect_mcycle_root_hashes(0, 32, 1), {
+        expect.equal(machine:collect_mcycle_root_hashes(32, 32, 1), {
             hashes = {},
             break_reason = cartesi.BREAK_REASON_YIELDED_MANUALLY,
-            mcycle_phase = 0,
+            mcycle_phase = 1,
         })
         expect.equal(machine:read_reg("mcycle"), 0)
         expect.equal(machine:collect_uarch_cycle_root_hashes(32), {
@@ -175,16 +177,16 @@ describe("collect hashes", function()
         local machine <close> = cartesi.machine({ ram = { length = 4096 } })
         local MAX_MCYCLE <const> = -1
         machine:write_reg("mcycle", MAX_MCYCLE - 1)
-        expect.equal(machine:collect_mcycle_root_hashes(machine:read_reg("mcycle") % 32, 32, 1), {
+        expect.equal(machine:collect_mcycle_root_hashes(MAX_MCYCLE, 32, machine:read_reg("mcycle") % 32), {
             hashes = {},
             break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE,
-            mcycle_phase = 31,
+            mcycle_phase = machine:read_reg("mcycle") % 32,
         })
         expect.equal(machine:read_reg("mcycle"), MAX_MCYCLE)
-        expect.equal(machine:collect_mcycle_root_hashes(machine:read_reg("mcycle") % 32, 32, 1), {
+        expect.equal(machine:collect_mcycle_root_hashes(MAX_MCYCLE, 32, machine:read_reg("mcycle") % 32), {
             hashes = {},
             break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE,
-            mcycle_phase = 31,
+            mcycle_phase = machine:read_reg("mcycle") % 32,
         })
         expect.equal(machine:read_reg("mcycle"), MAX_MCYCLE)
     end)
@@ -194,11 +196,11 @@ describe("collect hashes", function()
         local MAX_MCYCLE <const> = -1
         machine:write_reg("mcycle", MAX_MCYCLE - 1)
         expect.equal(
-            machine:collect_uarch_cycle_root_hashes(machine:read_reg("mcycle") % 32, 32, 1).break_reason,
+            machine:collect_uarch_cycle_root_hashes(MAX_MCYCLE).break_reason,
             cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE
         )
         expect.equal(machine:read_reg("mcycle"), MAX_MCYCLE)
-        expect.equal(machine:collect_uarch_cycle_root_hashes(machine:read_reg("mcycle") % 32, 32, 1), {
+        expect.equal(machine:collect_uarch_cycle_root_hashes(MAX_MCYCLE), {
             hashes = {},
             reset_indices = {},
             break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE,
@@ -281,8 +283,10 @@ describe("collect hashes", function()
                 expect_consistent_root_hash(machine)
                 expect.equal(machine:get_root_hash(), collect_machine:get_root_hash())
                 local mcycle_phase = machine:read_reg("mcycle") % mcycle_period
-                local collected = collect_machine:collect_mcycle_root_hashes(mcycle_phase, mcycle_period, period_count)
-                local expected_collected = expect_mcycle_root_hashes(machine, mcycle_phase, mcycle_period, period_count)
+                local mcycle_target = machine:read_reg("mcycle") + period_count * mcycle_period
+                local collected = collect_machine:collect_mcycle_root_hashes(mcycle_target, mcycle_period, mcycle_phase)
+                local expected_collected =
+                    expect_mcycle_root_hashes(machine, mcycle_target, mcycle_period, mcycle_phase)
                 local halt_exit_code = machine:read_reg("htif_tohost_data") >> 1
                 expect.equal(collected, expected_collected)
                 expect.equal(collect_machine:get_root_hash(), machine:get_root_hash())
@@ -309,10 +313,11 @@ describe("collect hashes", function()
                 local count_automatic_yields = 0
                 local halt_exit_code
                 for _ = 1, period_count * 2 do
+                    local mcycle_target = machine:read_reg("mcycle") + period_count * mcycle_period
                     local collected =
-                        collect_machine:collect_mcycle_root_hashes(mcycle_phase, mcycle_period, period_count)
+                        collect_machine:collect_mcycle_root_hashes(mcycle_target, mcycle_period, mcycle_phase)
                     local expected_collected =
-                        expect_mcycle_root_hashes(machine, mcycle_phase, mcycle_period, period_count)
+                        expect_mcycle_root_hashes(machine, mcycle_target, mcycle_period, mcycle_phase)
                     expect.equal(collect_machine:read_reg("mcycle"), machine:read_reg("mcycle"))
                     expect.equal(collected, expected_collected)
                     expect.equal(collect_machine:get_root_hash(), machine:get_root_hash())
@@ -354,8 +359,8 @@ describe("collect hashes", function()
                     expect_consistent_root_hash(machine)
                     collect_machine:run(big_last_mcycle - mcycle_count)
                     expect.equal(machine:get_root_hash(), collect_machine:get_root_hash())
-                    local collected = collect_machine:collect_uarch_cycle_root_hashes(mcycle_count)
-                    local expected_collected = expect_uarch_cycle_root_hashes(machine, mcycle_count)
+                    local collected = collect_machine:collect_uarch_cycle_root_hashes(big_last_mcycle)
+                    local expected_collected = expect_uarch_cycle_root_hashes(machine, big_last_mcycle)
                     local halt_exit_code = machine:read_reg("htif_tohost_data") >> 1
                     expect.equal(collected, expected_collected)
                     expect.equal(machine:read_reg("mcycle"), big_last_mcycle)
@@ -385,8 +390,9 @@ describe("collect hashes", function()
                     for _ = 1, period_count * 2 do
                         local mcycles_to_phase0 = mcycle_period
                             - ((machine:read_reg("mcycle") - mcycle_phase_offset) % mcycle_period)
-                        local collected = collect_machine:collect_uarch_cycle_root_hashes(mcycles_to_phase0)
-                        local expected_collected = expect_uarch_cycle_root_hashes(machine, mcycles_to_phase0)
+                        local mcycle_target = machine:read_reg("mcycle") + mcycles_to_phase0
+                        local collected = collect_machine:collect_uarch_cycle_root_hashes(mcycle_target)
+                        local expected_collected = expect_uarch_cycle_root_hashes(machine, mcycle_target)
                         expect.equal(collect_machine:read_reg("mcycle"), machine:read_reg("mcycle"))
                         expect.equal(collected, expected_collected)
                         expect.equal(collect_machine:get_root_hash(), machine:get_root_hash())

From c748e6db801241d3ebee3174f1599e65647f4c26 Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Thu, 11 Sep 2025 13:36:10 -0300
Subject: [PATCH 68/82] fix: make cartesi-machine-stored-hash work with new
 merkle tree changes

---
 src/cartesi-machine-stored-hash.lua | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/src/cartesi-machine-stored-hash.lua b/src/cartesi-machine-stored-hash.lua
index 25beca28f..04f9a672b 100755
--- a/src/cartesi-machine-stored-hash.lua
+++ b/src/cartesi-machine-stored-hash.lua
@@ -16,12 +16,11 @@
 -- with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 --
 
+local cartesi = require("cartesi")
 local util = require("cartesi.util")
 
-local f = assert(
-    io.open(assert(arg[1], "missing machine name") .. "/hash", "rb"),
-    string.format("unable to open machine '%s'", tostring(arg[1]))
-)
-local h = assert(f:read("a"), "unable to read hash")
-f:close()
-print(util.hexhash(h))
+local dir = assert(arg[1], "missing machine directory")
+local machine <close> = cartesi.machine(dir)
+local root_hash = machine:get_root_hash()
+local hex_root_hash = util.hexhash(root_hash)
+print(hex_root_hash)

From 03a8a23c87c8c3e2ea8f5f3e9e01a2d5da5c82f3 Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Mon, 1 Sep 2025 17:45:12 -0300
Subject: [PATCH 69/82] feat: implement root hashes context

---
 .clang-tidy                                   |   6 -
 .dockerignore                                 |   2 +-
 .github/workflows/build.yml                   |  12 +-
 .gitignore                                    |   3 +-
 Makefile                                      |   4 +-
 src/Makefile                                  |  62 +-
 src/access-log.h                              |  10 +-
 src/address-range-defines.h                   |   1 +
 src/address-range.h                           |   7 +-
 src/algorithm.h                               |  33 +-
 src/assert-printf.h                           |   7 +-
 src/back-merkle-tree.cpp                      | 167 ++--
 src/back-merkle-tree.h                        | 237 +++--
 src/base64.h                                  |   1 +
 src/cartesi-machine.lua                       |   4 +-
 src/clint-address-range.cpp                   |   2 +-
 src/clint-address-range.h                     |   4 +
 src/clua-cartesi.cpp                          |   3 +-
 src/clua-i-machine.cpp                        |  18 +-
 src/clua-i-machine.h                          |  11 +-
 src/collect-mcycle-hashes-state-access.h      |  12 +-
 src/collect-uarch-cycle-hashes-state-access.h |   4 +-
 src/complete-merkle-tree.cpp                  | 149 ----
 src/complete-merkle-tree.h                    | 134 ---
 src/concepts.h                                |  14 +-
 src/dense-hash-tree.h                         |   3 +-
 src/device-state-access.h                     |   2 +-
 src/dirty-page-tree.h                         |   9 +-
 src/dtb.cpp                                   |   1 +
 src/full-merkle-tree.cpp                      | 149 ----
 src/full-merkle-tree.h                        | 137 ---
 ...erkle-tree-hash.cpp => hash-tree-hash.cpp} |  29 +-
 src/hash-tree-proof.h                         |   7 +-
 src/hash-tree.cpp                             |  61 +-
 src/hash-tree.h                               |  16 +-
 src/host-addr.h                               |   2 +
 src/hot-tlb.h                                 |   1 -
 src/htif-address-range.cpp                    |   1 +
 src/htif-address-range.h                      |   2 +
 src/htif-constants.h                          |   6 -
 src/htif-defines.h                            |   6 +
 src/i-accept-counters.h                       |   2 +
 src/i-accept-scoped-notes.h                   |   8 +-
 src/i-dense-hash-tree.h                       |   5 +-
 src/i-dirty-page-tree.h                       |   9 +-
 src/i-hasher.h                                |   5 +
 src/i-interactive-state-access.h              |   2 +
 src/i-machine.h                               |  33 +-
 src/i-prefer-shadow-state.h                   |   3 +-
 src/i-prefer-shadow-uarch-state.h             |   3 +-
 src/i-state-access.h                          |  11 +-
 src/i-uarch-state-access.h                    |   4 +-
 src/interpret.cpp                             |  32 +-
 src/is-pristine.cpp                           |   1 -
 src/is-pristine.h                             |   3 -
 src/json-util.cpp                             |  56 +-
 src/json-util.h                               |  31 +-
 src/jsonrpc-discover.json                     |  27 +
 src/jsonrpc-machine-c-api.cpp                 |   4 -
 src/jsonrpc-machine.cpp                       |  35 +-
 src/jsonrpc-machine.h                         |  18 +-
 src/jsonrpc-remote-machine.cpp                |  35 +-
 src/keccak-256-hasher.cpp                     |  14 +-
 src/keccak-256-hasher.h                       |   5 +-
 src/local-machine.cpp                         |  22 +-
 src/local-machine.h                           |  16 +-
 src/machine-address-ranges.cpp                |   7 +-
 src/machine-address-ranges.h                  |   5 +-
 src/machine-c-api.cpp                         |  22 +-
 src/machine-c-api.h                           |  49 +-
 src/machine-config.cpp                        |   6 +-
 src/machine-config.h                          |   2 -
 src/machine-hash.h                            |   1 +
 src/machine-reg.h                             |   2 +
 src/machine.cpp                               | 398 ++++++---
 src/machine.h                                 |  37 +-
 src/mcycle-root-hashes.h                      |   9 +-
 src/memory-address-range.cpp                  |  18 +-
 src/memory-address-range.h                    |   7 +-
 src/mock-address-range.h                      |   6 +-
 src/os-filesystem.cpp                         |   4 +-
 src/os-filesystem.h                           |   1 -
 src/os-mmap.cpp                               |   6 +-
 src/os-mmap.h                                 |   3 +-
 src/os-posix-compat.h                         |   2 +-
 src/os.cpp                                    |  16 +-
 src/page-hash-tree-cache.h                    |  19 +-
 src/plic-address-range.cpp                    |   4 +-
 src/plic-address-range.h                      |   4 +-
 src/pmas-defines.h                            |   1 +
 src/pristine-merkle-tree.cpp                  |  61 --
 src/pristine-merkle-tree.h                    |  53 --
 src/processor-state.h                         |   5 +-
 src/record-send-cmio-state-access.h           |  27 +-
 src/record-step-state-access.h                |  20 +-
 src/replay-send-cmio-state-access.h           |  16 +-
 src/replay-step-state-access-interop.cpp      |   4 +-
 src/replay-step-state-access-interop.h        |   1 +
 src/replay-step-state-access.h                |  15 +-
 src/riscv-constants.h                         |   1 -
 src/scope-exit.h                              |   2 +-
 src/scope-remove.h                            |   4 +-
 src/send-cmio-response.cpp                    |  11 +-
 src/sha-256-hasher.cpp                        |  12 +-
 src/sha-256-hasher.h                          |   5 +-
 src/shadow-registers.h                        |   4 +-
 src/shadow-tlb.h                              |   3 +-
 src/shadow-uarch-state.h                      |   2 +-
 src/simd-hasher.h                             |   3 +-
 src/simd-vector-type.h                        |   2 +-
 src/soft-float.h                              |   2 +-
 src/state-access.h                            |   7 +-
 src/strict-aliasing.h                         |   4 -
 src/test-collect-hashes.lua                   |  46 +-
 src/translate-virtual-address.h               |   2 +-
 src/uarch-constants.h                         |  18 +-
 src/uarch-cycle-root-hashes.h                 |   1 +
 src/uarch-interpret.cpp                       |   4 +-
 src/uarch-processor-state.h                   |   4 -
 src/uarch-record-state-access.h               |  36 +-
 src/uarch-replay-state-access.h               |  18 +-
 src/uarch-reset-state.cpp                     |   6 +-
 src/uarch-solidity-compat.h                   |   6 -
 src/uarch-state-access.h                      |   8 +-
 src/uarch-step.cpp                            |  14 +-
 src/unique-c-ptr.h                            |   2 -
 src/variant-hasher.h                          |   7 +
 src/virtio-address-range.cpp                  |   3 +-
 src/virtio-address-range.h                    |   5 +-
 src/virtio-console-address-range.cpp          |   1 +
 src/virtio-console-address-range.h            |   2 +
 src/virtio-net-address-range.cpp              |   4 +-
 src/virtio-net-address-range.h                |   1 -
 src/virtio-net-tuntap-address-range.cpp       |   2 +
 src/virtio-net-tuntap-address-range.h         |   1 +
 src/virtio-net-user-address-range.cpp         |   6 +-
 src/virtio-net-user-address-range.h           |   3 +-
 src/virtio-p9fs-address-range.cpp             |   2 +-
 tests/Makefile                                |   8 +-
 tests/lua/cartesi/tabular.lua                 |  13 +
 tests/lua/spec-collect-hashes.lua             | 840 ++++++++++++++----
 tests/misc/.gitignore                         |   1 -
 tests/misc/Makefile                           |  15 +-
 tests/misc/test-machine-c-api.cpp             |   5 +-
 tests/misc/test-merkle-tree-hash.cpp          | 313 -------
 tests/misc/test-utils.h                       |  25 +-
 uarch/Makefile                                |   7 +-
 uarch/compute-uarch-pristine-hash.cpp         |   5 +-
 uarch/machine-uarch-bridge-state-access.h     |   6 +-
 uarch/uarch-ecall.c                           |   2 -
 uarch/uarch-run.cpp                           |   6 +-
 uarch/uarch-runtime.cpp                       |   5 +-
 uarch/uarch-runtime.h                         |  20 +-
 uarch/uarch-strict-aliasing.h                 |   3 +-
 154 files changed, 2080 insertions(+), 2012 deletions(-)
 delete mode 100644 src/complete-merkle-tree.cpp
 delete mode 100644 src/complete-merkle-tree.h
 delete mode 100644 src/full-merkle-tree.cpp
 delete mode 100644 src/full-merkle-tree.h
 rename src/{merkle-tree-hash.cpp => hash-tree-hash.cpp} (89%)
 delete mode 100644 src/pristine-merkle-tree.cpp
 delete mode 100644 src/pristine-merkle-tree.h
 delete mode 100644 tests/misc/test-merkle-tree-hash.cpp

diff --git a/.clang-tidy b/.clang-tidy
index f676fd523..71ed74611 100644
--- a/.clang-tidy
+++ b/.clang-tidy
@@ -1,13 +1,10 @@
 Checks: >-
   boost*,
-  -boost-use-ranges,
   bugprone*,
   -bugprone-easily-swappable-parameters,
-  -bugprone-crtp-constructor-accessibility,
   cert*,
   -cert-int09-c,
   clang-analyzer*,
-  -clang-analyzer-optin.cplusplus.VirtualCall,
   cppcoreguidelines*,
   -cppcoreguidelines-avoid-magic-numbers,
   -cppcoreguidelines-owning-memory,
@@ -33,8 +30,6 @@ Checks: >-
   -modernize-use-nodiscard,
   -modernize-use-trailing-return-type,
   -modernize-avoid-c-arrays,
-  -modernize-use-ranges,
-  -modernize-use-integer-sign-comparison,
   performance*,
   -performance-enum-size,
   portability*,
@@ -43,6 +38,5 @@ Checks: >-
   -readability-identifier-length,
   -readability-magic-numbers,
   -readability-enum-initial-value,
-  -readability-static-accessed-through-instance,
 WarningsAsErrors: >-
   *
diff --git a/.dockerignore b/.dockerignore
index 53b9d887b..d39f81a13 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -13,7 +13,7 @@
 build
 third-party/downloads
 src/cartesi-jsonrpc-machine
-src/cartesi-merkle-tree-hash
+src/cartesi-hash-tree-hash
 
 doc/html
 doc/api.md
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 1b6fae0a7..95abae7ed 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -209,11 +209,6 @@ jobs:
         run: |
           docker run --rm -t -v cmio-templates:/tmp/cartesi-machine/tests/data cartesi/machine-emulator:tests /usr/share/cartesi-machine/tests/scripts/test-cmio.sh cartesi-jsonrpc-machine cartesi-machine lua
 
-      - name: Run Merkle tree tests
-        run: |
-          docker run --rm -t ${{ github.repository_owner }}/machine-emulator:tests test-merkle-tree-hash --log2-root-size=30 --log2-leaf-size=12 --input=/usr/bin/test-merkle-tree-hash --hash-function=keccak256
-          docker run --rm -t ${{ github.repository_owner }}/machine-emulator:tests test-merkle-tree-hash --log2-root-size=30 --log2-leaf-size=12 --input=/usr/bin/test-merkle-tree-hash --hash-function=sha256
-
       - name: Run C API tests
         run: |
           docker run --rm -t ${{ github.repository_owner }}/machine-emulator:tests test-machine-c-api
@@ -378,11 +373,6 @@ jobs:
         run: |
           docker run --platform linux/arm64 --rm -t -v cmio-templates:/tmp/cartesi-machine/tests/data cartesi/machine-emulator:tests /usr/share/cartesi-machine/tests/scripts/test-cmio.sh cartesi-jsonrpc-machine cartesi-machine lua
 
-      - name: Run Merkle tree tests
-        run: |
-          docker run --platform linux/arm64 --rm -t ${{ github.repository_owner }}/machine-emulator:tests test-merkle-tree-hash --log2-root-size=30 --log2-leaf-size=12 --input=/usr/bin/test-merkle-tree-hash --hash-function=keccak256
-          docker run --platform linux/arm64 --rm -t ${{ github.repository_owner }}/machine-emulator:tests test-merkle-tree-hash --log2-root-size=30 --log2-leaf-size=12 --input=/usr/bin/test-merkle-tree-hash --hash-function=sha256
-
       - name: Run C API tests
         run: |
           docker run --platform linux/arm64 --rm -t ${{ github.repository_owner }}/machine-emulator:tests test-machine-c-api
@@ -554,7 +544,7 @@ jobs:
 
       - name: Run coverage
         run: |
-          docker run --name coverage-report -t ${{ github.repository_owner }}/machine-emulator:coverage make -j1 test-save-and-load test-machine test-hash test-lua test-jsonrpc test-c-api coverage-machine test-uarch-rv64ui test-uarch-interpreter coverage-uarch coverage-report coverage=yes
+          docker run --name coverage-report -t ${{ github.repository_owner }}/machine-emulator:coverage make -j1 test-save-and-load test-machine test-lua test-jsonrpc test-c-api coverage-machine test-uarch-rv64ui test-uarch-interpreter coverage-uarch coverage-report coverage=yes
           docker cp coverage-report:/usr/src/emulator/tests/build/coverage .
           docker rm coverage-report
 
diff --git a/.gitignore b/.gitignore
index f77446c75..6d5078aa6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,9 +13,8 @@ build
 pkg
 third-party/downloads
 src/cartesi-jsonrpc-machine
-src/cartesi-merkle-tree-hash
+src/cartesi-hash-tree-hash
 src/tests/test-machine-c-api
-src/tests/test-merkle-tree-hash
 
 doc/html
 doc/api.md
diff --git a/Makefile b/Makefile
index 8404e5596..3ec08cf1d 100644
--- a/Makefile
+++ b/Makefile
@@ -73,7 +73,7 @@ INSTALL_DIR= cp -RP
 SYMLINK= ln -sf
 CHMOD_EXEC= chmod 0755
 
-EMU_TO_BIN= src/cartesi-jsonrpc-machine src/cartesi-merkle-tree-hash
+EMU_TO_BIN= src/cartesi-jsonrpc-machine src/cartesi-hash-tree-hash
 EMU_TO_LIB= src/$(LIBCARTESI_SO) src/$(LIBCARTESI_SO_JSONRPC)
 EMU_TO_LIB_A= src/libcartesi.a src/libcartesi_jsonrpc.a src/libluacartesi.a src/libluacartesi_jsonrpc.a
 EMU_LUA_TO_BIN= src/cartesi-machine.lua src/cartesi-machine-stored-hash.lua
@@ -83,7 +83,7 @@ EMU_TO_LUA_CARTESI_CPATH= src/cartesi/jsonrpc.so
 EMU_TO_INC= $(addprefix src/,jsonrpc-machine-c-api.h machine-c-api.h machine-c-version.h)
 UARCH_TO_SHARE= uarch-ram.bin
 
-TESTS_TO_BIN= tests/build/misc/test-merkle-tree-hash tests/build/misc/test-machine-c-api
+TESTS_TO_BIN= tests/build/misc/test-machine-c-api
 TESTS_LUA_TO_LUA_PATH=tests/lua/cartesi
 TESTS_LUA_TO_TEST_LUA_PATH=$(wildcard tests/lua/*.lua)
 TESTS_SCRIPTS_TO_TEST_SCRIPTS_PATH=$(wildcard tests/scripts/*.sh)
diff --git a/src/Makefile b/src/Makefile
index 110d3e5e8..90dc98c88 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -97,7 +97,7 @@ endif
 
 SO_EXT=dylib
 LIBCARTESI_LDFLAGS=-install_name '@rpath/$(LIBCARTESI)'
-LIBCARTESI_MERKLE_TREE_LDFLAGS=-install_name '@rpath/$(LIBCARTESI_MERKLE_TREE)'
+LIBCARTESI_HASH_TREE_LDFLAGS=-install_name '@rpath/$(LIBCARTESI_HASH_TREE)'
 LIBCARTESI_JSONRPC_LDFLAGS=-install_name '@rpath/$(LIBCARTESI_JSONRPC)' -Wl,-rpath,@loader_path
 LUACARTESI_LDFLAGS=-install_name '@rpath/cartesi.so'
 LUACARTESI_JSONRPC_LDFLAGS=-install_name '@rpath/cartesi/jsonrpc.so' -Wl,-rpath,@loader_path/..
@@ -123,7 +123,7 @@ SLIRP_INC=
 SLIRP_LIB=-lslirp
 SO_EXT=so
 LIBCARTESI_LDFLAGS=
-LIBCARTESI_MERKLE_TREE_LDFLAGS=
+LIBCARTESI_HASH_TREE_LDFLAGS=
 LIBCARTESI_JSONRPC_LDFLAGS=-Wl,-rpath,'$$ORIGIN'
 LUACARTESI_LDFLAGS=
 LUACARTESI_JSONRPC_LDFLAGS=-Wl,-rpath,'$$ORIGIN/..'
@@ -132,7 +132,7 @@ PROFILE_DATA=
 endif
 
 LIBCARTESI=libcartesi-$(EMULATOR_VERSION_MAJOR).$(EMULATOR_VERSION_MINOR).$(SO_EXT)
-LIBCARTESI_MERKLE_TREE=libcartesi_merkle_tree-$(EMULATOR_VERSION_MAJOR).$(EMULATOR_VERSION_MINOR).$(SO_EXT)
+LIBCARTESI_HASH_TREE=libcartesi_hash_tree-$(EMULATOR_VERSION_MAJOR).$(EMULATOR_VERSION_MINOR).$(SO_EXT)
 LIBCARTESI_JSONRPC=libcartesi_jsonrpc-$(EMULATOR_VERSION_MAJOR).$(EMULATOR_VERSION_MINOR).$(SO_EXT)
 
 ifeq ($(slirp),yes)
@@ -148,18 +148,18 @@ DEFS+=-DNO_SLIRP
 endif
 
 LIBCARTESI_LIBS=$(LIBCARTESI_COMMON_LIBS)
-LIBCARTESI_MERKLE_TREE_LIBS=
+LIBCARTESI_HASH_TREE_LIBS=
 LIBCARTESI_JSONRPC_LIBS=
 LUACARTESI_LIBS=$(LIBCARTESI_COMMON_LIBS)
 LUACARTESI_JSONRPC_LIBS=
 CARTESI_JSONRPC_MACHINE_LIBS=$(LIBCARTESI_COMMON_LIBS)
-CARTESI_MERKLE_TREE_HASH_LIBS=
-
-#DEFS+= -DMT_ALL_DIRTY
+CARTESI_HASH_TREE_HASH_LIBS=
 
 C_WARNS=-Wall -Wextra -Wpedantic
-CXX_WARNS=$(C_WARNS) -Wno-missing-field-initializers
-CLANG_TIDY_WARNS=-Wthread-safety -Wglobal-constructors
+# C_WARNS+=-Wshadow -Wconversion -Wsign-conversion -Wsign-promo -Wuseless-cast -Wformat=2
+CXX_WARNS=$(C_WARNS)
+
+CLANG_TIDY_WARNS=-Wthread-safety -Wglobal-constructors -Wundef -Wredundant-decls -Wextra-semi
 
 # Place our include directories before the system's
 INCS+= \
@@ -285,9 +285,7 @@ PGO_WORKLOAD=\
 	whetstone 25000
 
 LINTER_IGNORE_SOURCES=
-LINTER_IGNORE_HEADERS=interpret-jump-table.h
 LINTER_SOURCES=$(filter-out $(LINTER_IGNORE_SOURCES),$(strip $(wildcard *.cpp) $(wildcard *.c)))
-LINTER_HEADERS=$(filter-out $(LINTER_IGNORE_HEADERS),$(strip $(wildcard *.hpp) $(wildcard *.h)))
 
 CLANG_TIDY=clang-tidy
 CLANG_TIDY_TARGETS=$(patsubst %.cpp,%.clang-tidy,$(patsubst %.c,%.clang-tidy,$(LINTER_SOURCES)))
@@ -305,7 +303,6 @@ STYLUA_FLAGS=--indent-type Spaces --collapse-simple-statement Always --respect-i
 
 EMPTY:=
 SPACE:=$(EMPTY) $(EMPTY)
-CLANG_TIDY_HEADER_FILTER=$(CURDIR)/($(subst $(SPACE),|,$(LINTER_HEADERS)))
 
 ifeq ($(threads),yes)
 CFLAGS+=$(PTHREAD_CFLAGS)
@@ -344,15 +341,15 @@ SOLDFLAGS+=$(MYSOLDFLAGS)
 LIBLDFLAGS+=$(MYLIBLDFLAGS)
 EXELDFLAGS+=$(MYEXELDFLAGS)
 
-all: libcartesi libcartesi_merkle_tree libcartesi_jsonrpc c-api luacartesi cartesi-jsonrpc-machine hash
+all: libcartesi libcartesi_hash_tree libcartesi_jsonrpc c-api luacartesi cartesi-jsonrpc-machine hash
 
 luacartesi: libluacartesi.a cartesi.so libluacartesi_jsonrpc.a cartesi/jsonrpc.so
 
 jsonrpc: cartesi/jsonrpc.so cartesi-jsonrpc-machine
 
-hash: cartesi-merkle-tree-hash
+hash: cartesi-hash-tree-hash
 
-c-api: $(LIBCARTESI) $(LIBCARTESI_MERKLE_TREE) $(LIBCARTESI_JSONRPC)
+c-api: $(LIBCARTESI) $(LIBCARTESI_HASH_TREE) $(LIBCARTESI_JSONRPC)
 
 .PHONY: all generate use clean lint format format-lua check-format check-format-lua luacartesi hash c-api compile_flags.txt
 
@@ -373,7 +370,7 @@ LIBCARTESI_OBJS:= \
 	os-mmap.o \
 	os-filesystem.o \
 	plic-address-range.o \
-	pristine-merkle-tree.o \
+	back-merkle-tree.o \
 	replay-step-state-access-interop.o \
 	send-cmio-response.o \
 	keccak-256-hasher.o \
@@ -404,17 +401,14 @@ LUACARTESI_OBJS:= \
 	clua-cartesi.o \
 	$(CARTESI_CLUA_OBJS)
 
-LIBCARTESI_MERKLE_TREE_OBJS:= \
+LIBCARTESI_HASH_TREE_OBJS:= \
 	keccak-256-hasher.o \
 	sha-256-hasher.o \
 	is-pristine.o \
 	back-merkle-tree.o \
-	pristine-merkle-tree.o \
-	complete-merkle-tree.o \
-	full-merkle-tree.o
 
-CARTESI_MERKLE_TREE_HASH_OBJS:= \
-	merkle-tree-hash.o
+CARTESI_HASH_TREE_HASH_OBJS:= \
+	hash-tree-hash.o
 
 LIBCARTESI_JSONRPC_OBJS:= \
 	jsonrpc-machine.o \
@@ -435,7 +429,7 @@ CARTESI_JSONRPC_MACHINE_OBJS:= \
 ifeq ($(gperf),yes)
 DEFS+=-DGPERF
 LIBCARTESI_LIBS+=-lprofiler
-LIBCARTESI_MERKLE_TREE_LIBS+=-lprofiler
+LIBCARTESI_HASH_TREE_LIBS+=-lprofiler
 LIBCARTESI_JSONRPC_LIBS+=-lprofiler
 LUACARTESI_LIBS+=-lprofiler
 LUACARTESI_JSONRPC_LIBS+=-lprofiler
@@ -448,10 +442,10 @@ so-version:
 	@echo $(EMULATOR_VERSION_MAJOR).$(EMULATOR_VERSION_MINOR)
 
 libcartesi: libcartesi.a libcartesi.$(SO_EXT)
-libcartesi.$(SO_EXT): $(LIBCARTESI) $(LIBCARTESI_MERKLE_TREE)
+libcartesi.$(SO_EXT): $(LIBCARTESI) $(LIBCARTESI_HASH_TREE)
 	ln -sf $< $@
-libcartesi_merkle_tree: libcartesi_merkle_tree.a libcartesi_merkle_tree.$(SO_EXT)
-libcartesi_merkle_tree.$(SO_EXT): $(LIBCARTESI_MERKLE_TREE)
+libcartesi_hash_tree: libcartesi_hash_tree.a libcartesi_hash_tree.$(SO_EXT)
+libcartesi_hash_tree.$(SO_EXT): $(LIBCARTESI_HASH_TREE)
 	ln -sf $< $@
 libcartesi_jsonrpc: libcartesi_jsonrpc.a libcartesi_jsonrpc.$(SO_EXT)
 libcartesi_jsonrpc.$(SO_EXT): $(LIBCARTESI_JSONRPC)
@@ -460,7 +454,7 @@ libcartesi_jsonrpc.$(SO_EXT): $(LIBCARTESI_JSONRPC)
 libcartesi.a: $(LIBCARTESI_OBJS)
 	$(AR) $@ $^
 
-libcartesi_merkle_tree.a: $(LIBCARTESI_MERKLE_TREE_OBJS)
+libcartesi_hash_tree.a: $(LIBCARTESI_HASH_TREE_OBJS)
 	$(AR) $@ $^
 
 libcartesi_jsonrpc.a: $(LIBCARTESI_JSONRPC_OBJS)
@@ -472,8 +466,8 @@ libluacartesi.a: $(LUACARTESI_OBJS)
 libluacartesi_jsonrpc.a: $(LUACARTESI_JSONRPC_OBJS)
 	$(AR) $@ $^
 
-$(LIBCARTESI_MERKLE_TREE): $(LIBCARTESI_MERKLE_TREE_OBJS)
-	$(CXX) -o $@ $^ $(LIBCARTESI_MERKLE_TREE_LIBS) $(LDFLAGS) $(LIBCARTESI_MERKLE_TREE_LDFLAGS) $(LIBLDFLAGS)
+$(LIBCARTESI_HASH_TREE): $(LIBCARTESI_HASH_TREE_OBJS)
+	$(CXX) -o $@ $^ $(LIBCARTESI_HASH_TREE_LIBS) $(LDFLAGS) $(LIBCARTESI_HASH_TREE_LDFLAGS) $(LIBLDFLAGS)
 
 $(LIBCARTESI): $(LIBCARTESI_OBJS)
 	$(CXX) -o $@ $^ $(LIBCARTESI_LIBS) $(LDFLAGS) $(LIBCARTESI_LDFLAGS) $(LIBLDFLAGS)
@@ -536,8 +530,8 @@ $(PROFILE_DATA):
 	llvm-profdata merge -output=default.profdata default*.profraw
 endif
 
-cartesi-merkle-tree-hash: $(CARTESI_MERKLE_TREE_HASH_OBJS) libcartesi_merkle_tree.a
-	$(CXX) -o $@ $^ $(CARTESI_MERKLE_TREE_HASH_LIBS) $(LDFLAGS) $(EXELDFLAGS)
+cartesi-hash-tree-hash: $(CARTESI_HASH_TREE_HASH_OBJS) libcartesi_hash_tree.a
+	$(CXX) -o $@ $^ $(CARTESI_HASH_TREE_HASH_LIBS) $(LDFLAGS) $(EXELDFLAGS)
 
 cartesi-jsonrpc-machine: $(CARTESI_JSONRPC_MACHINE_OBJS) libcartesi_jsonrpc.a libcartesi.a
 	$(CXX) -o $@ $^ $(CARTESI_JSONRPC_MACHINE_LIBS) $(LDFLAGS) $(EXELDFLAGS)
@@ -556,12 +550,12 @@ jsonrpc-discover.cpp: jsonrpc-discover.json
 	echo '} // namespace cartesi' >> jsonrpc-discover.cpp
 
 %.clang-tidy: %.cpp machine-c-version.h interpret-jump-table.h
-	@$(CLANG_TIDY) --header-filter='$(CLANG_TIDY_HEADER_FILTER)' $(CLANG_TIDY_FLAGS) $< -- $(CXXFLAGS) $(CLANG_TIDY_WARNS) $(LUA_INC) -DCLANG_TIDY_LINT 2>/dev/null
+	@$(CLANG_TIDY) $(CLANG_TIDY_FLAGS) $< -- $(CXXFLAGS) $(CLANG_TIDY_WARNS) $(LUA_INC) -DCLANG_TIDY_LINT 2>/dev/null
 	@$(CXX) $(CXXFLAGS) $(LUA_INC) $< -MM -MT $@ -MF $@.d > /dev/null 2>&1
 	@touch $@
 
 %.clang-tidy: %.c
-	@$(CLANG_TIDY) --header-filter='$(CLANG_TIDY_HEADER_FILTER)' $(CLANG_TIDY_FLAGS) $< -- $(CFLAGS) $(CLANG_TIDY_WARNS) -DCLANG_TIDY_LINT 2>/dev/null
+	@$(CLANG_TIDY) $(CLANG_TIDY_FLAGS) $< -- $(CFLAGS) $(CLANG_TIDY_WARNS) -DCLANG_TIDY_LINT 2>/dev/null
 	@$(CC) $(CFLAGS) $< -MM -MT $@ -MF $@.d > /dev/null 2>&1
 	@touch $@
 
@@ -619,7 +613,7 @@ clean-libcartesi: clean-objs
 	@rm -f *.so *.a cartesi/*.so *.dylib
 
 clean-executables:
-	@rm -f cartesi-jsonrpc-machine cartesi-merkle-tree-hash compute-uarch-pristine-hash
+	@rm -f cartesi-jsonrpc-machine cartesi-hash-tree-hash compute-uarch-pristine-hash
 
 clean-coverage:
 	@rm -f *.profdata *.profraw *.gcda *.gcov coverage.info coverage.txt
diff --git a/src/access-log.h b/src/access-log.h
index 26cbcb5ad..0c1b126b8 100644
--- a/src/access-log.h
+++ b/src/access-log.h
@@ -21,9 +21,7 @@
 /// \brief State access log implementation
 
 #include <algorithm>
-#include <cassert>
 #include <cstdint>
-#include <cstring>
 #include <optional>
 #include <stdexcept>
 #include <string>
@@ -32,7 +30,9 @@
 
 #include <boost/container/small_vector.hpp>
 
+#include "assert-printf.h"
 #include "bracket-note.h"
+#include "hash-tree-constants.h"
 #include "hash-tree.h"
 #include "machine-c-api.h"
 #include "machine-hash.h"
@@ -173,10 +173,10 @@ class access {
     /// \param root_hash Hash to be used as the root of the proof.
     /// \return The corresponding proof
     proof_type make_proof(const machine_hash root_hash) const {
-        // the access can be of data smaller than the merkle tree word size
-        // however, the proof must be at least as big as the merkle tree word size
+        // the access can be of data smaller than the hash tree word size
+        // however, the proof must be at least as big as the hash tree word size
         const int proof_log2_size = std::max(m_log2_size, HASH_TREE_LOG2_WORD_SIZE);
-        // the proof address is the access address aligned to the merkle tree word size
+        // the proof address is the access address aligned to the hash tree word size
         const uint64_t proof_address = m_address & ~(HASH_TREE_WORD_SIZE - 1);
         if (!m_sibling_hashes.has_value()) {
             throw std::runtime_error("can't make proof if access doesn't have sibling hashes");
diff --git a/src/address-range-defines.h b/src/address-range-defines.h
index 4bf43c51b..13e8d2577 100644
--- a/src/address-range-defines.h
+++ b/src/address-range-defines.h
@@ -56,5 +56,6 @@
 #ifndef EXPAND_UINT64_C
 #define EXPAND_UINT64_C(a) UINT64_C(a)
 #endif
+
 // NOLINTEND(cppcoreguidelines-macro-usage,cppcoreguidelines-macro-to-enum,modernize-macro-to-enum)
 #endif /* end of include guard: AR_DEFINES_H */
diff --git a/src/address-range.h b/src/address-range.h
index 8525fb7ae..3d3912acc 100644
--- a/src/address-range.h
+++ b/src/address-range.h
@@ -17,6 +17,7 @@
 #ifndef ADDRESS_RANGE_H
 #define ADDRESS_RANGE_H
 
+#include <algorithm>
 #include <array>
 #include <bit>
 #include <cinttypes>
@@ -24,9 +25,11 @@
 #include <tuple>
 #include <utility>
 
+#include "address-range-constants.h"
 #include "assert-printf.h"
 #include "i-device-state-access.h"
 #include "interpret.h"
+#include "pmas-constants.h"
 #include "pmas.h"
 
 #ifndef MICROARCHITECTURE
@@ -63,7 +66,7 @@ class address_range {
     }
 
     // NOLINTNEXTLINE(hicpp-use-equals-default,modernize-use-equals-default)
-    constexpr virtual ~address_range() {}; // = default; // doesn't work due to bug in gcc
+    constexpr virtual ~address_range() {} // = default; // doesn't work due to bug in gcc
 
     template <typename ABRT, size_t N, typename... ARGS>
     [[noreturn]]
@@ -399,4 +402,4 @@ static inline auto make_address_range(const char *description, uint64_t start, u
 
 } // namespace cartesi
 
-#endif // OCCUPIED_ADDRESS_RANGE_H
+#endif // ADDRESS_RANGE_H
diff --git a/src/algorithm.h b/src/algorithm.h
index e0732ea4d..60b7ccd0f 100644
--- a/src/algorithm.h
+++ b/src/algorithm.h
@@ -17,21 +17,42 @@
 #ifndef ALGORITHM_H
 #define ALGORITHM_H
 
+#include <concepts>
+#include <limits>
+#include <type_traits>
+
 #include "concepts.h"
 
-namespace cartesi::algorithm {
+namespace cartesi {
 
 /// \brief Adds new entry to back of container, if not already there
-/// \param value Value to insert.
-template <BackInsertableContainer Container, typename T>
-    requires std::constructible_from<typename Container::value_type, T &&> &&
-    std::equality_comparable_with<typename Container::value_type, T>
+/// \tparam Container Container type
+/// \tparam T Value type
+/// \param container Container to push back into
+/// \param value Value to push back
+template <typename Container, typename T>
+    requires BackInsertableWith<Container, T>
 constexpr void try_push_back(Container &container, T &&value) {
     if (container.empty() || container.back() != value) {
         container.push_back(std::forward<T>(value));
     }
 }
 
-} // namespace cartesi::algorithm
+/// \brief Performs saturating addition of two unsigned integers
+/// \tparam T Unsigned integer type
+/// \param a First addend
+/// \param b Second addend
+/// \param max Maximum value of T (default: std::numeric_limits<T>::max())
+/// \returns The sum of a and b, or the maximum value of T if overflow occurs
+template <typename T>
+    requires std::is_unsigned_v<T>
+static constexpr T saturating_add(T a, T b, T max = std::numeric_limits<T>::max()) noexcept {
+    if (b > max || a > max - b) [[unlikely]] {
+        return max;
+    }
+    return a + b;
+}
+
+} // namespace cartesi
 
 #endif
diff --git a/src/assert-printf.h b/src/assert-printf.h
index 015e17997..1bf7bb85b 100644
--- a/src/assert-printf.h
+++ b/src/assert-printf.h
@@ -21,12 +21,13 @@
 /// \brief Microarchitecture-dependent includes for printf and assert
 
 #ifdef MICROARCHITECTURE
-#include "uarch-runtime.h"
+#include "../uarch/uarch-runtime.h" // IWYU pragma: export
 #else
-#include <cassert>
-#include <cstdio>
+#include <cassert> // IWYU pragma: export
+#include <cstdio>  // IWYU pragma: export
 #endif
 
+#include <cinttypes> // IWYU pragma: export
 #include <cstdarg>
 #include <tuple>
 
diff --git a/src/back-merkle-tree.cpp b/src/back-merkle-tree.cpp
index ab081aa7f..1c3c36e6d 100644
--- a/src/back-merkle-tree.cpp
+++ b/src/back-merkle-tree.cpp
@@ -15,28 +15,23 @@
 //
 
 /// \file
-/// \brief Back Merkle tree implementation.
+/// \brief Back merkle tree implementation.
 
 #include "back-merkle-tree.h"
 
-#include <algorithm>
 #include <cassert>
+#include <cstddef>
 #include <cstdint>
 #include <limits>
 #include <stdexcept>
+#include <vector>
 
-#include "i-hasher.h"
+#include "machine-hash.h"
+#include "variant-hasher.h"
 
 namespace cartesi {
 
-back_merkle_tree::back_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size,
-    hash_function_type hash_function) :
-    m_log2_root_size{log2_root_size},
-    m_log2_leaf_size{log2_leaf_size},
-    m_max_leaves{UINT64_C(1) << (log2_root_size - log2_leaf_size)},
-    m_context(std::max(1, log2_root_size - log2_leaf_size + 1)),
-    m_pristine_hashes{log2_root_size, log2_word_size, hash_function},
-    m_hash_function(hash_function) {
+int back_merkle_tree::validate_log2_max_leaves_size(int log2_root_size, int log2_leaf_size, int log2_word_size) {
     if (log2_root_size < 0) {
         throw std::out_of_range{"log2_root_size is negative"};
     }
@@ -50,24 +45,26 @@ back_merkle_tree::back_merkle_tree(int log2_root_size, int log2_leaf_size, int l
         throw std::out_of_range{"log2_leaf_size is greater than log2_root_size"};
     }
     if (log2_word_size > log2_leaf_size) {
-        throw std::out_of_range{"log2_word_size is greater than log2_word_size"};
+        throw std::out_of_range{"log2_word_size is greater than log2_leaf_size"};
     }
-    if (log2_root_size - m_log2_leaf_size >= std::numeric_limits<uint64_t>::digits) {
-        throw std::out_of_range{"tree is too large for address type"};
+    if (log2_root_size - log2_leaf_size >= std::numeric_limits<uint64_t>::digits) {
+        throw std::out_of_range{"log2_root_size is too large"};
     }
+    return log2_root_size - log2_leaf_size;
 }
 
 void back_merkle_tree::push_back(const machine_hash &new_leaf_hash) {
     variant_hasher h{m_hash_function};
     machine_hash right = new_leaf_hash;
-    if (m_leaf_count >= m_max_leaves) {
+    if (m_leaf_count >= get_max_leaves()) {
         throw std::out_of_range{"too many leaves"};
     }
-    const int depth = m_log2_root_size - m_log2_leaf_size;
-    for (int i = 0; i <= depth; ++i) {
-        if ((m_leaf_count & (UINT64_C(1) << i)) != 0) {
+    const size_t log2_max_leaves = get_log2_max_leaves();
+    for (size_t i = 0; i <= log2_max_leaves; ++i) {
+        const auto i_span = UINT64_C(1) << i;
+        if ((m_leaf_count & i_span) != 0) {
             const auto &left = m_context[i];
-            get_concat_hash(h, left, right, right);
+            h.concat_hash(left, right, right);
         } else {
             m_context[i] = right;
             break;
@@ -76,99 +73,101 @@ void back_merkle_tree::push_back(const machine_hash &new_leaf_hash) {
     ++m_leaf_count;
 }
 
-void back_merkle_tree::pad_back(uint64_t new_leaf_count) {
-    variant_hasher h{m_hash_function};
-    if (new_leaf_count > m_max_leaves || m_leaf_count + new_leaf_count > m_max_leaves) {
-        throw std::invalid_argument("too many leaves");
+void back_merkle_tree::pad_back(uint64_t new_leaf_count, const machine_hashes &pad_hashes) {
+    if (new_leaf_count == 0) {
+        return;
+    }
+    const size_t max_leaves = get_max_leaves();
+    const size_t log2_max_leaves = get_log2_max_leaves();
+
+    // Validate inputs
+    if (new_leaf_count > max_leaves || m_leaf_count + new_leaf_count > max_leaves) {
+        throw std::invalid_argument{"too many leaves"};
     }
-    const int depth = m_log2_root_size - m_log2_leaf_size;
-    int j = 0;
-    while (j <= depth) {
+    if (pad_hashes.size() != log2_max_leaves + 1) {
+        throw std::invalid_argument{"pad hashes does not have expected size"};
+    }
+
+    variant_hasher h{m_hash_function};
+
+    // Process each bit position from LSB to MSB
+    for (size_t j = 0; j <= log2_max_leaves;) {
         const uint64_t j_span = UINT64_C(1) << j;
+
+        // Skip if this bit isn't set in new_leaf_count
         if (j_span > new_leaf_count) {
             break;
         }
-        // is our smallest tree at depth j?
-        if ((m_leaf_count & j_span) != 0) {
-            // if so, we can add 2^j pristine leaves directly
-            auto right = m_pristine_hashes.get_hash(m_log2_leaf_size + j);
-            for (int i = j; i <= depth; ++i) {
+
+        // Check if we have an existing subtree at this position
+        if ((m_leaf_count & j_span) != 0) { // Is our smallest tree at depth j?
+            // Combine existing subtree with padding and propagate upward
+            auto right = pad_hashes[j];
+            for (size_t i = j; i <= log2_max_leaves; ++i) {
                 const uint64_t i_span = UINT64_C(1) << i;
                 if ((m_leaf_count & i_span) != 0) {
                     const auto &left = m_context[i];
-                    get_concat_hash(h, left, right, right);
+                    h.concat_hash(left, right, right);
                 } else {
                     m_context[i] = right;
-                    // outer loop continues where we left off
+                    // Outer loop continues where we left off
                     j = i;
                     break;
                 }
             }
-            new_leaf_count = new_leaf_count - j_span;
-            m_leaf_count = m_leaf_count + j_span;
+            m_leaf_count += j_span;
+            new_leaf_count -= j_span;
         } else {
             ++j;
         }
     }
-    // now add the rest of the padding directly to the context
-    for (int i = 0; i <= depth; ++i) {
+
+    // Add the rest of the padding directly to the context
+    for (size_t i = 0; i <= log2_max_leaves && new_leaf_count > 0; ++i) {
         const uint64_t i_span = UINT64_C(1) << i;
+        // Check if we have to set the subtree at this position
         if ((new_leaf_count & i_span) != 0) {
-            m_context[i] = m_pristine_hashes.get_hash(m_log2_leaf_size + i);
-            new_leaf_count = new_leaf_count - i_span;
-            m_leaf_count = m_leaf_count + i_span;
+            m_context[i] = pad_hashes[i];
+            m_leaf_count += i_span;
+            new_leaf_count -= i_span;
         }
     }
+
+    assert(new_leaf_count == 0);
+    assert(m_leaf_count <= get_max_leaves());
 }
 
-machine_hash back_merkle_tree::get_root_hash() const {
-    variant_hasher h{m_hash_function};
-    assert(m_leaf_count <= m_max_leaves);
-    const int depth = m_log2_root_size - m_log2_leaf_size;
-    if (m_leaf_count < m_max_leaves) {
-        auto root = m_pristine_hashes.get_hash(m_log2_leaf_size);
-        for (int i = 0; i < depth; ++i) {
-            if ((m_leaf_count & (UINT64_C(1) << i)) != 0) {
-                const auto &left = m_context[i];
-                get_concat_hash(h, left, root, root);
-            } else {
-                const auto &right = m_pristine_hashes.get_hash(m_log2_leaf_size + i);
-                get_concat_hash(h, root, right, root);
-            }
-        }
-        return root;
+machine_hashes back_merkle_tree::make_pad_hashes(const machine_hash &leaf_hash, int log2_max_leaves,
+    hash_function_type hash_function) {
+    assert(log2_max_leaves >= 0);
+    machine_hashes hashes;
+    hashes.resize(log2_max_leaves + 1);
+    hashes[0] = leaf_hash;
+    variant_hasher h{hash_function};
+    for (size_t i = 1; i < hashes.size(); ++i) {
+        h.concat_hash(hashes[i - 1], hashes[i - 1], hashes[i]);
     }
-    return m_context[depth];
+    return hashes;
 }
 
-back_merkle_tree::proof_type back_merkle_tree::get_next_leaf_proof() const {
-    const int depth = m_log2_root_size - m_log2_leaf_size;
-    if (m_leaf_count >= m_max_leaves) {
-        throw std::out_of_range{"tree is full"};
-    }
-    variant_hasher h{m_hash_function};
-    proof_type proof{m_log2_root_size, m_log2_leaf_size};
-    proof.set_target_address(m_leaf_count << m_log2_leaf_size);
-    proof.set_target_hash(m_pristine_hashes.get_hash(m_log2_leaf_size));
-    machine_hash hash = m_pristine_hashes.get_hash(m_log2_leaf_size);
-    for (int i = 0; i < depth; ++i) {
-        if ((m_leaf_count & (UINT64_C(1) << i)) != 0) {
-            const auto &left = m_context[i];
-            proof.set_sibling_hash(left, m_log2_leaf_size + i);
-            get_concat_hash(h, left, hash, hash);
-        } else {
-            const auto &right = m_pristine_hashes.get_hash(m_log2_leaf_size + i);
-            proof.set_sibling_hash(right, m_log2_leaf_size + i);
-            get_concat_hash(h, hash, right, hash);
-        }
-    }
-    proof.set_root_hash(hash);
-#ifndef NDEBUG
-    if (!proof.verify(h)) {
-        throw std::runtime_error{"produced invalid proof"};
+static machine_hash get_pristine_word_hash(int log2_word_size, hash_function_type hash_function) {
+    std::vector<uint8_t> word(UINT64_C(1) << log2_word_size, 0);
+    machine_hash hash{};
+    variant_hasher h{hash_function};
+    h.hash(word, hash);
+    return hash;
+}
+
+machine_hashes back_merkle_tree::make_pristine_pad_hashes(int log2_root_size, int log2_leaf_size, int log2_word_size,
+    hash_function_type hash_function) {
+    validate_log2_max_leaves_size(log2_root_size, log2_leaf_size, log2_word_size);
+    auto pristine_pad_hashes = make_pad_hashes(get_pristine_word_hash(log2_word_size, hash_function),
+        log2_root_size - log2_word_size, hash_function);
+    if (log2_leaf_size > log2_word_size) {
+        pristine_pad_hashes.erase(pristine_pad_hashes.begin(),
+            pristine_pad_hashes.begin() + (log2_leaf_size - log2_word_size));
     }
-#endif
-    return proof;
+    return pristine_pad_hashes;
 }
 
 } // namespace cartesi
diff --git a/src/back-merkle-tree.h b/src/back-merkle-tree.h
index 3543bc5c2..28b0c1763 100644
--- a/src/back-merkle-tree.h
+++ b/src/back-merkle-tree.h
@@ -17,106 +17,191 @@
 #ifndef BACK_MERKLE_TREE_H
 #define BACK_MERKLE_TREE_H
 
+#include <algorithm>
 #include <cstdint>
-#include <vector>
+#include <limits>
+#include <stdexcept>
+#include <utility>
 
-#include "hash-tree-proof.h"
 #include "machine-hash.h"
-#include "pristine-merkle-tree.h"
 #include "variant-hasher.h"
 
 /// \file
-/// \brief Back Merkle tree interface.
+/// \brief Back back_hash_tree tree interface.
 
 namespace cartesi {
 
-/// \brief Incremental way of maintaining a Merkle tree for a stream of
-/// leaf hashes
-/// \details This is surprisingly efficient in both time and space.
-/// Adding the next leaf takes O(log(n)) in the worst case, but is
-/// this is amortized to O(1) time when adding n leaves.
-/// Obtaining the proof for the current leaf takes theta(log(n)) time.
-/// Computing the tree root hash also takes theta(log(n)) time.
-/// The class only ever stores log(n) hashes (1 for each tree level).
+/// \brief Incremental hash tree that efficiently maintains hashes for a stream of leaves
+/// \details Space-efficient design stores only O(log n) hashes (one per tree level).
+/// Leaf insertion is O(log n) worst-case but amortizes to O(1) over n operations.
 class back_merkle_tree {
 public:
-    /// \brief Storage for the proof of a word value.
-    using proof_type = hash_tree_proof;
-
-    /// \brief Constructor
-    /// \param log2_root_size Log<sub>2</sub> of root node
-    /// \param log2_leaf_size Log<sub>2</sub> of leaf node
-    /// \param log2_word_size Log<sub>2</sub> of word node
-    back_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size, hash_function_type hash_function);
+    /// \brief Constructor from an existing leaves context
+    /// \param log2_max_leaves Log base 2 of maximum amount of leaves
+    /// \param hash_function Hash function to use
+    /// \param leaf_count Amount of leaves already added to the tree
+    /// \param context Context representing the leaves hashes
+    back_merkle_tree(int log2_max_leaves, hash_function_type hash_function, uint64_t leaf_count = 0,
+        machine_hashes context = {}) :
+        m_hash_function(hash_function),
+        m_leaf_count{leaf_count},
+        m_context(std::max(1, log2_max_leaves + 1)) {
+        if (log2_max_leaves < 0) {
+            throw std::out_of_range{"log2_max_leaves is negative"};
+        }
+        if (log2_max_leaves >= std::numeric_limits<uint64_t>::digits) {
+            throw std::out_of_range{"log2_max_leaves is too large"};
+        }
+        if (leaf_count >= get_max_leaves()) {
+            throw std::out_of_range{"leaf count is greater than or equal to max leaves"};
+        }
+        // Unpack context
+        size_t j = 0;
+        if (leaf_count > 0) {
+            for (int i = 0; i <= log2_max_leaves; ++i) {
+                const auto i_span = UINT64_C(1) << i;
+                if ((leaf_count & i_span) != 0) {
+                    if (j >= context.size()) {
+                        throw std::out_of_range{"leaves context is incompatible"};
+                    }
+                    m_context[i] = context[j++];
+                }
+            }
+        }
+        if (j != context.size()) {
+            throw std::out_of_range{"leaves context is incompatible"};
+        }
+    }
+    /// \brief Constructor from known root, leaf and word sizes
+    /// \param log2_root_size Log base 2 of root node
+    /// \param log2_leaf_size Log base 2 of leaf node
+    /// \param log2_word_size Log base 2 of word node
+    /// \param hash_function Hash function to use
+    back_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size, hash_function_type hash_function) :
+        back_merkle_tree(validate_log2_max_leaves_size(log2_root_size, log2_leaf_size, log2_word_size), hash_function) {
+    }
 
     /// \brief Appends a new hash to the tree
     /// \param new_leaf_hash Hash of new leaf data
     /// \details
-    /// Consider the tree down to the leaf level.
-    /// The tree is only complete after 2^(log2_root_size-log2_leaf_size) leaves have been added.
-    /// Before that, when leaf_count leaves have been added, we assume the rest of the leaves are
-    /// filled with zeros (i.e., they are pristine).
-    /// The trick is that we do not need to store the hashes of all leaf_count leaves already added to the stream.
-    /// This is because, whenever a subtree is complete, all we need is its root hash.
-    /// The complete subtrees are disjoint, abutting, and appear in decreasing size.
-    /// In fact, there is exactly one complete subtree for each bit set in leaf_count.
-    /// We only need log2_root_size-log2_leaf_size+1 bits to represent leaf_count.
-    /// So our context is a vector with log2_root_size-log2_leaf_size+1 entries, where entry i contains
-    /// the hash for a complete subtree of size 2^i leaves.
-    /// We will only use the entries i if the corresponding bit is set in leaf_count.
-    /// Adding a new leaf hash exactly like adding 1 to leaf_count.
-    /// We scan from least to most significant bit in leaf_count.
-    /// We start with the right = leaf_hash and i = 0.
-    /// If the bit i is set in leaf_count, we replace context[i] = hash(context[i], right) and move up a bit.
-    /// If the bit is not set, we simply store context[i] = right and break.
-    /// In other words, we can update the context in log time (log2_root_size-log2_leaf_size)
+    /// The algorithm efficiently maintains only the root hashes of complete subtrees.
+    /// Each bit set in leaf_count corresponds to a complete subtree of size 2^i,
+    /// with its hash stored in context[i].
+    ///
+    /// Adding a leaf is equivalent to binary addition: scan bits from LSB to MSB.
+    /// For each set bit i in leaf_count, combine context[i] with the new hash
+    /// and propagate upward. Store the result at the first unset bit position.
+    /// This achieves O(log n) worst-case, O(1) amortized time complexity.
     void push_back(const machine_hash &new_leaf_hash);
 
     /// \brief Appends a number of padding hashes to the tree
-    /// \param leaf_count Number of padding hashes to append
+    /// \param new_leaf_count Number of padding hashes to append
+    /// \param pad_hashes Array containing the padding hashes
     /// \details
-    /// Recall that a bit i set in leaf_count represents a complete subtree
-    /// of size 2^i for which we have a hash in context[i].
-    /// The remaining entries in the context are unused.
-    /// The base case is when the least significant bit set in leaf_count is bigger than new_leaf_count.
-    /// We can simply add to context[j] a pristine subtree of size 2^j for each bit j set in new_leaf_count.
-    /// No used used entry in the context will be overwritten.
-    /// We can then simply add new_leaf_count to leaf_count and we are done.
-    /// In the general case, the least significant bit set i in leaf_count is less than or equal to new_leaf_count.
-    /// Here, we add a pristine subtree of size 2^i to the context and bubble up.
-    /// We add 2^i to leaf_count and subtract 2^i from new_leaf_count.
-    /// Then we repeat this process until we reach the base case.
-    void pad_back(uint64_t new_leaf_count);
+    /// Uses binary representation of leaf counts to efficiently add padding.
+    /// Each set bit i in leaf_count represents a complete subtree of size 2^i.
+    ///
+    /// Base case: When the least significant set bit in leaf_count exceeds new_leaf_count,
+    /// directly place pad subtrees at positions corresponding to bits set in new_leaf_count.
+    ///
+    /// General case: When overlap exists, combine the smallest existing subtree with
+    /// a matching pad subtree, bubble up the result, and repeat until base case is reached.
+    void pad_back(uint64_t new_leaf_count, const machine_hashes &pad_hashes);
 
     /// \brief Returns the root tree hash
     /// \returns Root tree hash
-    /// \details
-    /// We can produce the tree root hash from the context at any time, also in log time
-    /// Ostensibly, we add pristine leaves until the leaf_count hits 2^(log2_root_size-log2_leaf_size)
-    /// To do this in log time, we start by precomputing the hashes for all completely pristine subtree sizes
-    /// If leaf_count is already 2^(log2_root_size-log2_leaf_size), we return context[i].
-    /// Otherwise, we start with i = 0 and root = pristine[i+log2_leaf_size] (i.e., the invariant is that
-    /// root contains the hash of the rightmost subtree whose log size is i + log2_leaf_size)
-    /// If bit i is set, we set root = hash(context[i], root) and move up a bit (i.e., the subtree we
-    /// are growing is to the right of what is in the context)
-    /// If bit i is not set, we set root = hash(root, pristine[i+log2_leaf_size]) and move up a bit
-    /// (i.e., to grow our subtree, we need to pad it on the right with a pristine subtree of the same size)
-    machine_hash get_root_hash() const;
-
-    /// \brief Returns proof for the next pristine leaf
-    /// \returns Proof for leaf at given index, or throws exception
-    /// \details This is basically the same algorithm as
-    /// back_merkle_tree::get_root_hash.
-    proof_type get_next_leaf_proof() const;
+    /// \details The tree must be complete, otherwise an exception is thrown
+    machine_hash get_root_hash() const {
+        if (!full()) {
+            throw std::runtime_error{"attempt to get root hash of an incomplete back tree"};
+        }
+        return m_context.back();
+    }
+
+    /// \brief Clears the tree, making it empty (as if no leaves were added)
+    void clear() noexcept {
+        m_leaf_count = 0;
+    }
+
+    /// \brief Returns true if the tree is complete (reached maximum amount of leaves)
+    bool full() const noexcept {
+        return m_leaf_count >= get_max_leaves();
+    }
+
+    /// \brief Returns true if the tree is empty (no leaves were added)
+    bool empty() const noexcept {
+        return m_leaf_count == 0;
+    }
+
+    /// \brief Returns log base 2 of maximum amount of leaves that can be held by the tree
+    int get_log2_max_leaves() const noexcept {
+        return static_cast<int>(m_context.size()) - 1;
+    }
+
+    /// \brief Returns maximum amount of leaves that can be held by the tree
+    uint64_t get_max_leaves() const noexcept {
+        return static_cast<uint64_t>(1) << get_log2_max_leaves();
+    }
+
+    /// \brief Returns the hash function used by the tree
+    hash_function_type get_hash_function() const noexcept {
+        return m_hash_function;
+    }
+
+    /// \brief Returns amount of leaves already added to the tree
+    uint64_t get_leaf_count() const noexcept {
+        return m_leaf_count;
+    }
+
+    /// \brief Returns amount of leaves that can yet be added to the tree
+    uint64_t get_remaining_leaf_count() const noexcept {
+        return get_max_leaves() - m_leaf_count;
+    }
+
+    /// \brief Returns the leaves context
+    machine_hashes get_context() const {
+        // Pack context
+        machine_hashes context;
+        if (m_leaf_count > 0) {
+            const int log2_max_leaves = get_log2_max_leaves();
+            for (int i = 0; i <= log2_max_leaves; ++i) {
+                const auto i_span = UINT64_C(1) << i;
+                if ((m_leaf_count & i_span) != 0) {
+                    context.push_back(m_context[i]);
+                }
+            }
+        }
+        return context;
+    }
+
+    /// \brief Creates an array of pad hashes to be used with pad_back()
+    /// \param leaf_hash Hash of the leaf node
+    /// \param log2_max_leaves Log base 2 of maximum amount of leaves
+    /// \param hash_function Hash function to use
+    /// \returns Array of pad hashes
+    static machine_hashes make_pad_hashes(const machine_hash &leaf_hash, int log2_max_leaves,
+        hash_function_type hash_function);
+
+    /// \brief Creates an array of pristine pad hashes to be used with pad_back()
+    /// \param log2_root_size Log base 2 of root node
+    /// \param log2_leaf_size Log base 2 of leaf node
+    /// \param log2_word_size Log base 2 of word node
+    /// \param hash_function Hash function to use
+    /// \returns Array of pad hashes
+    static machine_hashes make_pristine_pad_hashes(int log2_root_size, int log2_leaf_size, int log2_word_size,
+        hash_function_type hash_function);
+
+    /// \brief Validates and computes log2_max_leaves from root, leaf and word sizes
+    /// \param log2_root_size Log base 2 of root node
+    /// \param log2_leaf_size Log base 2 of leaf node
+    /// \param log2_word_size Log base 2 of word node
+    /// \returns Log base 2 of maximum amount of leaves
+    static int validate_log2_max_leaves_size(int log2_root_size, int log2_leaf_size, int log2_word_size);
 
 private:
-    int m_log2_root_size;                   ///< Log<sub>2</sub> of tree size
-    int m_log2_leaf_size;                   ///< Log<sub>2</sub> of leaf size
-    uint64_t m_leaf_count{0};               ///< Number of leaves already added
-    uint64_t m_max_leaves;                  ///< Maximum number of leaves
-    std::vector<machine_hash> m_context;    ///< Hashes of bits set in leaf_count
-    pristine_merkle_tree m_pristine_hashes; ///< Hash of pristine subtrees of all sizes
-    hash_function_type m_hash_function;     ///< Hash function
+    hash_function_type m_hash_function; ///< Hash function
+    uint64_t m_leaf_count;              ///< Number of leaves already added
+    machine_hashes m_context;           ///< Hashes of bits set in leaf_count
 };
 
 } // namespace cartesi
diff --git a/src/base64.h b/src/base64.h
index ba34cb0c7..6b7cf7e9b 100644
--- a/src/base64.h
+++ b/src/base64.h
@@ -17,6 +17,7 @@
 #ifndef BASE64_H
 #define BASE64_H
 
+#include <cstddef>
 #include <cstdint>
 #include <sstream>
 #include <string>
diff --git a/src/cartesi-machine.lua b/src/cartesi-machine.lua
index 6d7effcf3..0fb9211e0 100755
--- a/src/cartesi-machine.lua
+++ b/src/cartesi-machine.lua
@@ -319,14 +319,14 @@ where options are:
     this includes anything written to machine's stdout or stderr.
 
   --skip-root-hash-check
-    skip merkle tree root hash check when loading a stored machine.
+    skip hash tree root hash check when loading a stored machine.
     i.e., assume the stored machine files are not corrupt.
     this is only intended to speed up machine loading in emulator tests.
 
     DON'T USE THIS OPTION IN PRODUCTION
 
   --skip-root-hash-store
-    skip merkle tree root hash saving when storing a machine.
+    skip hash tree root hash saving when storing a machine.
     i.e., assume the stored machine will use --skip-root-hash-check when loading.
     this is only intended to speed up machine saving in emulator tests.
 
diff --git a/src/clint-address-range.cpp b/src/clint-address-range.cpp
index 9665cd7f5..9f0c66068 100644
--- a/src/clint-address-range.cpp
+++ b/src/clint-address-range.cpp
@@ -27,7 +27,7 @@
 namespace cartesi {
 
 /// \brief Mapping between CSRs and their relative addresses in CLINT memory
-enum class clint_csr {
+enum class clint_csr : uint64_t {
     msip0 = UINT64_C(0), // Machine software interrupt for hart 0
     mtimecmp = UINT64_C(0x4000),
     mtime = UINT64_C(0xbff8)
diff --git a/src/clint-address-range.h b/src/clint-address-range.h
index 695d0315f..ed12edd5b 100644
--- a/src/clint-address-range.h
+++ b/src/clint-address-range.h
@@ -21,6 +21,10 @@
 
 #include "address-range-constants.h"
 #include "address-range.h"
+#include "i-device-state-access.h"
+#include "interpret.h"
+#include "pmas-constants.h"
+#include "pmas.h"
 
 /// \file
 /// \brief Core-Local Interruptor device.
diff --git a/src/clua-cartesi.cpp b/src/clua-cartesi.cpp
index 88476d1ba..8fecf9418 100644
--- a/src/clua-cartesi.cpp
+++ b/src/clua-cartesi.cpp
@@ -15,7 +15,6 @@
 //
 
 #include <cstddef>
-#include <cstdint>
 #include <exception>
 #include <string>
 #include <string_view>
@@ -33,7 +32,6 @@ extern "C" {
 #include "htif-constants.h"
 #include "machine-c-api.h"
 #include "machine-c-version.h"
-#include "machine-hash.h"
 #include "riscv-constants.h"
 #include "uarch-constants.h"
 #include "uarch-pristine.h"
@@ -214,6 +212,7 @@ CM_API int luaopen_cartesi(lua_State *L) {
     clua_setintegerfield(L, CM_VERSION_MINOR, "VERSION_MINOR", -1);
     clua_setintegerfield(L, CM_VERSION_PATCH, "VERSION_PATCH", -1);
     clua_setintegerfield(L, CM_HASH_SIZE, "HASH_SIZE", -1);
+    clua_setintegerfield(L, CM_MCYCLE_MAX, "MCYCLE_MAX", -1);
     clua_setintegerfield(L, CM_TREE_LOG2_WORD_SIZE, "TREE_LOG2_WORD_SIZE", -1);
     clua_setintegerfield(L, CM_TREE_LOG2_PAGE_SIZE, "TREE_LOG2_PAGE_SIZE", -1);
     clua_setintegerfield(L, CM_TREE_LOG2_ROOT_SIZE, "TREE_LOG2_ROOT_SIZE", -1);
diff --git a/src/clua-i-machine.cpp b/src/clua-i-machine.cpp
index 543db45f3..326ad1469 100644
--- a/src/clua-i-machine.cpp
+++ b/src/clua-i-machine.cpp
@@ -509,12 +509,14 @@ static const nlohmann::json &clua_get_machine_schema_dict(lua_State *L) try {
             {
                 {"hashes", "Base64Array"},
                 {"break_reason", "InterpreterBreakReason"},
+                {"back_tree", "BackMerkleTree"},
             }},
         {"UarchCycleRootHashes",
+            {{"hashes", "Base64Array"}, {"reset_indices", "ArrayArrayIndex"},
+                {"break_reason", "InterpreterBreakReason"}}},
+        {"BackMerkleTree",
             {
-                {"hashes", "Base64Array"},
-                {"reset_indices", "ArrayArrayIndex"},
-                {"break_reason", "InterpreterBreakReason"},
+                {"context", "Base64Array"},
             }},
     };
     return machine_schema_dict;
@@ -991,15 +993,17 @@ static int machine_obj_index_create(lua_State *L) {
 /// \brief This is the machine:collect_mcycle_root_hashes() method implementation.
 /// \param L Lua state.
 static int machine_obj_index_collect_mcycle_root_hashes(lua_State *L) {
-    lua_settop(L, 5);
+    lua_settop(L, 6);
     auto &m = clua_check<clua_managed_cm_ptr<cm_machine>>(L, 1);
     const uint64_t mcycle_end = luaL_checkinteger(L, 2);
     const uint64_t mcycle_period = luaL_checkinteger(L, 3);
     const uint64_t mcycle_phase = luaL_optinteger(L, 4, 0);
-    const auto log2_bundle_uarch_cycle_count = static_cast<uint32_t>(luaL_optinteger(L, 5, 0));
+    const auto log2_bundle_uarch_cycle_count = static_cast<int32_t>(luaL_optinteger(L, 5, 0));
+    const char *previous_back_tree =
+        !lua_isnil(L, 6) ? clua_check_schemed_json_string(L, 6, "BackMerkleTree") : nullptr;
     const char *result = nullptr;
     if (cm_collect_mcycle_root_hashes(m.get(), mcycle_end, mcycle_period, mcycle_phase, log2_bundle_uarch_cycle_count,
-            &result) != 0) {
+            previous_back_tree, &result) != 0) {
         return luaL_error(L, "%s", cm_get_last_error_message());
     }
     clua_push_schemed_json_table(L, result, "McycleRootHashes");
@@ -1012,7 +1016,7 @@ static int machine_obj_index_collect_uarch_cycle_root_hashes(lua_State *L) {
     lua_settop(L, 3);
     auto &m = clua_check<clua_managed_cm_ptr<cm_machine>>(L, 1);
     const uint64_t mcycle_end = luaL_checkinteger(L, 2);
-    const auto log2_bundle_uarch_cycle_count = static_cast<uint32_t>(luaL_optinteger(L, 3, 0));
+    const auto log2_bundle_uarch_cycle_count = static_cast<int32_t>(luaL_optinteger(L, 3, 0));
     const char *result = nullptr;
     if (cm_collect_uarch_cycle_root_hashes(m.get(), mcycle_end, log2_bundle_uarch_cycle_count, &result) != 0) {
         return luaL_error(L, "%s", cm_get_last_error_message());
diff --git a/src/clua-i-machine.h b/src/clua-i-machine.h
index 584ea08ce..465002af1 100644
--- a/src/clua-i-machine.h
+++ b/src/clua-i-machine.h
@@ -17,13 +17,16 @@
 #ifndef CLUA_I_MACHINE_H
 #define CLUA_I_MACHINE_H
 
-#include <memory>
 #include <string>
 #include <utility>
 
+#include <json.hpp>
+
+extern "C" {
+#include <lua.h>
+}
+
 #include "clua.h"
-#include "i-machine.h"
-#include "json-util.h"
 #include "machine-c-api.h"
 
 /// \file
@@ -71,7 +74,7 @@ class clua_managed_cm_ptr final {
         reset();
         std::swap(m_ptr, other.m_ptr);
         return *this;
-    };
+    }
 
     ~clua_managed_cm_ptr() {
         reset();
diff --git a/src/collect-mcycle-hashes-state-access.h b/src/collect-mcycle-hashes-state-access.h
index 188acf90f..e6b8e647b 100644
--- a/src/collect-mcycle-hashes-state-access.h
+++ b/src/collect-mcycle-hashes-state-access.h
@@ -17,16 +17,22 @@
 #ifndef COLLECT_MCYCLE_HASHES_STATE_ACCESS_H
 #define COLLECT_MCYCLE_HASHES_STATE_ACCESS_H
 
-#include <cassert>
+#include <cstdint>
 #include <stdexcept>
 
+#include "address-range-constants.h"
+#include "address-range.h"
+#include "assert-printf.h"
 #include "compiler-defines.h"
+#include "hash-tree-constants.h"
 #include "hash-tree.h"
+#include "host-addr.h"
 #include "i-accept-scoped-notes.h"
-#include "i-prefer-shadow-state.h"
 #include "i-state-access.h"
 #include "machine.h"
-#include "pmas.h"
+#include "os.h"
+#include "pmas-constants.h"
+#include "riscv-constants.h"
 #include "shadow-tlb.h"
 #include "strict-aliasing.h"
 
diff --git a/src/collect-uarch-cycle-hashes-state-access.h b/src/collect-uarch-cycle-hashes-state-access.h
index 17bf7e2ef..536c0edda 100644
--- a/src/collect-uarch-cycle-hashes-state-access.h
+++ b/src/collect-uarch-cycle-hashes-state-access.h
@@ -22,15 +22,17 @@
 #include <cstdint>
 #include <stdexcept>
 
+#include "address-range-constants.h"
 #include "compiler-defines.h"
+#include "hash-tree-constants.h"
 #include "hash-tree.h"
 #include "i-accept-scoped-notes.h"
 #include "i-prefer-shadow-uarch-state.h"
 #include "i-uarch-state-access.h"
 #include "machine.h"
+#include "os.h"
 #include "shadow-tlb.h"
 #include "shadow-uarch-state.h"
-#include "strict-aliasing.h"
 
 namespace cartesi {
 
diff --git a/src/complete-merkle-tree.cpp b/src/complete-merkle-tree.cpp
deleted file mode 100644
index b7ca70fcd..000000000
--- a/src/complete-merkle-tree.cpp
+++ /dev/null
@@ -1,149 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#include "complete-merkle-tree.h"
-
-#include <algorithm>
-#include <cassert>
-#include <limits>
-#include <stdexcept>
-#include <utility>
-
-#include "i-hasher.h"
-#include "variant-hasher.h"
-
-/// \file
-/// \brief Complete Merkle tree implementation.
-
-namespace cartesi {
-
-complete_merkle_tree::complete_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size,
-    hash_function_type hash_function) :
-    m_log2_root_size{log2_root_size},
-    m_log2_leaf_size{log2_leaf_size},
-    m_pristine{log2_root_size, log2_word_size, hash_function},
-    m_tree(std::max(0, log2_root_size - log2_leaf_size + 1)),
-    m_hash_function(hash_function) {
-    check_log2_sizes(log2_root_size, log2_leaf_size, log2_word_size);
-}
-
-/// \brief Returns proof for a given node
-/// \param address Node address
-/// \param log2_size Log<sub>2</sub> size subintended by node
-/// \returns Proof, or throws exception
-complete_merkle_tree::proof_type complete_merkle_tree::get_proof(uint64_t address, int log2_size) const {
-    if (log2_size < get_log2_leaf_size() || log2_size > get_log2_root_size()) {
-        throw std::out_of_range{"log2_size is out of bounds"};
-    }
-    auto aligned_address = (address >> log2_size) << log2_size;
-    if (address != aligned_address) {
-        throw std::out_of_range{"address is misaligned"};
-    }
-    proof_type proof{get_log2_root_size(), log2_size};
-    proof.set_root_hash(get_root_hash());
-    proof.set_target_address(address);
-    proof.set_target_hash(get_node_hash(address, log2_size));
-    for (int log2_sibling_size = log2_size; log2_sibling_size < get_log2_root_size(); ++log2_sibling_size) {
-        auto sibling_address = address ^ (UINT64_C(1) << log2_sibling_size);
-        proof.set_sibling_hash(get_node_hash(sibling_address, log2_sibling_size), log2_sibling_size);
-    }
-    return proof;
-}
-
-/// \brief Appends a new leaf hash to the tree
-/// \param hash Hash to append
-void complete_merkle_tree::push_back(const machine_hash &hash) {
-    auto &leaves = get_level(get_log2_leaf_size());
-    if (leaves.size() >= UINT64_C(1) << (get_log2_root_size() - get_log2_leaf_size())) {
-        throw std::out_of_range{"tree is full"};
-    }
-    leaves.push_back(hash);
-    bubble_up();
-}
-
-void complete_merkle_tree::check_log2_sizes(int log2_root_size, int log2_leaf_size, int log2_word_size) {
-    if (log2_root_size < 0) {
-        throw std::out_of_range{"log2_root_size is negative"};
-    }
-    if (log2_leaf_size < 0) {
-        throw std::out_of_range{"log2_leaf_size is negative"};
-    }
-    if (log2_word_size < 0) {
-        throw std::out_of_range{"log2_word_size is negative"};
-    }
-    if (log2_leaf_size > log2_root_size) {
-        throw std::out_of_range{"log2_leaf_size is greater than log2_root_size"};
-    }
-    if (log2_word_size > log2_leaf_size) {
-        throw std::out_of_range{"log2_word_size is greater than log2_word_size"};
-    }
-    if (log2_root_size >= std::numeric_limits<uint64_t>::digits) {
-        throw std::out_of_range{"tree is too large for address type"};
-    }
-}
-
-const machine_hash &complete_merkle_tree::get_node_hash(uint64_t address, int log2_size) const {
-    const auto &level = get_level(log2_size);
-    address >>= log2_size;
-    if (address >= (UINT64_C(1) << (get_log2_root_size() - log2_size))) {
-        throw std::out_of_range{"log2_size is out of bounds"};
-    }
-    if (address < level.size()) {
-        return level[address];
-    }
-    return m_pristine.get_hash(log2_size);
-}
-
-void complete_merkle_tree::bubble_up() {
-    variant_hasher h{m_hash_function};
-    // Go bottom up, updating hashes
-    for (int log2_next_size = get_log2_leaf_size() + 1; log2_next_size <= get_log2_root_size(); ++log2_next_size) {
-        auto log2_prev_size = log2_next_size - 1;
-        auto &prev = get_level(log2_prev_size);
-        auto &next = get_level(log2_next_size);
-        // Redo last entry (if any) because it may have been constructed
-        // from the last non-pristine entry in the previous level paired
-        // with a pristine entry (i.e., the previous level was odd).
-        auto first_entry = !next.empty() ? next.size() - 1 : next.size();
-        // Next level needs half as many (rounded up) as previous
-        next.resize((prev.size() + 1) / 2);
-        assert(first_entry <= next.size());
-        // Last safe entry has two non-pristine leaves
-        auto last_safe_entry = prev.size() / 2;
-        // Do all entries for which we have two non-pristine children
-        for (; first_entry < last_safe_entry; ++first_entry) {
-            get_concat_hash(h, prev[2 * first_entry], prev[(2 * first_entry) + 1], next[first_entry]);
-        }
-        // Maybe do last odd entry
-        if (prev.size() > 2 * last_safe_entry) {
-            get_concat_hash(h, prev.back(), m_pristine.get_hash(log2_prev_size), next[last_safe_entry]);
-        }
-    }
-}
-
-const complete_merkle_tree::level_type &complete_merkle_tree::get_level(int log2_size) const {
-    if (log2_size < get_log2_leaf_size() || log2_size > get_log2_root_size()) {
-        throw std::out_of_range{"log2_size is out of bounds"};
-    }
-    return m_tree[m_log2_root_size - log2_size];
-}
-
-complete_merkle_tree::level_type &complete_merkle_tree::get_level(int log2_size) {
-    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-const-cast): remove const to reuse code
-    return const_cast<level_type &>(std::as_const(*this).get_level(log2_size));
-}
-
-} // namespace cartesi
diff --git a/src/complete-merkle-tree.h b/src/complete-merkle-tree.h
deleted file mode 100644
index e2e4462c7..000000000
--- a/src/complete-merkle-tree.h
+++ /dev/null
@@ -1,134 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef COMPLETE_MERKLE_TREE_H
-#define COMPLETE_MERKLE_TREE_H
-
-#include <cstdint>
-#include <type_traits>
-#include <vector>
-
-#include "hash-tree-proof.h"
-#include "machine-hash.h"
-#include "meta.h"
-#include "pristine-merkle-tree.h"
-#include "variant-hasher.h"
-
-/// \file
-/// \brief Complete Merkle tree interface.
-
-namespace cartesi {
-
-/// \brief Complete Merkle tree
-/// \details This class implements complete Merkle tree, i.e., a tree in which
-/// the leaf level has a number of non-pristine leaves followed by a number
-/// of pristine leaves.
-/// The tree is optimized to store only the hashes that are not pristine.
-class complete_merkle_tree {
-public:
-    /// \brief Storage for a proof.
-    using proof_type = hash_tree_proof;
-
-    /// \brief Storage for a level in the tree.
-    using level_type = std::vector<machine_hash>;
-
-    /// \brief Constructor for pristine tree
-    /// \param log2_root_size Log<sub>2</sub> of tree size
-    /// \param log2_leaf_size Log<sub>2</sub> of leaf node
-    /// \param log2_word_size Log<sub>2</sub> of word
-    complete_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size, hash_function_type hash_function);
-
-    /// \brief Constructor from non-pristine leaves (assumed flushed left)
-    /// \param log2_root_size Log<sub>2</sub> of tree size
-    /// \param log2_leaf_size Log<sub>2</sub> of leaf node
-    /// \param log2_word_size Log<sub>2</sub> of word
-    template <typename L>
-    complete_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size, L &&leaves,
-        hash_function_type hash_function) :
-        complete_merkle_tree{log2_root_size, log2_leaf_size, log2_word_size, hash_function} {
-        static_assert(std::is_same_v<level_type, std::remove_cvref_t<L>>, "not a leaves vector");
-        get_level(get_log2_leaf_size()) = std::forward<L>(leaves);
-        bubble_up();
-    }
-
-    /// \brief Returns the tree's root hash
-    /// \returns Root hash
-    machine_hash get_root_hash() const {
-        return get_node_hash(0, get_log2_root_size());
-    }
-
-    /// \brief Returns the hash of a node at a given address of a given size
-    /// \param address Node address
-    /// \param log2_size Log<sub>2</sub> size subintended by node
-    const machine_hash &get_node_hash(uint64_t address, int log2_size) const;
-
-    /// \brief Returns proof for a given node
-    /// \param address Node address
-    /// \param log2_size Log<sub>2</sub> size subintended by node
-    /// \returns Proof, or throws exception
-    proof_type get_proof(uint64_t address, int log2_size) const;
-
-    /// \brief Appends a new leaf hash to the tree
-    /// \param hash Hash to append
-    void push_back(const machine_hash &hash);
-
-    /// \brief Returns number of leaves in tree
-    uint64_t size() const {
-        return get_level(get_log2_leaf_size()).size();
-    };
-
-private:
-    /// \brief Throws exception if log<sub>2</sub> sizes are inconsistent
-    ///  with one another
-    /// \param log2_root_size Log<sub>2</sub> of root node
-    /// \param log2_leaf_size Log<sub>2</sub> of leaf node
-    /// \param log2_word_size Log<sub>2</sub> of word
-    static void check_log2_sizes(int log2_root_size, int log2_leaf_size, int log2_word_size);
-
-    /// \brief Returns log<sub>2</sub> of size of tree
-    int get_log2_root_size() const {
-        return m_log2_root_size;
-    }
-
-    /// \brief Returns log<sub>2</sub> of size of leaf
-    int get_log2_leaf_size() const {
-        return m_log2_leaf_size;
-    }
-
-    /// \brief Update node hashes when a new set of non-pristine nodes is added
-    /// to the leaf level
-    void bubble_up();
-
-    ///< \brief Returns hashes at a given level
-    ///< \param log2_size Log<sub>2</sub> of size subintended by each
-    /// hash at level
-    const level_type &get_level(int log2_size) const;
-
-    ///< \brief Returns hashes at a given level
-    ///< \param log2_size Log<sub>2</sub> of size subintended by each
-    /// hash at level
-    level_type &get_level(int log2_size);
-
-    int m_log2_root_size;               ///< Log<sub>2</sub> of tree size
-    int m_log2_leaf_size;               ///< Log<sub>2</sub> of page size
-    pristine_merkle_tree m_pristine;    ///< Pristine hashes for all levels
-    std::vector<level_type> m_tree;     ///< Merkle tree
-    hash_function_type m_hash_function; ///< Hash function
-};
-
-} // namespace cartesi
-
-#endif
diff --git a/src/concepts.h b/src/concepts.h
index 4d1c852ea..5b11a55c4 100644
--- a/src/concepts.h
+++ b/src/concepts.h
@@ -17,7 +17,9 @@
 #ifndef CONCEPTS_H
 #define CONCEPTS_H
 
+#include <concepts>
 #include <ranges>
+#include <type_traits>
 
 /// \file
 /// \brief Concepts helper functions.
@@ -53,12 +55,14 @@ concept ScopedEnum = std::is_enum_v<E> && !std::is_convertible_v<E, std::underly
 template <typename T, typename... Ts>
 concept SameAsAny = (std::same_as<T, Ts> || ...);
 
-// C++20 concept to check if a container is back insertable
-template <typename T>
-concept BackInsertableContainer = std::ranges::range<T> && requires(T container, typename T::value_type value) {
+// C++20 concept to check if a container is back insertable with a value
+template <typename Container, typename T>
+concept BackInsertableWith = std::ranges::range<Container> && requires(Container container, T &&value) {
     { container.empty() } -> std::convertible_to<bool>;
-    { container.back() } -> std::convertible_to<typename T::reference>;
-    container.push_back(value);
+    { container.back() } -> std::convertible_to<typename Container::reference>;
+    container.push_back(std::forward<T>(value));
+    requires std::constructible_from<typename Container::value_type, T &&>;
+    requires std::equality_comparable_with<typename Container::value_type, T>;
 };
 
 } // namespace cartesi
diff --git a/src/dense-hash-tree.h b/src/dense-hash-tree.h
index 5c7f490fa..d0e38c3ba 100644
--- a/src/dense-hash-tree.h
+++ b/src/dense-hash-tree.h
@@ -17,6 +17,7 @@
 #ifndef DENSE_HASH_TREE_H
 #define DENSE_HASH_TREE_H
 
+#include <cstdint>
 #include <limits>
 #include <stdexcept>
 #include <vector>
@@ -28,7 +29,7 @@
 
 namespace cartesi {
 
-class dense_hash_tree : public i_dense_hash_tree {
+class dense_hash_tree final : public i_dense_hash_tree {
 
     using container_type = std::vector<machine_hash>;
     using size_type = container_type::size_type;
diff --git a/src/device-state-access.h b/src/device-state-access.h
index b424470c4..fecfa191a 100644
--- a/src/device-state-access.h
+++ b/src/device-state-access.h
@@ -32,7 +32,7 @@ namespace cartesi {
 /// interface provided by any class implementing the i_state_access interface.
 /// \tparam STATE_ACCESS Class implementing the i_state_access interface.
 template <typename STATE_ACCESS>
-class device_state_access : public i_device_state_access {
+class device_state_access final : public i_device_state_access {
 public:
     explicit device_state_access(STATE_ACCESS a, uint64_t mcycle) : m_a(a), m_mcycle(mcycle) {
         static_assert(is_an_i_state_access_v<STATE_ACCESS>, "not an i_state_access");
diff --git a/src/dirty-page-tree.h b/src/dirty-page-tree.h
index a79e1f6dd..9971f2548 100644
--- a/src/dirty-page-tree.h
+++ b/src/dirty-page-tree.h
@@ -21,22 +21,23 @@
 /// \brief Dirty map as a complete tree
 
 #include <algorithm>
-#include <cassert>
-#include <concepts>
 #include <cstdint>
+#include <initializer_list>
 #include <iostream>
-#include <iterator>
+#include <limits>
 #include <ranges>
+#include <span>
 #include <stdexcept>
 #include <vector>
 
+#include "assert-printf.h"
 #include "i-dirty-page-tree.h"
 #include "ranges.h"
 
 namespace cartesi {
 
 /// \brief Dirty page tree
-class dirty_page_tree : public i_dirty_page_tree {
+class dirty_page_tree final : public i_dirty_page_tree {
 public:
     /// \brief Each node in tree is either clean or dirty
     enum class status_type : uint8_t { clean, dirty };
diff --git a/src/dtb.cpp b/src/dtb.cpp
index b7e2983b9..6b36a569a 100644
--- a/src/dtb.cpp
+++ b/src/dtb.cpp
@@ -26,6 +26,7 @@
 
 #include "address-range-constants.h"
 #include "fdt-builder.h"
+#include "htif-constants.h"
 #include "machine-c-version.h"
 #include "machine-config.h"
 #include "plic-constants.h"
diff --git a/src/full-merkle-tree.cpp b/src/full-merkle-tree.cpp
deleted file mode 100644
index 64e34c1c9..000000000
--- a/src/full-merkle-tree.cpp
+++ /dev/null
@@ -1,149 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#include "full-merkle-tree.h"
-
-#include <algorithm>
-#include <limits>
-#include <stdexcept>
-#include <vector>
-
-#include "i-hasher.h"
-#include "pristine-merkle-tree.h"
-
-/// \file
-/// \brief Full Merkle tree implementation.
-
-namespace cartesi {
-
-full_merkle_tree::full_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size,
-    hash_function_type hash_function) :
-    m_log2_root_size{log2_root_size},
-    m_log2_leaf_size{log2_leaf_size},
-    m_max_leaves{UINT64_C(1) << std::max(0, log2_root_size - log2_leaf_size)},
-    m_hash_function{hash_function} {
-    check_log2_sizes(log2_root_size, log2_leaf_size, log2_word_size);
-    m_tree.resize(2 * m_max_leaves);
-    init_pristine_subtree(pristine_merkle_tree{log2_root_size, log2_word_size, hash_function}, 1, log2_root_size);
-}
-
-full_merkle_tree::full_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size,
-    const std::vector<machine_hash> &leaves, hash_function_type hash_function) :
-    m_log2_root_size(log2_root_size),
-    m_log2_leaf_size(log2_leaf_size),
-    m_max_leaves{UINT64_C(1) << std::max(0, log2_root_size - log2_leaf_size)},
-    m_hash_function{hash_function} {
-    check_log2_sizes(log2_root_size, log2_leaf_size, log2_word_size);
-    if (leaves.size() > m_max_leaves) {
-        throw std::out_of_range{"too many leaves"};
-    }
-    m_tree.resize(2 * m_max_leaves);
-    init_tree(pristine_merkle_tree{log2_root_size, log2_word_size, hash_function}, leaves);
-}
-
-full_merkle_tree::proof_type full_merkle_tree::get_proof(uint64_t address, int log2_size) const {
-    if (log2_size < get_log2_leaf_size() || log2_size > get_log2_root_size()) {
-        throw std::out_of_range{"log2_size is out of bounds"};
-    }
-    auto aligned_address = (address >> log2_size) << log2_size;
-    if (address != aligned_address) {
-        throw std::out_of_range{"address is misaligned"};
-    }
-    proof_type proof{get_log2_root_size(), log2_size};
-    proof.set_root_hash(get_root_hash());
-    proof.set_target_address(address);
-    proof.set_target_hash(get_node_hash(address, log2_size));
-    for (int log2_sibling_size = log2_size; log2_sibling_size < get_log2_root_size(); ++log2_sibling_size) {
-        auto sibling_address = address ^ (UINT64_C(1) << log2_sibling_size);
-        proof.set_sibling_hash(get_node_hash(sibling_address, log2_sibling_size), log2_sibling_size);
-    }
-#ifndef NDEBUG
-    variant_hasher h{m_hash_function};
-    if (!proof.verify(h)) {
-        throw std::runtime_error{"produced invalid proof"};
-    }
-#endif
-    return proof;
-}
-
-void full_merkle_tree::check_log2_sizes(int log2_root_size, int log2_leaf_size, int log2_word_size) {
-    if (log2_root_size < 0) {
-        throw std::out_of_range{"log2_root_size is negative"};
-    }
-    if (log2_leaf_size < 0) {
-        throw std::out_of_range{"log2_leaf_size is negative"};
-    }
-    if (log2_word_size < 0) {
-        throw std::out_of_range{"log2_word_size is negative"};
-    }
-    if (log2_leaf_size > log2_root_size) {
-        throw std::out_of_range{"log2_leaf_size is greater than log2_root_size"};
-    }
-    if (log2_word_size > log2_leaf_size) {
-        throw std::out_of_range{"log2_word_size is greater than log2_word_size"};
-    }
-    if (log2_root_size >= std::numeric_limits<uint64_t>::digits) {
-        throw std::out_of_range{"tree is too large for address type"};
-    }
-}
-
-void full_merkle_tree::init_pristine_subtree(const pristine_merkle_tree &pristine, int index, int log2_size) {
-    if (log2_size >= get_log2_leaf_size()) {
-        m_tree[index] = pristine.get_hash(log2_size);
-        init_pristine_subtree(pristine, left_child_index(index), log2_size - 1);
-        init_pristine_subtree(pristine, right_child_index(index), log2_size - 1);
-    }
-}
-
-void full_merkle_tree::init_subtree(variant_hasher &h, int index, int log2_size) {
-    if (log2_size > get_log2_leaf_size()) {
-        init_subtree(h, left_child_index(index), log2_size - 1);
-        init_subtree(h, right_child_index(index), log2_size - 1);
-        get_concat_hash(h, m_tree[left_child_index(index)], m_tree[right_child_index(index)], m_tree[index]);
-    }
-}
-
-void full_merkle_tree::init_tree(const pristine_merkle_tree &pristine, const std::vector<machine_hash> &leaves) {
-    std::copy(leaves.begin(), leaves.end(), &m_tree[m_max_leaves]);
-    std::fill_n(&m_tree[m_max_leaves + leaves.size()], m_max_leaves - leaves.size(),
-        pristine.get_hash(get_log2_leaf_size()));
-    variant_hasher h{m_hash_function};
-    init_subtree(h, 1, get_log2_root_size());
-}
-
-uint64_t full_merkle_tree::get_node_index(uint64_t address, int log2_size) const {
-    if (log2_size < get_log2_leaf_size() || log2_size > get_log2_root_size()) {
-        throw std::out_of_range{"log2_size is out of bounds"};
-    }
-    const uint64_t base = UINT64_C(1) << (get_log2_root_size() - log2_size);
-    // Nodes of log2_size live in indices [base, 2*base)
-    // 0 <unused>
-    // 1 log2_root_size
-    // 2 log2_root_size-1
-    // 3 log2_root_size-1
-    // 4 log2_root_size-2
-    // 5 log2_root_size-2
-    // 6 log2_root_size-2
-    // 7 log2_root_size-2
-    // 0 ...
-    address >>= log2_size;
-    if (address >= base) {
-        throw std::out_of_range{"address is out of bounds"};
-    }
-    return base + address;
-}
-
-} // namespace cartesi
diff --git a/src/full-merkle-tree.h b/src/full-merkle-tree.h
deleted file mode 100644
index 9898de6c1..000000000
--- a/src/full-merkle-tree.h
+++ /dev/null
@@ -1,137 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef FULL_MERKLE_TREE_H
-#define FULL_MERKLE_TREE_H
-
-#include <cstdint>
-#include <vector>
-
-#include "hash-tree-proof.h"
-#include "machine-hash.h"
-#include "pristine-merkle-tree.h"
-#include "variant-hasher.h"
-
-/// \file
-/// \brief Full Merkle tree interface.
-
-namespace cartesi {
-
-/// \brief Full Merkle tree
-/// \details This class implements a full merkle tree
-class full_merkle_tree {
-public:
-    /// \brief Storage for a proof.
-    using proof_type = hash_tree_proof;
-
-    /// \brief Constructor for a pristine tree
-    /// \param log2_root_size Log<sub>2</sub> of root node
-    /// \param log2_leaf_size Log<sub>2</sub> of leaf node
-    /// \param log2_word_size Log<sub>2</sub> of word
-    full_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size, hash_function_type hash_function);
-
-    /// \brief Constructor for list of consecutive leaf hashes
-    /// \param log2_root_size Log<sub>2</sub> of root node
-    /// \param log2_leaf_size Log<sub>2</sub> of leaf node
-    /// \param log2_word_size Log<sub>2</sub> of word
-    /// \param leaves List of leaf hashes
-    full_merkle_tree(int log2_root_size, int log2_leaf_size, int log2_word_size,
-        const std::vector<machine_hash> &leaves, hash_function_type hash_function);
-
-    /// \brief Returns log<sub>2</sub> of size of tree
-    int get_log2_root_size() const {
-        return m_log2_root_size;
-    }
-
-    /// \brief Returns log<sub>2</sub> of size of leaf
-    int get_log2_leaf_size() const {
-        return m_log2_leaf_size;
-    }
-
-    /// \brief Returns the tree's root hash
-    /// \returns Root hash
-    const machine_hash &get_root_hash() const {
-        return get_node_hash(0, get_log2_root_size());
-    }
-
-    /// \brief Returns the hash of a node at a given address of a given size
-    /// \param address Node address
-    /// \param log2_size Log<sub>2</sub> size subintended by node
-    const machine_hash &get_node_hash(uint64_t address, int log2_size) const {
-        return m_tree[get_node_index(address, log2_size)];
-    }
-
-    /// \brief Returns proof for a given node
-    /// \param address Node address
-    /// \param log2_size Log<sub>2</sub> size subintended by node
-    /// \returns Proof, or throws exception
-    proof_type get_proof(uint64_t address, int log2_size) const;
-
-private:
-    /// \brief Throws exception if log<sub>2</sub> sizes are inconsistent
-    ///  with one another
-    /// \param log2_root_size Log<sub>2</sub> of root node
-    /// \param log2_leaf_size Log<sub>2</sub> of leaf node
-    /// \param log2_word_size Log<sub>2</sub> of word
-    static void check_log2_sizes(int log2_root_size, int log2_leaf_size, int log2_word_size);
-
-    /// \brief Returns the index of the left child of node at given index
-    static constexpr int left_child_index(int index) {
-        return 2 * index;
-    }
-
-    /// \brief Returns the index of the right child of node at given index
-    static constexpr int right_child_index(int index) {
-        return (2 * index) + 1;
-    }
-
-    /// \brief Initialize all nodes for the pristine subtree with root
-    /// at a given index
-    /// \param pristine Hashes for pristine subtree nodes of all sizes
-    /// \param index Index of root for subtree to initialize
-    /// \param log2_size Log<sub>2</sub> size of root at index
-    void init_pristine_subtree(const pristine_merkle_tree &pristine, int index, int log2_size);
-
-    /// \brief Initialize all nodes for the subtree with root at a given index
-    /// \param h Hasher object
-    /// \param index Index of root for subtree to initialize
-    /// \param log2_size Log<sub>2</sub> size of root at index
-    /// \details The nodes corresponding to subtrees of size log2_leaf_size
-    /// are assumed to have already been set prior to calling this function
-    void init_subtree(variant_hasher &h, int index, int log2_size);
-
-    /// \brief Initialize tree from a list of consecutive page hashes
-    /// \param leaves List of page hashes
-    /// \details The page hashes in leaves are copied to the appropriate
-    /// subtree nodes, in order, and the rest are filled with pristine
-    /// page hashes
-    void init_tree(const pristine_merkle_tree &pristine, const std::vector<machine_hash> &leaves);
-
-    /// \brief Returns index of a node in the tree array
-    /// \param address Node address
-    /// \param log2_size
-    uint64_t get_node_index(uint64_t address, int log2_size) const;
-
-    int m_log2_root_size;               ///< Log<sub>2</sub> of tree size
-    int m_log2_leaf_size;               ///< Log<sub>2</sub> of leaf size
-    uint64_t m_max_leaves;              ///< Maximum number of leaves
-    std::vector<machine_hash> m_tree;   ///< Binary heap with tree node hashes
-    hash_function_type m_hash_function; ///< Hash function
-};
-
-} // namespace cartesi
-
-#endif
diff --git a/src/merkle-tree-hash.cpp b/src/hash-tree-hash.cpp
similarity index 89%
rename from src/merkle-tree-hash.cpp
rename to src/hash-tree-hash.cpp
index 5797bf9ba..7d8490448 100644
--- a/src/merkle-tree-hash.cpp
+++ b/src/hash-tree-hash.cpp
@@ -14,7 +14,6 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#include <cassert>
 #include <cstdarg>
 #include <cstddef>
 #include <cstdint>
@@ -23,10 +22,13 @@
 #include <cstring>
 #include <exception>
 #include <iostream>
+#include <span>
 #include <tuple>
 
+#include "assert-printf.h"
 #include "back-merkle-tree.h"
 #include "i-hasher.h"
+#include "machine-hash.h"
 #include "unique-c-ptr.h"
 #include "variant-hasher.h"
 
@@ -119,13 +121,13 @@ static void get_word_hash(variant_hasher &h, const unsigned char *word, int log2
     h.hash(std::span<const unsigned char>(word, 1 << log2_word_size), hash);
 }
 
-/// \brief Computes the Merkle hash of a leaf of data
+/// \brief Computes the hash tree hash of a leaf of data
 /// \param h Hasher object
 /// \param leaf_data Pointer to buffer containing leaf data with
 /// at least 2^log2_leaf_size bytes
 /// \param log2_leaf_size Log<sub>2</sub> of leaf size
 /// \param log2_word_size Log<sub>2</sub> of word size
-/// \returns Merkle hash of leaf data
+/// \returns Hash tree hash of leaf data
 static machine_hash get_leaf_hash(variant_hasher &h, const unsigned char *leaf_data, int log2_leaf_size,
     int log2_word_size) {
     assert(log2_word_size >= 1);
@@ -148,7 +150,7 @@ static void help(const char *name) {
 
   %s --log2-root-size=<integer> [options]
 
-Computes the Merkle tree root hash of 2^log2_root_size bytes read from
+Computes the hash tree root hash of 2^log2_root_size bytes read from
 a file. If the file contains fewer than 2^log2_root_size bytes, it is
 ostensibly padded with zeros to 2^log2_root_size bytes.
 
@@ -159,7 +161,7 @@ with 2^(log2_node_size-1) bytes.
 The node hash corresponding to word with 2^log2_word_size bytes is simply
 the hash of the data in the range.
 
-The Merkle tree root hash is simply the node hash corresponding to the
+The hash tree root hash is simply the node hash corresponding to the
 entire 2^log2_root_size range.
 
 The hash function used is Keccak-256.
@@ -178,6 +180,9 @@ The hash function used is Keccak-256.
   (> 0 and <= log2_root_size)
   The granularity in which bytes are read from the input file.
 
+  --hash-function=<string>              default: keccak256
+  The hash function to use, can be "keccak256" or "sha256".
+
   --help
   Prints this message and returns.
 )",
@@ -187,6 +192,7 @@ The hash function used is Keccak-256.
 
 int main(int argc, char *argv[]) try {
     const char *input_name = nullptr;
+    const char *hash_function_name = "keccak256";
     int log2_word_size = 3;
     int log2_leaf_size = 12;
     int log2_root_size = 0;
@@ -195,6 +201,7 @@ int main(int argc, char *argv[]) try {
         if (strcmp(argv[i], "--help") == 0) {
             help(argv[0]);
         } else if (stringval("--input=", argv[i], &input_name) ||
+            stringval("--hash-function=", argv[i], &hash_function_name) ||
             intval("--log2-word-size=", argv[i], &log2_word_size) ||
             intval("--log2-leaf-size=", argv[i], &log2_leaf_size) ||
             intval("--log2-root-size=", argv[i], &log2_root_size)) {
@@ -215,6 +222,14 @@ int main(int argc, char *argv[]) try {
             log2_leaf_size, log2_root_size);
         return 1;
     }
+    hash_function_type hash_function{};
+    if (std::string{hash_function_name} == "keccak256") {
+        hash_function = hash_function_type::keccak256;
+    } else if (std::string{hash_function_name} == "sha256") {
+        hash_function = hash_function_type::sha256;
+    } else {
+        error("invalid hash function name '%s'\n", hash_function_name);
+    }
     // Read from stdin if no input name was given
     auto input_file = unique_file_ptr{stdin};
     if (input_name != nullptr) {
@@ -233,7 +248,8 @@ int main(int argc, char *argv[]) try {
         return 1;
     }
 
-    const auto hash_function = hash_function_type::keccak256;
+    const auto pristine_pad_hashes =
+        back_merkle_tree::make_pristine_pad_hashes(log2_root_size, log2_leaf_size, log2_word_size, hash_function);
     back_merkle_tree back_tree{log2_root_size, log2_leaf_size, log2_word_size, hash_function};
     variant_hasher h{hash_function};
 
@@ -262,6 +278,7 @@ int main(int argc, char *argv[]) try {
         // proof-by-proof tree
         ++leaf_count;
     }
+    back_tree.pad_back(back_tree.get_remaining_leaf_count(), pristine_pad_hashes);
     print_hash(back_tree.get_root_hash(), stdout);
     return 0;
 } catch (const std::exception &e) {
diff --git a/src/hash-tree-proof.h b/src/hash-tree-proof.h
index 0d5b76b5e..c6560243b 100644
--- a/src/hash-tree-proof.h
+++ b/src/hash-tree-proof.h
@@ -22,13 +22,12 @@
 
 #include <algorithm>
 #include <cstdint>
-#include <ranges>
 #include <stdexcept>
-#include <type_traits>
+#include <utility>
 #include <vector>
 
 #include "i-hasher.h"
-#include "meta.h"
+#include "machine-hash.h"
 
 namespace cartesi {
 
@@ -250,7 +249,7 @@ class hash_tree_proof final {
     /// \return Index into siblings array, or throws exception if out of bounds
     int log2_size_to_index(int log2_size) const {
         const int index = log2_size - m_log2_target_size;
-        if (index < 0 || index >= static_cast<int>(m_sibling_hashes.size())) {
+        if (index < 0 || std::cmp_greater_equal(index, m_sibling_hashes.size())) {
             throw std::out_of_range{"log2_size is out of range"};
         }
         return index;
diff --git a/src/hash-tree.cpp b/src/hash-tree.cpp
index b64b3a2e7..30e5749d2 100644
--- a/src/hash-tree.cpp
+++ b/src/hash-tree.cpp
@@ -16,26 +16,41 @@
 
 #include "hash-tree.h"
 
+#include <algorithm>
+#include <array>
 #include <bit>
+#include <cassert>
+#include <concepts>
+#include <cstddef>
+#include <cstdint>
+#include <functional>
 #include <iostream>
+#include <iterator>
 #include <queue>
 #include <ranges>
+#include <span>
 #include <string>
+#include <type_traits>
 #include <utility>
+#include <vector>
 
-#include "algorithm.h"
-#include "os-features.h"
+#include "os-features.h" // IWYU pragma: keep
 
 #ifdef HAVE_OPENMP
 #include <omp.h>
 #endif
 
+#include "address-range.h"
+#include "algorithm.h"
+#include "hash-tree-constants.h"
+#include "hash-tree-stats.h"
 #include "i-hasher.h"
-#include "machine-address-ranges.h"
+#include "machine-config.h"
 #include "machine-hash.h"
 #include "page-hash-tree-cache-stats.h"
 #include "signposts.h"
 #include "simd-hasher.h"
+#include "variant-hasher.h"
 
 namespace cartesi {
 
@@ -92,7 +107,7 @@ void hash_tree::get_page_proof(address_range &ar, uint64_t address, proof_type &
         proof.set_sibling_hash(entry.node_hash_view(get_sibling_address(node_offset, log2_size), log2_size), log2_size);
     }
     proof.set_target_hash(entry.node_hash_view(node_offset, log2_target_size));
-    m_page_cache.return_entry(*opt_br);
+    page_hash_tree_cache::return_entry(*opt_br);
 }
 
 void hash_tree::get_dense_proof(address_range &ar, int ar_log2_size, uint64_t address, proof_type &proof) {
@@ -134,7 +149,7 @@ hash_tree::proof_type hash_tree::get_proof(address_ranges ars, uint64_t address,
             break;
         }
         const auto &node = m_sparse_nodes[node_index];
-        assert(static_cast<int>(node.log2_size) == curr_log2_size && "incorrect node log2_size");
+        assert(std::cmp_equal(node.log2_size, curr_log2_size) && "incorrect node log2_size");
         // hit sparse tree node
         if (curr_log2_size == log2_size) {
             proof.set_target_hash(node.hash);
@@ -280,11 +295,11 @@ bool hash_tree::return_updated_dirty_pages(address_ranges ars, dirty_pages &batc
     for (auto &[ar_index, br, changed] : batch) {
         auto &ar = ars[ar_index];
         auto offset = br.get_paddr_page() - ar.get_start();
-        if (m_page_cache.return_entry(br)) {
+        if (page_hash_tree_cache::return_entry(br)) {
             // If page hash was changed during update
             if (changed) {
                 // If we haven't already done so, add changed address range to list
-                algorithm::try_push_back(changed_ars, ar_index);
+                try_push_back(changed_ars, ar_index);
                 // If page was marked dirty but was not in fact dirty
             } else {
                 // We can safely mark the page clean because its contents already matched its hash
@@ -515,7 +530,7 @@ machine_hash hash_tree::get_dense_node_hash(address_range &ar, uint64_t address,
         }
         auto node_offset = address - paddr_page;
         auto hash = to_hash(opt_br->get().node_hash_view(node_offset, log2_size));
-        m_page_cache.return_entry(*opt_br);
+        page_hash_tree_cache::return_entry(*opt_br);
         return hash;
     }
     const auto offset = address - ar.get_start();
@@ -541,7 +556,7 @@ machine_hash hash_tree::get_node_hash(address_ranges ars, uint64_t address, int
             return m_pristine_hashes[log2_size];
         }
         const auto &node = m_sparse_nodes[node_index];
-        assert(static_cast<int>(node.log2_size) == curr_log2_size && "incorrect node log2_size");
+        assert(std::cmp_equal(node.log2_size, curr_log2_size) && "incorrect node log2_size");
         // hit sparse tree node
         if (curr_log2_size == log2_size) {
             return node.hash;
@@ -567,7 +582,7 @@ bool hash_tree::verify(address_ranges ars) const {
     variant_hasher h{m_hash_function};
     bool ret = true;
     for (auto ar_node_index = get_ar_sparse_node_index(0); const auto &ar : ars) {
-        const std::span<const unsigned char> mem{ar.get_host_memory(), ar.get_length()};
+        const std::span<const unsigned char> mem{ar.get_host_memory(), static_cast<size_t>(ar.get_length())};
         const auto &dht = ar.get_dense_hash_tree();
         const auto &dpt = ar.get_dirty_page_tree();
         auto ar_actually_dirty = false;
@@ -603,7 +618,7 @@ bool hash_tree::verify(address_ranges ars) const {
                                           << " differs\n";
                             }
                         }
-                        m_page_cache.return_entry(cache_entry);
+                        page_hash_tree_cache::return_entry(cache_entry);
                     }
                     std::cerr << "! FAILED!\n";
                 }
@@ -699,16 +714,16 @@ bool hash_tree::update_words(address_ranges ars, const dirty_words_type &dirty_w
         }
         if (ar_index >= static_cast<int>(ars.size())) {
             ++update_failures;
-            m_page_cache.return_entry(cache_entry);
+            page_hash_tree_cache::return_entry(cache_entry);
             continue;
         }
         auto &ar = ars[ar_index];
-        algorithm::try_push_back(changed_ars, ar_index);
+        try_push_back(changed_ars, ar_index);
         max_level_count = std::max(max_level_count, ar.get_level_count());
         const auto *base = ar.get_host_memory();
         if (!ar.is_memory() || base == nullptr) {
             ++update_failures;
-            m_page_cache.return_entry(cache_entry);
+            page_hash_tree_cache::return_entry(cache_entry);
             continue;
         }
         const auto page_offset = paddr_page - ar.get_start();
@@ -736,15 +751,15 @@ bool hash_tree::update_words(address_ranges ars, const dirty_words_type &dirty_w
             bool changed = false;
             if (!update_dirty_page(ar, cache_entry, changed)) {
                 ++update_failures;
-                m_page_cache.return_entry(cache_entry);
+                page_hash_tree_cache::return_entry(cache_entry);
                 continue;
             }
         }
         auto &dht = ar.get_dense_hash_tree();
         auto node_hash_view = dht.node_hash_view(page_offset, HASH_TREE_LOG2_PAGE_SIZE);
         std::ranges::copy(cache_entry.root_hash_view(), node_hash_view.begin());
-        m_page_cache.return_entry(cache_entry);
-        algorithm::try_push_back(curr_dense_node,
+        page_hash_tree_cache::return_entry(cache_entry);
+        try_push_back(curr_dense_node,
             dense_node_entry{.dht = dht, .offset = get_aligned_address(page_offset, HASH_TREE_LOG2_PAGE_SIZE + 1)});
     }
     for (int level = 1; level < max_level_count; ++level) {
@@ -758,7 +773,7 @@ bool hash_tree::update_words(address_ranges ars, const dirty_words_type &dirty_w
             auto left = dht.node_hash_view(offset, log2_size - 1);
             auto right = dht.node_hash_view(offset + child_size, log2_size - 1);
             queue.enqueue(left, right, parent);
-            algorithm::try_push_back(next_dense_node,
+            try_push_back(next_dense_node,
                 dense_node_entry{.dht = dht, .offset = get_aligned_address(offset, log2_size + 1)});
         }
         queue.flush();
@@ -788,7 +803,7 @@ bool hash_tree::update_page(address_ranges ars, uint64_t paddr_page) {
     update_dirty_page(ar, entry, changed);
     // If nothing changed, we are done
     if (!changed) {
-        m_page_cache.return_entry(entry);
+        page_hash_tree_cache::return_entry(entry);
         return true;
     }
     // Copy new page hash to address range's dense hash tree
@@ -814,7 +829,7 @@ bool hash_tree::update_page(address_ranges ars, uint64_t paddr_page) {
     int log2_size = ar_log2_size + 1;
     while (node_index != 0) {
         auto &node = m_sparse_nodes[node_index];
-        assert(log2_size == static_cast<int>(node.log2_size) && "invalid sparse node log2_size");
+        assert(std::cmp_equal(log2_size, node.log2_size) && "invalid sparse node log2_size");
         auto left_hash_view = get_sparse_node_hash_view(node.left, log2_size - 1);
         auto right_hash_view = get_sparse_node_hash_view(node.right, log2_size - 1);
         get_concat_hash(h, left_hash_view, right_hash_view, node.hash);
@@ -822,7 +837,7 @@ bool hash_tree::update_page(address_ranges ars, uint64_t paddr_page) {
         ++log2_size;
     }
     assert(log2_size == HASH_TREE_LOG2_ROOT_SIZE + 1 && "invalid sparse tree log2_size");
-    m_page_cache.return_entry(entry);
+    page_hash_tree_cache::return_entry(entry);
     return true;
 }
 
@@ -836,7 +851,7 @@ hash_tree::pristine_hashes hash_tree::get_pristine_hashes(hash_function_type has
         get_concat_hash(h, hash, hash, hash);
     }
     return hashes;
-};
+}
 
 static int get_concurrency([[maybe_unused]] int value) {
 #ifdef HAVE_OPENMP
@@ -857,7 +872,7 @@ hash_tree::hash_tree(const hash_tree_config &config, uint64_t concurrency, const
     m_spid_update_sparse_tree{os_signpost_id_generate(m_log)},
     m_page_cache{m_log, variant_hasher{hash_function}, config.phtc_size},
 #else
-    m_page_cache{variant_hasher{hash_function}, config.phtc_size},
+    m_page_cache{variant_hasher{hash_function}, static_cast<size_t>(config.phtc_size)},
 #endif
     m_sparse_nodes{create_nodes(ars)},
     m_pristine_hashes{get_pristine_hashes(hash_function)},
diff --git a/src/hash-tree.h b/src/hash-tree.h
index 260f94727..009cf4640 100644
--- a/src/hash-tree.h
+++ b/src/hash-tree.h
@@ -17,8 +17,14 @@
 #ifndef HASH_TREE_H
 #define HASH_TREE_H
 
+#include <array>
+#include <concepts>
+#include <cstdint>
 #include <iosfwd>
+#include <iterator>
 #include <memory_resource>
+#include <ranges>
+#include <type_traits>
 #include <vector>
 
 #include "unordered_dense.h"
@@ -27,14 +33,18 @@
 #include "hash-tree-constants.h"
 #include "hash-tree-proof.h"
 #include "hash-tree-stats.h"
+#include "i-dense-hash-tree.h"
 #include "machine-address-ranges.h"
 #include "machine-config.h"
 #include "machine-hash.h"
+#include "page-hash-tree-cache-stats.h"
 #include "page-hash-tree-cache.h"
-#include "signposts.h"
-#include "unique-c-ptr.h"
 #include "variant-hasher.h"
 
+#ifdef HAS_SIGNPOSTS
+#include "signposts.h"
+#endif
+
 namespace cartesi {
 
 class hash_tree {
@@ -86,7 +96,7 @@ class hash_tree {
 
     // This is ensures we use the hash_tree_view of machine_address_ranges everywhere
     template <typename MAR>
-    class hash_tree_view : public std::ranges::view_interface<hash_tree_view<MAR>> {
+    class hash_tree_view final : public std::ranges::view_interface<hash_tree_view<MAR>> {
         using V = decltype(std::declval<MAR>().hash_tree_view());
         static_assert(std::ranges::random_access_range<V>, "not a random access range");
         static_assert(std::ranges::view<V>, "not a view");
diff --git a/src/host-addr.h b/src/host-addr.h
index a8941e2ca..f6ea8025b 100644
--- a/src/host-addr.h
+++ b/src/host-addr.h
@@ -17,6 +17,8 @@
 #ifndef HOST_ADDR_H
 #define HOST_ADDR_H
 
+#include <cstdint>
+
 #include "strict-aliasing.h"
 
 namespace cartesi {
diff --git a/src/hot-tlb.h b/src/hot-tlb.h
index 471d461c3..97c102296 100644
--- a/src/hot-tlb.h
+++ b/src/hot-tlb.h
@@ -22,7 +22,6 @@
 /// \details The Translation Lookaside Buffer is a small cache used to speed up translation between address spaces.
 
 #include <array>
-#include <cstddef>
 #include <cstdint>
 
 #include "host-addr.h"
diff --git a/src/htif-address-range.cpp b/src/htif-address-range.cpp
index 4af6019ce..959a6bc43 100644
--- a/src/htif-address-range.cpp
+++ b/src/htif-address-range.cpp
@@ -20,6 +20,7 @@
 
 #include "htif-constants.h"
 #include "i-device-state-access.h"
+#include "interpret.h"
 
 namespace cartesi {
 
diff --git a/src/htif-address-range.h b/src/htif-address-range.h
index a7daa8a07..72a503f11 100644
--- a/src/htif-address-range.h
+++ b/src/htif-address-range.h
@@ -22,7 +22,9 @@
 #include "address-range-constants.h"
 #include "address-range.h"
 #include "i-device-state-access.h"
+#include "interpret.h"
 #include "pmas-constants.h"
+#include "pmas.h"
 
 /// \file
 /// \brief Host-Target InterFace device.
diff --git a/src/htif-constants.h b/src/htif-constants.h
index 744f69bba..73cc59358 100644
--- a/src/htif-constants.h
+++ b/src/htif-constants.h
@@ -26,12 +26,6 @@
 
 namespace cartesi {
 
-// helper for using UINT64_C with defines
-#ifndef EXPAND_UINT64_C
-// NOLINTNEXTLINE(cppcoreguidelines-macro-usage)
-#define EXPAND_UINT64_C(a) UINT64_C(a)
-#endif
-
 // Forward declarations
 /// \brief HTIF shifts
 enum HTIF_shifts {
diff --git a/src/htif-defines.h b/src/htif-defines.h
index 9147b3ae9..c07e7472e 100644
--- a/src/htif-defines.h
+++ b/src/htif-defines.h
@@ -49,6 +49,12 @@
 /* reply */
 #define HTIF_YIELD_REASON_ADVANCE_STATE_DEF 0
 #define HTIF_YIELD_REASON_INSPECT_STATE_DEF 1
+
+// helper for using UINT64_C with defines
+#ifndef EXPAND_UINT64_C
+#define EXPAND_UINT64_C(a) UINT64_C(a)
+#endif
+
 // NOLINTEND(cppcoreguidelines-macro-usage,cppcoreguidelines-macro-to-enum,modernize-macro-to-enum)
 
 #endif /* end of include guard: HTIF_DEFINES_H */
diff --git a/src/i-accept-counters.h b/src/i-accept-counters.h
index 1b944d352..d2ec50485 100644
--- a/src/i-accept-counters.h
+++ b/src/i-accept-counters.h
@@ -32,6 +32,8 @@ namespace cartesi {
 /// \tparam DERIVED Derived class implementing the interface. (An example of CRTP.)
 template <typename DERIVED>
 class i_accept_counters { // CRTP
+    i_accept_counters() = default;
+    friend DERIVED;
 
     /// \brief Returns object cast as the derived class
     DERIVED &derived() {
diff --git a/src/i-accept-scoped-notes.h b/src/i-accept-scoped-notes.h
index 1c1220269..08f3ccb43 100644
--- a/src/i-accept-scoped-notes.h
+++ b/src/i-accept-scoped-notes.h
@@ -21,14 +21,16 @@
 /// \brief Accept scoped notes interface
 
 #include <cstdarg>
-#include <cstdint>
 #include <type_traits>
 
+#include "meta.h"
+
+#ifdef DUMP_SCOPED_NOTE
 #include "assert-printf.h"
 #include "i-state-access.h"
 #include "i-uarch-state-access.h"
-#include "meta.h"
 #include "scoped-note.h"
+#endif
 
 namespace cartesi {
 
@@ -37,6 +39,8 @@ namespace cartesi {
 /// \tparam DERIVED Derived class implementing the interface. (An example of CRTP.)
 template <typename DERIVED>
 class i_accept_scoped_notes { // CRTP
+    i_accept_scoped_notes() = default;
+    friend DERIVED;
 
     /// \brief Returns object cast as the derived class
     DERIVED &derived() {
diff --git a/src/i-dense-hash-tree.h b/src/i-dense-hash-tree.h
index 951eee653..29ea50c65 100644
--- a/src/i-dense-hash-tree.h
+++ b/src/i-dense-hash-tree.h
@@ -17,7 +17,8 @@
 #ifndef I_DENSE_HASH_TREE_H
 #define I_DENSE_HASH_TREE_H
 
-#include "hash-tree-constants.h"
+#include <cstdint>
+
 #include "machine-hash.h"
 
 namespace cartesi {
@@ -56,7 +57,7 @@ class i_dense_hash_tree {
     virtual const_machine_hash_view do_root_hash_view() const noexcept = 0;
 };
 
-class empty_dense_hash_tree : public i_dense_hash_tree {
+class empty_dense_hash_tree final : public i_dense_hash_tree {
     const_machine_hash_view do_node_hash_view(uint64_t /*offset*/, int /*log2_size*/) const noexcept override {
         return no_hash_view();
     }
diff --git a/src/i-dirty-page-tree.h b/src/i-dirty-page-tree.h
index 07e146a5b..90fd354c1 100644
--- a/src/i-dirty-page-tree.h
+++ b/src/i-dirty-page-tree.h
@@ -24,6 +24,7 @@
 #include <iterator>
 #include <limits>
 #include <ranges>
+#include <type_traits>
 
 #include "address-range-constants.h"
 
@@ -67,9 +68,9 @@ class i_dirty_page_tree {
     constexpr positions_range level_positions_view(int level) const {
         if (level >= 0 && level < level_count()) {
             const auto begin = position_iterator::value_type{1} << (level_count() - level - 1);
-            return {begin, 2 * begin};
+            return positions_range{begin, 2 * begin};
         }
-        return {invalid_position, invalid_position};
+        return positions_range{invalid_position, invalid_position};
     }
 
     /// \brief Returns number of levels in tree, from root to leaves
@@ -257,7 +258,7 @@ class i_dirty_page_tree {
     i_dirty_page_tree &operator=(i_dirty_page_tree &&other) = default;
 
     // NOLINTNEXTLINE(hicpp-use-equals-default,modernize-use-equals-default)
-    constexpr virtual ~i_dirty_page_tree() {}; // = default; // doesn't work due to bug in gcc
+    constexpr virtual ~i_dirty_page_tree() {} // = default; // doesn't work due to bug in gcc
 
     /// \brief Returns view over the starting offset of all dirty nodes of a given log2_size
     /// \param log2_size Log<sub>2</sub> of node size
@@ -349,7 +350,7 @@ class empty_dirty_page_tree final : public i_dirty_page_tree {
     empty_dirty_page_tree(empty_dirty_page_tree &&other) = default;
     empty_dirty_page_tree &operator=(empty_dirty_page_tree &&other) = default;
     // NOLINTNEXTLINE(hicpp-use-equals-default,modernize-use-equals-default)
-    constexpr ~empty_dirty_page_tree() override {}; // = default; // doesn't work due to bug in gcc
+    constexpr ~empty_dirty_page_tree() override {} // = default; // doesn't work due to bug in gcc
 };
 
 } // namespace cartesi
diff --git a/src/i-hasher.h b/src/i-hasher.h
index 1b67965cb..5e149c8ea 100644
--- a/src/i-hasher.h
+++ b/src/i-hasher.h
@@ -20,12 +20,14 @@
 /// \file
 /// \brief Hasher interface
 
+#include <array>
 #include <cstddef>
 #include <cstdint>
 #include <ranges>
 #include <span>
 #include <stdexcept>
 #include <type_traits>
+#include <utility>
 
 #include "array2d.h"
 #include "concepts.h"
@@ -42,6 +44,9 @@ using const_hash_tree_word_view = std::span<const unsigned char, HASH_TREE_WORD_
 /// \tparam DERIVED Derived class implementing the interface. (An example of CRTP.)
 template <typename DERIVED>
 class i_hasher { // CRTP
+    i_hasher() = default;
+    friend DERIVED;
+
     /// \brief Returns object cast as the derived class
     DERIVED &derived() {
         return *static_cast<DERIVED *>(this);
diff --git a/src/i-interactive-state-access.h b/src/i-interactive-state-access.h
index 33229bfe9..7f4a4e4c5 100644
--- a/src/i-interactive-state-access.h
+++ b/src/i-interactive-state-access.h
@@ -32,6 +32,8 @@ namespace cartesi {
 /// \tparam DERIVED Derived class implementing the interface. (An example of CRTP.)
 template <typename DERIVED>
 class i_interactive_state_access { // CRTP
+    i_interactive_state_access() = default;
+    friend DERIVED;
 
     /// \brief Returns object cast as the derived class
     DERIVED &derived() {
diff --git a/src/i-machine.h b/src/i-machine.h
index 57e732ea4..54f162565 100644
--- a/src/i-machine.h
+++ b/src/i-machine.h
@@ -18,16 +18,19 @@
 #define I_MACHINE_H
 
 #include <cstdint>
+#include <optional>
 #include <string>
 
 #include "access-log.h"
 #include "address-range-description.h"
+#include "back-merkle-tree.h"
 #include "hash-tree-proof.h"
 #include "hash-tree-stats.h"
 #include "interpret.h"
 #include "machine-config.h"
 #include "machine-hash.h"
 #include "machine-reg.h"
+#include "machine-runtime-config.h"
 #include "mcycle-root-hashes.h"
 #include "uarch-cycle-root-hashes.h"
 #include "uarch-interpret.h"
@@ -89,9 +92,10 @@ class i_machine {
 
     /// \brief Collects the root hashes after every \p mcycle_period machine cycles until mcycle reaches \p mcycle_end,
     /// or if the machine halts or yields.
-    void collect_mcycle_root_hashes(uint64_t mcycle_end, uint64_t mcycle_period, uint64_t mcycle_phase,
-        uint32_t log2_bundle_mcycle_count, mcycle_root_hashes &result) {
-        do_collect_mcycle_root_hashes(mcycle_end, mcycle_period, mcycle_phase, log2_bundle_mcycle_count, result);
+    mcycle_root_hashes collect_mcycle_root_hashes(uint64_t mcycle_end, uint64_t mcycle_period, uint64_t mcycle_phase,
+        int32_t log2_bundle_mcycle_count, const std::optional<back_merkle_tree> &previous_back_tree) {
+        return do_collect_mcycle_root_hashes(mcycle_end, mcycle_period, mcycle_phase, log2_bundle_mcycle_count,
+            previous_back_tree);
     }
 
     /// \brief Serialize entire state to directory
@@ -114,22 +118,22 @@ class i_machine {
         return do_log_step_uarch(log_type);
     }
 
-    /// \brief Obtains the proof for a node in the Merkle tree.
+    /// \brief Obtains the proof for a node in the hash tree.
     hash_tree_proof get_proof(uint64_t address, int log2_size) const {
         return do_get_proof(address, log2_size);
     }
 
-    /// \brief Obtains the root hash of the Merkle tree.
+    /// \brief Obtains the root hash of the hash tree.
     machine_hash get_root_hash() const {
         return do_get_root_hash();
     }
 
-    /// \brief Obtains the root hash of the Merkle tree.
+    /// \brief Obtains the root hash of the hash tree.
     machine_hash get_node_hash(uint64_t address, int log2_size) const {
         return do_get_node_hash(address, log2_size);
     }
 
-    /// \brief Verifies integrity of Merkle tree.
+    /// \brief Verifies integrity of hash tree.
     bool verify_hash_tree() const {
         return do_verify_hash_tree();
     }
@@ -229,9 +233,9 @@ class i_machine {
 
     /// \brief Collects the root hashes after every \p uarch_cycle until \p mcycle_end machine cycle, implicitly
     /// resetting the uarch between mcycles.
-    void collect_uarch_cycle_root_hashes(uint64_t mcycle_end, uint32_t log2_bundle_uarch_cycle_count,
-        uarch_cycle_root_hashes &result) {
-        do_collect_uarch_cycle_root_hashes(mcycle_end, log2_bundle_uarch_cycle_count, result);
+    uarch_cycle_root_hashes collect_uarch_cycle_root_hashes(uint64_t mcycle_end,
+        int32_t log2_bundle_uarch_cycle_count) {
+        return do_collect_uarch_cycle_root_hashes(mcycle_end, log2_bundle_uarch_cycle_count);
     }
 
     /// \brief Returns a list of descriptions for all PMA entries registered in the machine, sorted by start
@@ -296,8 +300,9 @@ class i_machine {
         const std::string &dir) = 0;
     virtual void do_load(const std::string &directory, const machine_runtime_config &runtime, sharing_mode sharing) = 0;
     virtual interpreter_break_reason do_run(uint64_t mcycle_end) = 0;
-    virtual void do_collect_mcycle_root_hashes(uint64_t mcycle_end, uint64_t mcycle_period, uint64_t mcycle_phase,
-        uint32_t log2_bundle_mcycle_count, mcycle_root_hashes &result) = 0;
+    virtual mcycle_root_hashes do_collect_mcycle_root_hashes(uint64_t mcycle_end, uint64_t mcycle_period,
+        uint64_t mcycle_phase, int32_t log2_bundle_mcycle_count,
+        const std::optional<back_merkle_tree> &previous_back_tree) = 0;
     virtual void do_store(const std::string &dir, sharing_mode sharing) const = 0;
     virtual void do_clone_stored(const std::string &from_dir, const std::string &to_dir) const = 0;
     virtual interpreter_break_reason do_log_step(uint64_t mcycle_count, const std::string &filename) = 0;
@@ -323,8 +328,8 @@ class i_machine {
     virtual void do_reset_uarch() = 0;
     virtual access_log do_log_reset_uarch(const access_log::type &log_type) = 0;
     virtual uarch_interpreter_break_reason do_run_uarch(uint64_t uarch_cycle_end) = 0;
-    virtual void do_collect_uarch_cycle_root_hashes(uint64_t mcycle_end, uint32_t log2_bundle_uarch_cycle_count,
-        uarch_cycle_root_hashes &result) = 0;
+    virtual uarch_cycle_root_hashes do_collect_uarch_cycle_root_hashes(uint64_t mcycle_end,
+        int32_t log2_bundle_uarch_cycle_count) = 0;
     virtual address_range_descriptions do_get_address_ranges() const = 0;
     virtual void do_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length) = 0;
     virtual access_log do_log_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
diff --git a/src/i-prefer-shadow-state.h b/src/i-prefer-shadow-state.h
index dd75b9f56..7b22db40b 100644
--- a/src/i-prefer-shadow-state.h
+++ b/src/i-prefer-shadow-state.h
@@ -26,7 +26,6 @@
 
 #include "meta.h"
 #include "shadow-registers.h"
-#include "shadow-tlb.h"
 
 namespace cartesi {
 
@@ -36,6 +35,8 @@ namespace cartesi {
 /// \detail This is for state access methods that do not need individualized access to machine registers.
 template <typename DERIVED>
 class i_prefer_shadow_state { // CRTP
+    i_prefer_shadow_state() = default;
+    friend DERIVED;
 
     /// \brief Returns object cast as the derived class
     DERIVED &derived() {
diff --git a/src/i-prefer-shadow-uarch-state.h b/src/i-prefer-shadow-uarch-state.h
index af9319cf1..eda1e6a8a 100644
--- a/src/i-prefer-shadow-uarch-state.h
+++ b/src/i-prefer-shadow-uarch-state.h
@@ -25,7 +25,6 @@
 #include <type_traits>
 
 #include "meta.h"
-#include "shadow-tlb.h"
 #include "shadow-uarch-state.h"
 
 namespace cartesi {
@@ -36,6 +35,8 @@ namespace cartesi {
 /// \detail This is for state access methods that do not need individualized access to uarch registers.
 template <typename DERIVED>
 class i_prefer_shadow_uarch_state { // CRTP
+    i_prefer_shadow_uarch_state() = default;
+    friend DERIVED;
 
     /// \brief Returns object cast as the derived class
     DERIVED &derived() {
diff --git a/src/i-state-access.h b/src/i-state-access.h
index e216b3d4e..053453e41 100644
--- a/src/i-state-access.h
+++ b/src/i-state-access.h
@@ -24,12 +24,13 @@
 #include <cstdarg>
 #include <cstdint>
 #include <type_traits>
-#include <utility>
 
+#include "address-range.h"
 #include "assert-printf.h"
 #include "i-prefer-shadow-state.h"
 #include "meta.h"
 #include "poor-type-name.h"
+#include "shadow-registers.h"
 #include "shadow-tlb.h"
 
 namespace cartesi {
@@ -337,7 +338,7 @@ class i_state_access { // CRTP
     /// \param pma_index Index of PMA where word falls.
     /// \param pval Pointer to word receiving value.
     /// \warning T must not cross page boundary starting from \p faddr.
-    /// \warning T (when A is smaller) may or may not cross a Merkle tree word boundary starting from \p faddr!
+    /// \warning T (when A is smaller) may or may not cross a hash tree word boundary starting from \p faddr!
     template <typename T, typename A = T>
     void read_memory_word(fast_addr faddr, uint64_t pma_index, T *pval) const {
         static_assert(std::is_integral_v<T> && sizeof(T) <= sizeof(uint64_t), "unsupported type");
@@ -354,7 +355,7 @@ class i_state_access { // CRTP
     /// \param faddr Implementation-defined fast address.
     /// \param val Value to be written.
     /// \warning T must not cross page boundary starting from \p faddr.
-    /// \warning T (when A is smaller) may or may not cross a Merkle tree word boundary starting from \p faddr!
+    /// \warning T (when A is smaller) may or may not cross a hash tree word boundary starting from \p faddr!
     template <typename T, typename A = T>
     void write_memory_word(fast_addr faddr, uint64_t pma_index, T val) const {
         static_assert(std::is_integral_v<T> && sizeof(T) <= sizeof(uint64_t), "unsupported type");
@@ -421,9 +422,9 @@ class i_state_access { // CRTP
     /// \brief Marks a page as dirty
     /// \param faddr Implementation-defined fast address.
     /// \param pma_index Index of PMA where page falls
-    /// \details When there is a host machine, the Merkle tree only updates the hashes for pages that
+    /// \details When there is a host machine, the hash tree only updates the hashes for pages that
     /// have been modified. Pages can only be written to if they appear in the write TLB. Therefore,
-    /// the Merkle tree only considers the pages that are currently in the write TLB and those that
+    /// the hash tree only considers the pages that are currently in the write TLB and those that
     /// have been marked dirty. When a page leaves the write TLB, it is marked dirty.
     /// If the state belongs to a host machine, then this call MUST be forwarded to machine::mark_dirty_page();
     void mark_dirty_page(fast_addr faddr, uint64_t pma_index) const {
diff --git a/src/i-uarch-state-access.h b/src/i-uarch-state-access.h
index d697eb153..a80adb2ef 100644
--- a/src/i-uarch-state-access.h
+++ b/src/i-uarch-state-access.h
@@ -20,11 +20,13 @@
 #include <cinttypes>
 #include <cstdarg>
 #include <cstdint>
+#include <type_traits>
 
-#include "assert-printf.h"
+#include "assert-printf.h" // IWYU pragma: keep
 #include "i-prefer-shadow-uarch-state.h"
 #include "meta.h"
 #include "shadow-tlb.h"
+#include "shadow-uarch-state.h"
 
 // NOLINTBEGIN(cppcoreguidelines-macro-usage)
 #define DEFINE_USA_READ(REG)                                                                                           \
diff --git a/src/interpret.cpp b/src/interpret.cpp
index 0f3837e70..52e0711ac 100644
--- a/src/interpret.cpp
+++ b/src/interpret.cpp
@@ -91,25 +91,27 @@
 #include <utility>
 
 #ifdef MICROARCHITECTURE
+#include "../uarch/uarch-runtime.h"
 #include "machine-uarch-bridge-state-access.h"
 #else
-#include "collect-mcycle-hashes-state-access.h"
-#include "record-step-state-access.h"
-#include "replay-step-state-access.h"
-#include "state-access.h"
+#include "collect-mcycle-hashes-state-access.h" // IWYU pragma: keep
+#include "record-step-state-access.h"           // IWYU pragma: keep
+#include "replay-step-state-access.h"           // IWYU pragma: keep
+#include "state-access.h"                       // IWYU pragma: keep
+
 #endif // MICROARCHITECTURE
 
 #include "assert-printf.h"
 #include "compiler-defines.h"
 #include "device-state-access.h"
 #include "find-pma.h"
-#include "hot-tlb.h"
-#include "i-accept-counters.h"
+#include "i-accept-counters.h" // IWYU pragma: keep
 #include "i-interactive-state-access.h"
 #include "i-state-access.h"
 #include "meta.h"
 #include "riscv-constants.h"
 #include "rtc.h"
+#include "shadow-tlb.h"
 #include "soft-float.h"
 #include "translate-virtual-address.h"
 #include "uint128.h"
@@ -871,7 +873,7 @@ static void flush_tlb_slot(const STATE_ACCESS a, uint64_t slot_index) {
     // Make sure a valid page leaving the write TLB is marked as dirty
     // We must do this BEFORE we modify the TLB entries themselves
     // (Otherwise, we could stop uarch before it marks the page dirty but after
-    // the entry is no longer in the TLB, which would cause the Merkle tree to
+    // the entry is no longer in the TLB, which would cause the hash tree to
     // miss a dirty page.)
     if constexpr (SET == TLB_WRITE) {
         const auto old_vaddr_page = a.template read_tlb_vaddr_page<TLB_WRITE>(slot_index);
@@ -3154,8 +3156,10 @@ static FORCE_INLINE execute_status execute_SLTI(const STATE_ACCESS a, uint64_t &
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
-    return execute_arithmetic_immediate(a, pc, insn,
-        [](uint64_t rs1, int32_t imm) -> uint64_t { return static_cast<int64_t>(rs1) < static_cast<int64_t>(imm); });
+    return execute_arithmetic_immediate(a, pc, insn, [](uint64_t rs1, int32_t imm) -> uint64_t {
+        // NOLINTNEXTLINE(modernize-use-integer-sign-comparison)
+        return static_cast<int64_t>(rs1) < static_cast<int64_t>(imm);
+    });
 }
 
 /// \brief Implementation of the SLTIU instruction.
@@ -3165,8 +3169,10 @@ static FORCE_INLINE execute_status execute_SLTIU(const STATE_ACCESS a, uint64_t
     if constexpr (rd_kind == rd_kind::x0) {
         return advance_to_next_insn(a, pc);
     }
-    return execute_arithmetic_immediate(a, pc, insn,
-        [](uint64_t rs1, int32_t imm) -> uint64_t { return rs1 < static_cast<uint64_t>(imm); });
+    return execute_arithmetic_immediate(a, pc, insn, [](uint64_t rs1, int32_t imm) -> uint64_t {
+        // NOLINTNEXTLINE(modernize-use-integer-sign-comparison)
+        return rs1 < static_cast<uint64_t>(imm);
+    });
 }
 
 /// \brief Implementation of the XORI instruction.
@@ -6081,12 +6087,12 @@ interpreter_break_reason interpret(const STATE_ACCESS a, uint64_t mcycle_end) {
     const uint64_t mcycle = a.read_mcycle();
 
     // If the cpu is halted, we are done
-    if (a.read_iflags_H()) {
+    if (a.read_iflags_H() != 0) {
         return interpreter_break_reason::halted;
     }
 
     // If the cpu has yielded manually, we are done
-    if (a.read_iflags_Y()) {
+    if (a.read_iflags_Y() != 0) {
         return interpreter_break_reason::yielded_manually;
     }
 
diff --git a/src/is-pristine.cpp b/src/is-pristine.cpp
index 4daa6d300..e41487615 100644
--- a/src/is-pristine.cpp
+++ b/src/is-pristine.cpp
@@ -17,7 +17,6 @@
 #include "is-pristine.h"
 
 #include <cstddef>
-#include <cstdint>
 #include <span>
 
 #include "address-range-constants.h"
diff --git a/src/is-pristine.h b/src/is-pristine.h
index eab0b327e..293c6d863 100644
--- a/src/is-pristine.h
+++ b/src/is-pristine.h
@@ -19,14 +19,11 @@
 
 #include "compiler-defines.h"
 
-#include <cstddef>
-#include <cstdint>
 #include <ranges>
 #include <span>
 
 #include "address-range-constants.h"
 #include "concepts.h"
-#include "meta.h"
 
 namespace cartesi {
 
diff --git a/src/json-util.cpp b/src/json-util.cpp
index 32001e688..3d6bb6234 100644
--- a/src/json-util.cpp
+++ b/src/json-util.cpp
@@ -35,18 +35,27 @@
 
 #include "access-log.h"
 #include "address-range-description.h"
+#include "back-merkle-tree.h"
 #include "base64.h"
 #include "bracket-note.h"
-#include "hash-tree.h"
+#include "hash-tree-constants.h"
+#include "hash-tree-proof.h"
+#include "hash-tree-stats.h"
 #include "interpret.h"
 #include "jsonrpc-fork-result.h"
 #include "machine-config.h"
 #include "machine-hash.h"
+#include "machine-reg.h"
 #include "machine-runtime-config.h"
-#include "machine.h"
-#include "meta.h"
+#include "mcycle-root-hashes.h"
+#include "page-hash-tree-cache-stats.h"
+#include "ranges.h"
 #include "semantic-version.h"
+#include "shadow-registers.h"
+#include "shadow-uarch-state.h"
+#include "uarch-cycle-root-hashes.h"
 #include "uarch-interpret.h"
+#include "variant-hasher.h"
 
 namespace cartesi {
 
@@ -1904,6 +1913,7 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, mcycle_root_hashes
     ju_get_vector_like_field(jconfig, "hashes"s, value.hashes, new_path);
     ju_get_field(jconfig, "mcycle_phase"s, value.mcycle_phase, new_path);
     ju_get_field(jconfig, "break_reason"s, value.break_reason, new_path);
+    ju_get_opt_field(jconfig, "back_tree"s, value.back_tree, new_path);
 }
 
 template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key, mcycle_root_hashes &value,
@@ -1920,7 +1930,7 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, uarch_cycle_root_ha
     const auto &jconfig = j[key];
     const auto new_path = path + to_string(key) + "/";
     ju_get_vector_like_field(jconfig, "hashes"s, value.hashes, new_path);
-    ju_get_vector_like_field(jconfig, "reset_indices"s, value.hashes, new_path);
+    ju_get_vector_like_field(jconfig, "reset_indices"s, value.reset_indices, new_path);
     ju_get_field(jconfig, "break_reason"s, value.break_reason, new_path);
 }
 
@@ -1930,6 +1940,35 @@ template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t
 template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key,
     uarch_cycle_root_hashes &value, const std::string &path);
 
+template <typename K>
+void ju_get_opt_field(const nlohmann::json &j, const K &key, std::optional<back_merkle_tree> &value,
+    const std::string &path) {
+    value = {};
+    if (!contains(j, key, path)) {
+        return;
+    }
+    const auto &jconfig = j[key];
+    if (jconfig.is_null()) {
+        return;
+    }
+    const auto new_path = path + to_string(key) + "/";
+    uint64_t log2_max_leaves{};
+    hash_function_type hash_function{};
+    uint64_t leaf_count{};
+    machine_hashes context;
+    ju_get_field(jconfig, "log2_max_leaves"s, log2_max_leaves, new_path);
+    ju_get_field(jconfig, "hash_function"s, hash_function, new_path);
+    ju_get_field(jconfig, "leaf_count"s, leaf_count, new_path);
+    ju_get_vector_like_field(jconfig, "context"s, context, new_path);
+    value = back_merkle_tree{static_cast<int>(log2_max_leaves), hash_function, leaf_count, context};
+}
+
+template void ju_get_opt_field<uint64_t>(const nlohmann::json &j, const uint64_t &key,
+    std::optional<back_merkle_tree> &value, const std::string &path);
+
+template void ju_get_opt_field<std::string>(const nlohmann::json &j, const std::string &key,
+    std::optional<back_merkle_tree> &value, const std::string &path);
+
 void to_json(nlohmann::json &j, const machine_reg &reg) {
     j = reg_to_name(reg);
 }
@@ -2320,6 +2359,9 @@ void to_json(nlohmann::json &j, const std::vector<uint64_t> &ints) {
 void to_json(nlohmann::json &j, const mcycle_root_hashes &result) {
     j = nlohmann::json{{"hashes", base64_machine_hashes(result.hashes)}, {"mcycle_phase", result.mcycle_phase},
         {"break_reason", result.break_reason}};
+    if (result.back_tree.has_value()) {
+        j["back_tree"] = result.back_tree;
+    }
 }
 
 void to_json(nlohmann::json &j, const uarch_cycle_root_hashes &result) {
@@ -2327,4 +2369,10 @@ void to_json(nlohmann::json &j, const uarch_cycle_root_hashes &result) {
         {"break_reason", result.break_reason}};
 }
 
+void to_json(nlohmann::json &j, const back_merkle_tree &back_tree) {
+    j = nlohmann::json{{"log2_max_leaves", back_tree.get_log2_max_leaves()},
+        {"hash_function", hash_function_to_name(back_tree.get_hash_function())},
+        {"leaf_count", back_tree.get_leaf_count()}, {"context", base64_machine_hashes(back_tree.get_context())}};
+}
+
 } // namespace cartesi
diff --git a/src/json-util.h b/src/json-util.h
index e6867e571..f54185ef8 100644
--- a/src/json-util.h
+++ b/src/json-util.h
@@ -18,7 +18,6 @@
 #define JSON_UTIL_H
 
 #include <cstdint>
-#include <cstring>
 #include <optional>
 #include <stdexcept>
 #include <string>
@@ -29,6 +28,7 @@
 
 #include "access-log.h"
 #include "address-range-description.h"
+#include "back-merkle-tree.h"
 #include "bracket-note.h"
 #include "hash-tree-proof.h"
 #include "hash-tree-stats.h"
@@ -41,8 +41,11 @@
 #include "mcycle-root-hashes.h"
 #include "page-hash-tree-cache-stats.h"
 #include "semantic-version.h"
+#include "shadow-registers.h"
+#include "shadow-uarch-state.h"
 #include "uarch-cycle-root-hashes.h"
 #include "uarch-interpret.h"
+#include "variant-hasher.h"
 
 namespace cartesi {
 
@@ -601,6 +604,16 @@ template <typename K>
 void ju_get_opt_field(const nlohmann::json &j, const K &key, uarch_cycle_root_hashes &value,
     const std::string &path = "params/");
 
+/// \brief Attempts to load an std::optional<back_merkle_tree> object from a field in a JSON object
+/// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
+/// \param j JSON object to load from
+/// \param key Key to load value from
+/// \param value Object to store value
+/// \param path Path to j
+template <typename K>
+void ju_get_opt_field(const nlohmann::json &j, const K &key, std::optional<back_merkle_tree> &value,
+    const std::string &path = "params/");
+
 /// \brief Attempts to load a vector from a field in a JSON object
 /// \tparam K Key type (explicit extern declarations for uint64_t and std::string are provided)
 /// \param j JSON object to load from
@@ -681,7 +694,7 @@ class override_to_json {
     const T &m_t; // NOLINT(cppcoreguidelines-avoid-const-or-ref-data-members)
 
 public:
-    explicit override_to_json(const T &t) : m_t(t) {};
+    explicit override_to_json(const T &t) : m_t(t) {}
     const T &get() const {
         return m_t;
     }
@@ -736,6 +749,16 @@ void to_json(nlohmann::json &j, const semantic_version &version);
 void to_json(nlohmann::json &j, const std::vector<uint64_t> &uints);
 void to_json(nlohmann::json &j, const mcycle_root_hashes &result);
 void to_json(nlohmann::json &j, const uarch_cycle_root_hashes &result);
+void to_json(nlohmann::json &j, const back_merkle_tree &back_tree);
+
+template <typename T>
+void to_json(nlohmann::json &j, const std::optional<T> &v) {
+    if (v.has_value()) {
+        to_json(j, *v);
+    } else {
+        j = nullptr;
+    }
+}
 
 // Extern template declarations
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, std::string &value,
@@ -938,6 +961,10 @@ extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &k
     const std::string &base = "params/");
 extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key, uarch_cycle_root_hashes &value,
     const std::string &base = "params/");
+extern template void ju_get_opt_field(const nlohmann::json &j, const uint64_t &key,
+    std::optional<back_merkle_tree> &value, const std::string &base = "params/");
+extern template void ju_get_opt_field(const nlohmann::json &j, const std::string &key,
+    std::optional<back_merkle_tree> &value, const std::string &base = "params/");
 
 template <typename T>
 nlohmann::json to_json(const T &v) {
diff --git a/src/jsonrpc-discover.json b/src/jsonrpc-discover.json
index 96237b761..8220f8939 100644
--- a/src/jsonrpc-discover.json
+++ b/src/jsonrpc-discover.json
@@ -2329,6 +2329,9 @@
           },
           "break_reason": {
             "$ref": "#/components/schemas/InterpreterBreakReason"
+          },
+          "back_tree": {
+            "$ref": "#/components/schemas/BackMerkleTree"
           }
         },
         "required": ["hashes", "mcycle_phase", "break_reason"]
@@ -2348,6 +2351,30 @@
           }
         },
         "required": ["hashes", "reset_indices", "break_reason"]
+      },
+      "BackMerkleTree": {
+        "title": "BackMerkleTree",
+        "type": "object",
+        "properties": {
+          "log2_max_leaves": {
+            "$ref": "#/components/schemas/UnsignedInteger"
+          },
+          "hash_function": {
+            "$ref": "#/components/schemas/HashFunctionType"
+          },
+          "leaf_count": {
+            "$ref": "#/components/schemas/UnsignedInteger"
+          },
+          "context": {
+            "$ref": "#/components/schemas/Base64HashArray"
+          }
+        },
+        "required": [
+          "log2_max_leaves",
+          "hash_function",
+          "leaf_count",
+          "context"
+        ]
       }
     }
   }
diff --git a/src/jsonrpc-machine-c-api.cpp b/src/jsonrpc-machine-c-api.cpp
index 75f9ba296..f1cf0c40e 100644
--- a/src/jsonrpc-machine-c-api.cpp
+++ b/src/jsonrpc-machine-c-api.cpp
@@ -16,11 +16,7 @@
 
 #include "jsonrpc-machine-c-api.h"
 
-#include <csignal>
 #include <cstdint>
-#include <cstdio>
-#include <cstdlib>
-#include <cstring>
 #include <stdexcept>
 #include <string>
 
diff --git a/src/jsonrpc-machine.cpp b/src/jsonrpc-machine.cpp
index dfda36eda..49164df14 100644
--- a/src/jsonrpc-machine.cpp
+++ b/src/jsonrpc-machine.cpp
@@ -23,10 +23,14 @@
 #include <csignal>
 #include <cstddef>
 #include <cstdint>
+#include <cstdio>
 #include <cstdlib>
 #include <cstring>
 #include <exception>
+#include <limits>
 #include <memory>
+#include <optional>
+#include <span>
 #include <sstream>
 #include <stdexcept>
 #include <string>
@@ -50,11 +54,11 @@
 #pragma GCC diagnostic push
 #pragma GCC diagnostic ignored "-Wdeprecated-declarations"
 #pragma GCC diagnostic ignored "-Wunused-but-set-variable"
-#include <boost/asio/connect.hpp>
+#include <boost/asio/connect.hpp> // IWYU pragma: keep
 #include <boost/asio/ip/address.hpp>
 #include <boost/asio/ip/tcp.hpp>
-#include <boost/beast/core.hpp>
-#include <boost/beast/http.hpp>
+#include <boost/beast/core.hpp> // IWYU pragma: keep
+#include <boost/beast/http.hpp> // IWYU pragma: keep
 #include <boost/beast/version.hpp>
 #pragma GCC diagnostic pop
 
@@ -62,17 +66,23 @@
 
 #include "access-log.h"
 #include "address-range-description.h"
+#include "back-merkle-tree.h"
 #include "base64.h"
+#include "hash-tree-proof.h"
+#include "hash-tree-stats.h"
 #include "i-machine.h"
 #include "interpret.h"
 #include "json-util.h"
 #include "jsonrpc-fork-result.h"
 #include "jsonrpc-version.h"
 #include "machine-config.h"
+#include "machine-hash.h"
 #include "machine-runtime-config.h"
+#include "mcycle-root-hashes.h"
 #include "os.h"
 #include "scope-exit.h"
 #include "semantic-version.h"
+#include "uarch-cycle-root-hashes.h"
 #include "uarch-interpret.h"
 
 using namespace std::string_literals;
@@ -231,7 +241,7 @@ static std::string json_post(boost::asio::io_context &ioc, beast::tcp_stream &st
         beast::flat_buffer buffer;
         http::response_parser<http::string_body> res_parser;
         res_parser.eager(true);
-        res_parser.body_limit(16777216U); // can receive up to 16MB
+        res_parser.body_limit(std::numeric_limits<uint64_t>::max()); // can receive unlimited amount of data
 
         // Receive the HTTP response, we perform an asynchronous operation in order to support timeouts
         http::async_read(stream, buffer, res_parser, [&](beast::error_code ec, std::size_t /*bytes_transferred*/) {
@@ -583,7 +593,7 @@ i_machine *jsonrpc_machine::do_clone_empty() const {
         throw;
     }
     return clone;
-};
+}
 
 void jsonrpc_machine::do_create(const machine_config &config, const machine_runtime_config &runtime,
     const std::string &dir) {
@@ -645,10 +655,13 @@ interpreter_break_reason jsonrpc_machine::do_run(uint64_t mcycle_end) {
     return result;
 }
 
-void jsonrpc_machine::do_collect_mcycle_root_hashes(uint64_t mcycle_end, uint64_t mcycle_period, uint64_t mcycle_phase,
-    uint32_t log2_bundle_mcycle_count, mcycle_root_hashes &result) {
+mcycle_root_hashes jsonrpc_machine::do_collect_mcycle_root_hashes(uint64_t mcycle_end, uint64_t mcycle_period,
+    uint64_t mcycle_phase, int32_t log2_bundle_mcycle_count,
+    const std::optional<back_merkle_tree> &previous_back_tree) {
+    mcycle_root_hashes result;
     request("machine.collect_mcycle_root_hashes",
-        std::tie(mcycle_end, mcycle_period, mcycle_phase, log2_bundle_mcycle_count), result);
+        std::tie(mcycle_end, mcycle_period, mcycle_phase, log2_bundle_mcycle_count, previous_back_tree), result);
+    return result;
 }
 
 interpreter_break_reason jsonrpc_machine::do_log_step(uint64_t mcycle_count, const std::string &filename) {
@@ -817,9 +830,11 @@ uarch_interpreter_break_reason jsonrpc_machine::do_run_uarch(uint64_t uarch_cycl
     return result;
 }
 
-void jsonrpc_machine::do_collect_uarch_cycle_root_hashes(uint64_t mcycle_end, uint32_t log2_bundle_uarch_cycle_count,
-    uarch_cycle_root_hashes &result) {
+uarch_cycle_root_hashes jsonrpc_machine::do_collect_uarch_cycle_root_hashes(uint64_t mcycle_end,
+    int32_t log2_bundle_uarch_cycle_count) {
+    uarch_cycle_root_hashes result;
     request("machine.collect_uarch_cycle_root_hashes", std::tie(mcycle_end, log2_bundle_uarch_cycle_count), result);
+    return result;
 }
 
 address_range_descriptions jsonrpc_machine::do_get_address_ranges() const {
diff --git a/src/jsonrpc-machine.h b/src/jsonrpc-machine.h
index 963677a89..18c846930 100644
--- a/src/jsonrpc-machine.h
+++ b/src/jsonrpc-machine.h
@@ -17,25 +17,33 @@
 #ifndef JSONRPC_MACHINE_H
 #define JSONRPC_MACHINE_H
 
+#include <chrono>
 #include <cstdint>
 #include <memory>
+#include <optional>
 #include <string>
+#include <tuple>
 
 #include "access-log.h"
 #include "address-range-description.h"
+#include "back-merkle-tree.h"
+#include "hash-tree-proof.h"
+#include "hash-tree-stats.h"
 #include "i-machine.h"
 #include "interpret.h"
 #include "jsonrpc-fork-result.h"
 #include "machine-config.h"
+#include "machine-hash.h"
 #include "machine-runtime-config.h"
+#include "mcycle-root-hashes.h"
 #include "semantic-version.h"
+#include "uarch-cycle-root-hashes.h"
 #include "uarch-interpret.h"
 
 #pragma GCC diagnostic push
 #pragma GCC diagnostic ignored "-Wdeprecated-declarations"
 #include <boost/asio/io_context.hpp>
 #include <boost/beast/core/tcp_stream.hpp>
-#include <boost/container/static_vector.hpp>
 #pragma GCC diagnostic pop
 
 namespace cartesi {
@@ -108,8 +116,8 @@ class jsonrpc_machine final : public i_machine {
         const std::string &dir) override;
     void do_load(const std::string &directory, const machine_runtime_config &runtime, sharing_mode sharing) override;
     interpreter_break_reason do_run(uint64_t mcycle_end) override;
-    void do_collect_mcycle_root_hashes(uint64_t mcycle_end, uint64_t mcycle_period, uint64_t mcycle_phase,
-        uint32_t log2_bundle_mcycle_count, mcycle_root_hashes &result) override;
+    mcycle_root_hashes do_collect_mcycle_root_hashes(uint64_t mcycle_end, uint64_t mcycle_period, uint64_t mcycle_phase,
+        int32_t log2_bundle_mcycle_count, const std::optional<back_merkle_tree> &previous_back_tree) override;
     interpreter_break_reason do_log_step(uint64_t mcycle_count, const std::string &filename) override;
     void do_store(const std::string &dir, sharing_mode sharing) const override;
     void do_clone_stored(const std::string &from_dir, const std::string &to_dir) const override;
@@ -136,8 +144,8 @@ class jsonrpc_machine final : public i_machine {
     hash_tree_stats do_get_hash_tree_stats(bool clear) override;
     bool do_verify_hash_tree() const override;
     uarch_interpreter_break_reason do_run_uarch(uint64_t uarch_cycle_end) override;
-    void do_collect_uarch_cycle_root_hashes(uint64_t mcycle_end, uint32_t log2_bundle_uarch_cycle_count,
-        uarch_cycle_root_hashes &result) override;
+    uarch_cycle_root_hashes do_collect_uarch_cycle_root_hashes(uint64_t mcycle_end,
+        int32_t log2_bundle_uarch_cycle_count) override;
     address_range_descriptions do_get_address_ranges() const override;
     void do_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length) override;
     access_log do_log_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
diff --git a/src/jsonrpc-remote-machine.cpp b/src/jsonrpc-remote-machine.cpp
index 4073732e3..177dc42af 100644
--- a/src/jsonrpc-remote-machine.cpp
+++ b/src/jsonrpc-remote-machine.cpp
@@ -32,7 +32,10 @@
 #include <ctime>
 #include <exception>
 #include <iostream>
+#include <limits>
 #include <memory>
+#include <optional>
+#include <span>
 #include <sstream>
 #include <stdexcept>
 #include <string>
@@ -48,23 +51,23 @@
 
 #include <netinet/in.h>
 #include <sys/socket.h>
-#include <sys/types.h>
+#include <sys/types.h> // IWYU pragma: keep
 #include <unistd.h>
 
 #pragma GCC diagnostic push
 #pragma GCC diagnostic ignored "-Wdeprecated-declarations"
 #pragma GCC diagnostic ignored "-Wunused-but-set-variable"
 #include <boost/asio/signal_set.hpp>
-#include <boost/beast/core.hpp>
-#include <boost/beast/http.hpp>
+#include <boost/beast/core.hpp> // IWYU pragma: keep
+#include <boost/beast/http.hpp> // IWYU pragma: keep
 #include <boost/beast/version.hpp>
 #pragma GCC diagnostic pop
 
 #include <json.hpp>
 
 #include "access-log.h"
+#include "back-merkle-tree.h"
 #include "base64.h"
-#include "interpret.h"
 #include "json-util.h"
 #include "jsonrpc-discover.h"
 #include "jsonrpc-fork-result.h"
@@ -73,8 +76,6 @@
 #include "machine-hash.h"
 #include "machine-runtime-config.h"
 #include "machine.h"
-#include "os.h"
-#include "uarch-interpret.h"
 #include "unique-c-ptr.h"
 
 #define SLOG_PREFIX log_prefix
@@ -168,7 +169,7 @@ struct http_session : std::enable_shared_from_this<http_session> {
         // Create a new request parser
         req_parser = std::make_unique<http::request_parser<http::string_body>>();
         req_parser->eager(true);
-        req_parser->body_limit(16777216U); // can receive up to 16MB
+        req_parser->body_limit(std::numeric_limits<uint64_t>::max()); // can receive unlimited amount of data
 
         // Read a request
         http::async_read(stream, buffer, *req_parser,
@@ -363,9 +364,7 @@ struct http_handler : std::enable_shared_from_this<http_handler> {
         auto session = std::make_shared<http_session>(std::move(socket), shared_from_this());
 
         // Remove previous expired sessions
-        sessions.erase(std::remove_if(sessions.begin(), sessions.end(),
-                           [](const std::weak_ptr<http_session> &weak_session) { return weak_session.expired(); }),
-            sessions.end());
+        std::erase_if(sessions, [](const std::weak_ptr<http_session> &weak_session) { return weak_session.expired(); });
 
         // Keep track of the new session
         sessions.push_back(session);
@@ -909,15 +908,17 @@ static json jsonrpc_machine_collect_mcycle_root_hashes(const json &j, const std:
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"mcycle_end", "mcycle_period", "mcycle_phase", "log2_bundle_mcycle_count"};
-    auto args = parse_args<uint64_t, uint64_t, uint64_t, uint64_t>(j, param_name);
+    static const char *param_name[] = {"mcycle_end", "mcycle_period", "mcycle_phase", "log2_bundle_mcycle_count",
+        "previous_back_tree"};
+    auto args =
+        parse_args<uint64_t, uint64_t, uint64_t, uint64_t, std::optional<cartesi::back_merkle_tree>>(j, param_name);
     auto mcycle_end = std::get<0>(args);
     auto mcycle_period = std::get<1>(args);
     auto mcycle_phase = std::get<2>(args);
     auto log2_bundle_mcycle_count = std::get<3>(args);
-    cartesi::mcycle_root_hashes result;
-    session->handler->machine->collect_mcycle_root_hashes(mcycle_end, mcycle_period, mcycle_phase,
-        log2_bundle_mcycle_count, result);
+    auto previous_back_tree = std::get<4>(args);
+    const auto result = session->handler->machine->collect_mcycle_root_hashes(mcycle_end, mcycle_period, mcycle_phase,
+        static_cast<int>(log2_bundle_mcycle_count), previous_back_tree);
     return jsonrpc_response_ok(j, result);
 }
 
@@ -934,8 +935,8 @@ static json jsonrpc_machine_collect_uarch_cycle_root_hashes(const json &j,
     auto args = parse_args<uint64_t, uint64_t>(j, param_name);
     auto mcycle_end = std::get<0>(args);
     auto log2_bundle_uarch_cycle_count = std::get<1>(args);
-    cartesi::uarch_cycle_root_hashes result;
-    session->handler->machine->collect_uarch_cycle_root_hashes(mcycle_end, log2_bundle_uarch_cycle_count, result);
+    const auto result = session->handler->machine->collect_uarch_cycle_root_hashes(mcycle_end,
+        static_cast<int>(log2_bundle_uarch_cycle_count));
     return jsonrpc_response_ok(j, result);
 }
 
diff --git a/src/keccak-256-hasher.cpp b/src/keccak-256-hasher.cpp
index 2ec108400..30f0ce22d 100644
--- a/src/keccak-256-hasher.cpp
+++ b/src/keccak-256-hasher.cpp
@@ -15,17 +15,21 @@
 //
 
 #include "keccak-256-hasher.h"
-#include "compiler-defines.h"
-#include "i-hasher.h"
-#include "keccakf.h"
-#include "machine-hash.h"
-#include "simd-vector-type.h"
 
+#include <algorithm>
+#include <array>
 #include <bit>
 #include <cstddef>
 #include <cstdint>
 #include <span>
 
+#include "array2d.h"
+#include "compiler-defines.h"
+#include "i-hasher.h"
+#include "keccakf.h"
+#include "machine-hash.h"
+#include "simd-vector-type.h"
+
 namespace cartesi {
 
 // This code is not portable to big-endian architectures.
diff --git a/src/keccak-256-hasher.h b/src/keccak-256-hasher.h
index 7d8540c89..df96a0bde 100644
--- a/src/keccak-256-hasher.h
+++ b/src/keccak-256-hasher.h
@@ -19,12 +19,11 @@
 
 #include <array>
 #include <cstddef>
-#include <cstdint>
 #include <span>
-#include <type_traits>
 
 #include "array2d.h"
 #include "compiler-defines.h"
+#include "hash-tree-constants.h"
 #include "i-hasher.h"
 #include "machine-hash.h"
 
@@ -92,6 +91,8 @@ MULTIVERSION_AMD64_AVX512_BMI_BMI2 void keccak_256_hash_2x8(const array2d<const_
 
 class keccak_256_hasher final : public i_hasher<keccak_256_hasher> {
 public:
+    keccak_256_hasher() = default;
+
     static constexpr int MAX_LANE_COUNT = 8;
 
     template <size_t ConcatCount, size_t LaneCount, size_t Extent>
diff --git a/src/local-machine.cpp b/src/local-machine.cpp
index 91d4b0128..3daac6abf 100644
--- a/src/local-machine.cpp
+++ b/src/local-machine.cpp
@@ -17,15 +17,22 @@
 #include "local-machine.h"
 
 #include <cstdint>
+#include <optional>
 #include <string>
 
 #include "access-log.h"
 #include "address-range-description.h"
+#include "back-merkle-tree.h"
+#include "hash-tree-proof.h"
+#include "hash-tree-stats.h"
 #include "i-machine.h"
 #include "interpret.h"
 #include "machine-config.h"
+#include "machine-hash.h"
 #include "machine-runtime-config.h"
 #include "machine.h"
+#include "mcycle-root-hashes.h"
+#include "uarch-cycle-root-hashes.h"
 #include "uarch-interpret.h"
 
 namespace cartesi {
@@ -78,10 +85,11 @@ interpreter_break_reason local_machine::do_run(uint64_t mcycle_end) {
     return get_machine()->run(mcycle_end);
 }
 
-void local_machine::do_collect_mcycle_root_hashes(uint64_t mcycle_end, uint64_t mcycle_period, uint64_t mcycle_phase,
-    uint32_t log2_bundle_mcycle_count, mcycle_root_hashes &result) {
-    get_machine()->collect_mcycle_root_hashes(mcycle_end, mcycle_period, mcycle_phase, log2_bundle_mcycle_count,
-        result);
+mcycle_root_hashes local_machine::do_collect_mcycle_root_hashes(uint64_t mcycle_end, uint64_t mcycle_period,
+    uint64_t mcycle_phase, int32_t log2_bundle_mcycle_count,
+    const std::optional<back_merkle_tree> &previous_back_tree) {
+    return get_machine()->collect_mcycle_root_hashes(mcycle_end, mcycle_period, mcycle_phase, log2_bundle_mcycle_count,
+        previous_back_tree);
 }
 
 interpreter_break_reason local_machine::do_log_step(uint64_t mcycle_count, const std::string &filename) {
@@ -181,9 +189,9 @@ uarch_interpreter_break_reason local_machine::do_run_uarch(uint64_t uarch_cycle_
     return get_machine()->run_uarch(uarch_cycle_end);
 }
 
-void local_machine::do_collect_uarch_cycle_root_hashes(uint64_t mcycle_end, uint32_t log2_bundle_uarch_cycle_count,
-    uarch_cycle_root_hashes &result) {
-    get_machine()->collect_uarch_cycle_root_hashes(mcycle_end, log2_bundle_uarch_cycle_count, result);
+uarch_cycle_root_hashes local_machine::do_collect_uarch_cycle_root_hashes(uint64_t mcycle_end,
+    int32_t log2_bundle_uarch_cycle_count) {
+    return get_machine()->collect_uarch_cycle_root_hashes(mcycle_end, log2_bundle_uarch_cycle_count);
 }
 
 address_range_descriptions local_machine::do_get_address_ranges() const {
diff --git a/src/local-machine.h b/src/local-machine.h
index 0afe8806a..4cd52ed77 100644
--- a/src/local-machine.h
+++ b/src/local-machine.h
@@ -18,23 +18,29 @@
 #define LOCAL_MACHINE_H
 
 #include <cstdint>
+#include <optional>
 #include <string>
 
 #include "access-log.h"
 #include "address-range-description.h"
+#include "back-merkle-tree.h"
+#include "hash-tree-proof.h"
+#include "hash-tree-stats.h"
 #include "i-machine.h"
 #include "interpret.h"
 #include "machine-config.h"
 #include "machine-hash.h"
 #include "machine-runtime-config.h"
 #include "machine.h"
+#include "mcycle-root-hashes.h"
+#include "uarch-cycle-root-hashes.h"
 #include "uarch-interpret.h"
 
 namespace cartesi {
 
 /// \class local_machine
 /// \brief i_machine implementation pointing to a local machine instance
-class local_machine : public i_machine {
+class local_machine final : public i_machine {
 public:
     local_machine() = default;
     local_machine(const local_machine &other) = delete;
@@ -50,8 +56,8 @@ class local_machine : public i_machine {
         const std::string &dir) override;
     void do_load(const std::string &directory, const machine_runtime_config &runtime, sharing_mode sharing) override;
     interpreter_break_reason do_run(uint64_t mcycle_end) override;
-    void do_collect_mcycle_root_hashes(uint64_t mcycle_end, uint64_t mcycle_period, uint64_t mcycle_phase,
-        uint32_t log2_bundle_mcycle_count, mcycle_root_hashes &result) override;
+    mcycle_root_hashes do_collect_mcycle_root_hashes(uint64_t mcycle_end, uint64_t mcycle_period, uint64_t mcycle_phase,
+        int32_t log2_bundle_mcycle_count, const std::optional<back_merkle_tree> &previous_back_tree) override;
     interpreter_break_reason do_log_step(uint64_t mcycle_count, const std::string &filename) override;
     void do_store(const std::string &directory, sharing_mode sharing) const override;
     void do_clone_stored(const std::string &from_dir, const std::string &to_dir) const override;
@@ -78,8 +84,8 @@ class local_machine : public i_machine {
     void do_reset_uarch() override;
     access_log do_log_reset_uarch(const access_log::type &log_type) override;
     uarch_interpreter_break_reason do_run_uarch(uint64_t uarch_cycle_end) override;
-    void do_collect_uarch_cycle_root_hashes(uint64_t mcycle_end, uint32_t log2_bundle_uarch_cycle_count,
-        uarch_cycle_root_hashes &result) override;
+    uarch_cycle_root_hashes do_collect_uarch_cycle_root_hashes(uint64_t mcycle_end,
+        int32_t log2_bundle_uarch_cycle_count) override;
     address_range_descriptions do_get_address_ranges() const override;
     void do_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length) override;
     access_log do_log_send_cmio_response(uint16_t reason, const unsigned char *data, uint64_t length,
diff --git a/src/machine-address-ranges.cpp b/src/machine-address-ranges.cpp
index 8bb44bbd1..183883019 100644
--- a/src/machine-address-ranges.cpp
+++ b/src/machine-address-ranges.cpp
@@ -20,7 +20,6 @@
 #include "machine-address-ranges.h"
 
 #include <algorithm>
-#include <cerrno>
 #include <concepts>
 #include <cstdint>
 #include <cstdio>
@@ -37,14 +36,14 @@
 #include "clint-address-range.h"
 #include "htif-address-range.h"
 #include "machine-config.h"
+#include "machine-runtime-config.h"
 #include "memory-address-range.h"
+#include "meta.h"
 #include "os-filesystem.h"
-#include "os.h"
 #include "plic-address-range.h"
 #include "pmas-constants.h"
 #include "pmas.h"
 #include "processor-state.h"
-#include "scope-exit.h"
 #include "scope-remove.h"
 #include "uarch-pristine.h"
 #include "uarch-processor-state.h"
@@ -238,7 +237,7 @@ machine_address_ranges::machine_address_ranges(const machine_config &config,
         prepare_backing_stores(c, remover);
     }
 
-    // Add all address ranges to m_all, and potentially to interpret and merkle
+    // Add all address ranges to m_all, and potentially to interpret and hash
     m_shadow_state_index = static_cast<int>(m_all.size()); // NOLINT(cppcoreguidelines-prefer-member-initializer)
     push_back(make_shadow_state_address_range(c.processor), register_where{.hash_tree = true, .pmas = false});
     m_shadow_uarch_state_index = static_cast<int>(m_all.size()); // NOLINT(cppcoreguidelines-prefer-member-initializer)
diff --git a/src/machine-address-ranges.h b/src/machine-address-ranges.h
index b3220cddf..100425fcf 100644
--- a/src/machine-address-ranges.h
+++ b/src/machine-address-ranges.h
@@ -17,9 +17,12 @@
 #ifndef MACHINE_ADDRESS_RANGES_H
 #define MACHINE_ADDRESS_RANGES_H
 
+#include <concepts>
+#include <cstddef>
 #include <cstdint>
 #include <memory>
 #include <ranges>
+#include <string>
 #include <utility>
 #include <vector>
 
@@ -30,7 +33,6 @@
 #include "address-range.h"
 #include "machine-config.h"
 #include "machine-runtime-config.h"
-#include "meta.h"
 #include "scope-remove.h"
 #include "virtio-address-range.h"
 
@@ -98,7 +100,6 @@ class machine_address_ranges {
         if (index >= m_pmas.size()) [[unlikely]] {
             return m_sentinel;
         }
-        // NOLINTNEXTLINE(bugprone-narrowing-conversions)
         return *m_all[static_cast<size_t>(m_pmas[static_cast<size_t>(index)])];
     }
 
diff --git a/src/machine-c-api.cpp b/src/machine-c-api.cpp
index d33a2210c..8493b7069 100644
--- a/src/machine-c-api.cpp
+++ b/src/machine-c-api.cpp
@@ -16,6 +16,7 @@
 
 #include "machine-c-api.h"
 
+#include <algorithm>
 #include <any>
 #include <cstdint>
 #include <cstring>
@@ -26,16 +27,21 @@
 #include <optional>
 #include <ranges>
 #include <regex>
+#include <span>
 #include <stdexcept>
 #include <string>
 #include <system_error>
+#include <type_traits>
 #include <typeinfo>
 #include <variant>
 
 #include "access-log.h"
+#include "address-range-constants.h"
 #include "address-range-defines.h"
 #include "address-range-description.h"
+#include "back-merkle-tree.h"
 #include "htif-constants.h"
+#include "htif-defines.h"
 #include "i-machine.h"
 #include "interpret.h"
 #include "json-util.h"
@@ -48,6 +54,7 @@
 #include "machine-runtime-config.h"
 #include "machine.h"
 #include "os-features.h"
+#include "ranges.h"
 #include "sha-256-hasher.h"
 
 static std::string &get_last_err_msg_storage() {
@@ -646,13 +653,15 @@ cm_error cm_run(cm_machine *m, uint64_t mcycle_end, cm_break_reason *break_reaso
 }
 
 cm_error cm_collect_mcycle_root_hashes(cm_machine *m, uint64_t mcycle_end, uint64_t mcycle_period,
-    uint64_t mcycle_phase, uint32_t log2_bundle_mcycle_count, const char **result) try {
+    uint64_t mcycle_phase, int32_t log2_bundle_mcycle_count, const char *previous_back_tree, const char **result) try {
     if (result == nullptr) {
         throw std::invalid_argument("invalid result output");
     }
     auto *cpp_m = convert_from_c(m);
-    cartesi::mcycle_root_hashes cpp_res;
-    cpp_m->collect_mcycle_root_hashes(mcycle_end, mcycle_period, mcycle_phase, log2_bundle_mcycle_count, cpp_res);
+    const auto cpp_previous_back_tree =
+        cartesi::from_json<std::optional<cartesi::back_merkle_tree>>(previous_back_tree, "previous_back_tree");
+    const auto cpp_res = cpp_m->collect_mcycle_root_hashes(mcycle_end, mcycle_period, mcycle_phase,
+        log2_bundle_mcycle_count, cpp_previous_back_tree);
     *result = cm_set_temp_string(cartesi::to_json(cpp_res).dump());
     return cm_result_success();
 } catch (...) {
@@ -662,14 +671,13 @@ cm_error cm_collect_mcycle_root_hashes(cm_machine *m, uint64_t mcycle_end, uint6
     return cm_result_failure();
 }
 
-cm_error cm_collect_uarch_cycle_root_hashes(cm_machine *m, uint64_t mcycle_end, uint32_t log2_bundle_uarch_cycle_count,
+cm_error cm_collect_uarch_cycle_root_hashes(cm_machine *m, uint64_t mcycle_end, int32_t log2_bundle_uarch_cycle_count,
     const char **result) try {
     if (result == nullptr) {
         throw std::invalid_argument("invalid result output");
     }
     auto *cpp_m = convert_from_c(m);
-    cartesi::uarch_cycle_root_hashes cpp_res;
-    cpp_m->collect_uarch_cycle_root_hashes(mcycle_end, log2_bundle_uarch_cycle_count, cpp_res);
+    const auto cpp_res = cpp_m->collect_uarch_cycle_root_hashes(mcycle_end, log2_bundle_uarch_cycle_count);
     *result = cm_set_temp_string(cartesi::to_json(cpp_res).dump());
     return cm_result_success();
 } catch (...) {
@@ -1198,7 +1206,7 @@ cm_error cm_get_hash(cm_hash_function hash_function, const uint8_t *data, uint64
     if (data == nullptr && length > 0) {
         throw std::invalid_argument("invalid data input");
     }
-    const std::span<const unsigned char> data_span{data, length};
+    const std::span<const unsigned char> data_span{data, static_cast<size_t>(length)};
     cartesi::machine_hash cpp_result;
 
     switch (hash_function) {
diff --git a/src/machine-c-api.h b/src/machine-c-api.h
index 30418abeb..4d45c0d35 100644
--- a/src/machine-c-api.h
+++ b/src/machine-c-api.h
@@ -527,13 +527,13 @@ CM_API cm_error cm_get_initial_config(const cm_machine *m, const char **config);
 /// \returns 0 for success, non zero code for error.
 CM_API cm_error cm_get_address_ranges(const cm_machine *m, const char **ranges);
 
-/// \brief Obtains the root hash of the Merkle tree.
+/// \brief Obtains the root hash of the hash tree.
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
 /// \param hash Valid pointer to cm_hash structure that receives the hash.
 /// \returns 0 for success, non zero code for error.
 CM_API cm_error cm_get_root_hash(const cm_machine *m, cm_hash *hash);
 
-/// \brief Obtains the hash of a node in the Merkle tree.
+/// \brief Obtains the hash of a node in the hash tree.
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
 /// \param address Address of node.
 /// \param log2_size Log<sub>2</sub> of node size.
@@ -541,7 +541,7 @@ CM_API cm_error cm_get_root_hash(const cm_machine *m, cm_hash *hash);
 /// \returns 0 for success, non zero code for error.
 CM_API cm_error cm_get_node_hash(const cm_machine *m, uint64_t address, int32_t log2_size, cm_hash *hash);
 
-/// \brief Obtains the proof for a node in the machine state Merkle tree.
+/// \brief Obtains the proof for a node in the machine state hash tree.
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
 /// \param address Address of target node. Must be aligned to a 2^log2_size boundary.
 /// \param log2_size The log base 2 of the size subtended by the target node.
@@ -651,25 +651,41 @@ CM_API cm_error cm_run(cm_machine *m, uint64_t mcycle_end, cm_break_reason *brea
 /// \param mcycle_phase Number of machine cycles elapsed since last root hash collected.
 /// \param log2_bundle_mcycle_count Log base 2 of the amount of mcycle root hashes to bundle.
 /// If greater than 0, it collects subtree root hashes for 2^log2_bundle_mcycle_count root hashes.
+/// \param previous_back_tree Optional context to continue collecting bundled root hashes.
+/// If not NULL, it must be a JSON object as a string containing the back tree.
 /// \param result Receives a JSON object as a string, guaranteed to remain valid only until
 /// the next CM_API function is called from the same thread.
 /// The field "hashes" is an array of root hashes (as base64-encoded strings) after each period.
 /// The field "mcycle_phase" is the number of machine cycles elapsed since last root hash collected.
 /// The field "break_reason" is a string with the reason why the function returned.
 /// (Set to "failed" on failure.)
+/// The optional field "back_tree" is the back tree context to continue collecting bundled root hashes.
 /// For example:
 /// ```json
 /// {
 ///     "hashes": ["2av44Q3TaHKREgULA/iMoNe+btxCr+ja+hHGtXxaGjM=", ..., "FMAHn7mc2f+I30UjiywbAtOkw99iOa3NWS6fWql3UNU="],
 ///     "mcycle_phase": 1278,
-///     "break_reason": "yielded_manually"
+///     "break_reason": "yielded_manually",
+///     "back_tree": { ... },
 /// }
 /// ```
 /// \returns 0 for success, non zero code for error.
-/// \detail The first hash added to \p result.hashes is the root hash after (\p mcycle_period - \p mcycle_phase)
+/// \detail The first hash added to "hashes" is the root hash after (\p mcycle_period - \p mcycle_phase)
 /// machine cycles (if the function managed to get that far before returning).
+///
+/// If "break_reason" is "yielded_manually", "halted", or if mcycle reaches CM_MCYCLE_MAX (maximum mcycle value),
+/// this means that execution stopped at a fixed point.
+///
+/// When \p log2_bundle_mcycle_count is greater than 0 and execution stops at a fixed point, then
+/// the next-to-last hash in "hashes" represents a bundle that is completed by padding with repetitions of the final
+/// root hash, and the last hash in "hashes" represents a bundle consisting entirely of repetitions of that same final
+/// root hash.
+///
+/// When execution stops at a mcycle_period boundary or at a fixed point, the "back_tree" field is omitted.
+/// Otherwise the "back_tree" field is included in the result and contains partial root hashes as its context,
+/// and must be passed a subsequent function call to continue bundling root hashes properly.
 CM_API cm_error cm_collect_mcycle_root_hashes(cm_machine *m, uint64_t mcycle_end, uint64_t mcycle_period,
-    uint64_t mcycle_phase, uint32_t log2_bundle_mcycle_count, const char **result);
+    uint64_t mcycle_phase, int32_t log2_bundle_mcycle_count, const char *previous_back_tree, const char **result);
 
 /// \brief Runs the machine microarchitecture until CM_REG_UARCH_CYCLE reaches uarch_cycle_end or it halts.
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
@@ -683,13 +699,13 @@ CM_API cm_error cm_run_uarch(cm_machine *m, uint64_t uarch_cycle_end, cm_uarch_b
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
 /// \param mcycle_end End machine cycle value to execute, uarch cycle by uarch cycle.
 /// \param log2_bundle_uarch_cycle_count Log base 2 of the amount of uarch cycle root hashes to bundle.
-/// If greater than 0, it collects subtree root hashes for 2^log2_bundle_mcycle_count root hashes.
+/// If greater than 0, it collects subtree root hashes for 2^log2_bundle_uarch_cycle_count root hashes.
 /// \param result Receives an JSON object as a string, guaranteed to remain valid only until
 /// the next CM_API function is called from the same thread.
 /// The field "hashes" is an array (of hashes as base64-encoded strings) with the root hashes after each uarch cycle.
 /// The field "reset_indices" is an array with indices of the root hashes after each implicit uarch reset
 /// (i.e., after each machine cycle).
-/// The field "break_reason" is an integer with the reason why the function returned.
+/// The field "break_reason" is a string with the reason why the function returned.
 /// (Set to "failed" on failure.)
 /// For example:
 /// ```json
@@ -700,10 +716,23 @@ CM_API cm_error cm_run_uarch(cm_machine *m, uint64_t uarch_cycle_end, cm_uarch_b
 /// }
 /// ```
 /// \returns 0 for success, non zero code for error.
-/// \detail The first hash added to \p hashes is the root hash after the first uarch cycle, the last is the
+/// \detail The first hash added to "hashes" is the root hash after the first uarch cycle, the last is the
 /// root hash at the time function returns (for whatever reason), which always happens right after an uarch reset.
+///
+/// If \p log2_bundle_uarch_cycle_count is greater than zero, the "hashes" array contains bundles of root hashes.
+/// For each reset_index value in the "reset_indices" array:
+///   - hashes[reset_index - 1] contains a bundle representing repeated root hashes at the point where the uarch halted
+///     just before the uarch reset.
+///   - hashes[reset_index] contains a bundle representing repeated root hashes at the point where the uarch halted,
+///     followed by a single root hash immediately after the uarch reset.
+///
+/// If "break_reason" is "yielded_manually", "halted", or if mcycle reaches CM_MCYCLE_MAX (maximum mcycle value),
+/// this means that execution stopped at a fixed point.
+/// In these cases, the function will attempt to execute one additional mcycle at this fixed point,
+/// and collect the resulting root hashes as well. As a result, all root hashes collected after the next-to-last
+/// reset index correspond to this fixed point.
 CM_API cm_error cm_collect_uarch_cycle_root_hashes(cm_machine *m, uint64_t mcycle_end,
-    uint32_t log2_bundle_uarch_cycle_count, const char **result);
+    int32_t log2_bundle_uarch_cycle_count, const char **result);
 
 /// \brief Resets the entire microarchitecture state to pristine values.
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
diff --git a/src/machine-config.cpp b/src/machine-config.cpp
index 01a51beee..1d17719a8 100644
--- a/src/machine-config.cpp
+++ b/src/machine-config.cpp
@@ -16,21 +16,21 @@
 
 #include "machine-config.h"
 
-#include <cerrno>
 #include <cstdint>
 #include <exception>
 #include <iomanip>
 #include <ios>
+#include <span>
 #include <sstream>
 #include <stdexcept>
 #include <string>
-#include <system_error>
 
 #include <json.hpp>
 
 #include "address-range-constants.h"
 #include "json-util.h"
 #include "os-filesystem.h"
+#include "riscv-constants.h"
 
 static constexpr uint32_t archive_version = 6;
 
@@ -135,7 +135,7 @@ machine_config machine_config::load(const std::string &dir, sharing_mode sharing
         if (!jv.is_number_integer()) {
             throw std::runtime_error("expected integer field \"archive_version\"");
         }
-        if (jv.get<int>() != archive_version) {
+        if (jv.get<uint32_t>() != archive_version) {
             throw std::runtime_error("expected \"archive_version\" " + std::to_string(archive_version) + " (got " +
                 std::to_string(jv.get<int>()) + ")");
         }
diff --git a/src/machine-config.h b/src/machine-config.h
index a0d37bc7b..0d3199b94 100644
--- a/src/machine-config.h
+++ b/src/machine-config.h
@@ -17,13 +17,11 @@
 #ifndef MACHINE_CONFIG_H
 #define MACHINE_CONFIG_H
 
-#include <array>
 #include <cstdint>
 #include <string>
 #include <variant>
 #include <vector>
 
-#include "riscv-constants.h"
 #include "shadow-registers.h"
 #include "shadow-uarch-state.h"
 #include "variant-hasher.h"
diff --git a/src/machine-hash.h b/src/machine-hash.h
index 3001eec1a..0aae53a80 100644
--- a/src/machine-hash.h
+++ b/src/machine-hash.h
@@ -21,6 +21,7 @@
 /// \brief Storage for a hash
 
 #include <array>
+#include <cstddef>
 #include <span>
 #include <vector>
 
diff --git a/src/machine-reg.h b/src/machine-reg.h
index 277ef2071..307a4e074 100644
--- a/src/machine-reg.h
+++ b/src/machine-reg.h
@@ -17,6 +17,8 @@
 #ifndef MACHINE_REG_H
 #define MACHINE_REG_H
 
+#include <cstdint>
+
 #include "shadow-registers.h"
 #include "shadow-uarch-state.h"
 
diff --git a/src/machine.cpp b/src/machine.cpp
index 21f8972de..db6168a9f 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -15,50 +15,51 @@
 //
 
 #include "machine.h"
-#include "hash-tree-constants.h"
-#include "os-features.h"
 
 #include <algorithm>
 #include <array>
-#include <cerrno>
+#include <cassert>
 #include <cstdint>
 #include <cstdio>
 #include <cstring>
-#include <iomanip>
 #include <iostream>
-#include <iterator>
 #include <memory>
+#include <optional>
 #include <ranges>
+#include <span>
 #include <sstream>
 #include <stdexcept>
 #include <string>
-#include <system_error>
 #include <utility>
 
 #include "access-log.h"
 #include "address-range-constants.h"
 #include "address-range.h"
+#include "algorithm.h"
+#include "assert-printf.h"
+#include "back-merkle-tree.h"
 #include "collect-mcycle-hashes-state-access.h"
 #include "collect-uarch-cycle-hashes-state-access.h"
 #include "compiler-defines.h"
 #include "device-state-access.h"
 #include "dtb.h"
-#include "hash-tree-proof.h"
+#include "hash-tree-constants.h"
+#include "hash-tree-stats.h"
 #include "hash-tree.h"
 #include "host-addr.h"
 #include "hot-tlb.h"
 #include "htif-constants.h"
 #include "i-device-state-access.h"
-#include "i-hasher.h"
 #include "interpret.h"
 #include "is-pristine.h"
 #include "machine-config.h"
 #include "machine-hash.h"
 #include "machine-reg.h"
 #include "machine-runtime-config.h"
+#include "mcycle-root-hashes.h"
 #include "os-filesystem.h"
+#include "os-mmap.h"
 #include "os.h"
-#include "page-hash-tree-cache.h"
 #include "pmas-constants.h"
 #include "pmas.h"
 #include "processor-state.h"
@@ -71,20 +72,22 @@
 #include "scope-exit.h"
 #include "scope-remove.h"
 #include "send-cmio-response.h"
+#include "shadow-registers.h"
 #include "shadow-tlb.h"
 #include "shadow-uarch-state.h"
 #include "state-access.h"
 #include "strict-aliasing.h"
 #include "translate-virtual-address.h"
 #include "uarch-constants.h"
+#include "uarch-cycle-root-hashes.h"
 #include "uarch-interpret.h"
 #include "uarch-pristine-state-hash.h"
+#include "uarch-pristine.h"
 #include "uarch-record-state-access.h"
 #include "uarch-replay-state-access.h"
 #include "uarch-reset-state.h"
 #include "uarch-state-access.h"
 #include "uarch-step.h"
-#include "unique-c-ptr.h"
 #include "variant-hasher.h"
 #include "virtio-address-range.h"
 
@@ -499,11 +502,8 @@ void machine::dump_insn_hist() {
 }
 
 void machine::dump_stats() {
-#if DUMP_STATS
-    const auto hr = [](uint64_t a, uint64_t b) {
-        // NOLINTNEXTLINE(bugprone-narrowing-conversions,cppcoreguidelines-narrowing-conversions)
-        return static_cast<double>(b) / (a + b);
-    };
+#ifdef DUMP_STATS
+    const auto hr = [](uint64_t a, uint64_t b) { return static_cast<double>(b) / static_cast<double>(a + b); };
 
     d_printf("\nMachine Counters:\n");
     d_printf("inner loops: %" PRIu64 "\n", m_counters["stats.inner_loop"]);
@@ -1428,7 +1428,7 @@ static std::optional<std::span<const unsigned char>> ar_host_memory_view(const a
             throw std::runtime_error{
                 "memory address range "s.append(ar.get_description()).append("has no host memory")};
         }
-        return std::span<const unsigned char>{ar.get_host_memory() + offset, length};
+        return std::span<const unsigned char>{ar.get_host_memory() + offset, static_cast<size_t>(length)};
     }
     return {};
 }
@@ -1465,7 +1465,7 @@ void machine::read_memory(uint64_t paddr, unsigned char *data, uint64_t length)
         // Write as much as possible from current address range
         if (paddr >= ar_start && paddr < gap_start) {
             const auto from_ar = std::min(gap_start - paddr, length);
-            auto data_view = std::span<unsigned char>{data, from_ar};
+            auto data_view = std::span<unsigned char>{data, static_cast<size_t>(from_ar)};
             auto ar_view = ar_host_memory_view(ar, paddr - ar_start, from_ar);
             if (ar_view) {
                 std::ranges::copy(*ar_view, data_view.begin());
@@ -1561,7 +1561,7 @@ void machine::fill_memory(uint64_t paddr, uint8_t val, uint64_t length) {
     foreach_aligned_chunk(paddr, length, AR_PAGE_SIZE, [&ar, val](auto chunk_start, auto chunk_length) {
         const auto offset = chunk_start - ar.get_start();
         const auto dest = ar.get_host_memory() + offset;
-        if (val != 0 || !is_pristine(std::span<const unsigned char>{dest, chunk_length})) {
+        if (val != 0 || !is_pristine(std::span<const unsigned char>{dest, static_cast<size_t>(chunk_length)})) {
             memset(dest, val, chunk_length);
             ar.get_dirty_page_tree().mark_dirty_page_and_up(offset);
         }
@@ -1861,10 +1861,7 @@ interpreter_break_reason machine::log_step(uint64_t mcycle_count, const std::str
     auto root_hash_before = get_root_hash();
     record_step_state_access::context context(filename, m_c.hash_tree.hash_function);
     record_step_state_access a(context, *this);
-    uint64_t mcycle_end{};
-    if (__builtin_add_overflow(a.read_mcycle(), mcycle_count, &mcycle_end)) {
-        mcycle_end = UINT64_MAX;
-    }
+    const uint64_t mcycle_end = saturating_add(a.read_mcycle(), mcycle_count);
     os_silence_putchar(m_r.htif.no_console_putchar);
     auto break_reason = interpret(a, mcycle_end);
     a.finish();
@@ -1879,10 +1876,7 @@ interpreter_break_reason machine::verify_step(const machine_hash &root_hash_befo
     auto data = make_unique_mmap<unsigned char>(data_length, os_mmap_flags{}, filename, data_length);
     replay_step_state_access::context context;
     replay_step_state_access a(context, data.get(), data_length, root_hash_before);
-    uint64_t mcycle_end{};
-    if (__builtin_add_overflow(a.read_mcycle(), mcycle_count, &mcycle_end)) {
-        mcycle_end = UINT64_MAX;
-    }
+    const uint64_t mcycle_end = saturating_add(a.read_mcycle(), mcycle_count);
     auto break_reason = interpret(a, mcycle_end);
     a.finish(root_hash_after);
     return break_reason;
@@ -1934,7 +1928,7 @@ std::pair<uint64_t, execute_status> machine::poll_external_interrupts(uint64_t m
         // If timeout is greater than zero, we should also increment mcycle relative to the elapsed time
         if (timeout_us > 0) {
             const int64_t end_us = os_now_us();
-            const uint64_t elapsed_us = static_cast<uint64_t>(std::max(end_us - start_us, INT64_C(0)));
+            const uint64_t elapsed_us = static_cast<uint64_t>(std::max<int64_t>(end_us - start_us, 0));
             const uint64_t next_mcycle = mcycle + (elapsed_us * RTC_CYCLES_PER_US);
             mcycle = std::min(std::max(next_mcycle, mcycle), mcycle_max);
         }
@@ -1965,12 +1959,12 @@ void machine::write_counter(uint64_t val, const char *name, const char *domain)
     m_counters[get_counter_key(name, domain)] = val;
 }
 
-void machine::collect_mcycle_root_hashes(uint64_t mcycle_end, uint64_t mcycle_period, uint64_t mcycle_phase,
-    uint32_t log2_bundle_mcycle_count, mcycle_root_hashes &result) {
-    auto clear_result_on_failure = make_scope_fail([&] {
-        result = mcycle_root_hashes{};
-    });
+mcycle_root_hashes machine::collect_mcycle_root_hashes(uint64_t mcycle_end, uint64_t mcycle_period,
+    uint64_t mcycle_phase, int32_t log2_bundle_mcycle_count,
+    const std::optional<back_merkle_tree> &previous_back_tree) {
     const uint64_t mcycle_start = read_reg(reg::mcycle);
+
+    // Check preconditions
     if (mcycle_end < mcycle_start) {
         throw std::runtime_error{"mcycle is past"};
     }
@@ -1980,8 +1974,10 @@ void machine::collect_mcycle_root_hashes(uint64_t mcycle_end, uint64_t mcycle_pe
     if (mcycle_phase >= mcycle_period) {
         throw std::runtime_error{"mcycle_phase must be in {0, ..., mcycle_period-1}"};
     }
-    if (log2_bundle_mcycle_count != 0) {
-        throw std::runtime_error{"log2_bundle_mcycle_count != 0 is unsupported yet"};
+    if (previous_back_tree.has_value() &&
+        (previous_back_tree->get_log2_max_leaves() != log2_bundle_mcycle_count ||
+            previous_back_tree->get_hash_function() != m_c.hash_tree.hash_function)) {
+        throw std::runtime_error{"back tree context is incompatible"};
     }
     if (read_reg(reg::iunrep) != 0) {
         throw std::runtime_error{"cannot collect hashes from unreproducible machines"};
@@ -1993,74 +1989,133 @@ void machine::collect_mcycle_root_hashes(uint64_t mcycle_end, uint64_t mcycle_pe
         throw std::runtime_error{"update hash tree failed"};
     }
     if (m_c.hash_tree.hash_function == hash_function_type::keccak256) {
-        // Ensure that the microarchitecture is reset
-        auto current_uarch_state_hash =
-            get_node_hash(AR_SHADOW_UARCH_STATE_START, UARCH_STATE_LOG2_SIZE, skip_hash_tree_update);
-        if (current_uarch_state_hash != get_uarch_pristine_state_hash()) {
+        if (get_node_hash(AR_SHADOW_UARCH_STATE_START, UARCH_STATE_LOG2_SIZE, skip_hash_tree_update) !=
+            get_uarch_pristine_state_hash()) {
             throw std::runtime_error{"microarchitecture is not reset"};
         }
     }
-    result.hashes.clear();
+
+    // Reset fields in the result that are meant for output only
+    mcycle_root_hashes result;
     result.mcycle_phase = mcycle_phase;
+    result.break_reason = interpreter_break_reason::reached_target_mcycle;
+
     // Check halted and yielded break reasons first to behave with same priority as the interpreter
     if (read_reg(reg::iflags_H) != 0) {
         result.break_reason = interpreter_break_reason::halted;
-        std::swap(result, result);
-        return;
+        return result;
     }
     if (read_reg(reg::iflags_Y) != 0) {
         result.break_reason = interpreter_break_reason::yielded_manually;
-        std::swap(result, result);
-        return;
+        return result;
     }
+
+    // Initialize back tree
+    if (previous_back_tree.has_value()) {
+        result.back_tree = *previous_back_tree;
+    } else {
+        result.back_tree = back_merkle_tree{log2_bundle_mcycle_count, m_c.hash_tree.hash_function};
+    }
+    auto &back_tree = result.back_tree.value();
+
+    // Reserve space before entering the loop to minimize allocations
     result.hashes.reserve(mcycle_period);
-    result.break_reason = interpreter_break_reason::reached_target_mcycle;
     collect_mcycle_hashes_state_access::context context{};
     context.dirty_pages.reserve(std::clamp<uint64_t>(mcycle_period * 4, 16, 4096));
     const collect_mcycle_hashes_state_access a(context, *this);
     os_silence_putchar(m_r.htif.no_console_putchar);
-    uint64_t mcycle_last_phase = mcycle_phase;
-    for (uint64_t mcycle_target = mcycle_start; mcycle_target < mcycle_end;) {
-        if (__builtin_add_overflow(mcycle_target, mcycle_period - mcycle_last_phase, &mcycle_target)) {
-            mcycle_target = UINT64_MAX;
-        }
+
+    // The first iteration will target the next mcycle_period boundary,
+    // but will not exceed mcycle_end if that limit is reached first
+    uint64_t mcycle_target = saturating_add(mcycle_start, mcycle_period - mcycle_phase, mcycle_end);
+    bool at_fixed_point = false;
+
+    // Run until reaching next mcycle target
+    while (read_reg(reg::mcycle) < mcycle_target) {
+        assert(!at_fixed_point);
+
+        // Attempt to execute until finishing this period
         result.break_reason = interpret(a, mcycle_target);
+
+        // Mark dirty pages tracked by the context
         for (const uint64_t paddr_page : context.dirty_pages) {
-            // NOLINTNEXTLINE(cppcoreguidelines-pro-type-const-cast)
-            auto &ar = const_cast<address_range &>(find_address_range(paddr_page, HASH_TREE_PAGE_SIZE));
+            auto &ar = find_address_range(paddr_page, HASH_TREE_PAGE_SIZE);
             ar.get_dirty_page_tree().mark_dirty_pages_and_up(paddr_page - ar.get_start(), HASH_TREE_PAGE_SIZE);
         }
+        context.dirty_pages.clear();
+
+        // Update hash tree and retrieve root hash
         if (!m_ht.update(m_ars)) {
             throw std::runtime_error{"update hash tree failed"};
         }
-        context.dirty_pages.clear();
+
+        // Check if we reached a fixed point
         const auto mcycle_reached = read_reg(reg::mcycle);
-        // If the machine stopped before we asked, we are done
-        if (mcycle_reached != mcycle_target || mcycle_target == UINT64_MAX) {
-            break;
+        // ??(edubart): maybe we should create a machine method or pseudo register to check if we are at fixed point?
+        at_fixed_point = result.break_reason == interpreter_break_reason::halted ||
+            result.break_reason == interpreter_break_reason::yielded_manually || mcycle_reached == UINT64_MAX;
+
+        // Compute the new phase
+        result.mcycle_phase = saturating_add(mcycle_reached - mcycle_start, mcycle_phase) % mcycle_period;
+
+        // Add the current root hash to the back tree whenever we reach a period boundary or a fixed point
+        // This ensures we only append at the correct intervals, even when mcycle_end does not align with the period
+        if (result.mcycle_phase == 0 || at_fixed_point) {
+            const auto root_hash = m_ht.get_root_hash();
+            // Append root hash relative to this period to the result
+            back_tree.push_back(root_hash);
+
+            // When back tree is full, we can append the bundled root hash and reset it
+            if (back_tree.full()) {
+                result.hashes.emplace_back(back_tree.get_root_hash());
+                back_tree.clear();
+            }
         }
-        result.hashes.emplace_back(m_ht.get_root_hash());
-        mcycle_last_phase = 0;
-        // If the machine stopped before we asked, we are done
-        if (result.break_reason != interpreter_break_reason::reached_target_mcycle) {
+
+        // If last iteration broke due to any other reason than reaching its target mcycle, we are done
+        if (at_fixed_point || result.break_reason != interpreter_break_reason::reached_target_mcycle) {
             break;
         }
+
+        // The next iteration will target the next mcycle_period boundary,
+        // but will not exceed mcycle_end if that limit is reached first
+        mcycle_target = saturating_add(mcycle_target, mcycle_period, mcycle_end);
     }
-    result.mcycle_phase = (read_reg(reg::mcycle) - mcycle_start + mcycle_phase) % mcycle_period;
+
+    // If the machine yielded manually or halted, then append bundled root hashes with padding
+    if (at_fixed_point && log2_bundle_mcycle_count > 0) {
+        // Construct pad tree containing repetitions of the current root hash
+        const auto pad_hashes = back_merkle_tree::make_pad_hashes(m_ht.get_root_hash(), log2_bundle_mcycle_count,
+            m_c.hash_tree.hash_function);
+
+        // Pad back tree when partially filled and append its bundled root hash
+        if (!back_tree.empty()) {
+            assert(!back_tree.full());
+            back_tree.pad_back(back_tree.get_remaining_leaf_count(), pad_hashes);
+            result.hashes.emplace_back(back_tree.get_root_hash());
+            back_tree.clear();
+        }
+
+        // Append bundled root hash containing only repetitions of the last root hash
+        result.hashes.emplace_back(pad_hashes[log2_bundle_mcycle_count]);
+    }
+
+    // There is no need to return the back tree when it's empty
+    if (back_tree.empty()) {
+        result.back_tree.reset();
+    }
+
+    return result;
 }
 
-void machine::collect_uarch_cycle_root_hashes(uint64_t mcycle_end, uint32_t log2_bundle_uarch_cycle_count,
-    uarch_cycle_root_hashes &result) {
-    auto clear_result_on_failure = make_scope_fail([&] {
-        result = uarch_cycle_root_hashes{};
-    });
+uarch_cycle_root_hashes machine::collect_uarch_cycle_root_hashes(uint64_t mcycle_end,
+    int32_t log2_bundle_uarch_cycle_count) {
     const uint64_t mcycle_start = read_reg(reg::mcycle);
+
+    // Check preconditions
     if (mcycle_end < mcycle_start) {
         throw std::runtime_error{"mcycle is past"};
     }
-    if (log2_bundle_uarch_cycle_count != 0) {
-        throw std::runtime_error{"log2_bundle_mcycle_count != 0 is unsupported yet"};
-    }
     if (read_reg(reg::iunrep) != 0) {
         throw std::runtime_error{"cannot collect hashes from unreproducible machines"};
     }
@@ -2074,80 +2129,197 @@ void machine::collect_uarch_cycle_root_hashes(uint64_t mcycle_end, uint32_t log2
     if (!update_hash_tree()) {
         throw std::runtime_error{"update hash tree failed"};
     }
-    auto current_uarch_state_hash =
-        get_node_hash(AR_SHADOW_UARCH_STATE_START, UARCH_STATE_LOG2_SIZE, skip_hash_tree_update);
-    if (current_uarch_state_hash != get_uarch_pristine_state_hash()) {
+    if (get_node_hash(AR_SHADOW_UARCH_STATE_START, UARCH_STATE_LOG2_SIZE, skip_hash_tree_update) !=
+        get_uarch_pristine_state_hash()) {
         throw std::runtime_error{"microarchitecture is not reset"};
     }
-    result.hashes.clear();
-    result.reset_indices.clear();
-    // Check halted and yielded break reasons first to behave with same priority as the interpreter
+
+    // Reset fields in the result that are meant for output only
+    uarch_cycle_root_hashes result;
+    result.break_reason = interpreter_break_reason::reached_target_mcycle;
+
+    // Check halted and yielded break reasons, to behave with same priority as the interpreter
     if (read_reg(reg::iflags_H) != 0) {
         result.break_reason = interpreter_break_reason::halted;
-        return;
+        return result;
     }
     if (read_reg(reg::iflags_Y) != 0) {
         result.break_reason = interpreter_break_reason::yielded_manually;
-        return;
+        return result;
     }
+
+    // Initialize back tree
+    back_merkle_tree back_tree(log2_bundle_uarch_cycle_count, m_c.hash_tree.hash_function);
+
+    // Reserve space before entering the loop to minimize allocations
     const uint64_t mcycle_count = mcycle_end - mcycle_start;
+    hash_tree::dirty_words_type reset_dirty_words;
+    reset_dirty_words.reserve(64);
     result.hashes.reserve(mcycle_count * 512);
     result.reset_indices.reserve(mcycle_count);
-    result.break_reason = interpreter_break_reason::reached_target_mcycle;
     collect_uarch_cycle_hashes_state_access::context context{};
     context.dirty_words.reserve(8);
     const collect_uarch_cycle_hashes_state_access a(context, *this);
     os_silence_putchar(m_r.htif.no_console_putchar);
-    for (uint64_t mcycles = 0; mcycles < mcycle_count; ++mcycles) {
-        // If the machine stopped before we asked, we are done
-        if (read_reg(reg::iflags_H) != 0) {
-            result.break_reason = interpreter_break_reason::halted;
-            break;
-        }
-        if (read_reg(reg::iflags_Y) != 0) {
-            result.break_reason = interpreter_break_reason::yielded_manually;
-            break;
-        }
-        if (read_reg(reg::iflags_X) != 0 && mcycles > 0) {
-            result.break_reason = interpreter_break_reason::yielded_automatically;
-            break;
-        }
-        uint64_t mcycle_target{};
-        if (__builtin_add_overflow(read_reg(reg::mcycle), 1, &mcycle_target)) {
-            break;
-        }
-        auto uarch_cycle_start = read_reg(reg::uarch_cycle);
+
+    // The first iteration will target the next mcycle,
+    // but will not exceed mcycle_end if that limit is reached first
+    uint64_t mcycle_target = saturating_add(mcycle_start, UINT64_C(1), mcycle_end);
+    bool at_fixed_point = false;
+
+    // Run until reaching next mcycle target, or one more time when at a fixed point
+    while (read_reg(reg::mcycle) < mcycle_target || at_fixed_point) {
+        assert(back_tree.empty());
+        assert(read_reg(reg::uarch_cycle) == 0);
+
         // Add one hash after each uarch cycle
-        for (;;) {
-            uint64_t uarch_cycle_target{};
-            if (__builtin_add_overflow(uarch_cycle_start, 1, &uarch_cycle_target)) {
-                break;
-            }
+        for (uint64_t uarch_cycle_target = 1;                // First uarch cycle target  should always be 1
+            read_reg(reg::uarch_cycle) < uarch_cycle_target; // Run until reaching uarch cycle target
+            uarch_cycle_target = saturating_add(uarch_cycle_target, UINT64_C(1))) {
+            // Attempt to advance to the next uarch cycle
             uarch_interpret(a, uarch_cycle_target);
-            const auto uarch_cycle_reached = read_reg(reg::uarch_cycle);
+
+            // Update hash tree and retrieve root hash
             if (!m_ht.update_words(m_ars, context.dirty_words)) {
                 throw std::runtime_error{"update hash tree failed"};
             }
+            const auto root_hash = m_ht.get_root_hash();
+
+            // Track dirty uarch words to be reset later
+            for (auto word_paddr : context.dirty_words) {
+                if (word_paddr >= UARCH_STATE_START_ADDRESS &&
+                    word_paddr - UARCH_STATE_START_ADDRESS < UARCH_STATE_LENGTH) {
+                    reset_dirty_words.insert(word_paddr);
+                }
+            }
             context.dirty_words.clear();
-            if (uarch_cycle_reached != uarch_cycle_target) {
+
+            // Stop if we cannot advance more uarch cycles
+            if (read_reg(reg::uarch_cycle) != uarch_cycle_target) {
                 break;
             }
-            result.hashes.emplace_back(m_ht.get_root_hash());
-            uarch_cycle_start = uarch_cycle_reached;
+
+            // Append root hash to the result
+            back_tree.push_back(root_hash);
+
+            // When back tree is full, we can append the bundled root hash and reset it
+            if (back_tree.full()) {
+                result.hashes.emplace_back(back_tree.get_root_hash());
+                back_tree.clear();
+            }
+        }
+
+        // Ensure we uarch is really halted
+        if (read_reg(reg::uarch_halt_flag) == 0) {
+            throw std::runtime_error{"uarch is not halted after mcycle advance"};
         }
-        //??D maybe optimize this?
-        reset_uarch();
-        if (!update_hash_tree()) {
+        const auto halt_root_hash = m_ht.get_root_hash();
+
+        // Perform reset uarch directly (as an optimization), we need to only revert dirty words in its state
+        // Reset uarch registers
+        m_us->registers = uarch_registers_state{};
+        // Reset dirty words in uarch ram
+        auto &uram = find_address_range(AR_UARCH_RAM_START, AR_UARCH_RAM_LENGTH);
+        for (auto word_paddr : reset_dirty_words) {
+            if (word_paddr >= AR_UARCH_RAM_START && word_paddr - AR_UARCH_RAM_START < AR_UARCH_RAM_LENGTH) {
+                const uint64_t uram_start_offset = word_paddr - AR_UARCH_RAM_START;
+                const uint64_t uram_end_offset =
+                    std::min<uint64_t>(uram_start_offset + HASH_TREE_WORD_SIZE, AR_UARCH_RAM_LENGTH);
+                const uint64_t size = uram_end_offset - uram_start_offset;
+                // Handle the portion that needs to be copied from uarch_pristine_ram
+                const uint64_t copy_size = (uram_start_offset < uarch_pristine_ram_len) ?
+                    std::min<uint64_t>(size, uarch_pristine_ram_len - uram_start_offset) :
+                    0;
+                if (copy_size > 0) {
+                    std::memcpy(uram.get_host_memory() + uram_start_offset, uarch_pristine_ram + uram_start_offset,
+                        copy_size);
+                }
+                // Handle the portion that needs to be zeroed
+                if (copy_size < size) {
+                    std::memset(uram.get_host_memory() + uram_start_offset + copy_size, 0, size - copy_size);
+                }
+            }
+        }
+        // Update hash tree and retrieve root hash
+        if (!m_ht.update_words(m_ars, reset_dirty_words)) {
             throw std::runtime_error{"update hash tree failed"};
         }
-        const auto mcycle_reached = read_reg(reg::mcycle);
-        if (mcycle_reached != mcycle_target) {
+        reset_dirty_words.clear();
+        const auto reset_root_hash = m_ht.get_root_hash();
+
+        // Add one hash after the uarch reset
+        if (log2_bundle_uarch_cycle_count > 0) {
+            const auto halt_pad_hashes = back_merkle_tree::make_pad_hashes(halt_root_hash,
+                log2_bundle_uarch_cycle_count, m_c.hash_tree.hash_function);
+
+            // Pad back tree when partially filled and then append its bundled root hash
+            if (!back_tree.empty()) {
+                assert(!back_tree.full());
+                back_tree.pad_back(back_tree.get_remaining_leaf_count(), halt_pad_hashes);
+                result.hashes.emplace_back(back_tree.get_root_hash());
+                back_tree.clear();
+            }
+
+            // Append bundled root hash containing only repetitions of the halt root hash
+            result.hashes.emplace_back(halt_pad_hashes[log2_bundle_uarch_cycle_count]);
+
+            // Append bundled root hash containing repetitions of the halt root hash on the left
+            // and one reset root hash on the right
+            assert(back_tree.empty());
+            back_tree.pad_back((1 << log2_bundle_uarch_cycle_count) - 1, halt_pad_hashes);
+            back_tree.push_back(reset_root_hash);
+            assert(back_tree.full());
+            result.hashes.emplace_back(back_tree.get_root_hash());
+            back_tree.clear();
+
+            // Add the index where reset happened
+            result.reset_indices.emplace_back(result.hashes.size() - 1);
+        } else {
+            result.hashes.push_back(reset_root_hash);
+
+            // Add the index where reset happened
+            result.reset_indices.emplace_back(result.hashes.size() - 1);
+        }
+
+        // Ensure the machine really reached mcycle target
+        if (read_reg(reg::mcycle) != mcycle_target) {
             throw std::runtime_error{"machine did not reach the expected target mcycle"};
         }
-        // Add one hash after the uarch reset, and the index where it happened
-        result.reset_indices.emplace_back(result.hashes.size());
-        result.hashes.emplace_back(m_ht.get_root_hash());
+
+        // If we already attempt to advance one mcycle over a fixed point, we are done
+        if (at_fixed_point) {
+            break;
+        }
+
+        // If the machine halted, yielded manuallly or reached mcycle UINT64_MAX,
+        // then we are at a fixed point and should always attempt to advance one more mcycle
+        if (read_reg(reg::iflags_H) != 0) {
+            result.break_reason = interpreter_break_reason::halted;
+            at_fixed_point = true;
+            continue;
+        }
+        if (read_reg(reg::iflags_Y) != 0) {
+            result.break_reason = interpreter_break_reason::yielded_manually;
+            at_fixed_point = true;
+            continue;
+        }
+        if (read_reg(reg::mcycle) == UINT64_MAX) { // Reached maximum mcycle
+            at_fixed_point = true;
+            continue;
+        }
+        if (read_reg(reg::iflags_X) != 0) {
+            result.break_reason = interpreter_break_reason::yielded_automatically;
+            break;
+        }
+
+        // The next iteration will target the next mcycle successor,
+        // but will not exceed mcycle_end if that limit is reached first
+        mcycle_target = saturating_add(mcycle_target, UINT64_C(1), mcycle_end);
     }
+
+    assert(back_tree.empty());
+
+    return result;
 }
 
 } // namespace cartesi
diff --git a/src/machine.h b/src/machine.h
index 4fb522b3f..5ed10c85b 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -20,17 +20,17 @@
 /// \file
 /// \brief Cartesi machine interface
 
+#include <algorithm>
 #include <cstdint>
-#include <memory>
+#include <optional>
 #include <stdexcept>
 #include <string>
 #include <unordered_map>
 #include <utility>
-#include <vector>
 
 #include "access-log.h"
-#include "address-range-description.h"
 #include "address-range.h"
+#include "back-merkle-tree.h"
 #include "hash-tree-stats.h"
 #include "hash-tree.h"
 #include "host-addr.h"
@@ -38,11 +38,11 @@
 #include "interpret.h"
 #include "machine-address-ranges.h"
 #include "machine-config.h"
+#include "machine-hash.h"
 #include "machine-reg.h"
 #include "machine-runtime-config.h"
 #include "mcycle-root-hashes.h"
 #include "os.h"
-#include "pmas-constants.h"
 #include "processor-state.h"
 #include "scope-remove.h"
 #include "shadow-tlb.h"
@@ -50,7 +50,6 @@
 #include "uarch-interpret.h"
 #include "uarch-processor-state.h"
 #include "variant-hasher.h"
-#include "virtio-address-range.h"
 
 namespace cartesi {
 
@@ -174,6 +173,14 @@ class machine final {
         return m_ars.find(paddr, length);
     }
 
+    /// \brief Returns address range that covers a given physical memory region
+    /// \param paddr Target physical address of start of region.
+    /// \param length Length of region, in bytes.
+    /// \returns Corresponding address range if found, or an empty sentinel otherwise.
+    address_range &find_address_range(uint64_t paddr, uint64_t length) noexcept {
+        return m_ars.find(paddr, length);
+    }
+
     /// \brief No default constructor
     machine() = delete;
     /// \brief No copy constructor
@@ -208,13 +215,16 @@ class machine final {
     /// \param mcycle_phase Number of machine cycles elapsed since last root hash collected.
     /// \param log2_bundle_mcycle_count Log base 2 of the amount of mcycle root hashes to bundle.
     /// If greater than 0, it collects subtree root hashes for 2^log2_bundle_mcycle_count root hashes.
-    /// \param result Stores into result.hashes the root hashes after each period.
+    /// \param previous_back_tree Optional context to continue collecting bundled root hashes.
+    /// \returns The collected mcycle root hashes.
+    /// Stores into result.hashes the root hashes after each period.
     /// Stores into result.mcycle_phase the number of machine cycles after last root hash collected.
     /// Stores into result.break_reason the reason the function returned.
+    /// Stores into result.back_tree the back tree context to continue collecting bundled root hashes.
     /// \detail The first hash added to \p result.hashes is the root hash after (\p mcycle_period - \p mcycle_phase)
     /// machine cycles (if the function managed to get that far before returning).
-    void collect_mcycle_root_hashes(uint64_t mcycle_end, uint64_t mcycle_period, uint64_t mcycle_phase,
-        uint32_t log2_bundle_mcycle_count, mcycle_root_hashes &result);
+    mcycle_root_hashes collect_mcycle_root_hashes(uint64_t mcycle_end, uint64_t mcycle_period, uint64_t mcycle_phase,
+        int32_t log2_bundle_mcycle_count, const std::optional<back_merkle_tree> &previous_back_tree = {});
 
     /// \brief Runs the machine for the given mcycle count and generates a log of accessed pages and proof data.
     /// \param mcycle_count Number of mcycles to run the machine for.
@@ -238,14 +248,15 @@ class machine final {
     /// \brief Collects the root hashes after every uarch cycle until mcycle reaches \p mcycle_end,
     /// the machine yields, or halts. Implicitly resetting the uarch between mcycles.
     /// \param mcycle_end End machine cycle value to execute, uarch cycle by uarch cycle.
-    /// \param result Stores into result.hashes the root hashes after each uarch cycle.
     /// \param log2_bundle_uarch_cycle_count Log base 2 of the amount of uarch cycle root hashes to bundle.
-    /// Stores into result.reset_indices the indices of the root hashes after each implicit uarch reset (i.e., after
-    /// each machine cycle). Stores into result.break_reason the reason why the function returned.
+    /// \returns The collected uarch cycle root hashes.
+    /// Stores into result.hashes the root hashes after each uarch cycle.
+    /// Stores into result.reset_indices the indices of the root hashes after each implicit uarch reset
+    /// (i.e., after each machine cycle).
+    /// Stores into result.break_reason the reason why the function returned.
     /// \detail The first hash added to \p result.hashes is the root hash after the first uarch cycle, the last is the
     /// root hash at the time function returns (for whatever reason), which always happens right after an uarch reset.
-    void collect_uarch_cycle_root_hashes(uint64_t mcycle_end, uint32_t log2_bundle_uarch_cycle_count,
-        uarch_cycle_root_hashes &result);
+    uarch_cycle_root_hashes collect_uarch_cycle_root_hashes(uint64_t mcycle_end, int32_t log2_bundle_uarch_cycle_count);
 
     /// \brief Advances one micro step and returns a state access log.
     /// \param log_type Type of access log to generate.
diff --git a/src/mcycle-root-hashes.h b/src/mcycle-root-hashes.h
index f1a6dc222..8152476c7 100644
--- a/src/mcycle-root-hashes.h
+++ b/src/mcycle-root-hashes.h
@@ -18,7 +18,9 @@
 #define MCYCLE_ROOT_HASHES_H
 
 #include <cstdint>
+#include <optional>
 
+#include "back-merkle-tree.h"
 #include "interpret.h"
 #include "machine-hash.h"
 
@@ -26,9 +28,10 @@ namespace cartesi {
 
 /// \brief Collected mcycle root hashes
 struct mcycle_root_hashes {
-    machine_hashes hashes;                   ///< Root hashes collected after each machine cycle period
-    uint64_t mcycle_phase{};                 ///< Machine cycles elapsed since last collected root hash
-    interpreter_break_reason break_reason{}; ///< Reason why function returned
+    machine_hashes hashes;                     ///< Root hashes collected after each machine cycle period
+    uint64_t mcycle_phase{};                   ///< Machine cycles elapsed since last collected root hash
+    interpreter_break_reason break_reason{};   ///< Reason why function returned
+    std::optional<back_merkle_tree> back_tree; ///< Root hashes context
 };
 
 } // namespace cartesi
diff --git a/src/memory-address-range.cpp b/src/memory-address-range.cpp
index 7c9458c8f..e8bee634f 100644
--- a/src/memory-address-range.cpp
+++ b/src/memory-address-range.cpp
@@ -16,15 +16,17 @@
 
 #include "memory-address-range.h"
 
-#include <cerrno>
-#include <cstdio>
-#include <cstring>
+#include <algorithm>
+#include <cstddef>
+#include <cstdint>
+#include <exception>
 #include <stdexcept>
-#include <system_error>
 
 #include "address-range-constants.h"
-#include "os-filesystem.h"
-#include "unique-c-ptr.h"
+#include "address-range.h"
+#include "machine-config.h"
+#include "os-mmap.h"
+#include "pmas.h"
 
 namespace cartesi {
 
@@ -65,8 +67,8 @@ memory_address_range::memory_address_range(const std::string &description, uint6
     m_host_memory{m_ptr.get()},
     m_config{memory_config},
     m_backing_store{backing_store},
-    m_dpt{get_level_count(length), length >> AR_LOG2_PAGE_SIZE},
-    m_dht{get_level_count(length), length >> AR_LOG2_PAGE_SIZE} {
+    m_dpt{get_level_count(length), static_cast<size_t>(length >> AR_LOG2_PAGE_SIZE)},
+    m_dht{get_level_count(length), static_cast<size_t>(length >> AR_LOG2_PAGE_SIZE)} {
 } catch (const std::exception &e) {
     throw std::invalid_argument{std::string{e.what()}.append(" when initializing ").append(description)};
 } catch (...) {
diff --git a/src/memory-address-range.h b/src/memory-address-range.h
index 37be5c729..2879d0621 100644
--- a/src/memory-address-range.h
+++ b/src/memory-address-range.h
@@ -17,14 +17,15 @@
 #ifndef MEMORY_ADDRESS_RANGE_H
 #define MEMORY_ADDRESS_RANGE_H
 
-#include <cassert>
-#include <variant>
+#include <cstdint>
+#include <string>
 
 #include "address-range.h"
 #include "dense-hash-tree.h"
 #include "dirty-page-tree.h"
 #include "machine-config.h"
 #include "os-mmap.h"
+#include "pmas.h"
 
 namespace cartesi {
 
@@ -46,7 +47,7 @@ struct memory_address_range_config {
 /// \file
 /// \brief An address range occupied by memory
 
-class memory_address_range : public address_range {
+class memory_address_range final : public address_range {
     unique_mmap_ptr<unsigned char> m_ptr; ///< Pointer to mapped memory
     unsigned char *m_host_memory;         ///< Start of associated memory region in host.
     memory_address_range_config m_config; ///< Memory configuration passed to constructor.
diff --git a/src/mock-address-range.h b/src/mock-address-range.h
index dd7b18714..ae6ab4ebc 100644
--- a/src/mock-address-range.h
+++ b/src/mock-address-range.h
@@ -18,6 +18,9 @@
 #define MOCK_ADDRESS_RANGE_H
 
 #include <array>
+#include <concepts>
+#include <cstdint>
+#include <type_traits>
 #include <utility>
 #include <variant>
 
@@ -25,6 +28,7 @@
 #include "clint-address-range.h"
 #include "htif-address-range.h"
 #include "plic-address-range.h"
+#include "pmas-constants.h"
 #include "pmas.h"
 
 namespace cartesi {
@@ -70,7 +74,7 @@ static inline mock_address_range make_mock_address_range(uint64_t istart, uint64
             __builtin_trap();
             return std::monostate{};
     }
-};
+}
 
 template <typename ABRT>
 address_range &get_mock_address_range(mock_address_range &mock, ABRT abrt) {
diff --git a/src/os-filesystem.cpp b/src/os-filesystem.cpp
index 2a6c79385..bea6ea063 100644
--- a/src/os-filesystem.cpp
+++ b/src/os-filesystem.cpp
@@ -17,7 +17,7 @@
 #include "os-features.h"
 
 // Must be included before
-#include "os-posix-compat.h"
+#include "os-posix-compat.h" // IWYU pragma: keep
 
 #include <fcntl.h>    // open
 #include <sys/stat.h> // stat/fstat/mkdir/fchmod
@@ -29,6 +29,7 @@
 #include "is-pristine.h"
 #include "scope-exit.h"
 
+#include <algorithm>
 #include <array>
 #include <cerrno>
 #include <cstddef>
@@ -38,6 +39,7 @@
 #include <memory>
 #include <span>
 #include <sstream>
+#include <string>
 #include <system_error>
 #include <tuple>
 #include <utility>
diff --git a/src/os-filesystem.h b/src/os-filesystem.h
index 12630faa9..fbd2a6e90 100644
--- a/src/os-filesystem.h
+++ b/src/os-filesystem.h
@@ -21,7 +21,6 @@
 #include <memory>
 #include <span>
 #include <string>
-#include <system_error>
 #include <utility>
 
 namespace cartesi::os {
diff --git a/src/os-mmap.cpp b/src/os-mmap.cpp
index d89dedc5d..1b1acc17e 100644
--- a/src/os-mmap.cpp
+++ b/src/os-mmap.cpp
@@ -17,7 +17,7 @@
 #include "os-features.h"
 
 // Must be included before
-#include "os-posix-compat.h"
+#include "os-posix-compat.h" // IWYU pragma: keep
 
 #if defined(HAVE_MMAP)
 #include <fcntl.h>    // open
@@ -37,10 +37,14 @@
 
 #include "scope-exit.h"
 
+#include <algorithm>
 #include <cerrno>
+#include <cstdint>
 #include <cstring>
 #include <stdexcept>
+#include <string>
 #include <system_error>
+#include <utility>
 
 namespace cartesi {
 
diff --git a/src/os-mmap.h b/src/os-mmap.h
index 53bf02fda..05a9060b3 100644
--- a/src/os-mmap.h
+++ b/src/os-mmap.h
@@ -35,6 +35,7 @@
 /// mappings, and synchronization of file-backed memory regions.
 /// \}
 
+#include <cstddef>
 #include <cstdint>
 #include <memory>
 #include <string>
@@ -95,7 +96,7 @@ namespace detail {
 
 struct mmap_deleter {
     os_mmapd m_mmapd;
-    explicit mmap_deleter(os_mmapd mmapd) : m_mmapd(mmapd) {};
+    explicit mmap_deleter(os_mmapd mmapd) : m_mmapd(mmapd) {}
     template <typename T>
     void operator()(T * /*ptr*/) const noexcept {
         os_munmap(m_mmapd);
diff --git a/src/os-posix-compat.h b/src/os-posix-compat.h
index f4b00c53f..6f24fc186 100644
--- a/src/os-posix-compat.h
+++ b/src/os-posix-compat.h
@@ -173,7 +173,7 @@
 
 #endif // _WIN32
 
-#include <fcntl.h>
+#include <fcntl.h> // IWYU pragma: keep
 
 #ifndef O_BINARY
 #define O_BINARY 0 // NOLINT(cppcoreguidelines-macro-usage)
diff --git a/src/os.cpp b/src/os.cpp
index 8ed0ec728..0dfb6cab9 100644
--- a/src/os.cpp
+++ b/src/os.cpp
@@ -17,10 +17,11 @@
 #include "os-features.h"
 
 // Must be included first
-#include "os-posix-compat.h"
+#include "os-posix-compat.h" // IWYU pragma: keep
 
 #include "os.h"
 
+#include <algorithm>
 #include <array>
 #include <cerrno>
 #include <chrono>
@@ -28,14 +29,10 @@
 #include <cstdio>
 #include <cstdlib>
 #include <cstring>
-#include <exception>
-#include <functional>
-#include <string>
-#include <system_error>
+#include <stdexcept> // IWYU pragma: keep
 #include <tuple>
-#include <vector>
 
-#include <sys/time.h>
+#include <sys/time.h> // IWYU pragma: keep
 
 #ifdef HAVE_SIGACTION
 #include <csignal>
@@ -70,16 +67,11 @@
 
 #endif // _WIN32
 
-#include "compiler-defines.h"
-#include "unique-c-ptr.h"
-
 // Enable these defines to debug
 // #define DEBUG_OS
 
 namespace cartesi {
 
-using namespace std::string_literals;
-
 #ifdef HAVE_TTY
 /// \brief TTY global state
 struct tty_state {
diff --git a/src/page-hash-tree-cache.h b/src/page-hash-tree-cache.h
index 2523a476d..76d4f87c4 100644
--- a/src/page-hash-tree-cache.h
+++ b/src/page-hash-tree-cache.h
@@ -20,7 +20,11 @@
 /// \file
 /// \brief Page hash-tree cache interface
 
+#include <algorithm>
+#include <array>
 #include <bit>
+#include <cstddef>
+#include <cstdint>
 #include <functional>
 #include <iomanip>
 #include <iostream>
@@ -28,18 +32,20 @@
 #include <ranges>
 #include <span>
 #include <unordered_map>
+#include <utility>
+#include <vector>
 
 #include <boost/container/static_vector.hpp>
 #include <boost/intrusive/list.hpp>
+#include <boost/intrusive/list_hook.hpp>
 
-#include "address-range-constants.h"
 #include "algorithm.h"
-#include "compiler-defines.h"
+#include "assert-printf.h"
+#include "concepts.h"
 #include "hash-tree-constants.h"
 #include "i-hasher.h"
 #include "is-pristine.h"
 #include "machine-hash.h"
-#include "meta.h"
 #include "page-hash-tree-cache-stats.h"
 #include "ranges.h"
 #include "signposts.h"
@@ -282,8 +288,7 @@ class page_hash_tree_cache {
         /// \brief Enqueues a leaf for hashing
         void enqueue_leaf(const_hash_tree_word_view data, page_hash_tree_view page_tree, int word_index) noexcept {
             m_leaves_queue.enqueue(data, page_tree[word_index]);
-            algorithm::try_push_back(m_dirty_queue,
-                dirty_entry{.page_tree = page_tree, .node_index = entry::parent(word_index)});
+            try_push_back(m_dirty_queue, dirty_entry{.page_tree = page_tree, .node_index = entry::parent(word_index)});
         }
 
         /// \brief Flushes the entire queue
@@ -298,7 +303,7 @@ class page_hash_tree_cache {
                     m_concat_queue.enqueue(d.page_tree[entry::left_child(d.node_index)],
                         d.page_tree[entry::right_child(d.node_index)], d.page_tree[d.node_index]);
                     if (d.node_index > 1) [[likely]] {
-                        algorithm::try_push_back(next_dirty_queue,
+                        try_push_back(next_dirty_queue,
                             dirty_entry{.page_tree = d.page_tree, .node_index = entry::parent(d.node_index)});
                     }
                 }
@@ -380,7 +385,7 @@ class page_hash_tree_cache {
         while (start != 0) {
             for (int index = start; index < 2 * start; ++index) {
                 const auto node_hash =
-                    get_concat_hash(h, page_tree[e.left_child(index)], page_tree[e.right_child(index)]);
+                    get_concat_hash(h, page_tree[entry::left_child(index)], page_tree[entry::right_child(index)]);
                 if (node_hash != page_tree[index]) {
                     std::cerr << "hash mismatch in index " << std::dec << index << ":" << log2_size << '\n';
                     return false;
diff --git a/src/plic-address-range.cpp b/src/plic-address-range.cpp
index fe7a01357..44f423963 100644
--- a/src/plic-address-range.cpp
+++ b/src/plic-address-range.cpp
@@ -16,12 +16,12 @@
 
 #include "plic-address-range.h"
 
-#include "assert-printf.h"
 #include <cstdint>
 
+#include "address-range-constants.h"
 #include "i-device-state-access.h"
 #include "interpret.h"
-#include "pmas-constants.h"
+#include "plic-constants.h"
 #include "riscv-constants.h"
 
 // Enable these defines to debug PLIC
diff --git a/src/plic-address-range.h b/src/plic-address-range.h
index ed1a8a7b1..6f4794599 100644
--- a/src/plic-address-range.h
+++ b/src/plic-address-range.h
@@ -22,7 +22,9 @@
 #include "address-range-constants.h"
 #include "address-range.h"
 #include "i-device-state-access.h"
-#include "plic-constants.h"
+#include "interpret.h"
+#include "pmas-constants.h"
+#include "pmas.h"
 
 /// \file
 /// \brief Platform-Level Interrupt Controller address range.
diff --git a/src/pmas-defines.h b/src/pmas-defines.h
index 42561cd27..cdd3ee5a2 100644
--- a/src/pmas-defines.h
+++ b/src/pmas-defines.h
@@ -36,5 +36,6 @@
 #ifndef EXPAND_UINT64_C
 #define EXPAND_UINT64_C(a) UINT64_C(a)
 #endif
+
 // NOLINTEND(cppcoreguidelines-macro-usage,cppcoreguidelines-macro-to-enum,modernize-macro-to-enum)
 #endif /* end of include guard: PMA_DEFINES_H */
diff --git a/src/pristine-merkle-tree.cpp b/src/pristine-merkle-tree.cpp
deleted file mode 100644
index 57edd6cf1..000000000
--- a/src/pristine-merkle-tree.cpp
+++ /dev/null
@@ -1,61 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#include "pristine-merkle-tree.h"
-
-#include <algorithm>
-#include <cassert>
-#include <cstdint>
-#include <stdexcept>
-#include <vector>
-
-#include "i-hasher.h"
-
-/// \file
-/// \brief Pristine Merkle tree implementation.
-
-namespace cartesi {
-
-pristine_merkle_tree::pristine_merkle_tree(int log2_root_size, int log2_word_size, hash_function_type hash_function) :
-    m_log2_root_size{log2_root_size},
-    m_log2_word_size{log2_word_size},
-    m_hashes(std::max(0, log2_root_size - log2_word_size + 1)) {
-    if (log2_root_size < 0) {
-        throw std::out_of_range{"log2_root_size is negative"};
-    }
-    if (log2_word_size < 0) {
-        throw std::out_of_range{"log2_word_size is negative"};
-    }
-    if (log2_word_size > log2_root_size) {
-        throw std::out_of_range{"log2_word_size is greater than log2_root_size"};
-    }
-    std::vector<uint8_t> word(1 << log2_word_size, 0);
-    assert(word.size() == (UINT64_C(1) << log2_word_size));
-    variant_hasher h{hash_function};
-    h.hash(word, m_hashes[0]);
-    for (unsigned i = 1; i < m_hashes.size(); ++i) {
-        get_concat_hash(h, m_hashes[i - 1], m_hashes[i - 1], m_hashes[i]);
-    }
-}
-
-const machine_hash &pristine_merkle_tree::get_hash(int log2_size) const {
-    if (log2_size < m_log2_word_size || log2_size > m_log2_root_size) {
-        throw std::out_of_range{"log2_size is out of range"};
-    }
-    return m_hashes[log2_size - m_log2_word_size];
-}
-
-} // namespace cartesi
diff --git a/src/pristine-merkle-tree.h b/src/pristine-merkle-tree.h
deleted file mode 100644
index 9f65bf565..000000000
--- a/src/pristine-merkle-tree.h
+++ /dev/null
@@ -1,53 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef PRISTINE_MERKLE_TREE_H
-#define PRISTINE_MERKLE_TREE_H
-
-#include <cstdint>
-#include <vector>
-
-#include "machine-hash.h"
-#include "variant-hasher.h"
-
-/// \file
-/// \brief Pristine Merkle tree interface.
-
-namespace cartesi {
-
-/// \brief Hashes of pristine subtrees for a range of sizes
-class pristine_merkle_tree {
-public:
-    /// \brief Constructor
-    /// \param log2_root_size Log<sub>2</sub> of root node
-    /// \param log2_word_size Log<sub>2</sub> of word
-    pristine_merkle_tree(int log2_root_size, int log2_word_size, hash_function_type hash_function);
-
-    /// \brief Returns hash of pristine subtree
-    /// \param log2_size Log<sub>2</sub> of subtree size. Must be between
-    /// log2_word_size (inclusive) and log2_root_size (inclusive) passed
-    /// to constructor.
-    const machine_hash &get_hash(int log2_size) const;
-
-private:
-    int m_log2_root_size;               ///< Log<sub>2</sub> of tree size
-    int m_log2_word_size;               ///< Log<sub>2</sub> of word size
-    std::vector<machine_hash> m_hashes; ///< Vector with hashes
-};
-
-} // namespace cartesi
-
-#endif
diff --git a/src/processor-state.h b/src/processor-state.h
index f73d31afa..95cd1e282 100644
--- a/src/processor-state.h
+++ b/src/processor-state.h
@@ -20,14 +20,11 @@
 /// \file
 /// \brief Cartesi machine processor state structure definition.
 
-#include <array>
 #include <cstddef>
 #include <cstdint>
-#include <vector>
 
-#include "address-range.h"
+#include "address-range-constants.h"
 #include "hot-tlb.h"
-#include "riscv-constants.h"
 #include "shadow-registers.h"
 #include "shadow-tlb.h"
 
diff --git a/src/record-send-cmio-state-access.h b/src/record-send-cmio-state-access.h
index 00f1b024c..f8cd7b09c 100644
--- a/src/record-send-cmio-state-access.h
+++ b/src/record-send-cmio-state-access.h
@@ -20,22 +20,26 @@
 /// \file
 /// \brief State access implementation that records state accesses to an access log.
 
-#include <cassert>
 #include <cstdint>
 #include <cstring>
-#include <memory>
+#include <span>
 #include <utility>
 
 #include "access-log.h"
+#include "assert-printf.h"
 #include "hash-tree-constants.h"
 #include "host-addr.h"
 #include "i-accept-scoped-notes.h"
+#include "i-hasher.h"
 #include "i-state-access.h"
 #include "machine-hash.h"
+#include "machine-reg.h"
 #include "machine.h"
 #include "meta.h"
 #include "processor-state.h"
+#include "scoped-note.h"
 #include "shadow-registers.h"
+#include "variant-hasher.h"
 
 namespace cartesi {
 
@@ -85,8 +89,8 @@ class record_send_cmio_state_access :
         const uint64_t pleaf_aligned = paligned & ~(HASH_TREE_WORD_SIZE - 1);
         access a;
 
-        // We can skip updating the merkle tree while getting the proof because we assume that:
-        // 1) A full merkle tree update was called at the beginning of machine::log_load_cmio_input()
+        // We can skip updating the hash tree while getting the proof because we assume that:
+        // 1) A full hash tree update was called at the beginning of machine::log_load_cmio_input()
         // 2) We called update_hash_tree_page on all write accesses
         const auto proof = m_m.get_proof(pleaf_aligned, HASH_TREE_LOG2_WORD_SIZE, skip_hash_tree_update);
         // We just store the sibling hashes in the access because this is the only missing piece of data needed to
@@ -114,7 +118,7 @@ class record_send_cmio_state_access :
     /// \param text Textual description of the access.
     void log_before_write(uint64_t paligned, uint64_t val, const char *text) const {
         static_assert(HASH_TREE_LOG2_WORD_SIZE >= log2_size_v<uint64_t>,
-            "Merkle tree word size must be at least as large as a machine word");
+            "hash tree word size must be at least as large as a machine word");
         if ((paligned & (sizeof(uint64_t) - 1)) != 0) {
             throw std::invalid_argument{"paligned is not aligned to word size"};
         }
@@ -122,8 +126,8 @@ class record_send_cmio_state_access :
         const uint64_t pleaf_aligned = paligned & ~(HASH_TREE_WORD_SIZE - 1);
         access a;
 
-        // We can skip updating the merkle tree while getting the proof because we assume that:
-        // 1) A full merkle tree update was called at the beginning of machine::log_load_cmio_input()
+        // We can skip updating the hash tree while getting the proof because we assume that:
+        // 1) A full hash tree update was called at the beginning of machine::log_load_cmio_input()
         // 2) We called update_hash_tree_page on all write accesses
         const auto proof = m_m.get_proof(pleaf_aligned, HASH_TREE_LOG2_WORD_SIZE, skip_hash_tree_update);
         // We just store the sibling hashes in the access because this is the only missing piece of data needed to
@@ -151,7 +155,7 @@ class record_send_cmio_state_access :
         m_log.push_access(std::move(a), text);
     }
 
-    /// \brief Updates the Merkle tree after the modification of a word in the machine state.
+    /// \brief Updates the hash tree after the modification of a word in the machine state.
     /// \param paligned Physical address in the machine state, aligned to a 64-bit word.
     void update_after_write(uint64_t paligned) const {
         assert((paligned & (sizeof(uint64_t) - 1)) == 0);
@@ -159,7 +163,7 @@ class record_send_cmio_state_access :
         assert(updated);
     }
 
-    /// \brief Logs a write access before it happens, writes, and then update the Merkle tree.
+    /// \brief Logs a write access before it happens, writes, and then update the hash tree.
     /// \param paligned Physical address of the word in the machine state (Must be aligned to a 64-bit word).
     /// \param dest Reference to value before writing.
     /// \param val Value to write to \p dest.
@@ -242,7 +246,7 @@ class record_send_cmio_state_access :
         if (write_length > data_length) {
             m_m.fill_memory(paddr + data_length, 0, write_length - data_length);
         }
-        // we have to update the merkle tree after every write
+        // we have to update the hash tree after every write
         m_m.update_hash_tree();
 
         // log hash and written data
@@ -250,7 +254,8 @@ class record_send_cmio_state_access :
         a.get_written_hash().emplace();
         variant_hasher h(m_m.get_hash_function());
         const auto offset = paddr - ar.get_start();
-        get_merkle_tree_hash(h, std::span<const unsigned char>{ar.get_host_memory() + offset, write_length},
+        get_merkle_tree_hash(h,
+            std::span<const unsigned char>{ar.get_host_memory() + offset, static_cast<size_t>(write_length)},
             HASH_TREE_WORD_SIZE, a.get_written_hash().value());
         if (m_log.get_log_type().has_large_data()) {
             access_data &data = a.get_written().emplace(write_length);
diff --git a/src/record-step-state-access.h b/src/record-step-state-access.h
index b09c07e5a..f168f1709 100644
--- a/src/record-step-state-access.h
+++ b/src/record-step-state-access.h
@@ -17,19 +17,31 @@
 #ifndef RECORD_STEP_STATE_ACCESS_H
 #define RECORD_STEP_STATE_ACCESS_H
 
-#include <cassert>
+#include <array>
+#include <cstdint>
 #include <map>
-#include <optional>
+#include <stdexcept>
+#include <string>
+#include <utility>
 #include <vector>
 
-#include "compiler-defines.h"
+#include "address-range.h"
+#include "assert-printf.h"
+#include "hash-tree-constants.h"
 #include "hash-tree.h"
+#include "host-addr.h"
 #include "i-accept-scoped-notes.h"
 #include "i-prefer-shadow-state.h"
 #include "i-state-access.h"
+#include "machine-hash.h"
+#include "machine-reg.h"
 #include "machine.h"
 #include "os-filesystem.h"
+#include "os.h"
+#include "pmas-constants.h"
 #include "pmas.h"
+#include "riscv-constants.h"
+#include "shadow-registers.h"
 #include "shadow-tlb.h"
 #include "unique-c-ptr.h"
 #include "variant-hasher.h"
@@ -174,7 +186,7 @@ class record_step_state_access :
         page_indices_type::const_iterator &next_page_index, sibling_hashes_type &sibling_hashes) {
         auto page_count = UINT64_C(1) << page_count_log2_size;
         if (next_page_index == page_indices.cend() || page_index + page_count <= *next_page_index) {
-            // we can skip the merkle tree update, because a full update was done before the recording started
+            // we can skip the hash tree update, because a full update was done before the recording started
             sibling_hashes.push_back(m_m.get_node_hash(page_index << HASH_TREE_LOG2_PAGE_SIZE,
                 page_count_log2_size + HASH_TREE_LOG2_PAGE_SIZE, skip_hash_tree_update));
         } else if (page_count_log2_size > 0) {
diff --git a/src/replay-send-cmio-state-access.h b/src/replay-send-cmio-state-access.h
index 52ba8f38c..d86944b47 100644
--- a/src/replay-send-cmio-state-access.h
+++ b/src/replay-send-cmio-state-access.h
@@ -23,19 +23,19 @@
 #include <cstdint>
 #include <cstring>
 #include <ios>
+#include <span>
 #include <sstream>
 #include <stdexcept>
 #include <string>
 #include <vector>
 
 #include "access-log.h"
-#include "hash-tree.h"
+#include "hash-tree-constants.h"
 #include "i-hasher.h"
 #include "i-state-access.h"
+#include "machine-hash.h"
 #include "machine-reg.h"
 #include "meta.h"
-#include "riscv-constants.h"
-#include "shadow-registers.h"
 #include "unique-c-ptr.h"
 #include "variant-hasher.h"
 
@@ -50,7 +50,7 @@ struct i_state_access_fast_addr<replay_send_cmio_state_access> {
 };
 
 /// \brief Allows replaying a machine::send_cmio_response() from an access log.
-class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_state_access> {
+class replay_send_cmio_state_access final : public i_state_access<replay_send_cmio_state_access> {
 public:
     struct context {
         /// \brief Constructor replay_send_cmio_state_access context
@@ -124,7 +124,7 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
     /// \returns Value read.
     uint64_t check_read(uint64_t paligned, const char *text) const {
         static_assert(HASH_TREE_LOG2_WORD_SIZE >= log2_size_v<uint64_t>,
-            "Merkle tree word size must be at least as large as a machine word");
+            "Hash tree word size must be at least as large as a machine word");
         if ((paligned & (sizeof(uint64_t) - 1)) != 0) {
             throw std::invalid_argument{"address not aligned to word size"};
         }
@@ -181,7 +181,7 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
     /// \param text Textual description of the access.
     void check_write(uint64_t paligned, uint64_t word, const char *text) const {
         static_assert(HASH_TREE_LOG2_WORD_SIZE >= log2_size_v<uint64_t>,
-            "Merkle tree word size must be at least as large as a machine word");
+            "Hash tree word size must be at least as large as a machine word");
         if ((paligned & (sizeof(uint64_t) - 1)) != 0) {
             throw std::invalid_argument{"paligned not aligned to word size"};
         }
@@ -327,8 +327,8 @@ class replay_send_cmio_state_access : public i_state_access<replay_send_cmio_sta
         if (write_length > data_length) {
             memset(scratch.get() + data_length, 0, write_length - data_length);
         }
-        get_merkle_tree_hash(h, std::span<const unsigned char>{scratch.get(), write_length}, HASH_TREE_WORD_SIZE,
-            computed_data_hash);
+        get_merkle_tree_hash(h, std::span<const unsigned char>{scratch.get(), static_cast<size_t>(write_length)},
+            HASH_TREE_WORD_SIZE, computed_data_hash);
         // check if logged written hash matches the computed data hash
         if (written_hash != computed_data_hash) {
             throw std::invalid_argument{"logged written hash of " + text +
diff --git a/src/replay-step-state-access-interop.cpp b/src/replay-step-state-access-interop.cpp
index 2c312bba8..7ac7d4e04 100644
--- a/src/replay-step-state-access-interop.cpp
+++ b/src/replay-step-state-access-interop.cpp
@@ -20,8 +20,10 @@
 #include <span>
 #include <type_traits>
 
-#include "hash-tree.h"
+#include "hash-tree-constants.h"
 #include "i-hasher.h"
+#include "machine-hash.h"
+#include "variant-hasher.h"
 
 using namespace cartesi;
 
diff --git a/src/replay-step-state-access-interop.h b/src/replay-step-state-access-interop.h
index 2e4f63f51..03bc01cf2 100644
--- a/src/replay-step-state-access-interop.h
+++ b/src/replay-step-state-access-interop.h
@@ -19,6 +19,7 @@
 
 #include <cstdint>
 #include <cstdlib>
+#include <stdexcept>
 
 #include "compiler-defines.h"
 #include "variant-hasher.h"
diff --git a/src/replay-step-state-access.h b/src/replay-step-state-access.h
index 60de9271c..7516b6dde 100644
--- a/src/replay-step-state-access.h
+++ b/src/replay-step-state-access.h
@@ -18,28 +18,30 @@
 #define REPLAY_STEP_STATE_ACCESS_H
 
 #include <algorithm>
-#include <cassert>
+#include <cstdint>
 #include <cstdlib>
 #include <functional>
-#include <optional>
 #include <ranges>
+#include <variant>
 
+#include "address-range-constants.h"
+#include "address-range.h"
+#include "assert-printf.h"
 #include "compiler-defines.h"
 #include "host-addr.h"
 #include "i-accept-scoped-notes.h"
 #include "i-prefer-shadow-state.h"
 #include "i-state-access.h"
+#include "machine-hash.h"
 #include "machine-reg.h"
 #include "mock-address-range.h"
+#include "pmas-constants.h"
 #include "pmas.h"
 #include "replay-step-state-access-interop.h"
 #include "riscv-constants.h"
 #include "shadow-registers.h"
 #include "shadow-tlb.h"
-#include "shadow-uarch-state.h"
 #include "strict-aliasing.h"
-#include "uarch-constants.h"
-#include "uarch-defines.h"
 #include "variant-hasher.h"
 
 namespace cartesi {
@@ -472,8 +474,7 @@ class replay_step_state_access :
         // ilength in its implementation of read_pmas_entry.
         const uint64_t istart = read_pmas_istart(index);
         const uint64_t ilength = read_pmas_ilength(index);
-        // NOLINTNEXTLINE(bugprone-narrowing-conversions)
-        const int i = static_cast<int>(index);
+        const auto i = static_cast<size_t>(index);
         const auto abrt = [](const char *err) { interop_throw_runtime_error(err); };
         if (std::holds_alternative<std::monostate>(m_context.ars[i])) {
             m_context.ars[i] = make_mock_address_range(istart, ilength, abrt);
diff --git a/src/riscv-constants.h b/src/riscv-constants.h
index 2245c7146..b540b5d19 100644
--- a/src/riscv-constants.h
+++ b/src/riscv-constants.h
@@ -22,7 +22,6 @@
 #include "address-range-constants.h"
 #include "htif-constants.h"
 #include "machine-c-version.h"
-#include "pmas-constants.h"
 
 /// \file
 /// \brief RISC-V constants
diff --git a/src/scope-exit.h b/src/scope-exit.h
index 6d2fc196c..a04ae52a4 100644
--- a/src/scope-exit.h
+++ b/src/scope-exit.h
@@ -97,6 +97,6 @@ scope_fail<F> make_scope_fail(F &&f) {
     return scope_fail<F>(std::forward<F>(f));
 }
 
-}; // namespace cartesi
+} // namespace cartesi
 
 #endif
diff --git a/src/scope-remove.h b/src/scope-remove.h
index 31e894f5b..d64dc2982 100644
--- a/src/scope-remove.h
+++ b/src/scope-remove.h
@@ -17,10 +17,8 @@
 #ifndef SCOPE_REMOVE_H
 #define SCOPE_REMOVE_H
 
-#include <exception>
 #include <ranges>
 #include <string>
-#include <utility>
 #include <vector>
 
 #include "os-filesystem.h"
@@ -87,6 +85,6 @@ class scope_remove {
     std::vector<std::string> m_dirnames;  ///< List of directories to be removed
 };
 
-}; // namespace cartesi
+} // namespace cartesi
 
 #endif
diff --git a/src/send-cmio-response.cpp b/src/send-cmio-response.cpp
index 6c129b443..c4511aae8 100644
--- a/src/send-cmio-response.cpp
+++ b/src/send-cmio-response.cpp
@@ -17,17 +17,16 @@
 /// \file
 /// \brief This file is be converted to Solidity by the machine-solidity-step.
 
-// NOLINTBEGIN(google-readability-casting,misc-const-correctness,modernize-use-auto,hicpp-use-auto,readability-use-std-min-max)
-
 #include "send-cmio-response.h"
 
+#include "address-range-constants.h"
 #include "hash-tree-constants.h"
-#include "pmas-constants.h"
-#include "record-send-cmio-state-access.h"
-#include "replay-send-cmio-state-access.h"
-#include "state-access.h"
+#include "record-send-cmio-state-access.h" // IWYU pragma: keep
+#include "replay-send-cmio-state-access.h" // IWYU pragma: keep
+#include "state-access.h"                  // IWYU pragma: keep
 #include "uarch-solidity-compat.h"
 
+// NOLINTBEGIN(google-readability-casting,misc-const-correctness,modernize-use-auto,hicpp-use-auto,readability-use-std-min-max)
 namespace cartesi {
 
 template <typename STATE_ACCESS>
diff --git a/src/sha-256-hasher.cpp b/src/sha-256-hasher.cpp
index b4a19033b..33a581d7e 100644
--- a/src/sha-256-hasher.cpp
+++ b/src/sha-256-hasher.cpp
@@ -15,16 +15,20 @@
 //
 
 #include "sha-256-hasher.h"
-#include "compiler-defines.h"
-#include "i-hasher.h"
-#include "machine-hash.h"
-#include "simd-vector-type.h"
 
+#include <algorithm>
+#include <array>
 #include <bit>
 #include <cstddef>
 #include <cstdint>
 #include <span>
 
+#include "array2d.h"
+#include "compiler-defines.h"
+#include "i-hasher.h"
+#include "machine-hash.h"
+#include "simd-vector-type.h"
+
 namespace cartesi {
 
 // This code is not portable to big-endian architectures.
diff --git a/src/sha-256-hasher.h b/src/sha-256-hasher.h
index d81e4bbf5..dd5f66bf4 100644
--- a/src/sha-256-hasher.h
+++ b/src/sha-256-hasher.h
@@ -19,12 +19,11 @@
 
 #include <array>
 #include <cstddef>
-#include <cstdint>
 #include <span>
-#include <type_traits>
 
 #include "array2d.h"
 #include "compiler-defines.h"
+#include "hash-tree-constants.h"
 #include "i-hasher.h"
 #include "machine-hash.h"
 
@@ -100,6 +99,8 @@ MULTIVERSION_AMD64_AVX512_BMI_BMI2 void sha_256_hash_2x16(const array2d<const_ma
 
 class sha_256_hasher final : public i_hasher<sha_256_hasher> {
 public:
+    sha_256_hasher() = default;
+
     static constexpr int MAX_LANE_COUNT = 16; ///< Number of maximum supported SIMD lanes
 
     template <size_t ConcatCount, size_t LaneCount, size_t Extent>
diff --git a/src/shadow-registers.h b/src/shadow-registers.h
index 807c7dcf3..6648f5545 100644
--- a/src/shadow-registers.h
+++ b/src/shadow-registers.h
@@ -20,9 +20,7 @@
 #include <cstddef>
 #include <cstdint>
 
-#include "address-range.h"
-#include "compiler-defines.h"
-#include "pmas-constants.h"
+#include "address-range-constants.h"
 #include "riscv-constants.h"
 
 /// \file
diff --git a/src/shadow-tlb.h b/src/shadow-tlb.h
index d8589d11b..dddfec1d0 100644
--- a/src/shadow-tlb.h
+++ b/src/shadow-tlb.h
@@ -25,8 +25,7 @@
 #include <cstddef>
 #include <cstdint>
 
-#include "compiler-defines.h"
-#include "pmas-constants.h"
+#include "address-range-constants.h"
 #include "riscv-constants.h"
 
 namespace cartesi {
diff --git a/src/shadow-uarch-state.h b/src/shadow-uarch-state.h
index 868100379..9275e50ee 100644
--- a/src/shadow-uarch-state.h
+++ b/src/shadow-uarch-state.h
@@ -20,7 +20,7 @@
 #include <cstddef>
 #include <cstdint>
 
-#include "compiler-defines.h"
+#include "address-range-constants.h"
 #include "riscv-constants.h"
 
 /// \file
diff --git a/src/simd-hasher.h b/src/simd-hasher.h
index 7afeb5c2a..828ffe121 100644
--- a/src/simd-hasher.h
+++ b/src/simd-hasher.h
@@ -24,11 +24,12 @@
 /// It includes specialized hashers for single data items and concatenated data pairs,
 /// both utilizing queue-based batching to maximize SIMD efficiency.
 
+#include <array>
 #include <cstddef>
 
 #include <boost/container/static_vector.hpp>
 
-#include "compiler-defines.h"
+#include "array2d.h"
 #include "i-hasher.h"
 #include "machine-hash.h"
 
diff --git a/src/simd-vector-type.h b/src/simd-vector-type.h
index d8e107f40..d9929ab23 100644
--- a/src/simd-vector-type.h
+++ b/src/simd-vector-type.h
@@ -25,7 +25,7 @@
 #define SIMD_VECTOR_TYPE
 
 #include <cstddef>
-#include <cstdint>
+#include <cstdint> // IWYU pragma: keep
 
 namespace cartesi {
 
diff --git a/src/soft-float.h b/src/soft-float.h
index 0f23ced34..f2327be6c 100644
--- a/src/soft-float.h
+++ b/src/soft-float.h
@@ -43,10 +43,10 @@
 #ifndef SOFT_FLOAT_H
 #define SOFT_FLOAT_H
 
-#include <cassert>
 #include <cstdint>
 #include <type_traits>
 
+#include "assert-printf.h"
 #include "compiler-defines.h"
 #include "riscv-constants.h"
 #include "uint128.h"
diff --git a/src/state-access.h b/src/state-access.h
index e417d7611..692d2a9ab 100644
--- a/src/state-access.h
+++ b/src/state-access.h
@@ -20,22 +20,19 @@
 /// \file
 /// \brief Fast state access implementation
 
-#include <algorithm>
-#include <cassert>
 #include <cstdint>
 #include <stdexcept>
-#include <utility>
 
+#include "address-range.h"
+#include "assert-printf.h"
 #include "compiler-defines.h"
 #include "host-addr.h"
 #include "i-accept-counters.h"
 #include "i-accept-scoped-notes.h"
 #include "i-interactive-state-access.h"
 #include "i-state-access.h"
-#include "interpret.h"
 #include "machine.h"
 #include "os.h"
-#include "pmas-constants.h"
 #include "processor-state.h"
 #include "riscv-constants.h"
 #include "shadow-tlb.h"
diff --git a/src/strict-aliasing.h b/src/strict-aliasing.h
index a35becf52..e2a80ab41 100644
--- a/src/strict-aliasing.h
+++ b/src/strict-aliasing.h
@@ -17,10 +17,6 @@
 #ifndef STRICT_ALIASING_H
 #define STRICT_ALIASING_H
 
-#include <cstdint>
-#include <cstring>
-#include <type_traits>
-
 /// \file
 /// \brief Enforcement of the strict aliasing rule
 
diff --git a/src/test-collect-hashes.lua b/src/test-collect-hashes.lua
index ac52767a4..6dadb0bd8 100755
--- a/src/test-collect-hashes.lua
+++ b/src/test-collect-hashes.lua
@@ -16,39 +16,22 @@
 -- with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 --
 local cartesi = require("cartesi")
+local tabular = require("cartesi.tabular")
 --local jsonrpc = require("cartesi.jsonrpc")
 local calldata = require("cartesi.calldata")
 local socket = require("socket")
 
 local function stderr(...) io.stderr:write((string.format(...))) end
 
+local tappend = tabular.append
 local tinsert = table.insert
 
-local function tappend(t, elems)
-    local n = #t
-    for i, v in ipairs(elems) do
-        t[n + i] = v
-    end
-end
-
 local function errorf(fmt, ...) error(string.format(fmt, ...)) end
 
 local config = {
     dtb = {
-        entrypoint = "while true; do rollup accept; done",
-        init = 'echo "\
-         .\
-        / \\\\\
-      /    \\\\\
-\\\\---/---\\\\  /----\\\\\
- \\\\       X       \\\\\
-  \\\\----/  \\\\---/---\\\\\
-       \\\\    / CARTESI\
-        \\\\ /   MACHINE\
-         \'\
-"\
-busybox mkdir -p /run/drive-label && echo "root" > /run/drive-label/pmem0\
-',
+        entrypoint = "while true; do rollup accept >> /dev/null; done",
+        init = 'busybox mkdir -p /run/drive-label && echo "root" > /run/drive-label/pmem0',
     },
     flash_drive = {
         {
@@ -127,21 +110,20 @@ local function get_root_hashes_directly(input_count)
     local hashes
     local m, break_reason = create_machine()
     local mcycle = m:read_reg("mcycle")
-    local target_mcycle
     local index = 0
-    while index < input_count and break_reason ~= halted and break_reason ~= failed do
+    while break_reason ~= halted and break_reason ~= failed do
         if break_reason == yielded_manually then
             if hashes then tinsert(inputs, hashes) end
             hashes = {}
             local input = encode_input(index)
             m:send_cmio_response(cartesi.CMIO_YIELD_REASON_ADVANCE_STATE, input)
             index = index + 1
-            target_mcycle = mcycle + MCYCLE_PERIOD
+            if index >= input_count then break end
         end
+        local target_mcycle = mcycle + MCYCLE_PERIOD
         break_reason = m:run(target_mcycle)
         mcycle = m:read_reg("mcycle")
-        if mcycle == target_mcycle then
-            target_mcycle = mcycle + MCYCLE_PERIOD
+        if mcycle == target_mcycle or break_reason == yielded_manually or break_reason == halted then
             tinsert(hashes, m:get_root_hash())
         end
     end
@@ -166,8 +148,7 @@ local function get_root_hashes_with_collect(input_count)
     local m, break_reason = create_machine()
     local mcycle_phase
     local index = 0
-    local period_count = 7
-    while index < input_count and break_reason ~= halted and break_reason ~= failed do
+    while break_reason ~= halted and break_reason ~= failed do
         if break_reason == yielded_manually then
             if hashes then tinsert(inputs, hashes) end
             hashes = {}
@@ -175,12 +156,9 @@ local function get_root_hashes_with_collect(input_count)
             local input = encode_input(index)
             m:send_cmio_response(cartesi.CMIO_YIELD_REASON_ADVANCE_STATE, input)
             index = index + 1
+            if index >= input_count then break end
         end
-        local collected = m:collect_mcycle_root_hashes(
-            m:read_reg("mcycle") + period_count * MCYCLE_PERIOD,
-            MCYCLE_PERIOD,
-            mcycle_phase
-        )
+        local collected = m:collect_mcycle_root_hashes(cartesi.MCYCLE_MAX, MCYCLE_PERIOD, mcycle_phase)
         break_reason, mcycle_phase = collected.break_reason, collected.mcycle_phase
         tappend(hashes, collected.hashes)
     end
@@ -202,7 +180,7 @@ t = socket.gettime()
 local inputs_directly = get_root_hashes_directly(INPUT_COUNT)
 local directly_time = socket.gettime() - t
 
-stderr("collect in %.2gs, direct in %.2g", collect_time, directly_time)
+stderr("collect in %.2gs, direct in %.2g\n", collect_time, directly_time)
 
 if #inputs_collected ~= #inputs_directly then
     errorf("number of inputs do not match (%u vs %u)", #inputs_collected, #inputs_directly)
diff --git a/src/translate-virtual-address.h b/src/translate-virtual-address.h
index 58a862a13..291cbe9ca 100644
--- a/src/translate-virtual-address.h
+++ b/src/translate-virtual-address.h
@@ -67,7 +67,7 @@ static inline bool write_ram_uint64(STATE_ACCESS a, uint64_t paddr, uint64_t val
     const auto faddr = a.get_faddr(paddr, pma_index);
     // log writes to memory
     a.write_memory_word(faddr, pma_index, val);
-    // mark page as dirty so we know to update the Merkle tree
+    // mark page as dirty so we know to update the hash tree
     a.mark_dirty_page(faddr, pma_index);
     return true;
 }
diff --git a/src/uarch-constants.h b/src/uarch-constants.h
index 6930cc527..a5ccc0541 100644
--- a/src/uarch-constants.h
+++ b/src/uarch-constants.h
@@ -17,11 +17,12 @@
 #ifndef UARCH_CONSTANTS_H
 #define UARCH_CONSTANTS_H
 
+#include <cstdint>
+
 #include "address-range-constants.h"
+#include "address-range-defines.h"
 #include "uarch-defines.h"
 
-#include <cstdint>
-
 namespace cartesi {
 
 /// \brief uarch state constants
@@ -29,16 +30,17 @@ enum uarch_state_constants : uint64_t {
     UARCH_STATE_START_ADDRESS =
         EXPAND_UINT64_C(UARCH_STATE_START_ADDRESS_DEF), ///< Start address of the uarch state: shadow + ram
     UARCH_STATE_LOG2_SIZE = EXPAND_UINT64_C(UARCH_STATE_LOG2_SIZE_DEF), ///< Log2 size of the uarch state: shadow + ram
+    UARCH_STATE_LENGTH = UINT64_C(1) << UARCH_STATE_LOG2_SIZE,          ///< Size of the uarch state: shadow + ram
     UARCH_STATE_CHILD_LOG2_SIZE = UARCH_STATE_LOG2_SIZE - 1, ///< Log2 size of a uarch state child: shadow or ram
     UARCH_SHADOW_START_ADDRESS =
         EXPAND_UINT64_C(AR_SHADOW_UARCH_STATE_START_DEF), ///< Start address of the shadow uarch state
-    UARCH_SHADOW_LENGTH = EXPAND_UINT64_C(AR_SHADOW_UARCH_STATE_LENGTH_DEF),    ///< Length of the shadow uarch state
-    UARCH_RAM_START_ADDRESS = EXPAND_UINT64_C(AR_UARCH_RAM_START_DEF),          ///< Start address of the uarch ram
-    UARCH_RAM_LENGTH = EXPAND_UINT64_C(AR_UARCH_RAM_LENGTH_DEF),                ///< Length of the uarch ram
-    UARCH_STATE_ALIGN_MASK = (EXPAND_UINT64_C(1) << UARCH_STATE_LOG2_SIZE) - 1, ///< Mask for uarch state alignment
-    UARCH_STATE_MASK = ~UARCH_STATE_ALIGN_MASK,                                 ///< Mask for uarch state address space
+    UARCH_SHADOW_LENGTH = EXPAND_UINT64_C(AR_SHADOW_UARCH_STATE_LENGTH_DEF), ///< Length of the shadow uarch state
+    UARCH_RAM_START_ADDRESS = EXPAND_UINT64_C(AR_UARCH_RAM_START_DEF),       ///< Start address of the uarch ram
+    UARCH_RAM_LENGTH = EXPAND_UINT64_C(AR_UARCH_RAM_LENGTH_DEF),             ///< Length of the uarch ram
+    UARCH_STATE_ALIGN_MASK = (UINT64_C(1) << UARCH_STATE_LOG2_SIZE) - 1,     ///< Mask for uarch state alignment
+    UARCH_STATE_MASK = ~UARCH_STATE_ALIGN_MASK,                              ///< Mask for uarch state address space
     UARCH_STATE_CHILD_ALIGN_MASK =
-        (EXPAND_UINT64_C(1) << UARCH_STATE_CHILD_LOG2_SIZE) - 1 ///< Mask for uarch state child alignment
+        (UINT64_C(1) << UARCH_STATE_CHILD_LOG2_SIZE) - 1 ///< Mask for uarch state child alignment
 };
 
 static_assert((UARCH_STATE_START_ADDRESS & UARCH_STATE_ALIGN_MASK) == 0,
diff --git a/src/uarch-cycle-root-hashes.h b/src/uarch-cycle-root-hashes.h
index edf23f86f..d6619eb1e 100644
--- a/src/uarch-cycle-root-hashes.h
+++ b/src/uarch-cycle-root-hashes.h
@@ -18,6 +18,7 @@
 #define UARCH_CYCLE_ROOT_HASHES_H
 
 #include <cstdint>
+#include <vector>
 
 #include "interpret.h"
 #include "machine-hash.h"
diff --git a/src/uarch-interpret.cpp b/src/uarch-interpret.cpp
index 3ccf7dcba..b29d05e0d 100644
--- a/src/uarch-interpret.cpp
+++ b/src/uarch-interpret.cpp
@@ -18,8 +18,8 @@
 
 #include <cstdint>
 
-#include "collect-uarch-cycle-hashes-state-access.h"
-#include "uarch-state-access.h"
+#include "collect-uarch-cycle-hashes-state-access.h" // IWYU pragma: keep
+#include "uarch-state-access.h"                      // IWYU pragma: keep
 #include "uarch-step.h"
 
 namespace cartesi {
diff --git a/src/uarch-processor-state.h b/src/uarch-processor-state.h
index b1bfc601e..6464ea190 100644
--- a/src/uarch-processor-state.h
+++ b/src/uarch-processor-state.h
@@ -20,12 +20,8 @@
 /// \file
 /// \brief Cartesi microarchitecture machine processor state structure definition.
 
-#include <array>
 #include <cstdint>
-#include <memory>
 
-#include "memory-address-range.h"
-#include "riscv-constants.h"
 #include "shadow-uarch-state.h"
 
 namespace cartesi {
diff --git a/src/uarch-record-state-access.h b/src/uarch-record-state-access.h
index ec79c2067..e13ac4f1c 100644
--- a/src/uarch-record-state-access.h
+++ b/src/uarch-record-state-access.h
@@ -19,28 +19,25 @@
 
 /// \file
 /// \brief State access implementation that record and logs all accesses
+#include <algorithm>
 #include <cstdint>
-#include <cstring>
 #include <stdexcept>
-#include <string>
 #include <utility>
 
 #include "access-log.h"
-#include "host-addr.h"
+#include "hash-tree-constants.h"
 #include "i-accept-scoped-notes.h"
-#include "i-hasher.h"
 #include "i-prefer-shadow-uarch-state.h"
 #include "i-uarch-state-access.h"
+#include "machine-hash.h"
+#include "machine-reg.h"
 #include "machine.h"
 #include "meta.h"
-#include "riscv-constants.h"
+#include "os.h"
+#include "scoped-note.h"
 #include "shadow-tlb.h"
 #include "shadow-uarch-state.h"
-#include "strict-aliasing.h"
 #include "uarch-constants.h"
-#include "uarch-pristine-state-hash.h"
-#include "uarch-pristine.h"
-#include "uarch-processor-state.h"
 
 namespace cartesi {
 
@@ -68,7 +65,7 @@ class uarch_record_state_access :
 private:
     static std::pair<uint64_t, int> adjust_access(uint64_t paddr, int log2_size) {
         static_assert(cartesi::log2_size_v<uint64_t> <= HASH_TREE_LOG2_WORD_SIZE,
-            "Merkle tree word size must not be smaller than machine word size");
+            "Hash tree word size must not be smaller than machine word size");
         if (((paddr >> log2_size) << log2_size) != paddr) {
             throw std::invalid_argument{"misaligned access"};
         }
@@ -184,7 +181,7 @@ class uarch_record_state_access :
             [this, reg, val]() {
                 m_m.write_reg(reg, val);
                 if (!m_m.update_hash_tree_page(machine_reg_address(reg))) {
-                    throw std::invalid_argument{"error updating Merkle tree"};
+                    throw std::invalid_argument{"error updating hash tree"};
                 };
             },
             machine_reg_get_name(reg));
@@ -218,7 +215,7 @@ class uarch_record_state_access :
             [this, paddr, val]() {
                 m_m.write_word(paddr, val);
                 if (!m_m.update_hash_tree_page(paddr)) {
-                    throw std::invalid_argument{"error updating Merkle tree"};
+                    throw std::invalid_argument{"error updating hash tree"};
                 };
             },
             machine::get_what_name(paddr));
@@ -233,31 +230,31 @@ class uarch_record_state_access :
                 m_m.write_shadow_tlb(set_index, slot_index, vaddr_page, vp_offset, pma_index);
                 // Entire slot is in a single page
                 if (!m_m.update_hash_tree_page(shadow_tlb_get_abs_addr(set_index, slot_index))) {
-                    throw std::invalid_argument{"error updating Merkle tree"};
+                    throw std::invalid_argument{"error updating hash tree"};
                 };
             },
             "tlb.slot");
         // Writes to TLB slots have to be atomic.
-        // We can only do atomic writes of entire Merkle tree nodes.
+        // We can only do atomic writes of entire hash tree nodes.
         // Therefore, TLB slot must have a power-of-two size, or at least be aligned to it.
         static_assert(SHADOW_TLB_SLOT_SIZE == sizeof(shadow_tlb_slot), "shadow TLB slot size is wrong");
         static_assert((UINT64_C(1) << SHADOW_TLB_SLOT_LOG2_SIZE) == SHADOW_TLB_SLOT_SIZE,
             "shadow TLB slot log2 size is wrong");
         static_assert(SHADOW_TLB_SLOT_LOG2_SIZE >= HASH_TREE_LOG2_WORD_SIZE,
-            "shadow TLB slot must fill at least an entire Merkle tree word");
+            "shadow TLB slot must fill at least an entire hash tree word");
     }
 
     void do_reset_uarch() const {
         //??D I'd like to add an static_assert or some other guard mechanism to
         // guarantee that uarch.ram and uarch.shadow are alone in the entire
-        // span of their common Merkle tree parent node
+        // span of their common hash tree parent node
         log_write_access(
             UARCH_STATE_START_ADDRESS, UARCH_STATE_LOG2_SIZE,
             [this]() {
                 m_m.reset_uarch();
                 // reset_uarch() marks all modified pages as dirty
                 if (!m_m.update_hash_tree()) {
-                    throw std::invalid_argument{"error updating Merkle tree"};
+                    throw std::invalid_argument{"error updating hash tree"};
                 }
             },
             "uarch.state");
@@ -294,11 +291,6 @@ class uarch_record_state_access :
     auto do_make_scoped_note(const char *text) const {
         return scoped_note{*this, text};
     }
-
-    // -----
-    // i_prefer_shadow_uarch_state interface implementation
-    // -----
-    friend i_prefer_shadow_uarch_state<uarch_record_state_access>;
 };
 
 } // namespace cartesi
diff --git a/src/uarch-replay-state-access.h b/src/uarch-replay-state-access.h
index 7fc66b24a..dea2e5d25 100644
--- a/src/uarch-replay-state-access.h
+++ b/src/uarch-replay-state-access.h
@@ -20,20 +20,25 @@
 /// \file
 /// \brief State access implementation that replays recorded state accesses
 
+#include <algorithm>
 #include <cstdint>
-#include <cstring>
 #include <ios>
+#include <span>
 #include <sstream>
 #include <string>
+#include <tuple>
+#include <utility>
 #include <vector>
 
 #include "access-log.h"
+#include "hash-tree-constants.h"
 #include "hash-tree.h"
 #include "i-accept-scoped-notes.h"
 #include "i-hasher.h"
 #include "i-prefer-shadow-uarch-state.h"
 #include "i-uarch-state-access.h"
 #include "keccak-256-hasher.h"
+#include "machine-hash.h"
 #include "machine-reg.h"
 #include "machine.h"
 #include "meta.h"
@@ -130,7 +135,7 @@ class uarch_replay_state_access :
 
     static std::pair<uint64_t, int> adjust_access(uint64_t paddr, int log2_size) {
         static_assert(cartesi::log2_size_v<uint64_t> <= HASH_TREE_LOG2_WORD_SIZE,
-            "Merkle tree word size must not be smaller than machine word size");
+            "Hash tree word size must not be smaller than machine word size");
         const auto log2_word_size = HASH_TREE_LOG2_WORD_SIZE;
         const auto log2_access_size = std::max(log2_size, log2_word_size);
         const auto access_paddr = (paddr >> log2_access_size) << log2_access_size;
@@ -293,13 +298,13 @@ class uarch_replay_state_access :
 
     auto get_write_tlb_slot_hash(uint64_t vaddr_page, uint64_t vp_offset, uint64_t pma_index) const {
         // Writes to TLB slots have to be atomic.
-        // We can only do atomic writes of entire Merkle tree nodes.
+        // We can only do atomic writes of entire hash tree nodes.
         // Therefore, TLB slot must have a power-of-two size, or at least be aligned to it.
         static_assert(SHADOW_TLB_SLOT_SIZE == sizeof(shadow_tlb_slot), "shadow TLB slot size is wrong");
         static_assert((UINT64_C(1) << SHADOW_TLB_SLOT_LOG2_SIZE) == SHADOW_TLB_SLOT_SIZE,
             "shadow TLB slot log2 size is wrong");
         static_assert(SHADOW_TLB_SLOT_LOG2_SIZE >= HASH_TREE_LOG2_WORD_SIZE,
-            "shadow TLB slot must fill at least an entire Merkle tree word");
+            "shadow TLB slot must fill at least an entire hash tree word");
         shadow_tlb_slot slot_data{};
         shadow_tlb_fill_slot(vaddr_page, vp_offset, pma_index, slot_data);
         // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
@@ -360,11 +365,6 @@ class uarch_replay_state_access :
         return "uarch_replay_state_access";
     }
 
-    // -----
-    // i_prefer_shadow_uarch_state interface implementation
-    // -----
-    friend i_prefer_shadow_uarch_state<uarch_replay_state_access>;
-
     // -----
     // i_accept_scoped_notes interface implementation
     // -----
diff --git a/src/uarch-reset-state.cpp b/src/uarch-reset-state.cpp
index 8c08dac16..3f02f549e 100644
--- a/src/uarch-reset-state.cpp
+++ b/src/uarch-reset-state.cpp
@@ -21,10 +21,10 @@
 
 #include "uarch-reset-state.h"
 
-#include "uarch-record-state-access.h"
-#include "uarch-replay-state-access.h"
+#include "uarch-record-state-access.h" // IWYU pragma: keep
+#include "uarch-replay-state-access.h" // IWYU pragma: keep
 #include "uarch-solidity-compat.h"
-#include "uarch-state-access.h"
+#include "uarch-state-access.h" // IWYU pragma: keep
 
 namespace cartesi {
 
diff --git a/src/uarch-solidity-compat.h b/src/uarch-solidity-compat.h
index 9e621b95f..54e3a2090 100644
--- a/src/uarch-solidity-compat.h
+++ b/src/uarch-solidity-compat.h
@@ -17,16 +17,10 @@
 #ifndef UARCH_INTERPRET_SOLIDITY_COMPAT_H
 #define UARCH_INTERPRET_SOLIDITY_COMPAT_H
 
-#include <cassert>
-#include <cmath>
 #include <cstdint>
 #include <stdexcept>
 
-#ifdef DUMP_UARCH_INSN
 #include "assert-printf.h"
-#include <cinttypes>
-#endif
-
 #include "shadow-tlb.h"
 
 /// \file
diff --git a/src/uarch-state-access.h b/src/uarch-state-access.h
index 5d60593b6..bac8b08b5 100644
--- a/src/uarch-state-access.h
+++ b/src/uarch-state-access.h
@@ -17,18 +17,14 @@
 #ifndef UARCH_STATE_ACCESS_H
 #define UARCH_STATE_ACCESS_H
 
-#include <cassert>
 #include <cstdint>
-#include <stdexcept>
 
-#include "host-addr.h"
+#include "assert-printf.h"
 #include "i-accept-scoped-notes.h"
 #include "i-uarch-state-access.h"
 #include "machine.h"
 #include "os.h"
-#include "riscv-constants.h"
-#include "strict-aliasing.h"
-#include "uarch-pristine.h"
+#include "shadow-tlb.h"
 
 namespace cartesi {
 
diff --git a/src/uarch-step.cpp b/src/uarch-step.cpp
index 28636bab1..e87030c36 100644
--- a/src/uarch-step.cpp
+++ b/src/uarch-step.cpp
@@ -21,10 +21,12 @@
 
 #include "uarch-step.h"
 
-#include "collect-uarch-cycle-hashes-state-access.h"
-#include "uarch-record-state-access.h"
-#include "uarch-replay-state-access.h"
-#include "uarch-state-access.h"
+#include <cstdint>
+
+#include "collect-uarch-cycle-hashes-state-access.h" // IWYU pragma: keep
+#include "uarch-record-state-access.h"               // IWYU pragma: keep
+#include "uarch-replay-state-access.h"               // IWYU pragma: keep
+#include "uarch-state-access.h"                      // IWYU pragma: keep
 
 #include "uarch-constants.h"
 #include "uarch-solidity-compat.h"
@@ -449,8 +451,8 @@ static inline void executeSLTI(const UarchState a, uint32 insn, uint64 pc) {
     uint8 rd = operandRd(insn);
     uint8 rs1 = operandRs1(insn);
     if (rd != 0) {
-        uint64 rs1val = readX(a, rs1);
-        if (int64(rs1val) < imm) {
+        int64 rs1val = int64(readX(a, rs1));
+        if (rs1val < imm) {
             writeX(a, rd, 1);
         } else {
             writeX(a, rd, 0);
diff --git a/src/unique-c-ptr.h b/src/unique-c-ptr.h
index 4feb149d7..e9866136a 100644
--- a/src/unique-c-ptr.h
+++ b/src/unique-c-ptr.h
@@ -26,8 +26,6 @@
 #include <tuple>
 #include <type_traits>
 
-#include "os.h"
-
 namespace cartesi {
 
 namespace detail {
diff --git a/src/variant-hasher.h b/src/variant-hasher.h
index 91a27914a..f1a0ade09 100644
--- a/src/variant-hasher.h
+++ b/src/variant-hasher.h
@@ -17,11 +17,18 @@
 #ifndef VARIANT_HASHER_H
 #define VARIANT_HASHER_H
 
+#include <algorithm>
+#include <array>
+#include <cstddef>
 #include <cstdint>
+#include <span>
+#include <stdexcept>
 #include <variant>
 
+#include "array2d.h"
 #include "i-hasher.h"
 #include "keccak-256-hasher.h"
+#include "machine-hash.h"
 #include "sha-256-hasher.h"
 
 namespace cartesi {
diff --git a/src/virtio-address-range.cpp b/src/virtio-address-range.cpp
index 1450c7ec7..95c2d523f 100644
--- a/src/virtio-address-range.cpp
+++ b/src/virtio-address-range.cpp
@@ -26,6 +26,7 @@
 #include <cstdint>
 #include <stdexcept>
 
+#include "address-range.h"
 #include "i-device-state-access.h"
 #include "interpret.h"
 #include "os.h"
@@ -511,7 +512,7 @@ void virtio_address_range::do_prepare_select(select_fd_sets * /*fds*/, uint64_t
 bool virtio_address_range::do_poll_selected(int /*select_ret*/, select_fd_sets * /*fds*/,
     i_device_state_access * /*da*/) {
     return false;
-};
+}
 
 bool virtio_address_range::poll_nowait(i_device_state_access *da) {
     uint64_t timeout_us = 0;
diff --git a/src/virtio-address-range.h b/src/virtio-address-range.h
index 22f0c736a..283ec0167 100644
--- a/src/virtio-address-range.h
+++ b/src/virtio-address-range.h
@@ -19,10 +19,13 @@
 
 #include <array>
 #include <cstdint>
-#include <cstring>
 
 #include "address-range.h"
+#include "i-device-state-access.h"
+#include "interpret.h"
 #include "os.h"
+#include "pmas-constants.h"
+#include "pmas.h"
 
 namespace cartesi {
 
diff --git a/src/virtio-console-address-range.cpp b/src/virtio-console-address-range.cpp
index cbf476ebe..9cf77ec69 100644
--- a/src/virtio-console-address-range.cpp
+++ b/src/virtio-console-address-range.cpp
@@ -22,6 +22,7 @@
 
 #include "i-device-state-access.h"
 #include "os.h"
+#include "virtio-address-range.h"
 
 namespace cartesi {
 
diff --git a/src/virtio-console-address-range.h b/src/virtio-console-address-range.h
index 109c0ad7a..5e5bbfc85 100644
--- a/src/virtio-console-address-range.h
+++ b/src/virtio-console-address-range.h
@@ -19,6 +19,8 @@
 
 #include <cstdint>
 
+#include "i-device-state-access.h"
+#include "os.h"
 #include "virtio-address-range.h"
 
 namespace cartesi {
diff --git a/src/virtio-net-address-range.cpp b/src/virtio-net-address-range.cpp
index 169e6637a..c8692baa9 100644
--- a/src/virtio-net-address-range.cpp
+++ b/src/virtio-net-address-range.cpp
@@ -15,15 +15,15 @@
 //
 
 #include "virtio-net-address-range.h"
+#include "os-features.h"
 
 #if defined(HAVE_SLIRP) || defined(HAVE_TUNTAP)
 
 #include <cstdint>
-#include <memory>
-#include <utility>
 
 #include "i-device-state-access.h"
 #include "os.h"
+#include "virtio-address-range.h"
 
 namespace cartesi {
 
diff --git a/src/virtio-net-address-range.h b/src/virtio-net-address-range.h
index 2afbd1f1a..c752c45f3 100644
--- a/src/virtio-net-address-range.h
+++ b/src/virtio-net-address-range.h
@@ -22,7 +22,6 @@
 #if defined(HAVE_SLIRP) || defined(HAVE_TUNTAP)
 
 #include <cstdint>
-#include <memory>
 
 #include "i-device-state-access.h"
 #include "os.h"
diff --git a/src/virtio-net-tuntap-address-range.cpp b/src/virtio-net-tuntap-address-range.cpp
index 63d61c867..ea7975187 100644
--- a/src/virtio-net-tuntap-address-range.cpp
+++ b/src/virtio-net-tuntap-address-range.cpp
@@ -74,6 +74,8 @@
 
 #include "i-device-state-access.h"
 #include "os.h"
+#include "virtio-address-range.h"
+#include "virtio-net-address-range.h"
 
 // Include TUN/TAP headers
 #ifdef __linux__
diff --git a/src/virtio-net-tuntap-address-range.h b/src/virtio-net-tuntap-address-range.h
index afaf814a6..a72065791 100644
--- a/src/virtio-net-tuntap-address-range.h
+++ b/src/virtio-net-tuntap-address-range.h
@@ -26,6 +26,7 @@
 
 #include "i-device-state-access.h"
 #include "os.h"
+#include "virtio-address-range.h"
 #include "virtio-net-address-range.h"
 
 namespace cartesi {
diff --git a/src/virtio-net-user-address-range.cpp b/src/virtio-net-user-address-range.cpp
index 703c4fbb7..c588a64d9 100644
--- a/src/virtio-net-user-address-range.cpp
+++ b/src/virtio-net-user-address-range.cpp
@@ -63,18 +63,22 @@
 #include <cstddef>
 #include <cstdint>
 #include <cstring>
+#include <memory>
 #include <stdexcept>
 #include <string>
 #include <system_error>
 #include <type_traits>
+#include <utility>
 
-#include <arpa/inet.h>
+#include <arpa/inet.h> // IWYU pragma: keep
 #include <slirp/libslirp.h>
 #include <sys/select.h>
 
 #include "i-device-state-access.h"
 #include "machine-config.h"
 #include "os.h"
+#include "virtio-address-range.h"
+#include "virtio-net-address-range.h"
 
 using namespace std::string_literals;
 
diff --git a/src/virtio-net-user-address-range.h b/src/virtio-net-user-address-range.h
index 84db6d9c1..f8e562340 100644
--- a/src/virtio-net-user-address-range.h
+++ b/src/virtio-net-user-address-range.h
@@ -26,7 +26,7 @@
 #include <cstdint>
 #include <list>
 #include <memory>
-#include <unordered_set>
+#include <unordered_map>
 
 #include <slirp/libslirp.h>
 #if SLIRP_CONFIG_VERSION_MAX < 3
@@ -36,6 +36,7 @@
 #include "i-device-state-access.h"
 #include "machine-config.h"
 #include "os.h"
+#include "virtio-address-range.h"
 #include "virtio-net-address-range.h"
 
 /// \brief Slirp constants
diff --git a/src/virtio-p9fs-address-range.cpp b/src/virtio-p9fs-address-range.cpp
index 56f582900..54569c1aa 100644
--- a/src/virtio-p9fs-address-range.cpp
+++ b/src/virtio-p9fs-address-range.cpp
@@ -36,7 +36,7 @@
 #ifdef HAVE_POSIX_FS
 
 // Must be included before
-#include "os-posix-compat.h"
+#include "os-posix-compat.h" // IWYU pragma: keep
 
 #ifdef __APPLE__
 #include <sys/mount.h>
diff --git a/tests/Makefile b/tests/Makefile
index 114f731fe..647b4cacc 100644
--- a/tests/Makefile
+++ b/tests/Makefile
@@ -197,10 +197,6 @@ test-uarch-rv64ui:
 test-uarch-interpreter:
 	$(MAKE) -C ../third-party/riscv-arch-test verify XLEN=64 RISCV_TARGET=cartesi RISCV_ISA=rv64i RISCV_DEVICE=I WORK=$(BUILDDIR)/uarch-riscv-arch-test RUN_ARCH_TEST='$(RUN_ARCH_TEST)'
 
-test-hash:
-	$(LD_PRELOAD_PREFIX) ./build/misc/test-merkle-tree-hash --log2-root-size=30 --log2-leaf-size=12 --input=build/misc/test-merkle-tree-hash --hash-function=keccak256
-	$(LD_PRELOAD_PREFIX) ./build/misc/test-merkle-tree-hash --log2-root-size=30 --log2-leaf-size=12 --input=build/misc/test-merkle-tree-hash --hash-function=sha256
-
 test-jsonrpc:
 	./scripts/test-jsonrpc-server.sh ../src/cartesi-jsonrpc-machine '$(LUA) ../src/cartesi-machine.lua' '$(LUA) ./lua/cartesi-machine-tests.lua' '$(LUA)'
 
@@ -216,7 +212,7 @@ test-save-and-load: | $(CARTESI_IMAGES)
 test-yield-and-save: | $(CARTESI_IMAGES)
 	./scripts/test-yield-and-save.sh '$(LUA) ../src/cartesi-machine.lua'
 
-test-misc: test-c-api test-hash test-save-and-load test-yield-and-save
+test-misc: test-c-api test-save-and-load test-yield-and-save
 
 test-generate-uarch-logs: $(BUILDDIR)/uarch-riscv-tests-json-logs
 	$(LUA) ./lua/uarch-riscv-tests.lua --output-dir=$(BUILDDIR)/uarch-riscv-tests-json-logs --create-reset-uarch-log --create-send-cmio-response-log --jobs=$(NUM_JOBS) json-step-logs
@@ -254,7 +250,7 @@ coverage-report: $(COVERAGE_OUTPUT_DIR)
 export LLVM_PROFILE_FILE=coverage-%p.profraw
 endif
 
-test: test-save-and-load test-yield-and-save test-machine test-uarch test-uarch-rv64ui test-uarch-interpreter test-lua test-jsonrpc test-c-api test-hash test-cmio test-machine-with-log-step
+test: test-save-and-load test-yield-and-save test-machine test-uarch test-uarch-rv64ui test-uarch-interpreter test-lua test-jsonrpc test-c-api test-cmio test-machine-with-log-step
 
 lint format check-format:
 	@$(MAKE) -C misc $@
diff --git a/tests/lua/cartesi/tabular.lua b/tests/lua/cartesi/tabular.lua
index 57f35048b..593f9bfbf 100644
--- a/tests/lua/cartesi/tabular.lua
+++ b/tests/lua/cartesi/tabular.lua
@@ -37,4 +37,17 @@ M.expand = function(metadata, t)
     return expanded_t
 end
 
+function M.clear(t)
+    for k in pairs(t) do
+        t[k] = nil
+    end
+end
+
+function M.append(t, elems)
+    local n = #t
+    for i = 1, #elems do
+        t[n + i] = elems[i]
+    end
+end
+
 return M
diff --git a/tests/lua/spec-collect-hashes.lua b/tests/lua/spec-collect-hashes.lua
index 7852afb6d..6dbb868ca 100644
--- a/tests/lua/spec-collect-hashes.lua
+++ b/tests/lua/spec-collect-hashes.lua
@@ -1,10 +1,11 @@
 --[[
-Test suite for computation hashes.
+Test suite for collecting root hashes.
 ]]
 
 local lester = require("cartesi.third-party.lester")
 local describe, it, expect = lester.describe, lester.it, lester.expect
 local cartesi = require("cartesi")
+local tabular = require("cartesi.tabular")
 local util = require("cartesi.tests.util")
 
 local function expect_consistent_root_hash(machine)
@@ -13,17 +14,28 @@ local function expect_consistent_root_hash(machine)
     local external_root_hash = util.calculate_emulator_hash(machine)
     expect.equal(root_hash, node_hash)
     expect.equal(external_root_hash, root_hash)
+    return root_hash
 end
 
-local function expect_mcycle_root_hashes(machine, mcycle_end, mcycle_period, mcycle_phase)
-    local break_reason
+local function expect_mcycle_root_hashes(machine, mcycle_end, mcycle_period, mcycle_phase, log2_bundle_mcycle_count)
+    -- this reference implementation does not support the following conditions
+    assert(mcycle_end >= 0 and mcycle_end <= math.maxinteger)
+    assert(machine:read_reg("iflags_H") == 0, "unsupported call")
+    assert(machine:read_reg("iflags_Y") == 0, "unsupported call")
+    local break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE
     local hashes = {}
-    local mcycle_start = machine:read_reg("mcycle") + mcycle_period - mcycle_phase
-    for mcycle_target = mcycle_start, mcycle_end, mcycle_period do
+    local mcycle_start = machine:read_reg("mcycle")
+    local mcycle_first_target = mcycle_start + mcycle_period - mcycle_phase
+    local at_fixed_point = false
+    for mcycle_target = mcycle_first_target, mcycle_end, mcycle_period do
         break_reason = machine:run(mcycle_target)
         expect_consistent_root_hash(machine)
         if machine:read_reg("mcycle") ~= mcycle_target then
             mcycle_phase = mcycle_period - (mcycle_target - machine:read_reg("mcycle"))
+            if break_reason == cartesi.BREAK_REASON_HALTED or break_reason == cartesi.BREAK_REASON_YIELDED_MANUALLY then
+                table.insert(hashes, machine:get_root_hash())
+                at_fixed_point = true
+            end
             break
         end
         mcycle_phase = 0
@@ -32,183 +44,670 @@ local function expect_mcycle_root_hashes(machine, mcycle_end, mcycle_period, mcy
             break
         end
     end
-    assert(break_reason, "expect_mcycle_root_hashes failed")
+    if break_reason == cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE then
+        -- this reference implementation does not support partial period
+        assert(machine:read_reg("mcycle") == mcycle_end, "unsupported call")
+    end
+    local back_tree
+    if log2_bundle_mcycle_count and log2_bundle_mcycle_count > 0 then
+        local bundle_mcycle_count = 1 << log2_bundle_mcycle_count
+        if at_fixed_point then
+            -- add last root hash padding until last bundle is complete
+            while #hashes % bundle_mcycle_count ~= 0 do
+                table.insert(hashes, hashes[#hashes])
+            end
+            -- add a bundle with repetitions of the last root hash
+            for _ = 1, bundle_mcycle_count do
+                table.insert(hashes, hashes[#hashes])
+            end
+        elseif #hashes % bundle_mcycle_count ~= 0 then
+            back_tree = {
+                log2_max_leaves = log2_bundle_mcycle_count,
+                leaf_count = #hashes % bundle_mcycle_count,
+                hash_function = machine:get_initial_config().hash_tree.hash_function,
+                context = {},
+            }
+        end
+        -- bundle the root hashes
+        for _ = 1, log2_bundle_mcycle_count do
+            local next_hashes = {}
+            for i = 0, #hashes // 2 - 1 do
+                table.insert(next_hashes, cartesi.keccak256(hashes[i * 2 + 1], hashes[i * 2 + 2]))
+            end
+            if #hashes % 2 == 1 then
+                table.insert(back_tree.context, hashes[#hashes])
+            end
+            hashes = next_hashes
+        end
+    end
     return {
         hashes = hashes,
         break_reason = break_reason,
         mcycle_phase = mcycle_phase,
+        back_tree = back_tree,
     }
 end
 
-local function expect_uarch_cycle_root_hashes(machine, mcycle_end)
+local function expect_next_mcycle_uarch_root_hashes(
+    machine,
+    mcycle,
+    hashes,
+    reset_indices,
+    log2_bundle_uarch_cycle_count
+)
+    for uarch_cycle = 1, math.maxinteger do
+        if machine:run_uarch(uarch_cycle) == cartesi.UARCH_BREAK_REASON_UARCH_HALTED then
+            break
+        end
+        table.insert(hashes, machine:get_root_hash())
+        if uarch_cycle % 200 == 0 then -- checking every step would be very slow in CI
+            expect_consistent_root_hash(machine)
+        end
+    end
+    expect.equal(machine:read_reg("uarch_halt_flag"), 1)
+    local halt_root_hash = expect_consistent_root_hash(machine)
+    machine:reset_uarch()
+    local reset_root_hash = expect_consistent_root_hash(machine)
+    expect.equal(machine:read_reg("uarch_cycle"), 0)
+    expect.equal(machine:read_reg("mcycle"), mcycle)
+    if log2_bundle_uarch_cycle_count and log2_bundle_uarch_cycle_count > 0 then
+        local bundle_uarch_cycle_count = 1 << log2_bundle_uarch_cycle_count
+        -- add halt root hash padding until finishing a bundle
+        while #hashes % bundle_uarch_cycle_count ~= 0 do
+            table.insert(hashes, halt_root_hash)
+        end
+        -- add repetitions of the halt root hash
+        for _ = 1, 2 * bundle_uarch_cycle_count - 1 do
+            table.insert(hashes, halt_root_hash)
+        end
+        table.insert(hashes, reset_root_hash)
+        assert(#hashes % bundle_uarch_cycle_count == 0)
+    else
+        table.insert(hashes, reset_root_hash)
+    end
+    table.insert(reset_indices, #hashes)
+end
+
+local function expect_uarch_cycle_root_hashes(machine, mcycle_end, log2_bundle_uarch_cycle_count)
+    -- this reference implementation does not support the following conditions
+    assert(mcycle_end >= 0 and mcycle_end <= math.maxinteger, "unsupported call")
+    assert(machine:read_reg("iflags_H") == 0, "unsupported call")
+    assert(machine:read_reg("iflags_Y") == 0, "unsupported call")
     local hashes = {}
     local reset_indices = {}
-    local break_reason
+    local break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE
     local mcycle_start = machine:read_reg("mcycle")
     for mcycle = mcycle_start + 1, mcycle_end do
+        expect_next_mcycle_uarch_root_hashes(machine, mcycle, hashes, reset_indices, log2_bundle_uarch_cycle_count)
         if machine:read_reg("iflags_H") ~= 0 then
             break_reason = cartesi.BREAK_REASON_HALTED
+            expect_next_mcycle_uarch_root_hashes(machine, mcycle, hashes, reset_indices, log2_bundle_uarch_cycle_count)
             break
         end
         if machine:read_reg("iflags_Y") ~= 0 then
             break_reason = cartesi.BREAK_REASON_YIELDED_MANUALLY
+            expect_next_mcycle_uarch_root_hashes(machine, mcycle, hashes, reset_indices, log2_bundle_uarch_cycle_count)
             break
         end
-        if mcycle ~= mcycle_start + 1 and machine:read_reg("iflags_X") ~= 0 then
+        if machine:read_reg("iflags_X") ~= 0 then
             break_reason = cartesi.BREAK_REASON_YIELDED_AUTOMATICALLY
             break
         end
-        expect.equal(machine:read_reg("uarch_cycle"), 0)
-        for uarch_cycle = 1, math.maxinteger do
-            if machine:run_uarch(uarch_cycle) == cartesi.UARCH_BREAK_REASON_UARCH_HALTED then
-                break
+    end
+    if log2_bundle_uarch_cycle_count and log2_bundle_uarch_cycle_count > 0 then
+        -- bundle the root hashes
+        for _ = 1, log2_bundle_uarch_cycle_count do
+            assert(#hashes % 2 == 0)
+            local next_hashes = {}
+            for i = 0, #hashes // 2 - 1 do
+                table.insert(next_hashes, cartesi.keccak256(hashes[i * 2 + 1], hashes[i * 2 + 2]))
             end
-            table.insert(hashes, machine:get_root_hash())
-            if uarch_cycle % 200 == 0 then -- checking every step would be very slow in CI
-                expect_consistent_root_hash(machine)
+            hashes = next_hashes
+            for i = 1, #reset_indices do
+                assert(reset_indices[i] % 2 == 0)
+                reset_indices[i] = reset_indices[i] // 2
             end
         end
-        expect.equal(machine:read_reg("uarch_halt_flag"), 1)
-        expect_consistent_root_hash(machine)
-        machine:reset_uarch()
-        expect_consistent_root_hash(machine)
-        expect.equal(machine:read_reg("mcycle"), mcycle)
-        table.insert(hashes, machine:get_root_hash())
-        table.insert(reset_indices, #hashes)
-        if mcycle == mcycle_end then
-            break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE
-            break
-        end
     end
-    assert(break_reason, "expect_uarch_cycle_root_hashes failed")
     return {
         hashes = hashes,
         reset_indices = reset_indices,
-        break_reason = break_reason,
+        break_reason = assert(break_reason),
     }
 end
 
+local function create_remote_machine(...)
+    local jsonrpc = require("cartesi.jsonrpc")
+    return jsonrpc.spawn_server():set_cleanup_call(jsonrpc.SHUTDOWN):create(...)
+end
+
+local function create_local_machine(...)
+    return cartesi.machine(...)
+end
+
 describe("collect hashes", function()
-    it("should fail when collecting with invalid arguments", function()
-        local machine <close> = cartesi.machine({ ram = { length = 4096 } })
-        machine:run(1)
-        expect.fail(function()
-            machine:collect_mcycle_root_hashes(32, 32, 32)
-        end, "mcycle_phase must be in")
-        expect.fail(function()
-            machine:collect_mcycle_root_hashes(32, 0)
-        end, "mcycle_period cannot be 0")
-        expect.fail(function()
-            machine:collect_mcycle_root_hashes(machine:read_reg("mcycle") - 1, 32)
-        end, "mcycle is past")
-        expect.fail(function()
-            machine:collect_uarch_cycle_root_hashes(0)
-        end, "mcycle is past")
-    end)
-
-    it("should fail when collecting from unsupported machines", function()
-        local unrep_machine <close> =
-            cartesi.machine({ ram = { length = 4096 }, processor = { registers = { iunrep = 1 } } })
-        local soft_machine <close> = cartesi.machine({ ram = { length = 4096 } }, { soft_yield = true })
-        expect.fail(function()
-            unrep_machine:collect_mcycle_root_hashes(32, 32)
-        end, "cannot collect hashes from unreproducible machines")
-        expect.fail(function()
-            unrep_machine:collect_uarch_cycle_root_hashes(32)
-        end, "cannot collect hashes from unreproducible machines")
-        expect.fail(function()
-            soft_machine:collect_mcycle_root_hashes(32, 32)
-        end, "cannot collect hashes when soft yield is enabled")
-        expect.fail(function()
-            soft_machine:collect_uarch_cycle_root_hashes(32)
-        end, "cannot collect hashes when soft yield is enabled")
-    end)
-
-    it("should succeed when collecting 0 periods", function()
-        local machine <close> = cartesi.machine({ ram = { length = 4096 } })
-        machine:run(1)
-        expect.equal(machine:collect_mcycle_root_hashes(machine:read_reg("mcycle"), 32, 1), {
-            hashes = {},
-            break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE,
-            mcycle_phase = 1,
-        })
-        expect.equal(machine:collect_uarch_cycle_root_hashes(machine:read_reg("mcycle")), {
-            hashes = {},
-            reset_indices = {},
-            break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE,
-        })
-    end)
-
-    it("should succeed when collecting from halted machines", function()
-        local machine <close> = cartesi.machine({ ram = { length = 4096 } })
-        machine:write_reg("iflags_H", 1)
-        expect.equal(machine:collect_mcycle_root_hashes(32, 32, 1), {
-            hashes = {},
-            break_reason = cartesi.BREAK_REASON_HALTED,
-            mcycle_phase = 1,
-        })
-        expect.equal(machine:read_reg("mcycle"), 0)
-        expect.equal(machine:collect_uarch_cycle_root_hashes(32), {
-            hashes = {},
-            reset_indices = {},
-            break_reason = cartesi.BREAK_REASON_HALTED,
-        })
-        expect.equal(machine:read_reg("mcycle"), 0)
-    end)
-
-    it("should succeed when collecting from yielded machines", function()
-        local machine <close> = cartesi.machine({ ram = { length = 4096 } })
-        machine:write_reg("iflags_Y", 1)
-        expect.equal(machine:collect_mcycle_root_hashes(32, 32, 1), {
-            hashes = {},
-            break_reason = cartesi.BREAK_REASON_YIELDED_MANUALLY,
-            mcycle_phase = 1,
-        })
-        expect.equal(machine:read_reg("mcycle"), 0)
-        expect.equal(machine:collect_uarch_cycle_root_hashes(32), {
-            hashes = {},
-            reset_indices = {},
-            break_reason = cartesi.BREAK_REASON_YIELDED_MANUALLY,
-        })
-        expect.equal(machine:read_reg("mcycle"), 0)
-    end)
-
-    it("should succeed when collecting mcycles during mcycle overflow", function()
-        local machine <close> = cartesi.machine({ ram = { length = 4096 } })
-        local MAX_MCYCLE <const> = -1
-        machine:write_reg("mcycle", MAX_MCYCLE - 1)
-        expect.equal(machine:collect_mcycle_root_hashes(MAX_MCYCLE, 32, machine:read_reg("mcycle") % 32), {
-            hashes = {},
-            break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE,
-            mcycle_phase = machine:read_reg("mcycle") % 32,
-        })
-        expect.equal(machine:read_reg("mcycle"), MAX_MCYCLE)
-        expect.equal(machine:collect_mcycle_root_hashes(MAX_MCYCLE, 32, machine:read_reg("mcycle") % 32), {
-            hashes = {},
-            break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE,
-            mcycle_phase = machine:read_reg("mcycle") % 32,
-        })
-        expect.equal(machine:read_reg("mcycle"), MAX_MCYCLE)
-    end)
-
-    it("should succeed when collecting uarch cycles during mcycle overflows", function()
-        local machine <close> = cartesi.machine({ ram = { length = 4096 } })
-        local MAX_MCYCLE <const> = -1
-        machine:write_reg("mcycle", MAX_MCYCLE - 1)
-        expect.equal(
-            machine:collect_uarch_cycle_root_hashes(MAX_MCYCLE).break_reason,
-            cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE
-        )
-        expect.equal(machine:read_reg("mcycle"), MAX_MCYCLE)
-        expect.equal(machine:collect_uarch_cycle_root_hashes(MAX_MCYCLE), {
-            hashes = {},
-            reset_indices = {},
-            break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE,
-        })
-        expect.equal(machine:read_reg("mcycle"), MAX_MCYCLE)
-    end)
-
-    for _, hash_function in pairs({ "sha256", "keccak256" }) do
+    for _, desc in ipairs({
+        {
+            name = "local",
+            create_machine = create_local_machine,
+        },
+        {
+            name = "remote",
+            create_machine = create_remote_machine,
+        },
+    }) do
+        local create_machine = desc.create_machine
+        describe(desc.name, function()
+            it("should fail when collecting with invalid arguments", function()
+                local machine <close> = create_machine({ ram = { length = 4096 } })
+                machine:run(1)
+                expect.fail(function()
+                    machine:collect_mcycle_root_hashes(32, 32, 32)
+                end, "mcycle_phase must be in")
+                expect.fail(function()
+                    machine:collect_mcycle_root_hashes(32, 0)
+                end, "mcycle_period cannot be 0")
+                expect.fail(function()
+                    machine:collect_mcycle_root_hashes(machine:read_reg("mcycle") - 1, 32)
+                end, "mcycle is past")
+                expect.fail(function()
+                    machine:collect_uarch_cycle_root_hashes(0)
+                end, "mcycle is past")
+            end)
+
+            it("should fail when collecting with incompatible back trees", function()
+                local machine <close> = create_machine({ ram = { length = 4096 } })
+                expect.fail(function()
+                    machine:collect_mcycle_root_hashes(32, 32, 0, 0, {
+                        log2_max_leaves = 1,
+                        leaf_count = 1,
+                        hash_function = "keccak256",
+                        context = {
+                            string.rep("\x00", 32),
+                        },
+                    })
+                end, "back tree context is incompatible")
+                expect.fail(function()
+                    machine:collect_mcycle_root_hashes(32, 32, 0, 0, {
+                        log2_max_leaves = 0,
+                        leaf_count = 0,
+                        hash_function = "sha256",
+                        context = {},
+                    })
+                end)
+            end)
+
+            it("should fail when collecting with unsupported machines", function()
+                local unrep_machine <close> =
+                    create_machine({ ram = { length = 4096 }, processor = { registers = { iunrep = 1 } } })
+                local soft_machine <close> = create_machine({ ram = { length = 4096 } }, { soft_yield = true })
+                expect.fail(function()
+                    unrep_machine:collect_mcycle_root_hashes(32, 32)
+                end, "cannot collect hashes from unreproducible machines")
+                expect.fail(function()
+                    unrep_machine:collect_uarch_cycle_root_hashes(32)
+                end, "cannot collect hashes from unreproducible machines")
+                expect.fail(function()
+                    soft_machine:collect_mcycle_root_hashes(32, 32)
+                end, "cannot collect hashes when soft yield is enabled")
+                expect.fail(function()
+                    soft_machine:collect_uarch_cycle_root_hashes(32)
+                end, "cannot collect hashes when soft yield is enabled")
+            end)
+
+            it("should collect zero root hashes", function()
+                local mcycle_start = 1
+                local mcycle_end = 1
+                local mcycle_period = 32
+                local mcycle_phase = 1
+                local machine <close> = create_machine({ ram = { length = 4096 } })
+                machine:run(mcycle_start)
+                local log2_bundle_mcycle_count = 0
+                expect.equal(
+                    machine:collect_mcycle_root_hashes(
+                        mcycle_end,
+                        mcycle_period,
+                        mcycle_phase,
+                        log2_bundle_mcycle_count
+                    ),
+                    {
+                        hashes = {},
+                        break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE,
+                        mcycle_phase = mcycle_phase,
+                    }
+                )
+                expect.equal(
+                    machine:collect_mcycle_root_hashes(
+                        mcycle_end,
+                        mcycle_period,
+                        mcycle_phase,
+                        log2_bundle_mcycle_count,
+                        {
+                            log2_max_leaves = log2_bundle_mcycle_count,
+                            leaf_count = 0,
+                            hash_function = "keccak256",
+                            context = {},
+                        }
+                    ),
+                    {
+                        hashes = {},
+                        break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE,
+                        mcycle_phase = mcycle_phase,
+                    }
+                )
+                expect.equal(machine:collect_uarch_cycle_root_hashes(mcycle_end), {
+                    hashes = {},
+                    reset_indices = {},
+                    break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE,
+                })
+            end)
+
+            it("should collect one root hash", function()
+                local mcycle_start = 1
+                local mcycle_end = 4
+                local mcycle_period = 4
+                local mcycle_phase = 1
+                local machine <close> = create_machine({ ram = { length = 4096 } })
+                machine:run(mcycle_start)
+                local collected = machine:collect_mcycle_root_hashes(mcycle_end, mcycle_period, mcycle_phase)
+                expect.equal(machine:read_reg("mcycle"), mcycle_end)
+                expect.equal(collected, {
+                    hashes = { machine:get_root_hash() },
+                    break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE,
+                    mcycle_phase = 0,
+                })
+
+                local machine_uarch <close> = create_machine({ ram = { length = 4096 } })
+                machine_uarch:run(mcycle_start)
+                local collected_uarch = machine_uarch:collect_uarch_cycle_root_hashes(mcycle_end)
+                expect.equal(machine_uarch:read_reg("mcycle"), mcycle_end)
+                expect.equal(machine_uarch:get_root_hash(), machine:get_root_hash())
+                expect.equal(#collected_uarch.reset_indices, mcycle_end - mcycle_start)
+                expect.equal(
+                    collected_uarch.hashes[collected_uarch.reset_indices[#collected_uarch.reset_indices]],
+                    machine_uarch:get_root_hash()
+                )
+                expect.equal(collected_uarch.break_reason, cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE)
+            end)
+
+            it("should collect when mcycle_end is not aligned with mcycle_period", function()
+                local mcycle_end = 7
+                local mcycle_period = 4
+                local mcycle_start = mcycle_period
+                local mcycle_phase = 1
+                local compare_machine <close> = cartesi.machine({ ram = { length = 4096 } })
+                compare_machine:run(mcycle_start)
+                local expected_root_hash_period = compare_machine:get_root_hash()
+                compare_machine:run(mcycle_end)
+                local expected_root_hash_final = compare_machine:get_root_hash()
+
+                local machine <close> = create_machine({ ram = { length = 4096 } })
+                machine:run(1)
+                local collected = machine:collect_mcycle_root_hashes(mcycle_end, mcycle_period, mcycle_phase)
+                expect.equal(machine:read_reg("mcycle"), mcycle_end)
+                expect.equal(collected, {
+                    hashes = { expected_root_hash_period },
+                    break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE,
+                    mcycle_phase = mcycle_end % mcycle_period,
+                })
+                expect.equal(machine:get_root_hash(), expected_root_hash_final)
+            end)
+
+            it("should break as halted when collecting with a halted machine", function()
+                local mcycle_start = 0
+                local mcycle_end = 32
+                local mcycle_period = 32
+                local mcycle_phase = 1
+                local machine <close> = create_machine({ ram = { length = 4096 } })
+                machine:write_reg("iflags_H", 1)
+                local expected_root_hash = machine:get_root_hash()
+
+                expect.equal(machine:collect_mcycle_root_hashes(mcycle_end, mcycle_period, mcycle_phase), {
+                    hashes = {},
+                    break_reason = cartesi.BREAK_REASON_HALTED,
+                    mcycle_phase = mcycle_phase,
+                })
+                expect.equal(machine:read_reg("mcycle"), mcycle_start)
+                expect.equal(machine:get_root_hash(), expected_root_hash)
+
+                expect.equal(machine:collect_uarch_cycle_root_hashes(mcycle_period), {
+                    hashes = {},
+                    reset_indices = {},
+                    break_reason = cartesi.BREAK_REASON_HALTED,
+                })
+                expect.equal(machine:read_reg("mcycle"), mcycle_start)
+                expect.equal(machine:get_root_hash(), expected_root_hash)
+            end)
+
+            it("should break as yielded when collecting with a yielded machine", function()
+                local mcycle_start = 0
+                local mcycle_end = 32
+                local mcycle_period = 32
+                local mcycle_phase = 1
+                local machine <close> = create_machine({ ram = { length = 4096 } })
+                machine:write_reg("iflags_Y", 1)
+                local expected_root_hash = machine:get_root_hash()
+
+                expect.equal(machine:collect_mcycle_root_hashes(mcycle_end, mcycle_period, mcycle_phase), {
+                    hashes = {},
+                    break_reason = cartesi.BREAK_REASON_YIELDED_MANUALLY,
+                    mcycle_phase = mcycle_phase,
+                })
+                expect.equal(machine:read_reg("mcycle"), mcycle_start)
+                expect.equal(machine:get_root_hash(), expected_root_hash)
+
+                expect.equal(machine:collect_uarch_cycle_root_hashes(mcycle_period), {
+                    hashes = {},
+                    reset_indices = {},
+                    break_reason = cartesi.BREAK_REASON_YIELDED_MANUALLY,
+                })
+                expect.equal(machine:read_reg("mcycle"), mcycle_start)
+                expect.equal(machine:get_root_hash(), expected_root_hash)
+            end)
+
+            it("should break as halted when collecting up to the same mcycle with a halted machine", function()
+                local mcycle_end = 0
+                local mcycle_period = 32
+                local mcycle_phase = 1
+                local machine <close> = create_machine({ ram = { length = 4096 } })
+                machine:write_reg("iflags_H", 1)
+                local expected_root_hash = machine:get_root_hash()
+
+                expect.equal(machine:collect_mcycle_root_hashes(mcycle_end, mcycle_period, mcycle_phase), {
+                    hashes = {},
+                    break_reason = cartesi.BREAK_REASON_HALTED,
+                    mcycle_phase = mcycle_phase,
+                })
+                expect.equal(machine:read_reg("mcycle"), mcycle_end)
+                expect.equal(machine:get_root_hash(), expected_root_hash)
+
+                expect.equal(machine:collect_uarch_cycle_root_hashes(mcycle_end), {
+                    hashes = {},
+                    reset_indices = {},
+                    break_reason = cartesi.BREAK_REASON_HALTED,
+                })
+                expect.equal(machine:read_reg("mcycle"), mcycle_end)
+                expect.equal(machine:get_root_hash(), expected_root_hash)
+            end)
+
+            it("should break as yielded when collecting up to the same mcycle with a yielded machine", function()
+                local mcycle_end = 0
+                local mcycle_period = 32
+                local mcycle_phase = 1
+                local machine <close> = create_machine({ ram = { length = 4096 } })
+                machine:write_reg("iflags_Y", 1)
+                local expected_root_hash = machine:get_root_hash()
+
+                expect.equal(machine:collect_mcycle_root_hashes(mcycle_end, mcycle_period, mcycle_phase), {
+                    hashes = {},
+                    break_reason = cartesi.BREAK_REASON_YIELDED_MANUALLY,
+                    mcycle_phase = mcycle_phase,
+                })
+                expect.equal(machine:read_reg("mcycle"), mcycle_end)
+                expect.equal(machine:get_root_hash(), expected_root_hash)
+
+                expect.equal(machine:collect_uarch_cycle_root_hashes(mcycle_end), {
+                    hashes = {},
+                    reset_indices = {},
+                    break_reason = cartesi.BREAK_REASON_YIELDED_MANUALLY,
+                })
+                expect.equal(machine:read_reg("mcycle"), mcycle_end)
+                expect.equal(machine:get_root_hash(), expected_root_hash)
+            end)
+
+            it("should collect mcycles during mcycle overflow", function()
+                local mcycle_period = 32
+                local machine <close> = create_machine({ ram = { length = 4096 } })
+                machine:write_reg("mcycle", cartesi.MCYCLE_MAX - 1)
+                local collected = machine:collect_mcycle_root_hashes(
+                    cartesi.MCYCLE_MAX,
+                    mcycle_period,
+                    machine:read_reg("mcycle") % 32
+                )
+                expect.equal(collected, {
+                    hashes = { machine:get_root_hash() },
+                    break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE,
+                    mcycle_phase = machine:read_reg("mcycle") % mcycle_period,
+                })
+                expect.equal(machine:read_reg("mcycle"), cartesi.MCYCLE_MAX)
+
+                expect.equal(
+                    machine:collect_mcycle_root_hashes(
+                        cartesi.MCYCLE_MAX,
+                        mcycle_period,
+                        machine:read_reg("mcycle") % 32
+                    ),
+                    {
+                        hashes = {},
+                        break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE,
+                        mcycle_phase = machine:read_reg("mcycle") % mcycle_period,
+                    }
+                )
+                expect.equal(machine:read_reg("mcycle"), cartesi.MCYCLE_MAX)
+            end)
+
+            it("should collect uarch cycles during mcycle overflows", function()
+                local machine <close> = create_machine({ ram = { length = 4096 } })
+                machine:write_reg("mcycle", cartesi.MCYCLE_MAX - 1)
+                local collected_uarch = machine:collect_uarch_cycle_root_hashes(cartesi.MCYCLE_MAX)
+                expect.equal(collected_uarch.break_reason, cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE)
+                local expected_root_hash = machine:get_root_hash()
+                expect.equal(collected_uarch.hashes[collected_uarch.reset_indices[1]], expected_root_hash)
+                expect.equal(collected_uarch.hashes[collected_uarch.reset_indices[2]], expected_root_hash)
+                expect.equal(#collected_uarch.reset_indices, 2)
+                expect.equal(machine:read_reg("mcycle"), cartesi.MCYCLE_MAX)
+
+                expect.equal(machine:collect_uarch_cycle_root_hashes(cartesi.MCYCLE_MAX), {
+                    hashes = {},
+                    reset_indices = {},
+                    break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE,
+                })
+                expect.equal(machine:read_reg("mcycle"), cartesi.MCYCLE_MAX)
+            end)
+
+            local add_machine_config = {
+                ram = {
+                    length = 4096, -- non power of 2 on purpose to exercise address range boundaries
+                    backing_store = {
+                        data_filename = util.tests_path .. "rv64ui-p-add.bin",
+                    },
+                },
+            }
+            local yield_machine_config = {
+                ram = {
+                    length = 8191 * 4096, -- non power of 2 on purpose to exercise address range boundaries
+                    backing_store = {
+                        data_filename = util.tests_path .. "htif_yield.bin",
+                    },
+                },
+            }
+
+            it("should bundle mcycle root hashes leaving no back tree context when last bundle is complete", function()
+                local max_log2_bundle_mcycle_count = 3
+                local mcycle_start = 1
+                local mcycle_period = 8
+                local mcycle_end = mcycle_period * (1 << max_log2_bundle_mcycle_count) * 2
+                local mcycle_phase = mcycle_start % mcycle_period
+                for log2_bundle_mcycle_count = 0, max_log2_bundle_mcycle_count do
+                    local machine <close> = create_machine(add_machine_config)
+                    local compare_machine <close> = cartesi.machine(add_machine_config)
+                    machine:run(mcycle_start)
+                    compare_machine:run(mcycle_start)
+                    local collected = machine:collect_mcycle_root_hashes(
+                        mcycle_end,
+                        mcycle_period,
+                        mcycle_phase,
+                        log2_bundle_mcycle_count
+                    )
+                    expect.not_exist(collected.back_tree)
+                    local expected_collected = expect_mcycle_root_hashes(
+                        compare_machine,
+                        mcycle_end,
+                        mcycle_period,
+                        mcycle_phase,
+                        log2_bundle_mcycle_count
+                    )
+                    expect.equal(collected, expected_collected)
+                    expect.equal(machine:get_root_hash(), compare_machine:get_root_hash())
+                end
+            end)
+
+            it("should bundle mcycle root hashes leaving a back tree context when last bundle is incomplete", function()
+                local max_log2_bundle_mcycle_count = 3
+                local mcycle_start = 1
+                local mcycle_period = 8
+                local mcycle_end = mcycle_period * ((1 << max_log2_bundle_mcycle_count) + 1)
+                local mcycle_phase = mcycle_start % mcycle_period
+                for log2_bundle_mcycle_count = 1, max_log2_bundle_mcycle_count do
+                    local machine <close> = create_machine(add_machine_config)
+                    local compare_machine <close> = cartesi.machine(add_machine_config)
+                    machine:run(mcycle_start)
+                    compare_machine:run(mcycle_start)
+                    local collected = machine:collect_mcycle_root_hashes(
+                        mcycle_end,
+                        mcycle_period,
+                        mcycle_phase,
+                        log2_bundle_mcycle_count
+                    )
+                    expect.exist(collected.back_tree)
+                    local expected_collected = expect_mcycle_root_hashes(
+                        compare_machine,
+                        mcycle_end,
+                        mcycle_period,
+                        mcycle_phase,
+                        log2_bundle_mcycle_count
+                    )
+                    expect.equal(collected, expected_collected)
+                    expect.equal(machine:get_root_hash(), compare_machine:get_root_hash())
+                end
+            end)
+
+            it("should bundle mcycle root hashes continuing from a previous back tree context", function()
+                local max_log2_bundle_mcycle_count = 3
+                local mcycle_start = 1
+                local mcycle_period = 8
+                local mcycle_end = 1024
+                local mcycle_phase = mcycle_start % mcycle_period
+                for log2_bundle_mcycle_count = 1, max_log2_bundle_mcycle_count do
+                    local machine <close> = create_machine(add_machine_config)
+                    local compare_machine <close> = cartesi.machine(add_machine_config)
+                    machine:run(mcycle_start)
+                    compare_machine:run(mcycle_start)
+                    local all_hashes = {}
+                    local last_collected = {
+                        mcycle_phase = mcycle_phase,
+                    }
+                    for mcycle_target = mcycle_start + 1, mcycle_end do
+                        last_collected = machine:collect_mcycle_root_hashes(
+                            mcycle_target,
+                            mcycle_period,
+                            last_collected.mcycle_phase,
+                            log2_bundle_mcycle_count,
+                            last_collected.back_tree
+                        )
+                        tabular.append(all_hashes, last_collected.hashes)
+                    end
+                    local all_collected = {
+                        mcycle_phase = last_collected.mcycle_phase,
+                        break_reason = last_collected.break_reason,
+                        hashes = all_hashes,
+                        back_tree = last_collected.back_tree,
+                    }
+                    expect.not_exist(all_collected.back_tree)
+                    local expected_collected = expect_mcycle_root_hashes(
+                        compare_machine,
+                        mcycle_end,
+                        mcycle_period,
+                        mcycle_phase,
+                        log2_bundle_mcycle_count
+                    )
+                    expect.equal(all_collected, expected_collected)
+                    expect.equal(machine:get_root_hash(), compare_machine:get_root_hash())
+                end
+            end)
+
+            it("should bundle mcycle root hashes leaving no back tree context when halting", function()
+                local max_log2_bundle_mcycle_count = 6
+                local mcycle_start = 2
+                local mcycle_period = 32
+                local mcycle_end = 1024
+                local mcycle_phase = mcycle_start % mcycle_period
+                for log2_bundle_mcycle_count = 0, max_log2_bundle_mcycle_count do
+                    local machine <close> = create_machine(add_machine_config)
+                    local compare_machine <close> = cartesi.machine(add_machine_config)
+                    machine:run(mcycle_start)
+                    compare_machine:run(mcycle_start)
+                    local collected = machine:collect_mcycle_root_hashes(
+                        mcycle_end,
+                        mcycle_period,
+                        mcycle_phase,
+                        log2_bundle_mcycle_count
+                    )
+                    expect.not_exist(collected.back_tree)
+                    local expected_collected = expect_mcycle_root_hashes(
+                        compare_machine,
+                        mcycle_end,
+                        mcycle_period,
+                        mcycle_phase,
+                        log2_bundle_mcycle_count
+                    )
+                    expect.equal(collected, expected_collected)
+                    expect.equal(machine:get_root_hash(), compare_machine:get_root_hash())
+                    expect.equal(machine:read_reg("iflags_H"), 1)
+                end
+            end)
+
+            it("should bundle mcycle root hashes leaving no back tree context when yielding", function()
+                local max_log2_bundle_mcycle_count = 6
+                local mcycle_start = 3
+                local mcycle_period = 4
+                local mcycle_end = 1024
+                local mcycle_phase = mcycle_start % mcycle_period
+                for log2_bundle_mcycle_count = 0, max_log2_bundle_mcycle_count do
+                    local machine <close> = create_machine(yield_machine_config)
+                    local compare_machine <close> = cartesi.machine(yield_machine_config)
+                    machine:run(mcycle_start)
+                    compare_machine:run(mcycle_start)
+                    local collected = machine:collect_mcycle_root_hashes(
+                        mcycle_end,
+                        mcycle_period,
+                        mcycle_phase,
+                        log2_bundle_mcycle_count
+                    )
+                    expect.not_exist(collected.back_tree)
+                    local expected_collected = expect_mcycle_root_hashes(
+                        compare_machine,
+                        mcycle_end,
+                        mcycle_period,
+                        mcycle_phase,
+                        log2_bundle_mcycle_count
+                    )
+                    expect.equal(collected, expected_collected)
+                    expect.equal(machine:get_root_hash(), compare_machine:get_root_hash())
+                    expect.equal(machine:read_reg("iflags_Y"), 1)
+                end
+            end)
+
+            it("should bundle uarch cycle root hashes", function()
+                local max_log2_uarch_cycle_mcycle_count = 9
+                local mcycle_start = 256
+                local mcycle_end = mcycle_start + 2
+                for log2_uarch_cycle_mcycle_count = 0, max_log2_uarch_cycle_mcycle_count do
+                    local machine <close> = create_machine(add_machine_config)
+                    local compare_machine <close> = cartesi.machine(add_machine_config)
+                    machine:run(mcycle_start)
+                    compare_machine:run(mcycle_start)
+                    local collected = machine:collect_uarch_cycle_root_hashes(mcycle_end, log2_uarch_cycle_mcycle_count)
+                    local expected_collected =
+                        expect_uarch_cycle_root_hashes(compare_machine, mcycle_end, log2_uarch_cycle_mcycle_count)
+                    expect.equal(collected, expected_collected)
+                    expect.equal(machine:get_root_hash(), compare_machine:get_root_hash())
+                end
+            end)
+        end) -- describe remote/local
+    end -- for remote/local create
+
+    for _, hash_function in ipairs({ "sha256", "keccak256" }) do
         describe(hash_function, function()
             local big_machine_config = {
                 ram = {
@@ -273,6 +772,10 @@ describe("collect hashes", function()
             end
 
             it("should match sparse periodic root hashes", function()
+                --[[
+                This test runs a big machine booting a full Linux kernel (without a root filesystem) until it halts.
+                It exercises various subsystems (including the TLB) to verify the code correctly mark dirty pages.
+                ]]
                 local mcycle_start = 1
                 local mcycle_period = 8 * 1024 * 1024
                 local period_count = 16
@@ -297,8 +800,12 @@ describe("collect hashes", function()
             end)
 
             it("should match sparse periodic root hashes while yielding", function()
-                -- use prime numbers on purpose to test corner cases
-                local mcycle_start = 7
+                --[[
+                This test runs a small machine that triggers both manual and automatic yields at various points.
+                It verifies that root hash collection works correctly even when yields interrupt collection at
+                mcycle periods that are not aligned, ensuring robustness across yield and period boundaries.
+                ]]
+                local mcycle_start = 7 -- use prime numbers on purpose to test corner cases
                 local mcycle_phase = 3
                 local mcycle_period = 21
                 local period_count = yield_last_mcycle // mcycle_period
@@ -311,6 +818,7 @@ describe("collect hashes", function()
                 expect.equal(machine:get_root_hash(), collect_machine:get_root_hash())
                 local count_manual_yields = 0
                 local count_automatic_yields = 0
+                local count_halts = 1
                 local halt_exit_code
                 for _ = 1, period_count * 2 do
                     local mcycle_target = machine:read_reg("mcycle") + period_count * mcycle_period
@@ -339,7 +847,7 @@ describe("collect hashes", function()
                     end
                 end
                 expect.equal(machine:read_reg("mcycle"), yield_last_mcycle)
-                expect.equal(#yield_sparse_hashes, period_count)
+                expect.equal(#yield_sparse_hashes, period_count + count_manual_yields + count_halts)
                 expect.equal(count_manual_yields, 8)
                 expect.equal(count_automatic_yields, 7)
                 expect.equal(halt_exit_code, 42)
@@ -348,6 +856,12 @@ describe("collect hashes", function()
 
             if hash_function == "keccak256" then
                 it("should match dense uarch root hashes", function()
+                    --[[
+                    This test runs a big machine booting a full Linux kernel (without a root filesystem) until it halts,
+                    using microarchitecture stepping for the final mcycles only.
+                    This verifies that collecting root hashes via uarch is correct for complete mcycles,
+                    while minimizing test runtime by limiting uarch execution to a few mcycles.
+                    ]]
                     expect.truthy(big_last_mcycle ~= nil and big_last_root_hash ~= nil)
                     local machine <close> = cartesi.machine(big_machine_config)
                     local collect_machine <close> = cartesi.machine(big_machine_config)
@@ -370,8 +884,12 @@ describe("collect hashes", function()
 
                 it("should match dense uarch root hashes while yielding", function()
                     expect.truthy(yield_last_mcycle ~= nil and yield_last_root_hash ~= nil)
-                    -- use prime numbers on purpose to test corner cases
-                    local mcycle_start = 7
+                    --[[
+                    This test verifies that collecting root hashes via microarchitecture stepping remains correct even
+                    when execution is interrupted by both manual and automatic yields at various points.
+                    It ensures that root hash collection is robust and accurate across different yield scenarios.
+                    ]]
+                    local mcycle_start = 7 -- use prime numbers on purpose to test corner cases
                     local mcycle_phase = 3
                     local mcycle_period = 21
                     local period_count = yield_last_mcycle // mcycle_period
@@ -397,9 +915,9 @@ describe("collect hashes", function()
                         expect.equal(collected, expected_collected)
                         expect.equal(collect_machine:get_root_hash(), machine:get_root_hash())
                         mcycles_to_phase0 = (machine:read_reg("mcycle") - mcycle_phase_offset) % mcycle_period
-                        if mcycles_to_phase0 == 0 then
-                            local period_index = (machine:read_reg("mcycle") - mcycle_phase_offset) // mcycle_period
-                            expect.equal(yield_sparse_hashes[period_index], machine:get_root_hash())
+                        local at_fixed_point = machine:read_reg("iflags_Y") ~= 0 or machine:read_reg("iflags_H") ~= 0
+                        if mcycles_to_phase0 == 0 or at_fixed_point then
+                            expect.equal(yield_sparse_hashes[sparse_hashes_count + 1], machine:get_root_hash())
                             sparse_hashes_count = sparse_hashes_count + 1
                         end
                         if machine:read_reg("iflags_Y") == 1 then
@@ -420,7 +938,7 @@ describe("collect hashes", function()
                     expect.equal(halt_exit_code, 42)
                     expect.equal(sparse_hashes_count, #yield_sparse_hashes)
                 end)
-            end
-        end)
-    end
-end)
+            end -- if keccak256 hash function
+        end) -- descibre hash function
+    end -- for hash function
+end) -- describe collect hashes
diff --git a/tests/misc/.gitignore b/tests/misc/.gitignore
index 18e1e8954..1eb44190d 100644
--- a/tests/misc/.gitignore
+++ b/tests/misc/.gitignore
@@ -1,3 +1,2 @@
 test-machine-c-api
-test-merkle-tree-hash
 compile_flags.txt
diff --git a/tests/misc/Makefile b/tests/misc/Makefile
index e1f0fd1ca..8e94f4325 100644
--- a/tests/misc/Makefile
+++ b/tests/misc/Makefile
@@ -82,7 +82,7 @@ UBFLAGS+=-fno-delete-null-pointer-checks
 endif
 
 # We ignore test-machine-c-api.cpp cause it takes too long.
-LINTER_SOURCES=test-merkle-tree-hash.cpp
+LINTER_SOURCES=
 LINTER_HEADERS=$(wildcard *.h)
 
 CLANG_TIDY=clang-tidy
@@ -104,16 +104,13 @@ ifeq ($(slirp),yes)
 LIBCARTESI_LIBS+=$(SLIRP_LIB)
 endif
 
-all: $(BUILDDIR)/test-merkle-tree-hash $(BUILDDIR)/test-machine-c-api
+all: $(BUILDDIR)/test-machine-c-api
 
-../../src/libcartesi.a ../../src/libcartesi_merkle_tree.a:
-	$(info libcartesi.a and/or libcartesi_merkle_tree.a were not found! Build them first.)
+../../src/libcartesi.a ../../src/libcartesi_hash_tree.a:
+	$(info libcartesi.a and/or libcartesi_hash_tree.a were not found! Build them first.)
 	@exit 1
 
-$(BUILDDIR)/test-merkle-tree-hash: test-merkle-tree-hash.o ../../src/libcartesi.a ../../src/libcartesi_merkle_tree.a
-	$(CXX) -o $@ $^ $(CXXFLAGS)
-
-$(BUILDDIR)/test-machine-c-api: test-machine-c-api.o ../../src/libcartesi.a ../../src/libcartesi_merkle_tree.a
+$(BUILDDIR)/test-machine-c-api: test-machine-c-api.o ../../src/libcartesi.a ../../src/libcartesi_hash_tree.a
 	$(CXX) -o $@ $^ $(CXXFLAGS) $(LIBCARTESI_LIBS) $(OMP_LIB)
 
 %.o: %.cpp
@@ -145,6 +142,6 @@ clean-objs:
 	@rm -f *.o *.d
 
 clean: clean-tidy clean-objs
-	@rm -f $(BUILDDIR)/test-merkle-tree-hash $(BUILDDIR)/test-machine-c-api
+	@rm -f $(BUILDDIR)/test-machine-c-api
 
 .SUFFIXES:
diff --git a/tests/misc/test-machine-c-api.cpp b/tests/misc/test-machine-c-api.cpp
index d8a58dbed..87faee01e 100644
--- a/tests/misc/test-machine-c-api.cpp
+++ b/tests/misc/test-machine-c-api.cpp
@@ -34,11 +34,9 @@
 #include <json.hpp>
 
 #include <array>
-#include <chrono>
 #include <filesystem>
 #include <fstream>
 #include <iostream>
-#include <thread>
 
 #include <machine-c-api.h>
 #include <riscv-constants.h>
@@ -439,8 +437,7 @@ BOOST_FIXTURE_TEST_CASE_NOLINT(get_proof_inconsistent_tree_test, ordinary_machin
     cm_error error_code = cm_get_proof(_machine, 0, 64, &proof);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_OK);
 
-    // merkle tree is always consistent now as it updates on access
-
+    // Hash tree is always consistent now as it updates on access
     error_code = cm_get_proof(_machine, 0, CM_TREE_LOG2_PAGE_SIZE, &proof);
     BOOST_CHECK_EQUAL(error_code, CM_ERROR_OK);
 }
diff --git a/tests/misc/test-merkle-tree-hash.cpp b/tests/misc/test-merkle-tree-hash.cpp
deleted file mode 100644
index 1f0198ccb..000000000
--- a/tests/misc/test-merkle-tree-hash.cpp
+++ /dev/null
@@ -1,313 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#include <cassert>
-#include <cstdarg>
-#include <cstdint>
-#include <cstdio>
-#include <cstdlib>
-#include <cstring>
-#include <exception>
-#include <iostream>
-#include <new>
-#include <span>
-#include <tuple>
-#include <vector>
-
-#include <back-merkle-tree.h>
-#include <complete-merkle-tree.h>
-#include <full-merkle-tree.h>
-#include <hash-tree-proof.h>
-#include <i-hasher.h>
-#include <unique-c-ptr.h>
-#include <variant-hasher.h>
-
-using namespace cartesi;
-using namespace std::string_literals;
-
-namespace {
-/// \brief Checks if string matches prefix and captures remaninder
-/// \param pre Prefix to match in str.
-/// \param str Input string
-/// \param val If string matches prefix, points to remaninder
-/// \returns True if string matches prefix, false otherwise
-bool stringval(const char *pre, const char *str, const char **val) {
-    const size_t len = strlen(pre);
-    if (strncmp(pre, str, len) == 0) {
-        *val = str + len;
-        return true;
-    }
-    return false;
-}
-
-/// \brief Checks if string matches prefix and captures int that follows
-/// \param pre Prefix to match in str.
-/// \param str Input string
-/// \param val If string matches prefix and conversion to int succeeds, points
-/// to converted int
-/// \returns True if string matches prefix and conversion succeeds,
-/// false otherwise
-bool intval(const char *pre, const char *str, int *val) {
-    const size_t len = strlen(pre);
-    if (strncmp(pre, str, len) == 0) {
-        str += len;
-        int end = 0;
-        // NOLINTNEXTLINE(cert-err34-c): %n is used toverify conversion errors
-        return sscanf(str, "%d%n", val, &end) == 1 && (str[end] == 0);
-    }
-    return false;
-}
-
-/// \brief Prints hash in hex to file
-/// \param hash Hash to be printed.
-/// \param f File to print to
-void print_hash(const machine_hash &hash, FILE *f) {
-    for (auto b : hash) {
-        std::ignore = fprintf(f, "%02x", static_cast<int>(b));
-    }
-    std::ignore = fprintf(f, "\n");
-}
-
-// NOLINTNEXTLINE
-#if 0 // Unused
-/// \brief Reads a hash in hex from file
-/// \param f File to read from
-/// \returns Hash if successful, nothing otherwise
-static std::optional<machine_hash> read_hash(FILE *f) {
-    std::array<char, variant_hasher::hash_size * 2> hex_hash{};
-    if (fread(hex_hash.data(), 1, hex_hash.size(), f) != hex_hash.size()) {
-        return {};
-    }
-    machine_hash h;
-    for (size_t i = 0; i < variant_hasher::hash_size; ++i) {
-        std::array<char, 3> hex_c = {hex_hash[2 * i], hex_hash[2 * i + 1], '\0'};
-        unsigned c = 0;
-        // NOLINTNEXTLINE(cert-err34-c): we just generated the string so we don't need to verify it
-        if (sscanf(hex_c.data(), "%x", &c) != 1) {
-            return {};
-        }
-        h[i] = c;
-    }
-    return h;
-}
-#endif
-
-/// \brief Prints formatted message to stderr
-/// \param fmt Format string
-/// \param ... Arguments, if any
-// NOLINTNEXTLINE(cert-dcl50-cpp): this vararg is safe because the compiler can check the format
-__attribute__((format(printf, 1, 2))) void error(const char *fmt, ...) {
-    va_list ap;
-    va_start(ap, fmt);
-    std::ignore = vfprintf(stderr, fmt, ap);
-    va_end(ap);
-    exit(1);
-}
-
-/// \brief Computes the hash of a word
-/// \param h Hasher object
-/// \param leaf Pointer to leaf data. Must contain 2^log2_word_size bytes
-/// \param log2_word Log<sub>2</sub> of word size
-/// \param hash Receives the leaf hash
-void get_word_hash(variant_hasher &h, const unsigned char *word, int log2_word_size, machine_hash &hash) {
-    h.hash(std::span<const unsigned char>(word, 1 << log2_word_size), hash);
-}
-
-/// \brief Computes the Merkle hash of a leaf of data
-/// \param h Hasher object
-/// \param log2_word_size Log<sub>2</sub> of word size
-/// \param leaf_data Pointer to buffer containing leaf data with
-/// at least 2^log2_leaf_size bytes
-/// \param log2_leaf_size Log<sub>2</sub> of leaf size
-/// \returns Merkle hash of leaf data
-machine_hash get_leaf_hash(variant_hasher &h, int log2_word_size, const unsigned char *leaf_data, int log2_leaf_size) {
-    assert(log2_leaf_size >= log2_word_size);
-    if (log2_leaf_size > log2_word_size) {
-        machine_hash left = get_leaf_hash(h, log2_word_size, leaf_data, log2_leaf_size - 1);
-        const machine_hash right =
-            get_leaf_hash(h, log2_word_size, leaf_data + (1 << (log2_leaf_size - 1)), log2_leaf_size - 1);
-        get_concat_hash(h, left, right, left);
-        return left;
-    }
-    machine_hash leaf;
-    get_word_hash(h, leaf_data, log2_word_size, leaf);
-    return leaf;
-}
-
-/// \brief Prints help message
-void help(const char *name) {
-    std::ignore = fprintf(stderr,
-        "Usage:\n  %s [--input=<filename>] "
-        "[--log2-word-size=<w>] [--log2-leaf-size=<p>] "
-        "[--log2-root-size=<t>]\n"
-        "[--hash-function=(keccak256|sha256)]\n",
-        name);
-    exit(0);
-}
-}; // namespace
-
-int main(int argc, char *argv[]) try {
-    const char *input_name = nullptr;
-    const char *hash_function_name = nullptr;
-    int log2_word_size = 3;
-    int log2_leaf_size = 12;
-    int log2_root_size = 30;
-    // int incremental = false;
-    // Process command line arguments
-    for (int i = 1; i < argc; ++i) {
-        if (strcmp(argv[i], "--help") == 0) {
-            help(argv[0]);
-            return 1;
-        }
-        if (stringval("--input=", argv[i], &input_name) || intval("--log2-word-size=", argv[i], &log2_word_size) ||
-            intval("--log2-leaf-size=", argv[i], &log2_leaf_size) ||
-            intval("--log2-root-size=", argv[i], &log2_root_size) ||
-            stringval("--hash-function=", argv[i], &hash_function_name)) {
-            ;
-        } else {
-            error("unrecognized option '%s'\n", argv[i]);
-            return 1;
-        }
-    }
-    if (log2_word_size < 0 || log2_word_size > 64 || log2_leaf_size < log2_word_size || log2_leaf_size >= 64 ||
-        log2_leaf_size > log2_root_size || log2_root_size >= 64) {
-        error("invalid word size (%d) / leaf size (%d) / root size (%d) combination\n", log2_word_size, log2_leaf_size,
-            log2_root_size);
-        return 1;
-    }
-    hash_function_type hash_function{hash_function_type::keccak256};
-    if (hash_function_name == "keccak256"s) {
-        hash_function = hash_function_type::keccak256;
-    } else if (hash_function_name == "sha256"s) {
-        hash_function = hash_function_type::sha256;
-    } else {
-        error("invalid hash function type '%s'\n", hash_function_name);
-        return 1;
-    }
-    // Read from stdin if no input name was given
-    auto input_file = unique_file_ptr{stdin};
-    if (input_name != nullptr) {
-        input_file = make_unique_fopen(input_name, "ro", std::nothrow_t{});
-        if (!input_file) {
-            error("unable to open input file '%s'\n", input_name);
-            return 1;
-        }
-    }
-
-    // Allocate buffer for leaf data
-    const uint64_t leaf_size = UINT64_C(1) << log2_leaf_size; // NOLINT(misc-include-cleaner)
-    auto leaf_buf = make_unique_calloc<unsigned char>(leaf_size, std::nothrow_t{});
-    if (!leaf_buf) {
-        error("unable to allocate leaf buffer\n");
-        return 1;
-    }
-
-    std::cerr << "instantiating back tree\n";
-    back_merkle_tree back_tree{log2_root_size, log2_leaf_size, log2_word_size, hash_function};
-
-    std::cerr << "instantiating complete tree\n";
-    complete_merkle_tree complete_tree{log2_root_size, log2_leaf_size, log2_word_size, hash_function};
-
-    std::vector<machine_hash> leaf_hashes;
-
-    const uint64_t max_leaves = UINT64_C(1) << (log2_root_size - log2_leaf_size); // NOLINT(misc-include-cleaner)
-    uint64_t leaf_count = 0;
-    // Loop reading leaves from file until done or error
-    // As each leaf is loaded, we check that all four implementations
-    // have a consistent root:
-    // 1) The back_merkle_tree can receive leaf hashes and incrementally
-    // obtain the tree root in log time and keeping log size state
-    // 2) The full_merkle_tree builds a tree from scratch based on
-    // all leaf hashes
-    // 3) The full_merkle_tree can also receive leaf hashes and a
-    // log-size proof for the leaf currently in the tree and update
-    // the root hash in log time keeping only constant size state.
-    // 4) The complete_merkle_tree can receive leaf hashes and maintain
-    // only the part of the tree that is not pristine
-    variant_hasher h{hash_function};
-    while (true) {
-        auto got = fread(leaf_buf.get(), 1, leaf_size, input_file.get());
-        if (got == 0) {
-            if (ferror(input_file.get()) != 0) {
-                error("error reading input\n");
-                return 1;
-            }
-            break;
-        }
-        if (leaf_count >= max_leaves) {
-            error("too many leaves for tree\n");
-            return 1;
-        }
-        // Pad leaf with zeros if file ended before next leaf boundary
-        memset(leaf_buf.get() + got, 0, leaf_size - got);
-        // Compute leaf hash
-        auto leaf_hash = get_leaf_hash(h, log2_word_size, leaf_buf.get(), log2_leaf_size);
-        // Add to array of leaf hashes
-        leaf_hashes.push_back(leaf_hash);
-        // Print leaf hash
-        print_hash(leaf_hash, stderr);
-        // Get value proof for position of new leaf from incremental tree
-        auto back_leaf_proof = back_tree.get_next_leaf_proof();
-        // Add new leaf to back tree
-        back_tree.push_back(leaf_hash);
-        // Build full tree from array of leaf hashes
-        const full_merkle_tree tree_from_scratch(log2_root_size, log2_leaf_size, log2_word_size, leaf_hashes,
-            hash_function);
-        // Compare the root hash for the back tree and the tree
-        // from scratch
-        if (back_tree.get_root_hash() != tree_from_scratch.get_root_hash()) {
-            error("mismatch in root hash for back tree and "
-                  "tree from scratch\n");
-            return 1;
-        }
-        // Update back proof with new leaf
-        back_leaf_proof.set_root_hash(back_leaf_proof.bubble_up(h, leaf_hash));
-        back_leaf_proof.set_target_hash(leaf_hash);
-        if (!back_leaf_proof.verify(h)) {
-            error("updated back leaf proof failed verification\n");
-            return 1;
-        }
-        // Compare updated proof with proof generated from full tree
-        auto from_scratch_leaf_proof = tree_from_scratch.get_proof(leaf_count << log2_leaf_size, log2_leaf_size);
-        if (back_leaf_proof != from_scratch_leaf_proof) {
-            error("mismatch in leaf proofs for back tree and "
-                  "tree from scratch\n");
-        }
-        // Add new leaf to complete tree
-        complete_tree.push_back(leaf_hash);
-        // Compare the root hash for the coimplete tree and the tree
-        // from scratch
-        if (complete_tree.get_root_hash() != tree_from_scratch.get_root_hash()) {
-            error("mismatch in root hash for complete tree and "
-                  "tree from scratch\n");
-            return 1;
-        }
-        // Compare proof generated from full tree with proof generated
-        // from complete tree
-        auto complete_leaf_proof = complete_tree.get_proof(leaf_count << log2_leaf_size, log2_leaf_size);
-        if (from_scratch_leaf_proof != complete_leaf_proof) {
-            error("mismatch in leaf proofs for full tree and "
-                  "tree from scratch\n");
-        }
-        ++leaf_count;
-    }
-    std::ignore = fprintf(stderr, "passed test\n");
-    print_hash(back_tree.get_root_hash(), stdout);
-    return 0;
-} catch (std::exception &x) {
-    std::cerr << "Caught exception: " << x.what() << '\n';
-    exit(1);
-}
diff --git a/tests/misc/test-utils.h b/tests/misc/test-utils.h
index 4d1af3d01..417ac18a9 100644
--- a/tests/misc/test-utils.h
+++ b/tests/misc/test-utils.h
@@ -26,13 +26,13 @@
 // Calculate root hash for data buffer of log2_size
 namespace detail {
 
-constexpr int WORD_LOG2_SIZE = 5;
-constexpr int MERKLE_PAGE_LOG2_SIZE = 12;
-constexpr int MERKLE_PAGE_SIZE = (UINT64_C(1) << MERKLE_PAGE_LOG2_SIZE);
+constexpr int HASH_TREE_WORD_LOG2_SIZE = 5;
+constexpr int HASH_TREE_PAGE_LOG2_SIZE = 12;
+constexpr int HASH_TREE_PAGE_SIZE = (UINT64_C(1) << HASH_TREE_PAGE_LOG2_SIZE);
 
 static cartesi::machine_hash merkle_hash(cartesi::variant_hasher &h, const std::string_view &data, int log2_size) {
     cartesi::machine_hash result;
-    if (log2_size > WORD_LOG2_SIZE) {
+    if (log2_size > HASH_TREE_WORD_LOG2_SIZE) {
         --log2_size;
         auto half_size = data.size() / 2;
         auto left = merkle_hash(h, std::string_view{data.data() + 0, half_size}, log2_size);
@@ -95,11 +95,13 @@ static cartesi::machine_hash calculate_proof_root_hash(cartesi::variant_hasher &
 
 static cartesi::machine_hash calculate_emulator_hash(cm_machine *machine) {
     const auto hash_function = get_machine_hash_function(machine);
-    cartesi::variant_hasher h(hash_function);
-    cartesi::back_merkle_tree tree(CM_TREE_LOG2_ROOT_SIZE, CM_TREE_LOG2_PAGE_SIZE, CM_TREE_LOG2_WORD_SIZE,
-        hash_function);
+    cartesi::variant_hasher h{hash_function};
+    const auto pristine_pad_hashes = cartesi::back_merkle_tree::make_pristine_pad_hashes(CM_TREE_LOG2_ROOT_SIZE,
+        CM_TREE_LOG2_PAGE_SIZE, CM_TREE_LOG2_WORD_SIZE, hash_function);
+    cartesi::back_merkle_tree tree{CM_TREE_LOG2_ROOT_SIZE, CM_TREE_LOG2_PAGE_SIZE, CM_TREE_LOG2_WORD_SIZE,
+        hash_function};
     std::string page;
-    page.resize(detail::MERKLE_PAGE_SIZE);
+    page.resize(detail::HASH_TREE_PAGE_SIZE);
     const char *ranges_jsonstr{};
     if (cm_get_address_ranges(machine, &ranges_jsonstr) != 0) {
         throw std::runtime_error{cm_get_last_error_message()};
@@ -107,17 +109,18 @@ static cartesi::machine_hash calculate_emulator_hash(cm_machine *machine) {
     const auto mrds = cartesi::from_json<cartesi::address_range_descriptions>(ranges_jsonstr, "memory_ranges");
     uint64_t last = 0;
     for (const auto &m : mrds) {
-        tree.pad_back((m.start - last) >> detail::MERKLE_PAGE_LOG2_SIZE);
+        tree.pad_back((m.start - last) >> detail::HASH_TREE_PAGE_LOG2_SIZE, pristine_pad_hashes);
         auto end = m.start + m.length;
-        for (uint64_t s = m.start; s < end; s += detail::MERKLE_PAGE_SIZE) {
+        for (uint64_t s = m.start; s < end; s += detail::HASH_TREE_PAGE_SIZE) {
             // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
             if (cm_read_memory(machine, s, reinterpret_cast<unsigned char *>(page.data()), page.size()) != 0) {
                 throw std::runtime_error{cm_get_last_error_message()};
             }
-            auto page_hash = merkle_hash(h, page, detail::MERKLE_PAGE_LOG2_SIZE);
+            auto page_hash = merkle_hash(h, page, detail::HASH_TREE_PAGE_LOG2_SIZE);
             tree.push_back(page_hash);
         }
         last = end;
     }
+    tree.pad_back(tree.get_remaining_leaf_count(), pristine_pad_hashes);
     return tree.get_root_hash();
 }
diff --git a/uarch/Makefile b/uarch/Makefile
index 74f2d6f2d..4a7e2cac1 100644
--- a/uarch/Makefile
+++ b/uarch/Makefile
@@ -77,9 +77,6 @@ EMULATOR_SOURCES=\
 COMPUTE_SOURCES=\
 	compute-uarch-pristine-hash.cpp \
 	$(EMULATOR_SRC_DIR)/back-merkle-tree.cpp \
-	$(EMULATOR_SRC_DIR)/pristine-merkle-tree.cpp \
-	$(EMULATOR_SRC_DIR)/complete-merkle-tree.cpp \
-	$(EMULATOR_SRC_DIR)/full-merkle-tree.cpp \
 	$(EMULATOR_SRC_DIR)/keccak-256-hasher.cpp \
 	$(EMULATOR_SRC_DIR)/sha-256-hasher.cpp \
 	$(EMULATOR_SRC_DIR)/is-pristine.cpp \
@@ -90,10 +87,8 @@ EMULATOR_OBJS = $(patsubst %.c,%.emulator_c.o,$(patsubst %.cpp,%.emulator_cpp.o,
 COMPUTE_OBJS = $(patsubst %.c,%.compute_c.o,$(patsubst %.cpp,%.compute_cpp.o,$(COMPUTE_SOURCES)))
 
 LINTER_SOURCES=$(strip $(wildcard uarch-*.cpp))
-LINTER_HEADERS=$(strip $(wildcard uarch-*.h))
 EMPTY:=
 SPACE:=$(EMPTY) $(EMPTY)
-CLANG_TIDY_HEADER_FILTER=$(CURDIR)/($(subst $(SPACE),|,$(LINTER_HEADERS)))
 CLANG_TIDY=clang-tidy
 CLANG_TIDY_TARGETS=$(patsubst %.cpp,%.clang-tidy,$(LINTER_SOURCES))
 CLANG_TIDY_FLAGS=--warnings-as-errors=*
@@ -156,7 +151,7 @@ uarch-ram-entry.o: uarch-ram-entry.S
 	grep -v '^#' $@.tmp > $@
 
 %.clang-tidy: %.cpp
-	$(CLANG_TIDY) --header-filter='$(CLANG_TIDY_HEADER_FILTER)' $(CLANG_TIDY_FLAGS) $< -- -target riscv64-linux-gnu $(CFLAGS) $(CXXFLAGS) $(CLANG_TIDY_WARNS) 2>/dev/null
+	$(CLANG_TIDY) $(CLANG_TIDY_FLAGS) $< -- -target riscv64-linux-gnu $(CFLAGS) $(CXXFLAGS) $(CLANG_TIDY_WARNS) 2>/dev/null
 	@touch $@
 
 lint: $(CLANG_TIDY_TARGETS)
diff --git a/uarch/compute-uarch-pristine-hash.cpp b/uarch/compute-uarch-pristine-hash.cpp
index 4cce4281e..0c825bb94 100644
--- a/uarch/compute-uarch-pristine-hash.cpp
+++ b/uarch/compute-uarch-pristine-hash.cpp
@@ -65,6 +65,8 @@ Computes the hash of the pristine uarch state.
 }
 
 int main(int argc, char *argv[]) try {
+    const auto pristine_pad_hashes = back_merkle_tree::make_pristine_pad_hashes(UARCH_STATE_LOG2_SIZE, log2_page_size,
+        log2_word_size, hash_function_type::keccak256);
     back_merkle_tree tree{UARCH_STATE_LOG2_SIZE, log2_page_size, log2_word_size, hash_function_type::keccak256};
     keccak_256_hasher hasher{};
     machine_hash hash{};
@@ -103,7 +105,7 @@ int main(int argc, char *argv[]) try {
     tree.push_back(hash);
     // Add pristine gap between shadow uarch state and uarch RAM
     if (auto gap = (AR_UARCH_RAM_START - page_size - AR_SHADOW_UARCH_STATE_START) / page_size; gap != 0) {
-        tree.pad_back(gap);
+        tree.pad_back(gap, pristine_pad_hashes);
     }
     // Add all pages of uarch ram to merkle tree
     for (uint32_t p = 0; p < uarch_pristine_ram_len; p += page_size) {
@@ -118,6 +120,7 @@ int main(int argc, char *argv[]) try {
         tree.push_back(hash);
     }
     // Get uarch state hash
+    tree.pad_back(tree.get_remaining_leaf_count(), pristine_pad_hashes);
     auto uarch_state_hash = tree.get_root_hash();
     // Print header
     std::cout << "// This file is auto-generated and should not be modified\n";
diff --git a/uarch/machine-uarch-bridge-state-access.h b/uarch/machine-uarch-bridge-state-access.h
index 199dddb5a..c823fec4b 100644
--- a/uarch/machine-uarch-bridge-state-access.h
+++ b/uarch/machine-uarch-bridge-state-access.h
@@ -19,7 +19,8 @@
 
 #include "uarch-runtime.h" // must be included first, because of assert
 
-#include <optional>
+#include <array>
+#include <variant>
 
 #include "compiler-defines.h"
 #include "i-accept-scoped-notes.h"
@@ -136,8 +137,7 @@ class machine_uarch_bridge_state_access :
         };
         const uint64_t istart = bridge_read_pma_istart(index);
         const uint64_t ilength = bridge_read_pma_ilength(index);
-        // NOLINTNEXTLINE(bugprone-narrowing-conversions)
-        int i = static_cast<int>(index);
+        const auto i = static_cast<size_t>(index);
         if (std::holds_alternative<std::monostate>(m_ars[i])) {
             m_ars[i] = make_mock_address_range(istart, ilength, throw_abort);
         }
diff --git a/uarch/uarch-ecall.c b/uarch/uarch-ecall.c
index 33dc8790c..9b85b739d 100644
--- a/uarch/uarch-ecall.c
+++ b/uarch/uarch-ecall.c
@@ -15,10 +15,8 @@
 //
 
 #include "uarch-ecall.h"
-#include "compiler-defines.h"
 #include "uarch-defines.h"
 
-#include <stddef.h>
 #include <stdint.h>
 
 void ua_halt_ECALL() {
diff --git a/uarch/uarch-run.cpp b/uarch/uarch-run.cpp
index 65aa60f42..d9f0fd583 100644
--- a/uarch/uarch-run.cpp
+++ b/uarch/uarch-run.cpp
@@ -14,18 +14,16 @@
 // with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 //
 
-#include "uarch-runtime.h" // must be included first, because of assert
+// Must be included first, because of assert
+#include "uarch-runtime.h" // IWYU pragma: keep
 
 #include "compiler-defines.h"
 #include "interpret.h"
 #include "machine-uarch-bridge-state-access.h"
 #include "mock-address-range.h"
-#include "uarch-constants.h"
 #include "uarch-ecall.h"
 
-#include <array>
 #include <cstdint>
-#include <optional>
 
 using namespace cartesi;
 
diff --git a/uarch/uarch-runtime.cpp b/uarch/uarch-runtime.cpp
index f8e0d251a..012d66b47 100644
--- a/uarch/uarch-runtime.cpp
+++ b/uarch/uarch-runtime.cpp
@@ -15,11 +15,8 @@
 //
 
 #include "uarch-runtime.h"
-#include "compiler-defines.h"
-#include "uarch-constants.h"
 
 #include <cstddef>
-#include <cstdint>
 
 // NOLINTNEXTLINE(bugprone-reserved-identifier,cert-dcl37-c,cert-dcl51-cpp)
 extern "C" void __cxa_pure_virtual() {
@@ -83,7 +80,7 @@ extern "C" void *memset(void *ptr, int value, size_t num) {
     return ptr;
 }
 
-extern "C" NO_RETURN void abort() {
+extern "C" NO_RETURN void abort() noexcept {
     // NOLINTNEXTLINE(hicpp-no-assembler)
     asm volatile("ebreak"
         : // no output
diff --git a/uarch/uarch-runtime.h b/uarch/uarch-runtime.h
index 3f83a5b6a..edc06a2f1 100644
--- a/uarch/uarch-runtime.h
+++ b/uarch/uarch-runtime.h
@@ -17,6 +17,11 @@
 #ifndef UARCH_RUNTIME_H
 #define UARCH_RUNTIME_H
 
+// This is redundant, however should fix linter errors when editing source files
+#ifndef MICROARCHITECTURE
+#define MICROARCHITECTURE
+#endif
+
 #include "compiler-defines.h"
 #include "third-party/printf/printf.h"
 
@@ -24,7 +29,7 @@
 #include <cstddef>
 
 #ifndef NDEBUG
-// NOLINTNEXTLINE(cppcoreguidelines-macro-usage)
+// NOLINTBEGIN(cppcoreguidelines-macro-usage,cppcoreguidelines-avoid-do-while,modernize-use-std-print)
 #define assert(a)                                                                                                      \
     do {                                                                                                               \
         if (!(a)) {                                                                                                    \
@@ -32,6 +37,7 @@
             abort();                                                                                                   \
         }                                                                                                              \
     } while (0)
+// NOLINTEND(cppcoreguidelines-macro-usage,cppcoreguidelines-avoid-do-while,modernize-use-std-print)
 #else
 // NOLINTNEXTLINE(cppcoreguidelines-macro-usage)
 #define assert(a)
@@ -43,16 +49,6 @@
 // NOLINTNEXTLINE(cppcoreguidelines-macro-usage)
 #define vfprintf(f, fmt, ap) vprintf(fmt, ap)
 
-extern "C" NO_RETURN void abort();
-
-namespace cartesi {
-
-void os_open_tty();
-void os_close_tty();
-bool os_poll_tty(uint64_t /*timeout_us*/);
-int os_getchar();
-void os_putchar(uint8_t ch);
-
-} // namespace cartesi
+extern "C" NO_RETURN void abort() noexcept;
 
 #endif
diff --git a/uarch/uarch-strict-aliasing.h b/uarch/uarch-strict-aliasing.h
index cbdf2e0ff..f553ac09f 100644
--- a/uarch/uarch-strict-aliasing.h
+++ b/uarch/uarch-strict-aliasing.h
@@ -20,7 +20,8 @@
 /// \file
 /// \brief Enforcement of the strict aliasing rule
 
-#include "compiler-defines.h"
+#include <cstdint>
+
 #include "strict-aliasing.h"
 
 namespace cartesi {

From a14fb34ce80880d250707b832056157a171df19a Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Thu, 25 Sep 2025 17:59:08 -0300
Subject: [PATCH 70/82] feat: add maximum uarch cycle to prevent overflow in
 collect APIs

---
 src/clua-cartesi.cpp              |   2 +
 src/json-util.cpp                 |  15 ++-
 src/jsonrpc-discover.json         |   2 +-
 src/machine-c-api.h               |   2 +
 src/machine.cpp                   | 189 +++++++++++++++---------------
 src/uarch-constants.h             |   6 +-
 src/uarch-defines.h               |   3 +
 src/uarch-interpret.cpp           |   5 +-
 src/uarch-interpret.h             |   2 +-
 src/uarch-step.cpp                |   4 +-
 tests/lua/cmio-test.lua           |   3 +-
 tests/lua/machine-bind.lua        |  20 +++-
 tests/lua/machine-test.lua        |   3 +-
 tests/lua/mcycle-overflow.lua     |   5 +-
 tests/lua/spec-collect-hashes.lua |  49 ++++----
 15 files changed, 157 insertions(+), 153 deletions(-)

diff --git a/src/clua-cartesi.cpp b/src/clua-cartesi.cpp
index 8fecf9418..7fd59bf72 100644
--- a/src/clua-cartesi.cpp
+++ b/src/clua-cartesi.cpp
@@ -213,6 +213,7 @@ CM_API int luaopen_cartesi(lua_State *L) {
     clua_setintegerfield(L, CM_VERSION_PATCH, "VERSION_PATCH", -1);
     clua_setintegerfield(L, CM_HASH_SIZE, "HASH_SIZE", -1);
     clua_setintegerfield(L, CM_MCYCLE_MAX, "MCYCLE_MAX", -1);
+    clua_setintegerfield(L, CM_UARCH_CYCLE_MAX, "UARCH_CYCLE_MAX", -1);
     clua_setintegerfield(L, CM_TREE_LOG2_WORD_SIZE, "TREE_LOG2_WORD_SIZE", -1);
     clua_setintegerfield(L, CM_TREE_LOG2_PAGE_SIZE, "TREE_LOG2_PAGE_SIZE", -1);
     clua_setintegerfield(L, CM_TREE_LOG2_ROOT_SIZE, "TREE_LOG2_ROOT_SIZE", -1);
@@ -224,6 +225,7 @@ CM_API int luaopen_cartesi(lua_State *L) {
     clua_setintegerfield(L, CM_BREAK_REASON_REACHED_TARGET_MCYCLE, "BREAK_REASON_REACHED_TARGET_MCYCLE", -1);
     clua_setintegerfield(L, CM_UARCH_BREAK_REASON_REACHED_TARGET_CYCLE, "UARCH_BREAK_REASON_REACHED_TARGET_CYCLE", -1);
     clua_setintegerfield(L, CM_UARCH_BREAK_REASON_UARCH_HALTED, "UARCH_BREAK_REASON_UARCH_HALTED", -1);
+    clua_setintegerfield(L, CM_UARCH_BREAK_REASON_CYCLE_OVERFLOW, "UARCH_BREAK_REASON_CYCLE_OVERFLOW", -1);
     clua_setintegerfield(L, CM_ACCESS_LOG_TYPE_ANNOTATIONS, "ACCESS_LOG_TYPE_ANNOTATIONS", -1);
     clua_setintegerfield(L, CM_ACCESS_LOG_TYPE_LARGE_DATA, "ACCESS_LOG_TYPE_LARGE_DATA", -1);
     clua_setintegerfield(L, CM_CMIO_YIELD_COMMAND_AUTOMATIC, "CMIO_YIELD_COMMAND_AUTOMATIC", -1);
diff --git a/src/json-util.cpp b/src/json-util.cpp
index 3d6bb6234..5be2bbd31 100644
--- a/src/json-util.cpp
+++ b/src/json-util.cpp
@@ -570,6 +570,8 @@ static std::string uarch_interpreter_break_reason_to_name(uarch_interpreter_brea
             return "uarch_halted";
         case R::reached_target_cycle:
             return "reached_target_cycle";
+        case R::cycle_overflow:
+            return "cycle_overflow";
     }
     throw std::domain_error{"invalid uarch interpreter break reason"};
 }
@@ -607,13 +609,14 @@ static interpreter_break_reason interpreter_break_reason_from_name(const std::st
 
 static uarch_interpreter_break_reason uarch_interpreter_break_reason_from_name(const std::string &name) {
     using uibr = uarch_interpreter_break_reason;
-    if (name == "reached_target_cycle") {
-        return uibr::reached_target_cycle;
+    const static std::unordered_map<std::string, uibr> g_uibr_name = {
+        {"reached_target_cycle", uibr::reached_target_cycle}, {"uarch_halted", uibr::uarch_halted},
+        {"cycle_overflow", uibr::cycle_overflow}};
+    auto got = g_uibr_name.find(name);
+    if (got == g_uibr_name.end()) {
+        throw std::domain_error{"invalid uarch interpreter break reason"};
     }
-    if (name == "uarch_halted") {
-        return uibr::uarch_halted;
-    }
-    throw std::domain_error{"invalid uarch interpreter break reason"};
+    return got->second;
 }
 
 static hash_function_type hash_function_from_name(const std::string &name) {
diff --git a/src/jsonrpc-discover.json b/src/jsonrpc-discover.json
index 8220f8939..5b0aa0b88 100644
--- a/src/jsonrpc-discover.json
+++ b/src/jsonrpc-discover.json
@@ -1975,7 +1975,7 @@
       },
       "UarchInterpreterBreakReason": {
         "title": "UarchInterpreterBreakReason",
-        "enum": ["reached_target_cycle", "uarch_halted"]
+        "enum": ["reached_target_cycle", "uarch_halted", "cycle_overflow"]
       },
       "Base64String": {
         "title": "Base64String",
diff --git a/src/machine-c-api.h b/src/machine-c-api.h
index 4d45c0d35..ee181b671 100644
--- a/src/machine-c-api.h
+++ b/src/machine-c-api.h
@@ -37,6 +37,7 @@ extern "C" {
 #endif
 
 #define CM_MCYCLE_MAX UINT64_MAX
+#define CM_UARCH_CYCLE_MAX UINT64_C(1048576)
 
 // -----------------------------------------------------------------------------
 // API enums and structures
@@ -101,6 +102,7 @@ typedef enum cm_break_reason {
 typedef enum cm_uarch_break_reason {
     CM_UARCH_BREAK_REASON_REACHED_TARGET_CYCLE,
     CM_UARCH_BREAK_REASON_UARCH_HALTED,
+    CM_UARCH_BREAK_REASON_CYCLE_OVERFLOW,
     CM_UARCH_BREAK_REASON_FAILED,
 } cm_uarch_break_reason;
 
diff --git a/src/machine.cpp b/src/machine.cpp
index db6168a9f..80c1176c9 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -81,7 +81,6 @@
 #include "uarch-constants.h"
 #include "uarch-cycle-root-hashes.h"
 #include "uarch-interpret.h"
-#include "uarch-pristine-state-hash.h"
 #include "uarch-pristine.h"
 #include "uarch-record-state-access.h"
 #include "uarch-replay-state-access.h"
@@ -1851,12 +1850,8 @@ uarch_interpreter_break_reason machine::run_uarch(uint64_t uarch_cycle_end) {
 }
 
 interpreter_break_reason machine::log_step(uint64_t mcycle_count, const std::string &filename) {
-    if (m_c.hash_tree.hash_function == hash_function_type::keccak256) {
-        // Ensure that the microarchitecture is reset
-        auto current_uarch_state_hash = get_node_hash(AR_SHADOW_UARCH_STATE_START, UARCH_STATE_LOG2_SIZE);
-        if (current_uarch_state_hash != get_uarch_pristine_state_hash()) {
-            throw std::runtime_error{"microarchitecture is not reset"};
-        }
+    if (read_reg(reg::uarch_cycle) != 0) {
+        throw std::runtime_error{"microarchitecture is not reset"};
     }
     auto root_hash_before = get_root_hash();
     record_step_state_access::context context(filename, m_c.hash_tree.hash_function);
@@ -1988,14 +1983,12 @@ mcycle_root_hashes machine::collect_mcycle_root_hashes(uint64_t mcycle_end, uint
     if (!update_hash_tree()) {
         throw std::runtime_error{"update hash tree failed"};
     }
-    if (m_c.hash_tree.hash_function == hash_function_type::keccak256) {
-        if (get_node_hash(AR_SHADOW_UARCH_STATE_START, UARCH_STATE_LOG2_SIZE, skip_hash_tree_update) !=
-            get_uarch_pristine_state_hash()) {
-            throw std::runtime_error{"microarchitecture is not reset"};
-        }
+    if (read_reg(reg::uarch_cycle) != 0) {
+        throw std::runtime_error{"microarchitecture is not reset"};
     }
 
-    // Reset fields in the result that are meant for output only
+    // If the collection loop does not advance mcycle, keep the original mcycle_phase
+    // and set the break reason to indicate the target mcycle was reached
     mcycle_root_hashes result;
     result.mcycle_phase = mcycle_phase;
     result.break_reason = interpreter_break_reason::reached_target_mcycle;
@@ -2018,20 +2011,26 @@ mcycle_root_hashes machine::collect_mcycle_root_hashes(uint64_t mcycle_end, uint
     }
     auto &back_tree = result.back_tree.value();
 
-    // Reserve space before entering the loop to minimize allocations
-    result.hashes.reserve(mcycle_period);
     collect_mcycle_hashes_state_access::context context{};
-    context.dirty_pages.reserve(std::clamp<uint64_t>(mcycle_period * 4, 16, 4096));
     const collect_mcycle_hashes_state_access a(context, *this);
     os_silence_putchar(m_r.htif.no_console_putchar);
 
+    // Reserve space before entering the loop to minimize dynamic memory allocations,
+    // the reserved sizes below are based on empirical benchmarks to balance performance and memory usage,
+    // and are clamped to avoid over-allocation
+    const uint64_t max_result_hashes =
+        ((mcycle_end - mcycle_start) / (mcycle_period * (UINT64_C(1) << log2_bundle_mcycle_count))) + 1;
+    result.hashes.reserve(std::clamp<uint64_t>(max_result_hashes, 1, 16384));
+    context.dirty_pages.reserve(std::clamp<uint64_t>(mcycle_period * 4, 16, 4096));
+
     // The first iteration will target the next mcycle_period boundary,
     // but will not exceed mcycle_end if that limit is reached first
     uint64_t mcycle_target = saturating_add(mcycle_start, mcycle_period - mcycle_phase, mcycle_end);
+    uint64_t mcycle_reached = read_reg(reg::mcycle);
     bool at_fixed_point = false;
 
     // Run until reaching next mcycle target
-    while (read_reg(reg::mcycle) < mcycle_target) {
+    while (mcycle_reached < mcycle_target) {
         assert(!at_fixed_point);
 
         // Attempt to execute until finishing this period
@@ -2049,21 +2048,20 @@ mcycle_root_hashes machine::collect_mcycle_root_hashes(uint64_t mcycle_end, uint
             throw std::runtime_error{"update hash tree failed"};
         }
 
+        mcycle_reached = read_reg(reg::mcycle);
+
         // Check if we reached a fixed point
-        const auto mcycle_reached = read_reg(reg::mcycle);
-        // ??(edubart): maybe we should create a machine method or pseudo register to check if we are at fixed point?
         at_fixed_point = result.break_reason == interpreter_break_reason::halted ||
             result.break_reason == interpreter_break_reason::yielded_manually || mcycle_reached == UINT64_MAX;
 
         // Compute the new phase
-        result.mcycle_phase = saturating_add(mcycle_reached - mcycle_start, mcycle_phase) % mcycle_period;
+        result.mcycle_phase = (((mcycle_reached - mcycle_start) % mcycle_period) + mcycle_phase) % mcycle_period;
 
         // Add the current root hash to the back tree whenever we reach a period boundary or a fixed point
         // This ensures we only append at the correct intervals, even when mcycle_end does not align with the period
         if (result.mcycle_phase == 0 || at_fixed_point) {
-            const auto root_hash = m_ht.get_root_hash();
             // Append root hash relative to this period to the result
-            back_tree.push_back(root_hash);
+            back_tree.push_back(m_ht.get_root_hash());
 
             // When back tree is full, we can append the bundled root hash and reset it
             if (back_tree.full()) {
@@ -2129,61 +2127,59 @@ uarch_cycle_root_hashes machine::collect_uarch_cycle_root_hashes(uint64_t mcycle
     if (!update_hash_tree()) {
         throw std::runtime_error{"update hash tree failed"};
     }
-    if (get_node_hash(AR_SHADOW_UARCH_STATE_START, UARCH_STATE_LOG2_SIZE, skip_hash_tree_update) !=
-        get_uarch_pristine_state_hash()) {
+    if (read_reg(reg::uarch_cycle) != 0) {
         throw std::runtime_error{"microarchitecture is not reset"};
     }
 
-    // Reset fields in the result that are meant for output only
+    // If the collection loop does not advance mcycle, set the break reason to indicate the target mcycle was reached
     uarch_cycle_root_hashes result;
     result.break_reason = interpreter_break_reason::reached_target_mcycle;
 
-    // Check halted and yielded break reasons, to behave with same priority as the interpreter
-    if (read_reg(reg::iflags_H) != 0) {
-        result.break_reason = interpreter_break_reason::halted;
-        return result;
-    }
-    if (read_reg(reg::iflags_Y) != 0) {
-        result.break_reason = interpreter_break_reason::yielded_manually;
-        return result;
-    }
-
     // Initialize back tree
     back_merkle_tree back_tree(log2_bundle_uarch_cycle_count, m_c.hash_tree.hash_function);
 
-    // Reserve space before entering the loop to minimize allocations
-    const uint64_t mcycle_count = mcycle_end - mcycle_start;
     hash_tree::dirty_words_type reset_dirty_words;
-    reset_dirty_words.reserve(64);
-    result.hashes.reserve(mcycle_count * 512);
-    result.reset_indices.reserve(mcycle_count);
     collect_uarch_cycle_hashes_state_access::context context{};
-    context.dirty_words.reserve(8);
     const collect_uarch_cycle_hashes_state_access a(context, *this);
     os_silence_putchar(m_r.htif.no_console_putchar);
 
+    // Reserve space before entering the loop to minimize dynamic memory allocations,
+    // the reserved sizes below are based on empirical benchmarks to balance performance and memory usage
+    const uint64_t mcycle_count = mcycle_end - mcycle_start;
+    result.hashes.reserve(mcycle_count * 512);
+    result.reset_indices.reserve(mcycle_count);
+    context.dirty_words.reserve(8);
+    reset_dirty_words.reserve(64);
+
     // The first iteration will target the next mcycle,
     // but will not exceed mcycle_end if that limit is reached first
     uint64_t mcycle_target = saturating_add(mcycle_start, UINT64_C(1), mcycle_end);
-    bool at_fixed_point = false;
+    uint64_t mcycle_reached = read_reg(reg::mcycle);
+
+    // In case we start at fixed point, we will attempt to execute one extra mcycle which
+    bool at_fixed_point = read_reg(reg::iflags_H) != 0 || read_reg(reg::iflags_Y) != 0 || mcycle_start == UINT64_MAX;
+    if (at_fixed_point) {
+        mcycle_target = mcycle_reached;
+    }
 
     // Run until reaching next mcycle target, or one more time when at a fixed point
-    while (read_reg(reg::mcycle) < mcycle_target || at_fixed_point) {
+    while (mcycle_reached < mcycle_target || at_fixed_point) {
+        uint64_t uarch_cycle_reached = read_reg(reg::uarch_cycle);
         assert(back_tree.empty());
-        assert(read_reg(reg::uarch_cycle) == 0);
+        assert(uarch_cycle_reached == 0);
 
         // Add one hash after each uarch cycle
-        for (uint64_t uarch_cycle_target = 1;                // First uarch cycle target  should always be 1
-            read_reg(reg::uarch_cycle) < uarch_cycle_target; // Run until reaching uarch cycle target
-            uarch_cycle_target = saturating_add(uarch_cycle_target, UINT64_C(1))) {
+        for (uint64_t uarch_cycle_target = 1;         // First uarch cycle target  should always be 1
+            uarch_cycle_reached < uarch_cycle_target; // Run until reaching uarch cycle target
+            ++uarch_cycle_target) {
             // Attempt to advance to the next uarch cycle
-            uarch_interpret(a, uarch_cycle_target);
+            const auto uarch_break_reason = uarch_interpret(a, uarch_cycle_target);
+            uarch_cycle_reached = read_reg(reg::uarch_cycle);
 
             // Update hash tree and retrieve root hash
             if (!m_ht.update_words(m_ars, context.dirty_words)) {
                 throw std::runtime_error{"update hash tree failed"};
             }
-            const auto root_hash = m_ht.get_root_hash();
 
             // Track dirty uarch words to be reset later
             for (auto word_paddr : context.dirty_words) {
@@ -2194,13 +2190,21 @@ uarch_cycle_root_hashes machine::collect_uarch_cycle_root_hashes(uint64_t mcycle
             }
             context.dirty_words.clear();
 
-            // Stop if we cannot advance more uarch cycles
-            if (read_reg(reg::uarch_cycle) != uarch_cycle_target) {
+            // If the uarch cycle counter overflows, this is catastrophic and machine execution cannot continue
+            if (uarch_break_reason == uarch_interpreter_break_reason::cycle_overflow) {
+                throw std::runtime_error{"uarch reached its maximum cycle and cannot advance more uarch cycles"};
+            }
+            // If the uarch is halted, we can break the loop
+            if (uarch_break_reason == uarch_interpreter_break_reason::uarch_halted) {
                 break;
             }
 
+            // Sanity check to ensure the loop is working correctly, this should always be true
+            assert(uarch_cycle_reached == uarch_cycle_target);
+            assert(uarch_break_reason == uarch_interpreter_break_reason::reached_target_cycle);
+
             // Append root hash to the result
-            back_tree.push_back(root_hash);
+            back_tree.push_back(m_ht.get_root_hash());
 
             // When back tree is full, we can append the bundled root hash and reset it
             if (back_tree.full()) {
@@ -2209,10 +2213,9 @@ uarch_cycle_root_hashes machine::collect_uarch_cycle_root_hashes(uint64_t mcycle
             }
         }
 
-        // Ensure we uarch is really halted
-        if (read_reg(reg::uarch_halt_flag) == 0) {
-            throw std::runtime_error{"uarch is not halted after mcycle advance"};
-        }
+        // Sanity check to ensure the loop is working correctly, this should always be true
+        assert(read_reg(reg::uarch_halt_flag) != 0);
+
         const auto halt_root_hash = m_ht.get_root_hash();
 
         // Perform reset uarch directly (as an optimization), we need to only revert dirty words in its state
@@ -2222,21 +2225,19 @@ uarch_cycle_root_hashes machine::collect_uarch_cycle_root_hashes(uint64_t mcycle
         auto &uram = find_address_range(AR_UARCH_RAM_START, AR_UARCH_RAM_LENGTH);
         for (auto word_paddr : reset_dirty_words) {
             if (word_paddr >= AR_UARCH_RAM_START && word_paddr - AR_UARCH_RAM_START < AR_UARCH_RAM_LENGTH) {
-                const uint64_t uram_start_offset = word_paddr - AR_UARCH_RAM_START;
-                const uint64_t uram_end_offset =
-                    std::min<uint64_t>(uram_start_offset + HASH_TREE_WORD_SIZE, AR_UARCH_RAM_LENGTH);
-                const uint64_t size = uram_end_offset - uram_start_offset;
-                // Handle the portion that needs to be copied from uarch_pristine_ram
-                const uint64_t copy_size = (uram_start_offset < uarch_pristine_ram_len) ?
-                    std::min<uint64_t>(size, uarch_pristine_ram_len - uram_start_offset) :
-                    0;
-                if (copy_size > 0) {
-                    std::memcpy(uram.get_host_memory() + uram_start_offset, uarch_pristine_ram + uram_start_offset,
-                        copy_size);
-                }
-                // Handle the portion that needs to be zeroed
-                if (copy_size < size) {
-                    std::memset(uram.get_host_memory() + uram_start_offset + copy_size, 0, size - copy_size);
+                const uint64_t word_start_offset = word_paddr - AR_UARCH_RAM_START;
+                // Word is aligned and inside range, there can be no overflow
+                const uint64_t word_end_offset = word_start_offset + HASH_TREE_WORD_SIZE;
+                if (word_end_offset <= uarch_pristine_ram_len) { // Word is entirely inside pristine uarch ram image
+                    std::memcpy(uram.get_host_memory() + word_start_offset, uarch_pristine_ram + word_start_offset,
+                        HASH_TREE_WORD_SIZE);
+                } else if (word_start_offset >= uarch_pristine_ram_len) { // Word is entirely outside image
+                    std::memset(uram.get_host_memory() + word_start_offset, 0, HASH_TREE_WORD_SIZE);
+                } else { // Word stradles image boundary
+                    std::memcpy(uram.get_host_memory() + word_start_offset, uarch_pristine_ram + word_start_offset,
+                        uarch_pristine_ram_len - word_start_offset);
+                    std::memset(uram.get_host_memory() + uarch_pristine_ram_len, 0,
+                        word_end_offset - uarch_pristine_ram_len);
                 }
             }
         }
@@ -2281,40 +2282,36 @@ uarch_cycle_root_hashes machine::collect_uarch_cycle_root_hashes(uint64_t mcycle
             result.reset_indices.emplace_back(result.hashes.size() - 1);
         }
 
-        // Ensure the machine really reached mcycle target
-        if (read_reg(reg::mcycle) != mcycle_target) {
-            throw std::runtime_error{"machine did not reach the expected target mcycle"};
-        }
+        mcycle_reached = read_reg(reg::mcycle);
 
-        // If we already attempt to advance one mcycle over a fixed point, we are done
-        if (at_fixed_point) {
-            break;
-        }
+        // Sanity check to ensure the loop is working correctly, this should always be true
+        assert(mcycle_reached == mcycle_target);
 
-        // If the machine halted, yielded manuallly or reached mcycle UINT64_MAX,
-        // then we are at a fixed point and should always attempt to advance one more mcycle
+        // Retrieve break reason
         if (read_reg(reg::iflags_H) != 0) {
             result.break_reason = interpreter_break_reason::halted;
-            at_fixed_point = true;
-            continue;
-        }
-        if (read_reg(reg::iflags_Y) != 0) {
+        } else if (read_reg(reg::iflags_Y) != 0) {
             result.break_reason = interpreter_break_reason::yielded_manually;
-            at_fixed_point = true;
-            continue;
-        }
-        if (read_reg(reg::mcycle) == UINT64_MAX) { // Reached maximum mcycle
-            at_fixed_point = true;
-            continue;
-        }
-        if (read_reg(reg::iflags_X) != 0) {
+        } else if (read_reg(reg::iflags_X) != 0) {
             result.break_reason = interpreter_break_reason::yielded_automatically;
             break;
         }
 
-        // The next iteration will target the next mcycle successor,
-        // but will not exceed mcycle_end if that limit is reached first
-        mcycle_target = saturating_add(mcycle_target, UINT64_C(1), mcycle_end);
+        // If we already attempted to advance one mcycle over a fixed point, we are done
+        if (at_fixed_point) {
+            break;
+        }
+
+        // If the machine halted, yielded manuallly or reached mcycle UINT64_MAX,
+        // then we are at a fixed point and should always attempt to advance one more mcycle
+        at_fixed_point = result.break_reason == interpreter_break_reason::halted ||
+            result.break_reason == interpreter_break_reason::yielded_manually || mcycle_reached == UINT64_MAX;
+
+        if (!at_fixed_point) {
+            // The next iteration will target the next mcycle successor,
+            // but will not exceed mcycle_end if that limit is reached first
+            mcycle_target = saturating_add(mcycle_target, UINT64_C(1), mcycle_end);
+        }
     }
 
     assert(back_tree.empty());
diff --git a/src/uarch-constants.h b/src/uarch-constants.h
index a5ccc0541..a79a2b50d 100644
--- a/src/uarch-constants.h
+++ b/src/uarch-constants.h
@@ -21,6 +21,7 @@
 
 #include "address-range-constants.h"
 #include "address-range-defines.h"
+#include "machine-c-api.h"
 #include "uarch-defines.h"
 
 namespace cartesi {
@@ -40,7 +41,9 @@ enum uarch_state_constants : uint64_t {
     UARCH_STATE_ALIGN_MASK = (UINT64_C(1) << UARCH_STATE_LOG2_SIZE) - 1,     ///< Mask for uarch state alignment
     UARCH_STATE_MASK = ~UARCH_STATE_ALIGN_MASK,                              ///< Mask for uarch state address space
     UARCH_STATE_CHILD_ALIGN_MASK =
-        (UINT64_C(1) << UARCH_STATE_CHILD_LOG2_SIZE) - 1 ///< Mask for uarch state child alignment
+        (UINT64_C(1) << UARCH_STATE_CHILD_LOG2_SIZE) - 1, ///< Mask for uarch state child alignment
+    UARCH_LOG2_MAX_CYCLE = EXPAND_UINT64_C(UARCH_LOG2_MAX_CYCLE_DEF),
+    UARCH_MAX_CYCLE = (UINT64_C(1) << UARCH_LOG2_MAX_CYCLE),
 };
 
 static_assert((UARCH_STATE_START_ADDRESS & UARCH_STATE_ALIGN_MASK) == 0,
@@ -61,6 +64,7 @@ static_assert(UARCH_SHADOW_START_ADDRESS < UARCH_RAM_START_ADDRESS,
     "UARCH_SHADOW_START_ADDRESS must be smaller than UARCH_RAN_START_ADDRESS");
 static_assert((UARCH_SHADOW_LENGTH & (AR_PAGE_SIZE - 1)) == 0, "UARCH_SHADOW_LENGTH must be multiple of AR_PAGE_SIZE");
 static_assert((UARCH_RAM_LENGTH & (AR_PAGE_SIZE - 1)) == 0, "UARCH_RAM_LENGTH must be multiple of AR_PAGE_SIZE");
+static_assert(UARCH_MAX_CYCLE == CM_UARCH_CYCLE_MAX, "CM_UARCH_CYCLE_MAX must be equal to UARCH_MAX_CYCLE");
 
 /// \brief ecall function codes
 enum uarch_ecall_functions : uint64_t {
diff --git a/src/uarch-defines.h b/src/uarch-defines.h
index db2aabac4..2b48a6765 100644
--- a/src/uarch-defines.h
+++ b/src/uarch-defines.h
@@ -25,6 +25,9 @@
 /// \brief Log2 size of the entire uarch memory range: shadow and ram
 #define UARCH_STATE_LOG2_SIZE_DEF 22
 
+/// \brief Log2 of the expected maximum uarch cycle
+#define UARCH_LOG2_MAX_CYCLE_DEF 20
+
 // microarchitecture ecall function codes
 #define UARCH_ECALL_FN_HALT_DEF 1            // halt uarch
 #define UARCH_ECALL_FN_PUTCHAR_DEF 2         // putchar
diff --git a/src/uarch-interpret.cpp b/src/uarch-interpret.cpp
index b29d05e0d..b12295054 100644
--- a/src/uarch-interpret.cpp
+++ b/src/uarch-interpret.cpp
@@ -38,11 +38,8 @@ uarch_interpreter_break_reason uarch_interpret(const STATE_ACCESS a, uint64_t cy
                 break;
             case UArchStepStatus::UArchHalted:
                 return uarch_interpreter_break_reason::uarch_halted;
-            // LCOV_EXCL_START
             case UArchStepStatus::CycleOverflow:
-                // Prior condition ensures that this case is unreachable. but linter may complain about missing it
-                return uarch_interpreter_break_reason::reached_target_cycle;
-                // LCOV_EXCL_STOP
+                return uarch_interpreter_break_reason::cycle_overflow;
         }
     }
     return uarch_interpreter_break_reason::reached_target_cycle;
diff --git a/src/uarch-interpret.h b/src/uarch-interpret.h
index 5e835c993..774eb483b 100644
--- a/src/uarch-interpret.h
+++ b/src/uarch-interpret.h
@@ -21,7 +21,7 @@
 
 namespace cartesi {
 
-enum class uarch_interpreter_break_reason : int { reached_target_cycle, uarch_halted };
+enum class uarch_interpreter_break_reason : int { reached_target_cycle, uarch_halted, cycle_overflow };
 
 // Run the microarchitecture interpreter until cycle hits a target or a fixed point is reached
 template <typename STATE_ACCESS>
diff --git a/src/uarch-step.cpp b/src/uarch-step.cpp
index e87030c36..1e688b0c5 100644
--- a/src/uarch-step.cpp
+++ b/src/uarch-step.cpp
@@ -21,8 +21,6 @@
 
 #include "uarch-step.h"
 
-#include <cstdint>
-
 #include "collect-uarch-cycle-hashes-state-access.h" // IWYU pragma: keep
 #include "uarch-record-state-access.h"               // IWYU pragma: keep
 #include "uarch-replay-state-access.h"               // IWYU pragma: keep
@@ -1098,7 +1096,7 @@ UArchStepStatus uarch_step(const UarchState a) {
     // This must be the first read in order to match the first log access in machine::verify_step_uarch
     uint64 cycle = readCycle(a);
     // do not advance if cycle will overflow
-    if (cycle == UINT64_MAX) {
+    if (cycle >= UARCH_MAX_CYCLE) {
         return UArchStepStatus::CycleOverflow;
     }
     // do not advance if machine is halted
diff --git a/tests/lua/cmio-test.lua b/tests/lua/cmio-test.lua
index 0d298bb24..79186cda0 100755
--- a/tests/lua/cmio-test.lua
+++ b/tests/lua/cmio-test.lua
@@ -108,8 +108,7 @@ if machine_type == "jsonrpc" then
     to_shutdown = jsonrpc.connect_server(remote_address):set_cleanup_call(jsonrpc.SHUTDOWN)
 end
 
--- There is no UINT64_MAX in Lua, so we have to use the signed representation
-local MAX_MCYCLE = -1
+local MAX_MCYCLE = cartesi.MCYCLE_MAX
 
 local function load_machine(name)
     local runtime = {
diff --git a/tests/lua/machine-bind.lua b/tests/lua/machine-bind.lua
index cdd855b5c..be8afc5c9 100755
--- a/tests/lua/machine-bind.lua
+++ b/tests/lua/machine-bind.lua
@@ -27,9 +27,8 @@ local concurrency_update_hash_tree = util.parse_number(os.getenv("CARTESI_CONCUR
 
 local lua_cmd = arg[-1] .. " -e "
 
--- There is no UINT64_MAX in Lua, so we have to use the signed representation
-local MAX_MCYCLE = -1
-local MAX_UARCH_CYCLE = -1
+local MAX_MCYCLE = cartesi.MCYCLE_MAX
+local MAX_UARCH_CYCLE = cartesi.UARCH_CYCLE_MAX
 
 -- Print help and exit
 local function help()
@@ -688,6 +687,17 @@ do_test("do not advance micro cycle if uarch is halted", function(machine)
     assert(machine:read_reg("uarch_cycle") == 0, "uarch cycle should still be 0")
 end)
 
+do_test("do not advance micro cycle if uarch cycle overflows", function(machine)
+    machine:write_reg("uarch_cycle", cartesi.UARCH_CYCLE_MAX)
+    assert(machine:read_reg("uarch_cycle") == cartesi.UARCH_CYCLE_MAX, "uarch cycle should be 0")
+    local status = machine:run_uarch(cartesi.UARCH_CYCLE_MAX + 1)
+    assert(
+        status == cartesi.UARCH_BREAK_REASON_CYCLE_OVERFLOW,
+        "run_uarch should return UARCH_BREAK_REASON_CYCLE_OVERFLOW"
+    )
+    assert(machine:read_reg("uarch_cycle") == cartesi.UARCH_CYCLE_MAX, "uarch cycle should still be 0")
+end)
+
 do_test("advance micro cycles until halt", function(machine)
     assert(machine:read_reg("uarch_cycle") == 0, "uarch cycle should be 0")
     assert(machine:read_reg("uarch_halt_flag") == 0, "machine should not be halted")
@@ -1812,9 +1822,7 @@ for _, hash_fn in pairs({ "keccak256", "sha256" }) do
             check_error_find(err, "page count is zero")
             -- override page count to overflow
             copy_step_log(filename1, filename2, function(log_data)
-                -- There is no UINT64_MAX in Lua, so we have to use the signed representation
-                local MAX_MCYCLE_COUNT = -1
-                log_data.override_page_count = MAX_MCYCLE_COUNT
+                log_data.override_page_count = cartesi.MCYCLE_MAX
             end)
             _, err = pcall(function()
                 machine:verify_step(root_hash_before, filename2, mcycle_count, bad_hash)
diff --git a/tests/lua/machine-test.lua b/tests/lua/machine-test.lua
index ad7a74372..ebb810a1b 100755
--- a/tests/lua/machine-test.lua
+++ b/tests/lua/machine-test.lua
@@ -24,8 +24,7 @@ local jsonrpc
 -- run on the same computer and cartesi-jsonrpc-machine execution path
 -- must be provided
 
--- There is no UINT64_MAX in Lua, so we have to use the signed representation
-local MAX_MCYCLE = -1
+local MAX_MCYCLE = cartesi.MCYCLE_MAX
 
 local remote_address
 local test_path = "/tmp/"
diff --git a/tests/lua/mcycle-overflow.lua b/tests/lua/mcycle-overflow.lua
index 1bba1c534..854520e14 100755
--- a/tests/lua/mcycle-overflow.lua
+++ b/tests/lua/mcycle-overflow.lua
@@ -19,9 +19,8 @@
 local cartesi = require("cartesi")
 local test_util = require("cartesi.tests.util")
 
--- There is no UINT64_MAX in Lua, so we have to use the signed representation
-local MAX_MCYCLE = -1
-local MAX_UARCH_CYCLE = -1
+local MAX_MCYCLE = cartesi.MCYCLE_MAX
+local MAX_UARCH_CYCLE = cartesi.UARCH_CYCLE_MAX
 
 local function build_machine()
     local config = {
diff --git a/tests/lua/spec-collect-hashes.lua b/tests/lua/spec-collect-hashes.lua
index 6dbb868ca..0d48babd2 100644
--- a/tests/lua/spec-collect-hashes.lua
+++ b/tests/lua/spec-collect-hashes.lua
@@ -370,13 +370,12 @@ describe("collect hashes", function()
                 expect.equal(machine:read_reg("mcycle"), mcycle_start)
                 expect.equal(machine:get_root_hash(), expected_root_hash)
 
-                expect.equal(machine:collect_uarch_cycle_root_hashes(mcycle_period), {
-                    hashes = {},
-                    reset_indices = {},
-                    break_reason = cartesi.BREAK_REASON_HALTED,
-                })
+                local collected_uarch = machine:collect_uarch_cycle_root_hashes(mcycle_end)
                 expect.equal(machine:read_reg("mcycle"), mcycle_start)
                 expect.equal(machine:get_root_hash(), expected_root_hash)
+                expect.equal(collected_uarch.break_reason, cartesi.BREAK_REASON_HALTED)
+                expect.equal(#collected_uarch.reset_indices, 1)
+                expect.equal(collected_uarch.hashes[collected_uarch.reset_indices[1]], expected_root_hash)
             end)
 
             it("should break as yielded when collecting with a yielded machine", function()
@@ -396,13 +395,12 @@ describe("collect hashes", function()
                 expect.equal(machine:read_reg("mcycle"), mcycle_start)
                 expect.equal(machine:get_root_hash(), expected_root_hash)
 
-                expect.equal(machine:collect_uarch_cycle_root_hashes(mcycle_period), {
-                    hashes = {},
-                    reset_indices = {},
-                    break_reason = cartesi.BREAK_REASON_YIELDED_MANUALLY,
-                })
+                local collected_uarch = machine:collect_uarch_cycle_root_hashes(mcycle_end)
                 expect.equal(machine:read_reg("mcycle"), mcycle_start)
                 expect.equal(machine:get_root_hash(), expected_root_hash)
+                expect.equal(collected_uarch.break_reason, cartesi.BREAK_REASON_YIELDED_MANUALLY)
+                expect.equal(#collected_uarch.reset_indices, 1)
+                expect.equal(collected_uarch.hashes[collected_uarch.reset_indices[1]], expected_root_hash)
             end)
 
             it("should break as halted when collecting up to the same mcycle with a halted machine", function()
@@ -421,13 +419,11 @@ describe("collect hashes", function()
                 expect.equal(machine:read_reg("mcycle"), mcycle_end)
                 expect.equal(machine:get_root_hash(), expected_root_hash)
 
-                expect.equal(machine:collect_uarch_cycle_root_hashes(mcycle_end), {
-                    hashes = {},
-                    reset_indices = {},
-                    break_reason = cartesi.BREAK_REASON_HALTED,
-                })
-                expect.equal(machine:read_reg("mcycle"), mcycle_end)
+                local collected_uarch = machine:collect_uarch_cycle_root_hashes(mcycle_end)
                 expect.equal(machine:get_root_hash(), expected_root_hash)
+                expect.equal(collected_uarch.break_reason, cartesi.BREAK_REASON_HALTED)
+                expect.equal(#collected_uarch.reset_indices, 1)
+                expect.equal(collected_uarch.hashes[collected_uarch.reset_indices[1]], expected_root_hash)
             end)
 
             it("should break as yielded when collecting up to the same mcycle with a yielded machine", function()
@@ -446,13 +442,11 @@ describe("collect hashes", function()
                 expect.equal(machine:read_reg("mcycle"), mcycle_end)
                 expect.equal(machine:get_root_hash(), expected_root_hash)
 
-                expect.equal(machine:collect_uarch_cycle_root_hashes(mcycle_end), {
-                    hashes = {},
-                    reset_indices = {},
-                    break_reason = cartesi.BREAK_REASON_YIELDED_MANUALLY,
-                })
-                expect.equal(machine:read_reg("mcycle"), mcycle_end)
+                local collected_uarch = machine:collect_uarch_cycle_root_hashes(mcycle_end)
                 expect.equal(machine:get_root_hash(), expected_root_hash)
+                expect.equal(collected_uarch.break_reason, cartesi.BREAK_REASON_YIELDED_MANUALLY)
+                expect.equal(#collected_uarch.reset_indices, 1)
+                expect.equal(collected_uarch.hashes[collected_uarch.reset_indices[1]], expected_root_hash)
             end)
 
             it("should collect mcycles during mcycle overflow", function()
@@ -497,12 +491,11 @@ describe("collect hashes", function()
                 expect.equal(#collected_uarch.reset_indices, 2)
                 expect.equal(machine:read_reg("mcycle"), cartesi.MCYCLE_MAX)
 
-                expect.equal(machine:collect_uarch_cycle_root_hashes(cartesi.MCYCLE_MAX), {
-                    hashes = {},
-                    reset_indices = {},
-                    break_reason = cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE,
-                })
-                expect.equal(machine:read_reg("mcycle"), cartesi.MCYCLE_MAX)
+                collected_uarch = machine:collect_uarch_cycle_root_hashes(cartesi.MCYCLE_MAX)
+                expect.equal(machine:get_root_hash(), expected_root_hash)
+                expect.equal(collected_uarch.break_reason, cartesi.BREAK_REASON_REACHED_TARGET_MCYCLE)
+                expect.equal(#collected_uarch.reset_indices, 1)
+                expect.equal(collected_uarch.hashes[collected_uarch.reset_indices[1]], expected_root_hash)
             end)
 
             local add_machine_config = {

From 07fff18483f7295f13cf14e2a2c00ec7249d2712 Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Mon, 29 Sep 2025 13:10:05 -0300
Subject: [PATCH 71/82] feat: add remove_stored machine method

---
 src/clua-i-machine.cpp         | 12 ++++++++++++
 src/i-machine.h                |  6 ++++++
 src/jsonrpc-discover.json      | 21 +++++++++++++++++++++
 src/jsonrpc-machine.cpp        |  5 +++++
 src/jsonrpc-machine.h          |  1 +
 src/jsonrpc-remote-machine.cpp | 15 +++++++++++++++
 src/local-machine.cpp          |  4 ++++
 src/local-machine.h            |  1 +
 src/machine-c-api.cpp          | 11 +++++++++++
 src/machine-c-api.h            |  9 +++++++++
 src/machine.cpp                | 26 ++++++++++++++++++++++++++
 src/machine.h                  |  4 ++++
 12 files changed, 115 insertions(+)

diff --git a/src/clua-i-machine.cpp b/src/clua-i-machine.cpp
index 326ad1469..88cb6ed32 100644
--- a/src/clua-i-machine.cpp
+++ b/src/clua-i-machine.cpp
@@ -811,6 +811,17 @@ static int machine_obj_index_clone_stored(lua_State *L) {
     return 0;
 }
 
+/// \brief This is the machine:remove_stored() method implementation.
+/// \param L Lua state.
+static int machine_obj_index_remove_stored(lua_State *L) {
+    auto &m = clua_check<clua_managed_cm_ptr<cm_machine>>(L, 1);
+    const char *dir = luaL_checkstring(L, 2);
+    if (cm_remove_stored(m.get(), dir) != 0) {
+        return luaL_error(L, "%s", cm_get_last_error_message());
+    }
+    return 0;
+}
+
 /// \brief This is the machine:verify_hash_tree() method implementation.
 /// \param L Lua state.
 static int machine_obj_index_verify_hash_tree(lua_State *L) {
@@ -1177,6 +1188,7 @@ static const auto machine_obj_index = cartesi::clua_make_luaL_Reg_array({
     {"set_runtime_config", machine_obj_index_set_runtime_config},
     {"store", machine_obj_index_store},
     {"clone_stored", machine_obj_index_clone_stored},
+    {"remove_stored", machine_obj_index_remove_stored},
     {"swap", machine_obj_index_swap},
     {"translate_virtual_address", machine_obj_index_translate_virtual_address},
     {"verify_hash_tree", machine_obj_index_verify_hash_tree},
diff --git a/src/i-machine.h b/src/i-machine.h
index 54f162565..424cbb444 100644
--- a/src/i-machine.h
+++ b/src/i-machine.h
@@ -108,6 +108,11 @@ class i_machine {
         do_clone_stored(from_dir, to_dir);
     }
 
+    /// \brief Removes a stored machine from a directory
+    void remove_stored(const std::string &dir) const {
+        do_remove_stored(dir);
+    }
+
     /// \brief  Runs the machine for the given mcycle count and generates a log file of accessed pages and proof data.
     interpreter_break_reason log_step(uint64_t mcycle_count, const std::string &filename) {
         return do_log_step(mcycle_count, filename);
@@ -305,6 +310,7 @@ class i_machine {
         const std::optional<back_merkle_tree> &previous_back_tree) = 0;
     virtual void do_store(const std::string &dir, sharing_mode sharing) const = 0;
     virtual void do_clone_stored(const std::string &from_dir, const std::string &to_dir) const = 0;
+    virtual void do_remove_stored(const std::string &dir) const = 0;
     virtual interpreter_break_reason do_log_step(uint64_t mcycle_count, const std::string &filename) = 0;
     virtual access_log do_log_step_uarch(const access_log::type &log_type) = 0;
     virtual hash_tree_proof do_get_proof(uint64_t address, int log2_size) const = 0;
diff --git a/src/jsonrpc-discover.json b/src/jsonrpc-discover.json
index 5b0aa0b88..79609c841 100644
--- a/src/jsonrpc-discover.json
+++ b/src/jsonrpc-discover.json
@@ -254,6 +254,27 @@
         }
       }
     },
+    {
+      "name": "machine.remove_stored",
+      "summary": "Removes a stored machine instance from a directory",
+      "params": [
+        {
+          "name": "dir",
+          "description": "Directory to stored machine instance",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "result": {
+        "name": "status",
+        "description": "True when operation succeeded",
+        "schema": {
+          "type": "boolean"
+        }
+      }
+    },
     {
       "name": "machine.run",
       "summary": "Runs the emulator until a given cycle",
diff --git a/src/jsonrpc-machine.cpp b/src/jsonrpc-machine.cpp
index 49164df14..1f4e6eed1 100644
--- a/src/jsonrpc-machine.cpp
+++ b/src/jsonrpc-machine.cpp
@@ -680,6 +680,11 @@ void jsonrpc_machine::do_clone_stored(const std::string &from_dir, const std::st
     request("machine.clone_stored", std::tie(from_dir, to_dir), result);
 }
 
+void jsonrpc_machine::do_remove_stored(const std::string &dir) const {
+    bool result = false;
+    request("machine.remove_stored", std::tie(dir), result);
+}
+
 uint64_t jsonrpc_machine::do_read_reg(reg r) const {
     uint64_t result = 0;
     request("machine.read_reg", std::tie(r), result);
diff --git a/src/jsonrpc-machine.h b/src/jsonrpc-machine.h
index 18c846930..d98dbb903 100644
--- a/src/jsonrpc-machine.h
+++ b/src/jsonrpc-machine.h
@@ -121,6 +121,7 @@ class jsonrpc_machine final : public i_machine {
     interpreter_break_reason do_log_step(uint64_t mcycle_count, const std::string &filename) override;
     void do_store(const std::string &dir, sharing_mode sharing) const override;
     void do_clone_stored(const std::string &from_dir, const std::string &to_dir) const override;
+    void do_remove_stored(const std::string &dir) const override;
     uint64_t do_read_reg(reg r) const override;
     void do_write_reg(reg w, uint64_t val) override;
     void do_read_memory(uint64_t address, unsigned char *data, uint64_t length) const override;
diff --git a/src/jsonrpc-remote-machine.cpp b/src/jsonrpc-remote-machine.cpp
index 177dc42af..733f03e38 100644
--- a/src/jsonrpc-remote-machine.cpp
+++ b/src/jsonrpc-remote-machine.cpp
@@ -1009,6 +1009,20 @@ static json jsonrpc_machine_clone_stored_handler(const json &j, const std::share
     return jsonrpc_response_ok(j);
 }
 
+/// \brief JSONRPC handler for the machine.remove_stored method
+/// \param j JSON request object
+/// \param session HTTP session
+/// \returns JSON response object
+static json jsonrpc_machine_remove_stored_handler(const json &j, const std::shared_ptr<http_session> &session) {
+    if (!session->handler->machine) {
+        return jsonrpc_response_invalid_request(j, "no machine");
+    }
+    static const char *param_name[] = {"dir"};
+    auto args = parse_args<std::string>(j, param_name);
+    cartesi::machine::remove_stored(std::get<0>(args));
+    return jsonrpc_response_ok(j);
+}
+
 /// \brief JSONRPC handler for the machine.run method
 /// \param j JSON request object
 /// \param session HTTP session
@@ -1543,6 +1557,7 @@ static json jsonrpc_dispatch_method(const json &j, const std::shared_ptr<http_se
         {"machine.destroy", jsonrpc_machine_destroy_handler},
         {"machine.store", jsonrpc_machine_store_handler},
         {"machine.clone_stored", jsonrpc_machine_clone_stored_handler},
+        {"machine.remove_stored", jsonrpc_machine_remove_stored_handler},
         {"machine.run", jsonrpc_machine_run_handler},
         {"machine.log_step", jsonrpc_machine_log_step_handler},
         {"machine.run_uarch", jsonrpc_machine_run_uarch_handler},
diff --git a/src/local-machine.cpp b/src/local-machine.cpp
index 3daac6abf..77ccb7a41 100644
--- a/src/local-machine.cpp
+++ b/src/local-machine.cpp
@@ -81,6 +81,10 @@ void local_machine::do_clone_stored(const std::string &from_dir, const std::stri
     machine::clone_stored(from_dir, to_dir);
 }
 
+void local_machine::do_remove_stored(const std::string &dir) const {
+    machine::remove_stored(dir);
+}
+
 interpreter_break_reason local_machine::do_run(uint64_t mcycle_end) {
     return get_machine()->run(mcycle_end);
 }
diff --git a/src/local-machine.h b/src/local-machine.h
index 4cd52ed77..de789d168 100644
--- a/src/local-machine.h
+++ b/src/local-machine.h
@@ -61,6 +61,7 @@ class local_machine final : public i_machine {
     interpreter_break_reason do_log_step(uint64_t mcycle_count, const std::string &filename) override;
     void do_store(const std::string &directory, sharing_mode sharing) const override;
     void do_clone_stored(const std::string &from_dir, const std::string &to_dir) const override;
+    void do_remove_stored(const std::string &dir) const override;
     access_log do_log_step_uarch(const access_log::type &log_type) override;
     hash_tree_proof do_get_proof(uint64_t address, int log2_size) const override;
     machine_hash do_get_root_hash() const override;
diff --git a/src/machine-c-api.cpp b/src/machine-c-api.cpp
index 8493b7069..4e42faf24 100644
--- a/src/machine-c-api.cpp
+++ b/src/machine-c-api.cpp
@@ -638,6 +638,17 @@ cm_error cm_clone_stored(const cm_machine *m, const char *from_dir, const char *
     return cm_result_failure();
 }
 
+cm_error cm_remove_stored(const cm_machine *m, const char *dir) try {
+    if (dir == nullptr) {
+        throw std::invalid_argument("invalid dir");
+    }
+    const auto *cpp_m = convert_from_c(m);
+    cpp_m->remove_stored(dir);
+    return cm_result_success();
+} catch (...) {
+    return cm_result_failure();
+}
+
 cm_error cm_run(cm_machine *m, uint64_t mcycle_end, cm_break_reason *break_reason) try {
     auto *cpp_m = convert_from_c(m);
     const auto status = cpp_m->run(mcycle_end);
diff --git a/src/machine-c-api.h b/src/machine-c-api.h
index ee181b671..eea8c5a1f 100644
--- a/src/machine-c-api.h
+++ b/src/machine-c-api.h
@@ -468,6 +468,15 @@ CM_API cm_error cm_store(const cm_machine *m, const char *dir, cm_sharing_mode s
 /// The source directory machine must not have a running instance.
 CM_API cm_error cm_clone_stored(const cm_machine *m, const char *from_dir, const char *to_dir);
 
+/// \brief Removes all files and the directory of a previously stored machine.
+/// \param m Pointer to a machine object. Can be NULL (for local machines).
+/// \param dir Path to the directory containing the stored machine to be removed.
+/// \returns 0 for success, non zero code for error.
+/// \details The stored machine must not be in use.
+/// On success, the entire directory and all machine files are deleted.
+/// On failure, some files or the directory may remain.
+CM_API cm_error cm_remove_stored(const cm_machine *m, const char *dir);
+
 /// \brief Destroy a machine instance and remove it from the object.
 /// \param m Pointer to a non-empty machine object (holds a machine instance).
 /// \returns 0 for success, non zero code for error.
diff --git a/src/machine.cpp b/src/machine.cpp
index 80c1176c9..3cb34b96b 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -489,6 +489,32 @@ void machine::clone_stored(const std::string &from_dir, const std::string &to_di
     remover.retain_all();
 }
 
+void machine::remove_stored(const std::string &dir) {
+    if (dir.empty()) {
+        throw std::invalid_argument{"directory name cannot be empty"};
+    }
+    const auto config = machine_config::load(dir);
+
+    // Remove all address ranges
+    os::remove_file(config.processor.backing_store.data_filename);
+    os::remove_file(config.pmas.backing_store.data_filename);
+    os::remove_file(config.dtb.backing_store.data_filename);
+    os::remove_file(config.ram.backing_store.data_filename);
+    os::remove_file(config.cmio.rx_buffer.backing_store.data_filename);
+    os::remove_file(config.cmio.tx_buffer.backing_store.data_filename);
+    os::remove_file(config.uarch.processor.backing_store.data_filename);
+    os::remove_file(config.uarch.ram.backing_store.data_filename);
+    for (const auto &f : config.flash_drive) {
+        os::remove_file(f.backing_store.data_filename);
+    }
+
+    // Remove config
+    os::remove_file(machine_config::get_config_filename(dir));
+
+    // Remove directory
+    os::remove_directory(dir);
+}
+
 void machine::dump_insn_hist() {
 #ifdef DUMP_INSN_HIST
     d_printf("\nInstruction Histogram:\n");
diff --git a/src/machine.h b/src/machine.h
index 5ed10c85b..f4c9b8033 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -165,6 +165,10 @@ class machine final {
     /// \param to_dir Path to the destination directory where the cloned machine will be stored.
     static void clone_stored(const std::string &from_dir, const std::string &to_dir);
 
+    /// \brief Removes all files and the directory of a previously stored machine.
+    /// \param dir Path to the directory containing the stored machine to be removed.
+    static void remove_stored(const std::string &dir);
+
     /// \brief Returns address range that covers a given physical memory region
     /// \param paddr Target physical address of start of region.
     /// \param length Length of region, in bytes.

From d0259643801c2b54bb9c9e1f64cc35873f17f2f4 Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Wed, 24 Sep 2025 13:44:41 -0300
Subject: [PATCH 72/82] refactor: prepare page hash tree cache for memory
 mapping

---
 src/dense-hash-tree.h            |   1 +
 src/dirty-page-tree.h            |   3 +-
 src/hash-tree.h                  |   1 +
 src/os-mmap.h                    |   2 +-
 src/page-hash-tree-cache-stats.h |  16 ++--
 src/page-hash-tree-cache.h       | 126 ++++++++++++++++---------------
 6 files changed, 77 insertions(+), 72 deletions(-)

diff --git a/src/dense-hash-tree.h b/src/dense-hash-tree.h
index d0e38c3ba..ba7bace5d 100644
--- a/src/dense-hash-tree.h
+++ b/src/dense-hash-tree.h
@@ -104,6 +104,7 @@ class dense_hash_tree final : public i_dense_hash_tree {
     }
 
     int m_level_count;
+    //??(edubart): convert to std::span over mapped memory
     std::vector<machine_hash> m_storage;
 };
 
diff --git a/src/dirty-page-tree.h b/src/dirty-page-tree.h
index 9971f2548..10bfd23f0 100644
--- a/src/dirty-page-tree.h
+++ b/src/dirty-page-tree.h
@@ -333,7 +333,8 @@ class dirty_page_tree final : public i_dirty_page_tree {
 
     positions_range m_leaf_positions;  // Bounds on leaf positions
     positions_range m_valid_positions; // Bounds on all positions
-    container_type m_tree;             // Complete tree of flags
+    //??(edubart): convert to std::span over mapped memory
+    container_type m_tree; // Complete tree of flags
 };
 
 } // namespace cartesi
diff --git a/src/hash-tree.h b/src/hash-tree.h
index 009cf4640..97e8af9b2 100644
--- a/src/hash-tree.h
+++ b/src/hash-tree.h
@@ -201,6 +201,7 @@ class hash_tree {
 
     mutable page_hash_tree_cache m_page_cache;
     //??D Replace std::vector so entries can live on disk
+    //??(edubart): convert to a std::span over mmapped memory
     nodes_type m_sparse_nodes;
     const pristine_hashes m_pristine_hashes;
     int m_concurrency;
diff --git a/src/os-mmap.h b/src/os-mmap.h
index 05a9060b3..bf4057c20 100644
--- a/src/os-mmap.h
+++ b/src/os-mmap.h
@@ -52,7 +52,7 @@ namespace cartesi {
 struct os_mmap_flags {
     bool read_only{false};  ///< Mark mapped memory as read-only
     bool shared{false};     ///< Share mapped memory with the backing file
-    bool no_reserve{false}; ///< Do not reserve sawp memory for the mapping
+    bool no_reserve{false}; ///< Do not reserve swap memory for the mapping
 };
 
 /// \brief Structure representing a memory-mapped region.
diff --git a/src/page-hash-tree-cache-stats.h b/src/page-hash-tree-cache-stats.h
index 346544ebb..93a9c71b5 100644
--- a/src/page-hash-tree-cache-stats.h
+++ b/src/page-hash-tree-cache-stats.h
@@ -22,14 +22,14 @@
 namespace cartesi {
 
 struct page_hash_tree_cache_stats {
-    uint64_t page_hits{0};          ///\< Number of pages looked up and found in cache
-    uint64_t page_misses{0};        ///\< Number of pages looked up but missing from cache
-    uint64_t word_hits{0};          ///\< Number of words equal to corresponding word in cache entry
-    uint64_t word_misses{0};        ///\< Number of words differing from corresponding word in cache entry
-    uint64_t page_changes{0};       ///\< Number of pages changes during updates
-    uint64_t inner_page_hashes{0};  ///\< Number of inner page hashing operations performed
-    uint64_t pristine_pages{0};     ///\< Number of pages found to be pristine during updates
-    uint64_t non_pristine_pages{0}; ///\< Number of pages found not to be pristine during updates
+    uint64_t page_hits{0};          ///< Number of pages looked up and found in cache
+    uint64_t page_misses{0};        ///< Number of pages looked up but missing from cache
+    uint64_t word_hits{0};          ///< Number of words equal to corresponding word in cache entry
+    uint64_t word_misses{0};        ///< Number of words differing from corresponding word in cache entry
+    uint64_t page_changes{0};       ///< Number of pages changes during updates
+    uint64_t inner_page_hashes{0};  ///< Number of inner page hashing operations performed
+    uint64_t pristine_pages{0};     ///< Number of pages found to be pristine during updates
+    uint64_t non_pristine_pages{0}; ///< Number of pages found not to be pristine during updates
 };
 
 } // namespace cartesi
diff --git a/src/page-hash-tree-cache.h b/src/page-hash-tree-cache.h
index 76d4f87c4..35540b22f 100644
--- a/src/page-hash-tree-cache.h
+++ b/src/page-hash-tree-cache.h
@@ -31,11 +31,11 @@
 #include <optional>
 #include <ranges>
 #include <span>
-#include <unordered_map>
 #include <utility>
 #include <vector>
 
 #include <boost/container/static_vector.hpp>
+#include <boost/interprocess/offset_ptr.hpp>
 #include <boost/intrusive/list.hpp>
 #include <boost/intrusive/list_hook.hpp>
 
@@ -46,11 +46,13 @@
 #include "i-hasher.h"
 #include "is-pristine.h"
 #include "machine-hash.h"
+#include "os-mmap.h"
 #include "page-hash-tree-cache-stats.h"
 #include "ranges.h"
 #include "signposts.h"
 #include "simd-hasher.h"
 #include "strict-aliasing.h"
+#include "unordered_dense.h"
 
 namespace cartesi {
 
@@ -78,14 +80,17 @@ class page_hash_tree_cache {
 
     /// \class entry
     /// \brief Page hash-tree cache entry implementation
-    class entry : public boost::intrusive::list_base_hook<> {
+    class alignas(sizeof(uint64_t)) entry final :
+        public boost::intrusive::list_base_hook<boost::intrusive::void_pointer<
+            boost::interprocess::offset_ptr<void, int64_t, uint64_t, sizeof(uint64_t)>>> {
+        using ref = std::reference_wrapper<entry>;
 
         page m_page{};                ///< Page data for entry
         page_hash_tree m_hash_tree{}; ///< Hash-tree of data
 
         // First hash is not used, so we use its storage for some fields
         static constexpr uint64_t m_paddr_page_offset = 0;              ///< Offset where paddr_page is stored
-        static constexpr uint64_t m_borrowed_offset = sizeof(uint64_t); ///< Offset where borrowee flag is stored
+        static constexpr uint64_t m_borrowed_offset = sizeof(uint64_t); ///< Offset where borrowed flag is stored
 
         friend page_hash_tree_cache;
 
@@ -129,40 +134,33 @@ class page_hash_tree_cache {
         /// \brief Make entry's page and hash tree pristine, clear page address and borrowed flag
         /// \param pristine Pristine hash tree
         void clear(const page_hash_tree &pristine) noexcept {
-            clear_hash_tree(pristine);
             clear_page();
-            set_borrowed(false);
+            clear_hash_tree(pristine);
             set_paddr_page(0);
+            set_borrowed(false);
         }
 
         /// \brief Returns index of left child of node in page hash tree
         /// \param i Node index
         /// \returns Index of node's left child
-        static int left_child(int i) {
+        static constexpr int left_child(int i) noexcept {
             return 2 * i;
         }
 
         /// \brief Returns index of right child of node in page hash tree
         /// \param i Node index
         /// \returns Index of node's right child
-        static int right_child(int i) {
+        static constexpr int right_child(int i) noexcept {
             return (2 * i) + 1;
         }
 
         /// \brief Returns index of parent of node in page hash tree
         /// \param i Node index
         /// \returns Index of node's parent
-        static int parent(int i) {
+        static constexpr int parent(int i) noexcept {
             return i / 2;
         }
 
-        /// \brief Returns the log2 level of a node in the page hash tree (its height in the tree)
-        /// \param i Node index
-        /// \returns Log 2 level of the node
-        static int log2_level(int i) {
-            return std::countl_zero(static_cast<uint32_t>(i)) - 24;
-        }
-
         /// \brief Returns a pristine page tree for a given hasher
         /// \tparam H Hasher type
         /// \param h Hasher object
@@ -185,14 +183,11 @@ class page_hash_tree_cache {
         }
 
     public:
-        /// \brief Constructor from pristine page
-        /// \param pristine Pristine page hash tree for hasher in use
-        explicit entry(const page_hash_tree &pristine) : m_hash_tree{pristine} {}
-
-        entry(const entry &other) = default;
-        entry(entry &&other) = default;
-        entry &operator=(const entry &other) = default;
-        entry &operator=(entry &&other) = default;
+        entry() = default;
+        entry(const entry &other) = delete;
+        entry(entry &&other) = delete;
+        entry &operator=(const entry &other) = delete;
+        entry &operator=(entry &&other) = delete;
         ~entry() = default;
 
         /// \brief Returns page address for entry
@@ -251,6 +246,18 @@ class page_hash_tree_cache {
         }
     };
 
+    /// \brief Doubly-linked list of cache entries used for LRU (Least Recently Used) management.
+    /// \details The underlying data structure maintains three uint64_t values:
+    /// - An offset pointer to the list head
+    /// - An offset pointer to the list tail
+    /// - The current size of the list
+    using lru = boost::intrusive::list<entry, boost::intrusive::size_type<uint64_t>>;
+
+    // Ensure LRU and entry sizes are the same across all platforms we support
+    static_assert(sizeof(lru) == 3 * sizeof(uint64_t), "unexpected LRU size");
+    static_assert(sizeof(entry) == ((2 * sizeof(uint64_t)) + m_page_size + (m_page_hash_tree_size * MACHINE_HASH_SIZE)),
+        "unexpected entry size");
+
     template <IHasher hasher_type>
     class simd_page_hasher {
         struct leaf_entry {
@@ -326,7 +333,7 @@ class page_hash_tree_cache {
     // NOLINTNEXTLINE(cppcoreguidelines-missing-std-forward)
     bool enqueue_hash_entry(page_hash_tree_cache::simd_page_hasher<H> &queue, D &&d, entry &e,
         page_hash_tree_cache_stats &stats) noexcept {
-        if (std::ranges::size(d) != m_page_size) {
+        if (std::ranges::size(d) != m_page_size) [[unlikely]] {
             return false;
         }
         {
@@ -411,12 +418,17 @@ class page_hash_tree_cache {
         m_spid_pristine_update{os_signpost_id_generate(m_log)},
         m_spid_non_pristine_update{os_signpost_id_generate(m_log)},
 #endif
-        m_pristine_page_hash_tree{entry::get_pristine_page_hash_tree(std::forward<H>(h))},
-        m_entries{num_entries, entry{m_pristine_page_hash_tree}} {
-        m_map.reserve(num_entries);
+        m_mapped_memory{make_unique_mmap<unsigned char>(sizeof(lru) + (num_entries * sizeof(entry)))},
+        m_lru{*new(m_mapped_memory.get()) lru},
+        m_entries{new(m_mapped_memory.get() + sizeof(lru)) entry[num_entries], num_entries},
+        m_pristine_page_hash_tree{entry::get_pristine_page_hash_tree(std::forward<H>(h))} {
         if (num_entries == 0) {
             throw std::invalid_argument{"page hash-tree cache must have at least one entry"};
         }
+        m_map.reserve(num_entries);
+        for (auto &e : m_entries) {
+            e.clear_hash_tree(m_pristine_page_hash_tree);
+        }
     }
 
     page_hash_tree_cache(const page_hash_tree_cache &other) = delete;
@@ -427,10 +439,10 @@ class page_hash_tree_cache {
     /// \brief Tries to borrow a cache entry
     /// \param paddr_page Target physical address of page to borrow
     /// \returns Entry for page if in cache, nothing otherwise
-    std::optional<std::reference_wrapper<entry>> borrow_entry_if_hit(address_type paddr_page) {
+    std::optional<entry::ref> borrow_entry_if_hit(address_type paddr_page) {
         // Found entry for page in map?
         if (auto it = m_map.find(paddr_page); it != m_map.end()) {
-            entry &e = it->second.second;
+            entry &e = it->second;
             if (e.get_borrowed()) {
                 throw std::runtime_error{"page hash-tree cache entry already borrowed"};
             }
@@ -444,16 +456,16 @@ class page_hash_tree_cache {
     /// \param paddr_page Target physical address of page to borrow
     /// \param hit Receives true if page was found in cache, false if another page was evicted and its entry returned
     /// \returns Entry for page, nothing if all pages have already been borrowed
-    std::optional<std::reference_wrapper<entry>> borrow_entry(address_type paddr_page, bool &hit) {
+    std::optional<entry::ref> borrow_entry(address_type paddr_page, bool &hit) {
         SCOPED_SIGNPOST(m_log, m_spid_borrow, "phtc: borrow", "");
         // Found entry for page in map?
         if (auto it = m_map.find(paddr_page); it != m_map.end()) {
-            entry &e = it->second.second;
+            entry &e = it->second;
             if (e.get_borrowed()) {
                 throw std::runtime_error{"page hash-tree cache entry already borrowed"};
             }
             // Make it most recently used
-            m_lru.splice(m_lru.begin(), m_lru, it->second.first);
+            m_lru.splice(m_lru.begin(), m_lru, m_lru.iterator_to(e));
             hit = true;
             ++m_stats.page_hits;
             // Return borrowed entry
@@ -461,14 +473,14 @@ class page_hash_tree_cache {
         }
         hit = false;
         // Not in map, but we still have unused entries to lend
-        if (m_used < m_entries.size()) {
+        if (m_lru.size() < m_entries.size()) {
             ++m_stats.page_misses;
-            entry &e = m_entries[m_used++];
+            entry &e = m_entries[m_lru.size()];
             if (e.get_borrowed()) {
                 throw std::runtime_error{"page hash-tree cache entry already borrowed"};
             }
             m_lru.push_front(e);
-            m_map.emplace(paddr_page, map_value{m_lru.begin(), e});
+            m_map.emplace(paddr_page, e);
             // Return borrowed
             return std::ref(e.set_borrowed(true).set_paddr_page(paddr_page));
         }
@@ -482,7 +494,7 @@ class page_hash_tree_cache {
         m_map.erase(e.get_paddr_page());
         m_lru.pop_back();
         m_lru.push_front(e);
-        m_map.emplace(paddr_page, map_value{m_lru.begin(), e});
+        m_map.emplace(paddr_page, e);
         return std::ref(e.set_borrowed(true).set_paddr_page(paddr_page));
     }
 
@@ -516,25 +528,17 @@ class page_hash_tree_cache {
         for (auto &e : m_entries) {
             e.clear(m_pristine_page_hash_tree);
         }
-        m_used = 0;
     }
 
     /// \brief Returns current statistics
     /// \param clear Whether to clear statistics after retrieving them
     /// \returns Statistics
     page_hash_tree_cache_stats get_stats(bool clear = false) noexcept {
-        auto s = m_stats;
+        auto stats = m_stats;
         if (clear) {
-            m_stats.page_hits = 0;
-            m_stats.page_misses = 0;
-            m_stats.word_hits = 0;
-            m_stats.word_misses = 0;
-            m_stats.page_changes = 0;
-            m_stats.inner_page_hashes = 0;
-            m_stats.pristine_pages = 0;
-            m_stats.non_pristine_pages = 0;
-        }
-        return s;
+            m_stats = page_hash_tree_cache_stats{};
+        }
+        return stats;
     }
 
     page_hash_tree_cache_stats &get_stats_ref() noexcept {
@@ -606,20 +610,18 @@ class page_hash_tree_cache {
     os_signpost_id_t m_spid_non_pristine_update;
 #endif
 
-    using lru = boost::intrusive::list<entry>;           ///< Least-recently-used container type
-    using map_value = std::pair<lru::iterator, entry &>; ///< Value type for map
-    const page_hash_tree m_pristine_page_hash_tree;      ///< Pristine page hash tree for hasher in use
-    //??D Replace std::vector so entries can live on disk
-    std::vector<entry> m_entries; ///< Array of page hash-tree cache entries
-    //??D Replace the boost intrusive list with index-based implementation so list can live on disk as well
-    lru m_lru; ///< Least-recently-used list of entries
-    //??D Only the map will be reloaded from disk
-    //??D We *could* also replace the implementation, but I think this would be overkill
-    std::unordered_map<address_type, map_value> m_map; ///< Map from page addresses to corresponding entries
-    size_t m_used{0};                                  ///< How many entries have already been used
-
-    // Statistics
-    page_hash_tree_cache_stats m_stats;
+    unique_mmap_ptr<unsigned char> m_mapped_memory; ///< Mapped memory containing the LRU and entries
+
+    // The following fields may already be initialized by existing mapped memory
+    lru &m_lru;                 ///< Recently used entries
+    std::span<entry> m_entries; ///< Array of page hash-tree cache entries
+
+    // The following fields are always initialized from scratch
+    ankerl::unordered_dense::map<address_type, entry::ref> m_map; ///< Map from page addresses to corresponding entries
+    page_hash_tree_cache_stats m_stats;                           ///< Statistics
+
+    // ??(edubart): we could compute this on demand (on first use)
+    const page_hash_tree m_pristine_page_hash_tree; ///< Pristine page hash tree for hasher in use
 };
 
 } // namespace cartesi

From 7b528a8006c6c21ce61a124e784b2b1e90f7f432 Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Wed, 15 Oct 2025 10:00:34 -0300
Subject: [PATCH 73/82] refactor: remove unnecessary skip root hash check/store
 runtime configs

---
 src/cartesi-machine.lua      | 34 ----------------------------------
 src/json-util.cpp            |  4 ----
 src/jsonrpc-discover.json    |  6 ------
 src/machine-runtime-config.h |  2 --
 tests/lua/cmio-test.lua      |  2 --
 5 files changed, 48 deletions(-)

diff --git a/src/cartesi-machine.lua b/src/cartesi-machine.lua
index 0fb9211e0..3764a9dbd 100755
--- a/src/cartesi-machine.lua
+++ b/src/cartesi-machine.lua
@@ -318,20 +318,6 @@ where options are:
     suppress any console output during machine run.
     this includes anything written to machine's stdout or stderr.
 
-  --skip-root-hash-check
-    skip hash tree root hash check when loading a stored machine.
-    i.e., assume the stored machine files are not corrupt.
-    this is only intended to speed up machine loading in emulator tests.
-
-    DON'T USE THIS OPTION IN PRODUCTION
-
-  --skip-root-hash-store
-    skip hash tree root hash saving when storing a machine.
-    i.e., assume the stored machine will use --skip-root-hash-check when loading.
-    this is only intended to speed up machine saving in emulator tests.
-
-    DON'T USE THIS OPTION IN PRODUCTION
-
   --skip-version-check
     skip emulator version check when loading a stored machine.
     i.e., assume the stored machine is compatible with current emulator version.
@@ -750,8 +736,6 @@ local hash_tree = {
     hash_function = default_config.hash_tree.hash_function,
 }
 local concurrency_update_hash_tree = 0
-local skip_root_hash_check = false
-local skip_root_hash_store = false
 local skip_version_check = false
 local no_reserve = false
 local htif_no_console_putchar = false
@@ -1370,22 +1354,6 @@ local options = {
             return true
         end,
     },
-    {
-        "^%-%-skip%-root%-hash%-check$",
-        function(all)
-            if not all then return false end
-            skip_root_hash_check = true
-            return true
-        end,
-    },
-    {
-        "^%-%-skip%-root%-hash%-store$",
-        function(all)
-            if not all then return false end
-            skip_root_hash_store = true
-            return true
-        end,
-    },
     {
         "^%-%-skip%-version%-check$",
         function(all)
@@ -1936,8 +1904,6 @@ local runtime_config = {
     htif = {
         no_console_putchar = htif_no_console_putchar,
     },
-    skip_root_hash_check = skip_root_hash_check,
-    skip_root_hash_store = skip_root_hash_store,
     skip_version_check = skip_version_check,
     no_reserve = no_reserve,
 }
diff --git a/src/json-util.cpp b/src/json-util.cpp
index 5be2bbd31..0383b48ad 100644
--- a/src/json-util.cpp
+++ b/src/json-util.cpp
@@ -907,8 +907,6 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, machine_runtime_con
     }
     ju_get_opt_field(j[key], "concurrency"s, value.concurrency, path + to_string(key) + "/");
     ju_get_opt_field(j[key], "htif"s, value.htif, path + to_string(key) + "/");
-    ju_get_opt_field(j[key], "skip_root_hash_check"s, value.skip_root_hash_check, path + to_string(key) + "/");
-    ju_get_opt_field(j[key], "skip_root_hash_store"s, value.skip_root_hash_store, path + to_string(key) + "/");
     ju_get_opt_field(j[key], "skip_version_check"s, value.skip_version_check, path + to_string(key) + "/");
     ju_get_opt_field(j[key], "soft_yield"s, value.soft_yield, path + to_string(key) + "/");
     ju_get_opt_field(j[key], "no_reserve"s, value.no_reserve, path + to_string(key) + "/");
@@ -2300,8 +2298,6 @@ void to_json(nlohmann::json &j, const machine_runtime_config &runtime) {
     j = nlohmann::json{
         {"concurrency", runtime.concurrency},
         {"htif", runtime.htif},
-        {"skip_root_hash_check", runtime.skip_root_hash_check},
-        {"skip_root_hash_store", runtime.skip_root_hash_store},
         {"skip_version_check", runtime.skip_version_check},
         {"soft_yield", runtime.soft_yield},
         {"no_reserve", runtime.no_reserve},
diff --git a/src/jsonrpc-discover.json b/src/jsonrpc-discover.json
index 79609c841..dabe649b1 100644
--- a/src/jsonrpc-discover.json
+++ b/src/jsonrpc-discover.json
@@ -1223,12 +1223,6 @@
           "htif": {
             "$ref": "#/components/schemas/HTIFRuntimeConfig"
           },
-          "skip_root_hash_check": {
-            "type": "boolean"
-          },
-          "skip_root_hash_store": {
-            "type": "boolean"
-          },
           "skip_version_check": {
             "type": "boolean"
           },
diff --git a/src/machine-runtime-config.h b/src/machine-runtime-config.h
index 242a98d3b..a6c6c2ebd 100644
--- a/src/machine-runtime-config.h
+++ b/src/machine-runtime-config.h
@@ -38,8 +38,6 @@ struct htif_runtime_config {
 struct machine_runtime_config {
     concurrency_runtime_config concurrency{};
     htif_runtime_config htif{};
-    bool skip_root_hash_check{};
-    bool skip_root_hash_store{};
     bool skip_version_check{};
     bool soft_yield{};
     bool no_reserve{}; ///< Do not reserve swap memory when mapping flash drives
diff --git a/tests/lua/cmio-test.lua b/tests/lua/cmio-test.lua
index 79186cda0..088860f5a 100755
--- a/tests/lua/cmio-test.lua
+++ b/tests/lua/cmio-test.lua
@@ -115,8 +115,6 @@ local function load_machine(name)
         concurrency = {
             update_hash_tree = 0,
         },
-        skip_root_hash_check = true,
-        skip_root_hash_store = true,
     }
     if machine_type ~= "local" then
         local jsonrpc_machine <close> = assert(jsonrpc.connect_server(remote_address))

From 9594d5461355b2ff27f3d7f3db1d20a1514c9bad Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Mon, 29 Sep 2025 16:17:05 -0300
Subject: [PATCH 74/82] refactor: modernize memory mapping class

---
 src/Makefile                              |   2 +-
 src/machine-config.cpp                    |  10 +-
 src/machine-config.h                      |   2 +-
 src/machine.cpp                           |   9 +-
 src/memory-address-range.cpp              |  11 +-
 src/memory-address-range.h                |   9 +-
 src/{os-mmap.cpp => os-mapped-memory.cpp} | 155 ++++++++++++---------
 src/os-mapped-memory.h                    | 159 ++++++++++++++++++++++
 src/os-mmap.h                             | 122 -----------------
 src/page-hash-tree-cache.h                |  10 +-
 src/processor-state.h                     |   2 +-
 11 files changed, 276 insertions(+), 215 deletions(-)
 rename src/{os-mmap.cpp => os-mapped-memory.cpp} (80%)
 create mode 100644 src/os-mapped-memory.h
 delete mode 100644 src/os-mmap.h

diff --git a/src/Makefile b/src/Makefile
index 90dc98c88..4c82768c6 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -367,7 +367,7 @@ LIBCARTESI_OBJS:= \
 	machine-address-ranges.o \
 	memory-address-range.o \
 	os.o \
-	os-mmap.o \
+	os-mapped-memory.o \
 	os-filesystem.o \
 	plic-address-range.o \
 	back-merkle-tree.o \
diff --git a/src/machine-config.cpp b/src/machine-config.cpp
index 1d17719a8..1f8ca8996 100644
--- a/src/machine-config.cpp
+++ b/src/machine-config.cpp
@@ -44,26 +44,22 @@ std::string machine_config::get_data_filename(const std::string &dir, uint64_t s
 
 std::string machine_config::get_dht_filename(const std::string &dir, uint64_t start, uint64_t length) {
     std::ostringstream sout;
-    // dense hash tree
     sout << dir << "/" << std::hex << std::setw(16) << std::setfill('0') << start << "-" << length << ".dht";
     return sout.str();
 }
 
 std::string machine_config::get_dpt_filename(const std::string &dir, uint64_t start, uint64_t length) {
     std::ostringstream sout;
-    // dense hash tree
     sout << dir << "/" << std::hex << std::setw(16) << std::setfill('0') << start << "-" << length << ".dpt";
     return sout.str();
 }
 
 std::string machine_config::get_sht_filename(const std::string &dir) {
-    // sparse hash tree
     return dir + "/global.sht";
 }
 
 std::string machine_config::get_phtc_filename(const std::string &dir) {
-    // sparse hash tree
-    return dir + "/global.phc";
+    return dir + "/global.phtc";
 }
 
 std::string machine_config::get_config_filename(const std::string &dir) {
@@ -96,6 +92,10 @@ void machine_config::adjust_backing_store_config(uint64_t start, uint64_t length
 }
 
 void machine_config::adjust_hash_tree_config(const std::string &dir, hash_tree_config &c) {
+    // Strip create and truncate since backing store should be already created
+    c.create = false;
+    c.truncate = false;
+
     c.sht_filename = machine_config::get_sht_filename(dir);
     c.phtc_filename = machine_config::get_phtc_filename(dir);
 }
diff --git a/src/machine-config.h b/src/machine-config.h
index 0d3199b94..59008e8c9 100644
--- a/src/machine-config.h
+++ b/src/machine-config.h
@@ -193,7 +193,7 @@ struct machine_config final {
     /// \brief Get the name where dense hash-tree for an address range will be stored in a directory
     static std::string get_dht_filename(const std::string &dir, uint64_t start, uint64_t length);
 
-    /// \brief Get the name where dirty-page -tree for an address range will be stored in a directory
+    /// \brief Get the name where dirty page-tree for an address range will be stored in a directory
     static std::string get_dpt_filename(const std::string &dir, uint64_t start, uint64_t length);
 
     /// \brief Get the name where global sparse hash-tree will be stored in a directory
diff --git a/src/machine.cpp b/src/machine.cpp
index 3cb34b96b..89f58ec15 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -23,7 +23,6 @@
 #include <cstdio>
 #include <cstring>
 #include <iostream>
-#include <memory>
 #include <optional>
 #include <ranges>
 #include <span>
@@ -58,7 +57,7 @@
 #include "machine-runtime-config.h"
 #include "mcycle-root-hashes.h"
 #include "os-filesystem.h"
-#include "os-mmap.h"
+#include "os-mapped-memory.h"
 #include "os.h"
 #include "pmas-constants.h"
 #include "pmas.h"
@@ -394,7 +393,7 @@ static void store_address_range(const backing_store_config &from_config, const a
         throw std::runtime_error{"attempt to store non-memory address range "s.append(ar.get_description())};
     }
     // Write the memory data to a file
-    const std::string &data_filename = machine_config::get_data_filename(dir, ar.get_start(), ar.get_length());
+    const std::string data_filename = machine_config::get_data_filename(dir, ar.get_start(), ar.get_length());
     if (sharing == sharing_mode::all || (sharing == sharing_mode::config && from_config.shared)) {
         os::create_file(data_filename, std::span{ar.get_host_memory(), static_cast<size_t>(ar.get_length())});
     } else { // Copy unshared backing store
@@ -1894,9 +1893,9 @@ interpreter_break_reason machine::log_step(uint64_t mcycle_count, const std::str
 interpreter_break_reason machine::verify_step(const machine_hash &root_hash_before, const std::string &filename,
     uint64_t mcycle_count, const machine_hash &root_hash_after) {
     auto data_length = os::file_size(filename);
-    auto data = make_unique_mmap<unsigned char>(data_length, os_mmap_flags{}, filename, data_length);
+    auto mapped_data = os::mapped_memory(data_length, os::mapped_memory_flags{}, filename);
     replay_step_state_access::context context;
-    replay_step_state_access a(context, data.get(), data_length, root_hash_before);
+    replay_step_state_access a(context, mapped_data.get_ptr(), data_length, root_hash_before);
     const uint64_t mcycle_end = saturating_add(a.read_mcycle(), mcycle_count);
     auto break_reason = interpret(a, mcycle_end);
     a.finish(root_hash_after);
diff --git a/src/memory-address-range.cpp b/src/memory-address-range.cpp
index e8bee634f..4a800f2cf 100644
--- a/src/memory-address-range.cpp
+++ b/src/memory-address-range.cpp
@@ -25,14 +25,14 @@
 #include "address-range-constants.h"
 #include "address-range.h"
 #include "machine-config.h"
-#include "os-mmap.h"
+#include "os-mapped-memory.h"
 #include "pmas.h"
 
 namespace cartesi {
 
 using namespace std::string_literals;
 
-static os_mmap_flags check_mmap_flags(const pmas_flags &flags, const backing_store_config &backing_store,
+static os::mapped_memory_flags check_mmap_flags(const pmas_flags &flags, const backing_store_config &backing_store,
     const memory_address_range_config &memory_config) {
     if (!flags.M) {
         throw std::invalid_argument{"memory address range must be flagged memory"};
@@ -49,7 +49,7 @@ static os_mmap_flags check_mmap_flags(const pmas_flags &flags, const backing_sto
     if (memory_config.host_read_only && flags.W) {
         throw std::invalid_argument{"backing store for writable memory address range cannot be read-only"};
     }
-    return os_mmap_flags{
+    return os::mapped_memory_flags{
         .read_only = memory_config.host_read_only && !backing_store.newly_created(),
         .shared = backing_store.shared,
         .no_reserve = memory_config.host_no_reserve,
@@ -62,9 +62,8 @@ memory_address_range::memory_address_range(const std::string &description, uint6
     const pmas_flags &flags, const backing_store_config &backing_store,
     const memory_address_range_config &memory_config) try :
     address_range(description.c_str(), start, length, flags, throw_invalid_argument),
-    m_ptr{make_unique_mmap<unsigned char>(std::max(memory_config.host_length, length),
-        check_mmap_flags(flags, backing_store, memory_config), backing_store.data_filename, length)},
-    m_host_memory{m_ptr.get()},
+    m_mapped{std::max(memory_config.host_length, length), check_mmap_flags(flags, backing_store, memory_config),
+        backing_store.data_filename, length},
     m_config{memory_config},
     m_backing_store{backing_store},
     m_dpt{get_level_count(length), static_cast<size_t>(length >> AR_LOG2_PAGE_SIZE)},
diff --git a/src/memory-address-range.h b/src/memory-address-range.h
index 2879d0621..2d106c4b3 100644
--- a/src/memory-address-range.h
+++ b/src/memory-address-range.h
@@ -24,7 +24,7 @@
 #include "dense-hash-tree.h"
 #include "dirty-page-tree.h"
 #include "machine-config.h"
-#include "os-mmap.h"
+#include "os-mapped-memory.h"
 #include "pmas.h"
 
 namespace cartesi {
@@ -48,8 +48,7 @@ struct memory_address_range_config {
 /// \brief An address range occupied by memory
 
 class memory_address_range final : public address_range {
-    unique_mmap_ptr<unsigned char> m_ptr; ///< Pointer to mapped memory
-    unsigned char *m_host_memory;         ///< Start of associated memory region in host.
+    os::mapped_memory m_mapped;           ///< Pointer to mapped memory
     memory_address_range_config m_config; ///< Memory configuration passed to constructor.
     backing_store_config m_backing_store; ///< Backing store configuration passed to constructor.
     dirty_page_tree m_dpt;                ///< Tree of dirty pages.
@@ -81,11 +80,11 @@ class memory_address_range final : public address_range {
 
 private:
     unsigned char *do_get_host_memory() noexcept override {
-        return m_host_memory;
+        return m_mapped.get_ptr();
     }
 
     const unsigned char *do_get_host_memory() const noexcept override {
-        return m_host_memory;
+        return m_mapped.get_ptr();
     }
 
     bool do_is_host_read_only() const noexcept override {
diff --git a/src/os-mmap.cpp b/src/os-mapped-memory.cpp
similarity index 80%
rename from src/os-mmap.cpp
rename to src/os-mapped-memory.cpp
index 1b1acc17e..1654ab790 100644
--- a/src/os-mmap.cpp
+++ b/src/os-mapped-memory.cpp
@@ -33,7 +33,7 @@
 #include <sys/file.h> // flock
 #endif
 
-#include "os-mmap.h"
+#include "os-mapped-memory.h"
 
 #include "scope-exit.h"
 
@@ -41,18 +41,21 @@
 #include <cerrno>
 #include <cstdint>
 #include <cstring>
+#include <optional>
 #include <stdexcept>
 #include <string>
 #include <system_error>
 #include <utility>
 
-namespace cartesi {
+namespace cartesi::os {
 
 using namespace std::string_literals;
 
 constexpr uint64_t DEFAULT_MMAP_PAGE_SIZE = 4096;
 
-uint64_t os_get_mmap_page_size() {
+/// \brief Retrieves the system's memory page size.
+/// \details Typically 4KB, but may vary (e.g., 8KB on Solaris, 16KB on macOS arm64).
+static uint64_t os_get_mmap_page_size() {
 #ifdef HAVE_MMAP
     const auto page_size = sysconf(_SC_PAGESIZE);
     if (page_size < 0) {
@@ -71,8 +74,11 @@ uint64_t os_get_mmap_page_size() {
 #endif // HAVE_MMAP
 }
 
-os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string &backing_filename,
-    uint64_t backing_length) {
+mapped_memory::mapped_memory(uint64_t length, const mapped_memory_flags &flags, const std::string &backing_filename,
+    std::optional<uint64_t> backing_length) :
+    m_length(length),
+    m_backing_filename(backing_filename),
+    m_flags(flags) {
     // Check some preconditions
     if (backing_filename.empty() && flags.shared) {
         throw std::invalid_argument{"backing filename must be specified"s};
@@ -80,8 +86,13 @@ os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string
     if (length == 0) {
         throw std::invalid_argument{"memory map length cannot be zero"s};
     }
-    if (length < backing_length) {
-        throw std::invalid_argument{"length must be greater or equal than max backing length"s};
+    if (backing_length.has_value()) {
+        if (length < backing_length.value()) {
+            throw std::invalid_argument{"length must be greater or equal than max backing length"s};
+        }
+        m_backing_length = backing_length.value();
+    } else if (!backing_filename.empty()) {
+        m_backing_length = length;
     }
     const bool shared_write = flags.shared && !flags.read_only;
 
@@ -135,11 +146,11 @@ os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string
         backing_file_length = static_cast<uint64_t>(statbuf.st_size);
 
         // Check backing file length mismatch
-        if (backing_file_length != backing_length) {
+        if (backing_file_length != m_backing_length) {
             if (flags.shared) {
                 throw std::runtime_error{"backing file '"s + backing_filename + "' length ("s +
                     std::to_string(backing_file_length) + ") does not match desired backing length ("s +
-                    std::to_string(backing_length) + ")"s};
+                    std::to_string(m_backing_length) + ")"s};
             }
             // Backing file length may be less than desired backing length,
             // but this is fine, as we are not sharing the file.
@@ -224,11 +235,10 @@ os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string
         }
     }
 
-    return os_mmapd{.host_memory = host_memory,
-        .length = length,
-        .flags = flags,
-        .backing_sync_length = shared_write ? backing_length : 0,
-        .backing_fd = backing_fd};
+    // Commit state
+    m_host_memory = host_memory;
+    m_backing_sync_length = shared_write ? m_backing_length : 0;
+    m_backing_fd = backing_fd;
 
 #elif defined(_WIN32)
     HANDLE backing_fh = INVALID_HANDLE_VALUE;
@@ -296,13 +306,13 @@ os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string
         backing_file_length = static_cast<uint64_t>(size.QuadPart);
 
         // Check backing file length mismatch
-        if (backing_file_length != backing_length) {
+        if (backing_file_length != m_backing_length) {
             if (flags.shared) {
                 throw std::runtime_error{"backing file '"s + backing_filename + "' length ("s +
                     std::to_string(backing_file_length) + ") does not match desired backing length ("s +
-                    std::to_string(backing_length) + ")"s};
+                    std::to_string(m_backing_length) + ")"s};
 
-                backing_file_length = backing_length;
+                backing_file_length = m_backing_length;
             }
             // Backing file length may be less than desired backing length,
             // but this is fine, as we are not sharing the file.
@@ -371,14 +381,12 @@ os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string
         std::memcpy(host_memory, backing_host_memory, backing_file_length);
     }
 
-    return os_mmapd{.host_memory = host_memory,
-        .length = length,
-        .flags = flags,
-        .backing_sync_length = shared_write ? backing_length : 0,
-        .memory_mapping = static_cast<void *>(memory_mapping),
-        .backing_host_memory = backing_host_memory,
-        .backing_mapping = backing_mapping,
-        .backing_fh = static_cast<void *>(backing_fh)};
+    // Commit state
+    m_host_memory = host_memory;
+    m_backing_sync_length = shared_write ? m_backing_length : 0;
+    m_memory_mapping = static_cast<void *>(memory_mapping), m_backing_host_memory = backing_host_memory,
+    m_backing_mapping = backing_mapping, m_backing_fh = static_cast<void *>(backing_fh)
+};
 
 #else  // Fallback implementation using standard C APIs
     // Over-allocate to ensure we can align the pointer and store the original pointer.
@@ -444,18 +452,18 @@ os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string
             throw std::system_error{errno, std::generic_category(),
                 "unable to seek to beginning of backing file '"s + backing_filename + "'"s};
         }
-        const auto copy_length = std::min(backing_file_length, backing_length);
+        const auto copy_length = std::min(backing_file_length, m_backing_length);
         if (static_cast<uint64_t>(std::fread(host_memory, 1, copy_length, backing_fp)) != copy_length) {
             throw std::system_error{errno, std::generic_category(),
                 "unable to read from backing file '"s + backing_filename + "'"s};
         }
 
         // Check backing file length mismatch
-        if (backing_file_length != backing_length) {
+        if (backing_file_length != m_backing_length) {
             if (flags.shared) {
                 throw std::runtime_error{"backing file '"s + backing_filename + "' length ("s +
                     std::to_string(backing_file_length) + ") does not match desired backing length ("s +
-                    std::to_string(backing_length) + ")"s};
+                    std::to_string(m_backing_length) + ")"s};
             }
             // Backing file length may be less than desired backing length,
             // but this is fine, as we are not sharing the file.
@@ -469,73 +477,92 @@ os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags, const std::string
         }
     }
 
-    return os_mmapd{.host_memory = host_memory,
-        .length = length,
-        .flags = flags,
-        .backing_sync_length = shared_write ? backing_length : 0,
-        .backing_fp = backing_fp,
-        .unaligned_host_memory = unaligned_host_memory};
+    // Commit state
+    m_host_memory = host_memory;
+    m_backing_sync_length = shared_write ? m_backing_length : 0;
+    m_backing_fp = backing_fp;
+    m_unaligned_host_memory = unaligned_host_memory;
 #endif // HAVE_MMAP
 }
 
-void os_munmap(const os_mmapd &mmapd) noexcept {
+mapped_memory::mapped_memory(mapped_memory &&other) noexcept : mapped_memory() {
+    std::swap(m_host_memory, other.m_host_memory);
+    std::swap(m_length, other.m_length);
+    std::swap(m_backing_filename, other.m_backing_filename);
+    std::swap(m_backing_length, other.m_backing_length);
+    std::swap(m_backing_sync_length, other.m_backing_sync_length);
+    std::swap(m_flags, other.m_flags);
+#ifdef HAVE_MMAP
+    std::swap(m_backing_fd, other.m_backing_fd);
+#elif defined(_WIN32)
+    std::swap(m_memory_mapping, other.m_memory_mapping);
+    std::swap(m_backing_host_memory, other.m_backing_host_memory);
+    std::swap(m_backing_mapping, other.m_backing_mapping);
+    std::swap(m_backing_fh, other.m_backing_fh);
+#else
+    std::swap(m_backing_fp, other.m_backing_fp);
+    std::swap(m_unaligned_host_memory, other.m_unaligned_host_memory);
+#endif
+}
+
+mapped_memory::~mapped_memory() noexcept {
 #ifdef HAVE_MMAP
-    if (mmapd.host_memory != nullptr && mmapd.length > 0) {
+    if (m_host_memory != nullptr && m_length > 0) {
         // Asynchronously flush mapped memory to disk to help prevent data loss
-        if (mmapd.backing_sync_length > 0) {
-            std::ignore = msync(mmapd.host_memory, mmapd.backing_sync_length, MS_ASYNC);
+        if (m_backing_sync_length > 0) {
+            std::ignore = msync(m_host_memory, m_backing_sync_length, MS_ASYNC);
         }
-        std::ignore = munmap(mmapd.host_memory, mmapd.length);
+        std::ignore = munmap(m_host_memory, m_length);
     }
-    if (mmapd.backing_fd != -1) {
+    if (m_backing_fd != -1) {
         // Closing a file will also release file locks
-        while (close(mmapd.backing_fd) != 0 && errno == EINTR) {
+        while (close(m_backing_fd) != 0 && errno == EINTR) {
             // Interrupted by signal, retry
         };
     }
 
 #elif defined(_WIN32) // Windows implementation
     // Flush changes to disk if necessary
-    if (mmapd.backing_sync_length > 0 && mmapd.host_memory != nullptr) {
+    if (m_backing_sync_length > 0 && m_host_memory != nullptr) {
         // Asynchronously flush mapped memory to disk to help prevent data loss
-        if (mmapd.backing_host_memory != nullptr) {
-            std::memcpy(mmapd.backing_host_memory, mmapd.host_memory, mmapd.backing_sync_length);
-            std::ignore = FlushViewOfFile(mmapd.backing_host_memory, mmapd.backing_sync_length);
+        if (m_backing_host_memory != nullptr) {
+            std::memcpy(m_backing_host_memory, m_host_memory, m_backing_sync_length);
+            std::ignore = FlushViewOfFile(m_backing_host_memory, m_backing_sync_length);
         } else {
-            std::ignore = FlushViewOfFile(mmapd.host_memory, mmapd.backing_sync_length);
+            std::ignore = FlushViewOfFile(m_host_memory, m_backing_sync_length);
         }
     }
-    if (mmapd.host_memory != nullptr) {
-        std::ignore = UnmapViewOfFile(mmapd.host_memory);
+    if (m_host_memory != nullptr) {
+        std::ignore = UnmapViewOfFile(m_host_memory);
     }
-    if (mmapd.backing_host_memory != nullptr) {
-        std::ignore = UnmapViewOfFile(mmapd.backing_host_memory);
+    if (m_backing_host_memory != nullptr) {
+        std::ignore = UnmapViewOfFile(m_backing_host_memory);
     }
-    if (mmapd.memory_mapping != nullptr) {
-        std::ignore = CloseHandle(static_cast<HANDLE>(mmapd.memory_mapping));
+    if (m_memory_mapping != nullptr) {
+        std::ignore = CloseHandle(static_cast<HANDLE>(m_memory_mapping));
     }
-    if (mmapd.backing_mapping != nullptr) {
-        std::ignore = CloseHandle(static_cast<HANDLE>(mmapd.backing_mapping));
+    if (m_backing_mapping != nullptr) {
+        std::ignore = CloseHandle(static_cast<HANDLE>(m_backing_mapping));
     }
-    if (mmapd.backing_fh != nullptr && mmapd.backing_fh != INVALID_HANDLE_VALUE) {
+    if (m_backing_fh != nullptr && m_backing_fh != INVALID_HANDLE_VALUE) {
         OVERLAPPED overlapped{};
-        std::ignore = UnlockFileEx(static_cast<HANDLE>(mmapd.backing_fh), 0, MAXDWORD, MAXDWORD, &overlapped);
-        std::ignore = CloseHandle(static_cast<HANDLE>(mmapd.backing_fh));
+        std::ignore = UnlockFileEx(static_cast<HANDLE>(m_backing_fh), 0, MAXDWORD, MAXDWORD, &overlapped);
+        std::ignore = CloseHandle(static_cast<HANDLE>(m_backing_fh));
     }
 
 #else // Fallback implementation using standard C APIs
-    if (mmapd.backing_sync_length > 0 && mmapd.host_memory != nullptr && mmapd.backing_fp != nullptr) {
+    if (m_backing_sync_length > 0 && m_host_memory != nullptr && m_backing_fp != nullptr) {
         // Write back changes to backing file
-        std::ignore = std::fwrite(mmapd.host_memory, 1, mmapd.backing_sync_length, mmapd.backing_fp);
+        std::ignore = std::fwrite(m_host_memory, 1, m_backing_sync_length, m_backing_fp);
     }
-    if (mmapd.unaligned_host_memory != nullptr) {
-        std::free(mmapd.unaligned_host_memory); // NOLINT(cppcoreguidelines-no-malloc,hicpp-no-malloc)
+    if (m_unaligned_host_memory != nullptr) {
+        std::free(m_unaligned_host_memory); // NOLINT(cppcoreguidelines-no-malloc,hicpp-no-malloc)
     }
-    if (mmapd.backing_fp != nullptr) {
-        std::ignore = std::fclose(mmapd.backing_fp);
+    if (m_backing_fp != nullptr) {
+        std::ignore = std::fclose(m_backing_fp);
     }
 
 #endif // HAVE_MMAP
 }
 
-} // namespace cartesi
+} // namespace cartesi::os
diff --git a/src/os-mapped-memory.h b/src/os-mapped-memory.h
new file mode 100644
index 000000000..c87d54580
--- /dev/null
+++ b/src/os-mapped-memory.h
@@ -0,0 +1,159 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: LGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option) any
+// later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along
+// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+//
+
+#ifndef OS_MAPPED_MEMORY_H
+#define OS_MAPPED_MEMORY_H
+
+/// \file
+/// \brief Operating system memory mapping operations.
+/// \details \{
+/// This header file defines the interface for memory mapping operations for the emulator.
+/// It provides a cross-platform abstraction for memory-mapped regions, supporting both anonymous
+/// and file-backed mappings. The implementation ensures compatibility with various operating
+/// systems, including Linux, Windows, and fallback environments without native `mmap` support.
+///
+/// Key Features:
+/// - Memory mapping with optional file backing.
+/// - Support for read-only, shared, and exclusive access modes.
+/// - Automatic alignment to system page size for efficient memory access.
+/// - Cross-platform compatibility with platform-specific optimizations.
+///
+/// This module is designed to handle complex memory mapping scenarios, such as partial file
+/// mappings, and synchronization of file-backed memory regions.
+/// \}
+
+#include <cstdint>
+#include <optional>
+#include <span>
+#include <string>
+
+#include "os-features.h"
+
+#ifndef HAVE_MMAP
+#include <cstdio>
+#endif
+
+namespace cartesi::os {
+
+/// \brief Flags for memory mapping operations.
+struct mapped_memory_flags {
+    bool read_only{false};  ///< Mark mapped memory as read-only
+    bool shared{false};     ///< Share mapped memory with the backing file
+    bool no_reserve{false}; ///< Do not reserve swap memory for the mapping
+};
+
+/// \brief Represents a memory-mapped region, optionally backed by a file.
+class mapped_memory final {
+    void *m_host_memory{nullptr};      ///< Pointer to the mapped memory region
+    uint64_t m_length{0};              ///< The total size of the mapped memory
+    std::string m_backing_filename;    ///< Path to the backing file
+    uint64_t m_backing_length{0};      ///< Backing file length in bytes
+    uint64_t m_backing_sync_length{0}; ///< Length of file-backed portion for which memory sync is needed
+    mapped_memory_flags m_flags;       ///< Flags used for the mapping
+#ifdef HAVE_MMAP
+    int m_backing_fd{-1}; ///< File descriptor of the backing file
+#elif defined(_WIN32)
+    void *m_memory_mapping{nullptr};      ///< Handle of the memory mapping
+    void *m_backing_host_memory{nullptr}; ///< Pointer to the backing file mapped memory region
+    void *m_backing_mapping{nullptr};     ///< Handle of the backing file mapping
+    void *m_backing_fh{nullptr};          ///< Handle of the backing file
+#else
+    FILE *m_backing_fp{nullptr};            ///< Pointer of the backing file
+    void *m_unaligned_host_memory{nullptr}; ///< Pointer to the memory that we can deallocate with std::free()
+#endif
+
+    mapped_memory() = default;
+
+public:
+    /// \brief Maps a memory region, optionally backed by a file.
+    /// \param length Total memory length to map.
+    /// \param flags Flags for the mapping.
+    /// \param backing_filename Path to the file to back the memory mapping.
+    /// \param backing_length The expected size of the backing file in bytes (must be <= length).
+    /// \returns Structure containing the memory mapping information.
+    /// \details The memory is guaranteed to be aligned to 4096-byte boundaries.
+    /// Memory above backing file length are zereod, and modifications to that region are not written out to the file.
+    explicit mapped_memory(uint64_t length, const mapped_memory_flags &flags = {},
+        const std::string &backing_filename = {}, std::optional<uint64_t> backing_length = {});
+
+    /// \brief Move constructor.
+    mapped_memory(mapped_memory &&other) noexcept;
+
+    /// \brief Destructor.
+    ~mapped_memory() noexcept;
+
+    // No copy constructor or copy assignment
+    mapped_memory(const mapped_memory &other) = delete;
+    mapped_memory &operator=(const mapped_memory &other) = delete;
+
+    // No move assignment
+    mapped_memory &operator=(mapped_memory &&other) noexcept = delete;
+
+    /// \brief Returns a pointer to the mapped memory region.
+    unsigned char *get_ptr() {
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        return reinterpret_cast<unsigned char *>(m_host_memory);
+    };
+
+    /// \brief Returns a pointer to the mapped memory region.
+    const unsigned char *get_ptr() const {
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        return reinterpret_cast<const unsigned char *>(m_host_memory);
+    };
+
+    /// \brief Returns a span representing the mapped memory region.
+    std::span<unsigned char> get_span() noexcept {
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        return std::span<unsigned char>{reinterpret_cast<unsigned char *>(m_host_memory), m_length};
+    }
+
+    /// \brief Returns a span representing the mapped memory region.
+    std::span<const unsigned char> get_span() const noexcept {
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        return std::span<const unsigned char>{reinterpret_cast<const unsigned char *>(m_host_memory), m_length};
+    }
+
+    /// \brief Returns a span representing the backing portion of the mapped memory region.
+    std::span<unsigned char> get_backing_span() noexcept {
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        return std::span<unsigned char>{reinterpret_cast<unsigned char *>(m_host_memory), m_backing_length};
+    }
+
+    /// \brief Returns a span representing the backing portion of the mapped memory region.
+    std::span<const unsigned char> get_backing_span() const noexcept {
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        return std::span<const unsigned char>{reinterpret_cast<const unsigned char *>(m_host_memory), m_backing_length};
+    }
+
+    /// \brief Returns the total length of the mapped memory region.
+    uint64_t get_length() const noexcept {
+        return m_length;
+    }
+
+    /// \brief Returns the length of the backing file portion of the mapped memory region.
+    uint64_t get_backing_length() const noexcept {
+        return m_backing_length;
+    }
+
+    /// \brief Returns the flags used for the mapping.
+    mapped_memory_flags get_flags() const noexcept {
+        return m_flags;
+    }
+};
+
+} // namespace cartesi::os
+
+#endif
diff --git a/src/os-mmap.h b/src/os-mmap.h
deleted file mode 100644
index bf4057c20..000000000
--- a/src/os-mmap.h
+++ /dev/null
@@ -1,122 +0,0 @@
-// Copyright Cartesi and individual authors (see AUTHORS)
-// SPDX-License-Identifier: LGPL-3.0-or-later
-//
-// This program is free software: you can redistribute it and/or modify it under
-// the terms of the GNU Lesser General Public License as published by the Free
-// Software Foundation, either version 3 of the License, or (at your option) any
-// later version.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-// PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public License along
-// with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
-//
-
-#ifndef OS_MMAP_H
-#define OS_MMAP_H
-
-/// \file
-/// \brief Operating system memory mapping operations.
-/// \details \{
-/// This header file defines the interface for memory mapping operations for the emulator.
-/// It provides a cross-platform abstraction for memory-mapped regions, supporting both anonymous
-/// and file-backed mappings. The implementation ensures compatibility with various operating
-/// systems, including Linux, Windows, and fallback environments without native `mmap` support.
-///
-/// Key Features:
-/// - Memory mapping with optional file backing.
-/// - Support for read-only, shared, and exclusive access modes.
-/// - Automatic alignment to system page size for efficient memory access.
-/// - Cross-platform compatibility with platform-specific optimizations.
-///
-/// This module is designed to handle complex memory mapping scenarios, such as partial file
-/// mappings, and synchronization of file-backed memory regions.
-/// \}
-
-#include <cstddef>
-#include <cstdint>
-#include <memory>
-#include <string>
-
-#include "os-features.h"
-
-#ifndef HAVE_MMAP
-#include <cstdio>
-#endif
-
-namespace cartesi {
-
-/// \brief Flags for memory mapping operations.
-struct os_mmap_flags {
-    bool read_only{false};  ///< Mark mapped memory as read-only
-    bool shared{false};     ///< Share mapped memory with the backing file
-    bool no_reserve{false}; ///< Do not reserve swap memory for the mapping
-};
-
-/// \brief Structure representing a memory-mapped region.
-struct os_mmapd {
-    void *host_memory{nullptr};      ///< Pointer to the mapped memory region
-    uint64_t length{0};              ///< The total size of the mapped memory
-    os_mmap_flags flags;             ///< Flags used for the mapping
-    uint64_t backing_sync_length{0}; ///< Length of file-backed portion for which memory sync is needed
-#ifdef HAVE_MMAP
-    int backing_fd{-1}; ///< File descriptor of the backing file
-#elif defined(_WIN32)
-    void *memory_mapping{nullptr};      ///< Handle of the memory mapping
-    void *backing_host_memory{nullptr}; ///< Pointer to the backing file mapped memory region
-    void *backing_mapping{nullptr};     ///< Handle of the backing file mapping
-    void *backing_fh{nullptr};          ///< Handle of the backing file
-#else
-    FILE *backing_fp{nullptr};            ///< Pointer of the backing file
-    void *unaligned_host_memory{nullptr}; ///< Pointer to the memory that we can deallocate with std::free()
-#endif
-};
-
-/// \brief Retrieves the system's memory page size.
-/// \details Typically 4KB, but may vary (e.g., 8KB on Solaris, 16KB on macOS arm64).
-uint64_t os_get_mmap_page_size();
-
-/// \brief Maps a memory region, optionally backed by a file.
-/// \param length Total memory length to map.
-/// \param flags Flags for the mapping.
-/// \param backing_filename Path to the file to back the memory mapping.
-/// \param backing_length The expected size of the backing file in bytes (must be <= length).
-/// \returns Structure containing the memory mapping information.
-/// \details The memory is guaranteed to be aligned to 4096-byte boundaries.
-/// Memory above backing file length are zereod, and modifications to that region are not written out to the file.
-os_mmapd os_mmap(uint64_t length, const os_mmap_flags &flags = {}, const std::string &backing_filename = {},
-    uint64_t backing_length = 0);
-
-/// \brief Unmaps a previously mapped memory region.
-void os_munmap(const os_mmapd &mmapd) noexcept;
-
-namespace detail {
-
-struct mmap_deleter {
-    os_mmapd m_mmapd;
-    explicit mmap_deleter(os_mmapd mmapd) : m_mmapd(mmapd) {}
-    template <typename T>
-    void operator()(T * /*ptr*/) const noexcept {
-        os_munmap(m_mmapd);
-    }
-};
-
-} // namespace detail
-
-template <typename T>
-using unique_mmap_ptr = std::unique_ptr<T, detail::mmap_deleter>;
-
-template <typename T>
-static inline auto make_unique_mmap(size_t nmemb, const os_mmap_flags &flags = {},
-    const std::string &backing_filename = {}, uint64_t backing_length = 0) {
-    const size_t size = nmemb * sizeof(T);
-    const os_mmapd mmapd = os_mmap(size, flags, backing_filename, backing_length); // os_map throws on error
-    T *ptr = static_cast<T *>(mmapd.host_memory);
-    return unique_mmap_ptr<T>(ptr, detail::mmap_deleter{mmapd});
-}
-
-} // namespace cartesi
-
-#endif
diff --git a/src/page-hash-tree-cache.h b/src/page-hash-tree-cache.h
index 35540b22f..182715144 100644
--- a/src/page-hash-tree-cache.h
+++ b/src/page-hash-tree-cache.h
@@ -46,7 +46,7 @@
 #include "i-hasher.h"
 #include "is-pristine.h"
 #include "machine-hash.h"
-#include "os-mmap.h"
+#include "os-mapped-memory.h"
 #include "page-hash-tree-cache-stats.h"
 #include "ranges.h"
 #include "signposts.h"
@@ -418,9 +418,9 @@ class page_hash_tree_cache {
         m_spid_pristine_update{os_signpost_id_generate(m_log)},
         m_spid_non_pristine_update{os_signpost_id_generate(m_log)},
 #endif
-        m_mapped_memory{make_unique_mmap<unsigned char>(sizeof(lru) + (num_entries * sizeof(entry)))},
-        m_lru{*new(m_mapped_memory.get()) lru},
-        m_entries{new(m_mapped_memory.get() + sizeof(lru)) entry[num_entries], num_entries},
+        m_mapped_memory{sizeof(lru) + (num_entries * sizeof(entry))},
+        m_lru{*new(m_mapped_memory.get_ptr()) lru},
+        m_entries{new(m_mapped_memory.get_ptr() + sizeof(lru)) entry[num_entries], num_entries},
         m_pristine_page_hash_tree{entry::get_pristine_page_hash_tree(std::forward<H>(h))} {
         if (num_entries == 0) {
             throw std::invalid_argument{"page hash-tree cache must have at least one entry"};
@@ -610,7 +610,7 @@ class page_hash_tree_cache {
     os_signpost_id_t m_spid_non_pristine_update;
 #endif
 
-    unique_mmap_ptr<unsigned char> m_mapped_memory; ///< Mapped memory containing the LRU and entries
+    os::mapped_memory m_mapped_memory; ///< Mapped memory containing the LRU and entries
 
     // The following fields may already be initialized by existing mapped memory
     lru &m_lru;                 ///< Recently used entries
diff --git a/src/processor-state.h b/src/processor-state.h
index 95cd1e282..49042da26 100644
--- a/src/processor-state.h
+++ b/src/processor-state.h
@@ -61,7 +61,7 @@ static_assert(sizeof(shadow_state) == AR_SHADOW_STATE_LENGTH, "unexpected shadow
 
 // The size of the shadow state should align with the largest page size used by the supported operating systems.
 // For instance, macOS on arm64 currently utilizes a page size of 16KB.
-// Doing this ensures that memory allocations made with os_mmap()
+// Doing this ensures that memory allocations made with os::mapped_memory()
 // result in the backing shadow file occupying whole pages, avoiding partial page mappings.
 static_assert(sizeof(shadow_state) % 16384 == 0, "shadow state size must be multiple of a 16KB");
 

From 0e624108d7c6a19775373471ecb8e9fb2774b87a Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Tue, 7 Oct 2025 15:40:44 -0300
Subject: [PATCH 75/82] fix: don't leave zombies processes on lua tests

---
 tests/lua/cartesi-machine-tests.lua | 4 ++--
 tests/lua/cmio-test.lua             | 4 ++--
 tests/lua/machine-bind.lua          | 4 ++--
 tests/lua/machine-test.lua          | 4 ++--
 4 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/tests/lua/cartesi-machine-tests.lua b/tests/lua/cartesi-machine-tests.lua
index 95baf0318..77d11bf1a 100755
--- a/tests/lua/cartesi-machine-tests.lua
+++ b/tests/lua/cartesi-machine-tests.lua
@@ -622,9 +622,9 @@ local function build_machine(ram_image)
     }
     if remote_address then
         local jsonrpc_machine <close> = assert(jsonrpc.connect_server(remote_address))
-        return assert(jsonrpc_machine(config, runtime):set_cleanup_call(jsonrpc.SHUTDOWN))
+        return jsonrpc_machine:fork_server():set_cleanup_call(jsonrpc.SHUTDOWN):create(config, runtime)
     end
-    return assert(cartesi.machine(config, runtime))
+    return cartesi.machine(config, runtime)
 end
 
 local function print_machine(test_name, expected_cycles)
diff --git a/tests/lua/cmio-test.lua b/tests/lua/cmio-test.lua
index 088860f5a..c6effd475 100755
--- a/tests/lua/cmio-test.lua
+++ b/tests/lua/cmio-test.lua
@@ -118,9 +118,9 @@ local function load_machine(name)
     }
     if machine_type ~= "local" then
         local jsonrpc_machine <close> = assert(jsonrpc.connect_server(remote_address))
-        return assert(jsonrpc_machine(MACHINES_DIR .. name, runtime):set_cleanup_call(jsonrpc.SHUTDOWN))
+        return jsonrpc_machine:fork_server():set_cleanup_call(jsonrpc.SHUTDOWN):load(MACHINES_DIR .. name, runtime)
     else
-        return assert(cartesi.machine(MACHINES_DIR .. name, runtime))
+        return cartesi.machine(MACHINES_DIR .. name, runtime)
     end
 end
 
diff --git a/tests/lua/machine-bind.lua b/tests/lua/machine-bind.lua
index be8afc5c9..fbc48f616 100755
--- a/tests/lua/machine-bind.lua
+++ b/tests/lua/machine-bind.lua
@@ -250,9 +250,9 @@ local function build_machine(type, config_options)
     local new_machine
     if type ~= "local" then
         local jsonrpc_machine <close> = assert(jsonrpc.connect_server(remote_address))
-        new_machine = assert(jsonrpc_machine(config, runtime):set_cleanup_call(jsonrpc.SHUTDOWN))
+        new_machine = jsonrpc_machine:fork_server():set_cleanup_call(jsonrpc.SHUTDOWN):create(config, runtime)
     else
-        new_machine = assert(cartesi.machine(config, runtime))
+        new_machine = cartesi.machine(config, runtime)
     end
     if config.uarch.ram and config.uarch.ram.backing_store and config.uarch.ram.backing_store.data_filename then
         os.remove(config.uarch.ram.backing_store.data_filename)
diff --git a/tests/lua/machine-test.lua b/tests/lua/machine-test.lua
index ebb810a1b..1f31b9302 100755
--- a/tests/lua/machine-test.lua
+++ b/tests/lua/machine-test.lua
@@ -138,9 +138,9 @@ local function build_machine(type, config, runtime_config)
     }
     if type ~= "local" then
         local jsonrpc_machine <close> = assert(jsonrpc.connect_server(remote_address))
-        return assert(jsonrpc_machine(config, runtime_config):set_cleanup_call(jsonrpc.SHUTDOWN))
+        return jsonrpc_machine:fork_server():set_cleanup_call(jsonrpc.SHUTDOWN):create(config, runtime_config)
     else
-        return assert(cartesi.machine(config, runtime_config))
+        return cartesi.machine(config, runtime_config)
     end
 end
 

From 70ea7de7375aa1e797d829da66051bfc1421e69a Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Sat, 4 Oct 2025 18:05:42 -0300
Subject: [PATCH 76/82] refactor: make memory class non movable/copyable

---
 src/address-range.h            | 11 -----
 src/clint-address-range.h      |  5 ---
 src/dense-hash-tree.h          |  7 ++++
 src/dirty-page-tree.h          |  9 ++++
 src/htif-address-range.h       |  5 ---
 src/machine-address-ranges.cpp | 75 +++++++++++++++++++---------------
 src/machine-address-ranges.h   |  6 +--
 src/machine.cpp                |  2 +-
 src/memory-address-range.h     |  9 ++--
 src/mock-address-range.h       | 14 +++----
 src/os-mapped-memory.cpp       | 20 ---------
 src/os-mapped-memory.h         |  8 +---
 src/plic-address-range.h       |  5 ---
 src/unique-c-ptr.h             |  8 ----
 14 files changed, 75 insertions(+), 109 deletions(-)

diff --git a/src/address-range.h b/src/address-range.h
index 3d3912acc..b6c82cec7 100644
--- a/src/address-range.h
+++ b/src/address-range.h
@@ -389,17 +389,6 @@ class address_range {
 #endif
 };
 
-template <size_t N>
-constexpr static auto make_empty_address_range(const char (&description)[N]) {
-    return address_range{description};
-}
-
-template <typename ABRT>
-static inline auto make_address_range(const char *description, uint64_t start, uint64_t length, pmas_flags f,
-    ABRT abrt) {
-    return address_range{description, start, length, f, abrt};
-}
-
 } // namespace cartesi
 
 #endif // ADDRESS_RANGE_H
diff --git a/src/clint-address-range.h b/src/clint-address-range.h
index ed12edd5b..6eb32bf16 100644
--- a/src/clint-address-range.h
+++ b/src/clint-address-range.h
@@ -64,11 +64,6 @@ class clint_address_range final : public address_range {
         uint64_t val) noexcept override;
 };
 
-template <typename ABRT>
-static inline clint_address_range make_clint_address_range(ABRT abrt) {
-    return clint_address_range{abrt};
-}
-
 } // namespace cartesi
 
 #endif
diff --git a/src/dense-hash-tree.h b/src/dense-hash-tree.h
index ba7bace5d..722fb2d4e 100644
--- a/src/dense-hash-tree.h
+++ b/src/dense-hash-tree.h
@@ -61,6 +61,13 @@ class dense_hash_tree final : public i_dense_hash_tree {
         m_level_count{check_level_count(level_count, leaf_count)},
         m_storage{size_type{1} << level_count} {}
 
+    dense_hash_tree(const dense_hash_tree &) = delete;
+    dense_hash_tree &operator=(const dense_hash_tree &) = delete;
+    dense_hash_tree(dense_hash_tree &&) = delete;
+    dense_hash_tree &operator=(dense_hash_tree &&) = delete;
+
+    ~dense_hash_tree() override = default;
+
     machine_hash_view do_node_hash_view(uint64_t offset, int log2_size) noexcept override {
         if (auto index = to_index(offset, log2_size); index != invalid_index) {
             return machine_hash_view{m_storage[index]};
diff --git a/src/dirty-page-tree.h b/src/dirty-page-tree.h
index 10bfd23f0..52a992652 100644
--- a/src/dirty-page-tree.h
+++ b/src/dirty-page-tree.h
@@ -109,6 +109,15 @@ class dirty_page_tree final : public i_dirty_page_tree {
         build_from_leaves();
     }
 
+    // No copy or move constructors or assignments
+    dirty_page_tree(const dirty_page_tree &) = delete;
+    dirty_page_tree &operator=(const dirty_page_tree &) = delete;
+    dirty_page_tree(dirty_page_tree &&) = delete;
+    dirty_page_tree &operator=(dirty_page_tree &&) = delete;
+
+    /// \brief Destructor
+    ~dirty_page_tree() override = default;
+
     // Dump tree in DOT format
     void dump() const {
         std::cout << "digraph HashTree {\n";
diff --git a/src/htif-address-range.h b/src/htif-address-range.h
index 72a503f11..8146084e2 100644
--- a/src/htif-address-range.h
+++ b/src/htif-address-range.h
@@ -64,11 +64,6 @@ class htif_address_range final : public address_range {
         uint64_t val) noexcept override;
 };
 
-template <typename ABRT>
-static inline htif_address_range make_htif_address_range(ABRT abrt) {
-    return htif_address_range{abrt};
-}
-
 } // namespace cartesi
 
 #endif
diff --git a/src/machine-address-ranges.cpp b/src/machine-address-ranges.cpp
index 183883019..495578dbd 100644
--- a/src/machine-address-ranges.cpp
+++ b/src/machine-address-ranges.cpp
@@ -25,6 +25,7 @@
 #include <cstdio>
 #include <cstring>
 #include <iterator>
+#include <memory>
 #include <ranges>
 #include <stdexcept>
 #include <string>
@@ -47,7 +48,6 @@
 #include "scope-remove.h"
 #include "uarch-pristine.h"
 #include "uarch-processor-state.h"
-#include "unique-c-ptr.h"
 #include "virtio-address-range.h"
 #include "virtio-console-address-range.h"
 #include "virtio-net-tuntap-address-range.h"
@@ -71,8 +71,8 @@ static inline auto make_pmas_address_range(const pmas_config &config) {
         .IW = false,
         .DID = PMA_ISTART_DID::memory,
     };
-    return memory_address_range{"PMAs"s, AR_PMAS_START, AR_PMAS_LENGTH, flags, config.backing_store,
-        memory_address_range_config{.host_read_only = true}};
+    return std::make_unique<memory_address_range>("PMAs"s, AR_PMAS_START, AR_PMAS_LENGTH, flags, config.backing_store,
+        memory_address_range_config{.host_read_only = true});
 }
 
 static inline auto make_dtb_address_range(const dtb_config &config) {
@@ -88,7 +88,7 @@ static inline auto make_dtb_address_range(const dtb_config &config) {
         .IW = true,
         .DID = PMA_ISTART_DID::memory,
     };
-    return memory_address_range{"DTB"s, AR_DTB_START, AR_DTB_LENGTH, dtb_flags, config.backing_store};
+    return std::make_unique<memory_address_range>("DTB"s, AR_DTB_START, AR_DTB_LENGTH, dtb_flags, config.backing_store);
 }
 
 static inline auto make_shadow_state_address_range(const processor_config &config) {
@@ -103,8 +103,8 @@ static inline auto make_shadow_state_address_range(const processor_config &confi
         .DID = PMA_ISTART_DID::shadow_state,
     };
     static constexpr memory_address_range_config shadow_state_config{.host_length = sizeof(processor_state)};
-    return memory_address_range("shadow state", AR_SHADOW_STATE_START, AR_SHADOW_STATE_LENGTH, shadow_state_flags,
-        config.backing_store, shadow_state_config);
+    return std::make_unique<memory_address_range>("shadow state", AR_SHADOW_STATE_START, AR_SHADOW_STATE_LENGTH,
+        shadow_state_flags, config.backing_store, shadow_state_config);
 }
 
 static inline auto make_shadow_uarch_state_address_range(const uarch_processor_config &config) {
@@ -120,8 +120,8 @@ static inline auto make_shadow_uarch_state_address_range(const uarch_processor_c
     };
     static constexpr memory_address_range_config shadow_uarch_state_config{
         .host_length = sizeof(uarch_processor_state)};
-    return memory_address_range{"shadow uarch state", AR_SHADOW_UARCH_STATE_START, AR_SHADOW_UARCH_STATE_LENGTH,
-        shadow_uarch_state_flags, config.backing_store, shadow_uarch_state_config};
+    return std::make_unique<memory_address_range>("shadow uarch state", AR_SHADOW_UARCH_STATE_START,
+        AR_SHADOW_UARCH_STATE_LENGTH, shadow_uarch_state_flags, config.backing_store, shadow_uarch_state_config);
 }
 
 void machine_address_ranges::mark_always_dirty_pages() {
@@ -132,14 +132,13 @@ void machine_address_ranges::mark_always_dirty_pages() {
 }
 
 template <typename AR>
-    requires std::is_rvalue_reference_v<AR &&> && std::derived_from<AR, address_range>
-AR &machine_address_ranges::push_back(AR &&ar, register_where where) {
-    check(ar, where);                                   // Check if we can register it
-    auto ptr = make_moved_unique(std::forward<AR>(ar)); // Move object to heap, now owned by ptr
-    AR &ar_ref = *ptr;                                  // Get reference to object, already in heap, to return later
-    const auto index = m_all.size();                    // Get index the new address range will occupy
-    m_all.push_back(std::move(ptr));                    // Move ptr to list of address ranges
-    if (where.pmas) {                                   // Register as a PMA
+    requires std::derived_from<AR, address_range>
+AR &machine_address_ranges::push_back(std::unique_ptr<AR> &&ar_ptr, register_where where) {
+    AR &ar_ref = *ar_ptr;               // Get reference to object, already in heap, to return later
+    check(ar_ref, where);               // Check if we can register it
+    const auto index = m_all.size();    // Get index the new address range will occupy
+    m_all.push_back(std::move(ar_ptr)); // Move ptr to list of address ranges
+    if (where.pmas) {                   // Register as a PMA
         m_pmas.push_back(index);
     }
     if (where.hash_tree) { // Register with the hash tree
@@ -248,9 +247,12 @@ machine_address_ranges::machine_address_ranges(const machine_config &config,
     push_back(make_dtb_address_range(c.dtb), register_where{.hash_tree = true, .pmas = true});
     push_back_flash_drives(c.flash_drive, runtime_config);
     push_back_cmio(c.cmio);
-    push_back(make_htif_address_range(throw_invalid_argument), register_where{.hash_tree = false, .pmas = true});
-    push_back(make_clint_address_range(throw_invalid_argument), register_where{.hash_tree = false, .pmas = true});
-    push_back(make_plic_address_range(throw_invalid_argument), register_where{.hash_tree = false, .pmas = true});
+    push_back(std::make_unique<htif_address_range>(throw_invalid_argument),
+        register_where{.hash_tree = false, .pmas = true});
+    push_back(std::make_unique<clint_address_range>(throw_invalid_argument),
+        register_where{.hash_tree = false, .pmas = true});
+    push_back(std::make_unique<plic_address_range>(throw_invalid_argument),
+        register_where{.hash_tree = false, .pmas = true});
     push_back(make_pmas_address_range(c.pmas), register_where{.hash_tree = true, .pmas = true});
     push_back_virtio(c.virtio, c.processor.registers.iunrep);
 
@@ -283,8 +285,8 @@ void machine_address_ranges::push_back_uarch_ram(const uarch_ram_config &uram) {
         .DID = PMA_ISTART_DID::memory,
     };
     constexpr auto ram_description = "uarch RAM";
-    auto &ar = push_back(
-        memory_address_range{ram_description, AR_UARCH_RAM_START, AR_UARCH_RAM_LENGTH, uram_flags, uram.backing_store},
+    auto &ar = push_back(std::make_unique<memory_address_range>(ram_description, AR_UARCH_RAM_START,
+                             AR_UARCH_RAM_LENGTH, uram_flags, uram.backing_store),
         register_where{.hash_tree = true, .pmas = false});
     // Initialize uarch RAM
     if (uram.backing_store.newly_created()) {
@@ -330,7 +332,7 @@ void machine_address_ranges::push_back_ram(const ram_config &ram) {
     if (ram.length == 0) {
         throw std::invalid_argument("RAM length cannot be zero");
     }
-    push_back(memory_address_range{"RAM"s, AR_RAM_START, ram.length, ram_flags, ram.backing_store},
+    push_back(std::make_unique<memory_address_range>("RAM"s, AR_RAM_START, ram.length, ram_flags, ram.backing_store),
         register_where{.hash_tree = true, .pmas = true});
 }
 
@@ -354,8 +356,9 @@ void machine_address_ranges::push_back_flash_drives(const flash_drive_configs &f
             .IW = !f.read_only,
             .DID = PMA_ISTART_DID::flash_drive,
         };
-        push_back(memory_address_range{flash_description, f.start, f.length, flash_flags, f.backing_store,
-                      memory_address_range_config{.host_read_only = f.read_only, .host_no_reserve = r.no_reserve}},
+        push_back(std::make_unique<memory_address_range>(flash_description, f.start, f.length, flash_flags,
+                      f.backing_store,
+                      memory_address_range_config{.host_read_only = f.read_only, .host_no_reserve = r.no_reserve}),
             register_where{.hash_tree = true, .pmas = true});
         i++;
     }
@@ -378,12 +381,13 @@ void machine_address_ranges::push_back_virtio(const virtio_configs &virtio, uint
         const auto visitor = overloads{
             [this, virtio_idx, where](const virtio_console_config &) {
                 const auto start = AR_FIRST_VIRTIO_START + (virtio_idx * AR_VIRTIO_LENGTH);
-                push_back(make_virtio_console_address_range(start, AR_VIRTIO_LENGTH, virtio_idx), where);
+                push_back(std::make_unique<virtio_console_address_range>(start, AR_VIRTIO_LENGTH, virtio_idx), where);
             },
             [this, virtio_idx, where](const virtio_p9fs_config &c) {
 #ifdef HAVE_POSIX_FS
                 const auto start = AR_FIRST_VIRTIO_START + (virtio_idx * AR_VIRTIO_LENGTH);
-                push_back(make_virtio_p9fs_address_range(start, AR_VIRTIO_LENGTH, virtio_idx, c.tag, c.host_directory),
+                push_back(std::make_unique<virtio_p9fs_address_range>(start, AR_VIRTIO_LENGTH, virtio_idx, c.tag,
+                              c.host_directory),
                     where);
 #else
                 (void) c;
@@ -396,7 +400,9 @@ void machine_address_ranges::push_back_virtio(const virtio_configs &virtio, uint
             [this, virtio_idx, where](const virtio_net_tuntap_config &c) {
 #ifdef HAVE_TUNTAP
                 const auto start = AR_FIRST_VIRTIO_START + (virtio_idx * AR_VIRTIO_LENGTH);
-                push_back(make_virtio_net_tuntap_address_range(start, AR_VIRTIO_LENGTH, virtio_idx, c.iface), where);
+                push_back(
+                    std::make_unique<virtio_net_tuntap_address_range>(start, AR_VIRTIO_LENGTH, virtio_idx, c.iface),
+                    where);
 #else
                 (void) c;
                 (void) this;
@@ -411,7 +417,8 @@ void machine_address_ranges::push_back_virtio(const virtio_configs &virtio, uint
                     throw std::invalid_argument("too many virtio network user host-forwarding ports");
                 }
                 const auto start = AR_FIRST_VIRTIO_START + (virtio_idx * AR_VIRTIO_LENGTH);
-                push_back(make_virtio_net_user_address_range(start, AR_VIRTIO_LENGTH, virtio_idx, c), where);
+                push_back(std::make_unique<virtio_net_user_address_range>(start, AR_VIRTIO_LENGTH, virtio_idx, c),
+                    where);
 #else
                 (void) c;
                 (void) this;
@@ -447,11 +454,11 @@ void machine_address_ranges::push_back_cmio(const cmio_config &c) {
         .IW = true,
         .DID = PMA_ISTART_DID::cmio_rx_buffer,
     };
-    push_back(memory_address_range{"CMIO tx buffer"s, AR_CMIO_TX_BUFFER_START, AR_CMIO_TX_BUFFER_LENGTH, tx_flags,
-                  c.tx_buffer.backing_store},
+    push_back(std::make_unique<memory_address_range>("CMIO tx buffer"s, AR_CMIO_TX_BUFFER_START,
+                  AR_CMIO_TX_BUFFER_LENGTH, tx_flags, c.tx_buffer.backing_store),
         register_where{.hash_tree = true, .pmas = true});
-    push_back(memory_address_range{"CMIO rx buffer"s, AR_CMIO_RX_BUFFER_START, AR_CMIO_RX_BUFFER_LENGTH, rx_flags,
-                  c.rx_buffer.backing_store},
+    push_back(std::make_unique<memory_address_range>("CMIO rx buffer"s, AR_CMIO_RX_BUFFER_START,
+                  AR_CMIO_RX_BUFFER_LENGTH, rx_flags, c.rx_buffer.backing_store),
         register_where{.hash_tree = true, .pmas = true});
 }
 
@@ -473,8 +480,8 @@ void machine_address_ranges::replace(const memory_range_config &config) {
             }
             // Replace range, preserving original flags.
             // This will automatically start with all pages dirty.
-            ar = make_moved_unique(memory_address_range{ar->get_description(), ar->get_start(), ar->get_length(),
-                ar->get_flags(), config.backing_store});
+            ar = std::make_unique<memory_address_range>(ar->get_description(), ar->get_start(), ar->get_length(),
+                ar->get_flags(), config.backing_store);
             return;
         }
     }
diff --git a/src/machine-address-ranges.h b/src/machine-address-ranges.h
index 100425fcf..8a7fa5bf9 100644
--- a/src/machine-address-ranges.h
+++ b/src/machine-address-ranges.h
@@ -49,7 +49,7 @@ class machine_address_ranges {
     address_range_descriptions m_descrs;               ///< Address range descriptions for users
     int m_shadow_state_index;                          ///< Index of shadow state address range
     int m_shadow_uarch_state_index;                    ///< Index of shadow uarch state address range
-    address_range m_sentinel{make_empty_address_range("sentinel")};
+    address_range m_sentinel{"sentinel"};
 
 public:
     /// \brief Constructor
@@ -190,8 +190,8 @@ class machine_address_ranges {
     /// The \p where parameter tells whether to register the address range with the hash tree and/or as a PMA.
     /// Finally, the "virtio" subset lists every VirtIO address range that has been registered.
     template <typename AR>
-        requires std::is_rvalue_reference_v<AR &&> && std::derived_from<AR, address_range>
-    AR &push_back(AR &&ar, register_where where);
+        requires std::derived_from<AR, address_range>
+    AR &push_back(std::unique_ptr<AR> &&ar_ptr, register_where where);
 
     /// \brief Adds uarch RAM address range
     /// \param c uarch RAM configuration
diff --git a/src/machine.cpp b/src/machine.cpp
index 89f58ec15..2d35d7cae 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -2327,7 +2327,7 @@ uarch_cycle_root_hashes machine::collect_uarch_cycle_root_hashes(uint64_t mcycle
             break;
         }
 
-        // If the machine halted, yielded manuallly or reached mcycle UINT64_MAX,
+        // If the machine halted, yielded manually or reached mcycle UINT64_MAX,
         // then we are at a fixed point and should always attempt to advance one more mcycle
         at_fixed_point = result.break_reason == interpreter_break_reason::halted ||
             result.break_reason == interpreter_break_reason::yielded_manually || mcycle_reached == UINT64_MAX;
diff --git a/src/memory-address-range.h b/src/memory-address-range.h
index 2d106c4b3..c968cfebf 100644
--- a/src/memory-address-range.h
+++ b/src/memory-address-range.h
@@ -71,12 +71,13 @@ class memory_address_range final : public address_range {
     memory_address_range(const std::string &description, uint64_t start, uint64_t length, const pmas_flags &flags,
         const backing_store_config &backing_store = {}, const memory_address_range_config &memory_config = {});
 
+    ~memory_address_range() override = default;
+
+    // No copy or move constructors or assignments
     memory_address_range(const memory_address_range &) = delete;
+    memory_address_range(memory_address_range &&) = delete;
     memory_address_range &operator=(const memory_address_range &) = delete;
-    memory_address_range &operator=(memory_address_range &&) noexcept = delete;
-
-    ~memory_address_range() override = default;
-    memory_address_range(memory_address_range &&) noexcept = default;
+    memory_address_range &operator=(memory_address_range &&) = delete;
 
 private:
     unsigned char *do_get_host_memory() noexcept override {
diff --git a/src/mock-address-range.h b/src/mock-address-range.h
index ae6ab4ebc..be746bc38 100644
--- a/src/mock-address-range.h
+++ b/src/mock-address-range.h
@@ -56,19 +56,19 @@ static inline mock_address_range make_mock_address_range(uint64_t istart, uint64
     uint64_t start{};
     auto flags = pmas_unpack_istart(istart, start);
     if (flags.M) {
-        return check_mock_address_range(make_address_range(pmas_get_DID_name(flags.DID), start, ilength, flags, abrt),
-            start, ilength, flags, abrt);
+        return check_mock_address_range(address_range{pmas_get_DID_name(flags.DID), start, ilength, flags, abrt}, start,
+            ilength, flags, abrt);
     }
     if (ilength == 0) {
-        return check_mock_address_range(make_empty_address_range("empty"), start, ilength, flags, abrt);
+        return check_mock_address_range(address_range{"empty"}, start, ilength, flags, abrt);
     }
     switch (flags.DID) {
         case PMA_ISTART_DID::CLINT:
-            return check_mock_address_range(make_clint_address_range(abrt), start, ilength, flags, abrt);
+            return check_mock_address_range(clint_address_range{abrt}, start, ilength, flags, abrt);
         case PMA_ISTART_DID::PLIC:
-            return check_mock_address_range(make_plic_address_range(abrt), start, ilength, flags, abrt);
+            return check_mock_address_range(plic_address_range{abrt}, start, ilength, flags, abrt);
         case PMA_ISTART_DID::HTIF:
-            return check_mock_address_range(make_htif_address_range(abrt), start, ilength, flags, abrt);
+            return check_mock_address_range(htif_address_range{abrt}, start, ilength, flags, abrt);
         default:
             abrt("unhandled mock address range");
             __builtin_trap();
@@ -90,7 +90,7 @@ address_range &get_mock_address_range(mock_address_range &mock, ABRT abrt) {
         case 4:
             return std::get<4>(mock);
         default: {
-            static auto unhandled = make_empty_address_range("unhandled mock address range");
+            static auto unhandled = address_range{"unhandled mock address range"};
             abrt("unhandled mock address range");
             __builtin_trap();
             return unhandled;
diff --git a/src/os-mapped-memory.cpp b/src/os-mapped-memory.cpp
index 1654ab790..f8da41419 100644
--- a/src/os-mapped-memory.cpp
+++ b/src/os-mapped-memory.cpp
@@ -485,26 +485,6 @@ mapped_memory::mapped_memory(uint64_t length, const mapped_memory_flags &flags,
 #endif // HAVE_MMAP
 }
 
-mapped_memory::mapped_memory(mapped_memory &&other) noexcept : mapped_memory() {
-    std::swap(m_host_memory, other.m_host_memory);
-    std::swap(m_length, other.m_length);
-    std::swap(m_backing_filename, other.m_backing_filename);
-    std::swap(m_backing_length, other.m_backing_length);
-    std::swap(m_backing_sync_length, other.m_backing_sync_length);
-    std::swap(m_flags, other.m_flags);
-#ifdef HAVE_MMAP
-    std::swap(m_backing_fd, other.m_backing_fd);
-#elif defined(_WIN32)
-    std::swap(m_memory_mapping, other.m_memory_mapping);
-    std::swap(m_backing_host_memory, other.m_backing_host_memory);
-    std::swap(m_backing_mapping, other.m_backing_mapping);
-    std::swap(m_backing_fh, other.m_backing_fh);
-#else
-    std::swap(m_backing_fp, other.m_backing_fp);
-    std::swap(m_unaligned_host_memory, other.m_unaligned_host_memory);
-#endif
-}
-
 mapped_memory::~mapped_memory() noexcept {
 #ifdef HAVE_MMAP
     if (m_host_memory != nullptr && m_length > 0) {
diff --git a/src/os-mapped-memory.h b/src/os-mapped-memory.h
index c87d54580..efbf62293 100644
--- a/src/os-mapped-memory.h
+++ b/src/os-mapped-memory.h
@@ -89,17 +89,13 @@ class mapped_memory final {
     explicit mapped_memory(uint64_t length, const mapped_memory_flags &flags = {},
         const std::string &backing_filename = {}, std::optional<uint64_t> backing_length = {});
 
-    /// \brief Move constructor.
-    mapped_memory(mapped_memory &&other) noexcept;
-
     /// \brief Destructor.
     ~mapped_memory() noexcept;
 
-    // No copy constructor or copy assignment
+    // No copy or move constructors or assignments
     mapped_memory(const mapped_memory &other) = delete;
     mapped_memory &operator=(const mapped_memory &other) = delete;
-
-    // No move assignment
+    mapped_memory(mapped_memory &&other) noexcept = delete;
     mapped_memory &operator=(mapped_memory &&other) noexcept = delete;
 
     /// \brief Returns a pointer to the mapped memory region.
diff --git a/src/plic-address-range.h b/src/plic-address-range.h
index 6f4794599..2d3a98489 100644
--- a/src/plic-address-range.h
+++ b/src/plic-address-range.h
@@ -72,11 +72,6 @@ class plic_address_range final : public address_range {
         uint64_t val) noexcept override;
 };
 
-template <typename ABRT>
-static inline plic_address_range make_plic_address_range(ABRT abrt) {
-    return plic_address_range{abrt};
-}
-
 } // namespace cartesi
 
 #endif
diff --git a/src/unique-c-ptr.h b/src/unique-c-ptr.h
index e9866136a..9d1675d7a 100644
--- a/src/unique-c-ptr.h
+++ b/src/unique-c-ptr.h
@@ -24,7 +24,6 @@
 #include <new>
 #include <system_error>
 #include <tuple>
-#include <type_traits>
 
 namespace cartesi {
 
@@ -82,13 +81,6 @@ static inline auto make_unique_fopen(const char *pathname, const char *mode, con
     return unique_file_ptr{fopen(pathname, mode)};
 }
 
-template <typename T>
-static auto inline make_moved_unique(T &&t)
-    requires std::is_rvalue_reference_v<T &&>
-{
-    return std::make_unique<T>(std::forward<T>(t));
-}
-
 } // namespace cartesi
 
 #endif

From df64dbda13126d3c3b9de502652237a25c00e8d8 Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Mon, 6 Oct 2025 16:27:51 -0300
Subject: [PATCH 77/82] feat: persist hash tree state to disk

---
 src/cartesi-machine.lua        |  19 ++++
 src/dense-hash-tree.h          |  36 ++++---
 src/dirty-page-tree.h          |  84 +++++++++------
 src/hash-tree.cpp              |  90 ++++++++++++++---
 src/hash-tree.h                |  30 ++++--
 src/i-dense-hash-tree.h        |   8 ++
 src/i-dirty-page-tree.h        |  27 +++++
 src/json-util.cpp              |   5 +-
 src/jsonrpc-discover.json      |   3 -
 src/machine-address-ranges.cpp | 131 ++++++++++++++++--------
 src/machine-config.cpp         |  41 +++++---
 src/machine-config.h           |  15 ++-
 src/machine.cpp                | 180 +++++++++++++++++++++------------
 src/machine.h                  |   4 +-
 src/memory-address-range.cpp   |   9 +-
 src/memory-address-range.h     |  12 ++-
 src/os-mapped-memory.cpp       |  39 ++++---
 src/os-mapped-memory.h         |  33 ++----
 src/page-hash-tree-cache.h     |  88 ++++++++++++++--
 19 files changed, 600 insertions(+), 254 deletions(-)

diff --git a/src/cartesi-machine.lua b/src/cartesi-machine.lua
index 3764a9dbd..b5914f58f 100755
--- a/src/cartesi-machine.lua
+++ b/src/cartesi-machine.lua
@@ -106,6 +106,7 @@ where options are:
         length:<number>
         data_filename:<filename>
         dht_filename:<filename>
+        dpt_filename:<filename>
         shared
         create
         truncate
@@ -138,6 +139,10 @@ where options are:
         range for the drive, down to one hash per page.)
         when omitted or set to the empty, the hash tree will be built from scratch.
 
+        dpt_filename (optional)
+        gives the name of the file containing the dirty page tree for the flash drive.
+        when omitted or set to the empty, the dirty page tree will be built from scratch.
+
         shared (optional)
         target modifications to flash drive modify the memory and hash tree files.
         by default, image files are not modified and changes are lost.
@@ -185,6 +190,7 @@ where options are:
         length:<number>
         data_filename:<filename>
         dht_filename:<filename>
+        dpt_filename:<filename>
         shared
 
     semantics are the same as for the --flash-drive option with the following
@@ -204,6 +210,7 @@ where options are:
     <key>:<value> is one of
         data_filename:<filename>
         dht_filename:<filename>
+        dpt_filename:<filename>
         shared
         create
         truncate
@@ -667,6 +674,7 @@ local default_config = cartesi.machine:get_default_config()
 local images_path = adjust_images_path(os.getenv("CARTESI_IMAGES_PATH"))
 local flash_data_filename = { root = images_path .. "rootfs.ext2" }
 local flash_dht_filename = {}
+local flash_dpt_filename = {}
 local flash_label_order = { "root" }
 local flash_shared = {}
 local flash_create = {}
@@ -689,6 +697,7 @@ local ram = {
     backing_store = {
         data_filename = images_path .. "linux.bin",
         dht_filename = "",
+        dpt_filename = "",
     },
 }
 local init_splash = true
@@ -722,12 +731,14 @@ local uarch = {
         backing_store = {
             data_filename = "",
             dht_filename = "",
+            dpt_filename = "",
         },
     },
     ram = {
         backing_store = {
             data_filename = "",
             dht_filename = "",
+            dpt_filename = "",
         },
     },
 }
@@ -774,6 +785,7 @@ local function parse_memory_range(opts, all)
     local f = util.parse_options(opts, all, {
         data_filename = "string",
         dht_filename = "string",
+        dpt_filename = "string",
         shared = "boolean",
         create = "boolean",
         truncate = "boolean",
@@ -783,12 +795,14 @@ local function parse_memory_range(opts, all)
     f.backing_store = {
         data_filename = f.data_filename or "",
         dht_filename = f.dht_filename or "",
+        dpt_filename = f.dpt_filename or "",
         shared = f.shared,
         create = f.create,
         truncate = f.truncate,
     }
     f.data_filename = nil
     f.dht_filename = nil
+    f.dpt_filename = nil
     f.shared = nil
     f.create = nil
     f.truncate = nil
@@ -799,6 +813,7 @@ local function parse_backing_store(opts, all, def)
     local f = util.parse_options(opts, all, {
         data_filename = "string",
         dht_filename = "string",
+        dpt_filename = "string",
         shared = "boolean",
         create = "boolean",
         truncate = "boolean",
@@ -1225,6 +1240,7 @@ local options = {
                 label = "string",
                 data_filename = "string",
                 dht_filename = "string",
+                dpt_filename = "string",
                 shared = "boolean",
                 create = "boolean",
                 truncate = "boolean",
@@ -1238,6 +1254,7 @@ local options = {
             if f.label == nil then f.label = "drive" .. #flash_label_order end
             f.data_filename = f.data_filename or ""
             f.dht_filename = f.dht_filename or ""
+            f.dpt_filename = f.dpt_filename or ""
             if f.mke2fs == nil then f.mke2fs = f.data_filename == "" end
             if f.mount == nil then
                 -- mount only if there is a file backing
@@ -1258,6 +1275,7 @@ local options = {
             end
             flash_data_filename[d] = f.data_filename or flash_data_filename[d]
             flash_dht_filename[d] = f.dht_filename or flash_dht_filename[d]
+            flash_dpt_filename[d] = f.dpt_filename or flash_dpt_filename[d]
             flash_start[d] = f.start or flash_start[d]
             flash_length[d] = f.length or flash_length[d]
             flash_shared[d] = f.shared or flash_shared[d]
@@ -1965,6 +1983,7 @@ echo "
             backing_store = {
                 data_filename = flash_data_filename[label],
                 dht_filename = flash_dht_filename[label],
+                dpt_filename = flash_dpt_filename[label],
                 shared = flash_shared[label],
                 create = flash_create[label],
                 truncate = flash_truncate[label],
diff --git a/src/dense-hash-tree.h b/src/dense-hash-tree.h
index 722fb2d4e..05b98662b 100644
--- a/src/dense-hash-tree.h
+++ b/src/dense-hash-tree.h
@@ -19,19 +19,20 @@
 
 #include <cstdint>
 #include <limits>
+#include <span>
 #include <stdexcept>
-#include <vector>
 
 #include "address-range-constants.h"
 #include "hash-tree-constants.h"
 #include "i-dense-hash-tree.h"
 #include "machine-hash.h"
+#include "os-mapped-memory.h"
 
 namespace cartesi {
 
 class dense_hash_tree final : public i_dense_hash_tree {
 
-    using container_type = std::vector<machine_hash>;
+    using container_type = std::span<machine_hash>;
     using size_type = container_type::size_type;
 
     static constexpr auto invalid_index = std::numeric_limits<size_type>::max();
@@ -47,7 +48,7 @@ class dense_hash_tree final : public i_dense_hash_tree {
             throw std::invalid_argument{"too many leaves for level count"};
         }
         // Make sure we can allocate a vector of size 1 << level_count
-        if ((container_type{}.max_size() >> level_count) == 0) {
+        if ((std::numeric_limits<container_type::size_type>::max() >> level_count) == 0) {
             throw std::invalid_argument{"too many levels"};
         }
         return level_count;
@@ -57,9 +58,12 @@ class dense_hash_tree final : public i_dense_hash_tree {
     static constexpr int m_log2_word_size = HASH_TREE_LOG2_WORD_SIZE;
 
 public:
-    dense_hash_tree(int level_count, size_type leaf_count) :
+    dense_hash_tree(int level_count, size_type leaf_count, const std::string &backing_filename, bool shared) :
         m_level_count{check_level_count(level_count, leaf_count)},
-        m_storage{size_type{1} << level_count} {}
+        m_mapped_memory{get_storage_length(level_count, leaf_count), os::mapped_memory_flags{.shared = shared},
+            backing_filename},
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        m_tree{reinterpret_cast<machine_hash *>(m_mapped_memory.get_ptr()), size_type{1} << level_count} {}
 
     dense_hash_tree(const dense_hash_tree &) = delete;
     dense_hash_tree &operator=(const dense_hash_tree &) = delete;
@@ -68,28 +72,36 @@ class dense_hash_tree final : public i_dense_hash_tree {
 
     ~dense_hash_tree() override = default;
 
+    static uint64_t get_storage_length(int level_count, size_type leaf_count) {
+        return (UINT64_C(1) << check_level_count(level_count, leaf_count)) * sizeof(machine_hash);
+    }
+
+private:
     machine_hash_view do_node_hash_view(uint64_t offset, int log2_size) noexcept override {
         if (auto index = to_index(offset, log2_size); index != invalid_index) {
-            return machine_hash_view{m_storage[index]};
+            return machine_hash_view{m_tree[index]};
         }
         return no_hash_view();
     }
 
     const_machine_hash_view do_node_hash_view(uint64_t offset, int log2_size) const noexcept override {
         if (auto index = to_index(offset, log2_size); index != invalid_index) {
-            return const_machine_hash_view{m_storage[index]};
+            return const_machine_hash_view{m_tree[index]};
         }
         return no_hash_view();
     }
 
     const_machine_hash_view do_root_hash_view() const noexcept override {
         if (m_level_count != 0) {
-            return m_storage[1];
+            return m_tree[1];
         }
         return no_hash_view();
     }
 
-private:
+    std::span<const unsigned char> do_get_storage_data() const noexcept override {
+        return m_mapped_memory.get_storage_data();
+    }
+
     /// \brief Converts a node size to its level in the tree
     /// \param log2_size Log<sub>2</sub> of node size
     /// \returns Corresponding level (which may be out of range)
@@ -110,9 +122,9 @@ class dense_hash_tree final : public i_dense_hash_tree {
         return start + index;
     }
 
-    int m_level_count;
-    //??(edubart): convert to std::span over mapped memory
-    std::vector<machine_hash> m_storage;
+    int m_level_count;                 ///< Number of levels in tree
+    os::mapped_memory m_mapped_memory; ///< Mapped memory for tree storage
+    container_type m_tree;             ///< Complete tree of hashes
 };
 
 } // namespace cartesi
diff --git a/src/dirty-page-tree.h b/src/dirty-page-tree.h
index 52a992652..865eb63a8 100644
--- a/src/dirty-page-tree.h
+++ b/src/dirty-page-tree.h
@@ -28,22 +28,20 @@
 #include <ranges>
 #include <span>
 #include <stdexcept>
-#include <vector>
 
 #include "assert-printf.h"
 #include "i-dirty-page-tree.h"
+#include "os-mapped-memory.h"
 #include "ranges.h"
 
 namespace cartesi {
 
 /// \brief Dirty page tree
 class dirty_page_tree final : public i_dirty_page_tree {
-public:
     /// \brief Each node in tree is either clean or dirty
-    enum class status_type : uint8_t { clean, dirty };
+    enum class status_type : uint8_t { clean = 0, dirty = 1 };
 
-private:
-    using container_type = std::vector<status_type>;
+    using container_type = std::span<status_type>;
 
     /// \brief Checks if we can represent a tree with this many levels
     static int check_level_count(int level_count, size_type leaf_count) {
@@ -57,7 +55,7 @@ class dirty_page_tree final : public i_dirty_page_tree {
             throw std::invalid_argument{"too many leaves for level count"};
         }
         // Make sure we can allocate a vector of size 1 << level_count
-        if ((container_type{}.max_size() >> level_count) == 0) {
+        if ((std::numeric_limits<container_type::size_type>::max() >> level_count) == 0) {
             throw std::invalid_argument{"too many levels"};
         }
         // Make sure we can address position 1 << level_count
@@ -78,35 +76,43 @@ class dirty_page_tree final : public i_dirty_page_tree {
         }
     }
 
+    /// \brief Tells if the tree has been initialized
+    /// \returns True if initialized, false otherwise
+    bool is_initialized() const {
+        // Use tree position 0 as initialization flag, if it's not clean, then the tree is initialized
+        return m_tree[*position_iterator{0}] != status_type::clean;
+    }
+
+    /// \brief Marks the tree as initialized
+    void set_initialized() const {
+        // Use tree position 0 as initialization flag, marking it as dirty makes the tree initialized
+        m_tree[*position_iterator{0}] = status_type::dirty;
+    }
+
 public:
     /// \brief Constructor for leaves marked the same way
     /// \param leaf_count Number of leaves in tree. This is rounded up to the next power of 2.
     /// \param init Status of the first \p leaf_count leaves (the ones past leaf_count start clean)
-    explicit dirty_page_tree(int level_count, size_type leaf_count, status_type init = status_type::dirty) :
+    explicit dirty_page_tree(int level_count, size_type leaf_count, const std::string &backing_filename, bool shared,
+        status_type init = status_type::dirty) :
         i_dirty_page_tree{check_level_count(level_count, leaf_count)},
         m_leaf_positions{level_positions_view(0)},
         m_valid_positions{position_iterator(1), position_iterator(position_iterator::value_type{1} << level_count)},
-        m_tree{typename container_type::size_type{1} << level_count, status_type::clean} {
-        const auto lp = m_leaf_positions;
-        const auto first_leaf = *lp.begin();
-        const auto first_pad = first_leaf + leaf_count;
-        const auto pad_count = *lp.end() - first_pad;
-        std::ranges::fill(std::span(m_tree).subspan(first_leaf, leaf_count), init);
-        std::ranges::fill(std::span(m_tree).subspan(first_pad, pad_count), status_type::dirty);
-        build_from_leaves();
-    }
-
-    /// \brief Constructor from initializer list
-    /// \param leaves Status of first few leaves in tree.
-    /// \details This is a constructor mostly used in simple tests
-    explicit dirty_page_tree(int level_count, std::initializer_list<status_type> leaves) :
-        i_dirty_page_tree{check_level_count(level_count, leaves.size())},
-        m_leaf_positions{level_positions_view(0)},
-        m_valid_positions{position_iterator(1), position_iterator(position_iterator::value_type{1} << level_count)},
-        m_tree{typename container_type::size_type{1} << level_count, status_type::clean} {
-        const auto lp = m_leaf_positions;
-        std::ranges::copy(leaves, &m_tree[*lp.begin()]);
-        build_from_leaves();
+        m_mapped_memory{get_storage_length(level_count, leaf_count), os::mapped_memory_flags{.shared = shared},
+            backing_filename},
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        m_tree{reinterpret_cast<status_type *>(m_mapped_memory.get_ptr()), size_type{1} << level_count} {
+        if (!is_initialized()) {
+            const auto lp = m_leaf_positions;
+            const auto first_leaf = *lp.begin();
+            const auto first_pad = first_leaf + leaf_count;
+            const auto pad_count = *lp.end() - first_pad;
+            std::ranges::fill(m_tree, status_type::clean);
+            std::ranges::fill(m_tree.subspan(first_leaf, leaf_count), init);
+            std::ranges::fill(m_tree.subspan(first_pad, pad_count), status_type::dirty);
+            build_from_leaves();
+            set_initialized();
+        }
     }
 
     // No copy or move constructors or assignments
@@ -118,6 +124,10 @@ class dirty_page_tree final : public i_dirty_page_tree {
     /// \brief Destructor
     ~dirty_page_tree() override = default;
 
+    static uint64_t get_storage_length(int level_count, size_type leaf_count) {
+        return (UINT64_C(1) << check_level_count(level_count, leaf_count)) * sizeof(status_type);
+    }
+
     // Dump tree in DOT format
     void dump() const {
         std::cout << "digraph HashTree {\n";
@@ -328,6 +338,11 @@ class dirty_page_tree final : public i_dirty_page_tree {
         return m_tree[*pos] == status_type::dirty;
     }
 
+    /// \brief Tells if the dirty page tree is clean
+    bool do_is_clean() const noexcept override {
+        return m_tree[*get_root_position()] == status_type::clean;
+    }
+
     /// \brief Clean entire tree
     void do_clean() noexcept override {
         for (auto pos : dirty_positions_view(leaf_positions_view())) {
@@ -336,14 +351,19 @@ class dirty_page_tree final : public i_dirty_page_tree {
         assert(m_tree[*get_root_position()] == status_type::clean);
     }
 
+    /// \brief Gets storage data
+    std::span<const unsigned char> do_get_storage_data() const noexcept override {
+        return m_mapped_memory.get_storage_data();
+    }
+
     // -----
     // Fields
     // -----
 
-    positions_range m_leaf_positions;  // Bounds on leaf positions
-    positions_range m_valid_positions; // Bounds on all positions
-    //??(edubart): convert to std::span over mapped memory
-    container_type m_tree; // Complete tree of flags
+    positions_range m_leaf_positions;  ///< Bounds on leaf positions
+    positions_range m_valid_positions; ///< Bounds on all positions
+    os::mapped_memory m_mapped_memory; ///< Mapped memory for tree storage
+    container_type m_tree;             ///< Complete tree of flags
 };
 
 } // namespace cartesi
diff --git a/src/hash-tree.cpp b/src/hash-tree.cpp
index 30e5749d2..a617e291a 100644
--- a/src/hash-tree.cpp
+++ b/src/hash-tree.cpp
@@ -34,6 +34,7 @@
 #include <utility>
 #include <vector>
 
+#include "machine-address-ranges.h"
 #include "os-features.h" // IWYU pragma: keep
 
 #ifdef HAVE_OPENMP
@@ -452,21 +453,16 @@ bool hash_tree::update_dense_trees(address_ranges ars, const changed_address_ran
 
 bool hash_tree::update_sparse_tree(address_ranges ars, const changed_address_ranges &changed_ars) {
     SCOPED_SIGNPOST(m_log, m_spid_update_sparse_tree, "hash-tree: update sparse tree", "");
-    // If there no changed address ranges, we are done
-    // Otherwise, allocate a fifo that holds at most one entry per changed address-range leaf-node
+    // Allocate a fifo that holds at most one entry per changed address-range leaf-node
     // For each changed address-range leaf-node,
     //     Copy the hash from the root of the address-range dense hash tree to the leaf-node
     //     Enqueue its sparse node's parent for update
     // Until the queue is empty
     //     Update the hash of the node at the front from the hash of its children nodes
     //     If node is not the root, enqueue its parent for update
-    auto changed_count = std::ranges::size(changed_ars);
-    if (changed_count == 0) {
-        return true;
-    }
     using E = std::pair<int, int>;
     std::pmr::vector<E> changed_backing{&m_memory_pool};
-    changed_backing.reserve(changed_count);
+    changed_backing.reserve(std::ranges::size(changed_ars));
     std::priority_queue<E, decltype(changed_backing), std::greater<>> changed(std::greater<>{},
         std::move(changed_backing));
     for (auto ar_index : changed_ars) {
@@ -480,6 +476,23 @@ bool hash_tree::update_sparse_tree(address_ranges ars, const changed_address_ran
             changed.emplace(ar_parent_node.log2_size, ar_node.parent);
         }
     }
+    // Ensure all sparse leaf node hashes match their corresponding dense tree root hashes.
+    // This is necessary because sparse and dense trees can become unsynchronized,
+    // for example after constructing the hash tree from clean dense trees or swapping address ranges.
+    for (int ar_index = 0; const auto &ar : ars) {
+        auto ar_node_index = get_ar_sparse_node_index(ar_index);
+        auto &ar_node = m_sparse_nodes[ar_node_index];
+        auto ar_root_hash_view = ar.get_dense_hash_tree().root_hash_view();
+        if (!std::ranges::equal(ar_root_hash_view, ar_node.hash)) {
+            std::ranges::copy(ar_root_hash_view, ar_node.hash.begin());
+            auto &ar_parent_node = m_sparse_nodes[ar_node.parent];
+            if (ar_parent_node.marked == 0) {
+                ar_parent_node.marked = 1;
+                changed.emplace(ar_parent_node.log2_size, ar_node.parent);
+            }
+        }
+        ++ar_index;
+    }
     variant_hasher h{m_hash_function};
     simd_concat_hasher<variant_hasher, const_machine_hash_view> queue(h);
     int last_log2_size = -1;
@@ -862,24 +875,73 @@ static int get_concurrency([[maybe_unused]] int value) {
 #endif
 }
 
-hash_tree::hash_tree(const hash_tree_config &config, uint64_t concurrency, const_address_ranges ars,
-    hash_function_type hash_function) :
+hash_tree::hash_tree(const hash_tree_config &config, uint64_t concurrency, const nodes_type &init_sparse_nodes) :
 #ifdef HAS_SIGNPOSTS
     m_log{os_log_create("io.cartesi.machine-emulator", "hash-tree")},
     m_spid_update{os_signpost_id_generate(m_log)},
     m_spid_update_page_hashes{os_signpost_id_generate(m_log)},
     m_spid_update_dense_trees{os_signpost_id_generate(m_log)},
     m_spid_update_sparse_tree{os_signpost_id_generate(m_log)},
-    m_page_cache{m_log, variant_hasher{hash_function}, config.phtc_size},
+    m_page_cache{m_log, variant_hasher{config.hash_function}, static_cast<size_t>(config.phtc_size),
+        config.phtc_filename, config.shared},
 #else
-    m_page_cache{variant_hasher{hash_function}, static_cast<size_t>(config.phtc_size)},
+    m_page_cache{variant_hasher{config.hash_function}, static_cast<size_t>(config.phtc_size), config.phtc_filename,
+        config.shared},
 #endif
-    m_sparse_nodes{create_nodes(ars)},
-    m_pristine_hashes{get_pristine_hashes(hash_function)},
+    m_mapped_memory{init_sparse_nodes.size() * sizeof(node_type), os::mapped_memory_flags{.shared = config.shared},
+        config.sht_filename},
+    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+    m_sparse_nodes{reinterpret_cast<node_type *>(m_mapped_memory.get_ptr()), init_sparse_nodes.size()},
+    m_pristine_hashes{get_pristine_hashes(config.hash_function)},
     m_concurrency{get_concurrency(static_cast<int>(concurrency))},
-    m_hash_function{hash_function} {
+    m_hash_function{config.hash_function} {
+    if (init_sparse_nodes.size() != m_sparse_nodes.size()) {
+        throw std::runtime_error{"inconsistent amount of sparse hash tree nodes"};
+    }
+    // If root node log2_size is zero, then sparse nodes are not initialized yet
+    if (m_sparse_nodes[1].log2_size == 0) {
+        // Initialize sparse nodes in case of newly created memory mapping
+        std::ranges::copy(init_sparse_nodes, m_sparse_nodes.begin());
+    } else {
+        // Validate sparse nodes consistency
+        for (const auto &[node, init_node] : std::views::zip(m_sparse_nodes, init_sparse_nodes)) {
+            if (node.left != init_node.left || node.right != init_node.right || node.parent != init_node.parent ||
+                node.log2_size != init_node.log2_size || node.marked > 1) {
+                throw std::runtime_error{"inconsistent sparse hash tree nodes"};
+            }
+        }
+    }
 }
 
+hash_tree::hash_tree(const hash_tree_config &config, uint64_t concurrency, machine_address_ranges &mars,
+    const std::string &dir, scope_remove &remover) :
+    hash_tree(
+        [&] { // Create hash tree backing stores if needed
+            hash_tree_config c = config;
+            if (!dir.empty()) {
+                // Prepare hash tree backing store
+                c.shared = true;
+                c.create = true;
+                c.sht_filename = machine_config::get_sht_filename(dir);
+                c.phtc_filename = machine_config::get_phtc_filename(dir);
+            }
+
+            // Create sht storage
+            if (!c.sht_filename.empty() && c.shared && c.create) { // Create new file
+                os::truncate_file(c.sht_filename, hash_tree::get_sht_storage_length(mars), true);
+                remover.add_file(c.sht_filename);
+            }
+
+            // Create phtc storage
+            if (!c.phtc_filename.empty() && c.shared && c.create) { // Create new file
+                os::truncate_file(c.phtc_filename, hash_tree::get_phtc_storage_length(c), true);
+                remover.add_file(c.phtc_filename);
+            }
+
+            return c;
+        }(),
+        concurrency, create_nodes(mars)) {}
+
 void hash_tree::check_address_ranges(const_address_ranges ars) {
     for (int ar_i = 0; auto &&ar : ars) {
         // Empty ranges are not supported
diff --git a/src/hash-tree.h b/src/hash-tree.h
index 97e8af9b2..5f8937129 100644
--- a/src/hash-tree.h
+++ b/src/hash-tree.h
@@ -27,6 +27,7 @@
 #include <type_traits>
 #include <vector>
 
+#include "os-mapped-memory.h"
 #include "unordered_dense.h"
 
 #include "address-range.h"
@@ -131,10 +132,12 @@ class hash_tree {
     using dirty_words_type = ankerl::unordered_dense::set<uint64_t>;
     using dirty_pages_type = ankerl::unordered_dense::set<uint64_t>;
     using nodes_type = std::vector<node_type>;
+    using nodes_view_type = std::span<node_type>;
     using sibling_hashes_type = std::vector<machine_hash>;
 
-    hash_tree(const hash_tree_config &config, uint64_t concurrency, const_address_ranges ars,
-        hash_function_type hash_function);
+    hash_tree(const hash_tree_config &config, uint64_t concurrency, const nodes_type &init_sparse_nodes);
+    hash_tree(const hash_tree_config &config, uint64_t concurrency, machine_address_ranges &mars,
+        const std::string &dir, scope_remove &remover);
 
     hash_tree(const hash_tree &other) = delete;
     hash_tree(hash_tree &&other) = delete;
@@ -143,6 +146,22 @@ class hash_tree {
 
     ~hash_tree();
 
+    static uint64_t get_sht_storage_length(const_address_ranges ars) {
+        return create_nodes(ars).size() * sizeof(node_type);
+    }
+
+    static uint64_t get_phtc_storage_length(const hash_tree_config &config) {
+        return page_hash_tree_cache::get_storage_length(config.phtc_size);
+    }
+
+    std::span<const unsigned char> get_sht_storage_data() const noexcept {
+        return m_mapped_memory.get_storage_data();
+    }
+
+    std::span<const unsigned char> get_phtc_storage_data() const noexcept {
+        return m_page_cache.get_storage_data();
+    }
+
     bool update(address_ranges ars);
 
     bool update_words(address_ranges ars, const dirty_words_type &dirty_words);
@@ -186,7 +205,7 @@ class hash_tree {
         requires(std::same_as<std::remove_cvref_t<std::iter_reference_t<Iter>>, address_range> &&
             std::is_reference_v<std::iter_reference_t<Iter>>)
     static index_type append_nodes(uint64_t begin_page_index, uint64_t log2_page_count, Iter &ar_curr /* modifiable! */,
-        Iter ar_begin, Sent ar_sent, hash_tree::nodes_type &nodes, index_type parent);
+        Iter ar_begin, Sent ar_sent, nodes_type &nodes, index_type parent);
 
     static nodes_type create_nodes(const_address_ranges ars);
     static void check_address_ranges(const_address_ranges ars);
@@ -200,9 +219,8 @@ class hash_tree {
 #endif
 
     mutable page_hash_tree_cache m_page_cache;
-    //??D Replace std::vector so entries can live on disk
-    //??(edubart): convert to a std::span over mmapped memory
-    nodes_type m_sparse_nodes;
+    os::mapped_memory m_mapped_memory;
+    nodes_view_type m_sparse_nodes;
     const pristine_hashes m_pristine_hashes;
     int m_concurrency;
     hash_function_type m_hash_function;
diff --git a/src/i-dense-hash-tree.h b/src/i-dense-hash-tree.h
index 29ea50c65..d8a314d57 100644
--- a/src/i-dense-hash-tree.h
+++ b/src/i-dense-hash-tree.h
@@ -18,6 +18,7 @@
 #define I_DENSE_HASH_TREE_H
 
 #include <cstdint>
+#include <span>
 
 #include "machine-hash.h"
 
@@ -34,6 +35,9 @@ class i_dense_hash_tree {
     const_machine_hash_view root_hash_view() const noexcept {
         return do_root_hash_view();
     }
+    std::span<const unsigned char> get_storage_data() const noexcept {
+        return do_get_storage_data();
+    }
 
     i_dense_hash_tree() = default;
     i_dense_hash_tree(const i_dense_hash_tree &) = default;
@@ -55,6 +59,7 @@ class i_dense_hash_tree {
     virtual const_machine_hash_view do_node_hash_view(uint64_t offset, int log2_size) const noexcept = 0;
     virtual machine_hash_view do_node_hash_view(uint64_t offset, int log2_size) noexcept = 0;
     virtual const_machine_hash_view do_root_hash_view() const noexcept = 0;
+    virtual std::span<const unsigned char> do_get_storage_data() const noexcept = 0;
 };
 
 class empty_dense_hash_tree final : public i_dense_hash_tree {
@@ -67,6 +72,9 @@ class empty_dense_hash_tree final : public i_dense_hash_tree {
     const_machine_hash_view do_root_hash_view() const noexcept override {
         return no_hash_view();
     }
+    std::span<const unsigned char> do_get_storage_data() const noexcept override {
+        return {};
+    }
 };
 
 } // namespace cartesi
diff --git a/src/i-dirty-page-tree.h b/src/i-dirty-page-tree.h
index 90fd354c1..545220417 100644
--- a/src/i-dirty-page-tree.h
+++ b/src/i-dirty-page-tree.h
@@ -24,6 +24,7 @@
 #include <iterator>
 #include <limits>
 #include <ranges>
+#include <span>
 #include <type_traits>
 
 #include "address-range-constants.h"
@@ -183,10 +184,17 @@ class i_dirty_page_tree {
     /// \returns True if node is dirty, false otherwise
     virtual bool do_is_dirty_position(position_iterator pos) const noexcept = 0;
 
+    /// \brief Tells if the dirty page tree is clean
+    /// \returns True if root node is clean, false otherwise
+    virtual bool do_is_clean() const noexcept = 0;
+
     /// \brief Cleans entire tree
     /// \detail The derived class is free to ignore the operation
     virtual void do_clean() noexcept = 0;
 
+    /// \brief Gets storage data
+    virtual std::span<const unsigned char> do_get_storage_data() const noexcept = 0;
+
     /// Non-Virtual Interface (NVI) pattern for do_is_dirty_position()
     bool is_dirty_position(position_iterator pos) const noexcept {
         return do_is_dirty_position(pos);
@@ -286,6 +294,17 @@ class i_dirty_page_tree {
         do_clean();
     }
 
+    /// \brief Tells if the dirty page tree is clean
+    /// \returns True if root node is clean, false otherwise
+    bool is_clean() const noexcept {
+        return do_is_clean();
+    }
+
+    /// \brief Gets storage data
+    std::span<const unsigned char> get_storage_data() const noexcept {
+        return do_get_storage_data();
+    }
+
     /// \brief Marks a page clean (and all its ancestors that only have clean descendants)
     /// \param offset Offset within page
     /// \detail The derived class is free to ignore the operation
@@ -337,10 +356,18 @@ class empty_dirty_page_tree final : public i_dirty_page_tree {
         return true;
     }
 
+    bool do_is_clean() const noexcept override {
+        return true;
+    }
+
     void do_clean() noexcept override {
         ;
     }
 
+    std::span<const unsigned char> do_get_storage_data() const noexcept override {
+        return {};
+    }
+
 public:
     empty_dirty_page_tree() noexcept : i_dirty_page_tree{0} {
         ;
diff --git a/src/json-util.cpp b/src/json-util.cpp
index 0383b48ad..8a4c212ea 100644
--- a/src/json-util.cpp
+++ b/src/json-util.cpp
@@ -1512,7 +1512,6 @@ void ju_get_opt_field(const nlohmann::json &j, const K &key, hash_tree_config &v
     const auto new_path = path + to_string(key) + "/";
     ju_get_opt_field(jconfig, "shared"s, value.shared, new_path);
     ju_get_opt_field(jconfig, "create"s, value.create, new_path);
-    ju_get_opt_field(jconfig, "truncate"s, value.truncate, new_path);
     ju_get_opt_field(jconfig, "sht_filename"s, value.sht_filename, new_path);
     ju_get_opt_field(jconfig, "phtc_filename"s, value.phtc_filename, new_path);
     ju_get_opt_field(jconfig, "phtc_size"s, value.phtc_size, new_path);
@@ -2085,8 +2084,8 @@ void to_json(nlohmann::json &j, const memory_range_config &config) {
 }
 
 void to_json(nlohmann::json &j, const hash_tree_config &config) {
-    j = nlohmann::json{{"shared", config.shared}, {"create", config.create}, {"truncate", config.truncate},
-        {"sht_filename", config.sht_filename}, {"phtc_filename", config.phtc_filename}, {"phtc_size", config.phtc_size},
+    j = nlohmann::json{{"shared", config.shared}, {"create", config.create}, {"sht_filename", config.sht_filename},
+        {"phtc_filename", config.phtc_filename}, {"phtc_size", config.phtc_size},
         {"hash_function", hash_function_to_name(config.hash_function)}};
 }
 
diff --git a/src/jsonrpc-discover.json b/src/jsonrpc-discover.json
index dabe649b1..f09fe4ae8 100644
--- a/src/jsonrpc-discover.json
+++ b/src/jsonrpc-discover.json
@@ -1906,9 +1906,6 @@
           "create": {
             "type": "boolean"
           },
-          "truncate": {
-            "type": "boolean"
-          },
           "sht_filename": {
             "type": "string"
           },
diff --git a/src/machine-address-ranges.cpp b/src/machine-address-ranges.cpp
index 495578dbd..9941e384f 100644
--- a/src/machine-address-ranges.cpp
+++ b/src/machine-address-ranges.cpp
@@ -150,64 +150,113 @@ AR &machine_address_ranges::push_back(std::unique_ptr<AR> &&ar_ptr, register_whe
     return ar_ref; // Return reference to object in heap
 }
 
-static void prepare_backing_store(const backing_store_config &backing_store, uint64_t length, scope_remove &remover) {
-    if (!backing_store.data_filename.empty() && backing_store.shared) {
-        if (backing_store.create) { // Create new file
-            os::truncate_file(backing_store.data_filename, length, true);
-            remover.add_file(backing_store.data_filename);
-        } else if (backing_store.truncate) { // Truncate existing file
-            os::truncate_file(backing_store.data_filename, length, false);
+static void prepare_ar_backing_store(const backing_store_config &c, uint64_t length, scope_remove &remover) {
+    if (!c.shared) {
+        return;
+    }
+
+    // Create data storage
+    if (!c.data_filename.empty()) {
+        if (c.create) { // Create new file
+            os::truncate_file(c.data_filename, length, true);
+            remover.add_file(c.data_filename);
+        } else if (c.truncate) { // Truncate existing file
+            os::truncate_file(c.data_filename, length, false);
         }
     }
+
+    // Create dht storage only if needed
+    if (!c.dht_filename.empty() && (c.create || !os::exists(c.dht_filename))) {
+        os::truncate_file(c.dht_filename, memory_address_range::get_dht_storage_length(length), true);
+        remover.add_file(c.dht_filename);
+    }
+
+    // Create dpt storage only if needed
+    if (!c.dpt_filename.empty() && (c.create || !os::exists(c.dpt_filename))) {
+        os::truncate_file(c.dpt_filename, memory_address_range::get_dpt_storage_length(length), true);
+        remover.add_file(c.dpt_filename);
+    }
 }
 
-static void prepare_backing_store_for_share(const backing_store_config &from, backing_store_config &to, uint64_t length,
-    bool read_only, scope_remove &remover) {
-    to.shared = true;
-    if (from.newly_created()) { // Nothing to copy
-        os::truncate_file(to.data_filename, length, true);
-        remover.add_file(to.data_filename);
+static void prepare_ar_backing_store_for_share(const backing_store_config &from_c, backing_store_config &to_c,
+    uint64_t length, bool read_only, scope_remove &remover) {
+    to_c.shared = true;
+    const uint64_t dht_length = memory_address_range::get_dht_storage_length(length);
+    const uint64_t dpt_length = memory_address_range::get_dpt_storage_length(length);
+    if (from_c.newly_created()) { // Nothing to copy
+        // Prepare data storage
+        os::truncate_file(to_c.data_filename, length, true);
+        remover.add_file(to_c.data_filename);
+
+        // Prepare dht storage
+        os::truncate_file(to_c.dht_filename, dht_length, true);
+        remover.add_file(to_c.dht_filename);
+
+        // Prepare dpt storage
+        os::truncate_file(to_c.dpt_filename, dpt_length, true);
+        remover.add_file(to_c.dpt_filename);
+
         // Necessary, so the memory is always mapped as writeable in memory address range constructor
-        to.create = true;
+        to_c.create = true;
     } else {
-        os::copy_file(from.data_filename, to.data_filename, length);
-        remover.add_file(to.data_filename);
+        // Prepare data storage
+        os::copy_file(from_c.data_filename, to_c.data_filename, length);
+        remover.add_file(to_c.data_filename);
+
+        // Prepare dht storage
+        if (os::exists(from_c.dht_filename) && os::file_size(from_c.dht_filename) == dht_length) {
+            os::copy_file(from_c.dht_filename, to_c.dht_filename, dht_length);
+        } else {
+            os::truncate_file(to_c.dht_filename, dht_length, true);
+        }
+        remover.add_file(to_c.dht_filename);
+
+        // Prepare dpt storage
+        if (os::exists(from_c.dpt_filename) && os::file_size(from_c.dpt_filename) == dpt_length) {
+            os::copy_file(from_c.dpt_filename, to_c.dpt_filename, dpt_length);
+        } else {
+            os::truncate_file(to_c.dpt_filename, dpt_length, true);
+        }
+        remover.add_file(to_c.dpt_filename);
     }
-    os::change_writable(to.data_filename, !read_only);
+    os::change_writable(to_c.data_filename, !read_only);
 }
 
-static void prepare_backing_stores(const machine_config &c, scope_remove &remover) {
-    prepare_backing_store(c.processor.backing_store, AR_SHADOW_STATE_LENGTH, remover);
-    prepare_backing_store(c.pmas.backing_store, AR_PMAS_LENGTH, remover);
-    prepare_backing_store(c.dtb.backing_store, AR_DTB_LENGTH, remover);
-    prepare_backing_store(c.ram.backing_store, c.ram.length, remover);
-    prepare_backing_store(c.cmio.rx_buffer.backing_store, AR_CMIO_RX_BUFFER_LENGTH, remover);
-    prepare_backing_store(c.cmio.tx_buffer.backing_store, AR_CMIO_TX_BUFFER_LENGTH, remover);
-    prepare_backing_store(c.uarch.processor.backing_store, AR_SHADOW_UARCH_STATE_LENGTH, remover);
-    prepare_backing_store(c.uarch.ram.backing_store, AR_UARCH_RAM_LENGTH, remover);
+static void prepare_ar_backing_stores(const machine_config &c, scope_remove &remover) {
+    prepare_ar_backing_store(c.processor.backing_store, AR_SHADOW_STATE_LENGTH, remover);
+    prepare_ar_backing_store(c.pmas.backing_store, AR_PMAS_LENGTH, remover);
+    prepare_ar_backing_store(c.dtb.backing_store, AR_DTB_LENGTH, remover);
+    prepare_ar_backing_store(c.ram.backing_store, c.ram.length, remover);
+    prepare_ar_backing_store(c.cmio.rx_buffer.backing_store, AR_CMIO_RX_BUFFER_LENGTH, remover);
+    prepare_ar_backing_store(c.cmio.tx_buffer.backing_store, AR_CMIO_TX_BUFFER_LENGTH, remover);
+    prepare_ar_backing_store(c.uarch.processor.backing_store, AR_SHADOW_UARCH_STATE_LENGTH, remover);
+    prepare_ar_backing_store(c.uarch.ram.backing_store, AR_UARCH_RAM_LENGTH, remover);
     for (const auto &f : c.flash_drive) {
-        prepare_backing_store(f.backing_store, f.length, remover);
+        prepare_ar_backing_store(f.backing_store, f.length, remover);
     }
 }
 
-static void create_backing_stores_for_share(const machine_config &from_c, machine_config &to_c, scope_remove &remover) {
-    prepare_backing_store_for_share(from_c.processor.backing_store, to_c.processor.backing_store,
+static void prepare_ar_backing_stores_for_share(const machine_config &from_c, machine_config &to_c,
+    scope_remove &remover) {
+    prepare_ar_backing_store_for_share(from_c.processor.backing_store, to_c.processor.backing_store,
         AR_SHADOW_STATE_LENGTH, false, remover);
-    prepare_backing_store_for_share(from_c.pmas.backing_store, to_c.pmas.backing_store, AR_PMAS_LENGTH, false, remover);
-    prepare_backing_store_for_share(from_c.dtb.backing_store, to_c.dtb.backing_store, AR_DTB_LENGTH, false, remover);
-    prepare_backing_store_for_share(from_c.ram.backing_store, to_c.ram.backing_store, to_c.ram.length, false, remover);
-    prepare_backing_store_for_share(from_c.cmio.rx_buffer.backing_store, to_c.cmio.rx_buffer.backing_store,
+    prepare_ar_backing_store_for_share(from_c.pmas.backing_store, to_c.pmas.backing_store, AR_PMAS_LENGTH, false,
+        remover);
+    prepare_ar_backing_store_for_share(from_c.dtb.backing_store, to_c.dtb.backing_store, AR_DTB_LENGTH, false, remover);
+    prepare_ar_backing_store_for_share(from_c.ram.backing_store, to_c.ram.backing_store, to_c.ram.length, false,
+        remover);
+    prepare_ar_backing_store_for_share(from_c.cmio.rx_buffer.backing_store, to_c.cmio.rx_buffer.backing_store,
         AR_CMIO_RX_BUFFER_LENGTH, false, remover);
-    prepare_backing_store_for_share(from_c.cmio.tx_buffer.backing_store, to_c.cmio.tx_buffer.backing_store,
+    prepare_ar_backing_store_for_share(from_c.cmio.tx_buffer.backing_store, to_c.cmio.tx_buffer.backing_store,
         AR_CMIO_TX_BUFFER_LENGTH, false, remover);
-    prepare_backing_store_for_share(from_c.uarch.processor.backing_store, to_c.uarch.processor.backing_store,
+    prepare_ar_backing_store_for_share(from_c.uarch.processor.backing_store, to_c.uarch.processor.backing_store,
         AR_SHADOW_UARCH_STATE_LENGTH, false, remover);
-    prepare_backing_store_for_share(from_c.uarch.ram.backing_store, to_c.uarch.ram.backing_store, AR_UARCH_RAM_LENGTH,
-        false, remover);
+    prepare_ar_backing_store_for_share(from_c.uarch.ram.backing_store, to_c.uarch.ram.backing_store,
+        AR_UARCH_RAM_LENGTH, false, remover);
     for (size_t i = 0; i < to_c.flash_drive.size(); ++i) {
         const auto &from_f = from_c.flash_drive[i];
         auto &to_f = to_c.flash_drive[i];
-        prepare_backing_store_for_share(from_f.backing_store, to_f.backing_store, from_f.length, from_f.read_only,
+        prepare_ar_backing_store_for_share(from_f.backing_store, to_f.backing_store, from_f.length, from_f.read_only,
             remover);
     }
 }
@@ -217,7 +266,7 @@ machine_address_ranges::machine_address_ranges(const machine_config &config,
     // Copy config
     machine_config c = config;
 
-    // Prepare backing stores
+    // Prepare address ranges backing stores
     if (!dir.empty()) { // Machine that it's fully on-disk
         if (config.processor.registers.iunrep != 0) {
             throw std::invalid_argument{"fully on-disk machines must not be unreproducible"s};
@@ -230,10 +279,10 @@ machine_address_ranges::machine_address_ranges(const machine_config &config,
         // Store config
         remover.add_file(c.store(dir));
         // Copy backing stores and mark them as shared
-        create_backing_stores_for_share(config, c, remover);
+        prepare_ar_backing_stores_for_share(config, c, remover);
     } else { // A machine that may be partially or fully in-memory
         // Create and truncate backing stores as necessary
-        prepare_backing_stores(c, remover);
+        prepare_ar_backing_stores(c, remover);
     }
 
     // Add all address ranges to m_all, and potentially to interpret and hash
diff --git a/src/machine-config.cpp b/src/machine-config.cpp
index 1f8ca8996..af2029e70 100644
--- a/src/machine-config.cpp
+++ b/src/machine-config.cpp
@@ -66,7 +66,7 @@ std::string machine_config::get_config_filename(const std::string &dir) {
     return dir + "/config.json";
 }
 
-void machine_config::adjust_backing_store_config(uint64_t start, uint64_t length, const std::string &dir,
+void machine_config::adjust_ar_backing_store_config(uint64_t start, uint64_t length, const std::string &dir,
     sharing_mode sharing, backing_store_config &c) {
     // Convert sharing mode
     switch (sharing) {
@@ -91,31 +91,44 @@ void machine_config::adjust_backing_store_config(uint64_t start, uint64_t length
     c.dpt_filename = machine_config::get_dpt_filename(dir, start, length);
 }
 
-void machine_config::adjust_hash_tree_config(const std::string &dir, hash_tree_config &c) {
-    // Strip create and truncate since backing store should be already created
+void machine_config::adjust_ht_backing_store_config(const std::string &dir, sharing_mode sharing, hash_tree_config &c) {
+    // Convert sharing mode
+    switch (sharing) {
+        case sharing_mode::none:
+            c.shared = false;
+            break;
+        case sharing_mode::config:
+            // Preserve the shared setting as specified in the configuration
+            break;
+        case sharing_mode::all:
+            c.shared = true;
+            break;
+    }
+
+    // Strip create since backing store should be already created
     c.create = false;
-    c.truncate = false;
 
     c.sht_filename = machine_config::get_sht_filename(dir);
     c.phtc_filename = machine_config::get_phtc_filename(dir);
 }
 
 machine_config &machine_config::adjust_backing_stores(const std::string &dir, sharing_mode sharing) {
-    adjust_backing_store_config(AR_RAM_START, ram.length, dir, sharing, ram.backing_store);
-    adjust_backing_store_config(AR_DTB_START, AR_DTB_LENGTH, dir, sharing, dtb.backing_store);
+    adjust_ar_backing_store_config(AR_RAM_START, ram.length, dir, sharing, ram.backing_store);
+    adjust_ar_backing_store_config(AR_DTB_START, AR_DTB_LENGTH, dir, sharing, dtb.backing_store);
     for (auto &f : flash_drive) {
-        adjust_backing_store_config(f.start, f.length, dir, sharing, f.backing_store);
+        adjust_ar_backing_store_config(f.start, f.length, dir, sharing, f.backing_store);
     }
-    adjust_backing_store_config(AR_SHADOW_STATE_START, AR_SHADOW_STATE_LENGTH, dir, sharing, processor.backing_store);
-    adjust_backing_store_config(AR_CMIO_RX_BUFFER_START, AR_CMIO_RX_BUFFER_LENGTH, dir, sharing,
+    adjust_ar_backing_store_config(AR_SHADOW_STATE_START, AR_SHADOW_STATE_LENGTH, dir, sharing,
+        processor.backing_store);
+    adjust_ar_backing_store_config(AR_CMIO_RX_BUFFER_START, AR_CMIO_RX_BUFFER_LENGTH, dir, sharing,
         cmio.rx_buffer.backing_store);
-    adjust_backing_store_config(AR_CMIO_TX_BUFFER_START, AR_CMIO_TX_BUFFER_LENGTH, dir, sharing,
+    adjust_ar_backing_store_config(AR_CMIO_TX_BUFFER_START, AR_CMIO_TX_BUFFER_LENGTH, dir, sharing,
         cmio.tx_buffer.backing_store);
-    adjust_backing_store_config(AR_PMAS_START, AR_PMAS_LENGTH, dir, sharing, pmas.backing_store);
-    adjust_backing_store_config(AR_SHADOW_UARCH_STATE_START, AR_SHADOW_UARCH_STATE_LENGTH, dir, sharing,
+    adjust_ar_backing_store_config(AR_PMAS_START, AR_PMAS_LENGTH, dir, sharing, pmas.backing_store);
+    adjust_ar_backing_store_config(AR_SHADOW_UARCH_STATE_START, AR_SHADOW_UARCH_STATE_LENGTH, dir, sharing,
         uarch.processor.backing_store);
-    adjust_backing_store_config(AR_UARCH_RAM_START, AR_UARCH_RAM_LENGTH, dir, sharing, uarch.ram.backing_store);
-    adjust_hash_tree_config(dir, hash_tree);
+    adjust_ar_backing_store_config(AR_UARCH_RAM_START, AR_UARCH_RAM_LENGTH, dir, sharing, uarch.ram.backing_store);
+    adjust_ht_backing_store_config(dir, sharing, hash_tree);
     return *this;
 }
 
diff --git a/src/machine-config.h b/src/machine-config.h
index 59008e8c9..aac63b3c0 100644
--- a/src/machine-config.h
+++ b/src/machine-config.h
@@ -163,12 +163,11 @@ struct uarch_config final {
 
 /// \brief Hash tree config
 struct hash_tree_config final {
-    bool shared{false};        ///< Should changes be reflected in backing store?
-    bool create{false};        ///< Should backing store be created?
-    bool truncate{false};      ///< Should backing store be truncated to correct size?
-    std::string sht_filename;  ///< Backing storage for sparse hash-tree
-    std::string phtc_filename; ///< Backing storage for page hash-tree cache
-    uint64_t phtc_size{8192};  ///< Max number of pages in page hash-tree cache
+    bool shared{false};                                              ///< Should changes be reflected in backing store?
+    bool create{false};                                              ///< Should backing store be created?
+    std::string sht_filename;                                        ///< Backing storage for sparse hash-tree
+    std::string phtc_filename;                                       ///< Backing storage for page hash-tree cache
+    uint64_t phtc_size{4096};                                        ///< Max number of pages in page hash-tree cache
     hash_function_type hash_function{hash_function_type::keccak256}; ///< Hash function type to use in the hash-tree
 };
 
@@ -202,10 +201,10 @@ struct machine_config final {
     /// \brief Get the name where global page hash-tree cache will be stored in a directory
     static std::string get_phtc_filename(const std::string &dir);
 
-    static void adjust_backing_store_config(uint64_t start, uint64_t length, const std::string &dir,
+    static void adjust_ar_backing_store_config(uint64_t start, uint64_t length, const std::string &dir,
         sharing_mode sharing, backing_store_config &c);
 
-    static void adjust_hash_tree_config(const std::string &dir, hash_tree_config &c);
+    static void adjust_ht_backing_store_config(const std::string &dir, sharing_mode sharing, hash_tree_config &c);
 
     /// \brief Adjusts the machine config filling in default values
     machine_config &adjust_defaults();
diff --git a/src/machine.cpp b/src/machine.cpp
index 2d35d7cae..255b38af2 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -43,7 +43,6 @@
 #include "device-state-access.h"
 #include "dtb.h"
 #include "hash-tree-constants.h"
-#include "hash-tree-stats.h"
 #include "hash-tree.h"
 #include "host-addr.h"
 #include "hot-tlb.h"
@@ -51,11 +50,13 @@
 #include "i-device-state-access.h"
 #include "interpret.h"
 #include "is-pristine.h"
+#include "machine-address-ranges.h"
 #include "machine-config.h"
 #include "machine-hash.h"
 #include "machine-reg.h"
 #include "machine-runtime-config.h"
 #include "mcycle-root-hashes.h"
+#include "memory-address-range.h"
 #include "os-filesystem.h"
 #include "os-mapped-memory.h"
 #include "os.h"
@@ -101,10 +102,6 @@ static_assert(static_cast<int>(AR_LOG2_PAGE_SIZE) == static_cast<int>(HASH_TREE_
 
 using namespace std::string_literals;
 
-hash_tree_stats machine::get_hash_tree_stats(bool clear) noexcept {
-    return m_ht.get_stats(clear);
-}
-
 void machine::init_uarch_processor(const uarch_processor_config &p) {
     if (p.backing_store.newly_created()) {
         // Initialize to default values first
@@ -295,7 +292,7 @@ machine::machine(machine_config c, machine_runtime_config r, const std::string &
     m_c{std::move(c).adjust_defaults()}, // NOLINT(hicpp-move-const-arg,performance-move-const-arg)
     m_r{std::move(r)},                   // NOLINT(hicpp-move-const-arg,performance-move-const-arg)
     m_ars{m_c, m_r, dir, remover},
-    m_ht{m_c.hash_tree, m_r.concurrency.update_hash_tree, m_ars, m_c.hash_tree.hash_function},
+    m_ht{m_c.hash_tree, m_r.concurrency.update_hash_tree, m_ars, dir, remover},
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
     m_s{reinterpret_cast<processor_state *>(
         m_ars.find(AR_SHADOW_STATE_START, AR_SHADOW_STATE_LENGTH).get_host_memory())},
@@ -384,34 +381,6 @@ void machine::set_runtime_config(machine_runtime_config r) {
     m_r = std::move(r); // NOLINT(hicpp-move-const-arg,performance-move-const-arg)
 }
 
-static void store_address_range(const backing_store_config &from_config, const address_range &ar, bool read_only,
-    const std::string &dir, sharing_mode sharing, scope_remove &remover) {
-    if (ar.is_empty()) {
-        throw std::runtime_error{"attempt to store empty address range "s.append(ar.get_description())};
-    }
-    if (!ar.is_memory() || ar.get_host_memory() == nullptr) {
-        throw std::runtime_error{"attempt to store non-memory address range "s.append(ar.get_description())};
-    }
-    // Write the memory data to a file
-    const std::string data_filename = machine_config::get_data_filename(dir, ar.get_start(), ar.get_length());
-    if (sharing == sharing_mode::all || (sharing == sharing_mode::config && from_config.shared)) {
-        os::create_file(data_filename, std::span{ar.get_host_memory(), static_cast<size_t>(ar.get_length())});
-    } else { // Copy unshared backing store
-        if (from_config.data_filename.empty()) {
-            throw std::runtime_error{"attempt to restore unbacked address range "s.append(ar.get_description())};
-        }
-        if (from_config.shared) {
-            throw std::runtime_error{"attempt to restore shared address range "s.append(ar.get_description())};
-        }
-        os::copy_file(from_config.data_filename, data_filename, ar.get_length());
-    }
-    remover.add_file(data_filename);
-    if (read_only) {
-        // Mark host read-only ranges as read-only
-        os::change_writable(data_filename, false);
-    }
-}
-
 void machine::store(const std::string &dir, sharing_mode sharing) const {
     if (dir.empty()) {
         throw std::invalid_argument{"directory name cannot be empty"};
@@ -420,38 +389,87 @@ void machine::store(const std::string &dir, sharing_mode sharing) const {
         throw std::runtime_error{"cannot store unreproducible machines"};
     }
     scope_remove remover;
+
     // Create directory
     os::create_directory(dir);
     remover.add_directory(dir);
+
     // Store config
     remover.add_file(m_c.store(dir, sharing));
+
     // Store all address ranges
-    store_address_range(m_c.processor.backing_store, m_ars.find<uint64_t>(AR_SHADOW_STATE_START), false, dir, sharing,
-        remover);
-    store_address_range(m_c.pmas.backing_store, m_ars.find<uint64_t>(AR_PMAS_START), true, dir, sharing, remover);
-    store_address_range(m_c.dtb.backing_store, m_ars.find<uint64_t>(AR_DTB_START), false, dir, sharing, remover);
-    store_address_range(m_c.ram.backing_store, m_ars.find<uint64_t>(AR_RAM_START), false, dir, sharing, remover);
-    store_address_range(m_c.cmio.rx_buffer.backing_store, m_ars.find<uint64_t>(AR_CMIO_RX_BUFFER_START), false, dir,
-        sharing, remover);
-    store_address_range(m_c.cmio.tx_buffer.backing_store, m_ars.find<uint64_t>(AR_CMIO_TX_BUFFER_START), false, dir,
-        sharing, remover);
-    store_address_range(m_c.uarch.processor.backing_store, m_ars.find<uint64_t>(AR_SHADOW_UARCH_STATE_START), false,
-        dir, sharing, remover);
-    store_address_range(m_c.uarch.ram.backing_store, m_ars.find<uint64_t>(AR_UARCH_RAM_START), false, dir, sharing,
-        remover);
+    auto store_address_range = [&](const backing_store_config &c, const address_range &ar, bool read_only) {
+        if (ar.is_empty()) {
+            throw std::runtime_error{"attempt to store empty address range "s.append(ar.get_description())};
+        }
+        if (!ar.is_memory() || ar.get_host_memory() == nullptr) {
+            throw std::runtime_error{"attempt to store non-memory address range "s.append(ar.get_description())};
+        }
+        // Write the memory data to a file
+        const std::string data_filename = machine_config::get_data_filename(dir, ar.get_start(), ar.get_length());
+        const std::string dht_filename = machine_config::get_dht_filename(dir, ar.get_start(), ar.get_length());
+        const std::string dpt_filename = machine_config::get_dpt_filename(dir, ar.get_start(), ar.get_length());
+        if (sharing == sharing_mode::all || (sharing == sharing_mode::config && c.shared)) {
+            os::create_file(data_filename, std::span{ar.get_host_memory(), static_cast<size_t>(ar.get_length())});
+            remover.add_file(data_filename);
+            os::create_file(dht_filename, ar.get_dense_hash_tree().get_storage_data());
+            remover.add_file(dht_filename);
+            os::create_file(dpt_filename, ar.get_dirty_page_tree().get_storage_data());
+            remover.add_file(dpt_filename);
+        } else { // Copy unshared backing store
+            if (c.data_filename.empty()) {
+                throw std::runtime_error{"attempt to restore unbacked address range "s.append(ar.get_description())};
+            }
+            if (c.shared) {
+                throw std::runtime_error{"attempt to restore shared address range "s.append(ar.get_description())};
+            }
+            os::copy_file(c.data_filename, data_filename, ar.get_length());
+            remover.add_file(data_filename);
+            if (!c.dht_filename.empty()) {
+                os::copy_file(c.dht_filename, dht_filename);
+                remover.add_file(dht_filename);
+            }
+            if (!c.dpt_filename.empty()) {
+                os::copy_file(c.dpt_filename, dpt_filename);
+                remover.add_file(dpt_filename);
+            }
+        }
+        if (read_only) {
+            // Mark host read-only ranges as read-only
+            os::change_writable(data_filename, false);
+        }
+    };
+    store_address_range(m_c.processor.backing_store, m_ars.find<uint64_t>(AR_SHADOW_STATE_START), false);
+    store_address_range(m_c.pmas.backing_store, m_ars.find<uint64_t>(AR_PMAS_START), true);
+    store_address_range(m_c.dtb.backing_store, m_ars.find<uint64_t>(AR_DTB_START), false);
+    store_address_range(m_c.ram.backing_store, m_ars.find<uint64_t>(AR_RAM_START), false);
+    store_address_range(m_c.cmio.rx_buffer.backing_store, m_ars.find<uint64_t>(AR_CMIO_RX_BUFFER_START), false);
+    store_address_range(m_c.cmio.tx_buffer.backing_store, m_ars.find<uint64_t>(AR_CMIO_TX_BUFFER_START), false);
+    store_address_range(m_c.uarch.processor.backing_store, m_ars.find<uint64_t>(AR_SHADOW_UARCH_STATE_START), false);
+    store_address_range(m_c.uarch.ram.backing_store, m_ars.find<uint64_t>(AR_UARCH_RAM_START), false);
     for (const auto &f : m_c.flash_drive) {
-        store_address_range(f.backing_store, m_ars.find<uint64_t>(f.start), f.read_only, dir, sharing, remover);
+        store_address_range(f.backing_store, m_ars.find<uint64_t>(f.start), f.read_only);
+    }
+
+    // Store hash tree
+    const std::string sht_filename = machine_config::get_sht_filename(dir);
+    const std::string phtc_filename = machine_config::get_phtc_filename(dir);
+    if (sharing == sharing_mode::all || (sharing == sharing_mode::config && m_c.hash_tree.shared)) {
+        os::create_file(sht_filename, m_ht.get_sht_storage_data());
+        remover.add_file(sht_filename);
+        os::create_file(phtc_filename, m_ht.get_phtc_storage_data());
+        remover.add_file(phtc_filename);
+    } else {
+        os::truncate_file(sht_filename, m_ht.get_sht_storage_data().size(), true);
+        remover.add_file(sht_filename);
+        os::truncate_file(sht_filename, m_ht.get_phtc_storage_data().size(), true);
+        remover.add_file(sht_filename);
     }
+
     // Retain all stored files
     remover.retain_all();
 }
 
-static void clone_address_range(const backing_store_config &from, const backing_store_config &to,
-    scope_remove &remover) {
-    os::clone_file(from.data_filename, to.data_filename);
-    remover.add_file(to.data_filename);
-}
-
 void machine::clone_stored(const std::string &from_dir, const std::string &to_dir) {
     if (from_dir.empty() || to_dir.empty()) {
         throw std::invalid_argument{"directory name cannot be empty"};
@@ -472,18 +490,32 @@ void machine::clone_stored(const std::string &from_dir, const std::string &to_di
     remover.add_file(to_config_filename);
 
     // Clone all address ranges
-    clone_address_range(from_c.processor.backing_store, to_c.processor.backing_store, remover);
-    clone_address_range(from_c.pmas.backing_store, to_c.pmas.backing_store, remover);
-    clone_address_range(from_c.dtb.backing_store, to_c.dtb.backing_store, remover);
-    clone_address_range(from_c.ram.backing_store, to_c.ram.backing_store, remover);
-    clone_address_range(from_c.cmio.rx_buffer.backing_store, to_c.cmio.rx_buffer.backing_store, remover);
-    clone_address_range(from_c.cmio.tx_buffer.backing_store, to_c.cmio.tx_buffer.backing_store, remover);
-    clone_address_range(from_c.uarch.processor.backing_store, to_c.uarch.processor.backing_store, remover);
-    clone_address_range(from_c.uarch.ram.backing_store, to_c.uarch.ram.backing_store, remover);
+    auto clone_ar_backing_store = [&](const backing_store_config &from_bs, const backing_store_config &to_bs) {
+        os::clone_file(from_bs.data_filename, to_bs.data_filename);
+        remover.add_file(to_bs.data_filename);
+        os::clone_file(from_bs.dht_filename, to_bs.dht_filename);
+        remover.add_file(to_bs.dht_filename);
+        os::clone_file(from_bs.dpt_filename, to_bs.dpt_filename);
+        remover.add_file(to_bs.dpt_filename);
+    };
+    clone_ar_backing_store(from_c.processor.backing_store, to_c.processor.backing_store);
+    clone_ar_backing_store(from_c.pmas.backing_store, to_c.pmas.backing_store);
+    clone_ar_backing_store(from_c.dtb.backing_store, to_c.dtb.backing_store);
+    clone_ar_backing_store(from_c.ram.backing_store, to_c.ram.backing_store);
+    clone_ar_backing_store(from_c.cmio.rx_buffer.backing_store, to_c.cmio.rx_buffer.backing_store);
+    clone_ar_backing_store(from_c.cmio.tx_buffer.backing_store, to_c.cmio.tx_buffer.backing_store);
+    clone_ar_backing_store(from_c.uarch.processor.backing_store, to_c.uarch.processor.backing_store);
+    clone_ar_backing_store(from_c.uarch.ram.backing_store, to_c.uarch.ram.backing_store);
     for (size_t i = 0; i < to_c.flash_drive.size(); ++i) {
-        clone_address_range(from_c.flash_drive[i].backing_store, to_c.flash_drive[i].backing_store, remover);
+        clone_ar_backing_store(from_c.flash_drive[i].backing_store, to_c.flash_drive[i].backing_store);
     }
 
+    // Clone hash tree
+    os::clone_file(from_c.hash_tree.sht_filename, to_c.hash_tree.sht_filename);
+    remover.add_file(to_c.hash_tree.sht_filename);
+    os::clone_file(from_c.hash_tree.phtc_filename, to_c.hash_tree.phtc_filename);
+    remover.add_file(to_c.hash_tree.phtc_filename);
+
     // Retain all stored files
     remover.retain_all();
 }
@@ -496,17 +528,39 @@ void machine::remove_stored(const std::string &dir) {
 
     // Remove all address ranges
     os::remove_file(config.processor.backing_store.data_filename);
+    os::remove_file(config.processor.backing_store.dht_filename);
+    os::remove_file(config.processor.backing_store.dpt_filename);
     os::remove_file(config.pmas.backing_store.data_filename);
+    os::remove_file(config.pmas.backing_store.dht_filename);
+    os::remove_file(config.pmas.backing_store.dpt_filename);
     os::remove_file(config.dtb.backing_store.data_filename);
+    os::remove_file(config.dtb.backing_store.dht_filename);
+    os::remove_file(config.dtb.backing_store.dpt_filename);
     os::remove_file(config.ram.backing_store.data_filename);
+    os::remove_file(config.ram.backing_store.dht_filename);
+    os::remove_file(config.ram.backing_store.dpt_filename);
     os::remove_file(config.cmio.rx_buffer.backing_store.data_filename);
+    os::remove_file(config.cmio.rx_buffer.backing_store.dht_filename);
+    os::remove_file(config.cmio.rx_buffer.backing_store.dpt_filename);
     os::remove_file(config.cmio.tx_buffer.backing_store.data_filename);
+    os::remove_file(config.cmio.tx_buffer.backing_store.dht_filename);
+    os::remove_file(config.cmio.tx_buffer.backing_store.dpt_filename);
     os::remove_file(config.uarch.processor.backing_store.data_filename);
+    os::remove_file(config.uarch.processor.backing_store.dht_filename);
+    os::remove_file(config.uarch.processor.backing_store.dpt_filename);
     os::remove_file(config.uarch.ram.backing_store.data_filename);
+    os::remove_file(config.uarch.ram.backing_store.dht_filename);
+    os::remove_file(config.uarch.ram.backing_store.dpt_filename);
     for (const auto &f : config.flash_drive) {
         os::remove_file(f.backing_store.data_filename);
+        os::remove_file(f.backing_store.dht_filename);
+        os::remove_file(f.backing_store.dpt_filename);
     }
 
+    // Remove hash tree files
+    os::remove_file(config.hash_tree.sht_filename);
+    os::remove_file(config.hash_tree.phtc_filename);
+
     // Remove config
     os::remove_file(machine_config::get_config_filename(dir));
 
diff --git a/src/machine.h b/src/machine.h
index f4c9b8033..6510110c2 100644
--- a/src/machine.h
+++ b/src/machine.h
@@ -202,7 +202,9 @@ class machine final {
     /// \brief Returns hash-tree statistics
     /// \param clear Clear all statistics after collecting them
     /// \returns Structure containing all statistics
-    hash_tree_stats get_hash_tree_stats(bool clear = false) noexcept;
+    hash_tree_stats get_hash_tree_stats(bool clear = false) noexcept {
+        return m_ht.get_stats(clear);
+    }
 
     /// \brief Runs the machine until mcycle reaches mcycle_end, the machine halts or yields.
     /// \param mcycle_end Maximum value of mcycle before function returns.
diff --git a/src/memory-address-range.cpp b/src/memory-address-range.cpp
index 4a800f2cf..22d03aa31 100644
--- a/src/memory-address-range.cpp
+++ b/src/memory-address-range.cpp
@@ -52,6 +52,7 @@ static os::mapped_memory_flags check_mmap_flags(const pmas_flags &flags, const b
     return os::mapped_memory_flags{
         .read_only = memory_config.host_read_only && !backing_store.newly_created(),
         .shared = backing_store.shared,
+        .backing_gap = !backing_store.shared,
         .no_reserve = memory_config.host_no_reserve,
     };
 }
@@ -66,8 +67,12 @@ memory_address_range::memory_address_range(const std::string &description, uint6
         backing_store.data_filename, length},
     m_config{memory_config},
     m_backing_store{backing_store},
-    m_dpt{get_level_count(length), static_cast<size_t>(length >> AR_LOG2_PAGE_SIZE)},
-    m_dht{get_level_count(length), static_cast<size_t>(length >> AR_LOG2_PAGE_SIZE)} {
+    // TODO(edubart): as an optimization we could detect newly created backing stores and pre-initialize
+    // dirty hash tree as clean without even touching or causing page faults to the mapped memory
+    m_dpt{get_level_count(length), static_cast<size_t>(length >> AR_LOG2_PAGE_SIZE), backing_store.dpt_filename,
+        !backing_store.dpt_filename.empty() && backing_store.shared},
+    m_dht{get_level_count(length), static_cast<size_t>(length >> AR_LOG2_PAGE_SIZE), backing_store.dht_filename,
+        !backing_store.dht_filename.empty() && backing_store.shared} {
 } catch (const std::exception &e) {
     throw std::invalid_argument{std::string{e.what()}.append(" when initializing ").append(description)};
 } catch (...) {
diff --git a/src/memory-address-range.h b/src/memory-address-range.h
index c968cfebf..74c44eac8 100644
--- a/src/memory-address-range.h
+++ b/src/memory-address-range.h
@@ -61,7 +61,7 @@ class memory_address_range final : public address_range {
     /// \param length Length of address range
     /// \param flags Address range flags
     /// \param backing_store Configuration for underlying file backing.
-    /// \param config Additional configuration for memory address range.
+    /// \param memory_config Additional configuration for memory address range.
     /// \p config.host_length Length of host memory to be mapped.
     /// If set to 0, use \p length.
     /// Otherwise, \p host_length cannot be smaller than \p length.
@@ -79,6 +79,16 @@ class memory_address_range final : public address_range {
     memory_address_range &operator=(const memory_address_range &) = delete;
     memory_address_range &operator=(memory_address_range &&) = delete;
 
+    static uint64_t get_dht_storage_length(uint64_t length) {
+        return dense_hash_tree::get_storage_length(get_level_count(length),
+            static_cast<size_t>(length >> AR_LOG2_PAGE_SIZE));
+    }
+
+    static uint64_t get_dpt_storage_length(uint64_t length) {
+        return dirty_page_tree::get_storage_length(get_level_count(length),
+            static_cast<size_t>(length >> AR_LOG2_PAGE_SIZE));
+    }
+
 private:
     unsigned char *do_get_host_memory() noexcept override {
         return m_mapped.get_ptr();
diff --git a/src/os-mapped-memory.cpp b/src/os-mapped-memory.cpp
index f8da41419..1eb93a5ef 100644
--- a/src/os-mapped-memory.cpp
+++ b/src/os-mapped-memory.cpp
@@ -79,6 +79,8 @@ mapped_memory::mapped_memory(uint64_t length, const mapped_memory_flags &flags,
     m_length(length),
     m_backing_filename(backing_filename),
     m_flags(flags) {
+    const uint64_t desired_backing_length = backing_length.has_value() ? backing_length.value() : length;
+
     // Check some preconditions
     if (backing_filename.empty() && flags.shared) {
         throw std::invalid_argument{"backing filename must be specified"s};
@@ -86,13 +88,8 @@ mapped_memory::mapped_memory(uint64_t length, const mapped_memory_flags &flags,
     if (length == 0) {
         throw std::invalid_argument{"memory map length cannot be zero"s};
     }
-    if (backing_length.has_value()) {
-        if (length < backing_length.value()) {
-            throw std::invalid_argument{"length must be greater or equal than max backing length"s};
-        }
-        m_backing_length = backing_length.value();
-    } else if (!backing_filename.empty()) {
-        m_backing_length = length;
+    if (length < desired_backing_length) {
+        throw std::invalid_argument{"length must be greater or equal than max backing length"s};
     }
     const bool shared_write = flags.shared && !flags.read_only;
 
@@ -146,11 +143,11 @@ mapped_memory::mapped_memory(uint64_t length, const mapped_memory_flags &flags,
         backing_file_length = static_cast<uint64_t>(statbuf.st_size);
 
         // Check backing file length mismatch
-        if (backing_file_length != m_backing_length) {
-            if (flags.shared) {
+        if (backing_file_length != desired_backing_length) {
+            if (flags.shared || !flags.backing_gap) {
                 throw std::runtime_error{"backing file '"s + backing_filename + "' length ("s +
                     std::to_string(backing_file_length) + ") does not match desired backing length ("s +
-                    std::to_string(m_backing_length) + ")"s};
+                    std::to_string(desired_backing_length) + ")"s};
             }
             // Backing file length may be less than desired backing length,
             // but this is fine, as we are not sharing the file.
@@ -237,7 +234,7 @@ mapped_memory::mapped_memory(uint64_t length, const mapped_memory_flags &flags,
 
     // Commit state
     m_host_memory = host_memory;
-    m_backing_sync_length = shared_write ? m_backing_length : 0;
+    m_backing_sync_length = shared_write ? desired_backing_length : 0;
     m_backing_fd = backing_fd;
 
 #elif defined(_WIN32)
@@ -306,13 +303,11 @@ mapped_memory::mapped_memory(uint64_t length, const mapped_memory_flags &flags,
         backing_file_length = static_cast<uint64_t>(size.QuadPart);
 
         // Check backing file length mismatch
-        if (backing_file_length != m_backing_length) {
-            if (flags.shared) {
+        if (backing_file_length != desired_backing_length) {
+            if (flags.shared || !flags.backing_gap) {
                 throw std::runtime_error{"backing file '"s + backing_filename + "' length ("s +
                     std::to_string(backing_file_length) + ") does not match desired backing length ("s +
-                    std::to_string(m_backing_length) + ")"s};
-
-                backing_file_length = m_backing_length;
+                    std::to_string(desired_backing_length) + ")"s};
             }
             // Backing file length may be less than desired backing length,
             // but this is fine, as we are not sharing the file.
@@ -383,7 +378,7 @@ mapped_memory::mapped_memory(uint64_t length, const mapped_memory_flags &flags,
 
     // Commit state
     m_host_memory = host_memory;
-    m_backing_sync_length = shared_write ? m_backing_length : 0;
+    m_backing_sync_length = shared_write ? desired_backing_length : 0;
     m_memory_mapping = static_cast<void *>(memory_mapping), m_backing_host_memory = backing_host_memory,
     m_backing_mapping = backing_mapping, m_backing_fh = static_cast<void *>(backing_fh)
 };
@@ -452,18 +447,18 @@ mapped_memory::mapped_memory(uint64_t length, const mapped_memory_flags &flags,
             throw std::system_error{errno, std::generic_category(),
                 "unable to seek to beginning of backing file '"s + backing_filename + "'"s};
         }
-        const auto copy_length = std::min(backing_file_length, m_backing_length);
+        const auto copy_length = std::min(backing_file_length, desired_backing_length);
         if (static_cast<uint64_t>(std::fread(host_memory, 1, copy_length, backing_fp)) != copy_length) {
             throw std::system_error{errno, std::generic_category(),
                 "unable to read from backing file '"s + backing_filename + "'"s};
         }
 
         // Check backing file length mismatch
-        if (backing_file_length != m_backing_length) {
-            if (flags.shared) {
+        if (backing_file_length != desired_backing_length) {
+            if (flags.shared || !flags.backing_gap) {
                 throw std::runtime_error{"backing file '"s + backing_filename + "' length ("s +
                     std::to_string(backing_file_length) + ") does not match desired backing length ("s +
-                    std::to_string(m_backing_length) + ")"s};
+                    std::to_string(desired_backing_length) + ")"s};
             }
             // Backing file length may be less than desired backing length,
             // but this is fine, as we are not sharing the file.
@@ -479,7 +474,7 @@ mapped_memory::mapped_memory(uint64_t length, const mapped_memory_flags &flags,
 
     // Commit state
     m_host_memory = host_memory;
-    m_backing_sync_length = shared_write ? m_backing_length : 0;
+    m_backing_sync_length = shared_write ? desired_backing_length : 0;
     m_backing_fp = backing_fp;
     m_unaligned_host_memory = unaligned_host_memory;
 #endif // HAVE_MMAP
diff --git a/src/os-mapped-memory.h b/src/os-mapped-memory.h
index efbf62293..3a05c5bdb 100644
--- a/src/os-mapped-memory.h
+++ b/src/os-mapped-memory.h
@@ -50,9 +50,10 @@ namespace cartesi::os {
 
 /// \brief Flags for memory mapping operations.
 struct mapped_memory_flags {
-    bool read_only{false};  ///< Mark mapped memory as read-only
-    bool shared{false};     ///< Share mapped memory with the backing file
-    bool no_reserve{false}; ///< Do not reserve swap memory for the mapping
+    bool read_only{false};   ///< Mark mapped memory as read-only
+    bool shared{false};      ///< Share mapped memory with the backing file
+    bool backing_gap{false}; ///< Map anonnymous memory to complete backing file length in non-shared mappings
+    bool no_reserve{false};  ///< Do not reserve swap memory for the mapping
 };
 
 /// \brief Represents a memory-mapped region, optionally backed by a file.
@@ -60,7 +61,6 @@ class mapped_memory final {
     void *m_host_memory{nullptr};      ///< Pointer to the mapped memory region
     uint64_t m_length{0};              ///< The total size of the mapped memory
     std::string m_backing_filename;    ///< Path to the backing file
-    uint64_t m_backing_length{0};      ///< Backing file length in bytes
     uint64_t m_backing_sync_length{0}; ///< Length of file-backed portion for which memory sync is needed
     mapped_memory_flags m_flags;       ///< Flags used for the mapping
 #ifdef HAVE_MMAP
@@ -99,49 +99,36 @@ class mapped_memory final {
     mapped_memory &operator=(mapped_memory &&other) noexcept = delete;
 
     /// \brief Returns a pointer to the mapped memory region.
-    unsigned char *get_ptr() {
+    unsigned char *get_ptr() noexcept {
         // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
         return reinterpret_cast<unsigned char *>(m_host_memory);
     };
 
     /// \brief Returns a pointer to the mapped memory region.
-    const unsigned char *get_ptr() const {
+    const unsigned char *get_ptr() const noexcept {
         // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
         return reinterpret_cast<const unsigned char *>(m_host_memory);
     };
 
     /// \brief Returns a span representing the mapped memory region.
-    std::span<unsigned char> get_span() noexcept {
+    std::span<unsigned char> get_storage_data() noexcept {
         // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
         return std::span<unsigned char>{reinterpret_cast<unsigned char *>(m_host_memory), m_length};
     }
 
     /// \brief Returns a span representing the mapped memory region.
-    std::span<const unsigned char> get_span() const noexcept {
+    std::span<const unsigned char> get_storage_data() const noexcept {
         // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
         return std::span<const unsigned char>{reinterpret_cast<const unsigned char *>(m_host_memory), m_length};
     }
 
-    /// \brief Returns a span representing the backing portion of the mapped memory region.
-    std::span<unsigned char> get_backing_span() noexcept {
-        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        return std::span<unsigned char>{reinterpret_cast<unsigned char *>(m_host_memory), m_backing_length};
-    }
-
-    /// \brief Returns a span representing the backing portion of the mapped memory region.
-    std::span<const unsigned char> get_backing_span() const noexcept {
-        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        return std::span<const unsigned char>{reinterpret_cast<const unsigned char *>(m_host_memory), m_backing_length};
-    }
-
     /// \brief Returns the total length of the mapped memory region.
     uint64_t get_length() const noexcept {
         return m_length;
     }
 
-    /// \brief Returns the length of the backing file portion of the mapped memory region.
-    uint64_t get_backing_length() const noexcept {
-        return m_backing_length;
+    const std::string &get_backing_filename() {
+        return m_backing_filename;
     }
 
     /// \brief Returns the flags used for the mapping.
diff --git a/src/page-hash-tree-cache.h b/src/page-hash-tree-cache.h
index 182715144..a961d8d1c 100644
--- a/src/page-hash-tree-cache.h
+++ b/src/page-hash-tree-cache.h
@@ -78,6 +78,11 @@ class page_hash_tree_cache {
     static_assert(POD<machine_hash>, "machine_hash must be trivially copyable and standard layout");
     static_assert(POD<page_hash_tree>, "page_hash_tree must be trivially copyable and standard layout");
 
+    enum initialized_tag : uint64_t {
+        uninitialized = 0,
+        initialized = 0x50485443, // PHCT
+    };
+
     /// \class entry
     /// \brief Page hash-tree cache entry implementation
     class alignas(sizeof(uint64_t)) entry final :
@@ -409,25 +414,81 @@ class page_hash_tree_cache {
     /// \param num_entries Number of entries in cache
     template <IHasher H>
 #ifndef HAS_SIGNPOSTS
-    page_hash_tree_cache(H &&h, size_t num_entries) :
+    page_hash_tree_cache(H &&h, size_t num_entries, const std::string &backing_filename, bool shared) :
 #else
-    page_hash_tree_cache(os_log_t log, H &&h, size_t num_entries) :
+    page_hash_tree_cache(os_log_t log, H &&h, size_t num_entries, const std::string &backing_filename, bool shared) :
         m_log{log},
         m_spid_borrow{os_signpost_id_generate(m_log)},
         m_spid_pristine_check_and_update{os_signpost_id_generate(m_log)},
         m_spid_pristine_update{os_signpost_id_generate(m_log)},
         m_spid_non_pristine_update{os_signpost_id_generate(m_log)},
 #endif
-        m_mapped_memory{sizeof(lru) + (num_entries * sizeof(entry))},
-        m_lru{*new(m_mapped_memory.get_ptr()) lru},
-        m_entries{new(m_mapped_memory.get_ptr() + sizeof(lru)) entry[num_entries], num_entries},
+        m_mapped_memory{get_storage_length(num_entries), os::mapped_memory_flags{.shared = shared}, backing_filename},
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        m_initialized{*reinterpret_cast<initialized_tag *>(m_mapped_memory.get_ptr())},
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        m_lru{*reinterpret_cast<lru *>(m_mapped_memory.get_ptr() + sizeof(initialized_tag))},
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        m_entries{reinterpret_cast<entry *>(m_mapped_memory.get_ptr() + sizeof(initialized_tag) + sizeof(lru)),
+            num_entries},
         m_pristine_page_hash_tree{entry::get_pristine_page_hash_tree(std::forward<H>(h))} {
         if (num_entries == 0) {
             throw std::invalid_argument{"page hash-tree cache must have at least one entry"};
         }
         m_map.reserve(num_entries);
-        for (auto &e : m_entries) {
-            e.clear_hash_tree(m_pristine_page_hash_tree);
+
+        // Initialize mapped memory if needed
+        if (m_initialized == initialized_tag::uninitialized) {
+            // Use placement new to explicit initialize boost instrusive list internal fields
+            new (&m_lru) lru;
+            new (m_entries.data()) entry[num_entries];
+            // Set all entries hashes to pristine page
+            for (auto &e : m_entries) {
+                e.clear_hash_tree(m_pristine_page_hash_tree);
+            }
+            m_initialized = initialized_tag::initialized;
+        } else {
+            // Validate if the file type is correct
+            if (m_initialized != initialized_tag::initialized) {
+                throw std::runtime_error{"corrupted page hash-tree cache: file tag mismatch"};
+            }
+
+            // Validate list size
+            if (m_lru.size() > num_entries) {
+                throw std::runtime_error{"corrupted page hash-tree cache: LRU size exceeds capacity"};
+            }
+
+            // The mapped memory contains relative (offset) pointers.
+            // To ensure safety, we must validate all pointers before using them.
+            // Otherwise, dereferencing invalid pointers from corrupted files could result in undefined behavior.
+            // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+            const auto entries_begin = reinterpret_cast<uintptr_t>(m_entries.data());
+            // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+            const auto entries_end = reinterpret_cast<uintptr_t>(m_entries.data() + m_entries.size());
+            uint64_t list_size = 0;
+            // Validate that all entries in LRU are within the valid entries array range
+            for (auto &e : m_lru) {
+                // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+                const auto entry_addr = reinterpret_cast<uintptr_t>(&e);
+                // Check if entry pointer is within valid range
+                if (entry_addr < entries_begin || entry_addr >= entries_end) {
+                    throw std::runtime_error{"corrupted page hash-tree cache: LRU contains invalid entry pointer"};
+                }
+                // Check if entry is properly aligned
+                if ((entry_addr & (alignof(entry) - 1)) != 0) {
+                    throw std::runtime_error{"corrupted page hash-tree cache: LRU contains unaligned entry pointer"};
+                }
+                list_size++;
+            }
+            // Validate actual list size
+            if (m_lru.size() != list_size) {
+                throw std::runtime_error{"corrupted page hash-tree cache: LRU size mismatch"};
+            }
+
+            // Reconstruct entries map
+            for (auto &e : m_lru) {
+                m_map.emplace(e.get_paddr_page(), e);
+            }
         }
     }
 
@@ -436,6 +497,14 @@ class page_hash_tree_cache {
     page_hash_tree_cache &operator=(const page_hash_tree_cache &other) = delete;
     page_hash_tree_cache &operator=(page_hash_tree_cache &&other) = delete;
 
+    static uint64_t get_storage_length(size_t num_entries) {
+        return sizeof(lru) + (num_entries * sizeof(entry));
+    }
+
+    std::span<const unsigned char> get_storage_data() const noexcept {
+        return m_mapped_memory.get_storage_data();
+    }
+
     /// \brief Tries to borrow a cache entry
     /// \param paddr_page Target physical address of page to borrow
     /// \returns Entry for page if in cache, nothing otherwise
@@ -613,8 +682,9 @@ class page_hash_tree_cache {
     os::mapped_memory m_mapped_memory; ///< Mapped memory containing the LRU and entries
 
     // The following fields may already be initialized by existing mapped memory
-    lru &m_lru;                 ///< Recently used entries
-    std::span<entry> m_entries; ///< Array of page hash-tree cache entries
+    initialized_tag &m_initialized; ///< Whether cache has been initialized
+    lru &m_lru;                     ///< Recently used entries
+    std::span<entry> m_entries;     ///< Array of page hash-tree cache entries
 
     // The following fields are always initialized from scratch
     ankerl::unordered_dense::map<address_type, entry::ref> m_map; ///< Map from page addresses to corresponding entries

From 88690dd1d10d6def60e1e2ffdfd4f28a390e1534 Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Wed, 15 Oct 2025 18:47:36 -0300
Subject: [PATCH 78/82] test: add backing store tests

---
 src/cartesi-machine.lua           |   2 +-
 src/machine-address-ranges.cpp    |   3 +-
 src/machine-config.cpp            |   4 +-
 src/machine-config.h              |   2 +
 src/machine.cpp                   |  10 +-
 src/os-mapped-memory.cpp          |  17 +-
 tests/lua/cartesi/filesystem.lua  |  78 +++++
 tests/lua/cartesi/tabular.lua     |  59 +++-
 tests/lua/cartesi/utils.lua       |  26 ++
 tests/lua/mcycle-overflow.lua     |   4 +-
 tests/lua/spec-backing-stores.lua | 456 ++++++++++++++++++++++++++++++
 tests/lua/test-spec.lua           |   1 +
 12 files changed, 641 insertions(+), 21 deletions(-)
 create mode 100644 tests/lua/cartesi/filesystem.lua
 create mode 100644 tests/lua/cartesi/utils.lua
 create mode 100644 tests/lua/spec-backing-stores.lua

diff --git a/src/cartesi-machine.lua b/src/cartesi-machine.lua
index b5914f58f..6b598c742 100755
--- a/src/cartesi-machine.lua
+++ b/src/cartesi-machine.lua
@@ -2068,7 +2068,7 @@ echo "
 end
 
 for _, r in ipairs(memory_range_replace) do
-    main_machine:replace_memory_range(r.start, r.length, r.shared, r.image_filename)
+    main_machine:replace_memory_range(r)
 end
 
 local function dump_config(what, whatdef, out, indent)
diff --git a/src/machine-address-ranges.cpp b/src/machine-address-ranges.cpp
index 9941e384f..c9cb4a7a9 100644
--- a/src/machine-address-ranges.cpp
+++ b/src/machine-address-ranges.cpp
@@ -218,8 +218,9 @@ static void prepare_ar_backing_store_for_share(const backing_store_config &from_
             os::truncate_file(to_c.dpt_filename, dpt_length, true);
         }
         remover.add_file(to_c.dpt_filename);
+
+        os::change_writable(to_c.data_filename, !read_only);
     }
-    os::change_writable(to_c.data_filename, !read_only);
 }
 
 static void prepare_ar_backing_stores(const machine_config &c, scope_remove &remover) {
diff --git a/src/machine-config.cpp b/src/machine-config.cpp
index af2029e70..c57524426 100644
--- a/src/machine-config.cpp
+++ b/src/machine-config.cpp
@@ -55,11 +55,11 @@ std::string machine_config::get_dpt_filename(const std::string &dir, uint64_t st
 }
 
 std::string machine_config::get_sht_filename(const std::string &dir) {
-    return dir + "/global.sht";
+    return dir + "/hash_tree.sht";
 }
 
 std::string machine_config::get_phtc_filename(const std::string &dir) {
-    return dir + "/global.phtc";
+    return dir + "/hash_tree.phtc";
 }
 
 std::string machine_config::get_config_filename(const std::string &dir) {
diff --git a/src/machine-config.h b/src/machine-config.h
index aac63b3c0..72834b92f 100644
--- a/src/machine-config.h
+++ b/src/machine-config.h
@@ -210,6 +210,8 @@ struct machine_config final {
     machine_config &adjust_defaults();
 
     /// \brief Adjust backing stores to point to the directory
+    /// \param dir Directory where "config" is stored
+    /// \param sharing Sharing mode conversion policy to use for backing stores
     machine_config &adjust_backing_stores(const std::string &dir, sharing_mode sharing = sharing_mode::config);
 
     /// \brief Loads a machine config from a directory
diff --git a/src/machine.cpp b/src/machine.cpp
index 255b38af2..0ec09295c 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -395,7 +395,7 @@ void machine::store(const std::string &dir, sharing_mode sharing) const {
     remover.add_directory(dir);
 
     // Store config
-    remover.add_file(m_c.store(dir, sharing));
+    remover.add_file(m_c.store(dir));
 
     // Store all address ranges
     auto store_address_range = [&](const backing_store_config &c, const address_range &ar, bool read_only) {
@@ -418,10 +418,10 @@ void machine::store(const std::string &dir, sharing_mode sharing) const {
             remover.add_file(dpt_filename);
         } else { // Copy unshared backing store
             if (c.data_filename.empty()) {
-                throw std::runtime_error{"attempt to restore unbacked address range "s.append(ar.get_description())};
+                throw std::runtime_error{"attempt to rollback unbacked address range "s.append(ar.get_description())};
             }
             if (c.shared) {
-                throw std::runtime_error{"attempt to restore shared address range "s.append(ar.get_description())};
+                throw std::runtime_error{"attempt to rollback shared address range "s.append(ar.get_description())};
             }
             os::copy_file(c.data_filename, data_filename, ar.get_length());
             remover.add_file(data_filename);
@@ -462,8 +462,8 @@ void machine::store(const std::string &dir, sharing_mode sharing) const {
     } else {
         os::truncate_file(sht_filename, m_ht.get_sht_storage_data().size(), true);
         remover.add_file(sht_filename);
-        os::truncate_file(sht_filename, m_ht.get_phtc_storage_data().size(), true);
-        remover.add_file(sht_filename);
+        os::truncate_file(phtc_filename, m_ht.get_phtc_storage_data().size(), true);
+        remover.add_file(phtc_filename);
     }
 
     // Retain all stored files
diff --git a/src/os-mapped-memory.cpp b/src/os-mapped-memory.cpp
index 1eb93a5ef..0fb74ab94 100644
--- a/src/os-mapped-memory.cpp
+++ b/src/os-mapped-memory.cpp
@@ -144,6 +144,11 @@ mapped_memory::mapped_memory(uint64_t length, const mapped_memory_flags &flags,
 
         // Check backing file length mismatch
         if (backing_file_length != desired_backing_length) {
+            if (backing_file_length > desired_backing_length) {
+                throw std::runtime_error{"backing file '"s + backing_filename + "' length ("s +
+                    std::to_string(backing_file_length) + ") cannot be less than desired backing length ("s +
+                    std::to_string(desired_backing_length) + ")"s};
+            }
             if (flags.shared || !flags.backing_gap) {
                 throw std::runtime_error{"backing file '"s + backing_filename + "' length ("s +
                     std::to_string(backing_file_length) + ") does not match desired backing length ("s +
@@ -214,7 +219,7 @@ mapped_memory::mapped_memory(uint64_t length, const mapped_memory_flags &flags,
             if (flags.read_only) {
                 // We can't write on read-only mappings.
                 // This kind of mapping is unlikely to happen, so there is no need to support it.
-                throw std::system_error{errno, std::generic_category(),
+                throw std::runtime_error{
                     "possible non zero partial page when mapping backing file '"s + backing_filename + "' to memory"s};
             }
             // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
@@ -304,6 +309,11 @@ mapped_memory::mapped_memory(uint64_t length, const mapped_memory_flags &flags,
 
         // Check backing file length mismatch
         if (backing_file_length != desired_backing_length) {
+            if (backing_file_length > desired_backing_length) {
+                throw std::runtime_error{"backing file '"s + backing_filename + "' length ("s +
+                    std::to_string(backing_file_length) + ") cannot be less than desired backing length ("s +
+                    std::to_string(desired_backing_length) + ")"s};
+            }
             if (flags.shared || !flags.backing_gap) {
                 throw std::runtime_error{"backing file '"s + backing_filename + "' length ("s +
                     std::to_string(backing_file_length) + ") does not match desired backing length ("s +
@@ -455,6 +465,11 @@ mapped_memory::mapped_memory(uint64_t length, const mapped_memory_flags &flags,
 
         // Check backing file length mismatch
         if (backing_file_length != desired_backing_length) {
+            if (backing_file_length > desired_backing_length) {
+                throw std::runtime_error{"backing file '"s + backing_filename + "' length ("s +
+                    std::to_string(backing_file_length) + ") cannot be less than desired backing length ("s +
+                    std::to_string(desired_backing_length) + ")"s};
+            }
             if (flags.shared || !flags.backing_gap) {
                 throw std::runtime_error{"backing file '"s + backing_filename + "' length ("s +
                     std::to_string(backing_file_length) + ") does not match desired backing length ("s +
diff --git a/tests/lua/cartesi/filesystem.lua b/tests/lua/cartesi/filesystem.lua
new file mode 100644
index 000000000..b2e543463
--- /dev/null
+++ b/tests/lua/cartesi/filesystem.lua
@@ -0,0 +1,78 @@
+-- Copyright Cartesi and individual authors (see AUTHORS)
+-- SPDX-License-Identifier: LGPL-3.0-or-later
+--
+-- This program is free software: you can redistribute it and/or modify it under
+-- the terms of the GNU Lesser General Public License as published by the Free
+-- Software Foundation, either version 3 of the License, or (at your option) any
+-- later version.
+--
+-- This program is distributed in the hope that it will be useful, but WITHOUT ANY
+-- WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+-- PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+--
+-- You should have received a copy of the GNU Lesser General Public License along
+-- with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+--
+
+local utils = require("cartesi.utils")
+
+-- Module providing helpers for filesystem operations.
+local filesystem = {}
+
+-- Creates a temporary filename (an empty file is also created).
+function filesystem.temp_filename()
+    return (assert(os.tmpname()))
+end
+
+-- Returns a temporary path name (without creating a file or directory).
+function filesystem.temp_pathname()
+    local pathname = assert(os.tmpname())
+    assert(os.remove(pathname))
+    return pathname
+end
+
+-- Reads binary data from a file.
+function filesystem.read_file(filename)
+    local f <close> = assert(io.open(filename, "rb"))
+    return (assert(f:read("a")))
+end
+
+-- Writes a binary data to a new file (the file is overwritten if it exists).
+function filesystem.write_file(filename, data)
+    local f <close> = assert(io.open(filename, "wb"))
+    assert(f:write(data))
+end
+
+-- Returns the size of a file in bytes.
+function filesystem.get_file_size(filename)
+    local f <close> = assert(io.open(filename, "rb"))
+    return (assert(f:seek("end")))
+end
+
+-- Writes a binary data to a temporary file.
+function filesystem.write_temp_file(data)
+    local filename = filesystem.temp_filename()
+    local ok, err = pcall(function()
+        filesystem.write_file(filename, data)
+    end)
+    if not ok then
+        os.remove(filename)
+    end
+    assert(ok, err)
+    return filename
+end
+
+-- Writes a binary data to a temporary file that is auto removed when scoped ends.
+function filesystem.write_scope_temp_file(data)
+    local filename = filesystem.write_temp_file(data)
+    return utils.scope_exit(function()
+        filesystem.remove_file(filename)
+    end), filename
+end
+
+-- Removes a file.
+function filesystem.remove_file(filename)
+    assert(os.remove(filename))
+end
+
+return filesystem
diff --git a/tests/lua/cartesi/tabular.lua b/tests/lua/cartesi/tabular.lua
index 593f9bfbf..643c800b3 100644
--- a/tests/lua/cartesi/tabular.lua
+++ b/tests/lua/cartesi/tabular.lua
@@ -14,12 +14,12 @@
 -- with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 --
 
--- module to convert array tables into key-value tables
-local M = {}
+-- Module with helpers for table manipulations.
+local tabular = {}
 
--- convert a table with indexed rows into a table with named rows. e.g.
+-- Convert a table with indexed rows into a table with named rows. e.g.
 -- {"foo", 999} -> {name = "foo", cycles = 999} with keys described by md
-local function expand_row(metadata, row)
+function tabular.expand_row(metadata, row)
     local expanded_row = {}
     for key, val in ipairs(metadata) do
         expanded_row[val] = row[key]
@@ -27,27 +27,66 @@ local function expand_row(metadata, row)
     return expanded_row
 end
 
--- apply `expand_row` for each row of `t`. e.g.
+-- Apply `expand_row` for each row of `t`. e.g.
 -- {{ "foo", 999 }} -> {{name = "foo", cycles = 999}} with keys described by md
-M.expand = function(metadata, t)
+function tabular.expand(metadata, t)
     local expanded_t = {}
     for _, row in ipairs(t) do
-        expanded_t[#expanded_t + 1] = expand_row(metadata, row)
+        expanded_t[#expanded_t + 1] = tabular.expand_row(metadata, row)
     end
     return expanded_t
 end
 
-function M.clear(t)
+-- Clear all key-value pairs from table `t`.
+function tabular.clear(t)
     for k in pairs(t) do
         t[k] = nil
     end
 end
 
-function M.append(t, elems)
+-- Append all elements from `elems` to the end of table `t`.
+function tabular.append(t, elems)
     local n = #t
     for i = 1, #elems do
         t[n + i] = elems[i]
     end
 end
 
-return M
+local function deep_traverse_iter(t, path)
+    path = path or {}
+    for k, v in pairs(t) do
+        local current_path = {}
+        for i = 1, #path do
+            current_path[i] = path[i]
+        end
+        current_path[#current_path + 1] = k
+        if type(v) == "table" then
+            deep_traverse_iter(v, current_path)
+        else
+            coroutine.yield(current_path, k, v)
+        end
+    end
+end
+
+-- Iterator that recursively traverses all key-value pairs in table `t`,
+-- yielding the path to each value, its key, and the value itself.
+function tabular.deep_traverse(t)
+    return coroutine.wrap(function()
+        deep_traverse_iter(t)
+    end)
+end
+
+-- Recursively copy a table `t` and all its subtables.
+function tabular.deep_copy(t)
+    local copy = {}
+    for k, v in pairs(t) do
+        if type(v) == "table" then
+            copy[k] = tabular.deep_copy(v)
+        else
+            copy[k] = v
+        end
+    end
+    return copy
+end
+
+return tabular
diff --git a/tests/lua/cartesi/utils.lua b/tests/lua/cartesi/utils.lua
new file mode 100644
index 000000000..16fed6a01
--- /dev/null
+++ b/tests/lua/cartesi/utils.lua
@@ -0,0 +1,26 @@
+-- Copyright Cartesi and individual authors (see AUTHORS)
+-- SPDX-License-Identifier: LGPL-3.0-or-later
+--
+-- This program is free software: you can redistribute it and/or modify it under
+-- the terms of the GNU Lesser General Public License as published by the Free
+-- Software Foundation, either version 3 of the License, or (at your option) any
+-- later version.
+--
+-- This program is distributed in the hope that it will be useful, but WITHOUT ANY
+-- WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+-- PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+--
+-- You should have received a copy of the GNU Lesser General Public License along
+-- with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
+--
+
+-- Module providing utilities.
+local utils = {}
+
+-- Executes a callback when the scope exits.
+-- REMARKS: Use <close> on its returned value to make it behave deterministically.
+function utils.scope_exit(callback)
+    return setmetatable({}, { __gc = callback, __close = callback })
+end
+
+return utils
diff --git a/tests/lua/mcycle-overflow.lua b/tests/lua/mcycle-overflow.lua
index 854520e14..9fa47f454 100755
--- a/tests/lua/mcycle-overflow.lua
+++ b/tests/lua/mcycle-overflow.lua
@@ -25,8 +25,10 @@ local MAX_UARCH_CYCLE = cartesi.UARCH_CYCLE_MAX
 local function build_machine()
     local config = {
         ram = {
-            image_filename = test_util.tests_path .. "mcycle_overflow.bin",
             length = 32 << 20,
+            backing_store = {
+                data_filename = test_util.tests_path .. "mcycle_overflow.bin",
+            },
         },
     }
     local machine = cartesi.machine(config)
diff --git a/tests/lua/spec-backing-stores.lua b/tests/lua/spec-backing-stores.lua
new file mode 100644
index 000000000..d10876416
--- /dev/null
+++ b/tests/lua/spec-backing-stores.lua
@@ -0,0 +1,456 @@
+--[[
+Test suite for loading and storing machines.
+]]
+
+local lester = require("cartesi.third-party.lester")
+local cartesi = require("cartesi")
+local filesystem = require("cartesi.filesystem")
+local utils = require("cartesi.utils")
+local tabular = require("cartesi.tabular")
+local tests_util = require("cartesi.tests.util")
+local describe, it, expect = lester.describe, lester.it, lester.expect
+
+describe("backing stores", function()
+    local a_data = string.rep("A", 0x2000)
+    local b_data = string.rep("B", 0x2000)
+    local trunc_ro_data = string.rep("C", 0x2000)
+    local _ <close>, rw_data_filename = filesystem.write_scope_temp_file(a_data)
+    local _ <close>, ro_data_filename = filesystem.write_scope_temp_file(b_data)
+    local _ <close>, trunc_ro_data_filename = filesystem.write_scope_temp_file(trunc_ro_data)
+
+    local base_machine_config = {
+        ram = {
+            length = 0x10000,
+            backing_store = {
+                data_filename = tests_util.tests_path .. "rv64ui-p-addi.bin",
+            },
+        },
+        flash_drive = {
+            { -- read/write + backing file
+                backing_store = {
+                    data_filename = rw_data_filename,
+                },
+            },
+            { -- read only + backing file
+                read_only = true,
+                backing_store = {
+                    data_filename = ro_data_filename,
+                },
+            },
+            { -- read/write + backing file + in-memory truncate
+                length = 0x3000,
+                backing_store = {
+                    data_filename = trunc_ro_data_filename,
+                },
+            },
+            { -- read/write + no backing file
+                length = 0x1000,
+            },
+            { -- read only + no backing file
+                length = 0x1000,
+                read_only = true,
+            },
+        },
+        hash_tree = {
+            phtc_size = 32,
+        },
+    }
+
+    it("should store a machine with sharing mode all", function()
+        local stored_dirname = filesystem.temp_pathname()
+        local expected_root_hash
+
+        do -- store new machine
+            local machine <close> = cartesi.machine(base_machine_config)
+            machine:run()
+            expected_root_hash = machine:get_root_hash()
+            machine:store(stored_dirname, cartesi.SHARING_ALL)
+        end
+        local _ <close> = utils.scope_exit(function()
+            cartesi.machine:remove_stored(stored_dirname)
+        end)
+
+        do -- load stored machine
+            local machine <close> = cartesi.machine(stored_dirname, {}, cartesi.SHARING_NONE)
+            expect.equal(machine:get_root_hash(), expected_root_hash)
+        end
+    end)
+
+    it("should store a machine with sharing mode none", function()
+        local stored_dirname = filesystem.temp_pathname()
+        local cloned_dirname = filesystem.temp_pathname()
+        local expected_root_hash
+
+        do -- store new machine
+            local machine <close> = cartesi.machine(base_machine_config)
+            machine:store(stored_dirname)
+            expected_root_hash = machine:get_root_hash()
+        end
+        local _ <close> = utils.scope_exit(function()
+            cartesi.machine:remove_stored(stored_dirname)
+        end)
+
+        do -- load stored machine and store a clone
+            local machine <close> = cartesi.machine(stored_dirname, {}, cartesi.SHARING_NONE)
+            expect.equal(machine:get_root_hash(), expected_root_hash)
+            machine:run()
+            machine:store(cloned_dirname, cartesi.SHARING_NONE)
+        end
+        local _ <close> = utils.scope_exit(function()
+            cartesi.machine:remove_stored(cloned_dirname)
+        end)
+
+        do -- load cloned machine
+            local machine <close> = cartesi.machine(cloned_dirname, {}, cartesi.SHARING_NONE)
+            expect.equal(machine:get_root_hash(), expected_root_hash)
+        end
+    end)
+
+    it("should store a machine with sharing mode config", function()
+        local _ <close>, shared_data_filename = filesystem.write_scope_temp_file(a_data)
+        local stored_dirname = filesystem.temp_pathname()
+        local cloned_dirname = filesystem.temp_pathname()
+        local root_drive = {
+            start = 0x0080000000000000,
+            length = #a_data,
+            backing_store = {
+                data_filename = shared_data_filename,
+                shared = true,
+            },
+        }
+        local expected_root_hash
+
+        do -- store new machine
+            local config = tabular.deep_copy(base_machine_config)
+            config.flash_drive[1] = root_drive
+            local machine <close> = cartesi.machine(config)
+            machine:store(stored_dirname)
+            machine:write_memory(root_drive.start, string.rep("X", root_drive.length))
+            expected_root_hash = machine:get_root_hash()
+        end
+        local _ <close> = utils.scope_exit(function()
+            cartesi.machine:remove_stored(stored_dirname)
+        end)
+
+        do -- load stored machine and store only configured drives
+            local machine <close> = cartesi.machine(stored_dirname, {}, cartesi.SHARING_CONFIG)
+            machine:write_memory(root_drive.start, string.rep("X", root_drive.length))
+            machine:run()
+            machine:store(cloned_dirname, cartesi.SHARING_CONFIG)
+        end
+        local _ <close> = utils.scope_exit(function()
+            cartesi.machine:remove_stored(cloned_dirname)
+        end)
+
+        do -- check stored machine
+            local machine <close> = cartesi.machine(stored_dirname, {}, cartesi.SHARING_NONE)
+            expect.equal(machine:read_reg("mcycle"), 0)
+            expect.equal(machine:get_root_hash(), expected_root_hash)
+        end
+        do -- check cloned machine
+            local machine <close> = cartesi.machine(cloned_dirname, {}, cartesi.SHARING_NONE)
+            expect.equal(machine:read_reg("mcycle"), 0)
+            expect.equal(machine:get_root_hash(), expected_root_hash)
+        end
+    end)
+
+    it("should clone a stored machine", function()
+        local stored_dirname = filesystem.temp_pathname()
+        local cloned_dirname = filesystem.temp_pathname()
+        local expected_mid_root_hash
+        local expected_end_root_hash
+
+        do -- store new machine
+            local machine <close> = cartesi.machine(base_machine_config, {})
+            machine:run(100)
+            machine:store(stored_dirname)
+            expected_mid_root_hash = machine:get_root_hash()
+            machine:run()
+            expected_end_root_hash = machine:get_root_hash()
+        end
+        local _ <close> = utils.scope_exit(function()
+            cartesi.machine:remove_stored(stored_dirname)
+        end)
+
+        -- clone machine
+        cartesi.machine:clone_stored(stored_dirname, cloned_dirname)
+        local _ <close> = utils.scope_exit(function()
+            cartesi.machine:remove_stored(cloned_dirname)
+        end)
+
+        do -- load cloned machine
+            local machine <close> = cartesi.machine(cloned_dirname, {}, cartesi.SHARING_NONE)
+            expect.equal(machine:get_root_hash(), expected_mid_root_hash)
+            machine:run()
+            expect.equal(machine:get_root_hash(), expected_end_root_hash)
+        end
+
+        do -- load stored machine
+            local machine <close> = cartesi.machine(stored_dirname, {}, cartesi.SHARING_NONE)
+            expect.equal(machine:get_root_hash(), expected_mid_root_hash)
+            machine:run()
+            expect.equal(machine:get_root_hash(), expected_end_root_hash)
+        end
+    end)
+
+    it("should create a machine fully mapped on disk", function()
+        local stored_dirname = filesystem.temp_pathname()
+        local expected_root_hash
+
+        do -- store new machine
+            local machine <close> = cartesi.machine(base_machine_config, {}, stored_dirname)
+            machine:run()
+            expected_root_hash = machine:get_root_hash()
+        end
+        local _ <close> = utils.scope_exit(function()
+            cartesi.machine:remove_stored(stored_dirname)
+        end)
+
+        do -- load stored machine
+            local machine <close> = cartesi.machine(stored_dirname, {}, cartesi.SHARING_NONE)
+            expect.equal(machine:get_root_hash(), expected_root_hash)
+        end
+    end)
+
+    it("should load a machine fully mapped on disk", function()
+        local stored_dirname = filesystem.temp_pathname()
+        local expected_mid_root_hash
+        local expected_end_root_hash
+
+        do -- store new machine
+            local machine <close> = cartesi.machine(base_machine_config, {})
+            machine:store(stored_dirname)
+            expected_mid_root_hash = machine:get_root_hash()
+            machine:run()
+            expected_end_root_hash = machine:get_root_hash()
+        end
+        local _ <close> = utils.scope_exit(function()
+            cartesi.machine:remove_stored(stored_dirname)
+        end)
+
+        do -- load stored machine
+            local machine <close> = cartesi.machine(stored_dirname, {}, cartesi.SHARING_ALL)
+            expect.equal(machine:get_root_hash(), expected_mid_root_hash)
+            machine:run()
+            expect.equal(machine:get_root_hash(), expected_end_root_hash)
+        end
+
+        do -- load stored machine again
+            local machine <close> = cartesi.machine(stored_dirname, {}, cartesi.SHARING_ALL)
+            expect.equal(machine:get_root_hash(), expected_end_root_hash)
+        end
+    end)
+
+    it("should replace memory range", function()
+        local stored1_dirname = filesystem.temp_pathname()
+        local stored2_dirname = filesystem.temp_pathname()
+        local expected1_root_hash
+        local expected2_root_hash
+
+        do -- store new machine
+            local machine <close> = cartesi.machine(base_machine_config, {})
+            expected1_root_hash = machine:get_root_hash()
+            machine:store(stored1_dirname)
+            machine:write_memory(0x0080000000000000, 0x2000, string.rep("X", 0x2000))
+            expected2_root_hash = machine:get_root_hash()
+            machine:store(stored2_dirname)
+        end
+        local _ <close> = utils.scope_exit(function()
+            cartesi.machine:remove_stored(stored1_dirname)
+            cartesi.machine:remove_stored(stored2_dirname)
+        end)
+
+        do -- load stored machine
+            local machine <close> = cartesi.machine(stored1_dirname, {}, cartesi.SHARING_NONE)
+            expect.equal(machine:get_root_hash(), expected1_root_hash)
+            machine:replace_memory_range({
+                start = 0x0080000000000000,
+                length = 0x2000,
+                backing_store = {
+                    data_filename = stored2_dirname .. "/0080000000000000-2000.bin",
+                },
+            })
+            expect.equal(machine:get_root_hash(), expected2_root_hash)
+        end
+    end)
+
+    it("should replace memory range with existing clean page tree", function()
+        local stored1_dirname = filesystem.temp_pathname()
+        local stored2_dirname = filesystem.temp_pathname()
+        local expected1_root_hash
+        local expected2_root_hash
+
+        do -- store new machine
+            local machine <close> = cartesi.machine(base_machine_config, {})
+            expected1_root_hash = machine:get_root_hash()
+            machine:store(stored1_dirname)
+            machine:write_memory(0x0080000000000000, 0x2000, string.rep("X", 0x2000))
+            expected2_root_hash = machine:get_root_hash()
+            machine:store(stored2_dirname)
+        end
+        local _ <close> = utils.scope_exit(function()
+            cartesi.machine:remove_stored(stored1_dirname)
+            cartesi.machine:remove_stored(stored2_dirname)
+        end)
+
+        do -- load stored machine
+            local machine <close> = cartesi.machine(stored1_dirname, {}, cartesi.SHARING_NONE)
+            expect.equal(machine:get_root_hash(), expected1_root_hash)
+            machine:replace_memory_range({
+                start = 0x0080000000000000,
+                length = 0x2000,
+                backing_store = {
+                    data_filename = stored2_dirname .. "/0080000000000000-2000.bin",
+                    dht_filename = stored2_dirname .. "/0080000000000000-2000.dht",
+                    dpt_filename = stored2_dirname .. "/0080000000000000-2000.dpt",
+                },
+            })
+            expect.equal(machine:get_root_hash(), expected2_root_hash)
+        end
+    end)
+
+    it("should create a machine with new shared backing stores", function()
+        local filename_prefix = filesystem.temp_pathname()
+        local expected_root_hash
+        local function make_machine(create)
+            return cartesi.machine({
+                processor = {
+                    backing_store = {
+                        create = create,
+                        shared = create,
+                        data_filename = filename_prefix .. "-processor.bin",
+                        dht_filename = filename_prefix .. "-processor.dht",
+                        dpt_filename = filename_prefix .. "-processor.dpt",
+                    },
+                },
+                pmas = {
+                    backing_store = {
+                        create = create,
+                        shared = create,
+                        data_filename = filename_prefix .. "-pmas.bin",
+                        dht_filename = filename_prefix .. "-pmas.dht",
+                        dpt_filename = filename_prefix .. "-pmas.dpt",
+                    },
+                },
+                ram = {
+                    backing_store = {
+                        create = create,
+                        shared = create,
+                        data_filename = filename_prefix .. "-ram.bin",
+                        dht_filename = filename_prefix .. "-ram.dht",
+                        dpt_filename = filename_prefix .. "-ram.dpt",
+                    },
+                    length = 0x4000,
+                },
+                dtb = {
+                    backing_store = {
+                        create = create,
+                        shared = create,
+                        data_filename = filename_prefix .. "-dtb.bin",
+                        dht_filename = filename_prefix .. "-dtb.dht",
+                        dpt_filename = filename_prefix .. "-dtb.dpt",
+                    },
+                },
+                flash_drive = {
+                    {
+                        length = 8192,
+                        backing_store = {
+                            create = create,
+                            shared = create,
+                            data_filename = filename_prefix .. "-drive0.bin",
+                            dht_filename = filename_prefix .. "-drive0.dht",
+                            dpt_filename = filename_prefix .. "-drive0.dpt",
+                        },
+                    },
+                },
+                cmio = {
+                    rx_buffer = {
+                        backing_store = {
+                            create = create,
+                            shared = create,
+                            data_filename = filename_prefix .. "-cmio_rx.bin",
+                            dht_filename = filename_prefix .. "-cmio_rx.dht",
+                            dpt_filename = filename_prefix .. "-cmio_rx.dpt",
+                        },
+                    },
+                    tx_buffer = {
+                        backing_store = {
+                            create = create,
+                            shared = create,
+                            data_filename = filename_prefix .. "-cmio_tx.bin",
+                            dht_filename = filename_prefix .. "-cmio_tx.dht",
+                            dpt_filename = filename_prefix .. "-cmio_tx.dpt",
+                        },
+                    },
+                },
+                uarch = {
+                    processor = {
+                        backing_store = {
+                            create = create,
+                            shared = create,
+                            data_filename = filename_prefix .. "-uarch_processor.bin",
+                            dht_filename = filename_prefix .. "-uarch_processor.dht",
+                            dpt_filename = filename_prefix .. "-uarch_processor.dpt",
+                        },
+                    },
+                    ram = {
+                        backing_store = {
+                            create = create,
+                            shared = create,
+                            data_filename = filename_prefix .. "-uarch_ram.bin",
+                            dht_filename = filename_prefix .. "-uarch_ram.dht",
+                            dpt_filename = filename_prefix .. "-uarch_ram.dpt",
+                        },
+                    },
+                },
+                hash_tree = {
+                    phtc_size = 32,
+                    create = create,
+                    shared = create,
+                    phtc_filename = filename_prefix .. "-hash_tree.phtc",
+                    sht_filename = filename_prefix .. "-hash_tree.sht",
+                },
+            })
+        end
+
+        local initial_config
+        do -- store machine address ranges
+            local machine <close> = make_machine(true)
+            expected_root_hash = machine:get_root_hash()
+            initial_config = machine:get_initial_config()
+        end
+        local _ <close> = utils.scope_exit(function()
+            for _, k, v in tabular.deep_traverse(initial_config) do
+                if k:find("^%w+_filename$") then
+                    filesystem.remove_file(v)
+                end
+            end
+        end)
+
+        do -- load machine address ranges
+            local machine <close> = make_machine()
+            expect.equal(machine:get_root_hash(), expected_root_hash)
+        end
+    end)
+
+    it("should truncate backing store file to a bigger size", function()
+        local ram_data = string.rep("\x00", 0x1000)
+        local _ <close>, ram_filename = filesystem.write_scope_temp_file(ram_data)
+        local expected_ram_size = 0x2000
+
+        do
+            local _ <close> = cartesi.machine({
+                ram = {
+                    length = expected_ram_size,
+                    backing_store = {
+                        data_filename = ram_filename,
+                        truncate = true,
+                        shared = true,
+                    },
+                },
+            })
+        end
+
+        expect.equal(filesystem.get_file_size(ram_filename), expected_ram_size)
+    end)
+end)
diff --git a/tests/lua/test-spec.lua b/tests/lua/test-spec.lua
index 1046d8ea6..047b82d39 100755
--- a/tests/lua/test-spec.lua
+++ b/tests/lua/test-spec.lua
@@ -24,6 +24,7 @@ lester.parse_args()
 require("spec-hash-functions")
 require("spec-hash-tree")
 require("spec-collect-hashes")
+require("spec-backing-stores")
 
 lester.report() -- Print overall statistic of the tests run.
 lester.exit() -- Exit with success if all tests passed.

From 728add6ac32b8870906a72fa5dd7710ca77e1a4f Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Tue, 21 Oct 2025 14:48:11 -0300
Subject: [PATCH 79/82] chore: bump machine-guest-tools to v0.17.2

---
 tests/dependencies        | 2 +-
 tests/dependencies.sha256 | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/tests/dependencies b/tests/dependencies
index b50e51e01..abc74f48c 100644
--- a/tests/dependencies
+++ b/tests/dependencies
@@ -1,2 +1,2 @@
-https://github.com/cartesi/machine-guest-tools/releases/download/v0.17.1/rootfs-tools.ext2
+https://github.com/cartesi/machine-guest-tools/releases/download/v0.17.2/rootfs-tools.ext2
 https://github.com/cartesi/machine-linux-image/releases/download/v0.20.0/linux-6.5.13-ctsi-1-v0.20.0.bin
diff --git a/tests/dependencies.sha256 b/tests/dependencies.sha256
index 77d484b58..fca099abe 100644
--- a/tests/dependencies.sha256
+++ b/tests/dependencies.sha256
@@ -1,2 +1,2 @@
 65dd100ff6204346ac2f50f772721358b5c1451450ceb39a154542ee27b4c947  build/images/linux-6.5.13-ctsi-1-v0.20.0.bin
-e5d1f7c449e24314e0bcea1446e1c754a737aa7685b8c8d285a5e7eefa6b8044  build/images/rootfs-tools.ext2
+675a49e3c9bada29f25d5b559707b34553b94280c03f44ccb8203c2cf453b541  build/images/rootfs-tools.ext2

From dddbb5e898e30c64e41162febd133ba75249c1fc Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Tue, 21 Oct 2025 14:16:45 -0300
Subject: [PATCH 80/82] chore: bump emulator version to 0.20.0

---
 src/Makefile | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/Makefile b/src/Makefile
index 4c82768c6..595bca814 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -14,11 +14,11 @@
 # with this program (see COPYING). If not, see <https://www.gnu.org/licenses/>.
 #
 
-EMULATOR_MARCHID=19
+EMULATOR_MARCHID=20
 
 # Every new emulator release should bump these constants
 EMULATOR_VERSION_MAJOR=0
-EMULATOR_VERSION_MINOR=19
+EMULATOR_VERSION_MINOR=20
 EMULATOR_VERSION_PATCH=0
 EMULATOR_VERSION_LABEL=
 

From 362697bb06937ea9abe126d70c44760bd1196341 Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Thu, 23 Oct 2025 14:27:38 -0300
Subject: [PATCH 81/82] fix: linting errors with new clang-tidy

---
 .clang-tidy                                   |  1 +
 src/collect-uarch-cycle-hashes-state-access.h |  6 +-
 src/dirty-page-tree.h                         |  3 +-
 src/dtb.cpp                                   |  2 +-
 src/i-accept-scoped-notes.h                   |  2 +-
 src/jsonrpc-remote-machine.cpp                | 78 +++++++++----------
 src/machine-config.cpp                        |  2 +-
 src/os-mapped-memory.cpp                      |  8 +-
 src/os-mapped-memory.h                        |  6 +-
 src/os.cpp                                    |  2 +-
 src/soft-float.h                              |  2 +-
 src/virtio-p9fs-address-range.cpp             | 18 ++---
 uarch/uarch-runtime.cpp                       |  2 +-
 13 files changed, 70 insertions(+), 62 deletions(-)

diff --git a/.clang-tidy b/.clang-tidy
index 71ed74611..9b98f5647 100644
--- a/.clang-tidy
+++ b/.clang-tidy
@@ -38,5 +38,6 @@ Checks: >-
   -readability-identifier-length,
   -readability-magic-numbers,
   -readability-enum-initial-value,
+  -readability-use-concise-preprocessor-directives,
 WarningsAsErrors: >-
   *
diff --git a/src/collect-uarch-cycle-hashes-state-access.h b/src/collect-uarch-cycle-hashes-state-access.h
index 536c0edda..c8acc53a7 100644
--- a/src/collect-uarch-cycle-hashes-state-access.h
+++ b/src/collect-uarch-cycle-hashes-state-access.h
@@ -75,7 +75,8 @@ class collect_uarch_cycle_hashes_state_access :
         static_assert(shadow_uarch_state_get_what(AR_SHADOW_UARCH_STATE_START) ==
                 shadow_uarch_state_what::uarch_halt_flag,
             "code assumes halt_flag is the first shadow uarch register");
-        const auto *regs = &m_m.get_uarch_state().registers.halt_flag;
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        const auto *regs = reinterpret_cast<uint64_t *>(&m_m.get_uarch_state().registers);
         return regs[(static_cast<uint64_t>(what) - AR_SHADOW_UARCH_STATE_START) / sizeof(uint64_t)];
     }
 
@@ -84,7 +85,8 @@ class collect_uarch_cycle_hashes_state_access :
         static_assert(shadow_uarch_state_get_what(AR_SHADOW_UARCH_STATE_START) ==
                 shadow_uarch_state_what::uarch_halt_flag,
             "code assumes halt_flag is the first shadow uarch register");
-        auto *regs = &m_m.get_uarch_state().registers.halt_flag;
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+        auto *regs = reinterpret_cast<uint64_t *>(&m_m.get_uarch_state().registers);
         regs[(static_cast<uint64_t>(what) - AR_SHADOW_UARCH_STATE_START) / sizeof(uint64_t)] = val;
         mark_dirty_word(static_cast<uint64_t>(what));
     }
diff --git a/src/dirty-page-tree.h b/src/dirty-page-tree.h
index 865eb63a8..64c069d3b 100644
--- a/src/dirty-page-tree.h
+++ b/src/dirty-page-tree.h
@@ -21,6 +21,7 @@
 /// \brief Dirty map as a complete tree
 
 #include <algorithm>
+#include <cstddef>
 #include <cstdint>
 #include <initializer_list>
 #include <iostream>
@@ -101,7 +102,7 @@ class dirty_page_tree final : public i_dirty_page_tree {
         m_mapped_memory{get_storage_length(level_count, leaf_count), os::mapped_memory_flags{.shared = shared},
             backing_filename},
         // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        m_tree{reinterpret_cast<status_type *>(m_mapped_memory.get_ptr()), size_type{1} << level_count} {
+        m_tree{reinterpret_cast<status_type *>(m_mapped_memory.get_ptr()), size_t{1} << level_count} {
         if (!is_initialized()) {
             const auto lp = m_leaf_positions;
             const auto first_leaf = *lp.begin();
diff --git a/src/dtb.cpp b/src/dtb.cpp
index 6b36a569a..349072be4 100644
--- a/src/dtb.cpp
+++ b/src/dtb.cpp
@@ -51,7 +51,7 @@ static std::string misa_to_isa_string(uint64_t misa) {
 
 void dtb_init(const machine_config &c, unsigned char *dtb_start, uint64_t dtb_length) {
     using namespace std::string_literals;
-    enum : uint32_t { INTC_PHANDLE = 1, PLIC_PHANDLE };
+    enum : uint32_t { INTC_PHANDLE = 1, PLIC_PHANDLE }; // NOLINT(cppcoreguidelines-use-enum-class)
     constexpr uint32_t X_HOST = 13;
     constexpr uint32_t BOOTARGS_MAX_LEN = 4096;
 
diff --git a/src/i-accept-scoped-notes.h b/src/i-accept-scoped-notes.h
index 08f3ccb43..d568d84a0 100644
--- a/src/i-accept-scoped-notes.h
+++ b/src/i-accept-scoped-notes.h
@@ -94,7 +94,7 @@ class i_accept_scoped_notes { // CRTP
 
     /// \brief Adds annotations to the state, bracketing a scope
     /// \param text String with the text for the annotation
-    /// \returns An object that, when constructed and destroyed issues an annonation.
+    /// \returns An object that, when constructed and destroyed issues an annotation.
     auto make_scoped_note(const char *text) const {
         return derived().do_make_scoped_note(text);
     }
diff --git a/src/jsonrpc-remote-machine.cpp b/src/jsonrpc-remote-machine.cpp
index 733f03e38..7ded32e1e 100644
--- a/src/jsonrpc-remote-machine.cpp
+++ b/src/jsonrpc-remote-machine.cpp
@@ -380,7 +380,7 @@ struct http_handler : std::enable_shared_from_this<http_handler> {
 //------------------------------------------------------------------------------
 
 /// \brief Names for JSONRPC error codes
-enum jsonrpc_error_code : int {
+enum class jsonrpc_error_code : int {
     parse_error = -32700,      ///< When the request failed to parse
     invalid_request = -32600,  ///< When the request was invalid (missing fields, wrong types etc)
     method_not_found = -32601, ///< When the method was not found
@@ -647,7 +647,7 @@ static std::tuple<ARGS...> parse_array_args(const json &j) {
 /// \param param_name Name of each parameter
 /// \returns tuple with arguments
 template <typename... ARGS, size_t... I>
-static std::tuple<ARGS...> parse_object_args(const json &j, const char *(&param_name)[sizeof...(ARGS)],
+static std::tuple<ARGS...> parse_object_args(const json &j, const char *const (&param_name)[sizeof...(ARGS)],
     std::index_sequence<I...> /*unused*/) {
     std::tuple<ARGS...> tp;
     (cartesi::ju_get_field(j, std::string(param_name[I]), std::get<I>(tp)), ...);
@@ -660,7 +660,7 @@ static std::tuple<ARGS...> parse_object_args(const json &j, const char *(&param_
 /// \param param_name Name of each parameter
 /// \returns tuple with arguments
 template <typename... ARGS>
-static std::tuple<ARGS...> parse_object_args(const json &j, const char *(&param_name)[sizeof...(ARGS)]) {
+static std::tuple<ARGS...> parse_object_args(const json &j, const char *const (&param_name)[sizeof...(ARGS)]) {
     return parse_object_args<ARGS...>(j, param_name, std::make_index_sequence<sizeof...(ARGS)>{});
 }
 
@@ -670,7 +670,7 @@ static std::tuple<ARGS...> parse_object_args(const json &j, const char *(&param_
 /// \param param_name Name of each parameter
 /// \returns tuple with arguments
 template <typename... ARGS>
-static std::tuple<ARGS...> parse_args(const json &j, const char *(&param_name)[sizeof...(ARGS)]) {
+static std::tuple<ARGS...> parse_args(const json &j, const char *const (&param_name)[sizeof...(ARGS)]) {
     constexpr auto mandatory_params = count_mandatory_params<ARGS...>();
     if (!j.contains("params")) {
         if constexpr (mandatory_params == 0) {
@@ -825,7 +825,7 @@ static json jsonrpc_fork_handler(const json &j, const std::shared_ptr<http_sessi
 /// \details Changes the address the server is listening to.
 /// After this call, all new connections should be established using the new server address.
 static json jsonrpc_rebind_handler(const json &j, const std::shared_ptr<http_session> &session) {
-    static const char *param_name[] = {"address"};
+    static const char *const param_name[] = {"address"};
     auto args = parse_args<std::string>(j, param_name);
     const std::string new_server_address = std::get<0>(args);
     const tcp::endpoint new_local_endpoint = address_to_endpoint(new_server_address);
@@ -848,7 +848,7 @@ static json jsonrpc_machine_load_handler(const json &j, const std::shared_ptr<ht
     if (session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "machine exists");
     }
-    static const char *param_name[] = {"directory", "runtime_config", "sharing"};
+    static const char *const param_name[] = {"directory", "runtime_config", "sharing"};
     auto args = parse_args<std::string, cartesi::optional_param<cartesi::machine_runtime_config>,
         cartesi::optional_param<cartesi::sharing_mode>>(j, param_name);
     switch (count_args(args)) {
@@ -878,7 +878,7 @@ static json jsonrpc_machine_create_handler(const json &j, const std::shared_ptr<
     if (session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "machine exists");
     }
-    static const char *param_name[] = {"config", "runtime_config", "directory"};
+    static const char *const param_name[] = {"config", "runtime_config", "directory"};
     auto args = parse_args<cartesi::machine_config, cartesi::optional_param<cartesi::machine_runtime_config>,
         cartesi::optional_param<std::string>>(j, param_name);
     switch (count_args(args)) {
@@ -908,7 +908,7 @@ static json jsonrpc_machine_collect_mcycle_root_hashes(const json &j, const std:
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"mcycle_end", "mcycle_period", "mcycle_phase", "log2_bundle_mcycle_count",
+    static const char *const param_name[] = {"mcycle_end", "mcycle_period", "mcycle_phase", "log2_bundle_mcycle_count",
         "previous_back_tree"};
     auto args =
         parse_args<uint64_t, uint64_t, uint64_t, uint64_t, std::optional<cartesi::back_merkle_tree>>(j, param_name);
@@ -931,7 +931,7 @@ static json jsonrpc_machine_collect_uarch_cycle_root_hashes(const json &j,
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"mcycle_end", "log2_bundle_uarch_cycle_count"};
+    static const char *const param_name[] = {"mcycle_end", "log2_bundle_uarch_cycle_count"};
     auto args = parse_args<uint64_t, uint64_t>(j, param_name);
     auto mcycle_end = std::get<0>(args);
     auto log2_bundle_uarch_cycle_count = std::get<1>(args);
@@ -956,7 +956,7 @@ static json jsonrpc_machine_destroy_handler(const json &j, const std::shared_ptr
 /// \returns JSON response object
 /// \details This method causes the server to sleep for a number of milliseconds before the next call
 static json jsonrpc_delay_next_request_handler(const json &j, const std::shared_ptr<http_session> &session) {
-    static const char *param_name[] = {"ms"};
+    static const char *const param_name[] = {"ms"};
     auto args = parse_args<uint64_t>(j, param_name);
     session->handler->delay = std::get<0>(args);
     return jsonrpc_response_ok(j);
@@ -989,7 +989,7 @@ static json jsonrpc_machine_store_handler(const json &j, const std::shared_ptr<h
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"directory", "sharing"};
+    static const char *const param_name[] = {"directory", "sharing"};
     auto args = parse_args<std::string, cartesi::sharing_mode>(j, param_name);
     session->handler->machine->store(std::get<0>(args), std::get<1>(args));
     return jsonrpc_response_ok(j);
@@ -1003,7 +1003,7 @@ static json jsonrpc_machine_clone_stored_handler(const json &j, const std::share
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"from_dir", "to_dir"};
+    static const char *const param_name[] = {"from_dir", "to_dir"};
     auto args = parse_args<std::string, std::string>(j, param_name);
     cartesi::machine::clone_stored(std::get<0>(args), std::get<1>(args));
     return jsonrpc_response_ok(j);
@@ -1017,7 +1017,7 @@ static json jsonrpc_machine_remove_stored_handler(const json &j, const std::shar
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"dir"};
+    static const char *const param_name[] = {"dir"};
     auto args = parse_args<std::string>(j, param_name);
     cartesi::machine::remove_stored(std::get<0>(args));
     return jsonrpc_response_ok(j);
@@ -1031,7 +1031,7 @@ static json jsonrpc_machine_run_handler(const json &j, const std::shared_ptr<htt
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"mcycle_end"};
+    static const char *const param_name[] = {"mcycle_end"};
     auto args = parse_args<uint64_t>(j, param_name);
     auto reason = session->handler->machine->run(std::get<0>(args));
     return jsonrpc_response_ok(j, reason);
@@ -1045,7 +1045,7 @@ static json jsonrpc_machine_log_step_handler(const json &j, const std::shared_pt
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"mcycle_count", "filename"};
+    static const char *const param_name[] = {"mcycle_count", "filename"};
     auto args = parse_args<uint64_t, std::string>(j, param_name);
     auto reason = session->handler->machine->log_step(std::get<0>(args), std::get<1>(args));
     return jsonrpc_response_ok(j, reason);
@@ -1059,7 +1059,7 @@ static json jsonrpc_machine_run_uarch_handler(const json &j, const std::shared_p
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"uarch_cycle_end"};
+    static const char *const param_name[] = {"uarch_cycle_end"};
     auto args = parse_args<uint64_t>(j, param_name);
     auto reason = session->handler->machine->run_uarch(std::get<0>(args));
     return jsonrpc_response_ok(j, reason);
@@ -1073,7 +1073,7 @@ static json jsonrpc_machine_log_step_uarch_handler(const json &j, const std::sha
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"log_type"};
+    static const char *const param_name[] = {"log_type"};
     auto args = parse_args<cartesi::not_default_constructible<cartesi::access_log::type>>(j, param_name);
     // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
     return jsonrpc_response_ok(j, session->handler->machine->log_step_uarch(std::get<0>(args).value()));
@@ -1087,7 +1087,7 @@ static json jsonrpc_machine_log_reset_uarch_handler(const json &j, const std::sh
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"log_type"};
+    static const char *const param_name[] = {"log_type"};
     auto args = parse_args<cartesi::not_default_constructible<cartesi::access_log::type>>(j, param_name);
     // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
     return jsonrpc_response_ok(j, session->handler->machine->log_reset_uarch(std::get<0>(args).value()));
@@ -1099,7 +1099,7 @@ static json jsonrpc_machine_log_reset_uarch_handler(const json &j, const std::sh
 /// \returns JSON response object
 static json jsonrpc_machine_verify_step_handler(const json &j, const std::shared_ptr<http_session> &session) {
     (void) session;
-    static const char *param_name[] = {"root_hash_before", "filename", "mcycle_count", "root_hash_after"};
+    static const char *const param_name[] = {"root_hash_before", "filename", "mcycle_count", "root_hash_after"};
     auto args = parse_args<cartesi::machine_hash, std::string, uint64_t, cartesi::machine_hash>(j, param_name);
     // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
     auto reason =
@@ -1113,7 +1113,7 @@ static json jsonrpc_machine_verify_step_handler(const json &j, const std::shared
 /// \returns JSON response object
 static json jsonrpc_machine_verify_step_uarch_handler(const json &j,
     const std::shared_ptr<http_session> & /*session*/) {
-    static const char *param_name[] = {"root_hash_before", "log", "root_hash_after"};
+    static const char *const param_name[] = {"root_hash_before", "log", "root_hash_after"};
     auto args = parse_args<cartesi::machine_hash, cartesi::not_default_constructible<cartesi::access_log>,
         cartesi::machine_hash>(j, param_name);
     // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
@@ -1127,7 +1127,7 @@ static json jsonrpc_machine_verify_step_uarch_handler(const json &j,
 /// \returns JSON response object
 static json jsonrpc_machine_verify_reset_uarch_handler(const json &j,
     const std::shared_ptr<http_session> & /*session*/) {
-    static const char *param_name[] = {"root_hash_before", "log", "root_hash_after"};
+    static const char *const param_name[] = {"root_hash_before", "log", "root_hash_after"};
     auto args = parse_args<cartesi::machine_hash, cartesi::not_default_constructible<cartesi::access_log>,
         cartesi::machine_hash>(j, param_name);
     // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
@@ -1143,7 +1143,7 @@ static json jsonrpc_machine_get_proof_handler(const json &j, const std::shared_p
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"address", "log2_size"};
+    static const char *const param_name[] = {"address", "log2_size"};
     auto args = parse_args<uint64_t, uint64_t>(j, param_name);
     if (std::get<1>(args) > INT_MAX) {
         throw std::domain_error("log2_size is out of range");
@@ -1160,7 +1160,7 @@ static json jsonrpc_machine_get_hash_tree_stats_handler(const json &j, const std
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"clear"};
+    static const char *const param_name[] = {"clear"};
     auto args = parse_args<bool>(j, param_name);
     return jsonrpc_response_ok(j, session->handler->machine->get_hash_tree_stats(std::get<0>(args)));
 }
@@ -1198,7 +1198,7 @@ static json jsonrpc_machine_get_node_hash_handler(const json &j, const std::shar
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"address", "log2_size"};
+    static const char *const param_name[] = {"address", "log2_size"};
     auto args = parse_args<uint64_t, uint64_t>(j, param_name);
     if (std::get<1>(args) > INT_MAX) {
         throw std::domain_error("log2_size is out of range");
@@ -1215,7 +1215,7 @@ static json jsonrpc_machine_read_word_handler(const json &j, const std::shared_p
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"address"};
+    static const char *const param_name[] = {"address"};
     auto args = parse_args<uint64_t>(j, param_name);
     auto address = std::get<0>(args);
     return jsonrpc_response_ok(j, session->handler->machine->read_word(address));
@@ -1229,7 +1229,7 @@ static json jsonrpc_machine_write_word_handler(const json &j, const std::shared_
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"address", "value"};
+    static const char *const param_name[] = {"address", "value"};
     auto args = parse_args<uint64_t, uint64_t>(j, param_name);
     auto address = std::get<0>(args);
     auto value = std::get<1>(args);
@@ -1245,7 +1245,7 @@ static json jsonrpc_machine_read_memory_handler(const json &j, const std::shared
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"address", "length"};
+    static const char *const param_name[] = {"address", "length"};
     auto args = parse_args<uint64_t, uint64_t>(j, param_name);
     auto address = std::get<0>(args);
     auto length = std::get<1>(args);
@@ -1262,7 +1262,7 @@ static json jsonrpc_machine_write_memory_handler(const json &j, const std::share
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"address", "data"};
+    static const char *const param_name[] = {"address", "data"};
     auto args = parse_args<uint64_t, std::string>(j, param_name);
     auto address = std::get<0>(args);
     auto bin = cartesi::decode_base64(std::get<1>(args));
@@ -1279,7 +1279,7 @@ static json jsonrpc_machine_read_virtual_memory_handler(const json &j, const std
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"address", "length"};
+    static const char *const param_name[] = {"address", "length"};
     auto args = parse_args<uint64_t, uint64_t>(j, param_name);
     auto address = std::get<0>(args);
     auto length = std::get<1>(args);
@@ -1296,7 +1296,7 @@ static json jsonrpc_machine_write_virtual_memory_handler(const json &j, const st
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"address", "data"};
+    static const char *const param_name[] = {"address", "data"};
     auto args = parse_args<uint64_t, std::string>(j, param_name);
     auto address = std::get<0>(args);
     auto bin = cartesi::decode_base64(std::get<1>(args));
@@ -1314,7 +1314,7 @@ static json jsonrpc_machine_translate_virtual_address_handler(const json &j,
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"vaddr"};
+    static const char *const param_name[] = {"vaddr"};
     auto args = parse_args<uint64_t>(j, param_name);
     auto vaddr = std::get<0>(args);
     return jsonrpc_response_ok(j, session->handler->machine->translate_virtual_address(vaddr));
@@ -1328,7 +1328,7 @@ static json jsonrpc_machine_replace_memory_range_handler(const json &j, const st
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"range"};
+    static const char *const param_name[] = {"range"};
     auto args = parse_args<cartesi::memory_range_config>(j, param_name);
     session->handler->machine->replace_memory_range(std::get<0>(args));
     return jsonrpc_response_ok(j);
@@ -1342,7 +1342,7 @@ static json jsonrpc_machine_read_reg_handler(const json &j, const std::shared_pt
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"reg"};
+    static const char *const param_name[] = {"reg"};
     auto args = parse_args<cartesi::machine::reg>(j, param_name);
     return jsonrpc_response_ok(j, session->handler->machine->read_reg(std::get<0>(args)));
 }
@@ -1355,7 +1355,7 @@ static json jsonrpc_machine_write_reg_handler(const json &j, const std::shared_p
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"reg", "value"};
+    static const char *const param_name[] = {"reg", "value"};
     auto args = parse_args<cartesi::machine::reg, uint64_t>(j, param_name);
     session->handler->machine->write_reg(std::get<0>(args), std::get<1>(args));
     return jsonrpc_response_ok(j);
@@ -1366,7 +1366,7 @@ static json jsonrpc_machine_write_reg_handler(const json &j, const std::shared_p
 /// \param session HTTP session
 /// \returns JSON response object
 static json jsonrpc_machine_get_reg_address_handler(const json &j, const std::shared_ptr<http_session> & /*session*/) {
-    static const char *param_name[] = {"reg"};
+    static const char *const param_name[] = {"reg"};
     auto args = parse_args<cartesi::machine::reg>(j, param_name);
     return jsonrpc_response_ok(j, cartesi::machine::get_reg_address(std::get<0>(args)));
 }
@@ -1416,7 +1416,7 @@ static json jsonrpc_machine_set_runtime_config_handler(const json &j, const std:
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"runtime_config"};
+    static const char *const param_name[] = {"runtime_config"};
     auto args = parse_args<cartesi::machine_runtime_config>(j, param_name);
     session->handler->machine->set_runtime_config(std::get<0>(args));
     return jsonrpc_response_ok(j);
@@ -1452,7 +1452,7 @@ static json jsonrpc_machine_send_cmio_response_handler(const json &j, const std:
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"reason", "data"};
+    static const char *const param_name[] = {"reason", "data"};
     auto args = parse_args<uint16_t, std::string>(j, param_name);
     auto bin = cartesi::decode_base64(std::get<1>(args));
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
@@ -1466,7 +1466,7 @@ static json jsonrpc_machine_log_send_cmio_response_handler(const json &j,
     if (!session->handler->machine) {
         return jsonrpc_response_invalid_request(j, "no machine");
     }
-    static const char *param_name[] = {"reason", "data", "log_type"};
+    static const char *const param_name[] = {"reason", "data", "log_type"};
     auto args =
         parse_args<uint16_t, std::string, cartesi::not_default_constructible<cartesi::access_log::type>>(j, param_name);
     auto bin = cartesi::decode_base64(std::get<1>(args));
@@ -1485,7 +1485,7 @@ static json jsonrpc_machine_log_send_cmio_response_handler(const json &j,
 /// \returns JSON response object
 static json jsonrpc_machine_verify_send_cmio_response_handler(const json &j,
     const std::shared_ptr<http_session> & /*session*/) {
-    static const char *param_name[] = {"reason", "data", "root_hash_before", "log", "root_hash_after"};
+    static const char *const param_name[] = {"reason", "data", "root_hash_before", "log", "root_hash_after"};
     auto args = parse_args<uint16_t, std::string, cartesi::machine_hash,
         cartesi::not_default_constructible<cartesi::access_log>, cartesi::machine_hash>(j, param_name);
 
diff --git a/src/machine-config.cpp b/src/machine-config.cpp
index c57524426..268da07df 100644
--- a/src/machine-config.cpp
+++ b/src/machine-config.cpp
@@ -191,7 +191,7 @@ machine_config &machine_config::adjust_defaults() {
         const std::string flash_description = "flash drive "s + std::to_string(i);
         // Auto detect flash drive start address
         if (f.start == UINT64_C(-1)) {
-            f.start = AR_DRIVE_START + AR_DRIVE_OFFSET * i;
+            f.start = AR_DRIVE_START + (AR_DRIVE_OFFSET * i);
         }
         // Auto detect flash drive image length
         if (f.length == UINT64_C(-1)) {
diff --git a/src/os-mapped-memory.cpp b/src/os-mapped-memory.cpp
index 0fb74ab94..0ace48c39 100644
--- a/src/os-mapped-memory.cpp
+++ b/src/os-mapped-memory.cpp
@@ -27,6 +27,7 @@
 #else
 #include <cstdio>  // fopen/fclose/fread/fwrite/fflush
 #include <cstdlib> // calloc/free
+#include <memory>  // align
 #endif
 
 #if defined(HAVE_FLOCK)
@@ -389,9 +390,10 @@ mapped_memory::mapped_memory(uint64_t length, const mapped_memory_flags &flags,
     // Commit state
     m_host_memory = host_memory;
     m_backing_sync_length = shared_write ? desired_backing_length : 0;
-    m_memory_mapping = static_cast<void *>(memory_mapping), m_backing_host_memory = backing_host_memory,
-    m_backing_mapping = backing_mapping, m_backing_fh = static_cast<void *>(backing_fh)
-};
+    m_memory_mapping = static_cast<void *>(memory_mapping);
+    m_backing_host_memory = backing_host_memory;
+    m_backing_mapping = backing_mapping;
+    m_backing_fh = static_cast<void *>(backing_fh);
 
 #else  // Fallback implementation using standard C APIs
     // Over-allocate to ensure we can align the pointer and store the original pointer.
diff --git a/src/os-mapped-memory.h b/src/os-mapped-memory.h
index 3a05c5bdb..57cfa7e91 100644
--- a/src/os-mapped-memory.h
+++ b/src/os-mapped-memory.h
@@ -113,13 +113,15 @@ class mapped_memory final {
     /// \brief Returns a span representing the mapped memory region.
     std::span<unsigned char> get_storage_data() noexcept {
         // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        return std::span<unsigned char>{reinterpret_cast<unsigned char *>(m_host_memory), m_length};
+        return std::span<unsigned char>{reinterpret_cast<unsigned char *>(m_host_memory),
+            static_cast<size_t>(m_length)};
     }
 
     /// \brief Returns a span representing the mapped memory region.
     std::span<const unsigned char> get_storage_data() const noexcept {
         // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-        return std::span<const unsigned char>{reinterpret_cast<const unsigned char *>(m_host_memory), m_length};
+        return std::span<const unsigned char>{reinterpret_cast<const unsigned char *>(m_host_memory),
+            static_cast<size_t>(m_length)};
     }
 
     /// \brief Returns the total length of the mapped memory region.
diff --git a/src/os.cpp b/src/os.cpp
index 0dfb6cab9..1079342ae 100644
--- a/src/os.cpp
+++ b/src/os.cpp
@@ -121,7 +121,7 @@ static int new_ttyfd(const char *path) {
 }
 
 static int get_ttyfd() {
-    char *path{};
+    const char *path{};
     path = ttyname(STDERR_FILENO);
     if (path != nullptr) {
         return new_ttyfd(path);
diff --git a/src/soft-float.h b/src/soft-float.h
index f2327be6c..38b0fd93c 100644
--- a/src/soft-float.h
+++ b/src/soft-float.h
@@ -641,7 +641,7 @@ struct i_sfloat {
             a_exp--;
             a_mant <<= 1;
         }
-        a_exp = (a_exp >> 1) + EXP_MASK / 2;
+        a_exp = (a_exp >> 1) + (EXP_MASK / 2);
         a_mant <<= (F_SIZE - 4 - MANT_SIZE);
         if (sqrtrem_u(&a_mant, a_mant, static_cast<F_UINT>(0))) {
             a_mant |= 1;
diff --git a/src/virtio-p9fs-address-range.cpp b/src/virtio-p9fs-address-range.cpp
index 54569c1aa..a0fe0c9aa 100644
--- a/src/virtio-p9fs-address-range.cpp
+++ b/src/virtio-p9fs-address-range.cpp
@@ -1120,7 +1120,7 @@ bool virtio_p9fs_address_range::op_statfs(virtq_unserializer &&mmsg, uint16_t ta
 #endif
 #ifndef _WIN32
     // Get the fid state
-    p9_fid_state *fidp = get_fid_state(fid);
+    const p9_fid_state *fidp = get_fid_state(fid);
     if (fidp == nullptr) {
         return send_error(msg, tag, P9_EPROTO);
     }
@@ -1326,7 +1326,7 @@ bool virtio_p9fs_address_range::op_symlink(virtq_unserializer &&mmsg, uint16_t t
         return send_error(msg, tag, P9_ENOENT);
     }
     // Get the fid state
-    p9_fid_state *dfidp = get_fid_state(dfid);
+    const p9_fid_state *dfidp = get_fid_state(dfid);
     if (dfidp == nullptr) {
         return send_error(msg, tag, P9_EPROTO);
     }
@@ -1383,7 +1383,7 @@ bool virtio_p9fs_address_range::op_mknod(virtq_unserializer &&mmsg, uint16_t tag
         return send_error(msg, tag, P9_ENOENT);
     }
     // Get the fid state
-    p9_fid_state *dfidp = get_fid_state(dfid);
+    const p9_fid_state *dfidp = get_fid_state(dfid);
     if (dfidp == nullptr) {
         return send_error(msg, tag, P9_EPROTO);
     }
@@ -1727,7 +1727,7 @@ bool virtio_p9fs_address_range::op_lock(virtq_unserializer &&mmsg, uint16_t tag)
         return send_error(msg, tag, P9_EINVAL);
     }
     // Get the fid state
-    p9_fid_state *fidp = get_fid_state(fid);
+    const p9_fid_state *fidp = get_fid_state(fid);
     if ((fidp == nullptr) || fidp->fd < 0) {
         return send_error(msg, tag, P9_EPROTO);
     }
@@ -1779,7 +1779,7 @@ bool virtio_p9fs_address_range::op_getlock(virtq_unserializer &&mmsg, uint16_t t
 #endif
 #if defined(F_SETLK) && defined(F_SETLKW)
     // Get the fid state
-    p9_fid_state *fidp = get_fid_state(fid);
+    const p9_fid_state *fidp = get_fid_state(fid);
     if ((fidp == nullptr) || fidp->fd < 0) {
         return send_error(msg, tag, P9_EPROTO);
     }
@@ -1925,7 +1925,7 @@ bool virtio_p9fs_address_range::op_fsync(virtq_unserializer &&mmsg, uint16_t tag
     std::ignore = fprintf(stderr, "p9fs fsync: tag=%d fid=%d\n", tag, fid);
 #endif
     // Get the fid state
-    p9_fid_state *fidp = get_fid_state(fid);
+    const p9_fid_state *fidp = get_fid_state(fid);
     if ((fidp == nullptr) || fidp->fd < 0) {
         return send_error(msg, tag, P9_EPROTO);
     }
@@ -1954,8 +1954,8 @@ bool virtio_p9fs_address_range::op_link(virtq_unserializer &&mmsg, uint16_t tag)
         return send_error(msg, tag, P9_ENOENT);
     }
     // Get the fid state
-    p9_fid_state *dfidp = get_fid_state(dfid);
-    p9_fid_state *fidp = get_fid_state(fid);
+    const p9_fid_state *dfidp = get_fid_state(dfid);
+    const p9_fid_state *fidp = get_fid_state(fid);
     if ((dfidp == nullptr) || (fidp == nullptr)) {
         return send_error(msg, tag, P9_EPROTO);
     }
@@ -1992,7 +1992,7 @@ bool virtio_p9fs_address_range::op_mkdir(virtq_unserializer &&mmsg, uint16_t tag
         return send_error(msg, tag, P9_ENOENT);
     }
     // Get the fid state
-    p9_fid_state *dfidp = get_fid_state(dfid);
+    const p9_fid_state *dfidp = get_fid_state(dfid);
     if (dfidp == nullptr) {
         return send_error(msg, tag, P9_EPROTO);
     }
diff --git a/uarch/uarch-runtime.cpp b/uarch/uarch-runtime.cpp
index 012d66b47..69c7765dc 100644
--- a/uarch/uarch-runtime.cpp
+++ b/uarch/uarch-runtime.cpp
@@ -72,7 +72,7 @@ extern "C" void *memcpy(void *dest, const void *src, size_t n) {
 }
 
 extern "C" void *memset(void *ptr, int value, size_t num) {
-    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast,misc-const-correctness)
     volatile unsigned char *p = reinterpret_cast<unsigned char *>(ptr);
     while (num-- != 0) {
         *p++ = value;

From 1cce7ce70ff8e39a0edfcffaafb635ce1fd83c41 Mon Sep 17 00:00:00 2001
From: Eduardo Bart <edub4rt@gmail.com>
Date: Thu, 23 Oct 2025 13:57:09 -0300
Subject: [PATCH 82/82] feat: add revert root hash in shadow address range

---
 src/address-range-constants.h | 14 +++++----
 src/address-range-defines.h   | 59 ++++++++++++++++++-----------------
 src/clua-cartesi.cpp          |  1 +
 src/machine-c-api.cpp         |  1 +
 src/machine-c-api.h           |  1 +
 src/machine.cpp               |  5 ++-
 src/processor-state.h         |  6 +++-
 tests/lua/machine-bind.lua    | 14 +++++++++
 8 files changed, 64 insertions(+), 37 deletions(-)

diff --git a/src/address-range-constants.h b/src/address-range-constants.h
index 0d021cbc0..f09a7d47c 100644
--- a/src/address-range-constants.h
+++ b/src/address-range-constants.h
@@ -29,12 +29,14 @@ enum AR_ranges : uint64_t {
     AR_SHADOW_STATE_LENGTH = EXPAND_UINT64_C(AR_SHADOW_STATE_LENGTH_DEF),         ///< Length of shadow state range
     AR_SHADOW_REGISTERS_START = EXPAND_UINT64_C(AR_SHADOW_REGISTERS_START_DEF),   ///< Start of shadow registers range
     AR_SHADOW_REGISTERS_LENGTH = EXPAND_UINT64_C(AR_SHADOW_REGISTERS_LENGTH_DEF), ///< Length of shadow registers range
-    AR_SHADOW_TLB_START = EXPAND_UINT64_C(AR_SHADOW_TLB_START_DEF),               ///< Start of shadow TLB range
-    AR_SHADOW_TLB_LENGTH = EXPAND_UINT64_C(AR_SHADOW_TLB_LENGTH_DEF),             ///< Length of shadow TLB range
-    AR_PMAS_START = EXPAND_UINT64_C(AR_PMAS_START_DEF),                           ///< Start of PMAS list range
-    AR_PMAS_LENGTH = EXPAND_UINT64_C(AR_PMAS_LENGTH_DEF),                         ///< Length of PMAS list range
-    AR_DTB_START = EXPAND_UINT64_C(AR_DTB_START_DEF),                             ///< Start of DTB range
-    AR_DTB_LENGTH = EXPAND_UINT64_C(AR_DTB_LENGTH_DEF),                           ///< Length of DTB range
+    AR_SHADOW_REVERT_ROOT_HASH_START =
+        EXPAND_UINT64_C(AR_SHADOW_REVERT_ROOT_HASH_START_DEF),        ///< Start of revert root hash range
+    AR_SHADOW_TLB_START = EXPAND_UINT64_C(AR_SHADOW_TLB_START_DEF),   ///< Start of shadow TLB range
+    AR_SHADOW_TLB_LENGTH = EXPAND_UINT64_C(AR_SHADOW_TLB_LENGTH_DEF), ///< Length of shadow TLB range
+    AR_PMAS_START = EXPAND_UINT64_C(AR_PMAS_START_DEF),               ///< Start of PMAS list range
+    AR_PMAS_LENGTH = EXPAND_UINT64_C(AR_PMAS_LENGTH_DEF),             ///< Length of PMAS list range
+    AR_DTB_START = EXPAND_UINT64_C(AR_DTB_START_DEF),                 ///< Start of DTB range
+    AR_DTB_LENGTH = EXPAND_UINT64_C(AR_DTB_LENGTH_DEF),               ///< Length of DTB range
     AR_SHADOW_UARCH_STATE_START =
         EXPAND_UINT64_C(AR_SHADOW_UARCH_STATE_START_DEF), ///< Start of uarch shadow state range
     AR_SHADOW_UARCH_STATE_LENGTH =
diff --git a/src/address-range-defines.h b/src/address-range-defines.h
index 13e8d2577..c4366c278 100644
--- a/src/address-range-defines.h
+++ b/src/address-range-defines.h
@@ -18,35 +18,36 @@
 #define AR_DEFINES_H
 
 // NOLINTBEGIN(cppcoreguidelines-macro-usage,cppcoreguidelines-macro-to-enum,modernize-macro-to-enum)
-#define AR_SHADOW_STATE_START_DEF 0x0            ///< Shadow start address
-#define AR_SHADOW_STATE_LENGTH_DEF 0x8000        ///< Shadow length in bytes
-#define AR_SHADOW_REGISTERS_START_DEF 0x0        ///< Shadow registers start address
-#define AR_SHADOW_REGISTERS_LENGTH_DEF 0x1000    ///< Shadow registers length in bytes
-#define AR_SHADOW_TLB_START_DEF 0x1000           ///< Shadow TLB start address
-#define AR_SHADOW_TLB_LENGTH_DEF 0x6000          ///< Shadow TLB length in bytes
-#define AR_PMAS_START_DEF 0x10000                ///< PMA Array start address
-#define AR_PMAS_LENGTH_DEF 0x1000                ///< PMA Array length in bytes
-#define AR_SHADOW_UARCH_STATE_START_DEF 0x400000 ///< microarchitecture shadow state start address
-#define AR_SHADOW_UARCH_STATE_LENGTH_DEF 0x1000  ///< microarchitecture shadow state length
-#define AR_UARCH_RAM_START_DEF 0x600000          ///< microarchitecture RAM start address
-#define AR_UARCH_RAM_LENGTH_DEF 0x200000         ///< microarchitecture RAM length
-#define AR_CLINT_START_DEF 0x2000000             ///< CLINT start address
-#define AR_CLINT_LENGTH_DEF 0xC0000              ///< CLINT length in bytes
-#define AR_PLIC_START_DEF 0x40100000             ///< Start of PLIC range
-#define AR_PLIC_LENGTH_DEF 0x00400000            ///< Length of PLIC range
-#define AR_HTIF_START_DEF 0x40008000             ///< HTIF base address (to_host)
-#define AR_HTIF_LENGTH_DEF 0x1000                ///< HTIF length in bytes
-#define AR_FIRST_VIRTIO_START_DEF 0x40010000     ///< Start of first VIRTIO range
-#define AR_VIRTIO_LENGTH_DEF 0x1000              ///< Length of each VIRTIO range
-#define AR_LAST_VIRTIO_END_DEF 0x40020000        ///< End of last VIRTIO range
-#define AR_DTB_START_DEF 0x7ff00000              ///< DTB start address
-#define AR_DTB_LENGTH_DEF 0x100000               ///< DTB length in bytes
-#define AR_CMIO_RX_BUFFER_START_DEF 0x60000000   ///< CMIO RX buffer start address
-#define AR_CMIO_RX_BUFFER_LOG2_SIZE_DEF 21       ///< log<sub>2</sub> of CMIO RX buffer length in bytes
-#define AR_CMIO_TX_BUFFER_START_DEF 0x60800000   ///< CMIO TX buffer start address
-#define AR_CMIO_TX_BUFFER_LOG2_SIZE_DEF 21       ///< log<sub>2</sub> of CMIO TX buffer length in bytes
-#define AR_DRIVE_START_DEF 0x80000000000000      ///< Start PMA address for flash drives
-#define AR_DRIVE_OFFSET_DEF 0x10000000000000     ///< PMA offset for extra flash drives
+#define AR_SHADOW_STATE_START_DEF 0x0              ///< Shadow start address
+#define AR_SHADOW_STATE_LENGTH_DEF 0x8000          ///< Shadow length in bytes
+#define AR_SHADOW_REGISTERS_START_DEF 0x0          ///< Shadow registers start address
+#define AR_SHADOW_REGISTERS_LENGTH_DEF 0x1000      ///< Shadow registers length in bytes
+#define AR_SHADOW_REVERT_ROOT_HASH_START_DEF 0xfe0 ///< Shadow revert root hash start address
+#define AR_SHADOW_TLB_START_DEF 0x1000             ///< Shadow TLB start address
+#define AR_SHADOW_TLB_LENGTH_DEF 0x6000            ///< Shadow TLB length in bytes
+#define AR_PMAS_START_DEF 0x10000                  ///< PMA Array start address
+#define AR_PMAS_LENGTH_DEF 0x1000                  ///< PMA Array length in bytes
+#define AR_SHADOW_UARCH_STATE_START_DEF 0x400000   ///< microarchitecture shadow state start address
+#define AR_SHADOW_UARCH_STATE_LENGTH_DEF 0x1000    ///< microarchitecture shadow state length
+#define AR_UARCH_RAM_START_DEF 0x600000            ///< microarchitecture RAM start address
+#define AR_UARCH_RAM_LENGTH_DEF 0x200000           ///< microarchitecture RAM length
+#define AR_CLINT_START_DEF 0x2000000               ///< CLINT start address
+#define AR_CLINT_LENGTH_DEF 0xC0000                ///< CLINT length in bytes
+#define AR_PLIC_START_DEF 0x40100000               ///< Start of PLIC range
+#define AR_PLIC_LENGTH_DEF 0x00400000              ///< Length of PLIC range
+#define AR_HTIF_START_DEF 0x40008000               ///< HTIF base address (to_host)
+#define AR_HTIF_LENGTH_DEF 0x1000                  ///< HTIF length in bytes
+#define AR_FIRST_VIRTIO_START_DEF 0x40010000       ///< Start of first VIRTIO range
+#define AR_VIRTIO_LENGTH_DEF 0x1000                ///< Length of each VIRTIO range
+#define AR_LAST_VIRTIO_END_DEF 0x40020000          ///< End of last VIRTIO range
+#define AR_DTB_START_DEF 0x7ff00000                ///< DTB start address
+#define AR_DTB_LENGTH_DEF 0x100000                 ///< DTB length in bytes
+#define AR_CMIO_RX_BUFFER_START_DEF 0x60000000     ///< CMIO RX buffer start address
+#define AR_CMIO_RX_BUFFER_LOG2_SIZE_DEF 21         ///< log<sub>2</sub> of CMIO RX buffer length in bytes
+#define AR_CMIO_TX_BUFFER_START_DEF 0x60800000     ///< CMIO TX buffer start address
+#define AR_CMIO_TX_BUFFER_LOG2_SIZE_DEF 21         ///< log<sub>2</sub> of CMIO TX buffer length in bytes
+#define AR_DRIVE_START_DEF 0x80000000000000        ///< Start PMA address for flash drives
+#define AR_DRIVE_OFFSET_DEF 0x10000000000000       ///< PMA offset for extra flash drives
 
 #define AR_RAM_START_DEF 0x80000000 ///< RAM start address
 
diff --git a/src/clua-cartesi.cpp b/src/clua-cartesi.cpp
index 7fd59bf72..da9cad128 100644
--- a/src/clua-cartesi.cpp
+++ b/src/clua-cartesi.cpp
@@ -245,6 +245,7 @@ CM_API int luaopen_cartesi(lua_State *L) {
     clua_setintegerfield(L, CM_AR_CMIO_RX_BUFFER_LOG2_SIZE, "AR_CMIO_RX_BUFFER_LOG2_SIZE", -1);
     clua_setintegerfield(L, CM_AR_CMIO_TX_BUFFER_START, "AR_CMIO_TX_BUFFER_START", -1);
     clua_setintegerfield(L, CM_AR_CMIO_TX_BUFFER_LOG2_SIZE, "AR_CMIO_TX_BUFFER_LOG2_SIZE", -1);
+    clua_setintegerfield(L, CM_AR_SHADOW_REVERT_ROOT_HASH_START, "AR_SHADOW_REVERT_ROOT_HASH_START", -1);
     clua_setintegerfield(L, CM_AR_RAM_START, "AR_RAM_START", -1);
     // HTIF masks
     clua_setintegerfield(L, HTIF_HALT_CMD_HALT_MASK, "HTIF_HALT_CMD_HALT_MASK", -1);
diff --git a/src/machine-c-api.cpp b/src/machine-c-api.cpp
index 4e42faf24..f24ae0f37 100644
--- a/src/machine-c-api.cpp
+++ b/src/machine-c-api.cpp
@@ -66,6 +66,7 @@ static_assert(AR_CMIO_RX_BUFFER_START_DEF == CM_AR_CMIO_RX_BUFFER_START);
 static_assert(AR_CMIO_RX_BUFFER_LOG2_SIZE_DEF == CM_AR_CMIO_RX_BUFFER_LOG2_SIZE);
 static_assert(AR_CMIO_TX_BUFFER_START_DEF == CM_AR_CMIO_TX_BUFFER_START);
 static_assert(AR_CMIO_TX_BUFFER_LOG2_SIZE_DEF == CM_AR_CMIO_TX_BUFFER_LOG2_SIZE);
+static_assert(AR_SHADOW_REVERT_ROOT_HASH_START_DEF == CM_AR_SHADOW_REVERT_ROOT_HASH_START);
 static_assert(AR_RAM_START_DEF == CM_AR_RAM_START);
 
 static_assert(HTIF_YIELD_AUTOMATIC_REASON_PROGRESS_DEF == CM_CMIO_YIELD_AUTOMATIC_REASON_PROGRESS);
diff --git a/src/machine-c-api.h b/src/machine-c-api.h
index eea8c5a1f..75eea760d 100644
--- a/src/machine-c-api.h
+++ b/src/machine-c-api.h
@@ -57,6 +57,7 @@ typedef enum cm_pmas_constant {
     CM_AR_CMIO_RX_BUFFER_LOG2_SIZE = 21,
     CM_AR_CMIO_TX_BUFFER_START = 0x60800000,
     CM_AR_CMIO_TX_BUFFER_LOG2_SIZE = 21,
+    CM_AR_SHADOW_REVERT_ROOT_HASH_START = 0xfe0,
     CM_AR_RAM_START = 0x80000000,
 } cm_pmas_constant;
 
diff --git a/src/machine.cpp b/src/machine.cpp
index 0ec09295c..b5eadbfdb 100644
--- a/src/machine.cpp
+++ b/src/machine.cpp
@@ -1600,7 +1600,10 @@ void machine::write_memory(uint64_t paddr, const unsigned char *data, uint64_t l
         init_hot_tlb_contents();
         return;
     }
-    if (pmas_is_protected(ar.get_driver_id())) {
+    // Allow special case for writing the revert root hash
+    if (paddr == AR_SHADOW_REVERT_ROOT_HASH_START && length == sizeof(machine_hash)) {
+        ;
+    } else if (pmas_is_protected(ar.get_driver_id())) {
         throw std::invalid_argument{"attempted write to protected memory range "s.append(ar_descr)};
     }
     //??D In C++23, change this to use std::span and std::views::chunk std::views::drop/take and std::views::chain
diff --git a/src/processor-state.h b/src/processor-state.h
index 49042da26..55c052a98 100644
--- a/src/processor-state.h
+++ b/src/processor-state.h
@@ -25,6 +25,7 @@
 
 #include "address-range-constants.h"
 #include "hot-tlb.h"
+#include "machine-hash.h"
 #include "shadow-registers.h"
 #include "shadow-tlb.h"
 
@@ -34,7 +35,8 @@ namespace cartesi {
 /// \details It's stored in the processor backing file.
 struct shadow_state final {
     registers_state registers;          ///< Registers state
-    uint64_t registers_padding_[406]{}; ///< Padding to align next field to a page boundary
+    uint64_t registers_padding_[402]{}; ///< Padding to align next field to a page boundary
+    machine_hash revert_root_hash{};    ///< Revert root hash
     shadow_tlb_state tlb;               ///< Shadow TLB state
     uint64_t tlb_padding_[512]{};       ///< Padding to align next field to a page boundary
 };
@@ -55,6 +57,8 @@ struct processor_state final {
 static_assert(offsetof(shadow_state, tlb) % AR_PAGE_SIZE == 0, "shadow tlb state must be aligned to a page boundary");
 static_assert(offsetof(processor_state, penumbra) % AR_PAGE_SIZE == 0,
     "penumbra state must be aligned to a page boundary");
+static_assert(offsetof(shadow_state, revert_root_hash) == AR_SHADOW_REVERT_ROOT_HASH_START,
+    "unexpected shadow revert root hash start");
 
 static_assert(sizeof(processor_state) % AR_PAGE_SIZE == 0, "processor state size must be multiple of a page size");
 static_assert(sizeof(shadow_state) == AR_SHADOW_STATE_LENGTH, "unexpected shadow state size");
diff --git a/tests/lua/machine-bind.lua b/tests/lua/machine-bind.lua
index fbc48f616..fcc16ba6a 100755
--- a/tests/lua/machine-bind.lua
+++ b/tests/lua/machine-bind.lua
@@ -357,6 +357,20 @@ do_test("should provide proof for values in registers", function(machine)
     end
 end)
 
+print("\n\ntesting revert root hash")
+do_test("should write/read revert root hash", function(machine)
+    local before_root_hash = machine:get_root_hash()
+    machine:write_memory(cartesi.AR_SHADOW_REVERT_ROOT_HASH_START, before_root_hash)
+    assert(
+        machine:read_memory(cartesi.AR_SHADOW_REVERT_ROOT_HASH_START, cartesi.HASH_SIZE) == before_root_hash,
+        "unexpected revert root hash"
+    )
+    local after_root_hash = machine:get_root_hash()
+    assert(before_root_hash ~= after_root_hash)
+    machine:write_memory(cartesi.AR_SHADOW_REVERT_ROOT_HASH_START, string.rep("\x00", 32))
+    assert(before_root_hash == machine:get_root_hash())
+end)
+
 print("\n\ntesting get_reg_address function binding")
 do_test("should return address value for registers", function(machine)
     -- Check register address