= 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/rva.pdf[RVA Profile Family]
• https://riscv-software-src.github.io/riscv-unified-db/pdfs/MC-1.pdf[MC-1 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] 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/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

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

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