Project: udb - The Ruby Toolbox

This project is under rapid development. Expect schemas and APIs to change.

The data in the `spec` directory is also a work in progress and may be incorrect.

That said, the following data has been validated against third-party sources:

* Instruction encodings are validated to match riscv-opcodes
* Instruction names and assembly formats are validated against LLVM.

Quick links

The latest UDB-generated UNOFFICIAL RISC-V specifications.
UDB Documentation
How-to/recipes

Overview

The goal of the RISC-V Unified Database (UnifiedDB/UDB) is 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.

In addition to storing the data, UnifiedDB also provides many tools that use the data to generate artifacts such as specification documents, toolchain inputs, and simulators.

UnifiedDB is an open-source, worldwide project. Contributors do not need to be members of RISC-V International (RVI), though maintainers discuss strategic direction and coordinate with the RISC-V standard through the UnifiedDB Special Interest Group (UDB SIG) at RVI.

Repository structure

The following directories contain information relevant to most users of UnifiedDB

spec: Holds all data specification files, along with their schemas
spec/std: The RISC-V standard
spec/custom: Non-standard RISC-V extensions
spec/schemas: Data schemas for the specification content
cfgs: Configurations used by backends to customize generated outputs

Additionally, developers will be interested in the following:

backends: Tools to generate artifacts (documents, simulators, etc.) from UDB data
tools/ruby-gems: Ruby gem libraries for interacting with UDB / IDL
bin: Wrapper scripts to run commands in the development environment

Getting Started

Prerequisites

UnifiedDB tooling is designed to run natively on your host using mise.

A container runtime (Docker or Podman) is optional. It is only required for building generated C ISS code when a suitable native C toolchain and/or RISC-V cross-compiler is unavailable natively.

All core workflows—Ruby, Python, npm, and all other UDB generators—run natively (via mise) without a container.

Native Setup (mise)

From the repo root, run:

bin/setup

That’s it. bin/setup installs mise if needed, uses it to install all tool versions (Ruby, Python, Node.js, CMake, etc.), installs all dependencies (Ruby gems, Python packages, npm packages, native binaries), sets up git hooks, and walks you through choosing a C++ toolchain. It is safe to re-run at any time.

When it finishes, it will tell you how to activate mise in your shell profile so that mise-managed tools are available in future terminal sessions, and remind you to use the wrappers in bin/ when invoking any tool.

Tasks

./bin/regress -h             # get help on running regression tests

./bin/generate -h            # get help on generating content from UDB

./bin/chore -h               # get help on running repository development chores

udb

Development