CORE: Corpus Of RTL designs for EDA Research

A comprehensive collection of parameterized and configurable RTL modules written in Verilog, organized by category for EDA research and development. This repository contains 137 verified modules across 24 categories with complete testbenches and documentation.

Table of Contents

• Installation
• Quick Start
• Dataset Overview
• Directory Structure
• Dataset Analysis Tools
  • Verification Report
  • Dataset Analysis
  • Verilog Standards Analysis
• Contributing
• Technical Information
• Citation
• License

Installation

Prerequisites

• Python 3.6 or higher
• Icarus Verilog (iverilog) 12.0 or higher
• GTKWave (for waveform viewing)
• Make
• Verilator 5.0 or higher

Installation Steps

1. Clone the repository:

git clone https://github.com/SJTU-YONGFU-RESEARCH-GRP/core.git
cd core

2. Install Verilator (if not already installed):

Using package manager:

# For Ubuntu/Debian
sudo apt-get install verilator

# For CentOS/RHEL
sudo yum install verilator

# For macOS
brew install verilator

# For Windows (using WSL)
sudo apt-get install verilator

Or install from GitHub source (recommended for latest version):

# Install build dependencies
# For Ubuntu/Debian
sudo apt-get install git make autoconf g++ flex bison

# For CentOS/RHEL
sudo yum install git make autoconf gcc-c++ flex bison

# For macOS
brew install git make autoconf flex bison

# Clone and build Verilator
git clone https://github.com/verilator/verilator.git
cd verilator
git checkout stable  # or 'git checkout master' for latest development version
autoconf
./configure
make
sudo make install

3. Install Yosys (if not already installed):

Using package manager:

# For Ubuntu/Debian
sudo apt-get install yosys

# For CentOS/RHEL
yum install epel-release
yum install yosys

# For macOS
brew install yosys

# For Windows (using WSL)
sudo apt-get install yosys

Or install from GitHub source (recommended for latest version):

# Install build dependencies
# For Ubuntu/Debian
sudo apt-get install git build-essential clang bison flex libreadline-dev gawk tcl-dev libffi-dev graphviz xdot pkg-config python3 python3-pip libboost-system-dev libboost-python-dev libboost-filesystem-dev zlib1g-dev

# For CentOS/RHEL
yum install git gcc clang bison flex readline-devel gawk tcl-devel libffi-devel graphviz xdot pkgconfig python3 python3-pip boost-devel zlib-devel

# For macOS
brew install git clang bison flex readline gawk tcl-tk libffi graphviz xdot pkg-config python3 boost zlib

# Clone and build Yosys
git clone https://github.com/YosysHQ/yosys.git
cd yosys
make
sudo make install

4. Install Python dependencies:

pip install -r requirements.txt

The Python dependencies include:

• typing-extensions>=0.4.6 - For enhanced type hints support
• colorama>=0.4.6 - For colored terminal output
• tqdm>=4.65.0 - For progress bars
• rich>=13.0.0 - For rich terminal formatting and logging
• matplotlib - For generating plots and visualizations
• seaborn - For statistical data visualization

Quick Start

After installation, you can immediately start using the modules:

1. Browse the dataset: Explore modules in the libraries/ directory
2. Run verification: Run make verify_all, then python3 scripts/report.py to generate a verification report
3. Analyze the dataset: Use python3 scripts/analyze_verilog_dataset.py for detailed analysis
4. View documentation: Check category-specific docs in the docs/ directory

Reproducible Environment

To ensure consistent results across machines and CI:

• Python dependencies are pinned in requirements.txt.
• CI runs inside a pinned OSS CAD Suite container image.

Local (with Docker/Podman):

docker run --rm -v "$PWD":/workspace -w /workspace ghcr.io/yosyshq/oss-cad-suite:2024-06-01 \
  bash -lc "python -m pip install --upgrade pip && pip install -r requirements.txt && make verify_all && python3 scripts/report.py && python3 scripts/analyze_verilog_dataset.py --synth --output DATASET.md --loglevel INFO && python3 scripts/verilog_standard_report.py --output VERILOG_STANDARDS.md --loglevel INFO"

Make targets:

• make verify_all – build and run all testbenches
• make report – generate REPORT.md
• make analyze – generate DATASET.md
• make standards – generate VERILOG_STANDARDS.md

