= RISC-V Unified Database

== Generated artifacts

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

• https://riscv-software-src.github.io/riscv-unified-db/manual/html/index.html[ISA Manual with instruction and CSR appendix]
• https://riscv-software-src.github.io/riscv-unified-db/example_cfg/html/index.html[configuration-specific documentation]
• https://riscv-software-src.github.io/riscv-unified-db/ruby/arch_def/index.html[Ruby API documentation (database interface)]
• https://riscv-software-src.github.io/riscv-unified-db/ruby/idl/index.html[Ruby IDL API documentation (IDL compiler)]
• https://riscv-software-src.github.io/riscv-unified-db/pdfs/RVI20.pdf[RVI20 Profile Release]
• https://riscv-software-src.github.io/riscv-unified-db/pdfs/RVA20.pdf[RVA20 Profile Release]
• https://riscv-software-src.github.io/riscv-unified-db/pdfs/RVA22.pdf[RVA22 Profile Release]
• https://riscv-software-src.github.io/riscv-unified-db/pdfs/MC100.pdf[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 https://riscv-software-src.github.io/riscv-unified-db/manual/html/index.html[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 https://github.com/riscv/riscv-opcodes[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 https://apptainer.org/docs/admin/main/installation.html[Apptainer Installation].
• For Singularity CE, see https://docs.sylabs.io/guides/latest/admin-guide/installation.html[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 https://docs.sylabs.io/guides/4.1/user-guide/fakeroot.html[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 https://containers.dev/[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 https://docs.docker.com/engine/install[Docker installed].

With Docker installed, install the https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers[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:

[source,bash]

./do --tasks # list all documented tasks

examples

run smoke tests

./do test:smoke

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

• xref:arch/README.adoc[Architecture specification format]