RISC-V Unified Database

Generated artifacts

The following artifacts have been generated from the top of the main branch:

• ISA Manual with instruction and CSR appendix

• configuration-specific documentation

• Ruby API documentation (database interface)

• Ruby IDL API documentation (IDL compiler)

• RVI20 Profile Release

• RVA20 Profile Release

• RVA22 Profile Release

• MC100 Certification Requirements Document

Overview

The RISC-V Unified Database is intended to hold all the information needed to describe RISC-V, including a list of extensions, instruction specifications, CSR specifications, and documentation prose. The vision is that anything one would need for RISC-V can be generated from the information in this repository.

This repository contains:

• A (eventually complete) description of the RISC-V specification in a machine-readable format.

• A tool to generate multiple views of that spec, including:

  • A configuration-specific, human-readable documentation webpage

  • [COMING SOON] A configuration-specific Instruction Set Simulator

  • More backends are planned

What can it do?

Working examples:

• Generate configuration-specific documentation tailored to the set of implemented extensions and unnamed implementation options (e.g., ./do gen:html[generic_rv64]).

  • Only implemented extensions/instructions/CSRs are included

  • Unreachable/unimplemented parts of the formal specification are pruned away

  • A dedicated documentation page for every implemented instruction, including its encoding, pruned execution behavior, and what types of exceptions it may cause.

  • A dedicated documentation page for every implemented CSR, including its (possibly runtime-changing) encoding, fields, and pruned behavior on reads and writes

  • Clickable links to all mentions of instructions, extensions, CSRs, CSR fields, and glossary terms.

• Generate documentation for specific extensions (e.g., ./do gen:ext_pdf[B])

  • Automatically include a complete list of added instructions and CSRs

  • Per-instruction documentation

  • Per-CSR documentation

  • Formal specification

• Generate a single YAML file containing everything knowable about a configuration (e.g., ./do gen:cfg_arch[generic_rv64]).

Possibilities:

• Generate binutils files for an extension

• Generate instruction tables for compilers

• Generate riscv-opcodes

• Generate the full RISC-V specification, along with an appendix of instructions and CSRs

• …​

Prerequisites

There are two supported ways to run the RISC-V Unified Database, both of which are container-based.

Singularity/Apptainer

You can run within Singularity CE (>= 3.3) or Apptainer (>= 1.0) container system. Either one will work (they are forks).

If it is not installed, either ask your IT admin or:

• For Apptainer, see Apptainer Installation.

• For Singularity CE, see Singularity CE Installation.

Note	You do not need root privileges to download or use the container. However, to modify/build the container, you will need either root privileges or the ability to run in fakeroot mode. See Singularity Fakeroot Documentation for more information.

When you run with Singularity/Apptainer, the files under bin/ will run within the container, e.g.:

./bin/ruby --version
# => ruby 3.2.3 (2024-01-18 revision 52bb2ac0a6) [x86_64-linux-gnu]

Devcontainer

You can also leverage devcontainers to run the RISC-V Unified Database.

This is especially useful when using Visual Studio Code or GitHub codespaces, as it will setup up your IDE environment for you.

VS Code

To run the devcontainer locally, you will need to have Docker installed.

With Docker installed, install the Dev Containers extension in VS Code.

You can then run Dev Containers: Open Folder in Container…​ from the Command Palette (Ctrl+Shift+P) and select the folder with this repository.

GitHub Codespaces

You can start a GitHub Codespace for this repository by clicking the "Code" button and selecting "Open with Codespaces".

Tasks

Quick start:

./do --tasks                 # list all documented tasks

## examples

# validate against the schema
./do validate

# generate all versions of ISA manual, as an Antora static website
./do gen:html_manual MANUAL_NAME=isa VERSIONS=all

# generate an implementation-specific spec for the 'generic_rv64' config
./do gen:arch[generic_rv64]

More info

• Architecture specification format