https://github.com/riscv-software-src/riscv-unified-db
Machine-readable database of the RISC-V specification, and tools to generate various views
https://github.com/riscv-software-src/riscv-unified-db
risc-v riscv
Last synced: about 1 year ago
JSON representation
Machine-readable database of the RISC-V specification, and tools to generate various views
- Host: GitHub
- URL: https://github.com/riscv-software-src/riscv-unified-db
- Owner: riscv-software-src
- License: other
- Created: 2024-07-12T18:45:36.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-09T17:56:44.000Z (about 1 year ago)
- Last Synced: 2025-04-09T18:16:39.495Z (about 1 year ago)
- Topics: risc-v, riscv
- Language: Ruby
- Homepage: https://riscv-software-src.github.io/riscv-unified-db/
- Size: 46.9 MB
- Stars: 54
- Watchers: 12
- Forks: 37
- Open Issues: 170
-
Metadata Files:
- Readme: README.adoc
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
= RISC-V Unified Database
== Generated artifacts
The latest documentation artifacts generated from the HEAD of main, include ISA manuals, profiles, etc.,
can be found https://riscv-software-src.github.io/riscv-unified-db/index.html[on the GitHub pages site].
== 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[example_rv64_with_overlay]`).
** 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[example_rv64_with_overlay]`).
=== 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._:
```bash
./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 'example_rv64_with_overlay' config
./do gen:arch[example_rv64_with_overlay]
----
== More info
* xref:arch/README.adoc[Architecture specification format]