Hello, everyone. Welcome to the fourth episode of FPGA limerick. In this episode, we will talk about the linter, formatter, logging and editor for SpinalHDL. However, as we all know, the concepts like linter, formatter etc. are universal. They are not only confined to SpinalHDL. So we will expand the scope to other languages when it is necessary.

Linter for C/C++

Maybe we can start with a more popular language like C/C++. An often-used linter for C/C++ is clang-tidy. On Ubuntu, (which is the Linux distro we choose for WSL), it can be installed like

sudo apt install clang-tidy

And you can use the following to check a C/C++ source file:

clang-tidy -checks=* file_name.cpp

And you can use the following inline comment to ignore a certain warning, like

// NOLINT(cppcoreguidelines-avoid-magic-numbers, readability-magic-numbers)

Or simply just

// NOLINT

 

Formatter for C/C++

An often-used formatter for C/C++ is clang-formatter, which can be installed on Ubuntu like

sudo apt install clang-format

And you can format your code in place by:

clang-format -i -style="{BasedOnStyle: Google, SortIncludes: false}" file_name.cpp

Here we choose to follow Google C++ Style Guide, and to disable the sorting of the include order (The sorting of the include order might cause compiling error.)

Linter for Python

An often-used one is pylint

sudo apt install pylint

 

Linter for Verilog / SystemVerilog

Option 1: verible

Can be downloaded from https://github.com/chipsalliance/verible/releases

verible-verilog-lint file_name.sv

 

Option 2: verilator_bin

After installing verilator

verilator_bin --lint-only file_name.sv

 

Formatter for Verilog / SystemVerilog

