<img alt="OpenVADL" src="https://github.com/OpenVADL/openvadl/raw/v0.2.0/assets/logo/SVG/logo-dark.svg" width="320">

<a href="https://openvadl.github.io/openvadl/"><strong>Explore the docs »</strong></a>

OpenVADL is an open-source implementation of VADL, a processor description language. VADL enables users to specify both instruction set architectures (ISA) and microarchitectures in a modern, intuitive way. For details, see the official documentation.

OpenVADL can generate multiple artifacts from a single VADL specification:

• Instruction Set Simulator via a custom QEMU frontend
• Compiler via a custom LLVM backend
• Linker and Assembler by integrating a generated parser into LLVM

Additional tools, such as a Chisel generator for hardware synthesis, are in development.

Check out our VADL-related publications for more background.

Getting Started

If you want to use OpenVADL, please refer to the documentation. It covers everything you need to install OpenVADL, write a specification, and use the CLI to generate artifacts like a simulator or compiler.

For working VADL specifications examples, check out our reference specifications.
These are tested and kept up to date with the current OpenVADL version.

Contribution

If OpenVADL sounds like an interesting project and you'd like to collaborate or contribute, please reach out!

There are plenty of open tasks, including:

• A cycle-approximate simulator generator
• User-mode emulation in the generated ISS
• A documentation engine for embedding architecture specs directly in VADL
• Improvements to the QEMU-based ISS
• Enhancements to the LLVM-based compiler

There are also many potential Bachelor and Master thesis topics available.

Q&A and Bugs

If you have any questions, please use our discussion panel.
This helps others with similar issues find answers more easily.

If you encounter a crash or incorrect behavior, please report it as an issue.
Before creating a new issue, check if one already exists for the same problem.

Development

Before contributing, please read OpenVADL's contribution guidelines.

Project Structure

The open-vadl project includes multiple Gradle modules.

• vadl is the main module that contains all the logic of OpenVADL
• vadl-cli implements the CLI for OpenVADL users. It uses the vadl module as a library
• java-annotations provides Java (!) annotations (e.g. @Input) that are used in the VIAM. Additionally it provides errorprone bug detectors, that statically check if certain properties in the VIAM are correctly implemented.

Getting Started

You need a working JDK 21 (or higher) installation on your PATH to build OpenVADL. To directly build and run OpenVADL without installing it, use the ./gradlew run --args="<args>" command.

For example, you can create the ISS (Instruction Set Simulator) for a minimal risc-v example with:

./gradlew run --args="iss sys/risc-v/rv64im.vadl"

To get a description of the complete usage, you can run: ./gradlew run --args="--help"

Building

You can build and run in two steps with

./gradlew installDist

Which will create an executable script at: vadl-cli/build/install/openvadl/bin/openvadl.

To build a GraalVM Native Image you first need to set $JAVA_HOME or $GRAALVM_HOME to point to your GraalVM installation. With that you can run:

./gradlew nativeCompile

Which will create an executable at: vadl-cli/build/native/nativeCompile/openvadl

Run all tests

To run all tests you need to have docker running on your system.

./gradlew test

Note: The tests are quite resource intensive (especially on memory and disk space) so make sure docker has enough available, otherwise the tests might fail.

Expect the tests to run a long time (up to an hour isn't unrealistic).

Checkstyle

We are using Checkstyle to ensure a consistent format and documentation of the source code.

Install the Checkstyle plugin for your IDE and import our Checkstyle configuration. The configuration is located under config/checkstyle/checkstyle.xml.

To locally test if the checkstyle CI pipeline would fail, run the checkstyleAll gradle task.

Using Intellij

To use the Checkstyle confirm IntelliJ code style follow these steps:

1. Go to Settings > Editor > Code Style > Java
2. For the Scheme select Project

If you still get formatting conflicts between Intellij and Checkstyle follow these steps:

1. Go to Settings > Editor > Code Style > Java
2. Click on the settings icon and select Import Scheme > Checkstyle configuration
3. Choose the Checkstyle config file under config/checkstyle/checkstyle.xml
4. Enable the Java code style setting JavaDocs > Other > Indent continuation lines This prevents a JavaDocs formatting conflict between IntelliJ and Checkstyle.

With this, IntelliJ uses the code style rules as specified in the Checkstyle config. Note that Checkstyle and code style are not 100% compatible, so IntelliJ will eventually generate some invalid formatted code (such as Java docs paragraph separation).