Skip to content

Latest commit

 

History

History
110 lines (77 loc) · 4.99 KB

README.adoc

File metadata and controls

110 lines (77 loc) · 4.99 KB
Raw

RISC-V Unified Database

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 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 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:

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

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 validate                # validate against the schema
./do gen:arch[generic_rv64]  # generate arch spec for the 'generic_rv64' config