SpinalHDL Project Template

This repository is a Mill project template to help starting your SpinalHDL works. SpinalHDL officially provides a SBT template, and this repository is inspired by Chisel and introduces some GitHub Actions to get you started with a clean project.

You can choose this template or the official one at will.

Dependencies

Click the triangle (►) on the left to view the installation guide.

JDK

Before starting, please make sure you have a JDK >= 8 installed. You can install a JDK through the package manager that comes with your OS, or just download a prebuilt binaries such as Temurin or Oracle OpenJDK.

To install a JDK LTS:

# macOS with Homebrew
brew install openjdk@17
# Ubuntu
apt install default-jdk

Mill build tool

Mill is a powerful and easy-to-use build tool by Haoyi Li.

To install Mill:

# macOS with Homebrew
brew install mill

To install mill on other platforms, please visit its documentation.

Verilator (optional)

If you want to run the Scala-written testbench, you need to install a simulation tool, such as Verilator.

To install Verilator:

# macOS with Homebrew
brew install verilator
# Ubuntu
apt install verilator

To veiw the .vcd files generated in simulation, a waveform view tool is also required. You can use GTKWave or other commercial tools.

Intellij IDEA (optional)

Intellij IDEA is an IDE widely used in the Scala community. We strongly recommend you to use it, if you need an IDE.

Intellij IDEA is developed by JetBrains, and you can download it from here(the free Community Edition is good enough). You also need to install its Scala plugin (when you run Intellij IDEA the first time, it will ask you about it).

Sometimes you may need to specify some paths like JDK in the IDE preferences.

Get started

Create a repository from the template

This repository is a Github template. You can create your own repository from it by clicking the green Use this template in the top right. Please leave Include all branches unchecked; checking it will pollute the history of your new repository. For more information, see "Creating a repository from a template".

Do NOT clone this repository directly to the local.

Wait for the template cleanup workflow to complete

After using the template to create your own blank project, please wait a minute or two for the Template cleanup workflow to run which will removes some template-specific stuff from the repository (like the LICENSE). Refresh the repository page in your browser until you see a 2nd commit by actions-user titled Template cleanup.

Clone your repository

Once you have created a repository from this template and the Template cleanup workflow has completed, you can click the green Code to get a link for cloning your repository.

git clone git@github.com:%REPOSITORY%.git
cd %NAME%

(The variables wrapped in % will be filled in by the template cleanup)

Try the example code

Now you have a working SpinalHDL project. Some example RTL code written in Scala, which implements a simple counter, can be found in mylib/src/MyTop.scala. And mylib/test/src/MyTopSimSpec.scala is its corresponding testbench.

Open a terminal in the root of your cloned repository and run mill mylib.run. The first time it runs, the process may take some minutes to download dependencies.

# Emit Verilog RTL of your design
mill mylib.run

# Run its Scala-written testbench with ScalaTest framework
mill mylib.test

Dive into SpinalHDL and have fun!

It's time to create your own hardware! And you will discover the charm of SpinalHDL.

Don't forget:

• Add a LICENSE file for open source (or closed source). (How to select a license?)
• Set project organization and other publish settings in build.sc.
• Clean up the README.md (i.e. this file) and add your own content.
• Replace the example SpinalHDL code with yours.

Then commit above changes and push it to your repository:

git commit -m 'Starting %NAME%'
git push origin main

To open this project in an IDE (such as IDEA), please export the BSP configuration first.

mill mill.bsp.BSP/install

For more infomation

Visit the documentation for more SpinalHDL usage. If you have any questions or suggestions about this template itself, please open an issue.