docs: refactor README

CHANGELOG.md

@@ -5,18 +5,76 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
-### Added
-- Added the "log_step" method
-- Added the "verify_step" method
-- Added the "--log-step" option to "cartesi-machine.lua"
-
-### Changed
-- Added a "--jobs" option to "uarch-riscv-tests.lua" test
-- add-created-files.diff should now be applied with `-p1`
-- Improved send_cmio_response bounds checking
+## Added
+- Added `libluacartesi.a` and `libluacartesi_jsonrpc.a` static libraries when installing to allow packaging statically linked Lua programs
+- Added `--remote-spawn` command line option to spawn remote machines
+- Added `--remote-health-check` command line option to check availability of remote machines
+- Added `--store-json-config` command line option to store machine configs to JSON files
+- Added `--load-json-config` command line option to load machine configs from JSON files
+- Added `--server-fd` command line option to JSON-RPC remote machine
+- Added `--setpgid` command line option to JSON-RPC remote machine
+- Added `cartesi.tobase64`, `cartesi.frombase64`, `cartesi.tojson`, and `cartesi.fromjson` Lua functions
+- Added various new methods to JSON-RPC remote machine interface to allow more precise management of remote machine processes
+- Added timeout support to JSON-RPC remote machine requests
+- Added capability to retrieve PID of spawned remote machines
+- Added support for VirtIO devices in JSON configs
+- Added the `--log-step` command line option to log multiple machine cycles
+- Added the `cm_log_step` and `cm_verify_step` methods to log multiple machine cycles and verify with ZK VMs
+- Added the `cm_receive_cmio_request` method, the counterpart of `cm_send_cmio_response` method
+
+## Fixed
+- Fixed various linting errors with the latest Clang static analyzer
+- Fixed broken link when running `make bundle-boost`
+- Fixed many broken links in the README and markdown files
+- Fixed issues when using `--network` option in Alpine guests
+- Fixed issue when using `--assert-rolling-template`
+- Fixed `--skip-root-hash-store` not skipping root hash computation
+- Fixed kernel panic bug when feeding 100k stdin inputs into VirtIO console
+- Fixed bug when trying to advance multiple inputs through the `cartesi-machine` CLI
+- Fixed compile errors when targeting Windows, Alpine Linux, and WebAssembly
+
+## Changed
+- Optimized RISC-V instruction decoder to use token threading, computed goto, and big jump tables
+- Optimized RISC-V instruction fetcher to cache latest accessed pages
+- Refactored the code to use C++20 standard, which is now a minimum requirement
+- Refactored the public C API to be simpler and easier to use with other programming languages
+- Refactored the Lua API to make remote and local use the same API interface
+- Refactored and simplified many portions of the code, improving maintainability of the project
+- Changed default GCC compiler flags to better optimize the RISC-V interpreter
+- Changed flash drive start address configuration to be non-mandatory (it will be automatically chosen)
+- Changed sibling hashes ordering in JSON logs to match the expected ordering in Lua test suite
+- Changed rebind method of remote machines to support binding on port 0 and return the bound address
+- Changed to Debian RISC-V toolchain when compiling microarchitecture
+- Changed `--remote-fork` command line option to accept an address
+- Changed `add-generated-files.diff` to be applied with `patch -Np1` to make packaging easier
+- Changed default machine config to include bootargs
+- Changed machine configs and access logs to be represented as JSON strings in the C API
+- Renamed `--log-uarch-step` command line option to `--log-step-uarch`
+- Renamed `--log-uarch-reset` command line option to `--log-reset-uarch`
+- Renamed `--auto-uarch-reset` command line option to `--auto-reset-uarch`
+- Renamed various C API functions, structs, and enumerations
+- Revamped project README with more up-to-date explanations and simplified instructions
+- Changed help and configs to be printed to `stdout` instead of `stderr`
+- Changed the public C API to require less manual memory management
+- Improved documentation in the public C API header
+- Improved CI to use more parallel jobs when testing
+- Improved `send_cmio_response` bounds checking
+- Split `iflags` CSR into multiple CSRs
+
+## Removed
+- Removed publishing of Debian package artifacts in favor of official Linux package repositories
+- Removed use of `cartesi/toolchain` image
+- Removed automatic strip of binaries when performing `make install` (stripping should now be done when packaging)
+- Removed `no4lvl` from bootargs (Sv57 address translation is now disabled at interpreter level to fix NodeJS JIT issues)
+- Removed `rootfstype=ext2` from bootargs, allowing use of root filesystems in other formats, such as Ext4 and SquashFS
+- Removed all `*-defines.h` headers
+- Removed all specific read/write of machine registers from the public API
+- Removed various C API functions
+- Removed `dkjson` Lua library (not needed since we have our own JSON encoding functions now)
+- Removed GDB documentation from the repository (moved to the wiki)
+- Removed internal development documentation from the README (moved to the wiki)
+- Removed many dead code segments after the refactoring
 
-### Fixed
-- Fixed --skip-root-hash-store not skipping root hash computation when using the cli
 
 ## [0.18.1] - 2024-08-12
 ### Changed

Dockerfile

@@ -1,4 +1,4 @@
-FROM debian:bookworm-20241016 AS toolchain
+FROM debian:bookworm-20250113 AS toolchain
 
 RUN apt-get update && \
     DEBIAN_FRONTEND=noninteractive apt-get install --no-install-recommends -y \
@@ -80,7 +80,7 @@ FROM builder AS debian-packager
 RUN make install-uarch debian-package DESTDIR=$PWD/_install
 
 ####################################################################################################
-FROM debian:bookworm-20241016-slim
+FROM debian:bookworm-20250113-slim
 ARG MACHINE_EMULATOR_VERSION=0.0.0
 ARG TARGETARCH
 

LICENSES.md

@@ -0,0 +1,29 @@
+# License
+
+This projects is licensed under the L[LGPL 3.0](https://www.gnu.org/licenses/lgpl-3.0.html) license. See the license terms in [COPYING](COPYING).
+
+## Submodules and Dependencies
+
+This project includes several submodules and dependencies, each with its own licensing:
+
+- `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/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.
+- `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
+
+The project releases several Debian packages, each subject to its specific licensing terms:
+
+- `cartesi-machine-[VERSION]_[ARCHITECTURE].deb` and `cartesi-machine-tests-[VERSION]_[ARCHITECTURE].deb` packages are licensed under LGPL v3.0 and may include or link to other software components with different licenses.
+- `cartesi-machine-tests-data-[VERSION].deb`: This package contains files that are individually licensed under various terms, including but not limited to Apache-2.0, BSD-3-Clause-Regents, BSD-3-Clause, and GPL-2.0-only. For a comprehensive overview of the licenses applicable to specific files within this package, please refer to its copyright file, e.g., [tools/template/tests-data-copyright.template](tools/template/tests-data-copyright.template).
+
+For detailed licensing information of each Debian package, please refer to the copyright file included within the package.
+
+## Additional Notes
+
+This project may include or link to other software components with different licenses. Contributors and users are responsible for ensuring compliance with each component's licensing terms. For detailed information, please refer to the individual LICENSE files within each directory or submodule, and for the Debian packages, please review the respective copyright and licensing details as mentioned above.

Makefile

@@ -206,7 +206,7 @@ doc:
 bundle-boost: $(DEPDIR)/downloads/boost
 $(DEPDIR)/downloads/boost:
 	mkdir -p $(DOWNLOADDIR)
-	wget -O $(DEPDIR)/downloads/boost_1_81_0.tar.gz https://boostorg.jfrog.io/artifactory/main/release/1.81.0/source/boost_1_81_0.tar.gz
+	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