rggen/rggen

Code generation tool for control and status registers

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
    • VHDL
      • Need rggen-vhdl plugin
    • Supports standard bus protocols
      • AMBA APB
      • AMBA AXI4-Lite
      • 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)
  • SiFive DUH
    • Need rggen-duh plugin
• Plugin feature
  • Allow you to customize RgGen for your environment
    • Add your own special bit field types
    • Add your own host bus protocol

Installation

Ruby

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

Installatin 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.

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
  • Metrics DSim
  • Xilinx Vivado Simulator
  • Verilator
    • Need -Wno-unoptflat switch for Verilog RTL
  • Icarus Verilog
    • Verilog RTL only
• Synthesis tools
  • Synopsys Design Compiler
  • Intel Quartus
  • Xilinx 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 and/or VHDL RTL then you need to instll optional plugins listed below.

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

$ gem install rggen-verilog
$ 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-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
• 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.

Contact

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

• GitHub Issue Tracker
• GitHub Discussions
• Chat Room
• 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-duh
• https://github.com/rggen/rggen-verilog
• https://github.com/rggen/rggen-vhdl
• https://github.com/rggen/rggen-docker

Copyright & License

Copyright © 2019-2024 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.

rggen's Issues

Add comment property to register block, register file and register layers

Add comment property to register block, register file and register layers.

Support TOML

Support configuration file and register map written in TOML.
Parser gem:
https://github.com/fbernier/tomlrb

No error is reported even though step is less than width

Describe the bug
No error is reported even though step is less than width.

To Reproduce

- register_block:
  - name: foo
    byte_size: 256
  - register:
    - name: bar
      bit_fields:
      - { name: baz, bit_assignment: { width: 2, sequence_size: 2, step: 1 }, type: rw, initial_value: 0 }

Load this register map.

Expected behavior

step should be equal to or grater than width to avoid overlapping each elements.
Therefore, an error should be reported if step is less than width.

Introduce 'register_file' hierarchy

Support W1SRC/W0SRC/W1CRS/W0CRS bit field types

Add new bit field types listed below:

• W1SRC
  • W: 1/0 sets/no effect on matching bit
  • R: clears all bits
• W0SRC
  • W: 1/0 no effect on/sets matching bit
  • R: clears all bits
• W1CRS
  • W: 1/0 clears/no effect on matching bit
  • R: sets all bits
• W0CRS
  • W: 1/0 no effect on/clears matching bit
  • R: sets all bits

Add W1 and WO1 bit field types

Supported tools

Check whether or not following tools support generated CSR modules/RAL packages.

• Simulation
  • Cadence Xcelium
    • VHDL output
  • Mentor Questa/ModelSim
  • Aldec Riviera-PRO
  • GHDL
• Synthesis
  • Cadence Genus
  • Lattice
  • Microsemi
  • Efinix
  • Yosis

Use eval_gemfile instead of instance_eval

Use eval_gemfile instead of instance_eval to evaluate the gemfile read from other repository.

Update copyright year

Cannot load old plugin if newer version is installed

Cannot load old plugin if its newer version is installed.

$ rggen --plugin /opt/rbenv/versions/3.0.0/lib/ruby/gems/3.0.0/gems/rggen-verilog-0.3.0/lib/rggen/verilog/setup.rb --verbose-version
RgGen 0.25
  - rggen-core 0.25.0
  - rggen-default-register-map 0.25.1
  - rggen-sv-rtl 0.25.1
  - rggen-sv-ral 0.25.1
  - rggen-markdown 0.21.0
  - rggen-spreadsheet-loader 0.20.0
  - rggen-verilog 0.3.1

The setup file for rggen-verilog v0.3.0 is specified but rggen-verilog v0.3.1 is loaded.

Add WRC/WRS/WC/WS/WSRC/WCRS/WOC/WOS bit field typs

Add WRC/WRS/WSRC/WCRS/WOC/WOS bit field typs.

• WRC
  • W: as-is
  • R: clears all bits
• WRS
  • W: as-is
  • R: sets all bits
• WC
  • W: clears all bits
  • R: no effect
• WS
  • W: sets all bits
  • R: no effect
• WSRC
  • W: sets all bits
  • R: clears all bits
• WCRS
  • W: clears all bits
  • R: sets all bits
• WOC
  • W: clears all bits
  • R: error
• WOS
  • W: sets all bits
  • R: error

Enhancement of initial value attribute

It is convenience that initial values are able to be overrode when generated RTL module is instantiated. To support this case, introduce parameterized initial value.

If all of initial values are parameterized, generated parameter port list is very busy.
Therefore, initial values of certain bit fields should only be parameterized and new notation will be introduced.
If initial value is notated as hash default: 0 then this initial value is parameterized.

