Skip to main content

Getting Started

note

Before starting this tutorial install JDK 17 and set up IntelliJ IDEA as specified in setup.

Environment Setup

Let us create a Verik project and run the toolchain. The easiest way to get up and running is with the Verik template project. If you are signed in to GitHub select "use this template". This sets up a clean new GitHub repository with the contents of the template. Otherwise, simply clone the repository.

getting-started-github

Open the project in IntelliJ IDEA. A prompt should appear to load the Gradle project. If not, right click on build.gradle.kts and select "Import Gradle Project". If prompted to trust the Gradle project, select "Trust Project". This will set up the IntelliJ IDEA environment. All necessary project dependencies are automatically resolved by the Gradle build system from the Maven Central Repository.

If Gradle is unable to locate an installation of the Java JDK, it will prompt you to configure the Gradle JVM. Open the Gradle Preferences menu and click the drop-down menu for Gradle JVM. Select JDK 17 that we installed in setup.

getting-started-preferences

Open the preferences menu and navigate to File and Code Templates. In the Scheme drop-down menu select "Project". This configures IntelliJ IDEA to use the Verik file template when creating new source files. This is everything you need to get started. For further configuration of IntelliJ IDEA see IntelliJ configuration.

getting-started-template

Project Structure

The directory structure of the template project is shown below. It follows the default directory structure of a Gradle project.

.
├── README.md¹
├── build²
│ ├── compile
│ │ └── ...
│ └── import
│ └── ...
├── build.gradle.kts³
├── gradle
│ └── wrapper
│ ├── gradle-wrapper.jar
│ └── gradle-wrapper.properties
├── gradlew
├── gradlew.bat
├── settings.gradle.kts
└── src⁴
├── main
│ ├── kotlin
│ │ └── Counter.kt
│ └── verilog
│ └── CounterTypes.v
└── test
└── kotlin
└── CounterTest.kt
  1. Project README file
  2. Project build directory
  3. Gradle build script
  4. Project source directory

The output of the Verik toolchain is generated in the project build directory. The Gradle build script configures the toolchain as well as any project dependencies. The project source directory is split into three separate source sets.

  • main/kotlin: Implementation of a simple 8-bit counter
  • main/verilog: Types used by the counter
  • test/kotlin: Testbench for the counter

Use of the test source set is optional. It helps to organize the project by separating the design from the testbench.

Verik Importer

Pull up the Project toolbar and open src/main/verilog/CounterTypes.v. Count is defined as logic [7:0] and will be used as the width of our counter. We will run the importer so that we can use this declaration directly in Verik.

The Verik toolchain is implemented as a plugin to the Gradle build system. The plugin registers three Gradle tasks to each Verik project. verik for the overall toolchain, verikImport for the importer, and verikCompile for the compiler. Information on configuring the toolchain can be found at toolchain configuration. Pull up the Gradle toolbar and double-click on the verikImport Gradle task. If the import is successful, you should see an output similar to what is shown below.

getting-started-import-input

The importer generates the following files in the build directory.

.
└── import
├── imported.sv¹
├── log.txt²
├── report.yaml³
└── src⁴
└── imported
└── CounterTypes.kt

  1. Preprocessor output file
  2. Message log file
  3. Report file
  4. Imported source files

If we take a look at build/import/src/imported/CounterTypes.kt we see that Counter has been translated into a Verik type alias. The original line number and declaration signature is shown in a KDoc comment block above Counter. It can now be referenced from a Verik project.

getting-started-import-output

Verik Compiler

We will now turn our attention to the compiler. Pull up the Project toolbar and open src/main/kotlin/Counter.kt. All the code assistance features of IntelliJ IDEA should have automatically been enabled. Verik is syntactically legal Kotlin and can leverage tools developed for the vibrant Kotlin ecosystem!

getting-started-compile-input

Verik source files are annotated with @file:Verik. This tells the Verik IntelliJ plugin to apply the Verik code inspections. Counter is an 8-bit counter module that asserts strobe when count is zero. In general, HDL semantics is expressed with classes, annotations, and functions from the core library. We will explore the syntax for Verik in more detail in the following tutorials. To run the compiler, pull up the Gradle toolbar and double-click on the verikCompile Gradle task. The compiler generates the following files in the build directory.

.
└── compile
├── log.txt¹
├── out.sv²
├── report.yaml³
└── src⁴
├── Counter.sv
└── CounterTest.sv
  1. Message log file
  2. Output file
  3. Report file
  4. Compiled source files

The output file build/compile/out.sv includes the compiled source files in build/compile/src. The includes are automatically ordered to satisfy SystemVerilog compilation order constraints. If we look at build/compile/src/Counter.sv we see that Counter has been converted into a SystemVerilog module. The translation is direct, typically with one-to-one correspondence between the input and output source files. The output is similar to what a SystemVerilog engineer would have written. Line numbers from the original Verik source file are labeled with the `_( ) directive. For instance, Counter is declared on line 9 of src/main/kotlin/Counter.kt.

getting-started-compile-output

Simulator Targets

We can generate makefiles for common simulator targets with the verik Gradle task. These targets are configured in build.gradle.kts. Here we run the makefile for the Icarus Verilog target. This executes the simulation with iverilog.

getting-started-target