verible (download from https://github.com/chipsalliance/verible/releases )

format in place

verible-verilog-format --inplace file_name.sv

 

Linter and Logging for SpinalHDL

 

Now let’s get to the main part of this episode: SpinalHDL (or Scala)

The style is mostly based on

Official Scala Style Guide:

https://docs.scala-lang.org/style/

SpinalHDL Coding Convention

https://spinalhdl.github.io/SpinalDoc-RTD/dev/SpinalHDL/Getting%20Started/Scala%20Guide/coding_conventions.html

 

If you check out the Hello World example (v1.1.2 tag) from our GitHub repo

git clone --depth --branch v1.1.3 https://github.com/PulseRain/FpgaLimerick.git

cd FpgaLimerick

cd HelloWorld

You will see three configuration files (next to the build.sbt) for the linter/formatter:

.scalafix.conf: Configuration file for scalafix ( https://scalacenter.github.io/scalafix/)

scalastyle-config.xml: Configuration file for scalastyle ( http://www.scalastyle.org/)

(And scalastyle can also be enabled in IntelliJ Editor, which we will discuss later.)

.scalafmt.conf: Configuration for scalafmt ( https://scalameta.org/scalafmt/ )

(code formatter for scala, which is integrated with IntelliJ.)

 

Now let’s see how we can use those linter and formatter in SBT command line:

In FpgaLimerick/HelloWorld

And interactive like the following

C:\GitHub\FpgaLimerick\HelloWorld>sbt

[info] welcome to sbt 1.8.2 (Oracle Corporation Java 19.0.2)

[info] loading settings for project helloworld-build from plugins.sbt ...

[info] loading project definition from C:\GitHub\FpgaLimerick\HelloWorld\project

[info] loading settings for project helloworld from build.sbt ...

[info] set current project to helloworld (in build file:/C:/GitHub/FpgaLimerick/HelloWorld/)

[info] sbt server started at local:sbt-server-e926ab8ee3957332f208

[info] started sbt server

sbt:helloworld> scalastyle

[info] scalastyle using config C:\GitHub\FpgaLimerick\HelloWorld\scalastyle-config.xml

[info] scalastyle Processed 4 file(s)

[info] scalastyle Found 0 errors

[info] scalastyle Found 0 warnings

[info] scalastyle Found 0 infos

[info] scalastyle Finished in 5 ms

[success] created output: C:\GitHub\FpgaLimerick\HelloWorld\target

[success] Total time: 0 s, completed Mar 5, 2023, 4:50:35 AM

sbt:helloworld> scalafix -check

[info] Running scalafix on 4 Scala sources

[success] Total time: 6 s, completed Mar 5, 2023, 4:50:56 AM

sbt:helloworld>

 

For now, everything looks clean. Now if we open the

HelloWorld/src/spinal/NcoCounter.scala

Now change the line #88 from logger.info to println

And if we run “scalastyle” again, we will see the following:

sbt:helloworld> scalastyle

[info] scalastyle using config C:\GitHub\FpgaLimerick\HelloWorld\scalastyle-config.xml

[warn] C:\GitHub\FpgaLimerick\HelloWorld\src\spinal\NcoCounter.scala:88:4: Regular expression matched 'println'

[warn] C:\GitHub\FpgaLimerick\HelloWorld\src\spinal\NcoCounter.scala:88:4: Regular expression matched 'println'

[info] scalastyle Processed 4 file(s)

[info] scalastyle Found 0 errors

[info] scalastyle Found 2 warnings

[info] scalastyle Found 0 infos

[info] scalastyle Finished in 5 ms

[success] created output: C:\GitHub\FpgaLimerick\HelloWorld\target

[warn] warnings exist

[success] Total time: 0 s, completed Mar 5, 2023, 5:03:10 AM

sbt:helloworld>

 

Here the println gets a warning, because println is deemed as a bad way for logging, as explained in https://www.baeldung.com/scala/apache-log4j

For that, we have setup the build.sbt for log4j2, and put the configuration file in

HelloWorld/src/main/resources/log4j2.xml

Currently the log4j2 is setup to be at INFO level, and it will output to both stdout and log file. The log files can be found under the logs folder.

 

Formatter and Editor for SpinalHDL

We didn’t demo the scalafmt early for the SBT command line, as we think it is better to use the scalafmt together with the editor. As for the editor of SpinalHDL, it is best to use IntelliJ IDEA.

 The IntelliJ IDEA can be downloaded from

https://www.jetbrains.com/idea/download/download-thanks.html?platform=windows&code=IIC

And after installation, please also install the Scala Plugin, as illustrated below

Then, the Hello World project can be opened as SBT project.

And for the first time, in Menu 

File/Project Structure … /SDK needs to be setup for the JDK, as shown below

And the JVM for SBT can be setup in Menu

File/Settings … /Build, Execution, Deployment /Build Tools / sbt, Choose JRE on the right hand side:

As for the scalafmt, the formatter can be setup in Menu

File / Settings… /Editor/Code Style/Scala

Set the Formatter as scalafmt, and Click the “Reformat on Save”

Now, we can launch the sbt shell (at the bottom of the IntelliJ IDEA), and type in run to run the Hello World (choose 2 to test the verilator simulation)

To use scalastyle and exclude the test folder, please right click the test/spinal folder and mark directory as test sources root

Then in Menu

File / Settings…/Editor/Inspections/Scala/Code Style/Scala Style Inspection

And setup like the following:

Posted by FPGA Limerick at February 28, 2023 |  0 Comments

Hello, everyone. Welcome to the third episode of FPGA limerick. In this episode, we will get hands-on for SpinalHDL, starting by setting up the Development Environment.

Setup for Windows/MSYS2

As mentioned in the first episode, we will use Windows 11 + MSYS2 + WSL2 as our host platform. And we will start by MSYS2 first. To install MSYS2, please open your browser and go to https://www.msys2.org/

And at this point, we will install the following version for MSYS2:

https://github.com/msys2/msys2-installer/releases/download/2023-01-27/msys2-x86_64-20230127.exe

After the MSYS2 is installed, it needs to be setup for additional packages. Please open the MSYS2 MINGW64 from Windows Start Menu, and type in the following:

pacman -Syuu

After this command, the MSYS2 window will be closed automatically.

Please reopen it through Windows Start Menu (Please choose MSYS2 MINGW64 again), and type in

pacman -Syuu

again. Then please type in the following:

pacman -S --needed base-devel mingw-w64-x86_64-toolchain git flex mingw-w64-x86_64-cmake

pacman -U https://repo.msys2.org/mingw/x86_64/mingw-w64-x86_64-verilator-4.228-1-any.pkg.tar.zst

One thing I want to mention is that you will find similar steps on SpinalHDL’s official website. But it seems those steps on the official website is not up-to-date. So please follow the steps listed above exactly. This is especially true for the last step above when you try to install verilator.

Ok. Now after the last step to install verilator, you can close the MSYS2 window, and the put the following two paths in the system path:

C:\msys64\usr\bin

C:\msys64\mingw64\bin

(From the start menu, you can choose settings / system / about / advanced system settings, then choose environment variables

Double-click the path in system variables, click new and copy paste those two paths. Please make sure those two paths are at the top of the list.)

Setup for Windows/SBT 

Now, at this point, we are done with the MSYS2.  And next we will install the SBT. Please open your browser and go to https://www.scala-sbt.org/

And currently we are using SBT 1.8.2 for Windows, which can be directly downloaded from the following path:

https://github.com/sbt/sbt/releases/download/v1.8.2/sbt-1.8.2.msi

Just run the installer, click “More info” and then click “Run anyway”.

And the installer will add sbt executable to the system path automatically. 

Setup for Windows/JDK

After the SBT is installed, the next is to install JDK. The JDK can be downloaded from the following path:

https://www.oracle.com/java/technologies/downloads/

For Windows, we currently use JDK19, which can be downloaded directly from

https://download.oracle.com/java/19/latest/jdk-19_windows-x64_bin.msi

And after installation of the JDK, please add the following path to the system path (like what we did early for MSYS2):

C:\Program Files\Java\jdk-19\bin

Test with Hello World example

Now, at this point, we should be able to run the SBT in command line and compile the SpinalHDL source code. For this purpose, we have got a HelloWorld example in the GitHub repo.

Please open a command prompt and use the following command to check out the GitHub repo for FPGA Limerick

git clone --depth 1 --branch v1.0.0 https://github.com/PulseRain/FpgaLimerick.git

cd FpgaLimerick

cd HelloWorld

sbt

If everything is setup correctly, it will show something like:

C:\GitHub\FpgaLimerick\HelloWorld>sbt

[info] welcome to sbt 1.8.2 (Oracle Corporation Java 19.0.2)

[info] loading global plugins from C:\Users\chang\.sbt\1.0\plugins

[info] loading settings for project helloworld-build from plugins.sbt ...

[info] loading project definition from C:\GitHub\FpgaLimerick\HelloWorld\project

[info] loading settings for project helloworld from build.sbt ...

[info] set current project to helloworld (in build file:/C:/GitHub/FpgaLimerick/HelloWorld/)

[info] sbt server started at local:sbt-server-e926ab8ee3957332f208

[info] started sbt server

sbt:helloworld> run

[info] compiling 4 Scala sources to C:\GitHub\FpgaLimerick\HelloWorld\target\scala-2.12\classes ...

[warn] 6 feature warnings; re-run with -feature for details

[warn] one warning found

Multiple main classes detected. Select one to run:
 [1] com.pulserain.fpga.NcoCounter

 [2] com.pulserain.fpga.NcoCounterSim

Choose option 2 to run the simulation in verilator. And you are supposed to see the following output:

Enter number: 2

[info] running (fork) com.pulserain.fpga.NcoCounterSim

[info] [Runtime] SpinalHDL v1.8.0    git head : 4e3563a282582b41f4eaafc503787757251d23ea

[info] [Runtime] JVM max memory : 10144.0MiB

[info] [Runtime] Current date : 2023.02.25 17:26:48

[info] [Progress] at 0.000 : Elaborate components

[info] [Progress] at 0.484 : Checks and transforms

[info] [Progress] at 0.564 : Generate Verilog

[info] [Done] at 0.645

[info] [Progress] Simulation workspace in C:\GitHub\FpgaLimerick\HelloWorld\.\simWorkspace\NcoCounter

[info] [Progress] Verilator compilation started

[info] [Progress] Verilator compilation done in 8036.094 ms

[info] [Progress] Start NcoCounter test simulation with seed 924781703

[info] =========== start

[info] =========== done

[info] ==== measured 240000 / 1000001 = 23.999976 MHz, expected 24.000000 MHz

[info] === Output clock is accurate enough!

[info] [Done] Simulation done in 6882.373 ms

[success] Total time: 29 s, completed Feb 25, 2023, 5:27:04 PM

sbt:helloworld>

 

If you see this, congratulation! You have setup the SBT and Verilator correctly on Windows!

Setup for Linux

We will talk about the Linux setup in later episodes when we get to the cocotb. However, if you are really itchy to try it out on Linux, you can start by the following:

Use WSL (Windows Subsystem for Linux), set up the distro as:

wsl --install -d Ubuntu-20.04

In other words, please use Ubuntu 20.04 LTS.

And please run the setup script in FpgaLimerick/HelloWorld/script/wsl_setup.sh to install the necessary packages, including verialtor and questa.

Although this script has only been verified on WSL, I believe it can also be applied on the native version of Ubuntu 20.04 LTS.

Posted by FPGA Limerick at February 25, 2023 |  2 Comments

Hello, everyone. Welcome to the second episode of FPGA limerick. In this episode, we will talk about the benefit of SpinalHDL. And we will start by visiting the evolution history of HDL (Hardware Description Language).

History 101 for HDL/HVL

In the beginning of time when digital circuits started to emerge, everything was handcrafted. A typical example of such design practice is the ubiquitous presence of Texas Instruments’ 74-Series IC back then. At that time, a large digital circuit was usually composed of multiple discrete ICs (AND gate, OR gate, FlipFlop etc.). And the whole system was often bulky and slow.

But as Moore’s law settles in, the scale of digital circuit grew exponentially over the years. It calls for a better methodology and automation in design. And thus comes in the hardware description language.

The first hardware description language is VHDL. It was developed in 1983 under the funding of the Department of Defense. It was such a big deal at that time, and the VHDL was put under export control initially. As of today, a lot of US defense companies still use VHDL due to their DoD legacy.

At the same time, Verilog also emerged in the commercial world. Verilog was introduced by a company called Gateway Design Automation in 1984. (This company was later acquired by Cadence.). It offers similar design features to VHDL, but in a more concise fashion.

Oh! At this point, please allow me to hit a tangent on this. Because people often ask me: Between VHDL and Verilog, which one you think is better? And my answer is the following:

First of all, most of the time, you probably don’t have the privilege to choose. As for those well-established companies, the decision was made long time ago when the design team was initially formed. And libraries and code were created based that choice since then. New designs will always gravitate toward the same language for the sake of code reuse.

However, if you do have the chance to choose between VHDL and Verilog, I would recommend Verilog over VHDL for the following reasons:

a) VHDL is a strong typed language while Verilog is not. To use programming language as analogy, VHDL to Verilog is what Pascal to C. However, since VHDL and Verilog are both intended to describe hardware, every value eventually boils down to ones and zeros. The strong type offers little help besides making things awkward. And modern lint tools can do a much better job without using strong type.

b) The evolution of VHDL is lagging behind that of Verilog. Many useful features of Verilog 2001 can only find their counterparts in VHDL 2008. Wildcard and external names are two of the conspicuous examples.

c) Both VHDL and Verilog are weak on verification. In the early days, they have to rely on other languages, such as Vera, e or even tcl, for more advanced verification. But Verilog made up for this by upgrading itself to Systemverilog. As a superset of Verilog, Systemverilog is rich in features to enhance verification. 

d) For gate level simulation, Verilog holds a performance advantage over VHDL, because it has built-in primitives to describe gate level components. While VHDL has to rely on VITAL library in this regard. As a result of that, most 3rd party simulation libraries are in Verilog. So if your design is in VHDL, you have to acquire a mixed language license in addition to your existing VHDL license when you simulate a design that contains 3rd party library. As you might know, EDA licenses are notoriously expensive!

