When I first heard about the RISC-V Unified Database project, I was immediately drawn to its ambition: to become a single, machine-readable source of truth for the RISC-V Instruction Set Architecture (ISA). Once complete, the project would power a broad ecosystem of downstream tools such as assemblers, disassemblers, simulators, debuggers and more.
Coming from a software background, I had mostly thought of ISAs as static PDFs and reference manuals. Instead of every tool re-encoding the ISA in its own ad hoc format, the Unified Database aims to centralize that knowledge and let generators produce consistent artifacts.
As part of my mentorship within the Linux Foundation’s RISC-V Mentorship Program, I joined Ventana Micro (now part of Qualcomm). Over the course of the mentorship, I worked closely with my mentor to follow defined milestones, making the following contributions to the UDB project:
- Defining General Purpose Registers (GPRs) in the unified database
- Creating a QEMU instruction-set generator for insn32.decode
- Building a QEMU opcode-table generator for rv_opcode_data
- Adding a GNU Assembler test generator that emits GAS tests from UDB
Each of these efforts taught me something different about RISC-V.
Stepping into the RISC-V Unified Database
The RISC-V Unified Database is a monorepo that contains:
- A machine-readable model of the RISC-V ISA, including extensions, instructions, and CSRs
- Supporting schemas and tooling
- A growing collection of backends that generate artifacts for downstream tools
Before contributing, my understanding of RISC-V was fairly high level. I knew it as an open ISA with a rapidly growing ecosystem and strong interest in custom extensions. Working with UDB forced me to understand the ISA in a much more structured way:
- What information about each instruction needs to be captured in a database for it to be useful to tools?
- How should registers be represented so every tool can reason about them consistently?
- How do different consumers such as QEMU and binutils expect RISC-V information to be organized?
My journey with UDB started with a surprisingly basic question: where are the registers?
Adding GPR Information to the Unified Database
Pull Request: feat: add GPR Information to UDB (#1150)
The Problem
Although the database already modeled many aspects of the ISA, such as extensions, instructions, and CSRs, it lacked a machine-readable definition of the RISC-V General Purpose Registers.
This led to two main issues:
- Downstream tools often hardcoded register names, ABI aliases, and calling convention roles.
- There was no canonical description that could be reused for code generation, documentation, or testing.
In issue #1085 I captured the need to model registers, including GPRs, floating-point registers, and vector registers.
The Solution
My PR introduced structured register information into UDB.
The main pieces included:
- Schema Definition:
spec/schemas/register_schema.json
A JSON schema describing how multiple types of register files are represented in YAML: names, ABI mnemonics, calling-convention roles, and special attributes such as the zero register. - Register YAML Files:
- GPRs: spec/std/isa/register_file/X.yaml
Models all 32 RISC-V GPRs (x0–x31) with:- ABI names (zero, ra, sp, gp, t0–t6, s0–s11, a0–a7)
- Calling convention classifications (caller/callee-saved, arguments, return values)
- Special roles like stack pointer, frame pointer, zero register
- Conditional handling for RV32E, where only 16 registers are present
- FPRs: spec/std/isa/register_file/F.yaml
- All standard floating-point registers, with ABI conventions and roles.
- Vector Registers: spec/std/isa/register_file/V.yaml
- Complete vector register set for RISC-V, including naming and special-purpose descriptions.
- GPRs: spec/std/isa/register_file/X.yaml
- Integration into the UDB Type System:
- spec/schemas/schema_defs.json extended to recognize all register types
- database_obj.rb gained a RegisterFile kind for all types
- architecture.rb updated so architectures can load multiple register files (GPRs, FPRs, VRs) alongside extensions and instructions
Why RISC-V Data Modeling Matters
Adding structured GPR, FPR, and VR information allows scripts generating content for downstream tools (disassemblers, debuggers, code generators) to directly query register information from UDB instead of relying on hardcoded values.
For me, this was a deep introduction to the data modeling side of RISC-V. It shifted my perspective from simply asking “does the ISA function?” to “can we represent it with enough fidelity and structure that dozens of tools and contributors can consume it correctly and consistently?”
Generating QEMU’s insn32.decode from UDB
Pull Request: feat(backends): add QEMU generator for RISC-V instruction set (#1258)
After working on core architectural modeling, I moved to the backend side, specifically looking at how UDB could drive QEMU, one of the most widely used RISC-V emulators.
The Goal
QEMU’s RISC-V target relies on a file called insn32.decode to describe how 32-bit instructions are decoded. The file specifies instruction bit patterns, including opcode and funct fields, and maps those patterns to decode rules that drive operand extraction and translation logic.
The goal of this PR was to generate insn32.decode directly from the Unified Database, allowing QEMU’s decode logic to be derived from the same canonical ISA description instead of being maintained separately.
The Generator
The generator lives at:
- backends/generators/qemu/generate_insn32_decode.py
Example usage:
python3 generate_insn32_decode.py \
–include-all \
–arch BOTH \
–output generated_insn32_decode_output
Key implementation details:
- Since UDB does not yet model all instruction formats in the exact way QEMU expects, I introduced a temporary Python-side mapping to bridge that gap, with a clear TODO to remove it once the database carries that information natively.
- The generator uses instruction metadata from UDB to infer opcode layouts, instruction groupings, and architecture-specific inclusion.
This work also resolved issue #1255, which requested a QEMU instruction-set generator based on UDB.
Challenges and Learnings
- I spent significant time studying QEMU’s decode format and aligning it with UDB’s instruction model.
- Design decisions were needed around extension-gated instructions and future expansions such as compressed instructions and RV64-only decodes.
- This effort highlighted how important precise, machine-readable ISA descriptions are when connecting different ecosystems like UDB, QEMU, and binutils.
Emitting rv_opcode_data for QEMU Disassembly
Pull Request: feat(backends): add opcode-table generator for QEMU (#1271)
QEMU’s RISC-V disassembler uses a structure called rv_opcode_data in qemu/disas/riscv.c to match instruction encodings and drive mnemonic and operand formatting during disassembly.
After generating decode rules, the next logical step was generating the opcode tables themselves from UDB.
The Generator
This PR adds another QEMU backend:
- backends/generators/qemu/generate_opcode_table.py
Typical usage:
python3 generate_opcode_table.py \
–include-all \
–output ./rvi_opcode_data.snippet
The script extracts instruction mnemonics, operand information, opcode and funct fields, and extension membership from UDB. It then emits a C snippet that mirrors the layout used by QEMU’s rv_opcode_data.
Impact
Generating opcode tables from UDB brings QEMU closer to using a single canonical ISA source. It reduces inconsistencies between decode logic, disassembly, and documentation, and demonstrates that UDB can drive real production tools rather than just serving as a static data repository.
Generating GNU Assembler Tests from UDB
Pull Request: feat(backends): add GNU Assembler Test Generator for RISC-V (#1139)
Before the QEMU work, I contributed a backend targeting binutils GAS. The idea was simple: instead of hand-writing tests for every instruction and extension, generate them from UDB.
What the Generator Does
This backend produces GNU Assembler test files in the format expected by the binutils test suite. It iterates over instructions in the database and uses their mnemonics and operand patterns to emit valid assembly test cases.
Impact
Writing GAS tests is extremely tedious, and the generator significantly reduces the effort required.
Working with a Shared, Evolving, Open-Source Codebase
Across these PRs, some of the most valuable lessons were about working within a collaborative infrastructure project.
Navigating New Code and Languages
The repository spans Ruby, Python, C, C++, and more. I spent a lot of time reading existing generators, studying QEMU and binutils source code, and understanding exactly what downstream tools expected from the database.
Commit Messages and PR Discipline
Reviewers emphasized clear, narrative commit messages that explained the previous state, the problem, and the solution. This discipline forced me to reason carefully about design choices and made reviews and later refactors much easier.
Feedback Loops
Opening draft PRs helped turn early submissions into conversations rather than final declarations. That experience taught me to value feedback early, stay flexible on design, and prioritize long-term maintainability over short-term progress.
How This Work Shaped My Understanding of RISC-V
Contributing to UDB changed how I think about ISAs and toolchains:
- A unified database avoids duplication by letting one canonical representation feed many generators.
- It deepened my understanding of extension interactions, profiles like RV32E, and the subtle differences in expectations between downstream projects.
Looking Ahead
The work I have done so far, modeling GPRs, generating QEMU decode rules and opcode tables, and drafting a GAS test generator, feels like just the beginning.
Natural next steps include extending the register model to floating-point and vector registers, improving binutils test generation, and tightening integration between UDB and QEMU.
Contributing to the RISC-V Unified Database through the RISC-V Mentorship Program has been a formative experience for me as an engineer. I leave this mentorship with a much deeper understanding of RISC-V, greater confidence contributing to large infrastructure codebases, and strong motivation to continue contributing to open-source projects that prioritize correctness, reuse, and community-driven development.
Join the RISC-V Mentorship Program
Explore the current paid mentorship opportunities with RISC-V member organizations and join the Linux Foundation’s RISC-V Mentorship Program.
