rggen

RgGen

RgGen is a code generation tool for ASIC/IP/FPGA/RTL engineers. It will automatically generate source code related to control and status registers (CSR), e.g. SytemVerilog RTL, UVM register model (UVM RAL/uvm_reg), C header file, Wiki documents, from human readable register map specifications.

RgGen has following features:

• Generate source files related to CSR from register map specifications
  • RTL module
    • SystemVerilog
    • Verilog
      • Need rggen-verilog plugin
    • Veryl
      • Need rggen-veryl plugin
    • VHDL
      • Need rggen-vhdl plugin
    • Supports standard bus protocols
      • AMBA APB
      • AMBA AXI4-Lite
      • Avalon-MM
      • Wishbone
  • UVM register model (UVM RAL/uvm_reg)
  • C header file
  • Register map documents written in Markdown
• Register map specifications can be written in human readable format
  • Ruby with APIs to describe register map information
  • YAML
  • JSON
  • TOML
  • Spreadsheet (XLSX, ODS, CSV)
  • SystemRDL
    • Need rggen-systemrdl plugin
• Plugin feature
  • Allow you to customize RgGen for your environment
    • Add your own special bit field types
    • Add your own host bus protocol
• Browser-based Web UI is available at https://rggen.github.io/rggen-webui/

Installation

Ruby

RgGen is written in the Ruby programing language and its required version is 3.2 or later. You need to install any of these versions of Ruby before installing RgGen tool. To install Ruby, see this page.

Installation Command

RgGen depends on following sub components and other Ruby libraries.

• rggen-core
• rggen-default-register-map
• rggen-systemverilog
• rggen-c-header
• rggen-markdown
• rggen-spreadsheet-loader

To install RgGen and the dependencies, use the command below:

$ gem install rggen

RgGen and dependencies will be installed on your system root.

If you want to install them on other location, you need to specify install path and set GEM_PATH and PATH environment variables:

$ gem install --install-dir /path/to/your/install/directory rggen
$ export GEM_PATH=/path/to/your/install/directory
$ export PATH=$GEM_PATH/bin:$PATH

You would get the following error message duaring installation if you have the old RgGen (version < 0.9).

ERROR:  Error installing rggen:
        "rggen" from rggen-core conflicts with installed executable from rggen

To resolve the above error, there are three solutions. See this page

Docker Image

The rggen-docker is a Docker image to simplify installation and use of RgGen. You can also execute RgGen by using this image:

$ docker run -ti --rm -v ${PWD}:/work --user $(id -u):$(id -g) rggendev/rggen-docker:latest -c config.yml -o out block_0.yml

See the rggen-docker repository for further details.

Homebrew Installation

On macOS or Linux, if Homebrew is installed, you can install RgGen with this command:

brew install rggen

This will automatically install Ruby if needed, and will provide RgGen itself as well as the VHDL, Verilog, and Veryl plugins.

Web UI

A browser-based interface is available at https://rggen.github.io/rggen-webui/. No installation required — RgGen runs entirely in the browser.

• Define register blocks, registers, and bit fields in an interactive table UI
• Generate RTL (SystemVerilog, Verilog, Veryl, VHDL), UVM RAL (uvm_reg), C header, and Markdown documents
• Download all outputs as a ZIP archive
• Export and import register map definitions as YAML files

Usage

See Wiki documents.

Plugin

RgGen has plugin feature to allow your cusomization. See this Wiki document for futher detals.

Supported Tools

Following EDA tools can accept the generated source files.

• Simulation tools
  • Synopsys VCS
  • Cadence Xcelium
  • Altair DSim
  • AMD Vivado Simulator
  • Verilator
    • Need -Wno-unoptflat switch for Verilog RTL
  • Icarus Verilog
    • Verilog RTL only
• Synthesis tools
  • Synopsys Design Compiler
  • Altera Quartus
  • AMD Vivado
  • Yosys
    • Verilog RTL

Example

You can get sample configuration file and register map specification from the rggen-sample repository. This register map specification is for a UART IP.

• Configuration file
  • https://github.com/rggen/rggen-sample/blob/master/config.yml
• Register map specification
  • https://github.com/rggen/rggen-sample/blob/master/uart_csr.yml

You can try to use RgGen by uisng these example files. Hit command below:

$ rggen -c config.yml -o out uart_csr.yml

• -c: Specify path to your configuration file
• -o: Specify path to the directory where generated files will be written to

Then, generated files will be written to the out directory.

If you want to generate Verilog RTL, Veryl RTL and VHDL RTL then you need to instll optional plugins listed below.

• Verilog writer plugin: rggen-verilog
• Veryl writer plugin: rggen-veryl
• VHDL writer plugin: rggen-vhdl

$ gem install rggen-verilog
$ gem install rggen-veryl
$ gem install rggen-vhdl

In addition, you need to tell RgGen to use these plugins by using the --plugin option switch:

$ rggen -c config.yml --plugin rggen-verilog --plugin rggen-veryl --plugin rggen-vhdl uart_csr.yml

RgGen will generate following source files from the uart_csr.yml register map specification:

• SystemVerilog RTL
  • https://github.com/rggen/rggen-sample/blob/master/uart_csr.sv
  • https://github.com/rggen/rggen-sample/blob/master/uart_csr_rtl_pkg.sv
• Verilog RTL
  • https://github.com/rggen/rggen-sample/blob/master/uart_csr.v
  • https://github.com/rggen/rggen-sample/blob/master/uart_csr.vh
• Veryl RTL
  • https://github.com/rggen/rggen-sample/blob/master/uart_csr.veryl
• VHDL RTL
  • https://github.com/rggen/rggen-sample/blob/master/uart_csr.vhd
• UVM register model
  • https://github.com/rggen/rggen-sample/blob/master/uart_csr_ral_pkg.sv
• C header file
  • https://github.com/rggen/rggen-sample/blob/master/uart_csr.h
• Markdown document
  • https://github.com/rggen/rggen-sample/blob/master/uart_csr.md

Contributing

See Contributing Guide.

Publications

• Taichi Ishitani. RgGen: An Open-Source CSR Automation Tool. September 2026. In Design & Verification Conference & Exhibition (DVCon) Japan 2026.
  • Paper
  • Slide

Contact

Feedbacks, bug reports, questions and etc. are wellcome! You can post them by using following ways:

• GitHub Issue Tracker
• GitHub Discussions
• Discord
• Mailing List
• Mail

See Also

• https://github.com/rggen/rggen-core
• https://github.com/rggen/rggen-default-register-map
• https://github.com/rggen/rggen-systemverilog
• https://github.com/rggen/rggen-c-header
• https://github.com/rggen/rggen-markdown
• https://github.com/rggen/rggen-spreadsheet-loader
• https://github.com/rggen/rggen-systemrdl
• https://github.com/rggen/rggen-verilog
• https://github.com/rggen/rggen-veryl
• https://github.com/rggen/rggen-vhdl
• https://github.com/rggen/rggen-docker
• https://github.com/rggen/rggen-webui

Copyright & License

Copyright © 2019-2026 Taichi Ishitani. RgGen is licensed under the MIT License, see LICENSE for futher detils.

Code of Conduct

Everyone interacting in the RgGen project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.