OK, let’s go back to our history lesson. After the VHDL / Verilog appeared in 1980s, the size of the design gets bigger and bigger. And their weakness on verification becomes prominent. So in 1990s, HVL (Hardware Verification Language) were introduced. The first HVL was Vera by Sun Microsystems in 1995. Followed by e language in 1996. And the Vera later turned into OpenVera, which becomes the foundation of SystemVerilog

And in 2001, the HDL and HVL finally merged into one language called SystemVerilog. The SystemVerilog borrowed pages from a lot of other languages, and it supports class for Object Oriented feature. And it also has interface feature for transaction level simulation. The UVM standard is also mainly based on SystemVerilog (Which is the random verification approach by introducing random stimulus and comparing the result with reference model.)

And around the same time, those folks in the CS (Computer Science) world starts to get their hands on the HDL/HVL as well. Now come to think of it, every digital component, such as NAND gate, Flip-Flop can all be modelled as a class. In that sense, the digital design and verification can all be accomplished using high level programming language, such as C++. This approach is also favored by system designers, as the system model is often in C++. With the System C, everything (all the way from system design to RTL design) can be completed using C++ only. That is a brilliant idea by itself!

However, due to the combination of multiple unfavorable circumstances, System C did not pan out. In particular, it failed to win the hearts of FPGA vendors. As of today, the main stream FPGA vendors (both AMD and Intel) only accept VHDL, Verilog and SystemVerilog as input for synthesis.

