RISC-V Unified Database

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 taylored 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/unimplmented 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 dedication 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

The only requirement is the Singularity CE (>= 3.3) or Apptainer (>= 1.0) container system. Either one will work (they are forks).

If it is not installed, either as 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.

Setup

Do once:

./bin/setup

# or, if you also want development tools (:development group in Gemfile) installed
# DEVELOPMENT=1 ./bin/setup

Note	If you forget, don’t worry. Setup will be invoked by any program in bin/ if necessary.

VSCode

If using Visual Studio Code and want to use development tools, you will need to restart the editor after setup.

Helpful extensions are

• AsciiDoc

• YAML

• Solargraph (for a Ruby Language Server)

• Singularity (if you plan on working on the container)

The .vscode/settings.json file in the repo will ensure that Solargraph works without any additional configuration (assuming you’ve already run ./bin/setup).

Tasks

Quick start:

./do --tasks                 # list all documented tasks

# examples
./do gen:arch[generic_rv64]  # generate arch spec for the 'generic_rv64' config
./do validate                # validate against the schema

More info

• Architecture specification format

• Documentation for the generator tool and IDL

  • YARD docs for the generator tool and IDL