How riscv/sail-riscv works
Main Components
• Sail Model Core: This is the heart of the project (the “model” directory) that contains Sail specification files (e.g., riscv_insts_base.sail, riscv_types.sail, and many others). It defines instruction formats, decoder/encoder mappings, execution semantics, and concurrent features.
• C Emulator: Found under “c_emulator”, this component is generated from the Sail model and provides an executable platform to load and simulate RISC-V ELF binaries. It includes platform support (memory map, ELF loader, command-line options) and interfaces with external libraries (like libgmp and SoftFloat from the “dependencies” directory).
• Testing Infrastructure: In “test” (with subdirectories “riscv-tests” and “first_party”), there are test binaries, test scripts, and configuration files to run test suites on the emulator. This component validates the specification and its runtime behavior.
• Theorem Prover Support: The “handwritten_support” directory offers additional library definitions that support formal reasoning in Isabelle, Coq, and HOL4; it integrates with the Sail model to generate prover definitions.
• Build and Deployment Infrastructure: Build scripts (CMakeLists.txt, build_simulators.sh, and cmake modules), GitHub workflows, and Makefiles are used for compiling, testing, and packaging the project.
Relationships and Interactions
• The Sail Model (specification) acts as the source of truth. Its Sail code is processed by the Sail toolchain to:
– Generate documentation (both human-read and formal),
– Produce a C emulator executable,
– Create theorem-prover definitions (via handwritten support).
• The C Emulator depends on both the model and external libraries (e.g., SoftFloat under “dependencies”) and interacts with test binaries (located in “test” and “os-boot”) to demonstrate platform functionality.
• The testing layer feeds ELF files and test programs into the emulator (data flow from “test” to “c_emulator”), and results can be used to measure specification coverage.
• Documentation is generated directly from the Sail model, with additional extension details provided in the “doc” subdirectory. This connects back to the specification core.
• Build systems coordinate the integration: CMake files, GitHub workflows, and build scripts manage the compilation of both the emulator and the verification artifacts.
Architectural Patterns and Design Principles
• Layered Architecture: Separate layers consist of:
– The core formal model (Sail model),
– Derived artifacts (emulator, documentation, proofs),
– Supporting infrastructure (build scripts and tests).
• Toolchain Integration: The Sail toolchain drives multiple outputs from a single source specification (e.g., simulation executables, documentation, Prover interfaces).
Including Relevant Technologies
• Sail language and its associated toolchain,
• C language and its build system (CMake; Makefiles),
• Libraries such as GMP and SoftFloat in “dependencies”,
• Theorem proving tools (Isabelle, HOL4, Coq),
• Documentation generation tools (Latex, AsciiDoc).