The reason for System C’s unpopularity is still up to debate. And here is an answer provided by ChatGPT.

And a decade after System C’s debut, the idea of using high level programming language to do hardware design revived. And this time, Scala has replaced C++ to do the job, and Chisel and SpinalHDL are the two offspring of such idea. To distinguish them from VHDL/Verilog/SystemVerilog, people have coined a tech term for them: HCL (Hardware Construction Language). As mentioned in previous episode, for HCL, our bet is on the SpinalHDL side. And here is why:

1. The design done in HDL (VHDL/Verilog/SystemVerilog) is still too wordy. Practically, for the same design, the number of lines in SpinalHDL is only half of that for SystemVerilog.

2. The HDL (VHDL/Verilog/SystemVerilog) lacks high level data structure for design. Although SystemVerilog has introduced some high-level features like OO, they are mainly used for verification. The design in HDL is still done with very low-level data structure (like always for Verilog or process for VHDL). Again, to use programming language as analogy, HDL is more like Assembly while the HCL is more like modern high level programming language. 

3. To choose SpinalHDL over Chisel, the SpinalHDL holds certain advantages like those shown here.

Important Links for SpinalHDL 

And here are some important links for SpinalHDL:

Invented by Charles Papon

https://github.com/SpinalHDL

 

Document 

