cartesi · diegonehab · Apr 22, 2026 · May 4, 2026 · May 6, 2026 · May 14, 2026
diff --git a/.dockerignore b/.dockerignore
@@ -11,14 +11,15 @@
 **/*.deb
 
 build
+tests/build
+tests/fuzz/corpus
+tests/fuzz/corpus-config
+tests/fuzz/seed-corpus
 third-party/downloads
+third-party/riscv-arch-test/riscv-test-stats
 src/cartesi-jsonrpc-machine
 src/cartesi-hash-tree-hash
-
-doc/html
-doc/api.md
-doc/html/
-doc/xml/
+doc/
 
 .git
 .github

diff --git a/.gitattributes b/.gitattributes
@@ -1,2 +1,3 @@
 third-party/** linguist-vendored
 tests/** linguist-vendored
+doc/recipes/rootfs-docs.ext2 filter=lfs diff=lfs merge=lfs -text
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -685,9 +685,101 @@ jobs:
         run: |
           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 test-c-api-remote test-c-jsonrpc-api test-coverage-machine test-uarch-rv64ui test-uarch-interpreter test-coverage-uarch
 
+  docs:
+    name: Docs
+    needs: build
+    runs-on: ubuntu-latest-8-cores
+    steps:
+      - name: Checkout machine emulator source code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          submodules: recursive
+          lfs: true
+
+      - name: Setup variables
+        run: echo MACHINE_EMULATOR_VERSION=`make version` >> $GITHUB_ENV
+
+      - name: Install e2tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends e2tools
+
+      - name: Check rootfs-docs.ext2 is up to date
+        run: make -C doc check-rootfs-docs
+
+      - name: Ensure doc/recipes/rootfs-docs.licenses.md is tracked
+        run: |
+          if ! git ls-files --error-unmatch doc/recipes/rootfs-docs.licenses.md >/dev/null 2>&1; then
+            echo "::error::doc/recipes/rootfs-docs.licenses.md is not tracked in git. The sync check requires a committed baseline to diff against. Generate it with 'make -C doc build-rootfs-docs-license' and commit the result."
+            exit 1
+          fi
+
+      - name: Build rootfs-docs license report
+        run: make -C doc build-rootfs-docs-license
+
+      - name: Check rootfs-docs.licenses.md matches committed version
+        run: |
+          if git diff --quiet doc/recipes/rootfs-docs.licenses.md; then
+            exit 0
+          fi
+          git --no-pager diff doc/recipes/rootfs-docs.licenses.md
+          echo "::error::doc/recipes/rootfs-docs.licenses.md is out of sync with the generator. The diff above is what 'make -C doc build-rootfs-docs-license' produces vs the committed file. Check if changes were intended and, if so, regenerate locally and commit the result."
+          exit 1
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Depot CLI
+        uses: depot/setup-action@15c09a5f77a0840ad4bce955686522a257853461 # v1.7.1
+
+      - name: Build machine-emulator docker image
+        uses: depot/build-push-action@5f3b3c2e5a00f0093de47f657aeaefcedff27d18 # v1.17.0
+        with:
+          file: Dockerfile
+          context: .
+          platforms: linux/amd64
+          tags: cartesi/machine-emulator:devel
+          push: false
+          load: true
+          build-args: |
+            DEBUG=${{ (startsWith(github.ref, 'refs/tags/v') && 'no' || 'yes') }}
+            GIT_COMMIT=${GITHUB_SHA}
+            MACHINE_EMULATOR_VERSION=${{ env.MACHINE_EMULATOR_VERSION }}
+          project: ${{ vars.DEPOT_PROJECT }}
+          token: ${{ secrets.DEPOT_TOKEN }}
+
+      - name: Ensure doc/README.md is tracked
+        run: |
+          if ! git ls-files --error-unmatch doc/README.md >/dev/null 2>&1; then
+            echo "::error::doc/README.md is not tracked in git. The sync check requires a committed baseline to diff against. Generate it with 'make -C doc README.md' and commit the result."
+            exit 1
+          fi
+
+      - name: Build documentation
+        run: make -C doc README.md
+
+      - name: Check README.md matches committed version
+        run: |
+          if git diff --quiet doc/README.md; then
+            exit 0
+          fi
+          git --no-pager diff doc/README.md
+          echo "::error::doc/README.md is out of sync with the generator. The diff above is what 'make -C doc README.md' produces vs the committed file. Check if changes were intended and, if so, regenerate locally and commit the result."
+          exit 1
+
   publish_artifacts:
     name: Publish artifacts
-    needs: [build, lint, coverage, sanitize, test_amd64, test_arm64, risc0]
+    needs: [build, lint, coverage, sanitize, test_amd64, test_arm64, risc0, docs]
     runs-on: ubuntu-latest
     steps:
       - name: Checkout emulator source code
@@ -862,7 +954,7 @@ jobs:
 
       - name: Install rzup
         run: |
-          cargo install --git https://github.com/risc0/risc0 rzup
+          cargo install --locked --git https://github.com/risc0/risc0 rzup
           rzup install cargo-risczero 3.0.5
           rzup install r0vm 3.0.5
           rzup install cpp 2024.1.5

diff --git a/.gitignore b/.gitignore
@@ -18,10 +18,8 @@ src/cartesi-jsonrpc-machine
 src/cartesi-hash-tree-hash
 src/tests/test-machine-c-api
 
-doc/html
-doc/api.md
-doc/html/
-doc/xml/
+doc/doxygen/html
+doc/recipes/cache
 
 .clangd
 .venv

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,32 +6,63 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 ## Added
-- Added `--nvram` command line option and `nvram_configs` machine configuration for UIO-backed memory ranges, exposed to the guest via `generic-uio`
-- Added `label` field to flash drive and nvram configurations, propagated to the guest through DTB properties
-- Added optional directory argument to `--dump-memory-ranges` to support read-only install locations
+- Added a user manual under `doc/`, generated from a template by a docgen pipeline that executes and verifies every code snippet against the locally built emulator
+- Added `--nvram` command line option and `nvram` machine configuration for UIO-backed memory ranges, exposed to the guest as `/dev/uio*` via `generic-uio`
+- Added a `label` field to memory range configurations, exposed to the guest through a standard DTB `/aliases` node (`flashdriveN`, `nvramN`, and any user label)
+- Added recording of a revert root hash as a logged input of `send_cmio_response`, with `read_revert_root_hash`/`write_revert_root_hash` accessors across all API layers
+- Added reversion to the recorded revert root hash for rollup inputs that end rejected, when logging steps, logging uarch resets, verifying, and collecting root hashes
+- Added emission of per-output proofs from `--cmio-advance-state`
+- Added an optional user schema dictionary argument to `cartesi.tojson`/`cartesi.fromjson` to name binary and compound fields of caller-defined message types
+- Added a `cartesi.hash-tree` Lua module for hash-tree slice/splice verification and building the output-hashes frontier behind the output proofs
+- Added `get_address_name` to resolve a physical address to a descriptive name, across the C, Lua, and JSON-RPC APIs
+- Added the ability for `--initial-hash` and `--final-hash` to write the hash to a file
+- Added an optional directory argument to `--dump-memory-ranges` to support read-only install locations
 - Added decoding of RISC-V Zcb compressed instructions (required by kernels built with GCC 14)
 - Added fallback to `read_reg` in the GDB stub so `monitor reg <name>` works for any named register
-- Added `CM_FLASH_DRIVE_MAX`, `CM_NVRAM_MAX`, and `CM_MEMORY_RANGE_LABEL_MAX` constants to the public C API
+- Added `--bash-completion` to print a bash completion script for `cartesi-machine`
+- Added public C API constants `CM_FLASH_DRIVE_MAX`, `CM_NVRAM_MAX`, `CM_MEMORY_RANGE_LABEL_MAX`, `CM_RTC_FREQ_DIV`, and `CM_CMIO_LOG2_MAX_OUTPUT_COUNT`
+- Added the peripheral `CM_AR_*` address range constants, the `CM_PMA_*_DID` driver id constants, the HTIF device, command, shift, and mask constants, and the `CM_DTB_BOOTARGS_*` macros to the public C API
 - Added LuaCov-based coverage tracking for Lua code, integrated with the gcov report pipeline
+- Added a JSON-RPC C API coverage suite and converted `test-cm-cli` and `test-evmu` to the lester spec format
 - Added `spec-cm-cli.lua` covering every command-line option of `cartesi-machine.lua`
 
 ## Fixed
+- Fixed leaf size in `cartesi-hash-tree-hash`, which was 8 instead of 32
+- Fixed read-only flash drives not being mounted with `-o ro`, which trapped guest writes and panicked init
+- Fixed missing `#address-cells` on the per-CPU `interrupt-controller` node in the DTB, silencing a `dtc` interrupt-provider lint warning
 - Fixed firmware reserved region in the DTB being too small for OpenSBI built with GCC 14
 - Fixed missing validation of memory range labels and of `replace_memory_range` arguments
 - Fixed boolean merging in `merge_memory_range_opts` so options can be explicitly overridden to `false`
 - Fixed `--no-root-flash-drive` bootargs substitution pattern
 - Fixed `dump_pmas()` still calling the removed `get_memory_ranges()` method
 - Fixed unanchored patterns matching `--quiet` and `--assert-rolling-template`
 - Fixed `help()` internally calling `os.exit()`
+- Fixed a typo in the `cartesi-machine.lua` cmio handling
 
 ## Changed
-- Renamed `--dump-memory-ranges` to `--dump-address-ranges` for consistency with `get_address_ranges()`
+- Renamed the yield constants in `cm.h` and the Lua API from `CM_CMIO_YIELD_*` to `CM_HTIF_YIELD_*` (and the command suffix from `COMMAND` to `CMD`)
+- Renamed the PMA "device id" to "driver id" across the public API (`CM_PMA_*_DID` constants, `driver_id` in `get_address_ranges`)
+- Changed `get_address_ranges` to report per-range attributes (`is_memory`, `is_device`, `is_readable`, `is_writeable`, `is_executable`, `is_read_idempotent`, `is_write_idempotent`, and `driver_id`)
+- Replaced the `--store-json-config`/`--load-json-config` options with a `format:<lua|json>` sub-option on `--store-config`/`--load-config`, defaulting to the format inferred from the filename extension
+- Changed `--initial-proof`/`--final-proof` to default to Lua tables and accept `format:<lua|json>` and `label:` sub-options, where before they were dumped only as JSON
+- Reworked command-line option parsing so compound options such as `--volume` and `--port-forward` take `key:value` sub-options, and short options take a space-separated value (`-u <name>` instead of `-u=<name>`)
+- Changed memory ranges with an unset start to be placed past the end of RAM, rounded up to a power of two and aligned to their length, with flash drives and nvrams drawn from a shared pool
+- Changed `log_send_cmio_response` and `verify_send_cmio_response` to treat invalid responses and advance-state responses delivered outside an rx-accepted manual yield as no-ops, while the live `send_cmio_response` still rejects them as errors
+- Changed the uarch state-access layer to align misaligned accesses down to their natural size instead of rejecting them
+- Changed JSON-RPC error logs to omit the Boost `source_location` suffix at non-debug levels
 - Renamed all C++ headers from `.h` to `.hpp`, and renamed `machine-c-api.{h,cpp}` to `cm.{h,cpp}`
-- Bumped machine configuration archive version from 6 to 7 (for the new `nvram_configs` and `label` fields)
+- Bumped machine configuration archive version from 6 to 7 (for the new `nvram` and `label` fields)
 - Moved the `/run/cartesi/memoryranges/` sysfs setup from the DTB init script into `cartesi-init`
 - Updated guest bootargs to bind `uio_pdrv_genirq` to generic-uio nodes
 - Bumped test `linux.bin` and `rootfs.ext2` images
 
+## Removed
+- Removed the `--store-json-config` and `--load-json-config` options (folded into the `format:` sub-option of `--store-config`/`--load-config`)
+- Removed the `--replace-flash-drive` option, subsumed by `--replace-memory-range`
+- Removed `CM_ERROR_REGEX_ERROR` (covered by `CM_ERROR_RUNTIME_ERROR`) and `CM_ERROR_SYSTEM_ERROR`, and renumbered the error enum
+- Removed `machine_reg_get_name` in favor of `get_address_name`
+- Removed `mark_dirty_page` from the uarch and state-access interfaces
+
 ## [0.20.0] - 2026-04-09
 ## Added
 - Added RISC0 zkVM integration for fraud proof verification, with C++, Rust, and Solidity implementations

diff --git a/Dockerfile b/Dockerfile
@@ -1,4 +1,7 @@
-FROM debian:trixie-20250811 AS toolchain
+ARG BUILD_BASE=debian:trixie-20250811
+ARG RUNTIME_BASE=debian:trixie-20250811-slim
+
+FROM $BUILD_BASE AS toolchain
 
 RUN apt-get update && \
     DEBIAN_FRONTEND=noninteractive apt-get install --no-install-recommends -y \
@@ -56,15 +59,24 @@ FROM builder AS debian-packager
 RUN make install-uarch debian-package DESTDIR=$PWD/_install
 
 ####################################################################################################
-FROM debian:trixie-20250811-slim
+FROM $RUNTIME_BASE
 ARG TARGETARCH
+ARG RUNTIME_BASE
+LABEL io.cartesi.machine-emulator.base-image="$RUNTIME_BASE"
 
 COPY --from=debian-packager /usr/src/emulator/machine-emulator_${TARGETARCH}.deb machine-emulator.deb
+COPY tests/dependencies tests/dependencies.sha256 /usr/share/cartesi-machine/
 
 RUN apt-get update && \
-    apt-get install -y ./machine-emulator.deb && \
+    apt-get install -y gosu ./machine-emulator.deb && \
     rm -rf /var/lib/apt/lists/* /var/cache/apt/* machine-emulator.deb
 
+# Carried but dormant (no ENTRYPOINT set here, so production behavior is
+# unchanged): lets a derived dev image (e.g. doc/) opt into running as the host
+# user by pointing ENTRYPOINT at this script. Needs gosu, installed above.
+COPY tools/docker-entrypoint.sh /usr/local/bin/entrypoint.sh
+RUN chmod +x /usr/local/bin/entrypoint.sh
+
 RUN groupadd --system --gid 102 cartesi && \
     useradd --system --uid 102 --gid 102 --no-create-home --home /nonexistent --comment "cartesi user" --shell /bin/false cartesi
 

diff --git a/Makefile b/Makefile
@@ -77,7 +77,7 @@ 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
-EMU_TO_LUA_PATH= src/cartesi/util.lua src/cartesi/gdbstub.lua src/cartesi/evmu.lua
+EMU_TO_LUA_PATH= src/cartesi/util.lua src/cartesi/gdbstub.lua src/cartesi/evmu.lua src/cartesi/bash.lua src/cartesi/hash-tree.lua
 EMU_TO_LUA_THIRD_PARTY_PATH= src/cartesi/third-party/bint.lua
 EMU_TO_LUA_CPATH= src/cartesi.so
 EMU_TO_LUA_CARTESI_CPATH= src/cartesi/jsonrpc.so
@@ -105,6 +105,12 @@ export UARCH_DEFS
 TAG ?= devel
 DEBIAN_IMG ?= cartesi/machine-emulator:$(TAG).deb
 
+# Base images for the emulator Dockerfile. Single source of truth: passed as
+# build-args and stamped into the image as a label so downstream images (e.g.
+# doc/) can reuse the exact same base without duplicating these values.
+BUILD_BASE ?= debian:trixie-20250811
+RUNTIME_BASE ?= debian:trixie-20250811-slim
+
 # Docker image platform
 BUILD_PLATFORM ?=
 
@@ -247,11 +253,14 @@ test% coverage% build-tests%:
 
 build-tests-misc-with-builder-image: build-emulator-builder-image
 
-lint check-format format check-format-lua check-lua format-lua:
+lint check-format format:
 	@$(MAKE) $@-src $@-tests
 
+check-format-lua check-lua format-lua:
+	@$(MAKE) $@-src $@-tests $@-doc
+
 lint-% check-format-% format-% check-format-lua-% check-lua-% format-lua-%:
-	@eval $$($(MAKE) -s --no-print-directory env); $(MAKE) -C $(if $(findstring -src,$@),src,tests) $(subst -src,,$(subst -tests,,$@))
+	@eval $$($(MAKE) -s --no-print-directory env); $(MAKE) -C $(if $(findstring -doc,$@),doc,$(if $(findstring -src,$@),src,tests)) $(subst -doc,,$(subst -src,,$(subst -tests,,$@)))
 
 source-default:
 	@eval $$($(MAKE) -s --no-print-directory env); $(MAKE) -C $(SRCDIR)
@@ -269,13 +278,13 @@ $(SRCDIR)/interpret-jump-table.hpp:
 	@eval $$($(MAKE) -s --no-print-directory env); $(MAKE) -C $(SRCDIR) interpret-jump-table.hpp
 
 build-emulator-builder-image:
-	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 .
+	docker build $(DOCKER_PLATFORM) --build-arg DEBUG=$(debug) --build-arg COVERAGE=$(coverage) --build-arg THREADS=$(threads) --build-arg SANITIZE=$(sanitize) --build-arg BUILD_BASE=$(BUILD_BASE) --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 .
+	docker build $(DOCKER_PLATFORM) --build-arg BUILD_BASE=$(BUILD_BASE) --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 THREADS=$(threads) --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) --build-arg BUILD_BASE=$(BUILD_BASE) --build-arg RUNTIME_BASE=$(RUNTIME_BASE) -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 THREADS=$(threads) --build-arg SANITIZE=$(sanitize) --build-arg TAG=$(TAG) -t cartesi/machine-emulator:tests -f tests/Dockerfile .
@@ -284,7 +293,7 @@ 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 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 THREADS=$(threads) --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) --build-arg BUILD_BASE=$(BUILD_BASE) -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/doc/.dockerignore b/doc/.dockerignore
@@ -0,0 +1,6 @@
+Makefile
+README.md.template
+doxygen
+recipes/cache
+recipes/*.ext2
+!recipes/rootfs-docs.ext2
diff --git a/doc/.gitignore b/doc/.gitignore
@@ -0,0 +1,2 @@
+recipes/rootfs-docs.inputs.sha256
+recipes/rootfs-docs.inputs.sha256-have
diff --git a/doc/.luacheckrc b/doc/.luacheckrc
@@ -0,0 +1,16 @@
+-- alerts.lua and replace.lua are pandoc Lua filters: pandoc runs them inside
+-- its own interpreter, which injects the `pandoc` module along with the
+-- FORMAT and PANDOC_SCRIPT_FILE globals, and invokes the filter callbacks
+-- (Div, Pandoc) that the filter defines at the top level. Declare that
+-- environment so luacheck does not report the pandoc API as undefined or
+-- non-standard globals.
+--
+-- The recipe scripts under recipes/ are ordinary lua5.4 programs and are left
+-- under luacheck's default configuration, so genuine stray globals there are
+-- still caught.
+local pandoc_filter = {
+    read_globals = { "FORMAT", "PANDOC_SCRIPT_FILE", "pandoc" },
+    globals = { "Div", "Pandoc" },
+}
+files["alerts.lua"] = pandoc_filter
+files["replace.lua"] = pandoc_filter
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		recipes/rootfs-docs.inputs.sha256
		recipes/rootfs-docs.inputs.sha256-have