Dataset Overview

Category	Docs	Number	Modules
Adders	Adders	6	configurable_brent_kung_adder, configurable_carry_lookahead_adder, configurable_carry_select_adder, configurable_carry_skip_adder, configurable_conditional_sum_adder, configurable_kogge_stone_adder
Arbitration	Arbitration	4	arbiter, arbiter_rr, fair_priority_arbiter, matrix_arbiter
Arithmetic	Arithmetic	2	alu, configurable_comparator
CORDIC	CORDIC	3	cordic, cordic_core, sine_cosine_generator
Clock Domain Crossing	Clock Domain Crossing	4	clock_domain_crossing, clock_domain_crossing_fifo, handshake_synchronizer, multi_flop_synchronizer
Communication	Communication	12	ahb_lite_master, basic_spi_master, fixed_spi_master, final_spi_master, parameterized_deserializer, parameterized_i2c_master, parameterized_serdes, parameterized_spi_master, parameterized_uart_rx, parameterized_uart_tx, simple_spi_master, spi_master
Counters	Counters	15	configurable_clz_clo, gray_counter, johnson_counter, leading_zero_counter, loadable_updown_counter, parameterized_decade_counter, parameterized_gray_counter, parameterized_johnson_counter, parameterized_johnson_updown_counter, parameterized_loadable_counter, parameterized_onehot_counter, parameterized_ring_counter, parameterized_self_correcting_counter, parameterized_sync_reset_counter, parameterized_updown_counter
Debugging	Debugging	2	logic_analyzer, performance_counter
Encoding/Decoding	Encoding/Decoding	7	binary_to_gray, configurable_priority_encoder, gray_to_binary, hamming_code, parameterized_crc_generator, parameterized_scrambler, priority_encoder
Encryption	Encryption	2	aes_core, true_random_generator
FIFOs	FIFOs	20	async_fifo, barrel_shifter_fifo, bidirectional_fifo, cache_fifo, circular_buffer_fifo, configurable_param_fifo, configurable_sync_fifo, credit_based_fifo, dual_clock_fifo, elastic_buffer, fifo, fwft_fifo, memory_mapped_fifo, multi_ported_fifo, parameterized_priority_queue, pipelined_fifo, showahead_fifo, skid_buffer, smart_fifo, sync_fifo
Filters	Filters	2	configurable_fir_filter, fir_filter
Input/Output	Input/Output	2	dma_controller, gpio_controller
Interfaces	Interfaces	4	axi_lite_master, axi_stream_interface, pcie_endpoint, wishbone_master
Mathematics	Mathematics	3	fixed_point_sqrt, floating_point_adder, non_restoring_divider
Memory	Memory	4	ddr_controller, dual_port_ram, memory_controller, parameterized_cam
Multiplication	Multiplication	3	booth_multiplier, configurable_mult, radix4_booth_multiplier
Network on Chip	Network on Chip	5	configurable_mesh_router, crossbar_switch, mesh_router, network_interface, network_interface_cdc
Power Management	Power Management	5	clock_divider, clock_gating, parameterized_clock_gating, parameterized_freq_divider, power_domain_controller
Registers	Registers	19	barrel_rotator, barrel_shifter, bidirectional_shift_register, dual_edge_register, lfsr, onehot_decoder_register, parameterized_barrel_rotator, parameterized_rotation_sipo, piso_register, register_file, scan_register, shadow_register, sipo_register, siso_register, sync_preset_register, toggle_register, universal_shift_register, shift_register_left, shift_register_right
Signal Processing	Signal Processing	9	configurable_lfsr, configurable_prng, digital_thermometer_controller, multi_phase_pwm_controller, parameterized_dds, parameterized_fft, parameterized_pwm, pulse_width_detector, pwm_generator
State Machines	State Machines	1	sequence_detector_fsm
Testing	Testing	2	bist_controller, jtag_controller
Voting	Voting	1	majority_voter

Directory Structure

/ libraries         # Verilog RTL modules
/ docs              # Category documentation
report.py           # Verification report generator
REPORT.md           # Latest verification report
LICENSE             # Licensing information
README.md           # This file

Dataset Analysis Tools

Verification Report

Generate a comprehensive report of the verification results:

make verify_all
python3 scripts/report.py

This script scans RTL files and their testbenches, executes tests using make, and produces REPORT.md.