https://spinalhdl.github.io/SpinalDoc-RTD/

 

GitHub

https://github.com/SpinalHDL/SpinalHDL

Synthesis Flow for SpinalHDL

As for the synthesis flow, the SpinalHDL relies on SBT as the make for build. And it will produce VHDL, Verilog or SystemVerilog as the result.

Simulation Flow for SpinalHDL

And for simulation, behind the scene, the SpinalHDL will be compiled into Verilog, and simulated by Verilator. The verilator will actually turn the Verilog into C++, and running the simulation under GCC and JDK. 

And please don’t worry about those details at this point, as we will elaborate on SpinalHDL in later episodes. 

For the next episode, we will get hands-on for SpinalHDL, starting by setting up the development environment and a hello-world example.

Posted by FPGA Limerick at February 20, 2023 |  0 Comments

Hello, everyone. Welcome to FPGA limerick. This channel will bring in a series of talks on FPGA design, including both RTL and software, as well as some domain specific knowledges. 

The purpose of those talks is to lay the foundation for PulseRain Technology’s open-source IP portfolio along with the whole design methodology and design flow.

And of course, it is also for our own edification. 

The main topics to be covered are the following:

First of all, we will discuss the Hardware Design Language for RTL. As for PulseRain Technology, the main HDL that we use is SpinalHDL, plus some Systemverilog / Verilog. As you might know, SpinalHDL can produce Verilog or VHDL as its output. In this regard, we will give an in-depth talk on SpinalHDL, as it is becoming our “official language” for RTL design and verification. We will take a close look at the evolution of hardware design language to demonstrate the highlights of SpinalHDL. In addition to that, we will also show the nitty-gritty of SpinalHDL through hands-on knowledges.

Secondly, we will talk about the simulation / verification for various IPs. The main simulation tools we are gonna use are verilator and cocotb. The verilator will be seamlessly integrated into SpinalHDL environment. And it will also be used on cocotb. Cocotb is a good complement to SpinalHDL by providing a Python testbench and an abundance of library such as AXI bus.

Thirdly, we will usher in PulseRain Technology’s open-source IP portfolio, which also covers various domain knowledges for things like SPI, I2C, UART, Micro-SD card, RISC-V processor etc.

And in addition, if you, the audience, have other interesting topics that you would like us to cover, you are welcome to post your suggestions as the YouTube comments.

Ok, now let’s talk about a few logistics issues:

*) YouTube Playlist

https://www.youtube.com/playlist?list=PLHOqkTaFz2PocamNBd9LdAYBMtrlzHwNu

To keep each talk  short and sweet, we plan to make each episode less than 15 minutes.

*) Github repo, all the code and documents can be found in this repo:

https://github.com/PulseRain/FpgaLimerick

BTW, the license term for this repo is Apache 2.0

*) Companion Blog

And also, we have a companion blog as a supplement to the videos. You can find the blog at https://fpga.pulserain.com. It is pretty much the text version of the same talk.

*) Development Platform

We plan to use Windows 11 + MSYS2 + WSL2 to run all the dev tools. MSYS is a collection of tools, kind like Cygwin. And I believe WSL stands for Windows Subsystem for Linux. 

In fact, we’ve found such combination is the best for productivity.

*) FPGA dev board

Digilent Arty A7-100T 

https://digilent.com/shop/arty-a7-artix-7-fpga-development-board/

Posted by FPGA Limerick at February 13, 2023 |  0 Comments

The content of this blog is licensed under a creative common license. The full text of the license can be found here.

Posted by FPGA Limerick at February 12, 2023 |  0 Comments

*) Legal Disclaimer
*) Introduction

*) GitHub Repo
*) YouTube
*) reddit
*) SpinalHDL
*) cocotb

*) FCC Wireless
*) ARRL
*) PAPA System
*) EARS