# riscv/sail-riscv architecture

> Architecture diagram of the GitHub repository riscv/sail-riscv, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/riscv/sail-riscv
- Repository: https://github.com/riscv/sail-riscv

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Specification"
        SAIL["Sail Specification (Model)"]:::specification
    end

    subgraph "Generated Artifacts"
        CEMULATOR["C Emulator"]:::emulator
        DOC["Documentation Output"]:::documentation
        THEOREM["Formal Verification Artifacts"]:::verification
    end

    subgraph "Testing & Verification"
        TESTING["Testing Infrastructure"]:::testing
    end

    subgraph "Build Infrastructure"
        BUILD["Build & Deployment Infrastructure"]:::build
    end

    subgraph "External Dependencies"
        EXTERNAL["External Libraries (GMP, SoftFloat)"]:::external
    end

    OSBOOT["OS Boot Support"]:::boot

    SAIL -->|"Emulator Generation (via Sail toolchain)"| CEMULATOR
    SAIL -->|"Doc Generation (LaTeX/AsciiDoc)"| DOC
    SAIL -->|"Theorem-Prover Definitions"| THEOREM
    TESTING -->|"Test Inputs/Results"| CEMULATOR
    BUILD -->|"Build Coordination"| CEMULATOR
    BUILD -->|"Build Coordination"| DOC
    BUILD -->|"Build Coordination"| THEOREM
    EXTERNAL -->|"Platform Dependencies"| CEMULATOR
    CEMULATOR -->|"OS Boot"| OSBOOT

    click SAIL "https://github.com/riscv/sail-riscv/tree/master/model/"
    click CEMULATOR "https://github.com/riscv/sail-riscv/tree/master/c_emulator/"
    click DOC "https://github.com/riscv/sail-riscv/tree/master/doc/"
    click TESTING "https://github.com/riscv/sail-riscv/tree/master/test/"
    click THEOREM "https://github.com/riscv/sail-riscv/tree/master/handwritten_support/"
    click BUILD "https://github.com/riscv/sail-riscv/blob/master/CMakeLists.txt"

    classDef specification fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef emulator fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef documentation fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef verification fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef testing fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef build fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef external fill:#fefefe,stroke:#818182,stroke-width:2px;
    classDef boot fill:#e2f0cb,stroke:#3c763d,stroke-width:2px;
```