In addition, introduce arrayed initial value attribute for sequential bit field.

Introduce GitHub Actions

Introduce GitHub Actions instead of Travis CI.

• https://github.com/actions/setup-ruby
• https://github.com/actions/cache/blob/master/examples.md#ruby---bundler
• https://github.com/codecov/codecov-action
• https://github.com/SonarSource/sonarcloud-github-action

type of registers supported

Hi taichi-ishitani,
I have come across your rggen for generating registers, Can you please tell me the type of registers it supports. Is it mentioned in any of your docs ? Please let me know. If it's not mentioned tell me here and I will add that in your docs.

Thank You,

Hung-up when NameError is raised from Feature object

Hung-up when NameError is raised from Feature object.
It is because that:

• When NameError#to_s is being called #inspect is also called on NameError#receiver.
  • In this case NameError#receiver returns a Feature object.
• Feature#inspect is not implemented so the default behavior is invoked.
  • #inspect is called on all of its instance variables.
• An infinite loop occurs because of the following circular reference.
  • Feature#component -> Component#features -> self -> ...

To avoid above problem, Feature#inspect needs to be implemented.

Enhance input file loader

Enhance input file loader to introduce following feature.

• Introduce ignore_values list
  • ignore_values is a list of values which loader cannot be handle. Values within this list will be removed from valid_value_list.
  • This feature is needed to add comment property to register block/register file/register layer because because spreadsheet based register map cannot contain comment property.
• Introduce value converter
  • value convert will convert input data into values within valid_value_list.
  • This is for loader converting other register map format such as SystemRDL

Change notation of bit assignment

Change notation of bit assignment to swap position of LSB and width.
This is to support bit assignment without LSB position on XLSX register map.

For backward compatibility, add a new configuration parameter to specify what is the first element of notation of bit assignment.

Ruby 3.0 support

Check RgGen can be used with Ruby 3.0

Test ticket from Code Climate

Introduce common Gemfile

Introduce common Gemfile.

Drop Ruby 2.4 support

Ruby 2.4 has already been EOL.
Update of Ruby 2.5 is listed below.
https://qiita.com/jnchito/items/f182b6f0093a6a3701a1
https://qiita.com/jnchito/items/0d2d17a79a3e82fe3815

Enhance YAML/JSON based register map

Currently, one layer is described by using one Hash and an Array at the special key is used to describe a set of sub layers.

register_maps:
  - name: foo_0
    registers:
    - name: bar_0
    - name: baz_0
    register_files:
    - name: bar_1
    - name: baz_1

This notation has a problem; Describing sub-layers in order bar_0 -> bar_1 -> baz_0 -> baz_1 like below

register_maps:
  - name: foo_0
    registers:
    - name: bar_0
    register_files:
    - name: bar_1
    registers:
    - name: baz_0
    register_files:
    - name: baz_1

does not work well because bar_0 and bar_1 are overridden by baz_0 and baz_1.

To resolve this problem, new notation using an Array of Hash will be introduce like below.

- register_block:
  - name: foo_0
  - register:
    - name: bar_0
  - register_file:
    - name: bar_1
  - register:
    - name: baz_0
  - register_file:
    - name: baz_1

An Array will be merged into one Hash except for values having special keys register_block/register_file/register/bit_field.
These values will be pushed into an Array at special keys register_blocks/register_files/registers/bit_fields.

After loading the new notation, following Hash object will be getten.

{
  register_blocks: [
    {
      name: foo_0,
      registers: [
        { name: bar_0 },
        { name: baz_0 }
      ],
      register_files: [
        { name: bar_1 },
        { name: baz_1 }
      ]
    }
  ]
}

Add internal register type

Add internal register type to support nested register block.
This type is to specify a register block which is put within other register block.

Outline of register map format:

register_blocks:
  - name: inner_block_0
    byte_size: 128
    # regsiter descriptions

  - name: inner_block_1
    byte_size: 128
    # regsiter descriptions

  - name: top_block
    byte_size: 256
    regsiters:
      - { name inner_block_0, type: [internal, inner_block_0] }
      - { name inner_block_1, type: [internal, inner_block_1] }

Reason why nested register block support is added as a new register type:

• similar to external register type
• no change to precondition of register map structure

Not support ID for AXI4-Lite

ID for AXI4-Lite is an optional field.
Generated CSR modules with AXI4-Lite should accept and return ID.

SystemRDL support

Implement SystemRDL parser.

sonarcloud does not support SimpleCov 0.18.0 or later

https://community.sonarsource.com/t/simplecov-resultset-json-format-changed-with-0-18-0/19488

Use SimpleCov 0.17 as workaround for this issue.

Bluespec support

