SystemRDL Toolkit

A comprehensive SystemRDL 2.0 toolkit based on ANTLR4 that provides parsing, elaboration, and conversion capabilitiesfor SystemRDL register description files.

Features

• SystemRDL 2.0 Support: Implementation of SystemRDL 2.0 specification
• AST & Elaboration: Parse and elaborate SystemRDL designs with semantic analysis
• AST Export: Export AST and elaborated models to JSON format
• CSV Conversion: Convert CSV specifications to SystemRDL format
• Template Rendering: Documentation generation using Jinja2 templates
• Validation Testing: Integration with Python SystemRDL compiler
• C++ API: Library interface without ANTLR4 header dependencies
• Build Flexibility: Support for multiple ANTLR4 versions

Tools Included

Tool	Description
systemrdl_parser	Parse SystemRDL files and generate Abstract Syntax Trees
systemrdl_elaborator	Elaborate parsed designs with semantic analysis
systemrdl_csv2rdl	Convert CSV register specifications to SystemRDL
systemrdl_render	Generate documentation using Jinja2 templates

Quick Start

Prerequisites

Ubuntu/Debian:

sudo apt-get install cmake build-essential pkg-config python3 python3-venv

Gentoo:

sudo emerge cmake dev-util/cmake python:3.13

Build

# Clone and build
git clone <repository-url>
cd systemrdl-toolkit
mkdir build && cd build
cmake ..
make -j$(nproc)

# Run tests
make test-fast

Example Usage

# Parse SystemRDL file
./systemrdl_parser design.rdl --json

# Elaborate design
./systemrdl_elaborator design.rdl --json

# Convert CSV to SystemRDL
./systemrdl_csv2rdl registers.csv -o design.rdl

# Generate documentation
./systemrdl_render design.rdl -t template.j2 -o output.html

Documentation

Document	Description
BUILD.md	Detailed build instructions and dependencies
TOOLS.md	Command-line tools usage guide
API.md	C++ library API reference and examples
TESTING.md	Testing framework and validation procedures
DEVELOPMENT.md	Development setup and contribution guide
TROUBLESHOOTING.md	Common issues and solutions
ARCHITECTURE.md	Project structure and components

Library Usage

The toolkit provides a modern C++ library for integrating SystemRDL functionality:

#include "systemrdl_api.h"

// Parse SystemRDL content
auto result = systemrdl::parse_string(rdl_content);
if (result.success) {
    std::cout << "AST JSON: " << result.json_output << std::endl;
}

// Elaborate design
auto elab_result = systemrdl::elaborate_string(rdl_content);
if (elab_result.success) {
    std::cout << "Elaborated JSON: " << elab_result.json_output << std::endl;
}

See API.md for complete library documentation.

Testing

The project includes comprehensive validation using both C++ and Python SystemRDL tools:

# Run all tests
make test

# Quick validation tests
make test-fast

# Specific test categories
make test-parser test-elaborator test-csv2rdl

Installation

# Install to system
sudo make install

# Use in your project
find_package(SystemRDL REQUIRED)
target_link_libraries(your_target SystemRDL::systemrdl)

Configuration

ANTLR4 Version Control

# Use specific version
cmake .. -DANTLR4_VERSION=4.12.0

# Use system ANTLR4
cmake .. -DUSE_SYSTEM_ANTLR4=ON

# Environment variable
export ANTLR4_VERSION=4.11.1

Build Options

# Build components
cmake .. -DSYSTEMRDL_BUILD_TOOLS=ON -DSYSTEMRDL_BUILD_TESTS=ON

# Library types
cmake .. -DSYSTEMRDL_BUILD_SHARED=ON -DSYSTEMRDL_BUILD_STATIC=ON

Version Information

• Version: 0.1.0
• SystemRDL Standard: 2.0
• C++ Standard: C++17
• ANTLR4 Version: 4.13.2 (default)

All tools support --version flag for detailed version information including Git commit and build status.

Acknowledgments

The SystemRDL grammar file (SystemRDL.g4) is derived from the SystemRDL Compiler project. We express our sincere gratitude to the SystemRDL organization and contributors for providing the comprehensiveSystemRDL 2.0 specification and grammar implementation.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Issues & Support

• Documentation: Check the doc/ directory for detailed guides
• Bug Reports: Use the issue tracker
• Questions: See TROUBLESHOOTING.md for common issues
• Contributing: Read DEVELOPMENT.md for contribution guidelines