📊 View the latest report: REPORT.md

Dataset Analysis

Analyze the Verilog dataset and generate a comprehensive report with synthesis metrics:

python3 scripts/analyze_verilog_dataset.py --synth --output my_report.md --loglevel INFO

What it does:

• Analyzes all Verilog files in libraries/ for code metrics (lines, parameters, ports, patterns, etc.)
• Optionally runs Yosys synthesis to collect hardware metrics (cell count, wire count, etc.)
• Generates plots and a markdown report summarizing the dataset's structure, complexity, and synthesis statistics

📊 View the latest analysis: DATASET.md

Verilog Standards Analysis

Generate a detailed standards compliance report:

python3 scripts/verilog_standard_report.py --output VERILOG_STANDARDS.md --loglevel INFO

Analysis includes:

• Standards compliance (Verilog-1995 through SystemVerilog-2017)
• Feature usage statistics
• File-by-file analysis
• Visual charts showing standards distribution

📊 View the standards report: VERILOG_STANDARDS.md

Contributing

We welcome and encourage community contributions to expand the CORE dataset! Your contributions help make this repository a more comprehensive resource for EDA research and development.

How to Contribute

1. Reporting Issues

• Found a bug or issue? Create an issue on GitHub
• Include detailed information about the problem and steps to reproduce it
• Suggest improvements or request new module categories

2. Contributing New Modules

We're always looking for new high-quality Verilog RTL modules to add to the dataset. Here's how you can contribute:

What we're looking for:

• Well-documented, parameterized Verilog modules
• Comprehensive testbenches (preferably in C++ using Verilator)
• Modules that follow good RTL design practices
• Coverage of new design patterns or categories not currently in the dataset

Contribution Process:

1. Fork the repository and create a new branch for your contribution
2. Add your Verilog module(s) to the appropriate category in libraries/
3. Include comprehensive testbenches following our naming convention (tb_*.cpp)
4. Add documentation explaining the module's functionality and parameters
5. Test your modules using our verification flow (make command)
6. Submit a pull request with a clear description of your contribution

File Organization:

• Place Verilog files in the appropriate libraries/[category]/ directory
• Include testbench files with tb_ prefix
• Add documentation to the corresponding docs/README_[CATEGORY].md file
• Follow existing naming conventions and coding styles

3. Improving Existing Modules

• Fix bugs in existing modules
• Improve testbench coverage
• Optimize implementations
• Add better documentation or comments

4. Documentation and Tools

• Improve documentation clarity
• Enhance analysis scripts
• Add new visualization features
• Fix typos or formatting issues

Contribution Guidelines

• Code Quality: Ensure your code is clean, well-commented, and follows Verilog best practices
• Testing: All modules must include working testbenches that demonstrate functionality
• Documentation: Provide clear documentation explaining module purpose, parameters, and usage
• Licensing: By contributing, you agree that your contributions will be licensed under the same CC BY-NC 4.0 license

Getting Started

1. Explore the existing codebase to understand our structure and conventions
2. Check open issues to see if there are specific modules or features we need
3. Start small - consider fixing bugs or improving documentation before adding large new features
4. Ask questions - create an issue if you need clarification on contribution guidelines

Join our community and help make CORE the most comprehensive RTL dataset for EDA research!

For questions about contributions, please create an issue or reach out to the maintainers.

Technical Information

• Current Version: 1.0.0
• Last Updated: 2024
• Supported Verilog Standards: IEEE 1364-2005, IEEE 1800-2012
• Tool Versions:
  • Verilator: 5.036
  • Yosys: 0.53+81
  • Icarus Verilog: 11.0
  • Python: 3.10.12

Citation

If you use this repository in your research or work, please cite it as follows:

@misc{core2024,
  author = {Kian Kit Cheah, Fu Qi Chua, Yunxiang Zhang, Zhuofan Lin, Yuxin Ji, Xinfei Guo, Harikrishnan Ramiah, and Yongfu Li},
  title = {Descriptor: A Corpus of Synthesizable Verilog RTL Modules Dataset for EDA Research (CORE)},
  year = {2025},
  journal = {IEEE Data Descriptions},
  url = {\url{https://github.com/SJTU-YONGFU-RESEARCH-GRP/core}},
}

License

This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International Public License.