Implement generator for bluespec.

Integrate bit field modules

Currently, there are bit field modules for each bit field types.
Integrate these bit field modules into one bit field module.

Could you give me some ideas about rggen scripts？

Hi @taichi-ishitani
It‘s amazing to see your scripts, but i am not familiar with RUBY, if i rewrite this scripts to python,
could you give me some ideas about how do you write rggen and your thinking?

Remove updating $LOAD_PATH from gemspec

Remove updating $LOAD_PATH from gemspec.
Use File.extend_path instead.

Drop Ruby 2.3

Ruby 2.3 has already been EOL.
Update of Ruby 2.4 is listed below.
https://qiita.com/jnchito/items/9f9d45581816f121af07

Add 'reserved' register type

Add reserved register type.

• Reserve an address space for feature use
• The address space cannot be shared with other registers
• No code except for documents will be generated

To implement reserved register type, following changes are also needed:

• Add #document_only? property for the InputBase::Component
• Add two ComponentFactory for code generation
  • One is for source file generation
  • Another one is for document generation
• Add #document to set of APIs to define register type

remove unnecessary 0/1 from index calcuration

Invalid version spec

Current version specifications for sub rggen libraries cannot fix their minor version.
To solve this problem, add .0 to the version specifications like below.

spec.gem 'rggen-core', '~> 0.18.0'

Improve error message for value gotten from YAML files

Currently, input values get from YAML file have no location info.
For usability, get location info from YAML file and set them to input values.

Introduce PluginSpec object

Introduce PluginSpec object. It contains following plugin information.

• name
• version
• file which will be load
• component and feature classes will be registered

In addition, following changes will be made.

• introducing Plugin module to provide a method to create PluginSpec object
• rename RgGen.setup with RgGen.register_plugin

Remove 'BracesAroundHashParameters' from .rubocop.yml

Due to rubocop/rubocop#7641, lint check by rubocop is field.

Error: The `Style/BracesAroundHashParameters` cop has been removed.
(obsolete configuration found in .rubocop.yml, please update it)

Therefore 'BracesAroundHashParameters' should be removed from .rubocop.yml.
In addition Gemfile needs to be updated so that rubocop >= 0.80 is used.

Replace 'codecov' gem with 'codecov-action'

Introduce bump gem

Introduce bump gem to bump version.

Update copyright year

Happy new year 🐮

Omit name of bit field when its parent register has only one bit field

If a register has one bit field only, name of the bit filed should be able to be omitted.
In this case, use name of its parent register as its name.
That is, following register specification can be accepted and name of bit field will be set to foo.

name: foo
offset_address: 0x00
bit_fields:
    - { bit_assignment: { lsb: 0, width: 1}, type: rw, initial_value: 0 }

Add 'rws' bit field type

Add a new bit field type named rws.
Characteristics of this field type are listed below.

• Almost same with rw bit field type
• External value can be set to value of the bit field

How to compile generated systemverilog?

Hello, I have a question about synthesis/compiling.
I tried to compile the sample systemverilog file block_0.sv by using VCS. And it suggested me I also need rggen_rtl_pkg. Then I downloaded the whole rggen-sv-rtl-master, and tried to compile block_0.sv with compile.f.

But then the problems come out:
**Top Level Modules:
rggen_bit_field_rc
rggen_bit_field_reserved
rggen_bit_field_ro
rggen_bit_field_rs
rggen_bit_field_rw_wo
rggen_bit_field_rwc
rggen_bit_field_rwe
rggen_bit_field_rwl
rggen_bit_field_rws
rggen_bit_field_w01c_wc_woc
rggen_bit_field_w01crs_wcrs
rggen_bit_field_w01s_ws_wos
rggen_bit_field_w01t
rggen_bit_field_w01src_wsrc
rggen_bit_field_w01trg
rggen_bit_field_wrc
rggen_bit_field_wrs
rggen_default_register
rggen_external_register
rggen_indirect_register
rggen_apb_adapter
rggen_apb_bridge
rggen_axi4lite_adapter
rggen_axi4lite_bridge

Error-[SV-UIP] Unconnected interface port
./rggen-sv-rtl-master/rggen_bit_field_rc.sv, 7
"bit_field_if"
The port 'bit_field_if' of top-level module 'rggen_bit_field_rc' whose type
is interface 'rggen_bit_field_if' is left unconnected. It is illegal to
leave the interface ports unconnected.
Please make sure that all the interface ports are connected.

Error-[SV-UIP] Unconnected interface port
./rggen-sv-rtl-master/rggen_bit_field_reserved.sv, 2
"bit_field_if"
The port 'bit_field_if' of top-level module 'rggen_bit_field_reserved' whose
type is interface 'rggen_bit_field_if' is left unconnected. It is illegal to
leave the interface ports unconnected.
Please make sure that all the interface ports are connected.

