Table of Content

• Table of Content
• Introduction to Scala and SpinalHDL: A Demonstration Project
  • Scala/SpinalHDL Environment Installation and Setup
    • Windows
  • Project Structure
    • Why Scala 2
    • Why ScalaTest
• Developer's Note
  • How to start with Vscode and metal
  • Pre-commit Hooks
  • Trouble Shooting
    • Installing OSS CAD Suite on Mac
    • Using X11 Forwarding on Mac

Introduction to Scala and SpinalHDL: A Demonstration Project

This is a Scala/SpinalHDL demo project.

Using Scala with SpinalHDL offers a powerful environment for hardware design. By leveraging the expressiveness of Scala, which combines object-oriented programming (OOP) and functional programming paradigms, designers can write high-level, maintainable hardware descriptions. SpinalHDL, as a Scala library, provides advanced features and abstractions that enhance the design process, leading to more efficient workflows and higher quality hardware systems.

SpinalHDL has a steep learning curve. To get started, I recommend practicing how to write SpinalHDL code using this website: HDLBits — Verilog Practice.

I have included several practice solutions in the src/main/scala/hdlbits folder. The generated simulation files and Verilog files will be placed in the gen and simWorkspace folders.

Please note that these solutions are not necessarily optimal, but rather intended to help you gradually work through the SpinalHDL language.

Additionally, the SpinalHDL template, cloned using git clone --depth 1 https://github.com/SpinalHDL/SpinalTemplateSbt.git MySpinalProject, is located in the src/main/scala/spinal_hdl_template_demo directory. This setup demonstrates how to use SpinalHDL and verifies that the current configuration and project structure are compatible.

For the fastest way to learn Scala and SpinalHDL, refer to the following documentation:

• Scala Documentation
• SpinalHDL Documentation

And here is a great open-source RISC-V CPU that has been implemented completely in SpinalHDL by Charles Papon (who’s also the creator of SpinalHDL.):

• VexRiscv

If you have any questions, you can always ask ChatGPT.

Scala/SpinalHDL Environment Installation and Setup

To install and setup Scala/SpinalHDL environment, please follow this page Install and setup. In this project, we demonstrate how to:

• Build the project using Scala 2 and the sbt build tool. Compile the code with sbt compile, run it with sbt run, and start a Scala 2 REPL with sbt console.
• Integrate ScalaTest. Run tests with sbt test.
• Use VSCode for editing, with the Scala (Metals) extension.
• Utilize external HDL simulators Verilator as the backend, and Gtkwave to view the waves generated by Verilator during simulation.
• Perform formal verification with the open-source Symbi-Yosys toolchain.

Please note that Verilator and Gtkwave are included in the Symbi-Yosys suite. For instance, I downloaded the oss-cad-suite-darwin-arm64-20240521.tgz.

Windows

Refer to https://www.chisel-lang.org/docs/installation:

1. Install scoop

2. Install Java Development Kit (JDK), SBT, python and pipx using scoop

   scoop install temurin17-jdk
   brew install sbt
   scoop install main/python
   scoop install main/pipx

3. To check all installed applications via Scoop, you can use the following command:

   > scoop list
   Installed apps:
   
   Name          Version   Source Updated             Info
   ----          -------   ------ -------             ----
   dark          3.14      main   2024-09-19 14:15:46
   pipx          1.7.1     main   2024-09-19 14:08:42
   python        3.12.6    main   2024-09-19 14:16:18
   sbt           1.10.0    main   2024-08-29 17:45:36
   temurin17-jdk 17.0.12-7 java   2024-09-19 13:54:47

4. Install pre-commit using pipx. Since pre-commit is installed under C:\Users\Johns575\.local\bin, remember to append to $env:Path variable

   > pipx install pre-commit
   > pipx list
   venvs are in C:\Users\Johns575\pipx\venvs
   apps are exposed on your $PATH at C:\Users\Johns575\.local\bin
   manual pages are exposed at C:\Users\Johns575\.local\share\man
       package pre-commit 3.8.0, installed using Python 3.12.6
       - pre-commit.exe

5. Refers to https://get-coursier.io/docs/cli-installation, do the following:

   # PowerShell
   > Invoke-WebRequest -Uri "https://github.com/coursier/launchers/raw/master/cs-x86_64-pc-win32.zip" -OutFile "cs-x86_64-pc-win32.zip"
   > Expand-Archive -Path "cs-x86_64-pc-win32.zip" -DestinationPath .
   > Rename-Item -Path "cs-x86_64-pc-win32.exe" -NewName "cs.exe"
   > Remove-Item -Path "cs-x86_64-pc-win32.zip"
   .\cs setup

   this should append C:\Users\Johns575\AppData\Local\Coursier\data\bin to $env:Path, where Scala development environment is installed (including cs, scala-cli, scala, scalac, sbt, scalafmt, ..), restart vscode and you will see it.

Project Structure

This project is based on the Scala template created with the command sbt new scala/hello_world.g8, which pulls a project template from GitHub. The following shows the structure of this project:

• All Scala/SpinalHDL code is located in src/main, while unit tests are in src/test.
• The .bloop, .metals, .scalafmt.conf, .vscode, project, target, and tmp folders are automatically created by VSCode and the Scala (Metals) extension. These can be ignored.
• The .git directory is created by Git. The .gitignore file is adapted from the SpinalHDL template with a few minor modifications.
• The generated simulation files and Verilog files will be placed in the gen and simWorkspace folders.

.
├── .bloop
├── .git
├── .gitignore
├── .metals
├── .scalafmt.conf
├── .vscode
├── build.sbt
├── project
│   └── build.properties
├── src
│   ├── main
│   │   └── scala
│   └── test
│       └── scala

Why Scala 2

Seems like SpinalHDL cannot work with Scala 3. Both VexRiscv and the SpinalHDL template from git clone --depth 1 https://github.com/SpinalHDL/SpinalTemplateSbt.git MySpinalProject compile with Scala 2. And if we use "2.11.12", the following error message will shows up, so we choose Scala version "2.12.19" as suggested:

You are using legacy Scala version 2.11.12, which might no longer be supported by Metals in the future. To get the best support possible it's recommended to update to at least Scala version 2.12.19.

Why ScalaTest

Because it has the most stability guarantee, and an another SpinalHDL project VexRiscv is depending on ScalaTest as well. Another choice originally from the scala template is MUnit. But it has no stability guarantees.

Note that it is not realistic to do simulation with ScalaTest. To find out usage of ScalaTest, VexRiscv is a good code-base to trace.

Developer's Note

How to start with Vscode and metal

git clone https://github.com/ttboma/spinalhdl-demo
cd spinalhdl-demo
code -a .

and then execute metal vscode extension command: metals.build-import. You are good to go.

Pre-commit Hooks

I choose to apply these scala-pre-commit-hooks. Make sure to run pre-commit install the first time cloning this project:

% pre-commit --version
pre-commit 3.7.1
% pre-commit install --hook-type commit-msg --hook-type pre-commit --hook-type pre-push

Trouble Shooting

Installing OSS CAD Suite on Mac

$ brew install xattr
$ brew install cffi
$ xattr -d com.apple.quarantine oss-cad-suite-darwin-arm64-20240516.tgz
$ tar -xzvf oss-cad-suite-darwin-arm64-20240516.tgz
$ export PATH="<extracted_location>/oss-cad-suite/bin:$PATH"

Using X11 Forwarding on Mac

For instructions on using X11 forwarding on Mac, check out: X11 Forwarding on Mac.