Error-[SV-UIP] Unconnected interface port
./rggen-sv-rtl-master/rggen_bit_field_ro.sv, 4
"bit_field_if"
The port 'bit_field_if' of top-level module 'rggen_bit_field_ro' whose type
is interface 'rggen_bit_field_if' is left unconnected. It is illegal to
leave the interface ports unconnected.
Please make sure that all the interface ports are connected.

Error-[SV-UIP] Unconnected interface port
./rggen-sv-rtl-master/rggen_bit_field_rs.sv, 7
"bit_field_if"
The port 'bit_field_if' of top-level module 'rggen_bit_field_rs' whose type
is interface 'rggen_bit_field_if' is left unconnected. It is illegal to
leave the interface ports unconnected.
Please make sure that all the interface ports are connected.

Error-[SV-UIP] Unconnected interface port
./rggen-sv-rtl-master/rggen_bit_field_rw_wo.sv, 9
"bit_field_if"
The port 'bit_field_if' of top-level module 'rggen_bit_field_rw_wo' whose
type is interface 'rggen_bit_field_if' is left unconnected. It is illegal to
leave the interface ports unconnected.
Please make sure that all the interface ports are connected.

Error-[SV-UIP] Unconnected interface port
./rggen-sv-rtl-master/rggen_bit_field_rwc.sv, 8
"bit_field_if"
The port 'bit_field_if' of top-level module 'rggen_bit_field_rwc' whose type
is interface 'rggen_bit_field_if' is left unconnected. It is illegal to
leave the interface ports unconnected.
Please make sure that all the interface ports are connected.

Error-[SV-UIP] Unconnected interface port
./rggen-sv-rtl-master/rggen_bit_field_rwe.sv, 7
"bit_field_if"
The port 'bit_field_if' of top-level module 'rggen_bit_field_rwe' whose type
is interface 'rggen_bit_field_if' is left unconnected. It is illegal to
leave the interface ports unconnected.
Please make sure that all the interface ports are connected.**

I found that you are using interface and modport to define these "unconnected ports".
Since I am not very familiar with this syntax, I am not sure if it is synthesizable.
And I am also wondering whether my script is correct or not.
Below is my run_vcs script:
source /home/zzeng00/.bashrc
vcs -sverilog -f file.f -R -debug_all -timescale=1ns/10ps +lint=TFIPC-L +lint=PCWM -y /tools/eda/dc2016-L-2016.03-SP1/dw/sim_ver +incdir+/tools/eda/dc2016-L-2016.03-SP1/dw/sim_ver +libext+.v

Could you point out my mistake?
Thank you very much!

Simplify format of version info

Format of version info for verbose version printing is like below.

• fixed string: rggen
• plugin name
• version number

To simplify version info, remove fixed string rggen.

configuration/protocol does not consider other generators than SystemVerilog generator

configuration/protocol does not consider other generators than SystemVerilog generator.

For example:

• SystemVerilog generator implements foo protocol
• Other generator does not implement foo protocol

In the case of above, configuration value foo is passed even though other generator does not support foo protocol.

To fix this issue, shared_context should be shared between same features.

Support Avalon-MM protocol

Add Avalon-MM to supported host interface protocols.
Specification is here.
https://www.intel.com/content/dam/www/programmable/us/en/pdfs/literature/manual/mnl_avalon_spec.pdf

Separate feature implementations

Currently, features for register map and features for generator are managed together.
For re-usability, separate these features and move them to different repositories.

• Features for register map
  • move them to a new repository named rggen-default-register-map
• Features for SV RTL and RAL generators
  • move them to rggen-systemverilog
• Features for Markdown generator
  • move them to rggen-markdown

Issue about csr type and sample XLSX file

Hello!
I want to generate a type of CSR which is Read/Write and self-clean in the next cycle (like a pulse write). RWC type might be the closest one. Could you add this type to your script?
Also, I tried to open the sample XLSX file on your spec page, but it showed the page not found. Could you also fix this issue?
https://github.com/rggen/rggen/wiki/Register-Map-Specifications

Thanks

Documentation on the register map semantics.

Is there any documentation on the register map semantics? The README points to the repository with examples https://github.com/rggen/rggen-sample, but not all things are clear solely on the examples. For instance, what is the exact difference between the register_block and register_file? Is it possible to create nested structure of the register_blocks?

Add W0T/W1T bit field types

Add W0T/W1T bit field types.

• W0T
  • W: 1/0 no effect on/toggles matching bit
  • R: no effect
• W1T
  • 1/0 toggles/no effect on matching bit
  • R: no effect